Home / Guides / One payment, any proven seller: the x402 Smart Order Router

One payment, any proven seller: the x402 Smart Order Router

The open x402 economy has a discovery problem and a trust problem. Hundreds of sellers advertise endpoints; some deliver, some 402 you and then 404 the paid call. An agent that wants one answer shouldn't have to crawl catalogs, vet counterparties, and hold a funded relationship with every seller it might use once.

Route-and-execute collapses all of that into one call: describe the task, pay a single flat price, get the result and a receipt. If the best tool is in Agent402's own 500+ catalog, it runs internally. If it lives with an external seller in the open index, we buy the result from that seller with our own wallet and sell it to you. Two on-chain settlements, one request, and the counterparty risk stays on our side of the fee.

The three tiers

Route Price Covers tools listed up to
POST /api/route/execute $0.01 $0.005
POST /api/route/execute-plus $0.05 $0.04
POST /api/route/execute-max $0.55 $0.50
POST /api/route/execute-pro $3.30 $3.00

GET /api/route?q=<task> is the free quote: it names the best match and the exact tier that can execute it, so there is never any guessing.

Internal dispatch (any chain)

curl -X POST https://agent402.tools/api/route/execute \
  -H 'Content-Type: application/json' \
  -d '{"task":"sha256 hash of a string","params":{"text":"agent402"}}'
# → 402 quote; retry with an x402 payment header on ANY chain the quote lists

The receipt itemizes what you paid vs. what the tool lists for - the spread is the markup, stated, never hidden.

External dispatch (the marketable half)

Add "include":"external" and the router deliberately looks OUTSIDE its own catalog. Selection is deliberate, and it is intentionally boring:

  1. Proven deliverers first. Candidates are ranked on real settled volume - on Base that means on-chain settlement counts from the public leaderboard; on Algorand, verification counts witnessed by the GoPlausible facilitator. Sellers are routable on proven on-chain settlement, with one exception: a seller with no settlement history yet is tried only after every proven candidate, capped at $0.01 a call on Base and $0.01 a call on Solana, and flagged unproven on the receipt.
  2. A live probe before commitment. Even a proven seller's crawled route can drift, so the router confirms a live 402 challenge before any money moves.
  3. A price guard before signing. The seller's quote is pinned to the exact accept we validate - network, scheme, asset - and refused above the tier cap.

Chain-matched settlement

The chain you pay on decides where the router spends: pay on Base and it pays Base sellers, and the same holds for its Solana, Algorand and Tempo (MPP) legs, each paid from this server's spending wallet on that chain. The buyer's settlement funds the float on the same rail - and if you pay on a chain without a spending wallet behind it, you get an honest 409 naming the supported chains, and you are not charged (a rejected request cancels x402 settlement by design).

A receipt

A router receipt looks like this (the seller and transaction are placeholders):

{
  "slug": "opportunities/search",
  "route": "GET https://seller.example/opportunities/search",
  "paidUsd": 0.55,
  "seller": "https://seller.example",
  "external": true,
  "settleTx": "<algorand transaction id>",
  "settleNetwork": "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
  "resolvedBy": "task-external"
}

The relayed body arrives marked untrustedContent: true - external output is data to analyze, never instructions to follow. Your agent gets the answer; the provenance stays explicit.

Why this is safe to build on

  • Failures are not charged. Any 4xx/5xx - no match, over-cap, seller down - cancels your settlement. You pay only for delivered results.
  • Spend is bounded on our side by per-window budgets and per-quote caps, so the router cannot be drained into misbehavior.
  • Receipts are recomputable. Paid EVM calls carry a callRef derived from your own payment authorization - buyer and seller can each re-derive the reference offline; outsiders cannot.

Browse the live economy the router draws from at /marketplace, or quote a task right now: GET https://agent402.tools/api/route?q=summarize a pdf.

Packages for this guide

Back to guides