Skip to main content

Make an x402 endpoint

To be listable, your endpoint must speak x402: when called without payment it returns 402 Payment Required with a challenge; when called with a valid X-PAYMENT header it verifies, settles, and returns the data.

The contract​

1. Agent  ── GET /x402/rates ─────────────▶  your server
2. Server ── 402 + payment requirements ──▶  agent           (no payment yet)
3. Agent  ── GET /x402/rates
            X-PAYMENT: <base64 signed authorization> ──▶ your server
4. Server ── verify + settle on XDC ──▶ 200 + data

The 402 challenge​

Your 402 body advertises what to pay. It must specify the network, the USDC asset, the amount, and the recipient (payTo):

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "xdc",
      "maxAmountRequired": "10000",
      "asset": "0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1",
      "payTo": "0xYourRecipientAddress",
      "resource": "https://api.acme.example/x402/rates/summary"
    }
  ]
}
  • asset is USDC on XDC (6 decimals) — 10000 = 0.01 USDC. See Constants.
  • payTo must match the payTo your listing advertises (see pricing & payTo).

The X-PAYMENT header​

The agent signs an EIP-3009 transferWithAuthorization for the exact amount to your payTo, base64-encodes it, and sends it as X-PAYMENT. Your server verifies the signature/amount and settles it.

Two ways to settle​

You don't need to run chain infrastructure — settlement is gasless via a facilitator/relayer that submits the signed authorization on-chain and pays the XDC gas.

  • Use a facilitator — verify + settle by calling a facilitator service (the platform's or your own). This is the simplest path; your server stays secret-free and never touches gas.
  • Self-settle — if you prefer, submit the transferWithAuthorization yourself from a sponsor account.

Either way the agent pays only USDC and never holds gas.

Implementation notes​

  • HTTPS is mandatory (see security). Plaintext endpoints are rejected and expose payments to interception.
  • Make settlement idempotent per authorization nonce so a retried request can't double-charge or double-serve.
  • Return the real data on 200 only after settlement is confirmed (or safely queued).
  • Keep the advertised price, asset, and payTo consistent between your listing and your 402 challenge.

Next: Set pricing & payTo →