Routing API for paid agent endpoints

Pick the right paid API for your agent — in one call.

Agents shouldn't crawl a 45K-entry x402 catalog before every paid call. Send the task and budget; get one recommended endpoint, the reason it won, and ranked alternatives. Today: 6 task types on Base mainnet — extensible to new markets without changing this API.

Routed —

Curated —

Route price $0.001 USDC

Open API docs

curl https://x402route.vercel.app/v1/tasks

Free GET — see what we route. Paid POST /v1/route returns the recommendation.

Request POST /v1/route

{
  "task": "defi_tvl",
  "params": {
    "protocol": "aave-v3"
  },
  "constraints": {
    "max_price_usd": 0.01,
    "mode": "balanced"
  }
}

Response $0.001

{
  "recommended_endpoint": "https://x402.ottoai.services/yield-markets",
  "source": "bazaar",
  "reason": "Balanced pick at $0.001",
  "alternatives": [
    {
      "endpoint": "https://defillama.com/x402/yield",
      "source": "bazaar",
      "price_usd": 0.005
    }
  ],
  "quality_score": 0.827
}

How it works

Agent → x402route → Endpoint.

Agent

Sends a task, params, and budget.

→

x402route

Checks available endpoints and returns one recommendation.

→

Endpoint

The agent calls the selected endpoint directly and pays it via x402.

How the route is decided

Filters first. Score second.

step 1 — budget

Price fit first

Endpoints above `max_price_usd` are removed before the final choice.

step 2 — liveness

Active health checks

Confirmed-dead endpoints (no successful pings) are excluded; intermittent ones get penalized.

step 3 — mode

Agent intent

`cheapest`, `balanced`, and `best_quality` change how the winner is picked among survivors.

always — transparency

Inspectable scoring

Per-endpoint quality_score is exposed via `GET /v1/score?endpoint=URL` so agents can debug picks.

Live selection modes

Three ways to choose the route.

cheapest

Use when cost matters more than latency or quality.

-d '{"task":"token_price","constraints":{"mode":"cheapest"}}'

balanced

Use when default choice. Combines price with usage and uptime signals.

-d '{"task":"token_price","constraints":{"mode":"balanced"}}'

best_quality

Use when trust matters more than price.

-d '{"task":"token_price","constraints":{"mode":"best_quality"}}'

Supported tasks

11 live task types today.

token_price

Current token price on an on-chain DEX.

token_liquidity

DEX pool liquidity and volume for a token.

chain_rpc

Read-only RPC calls to an EVM blockchain.

defi_tvl

TVL and yield metrics for DeFi protocols.

dex_pools

Active pools for a token pair on DEXes.

crypto_news

Current crypto news and headlines.

risk_score

Token risk analysis (rug, honeypot, scam flags).

social_sentiment

Twitter/X sentiment and trends for a token or topic.

oracle_price

Specialized price oracles (perps, regional exchanges).

nft_metadata

NFT collection metadata (floor price, volume, supply).

transaction_history

Wallet transaction history (transfers, swaps, contract calls).

+ more soon

wallet_balance, swap_quote, token_holders — on the roadmap (waiting on x402 supply).

API surface

Four endpoints. Three are free.

POST /v1/route $0.001

Get one recommended endpoint for a task. Paid via x402.

GET /v1/tasks free

List all routed task types with chains and price ranges.

GET /v1/endpoints free

List all curated endpoints. Optional ?task= filter.

GET /v1/score?endpoint=URL free

Inspect raw signals and per-task quality_score for any endpoint.

Boundaries

A router, not a proxy.

No provider proxy

x402route returns the route decision. The agent calls the selected endpoint directly.

No data resale

The response is a provider recommendation, not the final token price, RPC result, or news payload.

No account layer

The route call is paid with x402. No dashboard, login, or subscription is required.

Compatibility

Works with

MCP Claude / Cursor / any MCP client AWS Bedrock AgentCore x402 payments, preview Plain HTTP Any agent that speaks x402

x402 payment

Pay once. Route once.

Challenge → sign → retry

POST /v1/route returns HTTP 402 with a payment-required header. Sign an EIP-3009 transferWithAuthorization for 0.001 USDC on Base, retry with the X-PAYMENT header, get the route.

Existing libraries

x402-fetch and x402-axios handle the challenge-response loop automatically. AWS Bedrock AgentCore SDK does too at preview.

Spec

The x402 protocol is documented at github.com/coinbase/x402. Network and token agnostic — Solana and other rails on the roadmap.