Quickstart

1. Get an API key

Sign in to the merchant dashboard and create a test API key under API Keys.

2. Create an invoice

The API key environment decides whether the invoice is test or live — do not send environment.

curl -X POST http://api.localhost:4000/v1/invoices \
  -H "Authorization: Bearer test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00"
  }'

Amounts are decimal strings in major units — "10.00" = 10.00 USDC/USDT (up to 6 decimal places).

Optional: lock network and/or token

curl -X POST http://api.localhost:4000/v1/invoices \
  -H "Authorization: Bearer test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "networkId": 11155111,
    "token": "USDC"
  }'

• networkId — only that network gets a deposit address; checkout cannot switch networks
• token — only that stablecoin is accepted; checkout cannot switch tokens
• Both — checkout shows a fixed payment route (no selectors)

Example response (truncated):

{
  "id": "…",
  "status": "CREATED",
  "environment": "test",
  "amount": "10",
  "amountReceived": "0",
  "checkoutUrl": "http://checkout.localhost:3000/i/…",
  "expiresAt": "…",
  "addresses": [
    {
      "chainId": "…",
      "chainName": "Sepolia",
      "family": "evm",
      "networkId": 11155111,
      "depositAddress": "0x…",
      "tokens": [
        {
          "symbol": "USDC",
          "contractAddress": "0x…",
          "decimals": 6
        }
      ]
    }
  ]
}

Send your customer to checkoutUrl. If you display deposit addresses yourself, always show chainName and only the listed tokens — sending any other asset to that address will not count as payment.

3. Listen for webhooks

Configure a webhook URL in the merchant dashboard (Webhooks). Fulfill on invoice.paid — that is the fulfillment signal.

See Webhooks for signature verification and Invoice lifecycle for status meanings.

4. Go live

When ready, complete go-live in the dashboard. After platform approval, create a live API key and switch your integration.