Circle API

A retail payment backend built on Circle's USDC sandbox APIs. It lets you create users, provision Circle-backed wallets, and transfer USDC between customers and merchants — with every transaction persisted locally in PostgreSQL via Prisma.

Stack

• Runtime: Node.js 20+ / TypeScript
• Framework: Express + Zod validation
• Database: PostgreSQL (Prisma ORM)
• Payments: Circle Programmable Wallets (sandbox)
• Docs: Swagger UI at /api-docs
• MCP: Model Context Protocol server for AI tool integrations

Prerequisites

• Node.js 20+
• Docker Desktop (for the local Postgres container)
• A Circle sandbox account → app-sandbox.circle.com

Setup

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Set CIRCLE_API_KEY from Circle sandbox → Developer → API Keys

# 3. Start Postgres
docker compose -f prisma/docker-compose.yml up -d

# 4. Run migrations
npm run db:migrate   # when prompted, name the migration: init

# 5. Start dev server
npm run dev          # http://localhost:3002

Environment Variables

Variable	Description
CIRCLE_API_KEY	Sandbox API key from Circle dashboard
CIRCLE_BASE_URL	https://api-sandbox.circle.com/v1
DATABASE_URL	PostgreSQL connection string
PORT	Server port (default 3000)

API Overview

Users

Method	Path	Description
POST	/user/create	Create a user

Wallets

Method	Path	Description
POST	/wallet/create	Create a CUSTOMER or MERCHANT wallet
GET	/wallet/:id/balance	Fetch live balance from Circle

Payments

Method	Path	Description
POST	/payment/send	Send USDC from customer → merchant
GET	/payment/:id	Get transaction status (auto-syncs from Circle)

Full interactive docs available at http://localhost:3002/api-docs once the server is running.

Data Model

User ──< Wallet ──< Transaction (as sender or receiver)

• Balances are fetched live from Circle on every request — never cached locally.
• PENDING transactions are synced from Circle on every GET /payment/:id.
• idempotencyKey deduplicates Circle transfer calls — safe to retry with the same key.

Scripts

Command	Description
npm run dev	Start dev server with hot reload
npm run mcp	Start MCP server
npm run build	Compile TypeScript
npm start	Run compiled build
npm run db:migrate	Apply Prisma migrations
npm run db:studio	Open Prisma Studio

Sandbox Funding

Circle sandbox wallets start with zero balance. To add test USDC:

1. Go to app-sandbox.circle.com
2. Navigate to Payments → Master Wallet
3. Use the faucet to top up your master wallet
4. Transfer funds to a customer wallet via the Circle dashboard or API

Transaction Status Reference

Circle status	Internal status
pending	PENDING
complete	COMPLETE
failed	FAILED