Examples

Try it in the browser (free, no wallet)

Free trial of the paid route

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

Results appear here. Nothing is paid on this page.

Copy-paste scripts

Free from the shell

#!/bin/sh
# Free, no wallet: X402 Router discovery from the shell.
R=https://router-production-ab89.up.railway.app
curl -s -X POST $R/route -H 'content-type: application/json' -d '{"q":"weather","chain":"Base"}'      # best match + top 3
curl -s "$R/api/endpoints?q=weather&chain=Base&limit=5"                                               # search LIVE endpoints
curl -s "$R/status/endpoint?url=https://example.com/x402/endpoint"                                    # reliability history of one endpoint
curl -si -X POST $R/route/paid -H 'content-type: application/json' -d '{"q":"weather"}' | grep -i '^payment-required'   # the 402 (no charge)

Free trial, shell and Python

#!/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).
# pip install httpx
# Free trial of X402 Router's /route/paid: 3 free calls per wallet and per IP per UTC day, no payment needed.
# Falls back to telling you the price when the trial is used up (then use paid_client.py).
import os, httpx

ROUTER = os.environ.get("X402_ROUTER_URL", "https://router-production-ab89.up.railway.app")
WALLET = os.environ["WALLET"]   # your EVM 0x... or Solana address (only used as the trial key; nothing is signed)

def route_trial(q, chain=None, max_price=None, category=None):
    body = {k: v for k, v in {"q": q, "chain": chain, "max_price": max_price, "category": category}.items() if v is not None}
    r = httpx.post(ROUTER + "/route/paid", json=body, headers={"X-402-Trial": WALLET}, timeout=30)
    left = r.headers.get("X-402-Trial-Remaining")
    if r.status_code == 402:
        return {"trial_used_up": True, "remaining": left, "next": "pay 0.01 USDC per call with an x402 client (paid_client.py)"}
    r.raise_for_status()
    return {"remaining": left, **r.json()}

if __name__ == "__main__":
    out = route_trial("weather", chain="Base")
    print("trial calls left today:", out.get("remaining"))
    print(out.get("best", out))

Paid, TypeScript

// 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));

Paid, Python

# 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))

Framework wrappers: LangChain · CrewAI · AgentKit · MCP. Test notes are on each guide.

Each paid run costs 0.01 USDC on Base, paid to the router's payTo shown in the 402. Use a dedicated low-balance wallet. The scripts were tested on 17 Nov 2026 against a local replay of the live 402 (signed, never sent).

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