Pay from code with an x402 client

Any x402 v2 client works. It sends the request, gets 402 with a PAYMENT-REQUIRED header, signs a gasless USDC authorization (EIP-3009) and retries with PAYMENT-SIGNATURE. Your wallet needs a little USDC on Base and no ETH.

0. Try it free first (no wallet funds, no signing)

#!/bin/sh
# Free trial of X402 Router's paid route: 3 free calls per wallet per day, no payment needed.
# Put your own wallet address in X-402-Trial (EVM 0x... or Solana base58). Nothing is signed or charged.
ROUTER="${X402_ROUTER_URL:-https://router-production-ab89.up.railway.app}"
WALLET="${WALLET:-0xYourWalletAddressHere000000000000000000}"
curl -s -D - -X POST "$ROUTER/route/paid" \
  -H 'content-type: application/json' \
  -H "X-402-Trial: $WALLET" \
  -d '{"q":"weather","chain":"Base"}'
# 200 + headers  X-402-Trial: true  X-402-Trial-Remaining: N  -> same full ranked answer as a paid call.
# When the trial is used up you get the normal 402 (PAYMENT-REQUIRED) plus X-402-Trial-Remaining: 0;
# from then on pay 0.01 USDC per call with any x402 client (see paid_client.py / paid-client.ts).

Free trial: 3 free trial calls per wallet per day, no payment needed. Add the header X-402-Trial: <your wallet address> (EVM 0x… or Solana) to /route/paid and you get the same full ranked answer a paid call gets. Limits: 3 per wallet and 3 per IP per UTC day, from a shared pool of 100 a day. After that you get the normal 402. Try it · trial.sh · trial_call.py

1. See the 402 (free)

curl -i -X POST https://router-production-ab89.up.railway.app/route/paid -H 'content-type: application/json' -d '{"q":"weather"}'

What the challenge asks for (decoded from the live header):

{
 "x402Version": 2,
 "accepts": [
  {
   "scheme": "exact",
   "network": "eip155:8453",
   "amount": "10000",
   "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
   "payTo": "0x4a1ae0abcd9a6fc7bbcc2a51fa4bb1d6af1b76cc"
  },
  {
   "scheme": "exact",
   "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   "amount": "10000",
   "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
   "payTo": "7F9nMqE3Bipa7RAgYykxWETRCrixWJLyDHKbZNdv9XEK"
  }
 ]
}

2. TypeScript (@x402/fetch)

// X402 Router paid client (TypeScript, Node 20+). npm i @x402/fetch @x402/evm viem
// Pays 0.01 USDC on Base per call (gasless EIP-3009 signature; the wallet needs a little USDC, no ETH).
// Usage (ESM: "type": "module" in package.json, or save as .mts): EVM_PRIVATE_KEY=0x... npx tsx paid-client.ts "weather"
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const ROUTER = process.env.X402_ROUTER_URL ?? "https://router-production-ab89.up.railway.app";
const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`) });
const pay = wrapFetchWithPayment(fetch, client);   // gets the 402, signs the USDC authorization, retries

export async function routePaid(q: string, chain = "Base", max_price?: number) {
  const res = await pay(`${ROUTER}/route/paid`, {
    method: "POST", headers: { "content-type": "application/json" },
    body: JSON.stringify({ q, chain, ...(max_price !== undefined ? { max_price } : {}) }),
  });
  if (!res.ok) throw new Error(`router answered ${res.status}`);
  return res.json();   // { best, ranked[], target_url, price, ... }
}

console.log(JSON.stringify(await routePaid(process.argv.slice(2).join(" ") || "weather"), null, 1));

Download paid-client.ts

3. Python (x402 + httpx)

# X402 Router paid client (Python). pip install "x402[httpx,evm]"
# Pays 0.01 USDC on Base per call (gasless EIP-3009 signature; the wallet needs a little USDC, no ETH).
# Usage: EVM_PRIVATE_KEY=0x... python paid_client.py "weather"
import asyncio, json, os, sys
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

ROUTER = os.environ.get("X402_ROUTER_URL", "https://router-production-ab89.up.railway.app")

async def route_paid(q: str = "", chain: str = "Base", max_price: float | None = None, category: str | None = None) -> dict:
    """Best live x402 endpoint for a task + the full ranked list (up to 25). Costs 0.01 USDC."""
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))
    body = {k: v for k, v in {"q": q, "chain": chain, "max_price": max_price, "category": category}.items() if v not in (None, "")}
    async with x402HttpxClient(client) as http:   # gets the 402, signs the USDC authorization, retries
        r = await http.post(f"{ROUTER}/route/paid", json=body)
        await r.aread()
        r.raise_for_status()
        return r.json()

if __name__ == "__main__":
    print(json.dumps(asyncio.run(route_paid(" ".join(sys.argv[1:]) or "weather")), indent=1))

Download paid_client.py

What you get back

best (name, url, price_usdc, chains, score, latency_ms, reliability and a pay block with method, url, pay_to, asset, networks, x402_version), ranked (up to 25 of the same), plus target_url, price, fee, total and total_matches.

Test status (17 Nov 2026): @x402/fetch 2.31.0 + @x402/evm 2.31.0 (Node 24, ESM) and x402 2.28.0 (Python 3.13) were run against a local replay of the router's live unsigned 402 (exact captured PAYMENT-REQUIRED header and body); the client produced a valid x402 v2 payment for 0.01 USDC (amount 10000) on eip155:8453 to the router's payTo. The signed payment was captured locally and never sent, so no funds moved.

Filters (all optional): q text, chain (Base, Solana, eip155:8453...), category (AI, Data, Finance...), max_price in USDC. Set X402_ROUTER_URL to point the scripts somewhere else.

Prices: /route/paid 0.01 USDC, /check/paid 0.002 USDC, /route free. x402 v2 on Base (eip155:8453) or Solana. Machine-readable: OpenAPI · /.well-known/x402 · llms.txt