x402 protocol reference

Linkex implements x402 version 2 with the exact scheme for account top-ups. This page is the complete integration reference. For the guided version see x402 autonomous top-up.

Sequence

Endpoints

Method & path	Auth	Purpose
`GET /api/user/topup/x402/config`	API key or session	Discover enabled networks, tokens, bounds, recipients
`GET /api/user/topup/x402/orders`	API key or session	List pending orders with fresh challenges
`POST /api/user/topup/x402/orders`	API key or session	Create an order (rate-limited)
`POST /api/user/topup/x402/orders/{id}/resume`	API key or session	Re-issue the challenge for a pending order
`POST /api/x402/pay/{orderId}`	none — signature is the auth	Submit the signed payment (rate-limited, 1 MiB max body)

Interactive schemas: API reference → x402.

Order creation

POST /api/user/topup/x402/orders
{ "amount_usd": 5, "network": "eip155:8453", "symbol": "USDC" }

amount_usd — within [min_topup_usd, max_topup_usd] from config (defaults $1–$1,000).
network / symbol — optional; omitted → platform default network and its default token (BNB Chain defaults to $U, everything else USDC).
Agent binding: with an agent key, the order is force-bound to that agent's wallet; agent_wallet_id in the body is ignored.
At most 3 pending orders per account (X402_PENDING_CAP).
Orders expire 600 seconds after creation.

The challenge

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000000",
    "maxAmountRequired": "5000000",
    "resource": "https://linkex.ai/api/x402/pay/12345",
    "payTo": "0xRECIPIENT",
    "maxTimeoutSeconds": 300,
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

extra depends on the settlement method:

Method	Networks	`extra`
EIP-3009	Base USDC, BNB $U	`{ "name", "version" }` — the token's EIP-712 domain (BNB additionally `"assetTransferMethod": "eip3009"`)
Permit2	BNB USDT / USDC	`{ "assetTransferMethod": "permit2-exact", "spenderAddress" }`
SVM	Solana USDC	`{ "feePayer", "memo" }` — sponsored fee payer and the invoice memo to include

Always verify payTo (and on Solana the derived token account) against GET /api/user/topup/x402/config before signing. Linkex clients refuse mismatched recipients; yours should too.

Submitting payment

POST /api/x402/pay/{orderId} with the signed payload. The gateway validates that scheme, network, asset, payTo, and the exact amount match the order, then settles.

Responses are always HTTP 200 with an envelope:

{ "success": true, "data": { "order_id": 12345, "status": "settled", "balance_added": 5, "new_balance": 12.34 } }

status values: settled (credited) or credit_pending (on-chain confirmation still in flight; a background reconciler — every 2 minutes, with on-chain verification — completes the credit).

Spend caps (agent orders)

For agent-bound orders the caps are charged atomically at the pending→settling transition:

per_call_cap_usd — per-order
daily_cap_usd — resets by calendar day
total_cap_usd — lifetime

Exceeding any returns SPEND_CAP_EXCEEDED; failed or reset orders reverse the charge.

Error codes

Returned as success: false with an uppercase message:

Code	Meaning
`X402_DISABLED`	Rail disabled on this deployment
`X402_INVALID_AMOUNT`	Outside min/max bounds
`X402_UNSUPPORTED_ASSET`	Unknown network/token combination
`X402_PENDING_CAP`	Already 3 pending orders
`ORDER_NOT_FOUND` / `INVALID_ORDER_ID`	Bad order reference
`ORDER_EXPIRED`	Past the 600 s window — create a new order
`PAYLOAD_MISMATCH`	Signed payload doesn't match the order
`SETTLING_IN_PROGRESS`	Duplicate submit while settling
`ORDER_NOT_PENDING` / `ORDER_ALREADY_SETTLED`	Wrong state
`SPEND_CAP_EXCEEDED`	Agent cap would be breached
`X402_SETTLE_PENDING`	Facilitator confirmation pending — credit follows automatically
`X402_SOLANA_FEEPAYER_UNAVAILABLE`	Sponsored fee payer temporarily unavailable

Compatible signers

Binance Agentic Wallet — baw x402-payment preview / sign
@linkexai/agent-sdk — buildX402PaymentPayload (EVM), buildSvmPaymentPayload (Solana)
Coinbase x402 tooling and any conformant x402 v2 client

x402 protocol reference

On this page