API Reference

All API endpoints are served on port 4000 and require an Authorization: Bearer <API_SECRET_KEY> header unless noted otherwise.

Base URL

http://localhost:4000/v1

Charges

Create a charge

POST /v1/charges

Creates a new payment charge. The processor assigns an HD wallet address (shared across all configured chains) and returns payment details including per-chain token info.

Request body

Field	Type	Required	Description
`amount`	number	Yes	Amount in USD
`customerEmail`	string	No	Customer email for records
`metadata`	object	No	Arbitrary key-value data stored with the charge

Example request

curl -X POST http://localhost:4000/v1/charges \
  -H "Authorization: Bearer $API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "customerEmail": "buyer@example.com",
    "metadata": { "orderId": "ORD-1234" }
  }'

Example response

{
  "id": "cm1abc123",
  "status": "PENDING",
  "expectedAmountUsd": "49.99",
  "customerEmail": "buyer@example.com",
  "metadata": { "orderId": "ORD-1234" },
  "wallets": [
    {
      "chain": "eth-sepolia",
      "chainId": 11155111,
      "address": "0xABC123...",
      "tokens": [
        { "symbol": "USDC", "address": "0xDEF456...", "decimals": 6 },
        { "symbol": "ETH", "decimals": 18 }
      ]
    }
  ],
  "checkoutUrl": "http://localhost:4002/checkout/cm1abc123",
  "createdAt": "2026-03-08T12:00:00.000Z"
}

Error codes

Code	Meaning
`NO_CHAINS_CONFIGURED`	No chains are configured in the server config
`NO_AVAILABLE_WALLETS`	The escrow wallet pool is exhausted

Get a charge

GET /v1/charges/:id

Returns the current state of a charge, including received token and amount if payment has been detected.

Example response

{
  "id": "cm1abc123",
  "status": "COMPLETED",
  "expectedAmountUsd": "49.99",
  "receivedToken": "ETH",
  "receivedTokenAddress": null,
  "receivedAmount": "0.014285",
  "receivedAmountUsd": "49.99",
  "wallets": [ ... ],
  "createdAt": "2026-03-08T12:00:00.000Z",
  "completedAt": "2026-03-08T12:04:37.000Z"
}

Payment statuses

Status	Description
`PENDING`	Waiting for payment
`COMPLETED`	Full payment received
`EXPIRED`	Charge expired before payment

Get a quote

GET /v1/charges/:id/quote?chain=<chain>&token=<symbol>

Returns the exact token amount required to pay for a specific chain and token combination. Exchange rates are cached and refreshed on a configurable interval (default 5 minutes).

Query parameters

Parameter	Description
`chain`	Chain key, e.g. `eth-sepolia`
`token`	Token symbol, e.g. `ETH` or `USDC`

Example request

curl "http://localhost:4000/v1/charges/cm1abc123/quote?chain=eth-sepolia&token=ETH" \
  -H "Authorization: Bearer $API_SECRET_KEY"

Example response

{
  "chain": "eth-sepolia",
  "token": "ETH",
  "requiredAmount": "0.014285",
  "decimals": 18,
  "tokenAddress": null,
  "usdRate": 3500.00,
  "expiresAt": "2026-03-08T12:05:00.000Z"
}

List configured chains

GET /v1/charges/chains

Returns all chains and tokens the server is configured to accept. No authentication required.

Example response

{
  "chains": {
    "eth-sepolia": {
      "chainId": 11155111,
      "tokens": {
        "USDC": { "symbol": "USDC", "address": "0x...", "decimals": 6 },
        "ETH":  { "symbol": "ETH",  "decimals": 18 }
      }
    }
  }
}

Webhooks

Register a webhook

POST /v1/webhooks

Registers a URL to receive HTTP POST callbacks when charge status changes.

Request body

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to call
`events`	string[]	No	Event types to subscribe to (defaults to all)
`secret`	string	No	Shared secret for HMAC signature verification

Supported events

Event	Triggered when
`charge.completed`	Payment fully received
`charge.expired`	Charge expired

Webhook payload

{
  "event": "charge.completed",
  "chargeId": "cm1abc123",
  "status": "COMPLETED",
  "receivedAmountUsd": "49.99",
  "timestamp": "2026-03-08T12:04:37.000Z"
}

API Reference

On this page