Skip to main content

Accept x402 payments on XDC

This guide shows how to accept x402 payments on XDC from an API you host yourself. Your server answers 402, then calls the public x402 facilitator to verify and settle the payment in USDC. Settlement is gasless for the buyer.

You need a server that can serve HTTP and a place to keep one secret. You do not need a wallet or any native XDC for gas.

1. Get a seller key​

Open xdcai.tech/account/facilitator, pick the address your API should be paid at, and mint a seller API key. The key is shown once and stored only as a hash, so copy it into your server's secrets now. Top up a small amount of credits so your first settlement can go through.

2. Answer 402 with a price​

When a request arrives without a valid payment, answer 402 and advertise what you charge. The important fields are the network (eip155:50), the asset (USDC), the amount in atomic units (6 decimals, so 10000 is 0.01 USDC), and the address you are paid at.

HTTP/1.1 402 Payment Required

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:50",
    "asset": "0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1",
    "amount": "10000",
    "payTo": "<your receiving address>"
  }]
}

3. Verify the payment​

The buyer signs an EIP-3009 authorization and repeats the request with it attached. Send it to the facilitator's verify endpoint with your key. Verify is a read and is free.

curl -X POST https://public-facilitator.xdcai.tech/verify \
  -H "Authorization: Bearer $FACILITATOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paymentPayload": ..., "paymentRequirements": ... }'

If verification fails, the payment is not real or does not cover the price. Return 402 again and do not serve the content.

4. Settle and confirm​

Once verified, ask the facilitator to settle. Settlement is asynchronous: it returns an id, and you poll until it confirms on-chain and reports a transaction hash.

# broadcast the transfer
curl -X POST https://public-facilitator.xdcai.tech/settle \
  -H "Authorization: Bearer $FACILITATOR_KEY" \
  -d '{ ... }'

# then poll until it confirms
curl https://public-facilitator.xdcai.tech/settlements/{id} \
  -H "Authorization: Bearer $FACILITATOR_KEY"

Only serve the paid content after settlement confirms. This "serve after settle" order is what stops a bad payment from getting a free response.

5. Handle the billing states​

Two responses are about your account, not the buyer:

  • 403 insufficient_facilitator_credits - you are out of credits. Top up. Do not tell the buyer their payment failed.
  • 403 seller_plan_inactive - your seller plan is inactive.

Common mistake: the EIP-712 token name​

On XDC the USDC EIP-712 token name is USDC, not USD Coin. The wrong name produces a different domain separator and every signature fails to recover. This is the single most common integration failure. See the overview for the full constant table.

Where to go next​

If you would rather not write any of this, the gateway wraps your existing API and does all of it for you.