# Pay per call with x402

The x402 flow step by step: call a Munition endpoint, read the 402 payment requirements, sign from your wallet, retry with the payment header.

[x402](https://www.x402.org/) lets an agent pay for a single HTTP request with USDC from its own wallet. There is no account, no API key and no sign-up: the request itself carries the payment. Munition's x402 routes use version 2 of the protocol.

This page follows one call to `POST https://api.munition.io/v1/serper/search`, a Google search that costs 0.004 USDC. Every paid x402 route follows the same five steps; the method, the input and the price differ. Ready-to-run code is on [Copy-paste examples](/docs/payments/examples).

## The flow in five steps

### 1. Call the endpoint

Send the request as you normally would, with no payment header:

```bash
curl -sS -i https://api.munition.io/v1/serper/search \
  -H 'Content-Type: application/json' \
  --data '{"q":"x402 protocol","gl":"us","hl":"en","num":10}'
```

Without a payment header, the route answers `402` before it reads the body, so this works with any body. With a payment header, the body is checked first: a malformed request gets `400` before the payment is verified, and nothing is charged.

### 2. Receive a 402 with the payment requirements

The API answers `402 Payment Required`. The body is a short JSON error:

```json
{ "error": { "code": "payment_required", "message": "x402 payment required for Munition Google Search." } }
```

The requirements themselves are in the `PAYMENT-REQUIRED` response header, as base64-encoded JSON. [Reading the 402](#reading-the-402) shows it decoded.

Requests that look like a web browser (an `Accept: text/html` header and a Mozilla user agent) get an HTML payment page instead of the JSON body. Agents and HTTP clients get JSON.

### 3. Sign the payment from your wallet

Pick one entry of `accepts`: a network and asset your wallet holds. Then sign a payment of exactly `amount` (in USDC atomic units: 6 decimals, so `4000` is 0.004 USDC) to `payTo`:

- **On Base, Polygon and Arbitrum** (`eip155:*`), the wallet signs an EIP-3009 `TransferWithAuthorization` for the USDC contract in `asset`. The EIP-712 domain is `extra.name` and `extra.version` with the network's chain id and `asset` as the verifying contract. The authorization is valid for `maxTimeoutSeconds` (300).
- **On Solana** (`solana:*`), the wallet partially signs a USDC `TransferChecked` transaction to `payTo`. The fee payer is `extra.feePayer`, the facilitator's account, which pays the network fee.

The result is the x402 version 2 payment payload, a JSON object with:

- `x402Version`: `2`;
- `resource`: the `resource` object of the 402, unchanged;
- `accepted`: the `accepts` entry you chose, unchanged;
- `payload`: the signature. On EVM networks it is `{ "authorization": { "from", "to", "value", "validAfter", "validBefore", "nonce" }, "signature" }`; on Solana it is `{ "transaction": "<base64 partially signed transaction>" }`;
- `extensions`: the 402's `extensions`, when you pass them on.

An x402 client library builds and signs this for you: see the [TypeScript example](/docs/payments/examples#typescript).

### 4. Retry with the payment header

Send the same request again, with the payload base64-encoded in the `PAYMENT-SIGNATURE` header:

```bash
curl -sS -i https://api.munition.io/v1/serper/search \
  -H 'Content-Type: application/json' \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE" \
  -H 'Idempotency-Key: serper-x402-protocol-1' \
  --data '{"q":"x402 protocol","gl":"us","hl":"en","num":10}'
```

Munition verifies the payment with the x402 facilitator (Coinbase CDP), settles it on chain, and only then calls the provider. Settlement comes first, so a provider failure after this point does not undo the payment: [Errors and refunds](/docs/payments/errors) says what the API returns then.

### 5. Get the result

The answer is `200` with the search results as JSON. The `PAYMENT-RESPONSE` header carries the settlement receipt: base64-encoded JSON with `success`, `transaction` (the on-chain transaction hash), `network` and the `payer` address.

## Reading the 402

This is the `PAYMENT-REQUIRED` header of an unpaid `POST /v1/serper/search`, decoded. It was captured from Munition's server in its test environment, and a test checks on every change that the server still answers with the same structure and the same amount. The `payTo` addresses and the Solana `feePayer` below are placeholders: a live challenge carries Munition's real receiving addresses and the facilitator's fee payer, so always read them from the challenge you receive.

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.munition.io/v1/serper/search",
    "description": "Munition Google Search: x402-paid Google web search results for AI agents via Serper. Pay 0.004 USDC per query for organic results (title, link, snippet, position), answer box, knowledge graph, people-also-ask and related searches. Country and language selectable.",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "4000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x2222222222222222222222222222222222222222",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    },
    {
      "scheme": "exact",
      "network": "eip155:137",
      "amount": "4000",
      "asset": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "payTo": "0x2222222222222222222222222222222222222222",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    },
    {
      "scheme": "exact",
      "network": "eip155:42161",
      "amount": "4000",
      "asset": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "payTo": "0x2222222222222222222222222222222222222222",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "4000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "MunitionPayTo111111111111111111111111111111",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USDC", "feePayer": "FeePayer11111111111111111111111111111111111" }
    }
  ],
  "extensions": {
    "bazaar": {
      "info": {
        "input": {
          "type": "http",
          "bodyType": "json",
          "body": { "q": "x402 protocol", "gl": "us", "hl": "en", "num": 10 },
          "method": "POST"
        },
        "output": {
          "type": "json",
          "example": {
            "query": "x402 protocol",
            "organic": [
              {
                "title": "x402: HTTP-native payments",
                "link": "https://www.x402.org/",
                "snippet": "An open protocol for internet-native payments.",
                "position": 1
              }
            ],
            "meta": { "resultCount": 1, "searchedAt": "2026-09-09T00:00:00.000Z" }
          }
        },
        "serviceName": "Munition",
        "tags": ["search", "google", "web"],
        "iconUrl": "https://munition.io/logo.png"
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "input": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "http" },
              "method": { "type": "string", "enum": ["POST"] },
              "bodyType": { "type": "string", "enum": ["json", "form-data", "text"] },
              "body": {
                "type": "object",
                "properties": {
                  "q": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000,
                    "description": "Google query."
                  },
                  "gl": {
                    "type": "string",
                    "default": "us",
                    "description": "Country code (gl), e.g. us, fr, de."
                  },
                  "hl": {
                    "type": "string",
                    "default": "en",
                    "description": "Interface language (hl), e.g. en, fr."
                  },
                  "num": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 },
                  "page": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 },
                  "tbs": {
                    "type": "string",
                    "description": "Time filter, e.g. qdr:d, qdr:w, qdr:m, qdr:y."
                  }
                },
                "required": ["q"],
                "additionalProperties": false
              }
            },
            "required": ["type", "method", "bodyType", "body"],
            "additionalProperties": false
          },
          "output": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "example": {
                "type": "object",
                "properties": {
                  "query": { "type": "string" },
                  "organic": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "title": { "type": "string" },
                        "link": { "type": "string", "format": "uri" },
                        "snippet": { "type": "string" },
                        "position": { "type": "integer" },
                        "date": { "type": "string" }
                      },
                      "required": ["title", "link"]
                    }
                  },
                  "answerBox": { "type": ["object", "null"] },
                  "knowledgeGraph": { "type": ["object", "null"] },
                  "peopleAlsoAsk": { "type": "array", "items": { "type": "object" } },
                  "relatedSearches": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": { "query": { "type": "string" } }
                    }
                  },
                  "meta": {
                    "type": "object",
                    "properties": {
                      "resultCount": { "type": "integer" },
                      "searchedAt": { "type": "string", "format": "date-time" }
                    },
                    "required": ["resultCount", "searchedAt"]
                  }
                },
                "required": ["query", "organic", "meta"]
              }
            },
            "required": ["type"]
          }
        },
        "required": ["input"]
      }
    }
  }
}
```

- `x402Version`: always `2`.
- `resource`: the URL being paid for, its description and the media type of the result.
- `accepts`: one entry per way to pay; pick any. `scheme` is `exact` (a fixed price), `network` is a [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) id, `asset` the USDC contract (or mint, on Solana), `amount` the price in USDC atomic units. The networks are listed on [Networks and assets](/docs/payments/networks).
- `extensions.bazaar`: discovery metadata. `info.input` is an example request, `info.output` an example result, and `schema` the JSON Schema of both. The body schema is at `schema.properties.input.properties.body`.

The live challenge is authoritative: an agent should read the price and networks from it rather than from a cached copy.

## MPP routes

Some services are also sold over MPP, which uses HTTP authentication headers instead of x402's payment headers. MPP routes live under `/v1/mpp/*` and mirror an x402 route: `POST /v1/mpp/serper/search` takes the same input, returns the same result and costs the same as `POST /v1/serper/search`.

- **Challenge:** without credentials, an MPP route answers `402` with a `WWW-Authenticate: Payment` challenge (method `evm`, intent `charge`) and a JSON problem body summarizing the amount, currency and recipient.
- **Payment:** the client retries with `Authorization: Payment <credential>`, an EIP-3009 USDC authorization for the charge in the challenge. Munition submits it on chain itself.
- **Receipt:** a successful answer carries a `Payment-Receipt` header.

MPP mirrors exist for web research (`/v1/mpp/exa/*`, `/v1/mpp/firecrawl/*`, `/v1/mpp/serper/*`), uploads (`/v1/mpp/uploads`), flight search (`/v1/mpp/flights/search`) and forms (`/v1/mpp/forms`). HTML to PDF, airport search and flight offer details are x402 only. MPP networks are on [Networks and assets](/docs/payments/networks#mpp), and the machine-readable list of MPP routes is at `https://api.munition.io/.well-known/mpp.json`.
