x402 API Monetization

Charge AI agents per request over HTTP 402 with gasless stablecoin payments.

Open the interactive version or read this guide as markdown.

Tags: x402, Agent Payments, Payments, Node.js

Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io

You are helping me add per-request crypto payments to my existing API using the x402 protocol and CoinCircuit as the facilitator. I have the CoinCircuit MCP server connected.

If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:

• Call get_api_overview in the CoinCircuit MCP for base URLs, auth method, and available features.
• Call get_endpoint with method post and path /api/v1/x402/requirements for the payment requirements schema.
• Call get_endpoint with method post and path /api/v1/x402/settle for the settlement schema.
• Call get_endpoint with method post and path /api/v1/x402/verify for the pre-validation schema.
• Call get_endpoint with method get and path /api/v1/x402/supported for the supported networks and assets.
• Call search_api with query x402 and type endpoints to find all x402 endpoints.

Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP.

API Basics

• Base URL (production): https://api.coincircuit.io
• Base URL (sandbox): https://sandbox-api.coincircuit.io
• Auth: Pass your API key in the x-api-key header on every request.

Project Context

I have an API backend and I'm adding x402 payment gating so AI agents pay per request. The flow:

1. Agent hits a paid endpoint on my API.
2. My server asks CoinCircuit to build the payment requirements for the price.
3. My server returns a 402 with those requirements.
4. The agent signs a gasless payment and sends it back.
5. My server submits the signed payment to CoinCircuit, which settles it on-chain and covers gas.
6. My server delivers the resource once settlement confirms.

The agent needs only a wallet and a signing key.

What I Need You to Implement

1. Middleware: check for payment

Create middleware that intercepts requests to paid endpoints. If the request has no payment, proceed to step 2 (build requirements and return 402). If it includes a signed payment, proceed to step 5 (settle).

2. Build the payment requirements

When an agent hits a paid endpoint without payment:

Endpoint: POST /api/v1/x402/requirements (Call get_endpoint with method post, path /api/v1/x402/requirements, section request in the CoinCircuit MCP for the full request body.)

{
  "chain": "base",
  "asset": "USDC",
  "amount": "0.10",
  "resource": "https://your-api.com/api/premium-data"
}

Response: the ready-to-return 402 body, with a friendly summary and a canonical accepts array. payTo defaults to your deposit address, so the payment credits your balance. Pass your own payTo to settle elsewhere.

(Call get_endpoint with method post, path /api/v1/x402/requirements, section success in the CoinCircuit MCP for the full response.)

3. Return the 402 response

Return the body with a 402 status. A standard x402 client reads accepts[0] and signs against it.

4. Agent signs the payment (client-side reference)

The wire scheme is exact. The agent signs for the mechanism its chain uses and returns the canonical paymentPayload:

• USDC on EVM: an EIP-712 TransferWithAuthorization (EIP-3009), returned as { signature, authorization }.
• USDT on EVM: a Permit2 permit, returned as { signature, authorization }.
• USDC or USDT on Solana: an SPL token transfer with extra.feePayer set as the transaction fee payer, partially signed, returned as { transaction } (base64).

The agent sends the paymentPayload back to your server.

5. Pre-validate the payment (optional but recommended)

Before settling, dry-run the payment:

Endpoint: POST /api/v1/x402/verify (Call get_endpoint with method post, path /api/v1/x402/verify in the CoinCircuit MCP for the full schema.)

It takes the same body as settle and returns the per-check result, so you can catch insufficient balance, expired authorizations, and invalid signatures before settling.

6. Settle the payment on-chain

Endpoint: POST /api/v1/x402/settle (Call get_endpoint with method post, path /api/v1/x402/settle in the CoinCircuit MCP for the full request/response schema.)

Send { x402Version, paymentPayload, paymentRequirements }, the signed payload plus the requirements you issued. CoinCircuit verifies the payment, submits the transaction on-chain, covers gas, and returns the transaction hash and confirmation.

7. Deliver the resource

Once the settle response confirms success, return the requested data to the agent with the transaction hash as a receipt.

Integration Flow Summary

Agent  -> GET /api/premium-data
Server -> CoinCircuit: POST /api/v1/x402/requirements
Server -> Agent: 402 (accepts: payment requirements)
Agent  -> Signs the payment (exact scheme)
Agent  -> Server: POST /api/premium-data/pay (signed paymentPayload)
Server -> CoinCircuit: POST /api/v1/x402/verify (optional)
Server -> CoinCircuit: POST /api/v1/x402/settle
Server -> Agent: 200 (resource + tx receipt)

Supported Chains and Assets

Constraints

• Forward the same paymentRequirements you issued into the settle call alongside the signed paymentPayload. CoinCircuit checks the payment matches them.
• The agent signs the authorization; your server settles it. This lets you validate the request and release the resource only after settlement confirms.
• amount is a decimal string in asset units (e.g. "0.10" USDC).
• Use the verify endpoint first in production to catch bad signatures before spending gas.
• Solana payments expire in ~60 seconds based on the blockhash. Build the requirements close to when the agent will sign.
• For Permit2 (USDT), the agent does a one-time on-chain approval of the Permit2 contract (0x000000000022D473030F116dDEE9F6B43aC78BA3) for the token.
• EVM networks offer sub-second block times and gas costs under a cent. Solana settles in under a second with fees below $0.001.