Specie docs

Quickstart

Taking your first payment.

1. Get an API key

Sign up, then Dashboard → API keys → Create key. It is shown once and stored only as a hash, so copy it now.

Set your business name and logo under Settings while you are there. They appear at checkout, and a payer who cannot tell who is asking for money will not pay.

2. Create a payment

curl -X POST https://your-deployment/api/v1/payments \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "description": "Pro plan — 30 days",
    "reference": "ORD-1234",
    "success_url": "https://yourapp.com/thanks"
  }'
{
  "id": "0x7f3a...",
  "status": "pending",
  "amount": "25.00",
  "pay_url": "https://your-deployment/pay/0x7f3a...",
  "deposit_address": "0xe37410ad78b2dce3f57e2237554df10a5dd35ba4"
}

Send the customer to pay_url, or pass id to the widget.

3. Get told when it is paid

curl -X POST https://your-deployment/api/v1/webhook_endpoints \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/webhooks/arc"}'

The response contains a signing secret, shown once. Verify every delivery with it — see webhooks.

Amounts are strings

{ "amount": "25.00" }

Never 25.0 as a number. USDC has six decimal places and floating point cannot represent them exactly; 0.1 + 0.2 is the wrong amount to charge someone. Every amount in this API is a decimal string.

Testing

Fund a wallet from the Circle faucet, open the pay_url, and pay it. Watch it reach confirmed in the dashboard.

The minimum payment is 0.50 USDC — below that, relayer gas costs more than the fee earns.

What next