Pay per request with x402

How a request is paid

1. Request

   Your agent calls a tool’s x402 endpoint with no payment attached.

2. Quote

   Strale answers 402 Payment Required with the price in USDC on Base, the payee address and how long the quote stays valid.

3. Pay

   The agent’s wallet signs a USDC authorisation for that amount. Signing costs the buyer no gas, so the wallet needs USDC and no ETH.

4. Repeat

   The agent sends the same request again with the signed payment in the PAYMENT-SIGNATURE header. Strale runs the tool, settles the payment once the tool returns a usable result, and answers with the result. A failed call is not charged.

See a price quote

Asking for a quote costs nothing and needs no wallet. This asks for Address Geocoding, the lowest-priced eligible tool in the catalogue at $0.0216 USDC a call.

curl -i 'https://api.strale.io/x402/v2/address-geocode?address=Eiffel+Tower%2C+Paris'

The response is HTTP 402. The quote is in the body, and also in the PAYMENT-REQUIRED header on /x402/v2/ paths. Trimmed:

{
  "x402Version": 2,
  "error": "Payment required. Address Geocoding costs $0.0216 USDC per call.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "21600",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "<Strale’s payee address>",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

amount is in USDC atomic units, six decimals: 21600 is $0.0216. The quote is valid for 300 seconds.

Make a paid call

1. Fund a wallet

   Use a wallet on Base that holds a little USDC. The tool above costs $0.0216 a call. Export its private key as X402_PRIVATE_KEY for this script, and use a dedicated wallet for it.

2. Install the x402 client

   Install Copy

   npm install @x402/core @x402/evm viem

3. Run the script

   It requests the tool, reads the quote, signs a payment for that amount and repeats the request.

   buy.ts Copy

   import { x402Client, x402HTTPClient } from "@x402/core/client";
   import { ExactEvmScheme } from "@x402/evm";
   import { privateKeyToAccount } from "viem/accounts";
   
   const account = privateKeyToAccount(process.env.X402_PRIVATE_KEY as `0x${string}`);
   const client = x402Client.fromConfig({
     schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
   });
   const http = new x402HTTPClient(client);
   
   const url = "https://api.strale.io/x402/v2/address-geocode?address=Eiffel+Tower%2C+Paris";
   const first = await fetch(url);
   if (first.status !== 402) {
     console.log(first.status, await first.json());
     process.exit(0);
   }
   
   // The 402 body is the price quote. Sign a payment for exactly that amount.
   const quote = await first.json();
   const payload = await client.createPaymentPayload(quote);
   
   const paid = await fetch(url, { headers: http.encodePaymentSignatureHeader(payload) });
   console.log(paid.status, JSON.stringify(await paid.json(), null, 2));
   console.log(paid.headers.get("X-PAYMENT-RESPONSE")); // base64 JSON with the settlement transaction

   Run it with X402_PRIVATE_KEY=0x… npx tsx buy.ts. A runnable version is in the repository at examples/x402-autonomous-buyer.

4. Read the result

   A paid call returns HTTP 200 with the tool’s output as the body. The extra _meta field carries the capability, the latency, the provenance and the payment, including the settlement ID. The X-PAYMENT-RESPONSE header holds the settlement transaction as base64 JSON.

Eligible tools

275 tools and 89 bundled checks accept x402 today. The set changes, so read it from the catalogue instead of assuming a tool is on it. Tools that are not on it run with an API key through the REST API or MCP.

Both /x402/{slug} and /x402/v2/{slug} work. The v2 path always sends the current quote format with CAIP-2 network names; the older path serves older clients. Use v2 for new code. Free tools need no payment at all: call them with the REST API without a key.

Responses and errors

• There are no transaction IDs on this route. Keep _meta.payment.settlement_id as your record of a call.
• Each call stands alone. There is no balance, no spend cap and no max_price_cents; the quote is the price you agree to by signing it.