Getting Started

Quickstart

Convert USDC on Base to NGN in a Nigerian bank account in four API calls.

Authentication

There are two ways to access protected endpoints:

Option 1 — API Key

Contact gabedev to request an API key. Pass it via the x-api-key header.

curl ... -H "x-api-key: YOUR_KEY"

Option 2 — x402 Micropayment

Pay per-call using the x402 protocol. Perfect for AI agents — no signup, attach a payment proof in the x-payment header.

curl ... -H "x-payment: PROOF"

# Health check — no auth required
curl https://clova-pay-africa-production.up.railway.app/v1/health

Step 1 — Get a quote

Quotes are valid for 5 minutes. The response includes the live NGN rate, fee breakdown, and what the recipient will actually receive.

curl -X POST https://clova-pay-africa-production.up.railway.app/v1/quotes \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC_BASE",
    "amountCrypto": "100",
    "destinationCurrency": "NGN"
  }'

// Response
{
  "quoteId": "q_550e8400...",
  "asset": "USDC_BASE",
  "amountCrypto": "100",
  "rate": "1503.50",
  "feeBps": 150,
  "feeNgn": "2255.25",
  "receiveNgn": "148094.75",
  "expiresAt": 1709812800000
}

Step 2 — Create an order

Submit the recipient's Nigerian bank details. We call Paycrest and return a unique depositAddress for this order. Use GET /v1/banks to look up supported bank codes.

curl -X POST https://clova-pay-africa-production.up.railway.app/v1/orders \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC_BASE",
    "amountCrypto": "100",
    "recipient": {
      "accountName": "John Doe",
      "accountNumber": "0123456789",
      "bankCode": "058"
    },
    "returnAddress": "0xYourRefundWallet"
  }'

// Response
{
  "orderId": "ord_abc123...",
  "depositAddress": "0xPaycrestDepositAddr...",
  "asset": "USDC_BASE",
  "status": "awaiting_deposit",
  "receiveNgn": "148094.75",
  "expiresAt": 1709814600000
}

Step 3 — Send crypto to depositAddress

Transfer exactly 100 USDC on Base to the depositAddress returned in the order response. Paycrest detects the deposit and kicks off the NGN transfer automatically. The order expires if no deposit arrives within 30 minutes.

USDCx on Stacks?

For USDCX_STACKS orders, depositAddress is the Clova Clarity contract principal. Call deposit(token, amount, memo) on the contract where memo is your orderId encoded as a buffer. This is how our watcher matches the deposit to your order.

Step 4 — Poll or use webhooks

Check status by polling or register a webhook endpoint to receive order.fulfilled / order.failed events.

# Poll order status
curl https://clova-pay-africa-production.up.railway.app/v1/orders/ord_abc123... \
  -H "x-api-key: YOUR_OWNER_API_KEY"

# Order statuses: awaiting_deposit → confirming → paid_out → settled
#                                                           ↓
#                                                         failed / expired

Order lifecycle

Status	Meaning
`awaiting_deposit`	Order created. Waiting for crypto to arrive at depositAddress.
`confirming`	Deposit detected on-chain. Waiting for confirmations.
`paid_out`	Paycrest transfer initiated. NGN on its way to the bank.
`settled`	Bank transfer confirmed. Done.
`failed`	Paycrest transfer failed. Check failureReason.
`expired`	No deposit received within 30 minutes.