How to Pay for x402 APIs — A Guide for Developers and Agents

February 10, 2026

What just happened

You sent a request to an API and got back a 402 Payment Required. Instead of an error, this is an invitation: the server is telling you exactly how to pay and retry.

Here's what it looks like. Send a request to img402's paid upload endpoint:

bash

curl -s -X POST https://img402.dev/api/upload/token

And you get back:

402 Response
{
  "x402Version": 1,
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://img402.dev/api/upload/token",
      "description": "Pay $0.01 USDC to get an upload token...",
      "mimeType": "application/json"
    }
  ]
}

That response body is the entire protocol. No docs to find, no API keys to generate, no accounts to create. The 402 itself tells you the price, the network, and how to pay.

Reading the 402 response

The accepts array lists every payment method the server will accept. Each item contains:

Anatomy of an accepts item
{
  "scheme": "exact",           // Payment type — "exact" means a specific amount
  "network": "base",           // Blockchain — Base (Coinbase's L2)
  "maxAmountRequired": "10000", // Amount in atomic units (USDC has 6 decimals)
                                // 10000 = 0.01 USDC = $0.01
  "resource": "https://img402.dev/api/upload/token",  // What you're paying for
  "description": "Pay $0.01 USDC to get an upload token...",
  "mimeType": "application/json"
}

The key thing: maxAmountRequired is in atomic units. USDC uses 6 decimal places, so 10000 = 0.01 USDC = one cent. If you see 1000000, that's $1.00.

Option 1: Payments MCP (simplest)

If you're an AI agent with the Payments MCP tool available, this is one tool call:

MCP tool call
{
  "tool": "make_http_request_with_x402",
  "params": {
    "baseURL": "https://img402.dev",
    "path": "/api/upload/token",
    "method": "POST"
  }
}

The MCP tool sends the request, sees the 402, constructs the USDC authorization, signs it with the agent's wallet, and retries — all in one step. You get back the successful response directly:

Response
{
  "token": "a1b2c3d4e5f6...",
  "expiresAt": "2026-02-10T01:00:00.000Z"
}

No payment code to write. The MCP tool handles the 402 negotiation, wallet signing, and retry automatically.

Option 2: @x402/client library

For apps and scripts, the @x402/client library wraps the payment flow into a standard HTTP client.

Using @x402/client

import { x402Client, x402HTTPClient } from "@x402/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

// Create a client with your wallet signer
const client = new x402Client();
registerExactEvmScheme(client, signer); // ethers/viem signer

const http = new x402HTTPClient(client);

// Make the request — the client handles 402 automatically
const response = await http.post(
  "https://img402.dev/api/upload/token"
);

console.log(response.data);
// { token: "a1b2c3d4e5f6...", expiresAt: "..." }

Under the hood, the client:

Sends your request and receives the 402
Parses accepts to find a payment scheme it can handle
Creates a USDC authorization (an EIP-3009 transferWithAuthorization signature)
Base64-encodes the payment proof and retries with a payment header
Returns the successful response

The payment is a signed authorization, not a transfer. Your USDC only moves when the server submits the authorization to the facilitator for settlement.

Option 3: Manual wallet signing

To understand what's happening at the protocol level, here's the manual flow:

Read the 402 — Parse accepts to get the amount, asset, and payTo address
Sign a USDC authorization — Create an EIP-3009 transferWithAuthorization with the amount and recipient
Encode the payment — Wrap the signature in the x402 payment envelope and base64-encode it
Retry the request — Send the original request again with the payment header

Manual payment with curl
# 1. Get the 402 response (already done above)

# 2. After signing the authorization with your wallet,
#    base64-encode the payment envelope:
PAYMENT=$(echo -n '{"x402Version":1,"scheme":"exact","network":"base","payload":{"signature":"0x...","authorization":{"from":"0x...","to":"0x...","value":"10000",...}}}' | base64)

# 3. Retry with the payment header
curl -s -X POST https://img402.dev/api/upload/token \
  -H "X-PAYMENT: $PAYMENT"

This is the same thing the MCP tool and client library do automatically. For the full EIP-3009 signing details, see the x402 protocol spec.

v1 vs v2

Two versions of the x402 protocol exist. The differences are small but worth knowing:

v1 uses the X-PAYMENT header. The payment envelope contains scheme, network, and payload.
v2 uses the PAYMENT-SIGNATURE header. The envelope wraps the full accepted requirement alongside the payload.

The underlying EVM signature is identical in both versions — it's the same USDC authorization either way. Most tools (including the Payments MCP) speak v1. Newer libraries like @x402/client default to v2. Well-built servers accept both.

After you pay

Once the server receives your payment header, it:

Verifies — Forwards the payment proof to a facilitator (Coinbase's settlement service, in the case of img402) to confirm it's valid
Processes your request — Runs the actual API logic
Settles — The facilitator submits the USDC authorization on-chain, transferring the funds
Returns the result — You get back a normal HTTP response

For img402, that means you get back your upload token:

Successful response
{
  "token": "a1b2c3d4e5f6...",
  "expiresAt": "2026-02-10T01:00:00.000Z"
}

You can then use the token to upload an image via curl:

bash

curl -s -X POST https://img402.dev/api/upload \
  -H "X-Upload-Token: a1b2c3d4e5f6..." \
  -F [email protected]

Upload response
{
  "url": "https://i.img402.dev/aBcDeFgHiJ.png",
  "id": "aBcDeFgHiJ",
  "contentType": "image/png",
  "sizeBytes": 182400,
  "expiresAt": "2027-02-10T00:00:00.000Z"
}

Retries are safe

The same payment proof always produces the same response. If you get a network error after paying, retry with the exact same headers — the server will recognize the payment and return the result without charging you again.

This is idempotent by design. The payment authorization is a specific signed message tied to an amount and recipient. It can only be settled once, so replaying it is always safe.

Finding x402 services

There are several ways to discover APIs that accept x402 payments:

Bazaar catalog — The Payments MCP includes a bazaar_list tool that searches a directory of x402 services
llms.txt files — AI-readable site descriptions (like img402.dev/llms.txt) that list endpoints and pricing
OpenAPI specs — Standard API documentation that includes 402 response schemas

But the most powerful discovery mechanism is the 402 response itself. Unlike traditional APIs where you need to find documentation, create an account, generate API keys, and store credentials — with x402, hitting the endpoint IS the documentation. The 402 tells you the price, the network, the asset, and exactly how to pay. No signup portal required.

Try it: curl -s https://img402.dev/api/upload/token -X POST | jq. That response is everything a client needs to complete the payment and use the API.