x402 API monetization

Charge agents per request with x402 and CoinCircuit settlement.

Use this prompt to gate API access behind x402 payments and settle agent-signed authorizations through CoinCircuit.

x402 Agent Payments Payments Node.js

What this prompt covers

• Create per-request payment sessions
• Return 402 responses with payment details
• Verify and settle signed agent payments on-chain

x402-api-monetization.prompt.md

You are helping me add per-request crypto payments to my existing API using the x402 protocol and CoinCircuit for settlement. 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/payments` for the checkout session creation schema.
- Call `get_endpoint` with method `post` and path `/api/v1/payments/agent/settle` for the agent settlement schema.
- Call `get_endpoint` with method `post` and path `/api/v1/payments/agent/verify` for the pre-validation schema.
- Call `search_api` with query `agent settle` and type `endpoints` to find all agent payment endpoints.
- Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload.

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 creates a CoinCircuit payment session for the resource price
3. Returns a 402 response with the payment details (deposit address, amount, chain)
4. Agent signs the payment and sends it back
5. My server submits the signed payload to CoinCircuit for on-chain settlement
6. Delivers the resource once settlement confirms

The agent only needs a wallet and signing key. No CoinCircuit API key, no gas tokens.

## 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 proof, proceed to step 2 (create session + return 402). If it includes a signed payload, proceed to step 5 (settle).

### 2. Create a payment session

When an agent hits a paid endpoint without payment:

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

```json
{
  "amount": "1.00",
  "currency": "USD",
  "title": "API call - /api/premium-data",
  "description": "Single API request",
  "asset": "USDC",
  "chain": "base",
  "customer": {
    "email": "[e-mail]"
  },
  "metadata": {
    "endpoint": "/api/premium-data",
    "agentWallet": "0xAgentAddress..."
  }
}
```

**Response (201):** Returns a session object with:
- `data.reference` - session reference (keep this server-side for settlement)
- `data.payment.address` - the deposit address
- `data.payment.amount` - the required crypto amount
- `data.expiresAt` - session expiration

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

### 3. Return the 402 response

Send the payment details back to the agent. Your server stores the session reference internally, keyed by the deposit address or a short-lived token, so you can match the agent's payment to the session.

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

The agent picks a signing scheme and produces a flat payload. Each scheme produces a payload with `from`, `to`, `value`, and scheme-specific fields:

- **EIP-3009:** `validAfter`, `validBefore`, `nonce` (random 32-byte hex), `signature`
- **Permit2:** `deadline`, `nonce` (numeric), `signature`
- **Solana:** `transaction` (base64 partially signed tx)

The agent sends this back to your server.

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

Before settling, dry-run the payment:

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

Returns 200 if the payment will succeed, or 400 with per-check pass/fail results. Catches issues like insufficient balance, expired nonces, and invalid signatures before touching the blockchain.

### 6. Settle the payment on-chain

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

**Always include `sessionReference` from step 2 in the settle request.** CoinCircuit uses it to verify the signed payment against the original session's required amount, deposit address, chain, and asset. Without it, these checks are skipped and the payment is not validated against the session. Also include the scheme, chain, asset, and the signed payload. CoinCircuit submits the transaction on-chain, covers gas, and returns the transaction hash and block confirmation.

### 7. Deliver the resource

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

### Integration Flow Summary

```
Agent -> GET /api/premium-data
Server -> CoinCircuit: POST /payments (creates session)
Server -> Agent: 402 (deposit address, amount, schemes)
Agent -> Signs payment (eip3009 / permit2 / solana)
Agent -> Server: POST /api/premium-data/pay (signed payload)
Server -> CoinCircuit: POST /payments/agent/verify (optional)
Server -> CoinCircuit: POST /payments/agent/settle
Server -> Agent: 200 (resource + tx receipt)
```

### Supported Chains and Assets

| Scheme | Asset | Chains |
|--------|-------|--------|
| eip3009 | USDC | Base, Arbitrum |
| permit2 | USDC, USDT | Base, Arbitrum, BSC |
| solana | SOL, USDC, USDT | Solana |

## Constraints

- **Always pass `sessionReference` in the settle call.** This is how CoinCircuit verifies the payment matches the session's required amount, deposit address, chain, and asset. Without it, those checks are skipped.
- The agent signs the authorization, but your server submits it. This lets you control the session lifecycle and validate amounts before settlement.
- The agent needs no CoinCircuit API key and no gas tokens. It only needs a wallet and signing capability.
- Session `amount` is a **string** in fiat (e.g. `"1.00"`)
- Always use the verify endpoint first in production to catch bad signatures before spending gas
- Solana transactions expire in ~60 seconds based on the blockhash. Generate the session close to when the agent will sign.
- EIP-3009 nonces are random 32-byte hex values. Permit2 nonces are numeric.
- For Permit2, the agent must have done a one-time on-chain approval of the Permit2 contract (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) for the token
- All EVM networks offer sub-second block times and gas costs under a cent. Solana settles in under a second with fees below $0.001.