# AgentRoute

A pay-per-call HTTP API gateway for AI agents. 84 endpoints across crypto data, onchain primitives, identity, search, general utilities, and fun APIs behind a single x402 v2 paywall on Base mainnet.

## Who This Is For

- Autonomous AI agents that need data without managing API keys
- Trading bots looking for market data, whale alerts, DEX routing, sentiment, and safety checks
- LLM coding assistants using MCP tools in Claude Desktop, Cursor, Cline, or Continue
- Crypto apps that already use x402 / ATXP and want one consolidated source

## How To Call

### Direct HTTP With @x402/fetch
```ts
import { wrapFetchWithPaymentFromConfig } from '@x402/fetch'
import { ExactEvmScheme } from '@x402/evm'
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount(process.env.AGENT_PK as `0x${string}`)
const fetchPaid = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(account) }],
})
const r = await fetchPaid('https://traderoute-psi.vercel.app/api/route/market-data?token=SOL')
const data = await r.json()
```

The modern v2 client reads PAYMENT-REQUIRED, signs the payment, and retries with PAYMENT-SIGNATURE. Legacy examples may refer to x402-fetch.

### MCP Server
```json
{ "agentroute": {
  "command": "npx", "args": ["-y", "@smxfreeze/traderoute-mcp"],
  "env": { "BUYER_PRIVATE_KEY": "0x...", "MAX_CALL_USDC": "0.10" }
} }
```
All 84 endpoints become MCP tools an LLM can discover.

### Free Preview
Every endpoint has a free preview at https://traderoute-psi.vercel.app/api/preview/<capability>. Use it to inspect response shape before paying.

## Discovery Files

- https://traderoute-psi.vercel.app/.well-known/x402.json - x402 service catalog
- https://traderoute-psi.vercel.app/openapi.json - OpenAPI 3.1 spec for all endpoints
- https://traderoute-psi.vercel.app/api/discover - JSON catalog with sample links per capability
- https://traderoute-psi.vercel.app/api/health - runtime config
- Agentic Market validator: https://agentic.market/validate?url=https%3A%2F%2Ftraderoute-psi.vercel.app%2Fapi%2Froute%2Fmarket-data

## Agentic Market Readiness

- Unpaid paid endpoints return HTTP 402
- The x402 v2 payload is delivered in the PAYMENT-REQUIRED response header
- Each payload includes resource.url, resource.description, resource.mimeType, accepts[].amount, and extensions.bazaar metadata
- Each capability publishes example_params, input_schema, output_schema, output_example, and a free preview URL

## Categories

1. Crypto trading data - signal, market-data, onchain, sentiment, safety, trending, predict-pump, arb-opportunities, signal-pro, holders, whale-alert, new-pairs, defi-momentum, kol-mention
2. DEX / execution - dex-route, gas, mempool, mev, bridge-quote, liquidity, solana-route, mev-protect, flashloan-route
3. Onchain primitives - block-info, erc20-balance, tx-simulate, nft-owner, tx-decode, contract-info, address-resolve, abi-fetch
4. DeFi data - protocol-tvl, dex-volume, fees-revenue, stablecoin-stats, chain-info, fear-greed, lending-rates, validator-yield
5. Identity - identity-resolve, ens-records, farcaster-cast
6. Utilities - weather, fx-rate, world-time, holidays, hn-trending, github-trending, wikipedia, dns-lookup, ip-info, stock-quote

## Pricing

- Agentic/Bazaar-compatible minimum: $0.001 USDC per paid call
- Range: $0.001 to $0.05 USDC per call
- Settled on-chain on Base mainnet through the Coinbase CDP facilitator
- Receiving wallet: 0x2836c673aa155c35D656D655341E16c9997B3A58
- No subscription, no signup, no API key

## Full Endpoint List

