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.
#!/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)
#!/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))
// 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));
# 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