Skip to main content

X402 API

The X402 API enables advanced, non-custodial crypto payments using the EIP-402 ("Pay with Authorization") standard. It allows clients to fetch payment requirements and submit signed payment authorizations for on-chain settlement.

Endpoints​

1. Get Payment Requirements​

GET /x402/:linkId

Returns the EIP-402 payment requirements for a given payment link. Used by wallets or agents to construct and sign the payment payload.

  • Response Code: 402 (Payment Required)

Response Example:

{
  "x402Version": 1,
  "accepts": [
    {
      "amount": "100000000", // USDC in smallest units
      "currency": "USDC",
      "network": "base-sepolia",
      "recipient": "0x123...",
      "verifyingContract": "0xabc...", // USDC contract address
      "chainId": 84532,
      "aiUrl": "https://pay.blockia.com/x402/abc123..."
      // ...other EIP-712 domain fields
    }
  ],
  "error": null
}
  • If the link is not payable or expired, accepts will be empty and error will be set.

2. Submit X402 Payment​

POST /x402/:linkId/pay

Submits a signed EIP-402 payment payload for settlement. The backend verifies the signature, checks nonce, and broadcasts the transaction.

Request Example:

{
  "network": "base-sepolia",
  "payload": {
    "from": "0xabc...",
    "to": "0x123...",
    "value": "100000000",
    "nonce": "0xdeadbeef...",
    "validAfter": 0,
    "validBefore": 9999999999,
    "data": "0x...",
    "signature": "0x..."
  }
}

Response Example:

{
  "success": true,
  "txHash": "0xtransaction...",
  "networkId": "base-sepolia",
  "error": null
}
  • If the signature or nonce is invalid, or the payment fails, success will be false and error will be set.

Business Rules​

  • Only active, non-expired payment links are payable.
  • Only USDC on supported networks (Base, Base Sepolia) is accepted.
  • Nonce and signature are strictly validated (EIP-712/EIP-3009).
  • Each payment link can only be paid once.
  • All responses are machine-readable JSON.

Error Handling​

  • If a payment link is not found, expired, or not payable, the error field will be set in the response.
  • Validation errors (invalid signature, nonce reuse, etc.) return success: false and a descriptive error.