Pay per request, no account needed.

How it works

When an agent calls an /api/x402/* endpoint without a payment header, the server responds with 402 Payment Required and a JSON body that says how much to pay, to which wallet and in which token.

The agent transfers USDC on Base, then sends the same request again with an X-Payment header that points to the transaction. The server checks the transfer on-chain, records the transaction hash so it can't be used twice, and runs the request.

Step by step

1. 1 Request Call a paid endpoint, for example POST /api/x402/image/generate, with your parameters and no API key.
2. 2 Quote The server answers 402 Payment Required with the amount, the wallet to pay and the USDC contract.
3. 3 Pay Send at least that much USDC on Base to the quoted wallet and wait for the transaction to confirm.
4. 4 Retry Repeat the same request with an X-Payment header that carries the transaction hash.
5. 5 Verify The server reads the receipt from Base, checks the USDC transfer and records the hash.
6. 6 Result The request runs as usual, and an X-Payment-Response header confirms the payment.

The 402 response

For a request quoted at 20 credits, the body looks like this. maxAmountRequired is in USDC's smallest unit: 200,000 is 0.2 USDC.

{
    "x402Version": 1,
    "accepts": [
        {
            "scheme": "exact",
            "network": "base",
            "maxAmountRequired": "200000",
            "resource": "https://dev.ai.immersive.inc/api/x402/image/generate",
            "description": "Immersive AI API — 20 credits",
            "mimeType": "application/json",
            "payTo": "0xf9d8ee48Ea0ae1399478f0E866C2C2352DC23A96",
            "maxTimeoutSeconds": 300,
            "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "extra": {
                "name": "USDC",
                "version": "2",
                "chainId": 8453
            }
        }
    ],
    "error": "X-Payment header required. See accepts[0] for payment details."
}

Retry with proof of payment

Encode {txHash, from, chainId, amount} as base64 on a single line and send it as X-Payment. GNU base64 wraps long output, so use -w0 on Linux; on macOS base64 doesn't wrap.

PAYMENT=$(printf '%s' '{"txHash":"0xYOUR_TX_HASH","from":"0xYOUR_WALLET","chainId":8453,"amount":"200000"}' | base64 -w0)

curl -X POST https://dev.ai.immersive.inc/api/x402/image/generate \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT" \
  -d '{"generator": "nano_banana_2_1", "prompt": "A lighthouse at dusk"}'

PAYMENT=$(printf '%s' '{"txHash":"0xYOUR_TX_HASH","from":"0xYOUR_WALLET","chainId":8453,"amount":"200000"}' | base64)

curl -X POST https://dev.ai.immersive.inc/api/x402/image/generate \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT" \
  -d '{"generator": "nano_banana_2_1", "prompt": "A lighthouse at dusk"}'

This server takes the hash of a confirmed transfer as proof, not a signed payment authorization, so build the header as shown rather than with a generic x402 client library.

On success the response carries an X-Payment-Response header: base64-encoded JSON with success, txHash and the credits the payment covered.

Pricing

The 402 response quotes the request you sent, with the same parameters (model, resolution, duration) you would send with an API key; see Models and pricing for the rate card. Credits convert at 100 credits per USDC.

Verification

• The server fetches the transaction receipt with eth_getTransactionReceipt and only accepts a transaction that is mined and succeeded.
• It adds up the USDC Transfer events to its wallet in that transaction; together they must cover the quoted amount.
• The chainId in the header must be 8453.
• Each transaction hash pays for one request. Sending it again returns 402.

Endpoints

The paid endpoints take the same parameters as their /api/v1/ counterparts. Polling a job's status is free.

MCP tools

The MCP server has two tools for x402: get_x402_payment_info returns the wallet, network, USDC contract, chain ID and rate, and get_x402_endpoint_cost returns the USDC amount for an endpoint and its parameters, so an agent can fund the transfer before it calls. The resource x402://ai-api/payment-info has the same information in machine-readable form.