Skip to content

README.md

Latest commit

 

History

History
109 lines (78 loc) · 3.11 KB

README.md

File metadata and controls

109 lines (78 loc) · 3.11 KB
Raw

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