Munition
Docs menu

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

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

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 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 id, asset the USDC contract (or mint, on Solana), amount the price in USDC atomic units. The networks are listed on Networks and assets.
  • 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, and the machine-readable list of MPP routes is at https://api.munition.io/.well-known/mpp.json.