- /api/route/signal | $0.0200 | Trading signal - Buy/sell/hold call for a token
- /api/route/market-data | $0.0050 | Market data - Price, volume, market cap
- /api/route/onchain | $0.0100 | Onchain lookup - Wallet activity, holders, flows
- /api/route/sentiment | $0.0050 | Sentiment - Social + news read on a token
- /api/route/safety | $0.0100 | Safety check - Rug/honeypot/contract analysis
- /api/route/dex-route | $0.0100 | DEX route - Best swap route + price impact
- /api/route/gas | $0.0010 | Gas estimate - Current gas price for a chain
- /api/route/mempool | $0.0050 | Mempool watch - Pending tx for a token
- /api/route/mev | $0.0100 | MEV risk - MEV risk score for a planned tx
- /api/route/bridge-quote | $0.0150 | Bridge quote - Cross-chain bridge quote
- /api/route/liquidity | $0.0050 | Liquidity depth - Pool depth at a price level
- /api/route/trending | $0.0050 | Trending tokens - Top trending tokens right now
- /api/route/news | $0.0100 | Token news - Latest news for a token
- /api/route/social-trending | $0.0050 | Social hot - Hot mentions on X / Farcaster
- /api/route/holders | $0.0100 | Holders - Token holder distribution
- /api/route/whale-alert | $0.0300 | Whale alert - Recent whale moves
- /api/route/nft-floor | $0.0050 | NFT floor - NFT floor price
- /api/route/lending-rates | $0.0050 | Lending rates - DeFi lending rates by chain
- /api/route/validator-yield | $0.0050 | Validator yield - Staking yields per validator
- /api/route/portfolio | $0.0200 | Portfolio - Wallet portfolio summary
- /api/route/airdrop | $0.0150 | Airdrop check - Eligibility for current airdrops
- /api/route/predict-pump | $0.0500 | Pump prediction - Will this pump in next hour?
- /api/route/arb-opportunities | $0.0500 | Arb scan - Cross-DEX arbitrage
- /api/route/signal-pro | $0.0300 | Signal Pro - Signal with reasoning + sources
- /api/route/web-search | $0.0100 | Web search - Web search w/ AI-friendly results
- /api/route/web-scrape | $0.0150 | Web scrape - Scrape & extract a URL
- /api/route/news-search | $0.0100 | News search - Search recent news by keyword
- /api/route/wallet-cluster | $0.0250 | Wallet cluster - Find wallets related to a target
- /api/route/wash-detection | $0.0200 | Wash detection - Detect wash trading on a token
- /api/route/bot-detection | $0.0100 | Bot detection - Is this wallet a bot?
- /api/route/phishing-check | $0.0100 | Phishing check - Is this address malicious?
- /api/route/wallet-reputation | $0.0150 | Wallet reputation - Composite reputation score
- /api/route/address-resolve | $0.0010 | Address resolve - ENS / SNS / handle resolution
- /api/route/tx-decode | $0.0020 | Tx decode - Decode a raw transaction
- /api/route/contract-info | $0.0030 | Contract info - Metadata, proxy, owner
- /api/route/abi-fetch | $0.0020 | ABI fetch - Get verified ABI for a contract
- /api/route/mev-protect | $0.0400 | MEV protect - Private-pool submission, sandwich shield
- /api/route/flashloan-route | $0.0500 | Flashloan route - Flash-loan-backed arbitrage path
- /api/route/kol-mention | $0.0100 | KOL mention - Influencer mentions of a token
- /api/route/protocol-tvl | $0.0050 | Protocol TVL - TVL + chains for any DeFi protocol
- /api/route/dex-volume | $0.0050 | DEX volume - Ranked DEX volume by chain
- /api/route/fees-revenue | $0.0100 | Fees & revenue - Protocol fees and revenue rankings
- /api/route/stablecoin-stats | $0.0050 | Stablecoin stats - Supplies, peg deviation, by chain
- /api/route/chain-info | $0.0030 | Chain info - TVL, fees, txn count for any L1/L2
- /api/route/fear-greed | $0.0030 | Fear & Greed - Crypto market sentiment index + classification
- /api/route/global-stats | $0.0030 | Global market - Total mcap, BTC dominance, 24h vol
- /api/route/token-categories | $0.0050 | Token categories - Sector breakdowns (AI, memes, DeFi)
- /api/route/historical-price | $0.0100 | Historical OHLC - OHLC candles for any token
- /api/route/solana-route | $0.0100 | Solana DEX route - Best Jupiter swap route
- /api/route/block-info | $0.0020 | Block info - Block details + gas usage
- /api/route/erc20-balance | $0.0020 | ERC-20 balance - Token balance for any wallet
- /api/route/tx-simulate | $0.0050 | Tx simulate - eth_call dry-run a transaction
- /api/route/nft-owner | $0.0020 | NFT owner - ownerOf for any token id
- /api/route/identity-resolve | $0.0050 | Identity resolve - ENS/Farcaster/Lens/SNS combined
- /api/route/ens-records | $0.0050 | ENS records - All records (avatar, twitter, …)
- /api/route/farcaster-cast | $0.0030 | Farcaster cast - Fetch a public Farcaster cast
- /api/route/weather | $0.0020 | Weather - Current + 7-day forecast by city/coords (Open-Meteo)
- /api/route/geocode | $0.0030 | Geocode - Place name → coordinates (OSM Nominatim)
- /api/route/reverse-geocode | $0.0030 | Reverse geocode - Coordinates → address (OSM Nominatim)
- /api/route/fx-rate | $0.0020 | FX rate - Live fiat currency conversion rates
- /api/route/world-time | $0.0010 | World time - Current local time + offset for any timezone
- /api/route/holidays | $0.0020 | Public holidays - Public holidays for a country in a year (Nager.Date)
- /api/route/hn-trending | $0.0030 | HN trending - Top Hacker News stories right now
- /api/route/github-trending | $0.0050 | GitHub trending - Trending repos by language + window
- /api/route/wikipedia | $0.0030 | Wikipedia - Search + extract Wikipedia article summary
- /api/route/dns-lookup | $0.0020 | DNS lookup - DNS records (A, AAAA, MX, TXT, NS) via Cloudflare DoH
- /api/route/ip-info | $0.0020 | IP info - Geolocation + ASN for any IP (ip-api.com)
- /api/route/stock-quote | $0.0050 | Stock quote - Live equity quote (Yahoo Finance public)
- /api/route/new-pairs | $0.0200 | New pairs - Recently-launched DEX pairs with liquidity rank (DexScreener boosted)
- /api/route/defi-momentum | $0.0100 | DeFi momentum - Top protocols by 1d/7d/30d TVL change (DefiLlama)
- /api/route/dictionary | $0.0010 | Dictionary - Word definitions, phonetic, examples (Free Dictionary API)
- /api/route/synonyms | $0.0010 | Synonyms - Synonyms for a word (Datamuse)
- /api/route/rhymes | $0.0010 | Rhymes - Words that rhyme with X (Datamuse)
- /api/route/lorem-ipsum | $0.0010 | Lorem Ipsum - Generate filler paragraphs
- /api/route/country-info | $0.0010 | Country info - Capital, currency, population, languages (REST Countries)
- /api/route/postal-lookup | $0.0010 | Postal code - Postal code → city/region (Zippopotam.us, multi-country)
- /api/route/iss-location | $0.0010 | ISS position - Current ISS lat/lon (Open Notify)
- /api/route/cat-fact | $0.0010 | Cat fact - Random cat fact (catfact.ninja)
- /api/route/dog-image | $0.0010 | Dog image - Random dog photo URL (dog.ceo)
- /api/route/dadjoke | $0.0010 | Dad joke - Random dad joke (icanhazdadjoke)
- /api/route/trivia | $0.0010 | Trivia question - Random multiple-choice trivia (Open Trivia DB)
- /api/route/guess-age | $0.0010 | Guess age - Predicted age from a first name (agify.io)
- /api/route/guess-gender | $0.0010 | Guess gender - Predicted gender from a first name (genderize.io)
- /api/route/guess-nationality | $0.0010 | Guess nationality - Top likely nationalities from a name (nationalize.io)

## Network

- Chain: Base mainnet (EIP-155 chain ID 8453)
- x402 network: eip155:8453
- Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Protocol: x402 v2 (HTTP 402, PAYMENT-REQUIRED, PAYMENT-SIGNATURE)
- Facilitator: Coinbase Developer Platform (https://api.cdp.coinbase.com/platform/v2/x402)

## Source

- GitHub: https://github.com/SMXFREEZE/traderoute
- MCP server: https://github.com/SMXFREEZE/traderoute/tree/main/mcp
- Built with: Next.js 16 App Router, @x402/next, @x402/fetch, viem, public APIs, and free preview routes