# x402 API Monetization

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

Section: Build with AI
Source: https://coincircuit.io/docs/guides/x402-api-monetization/
Interactive version: https://coincircuit.io/api-reference?tab=guides&guide=x402-api-monetization

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.)*

```json
{
  "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

| Asset | Networks | Mechanism |
|-------|----------|-----------|
| USDC | Base, Arbitrum, BSC, Solana | EIP-3009 (EVM), partial signing (Solana) |
| USDT | Base, Arbitrum, BSC, Solana | Permit2 (EVM), partial signing (Solana) |

## 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.