# Toll402 > The OpenRouter for AI-agent tools: one gateway, one wallet, every capability. Built-in tools, community-forged tools and other x402 services, all paid per call in USDC via x402 (HTTP 402). No signup, no API key. Base URL: https://toll402.dev Catalog (JSON): https://toll402.dev/v1/catalog OpenAPI: https://toll402.dev/openapi.json Quickstart (code snippets): https://toll402.dev/v1/quickstart Agent card: https://toll402.dev/.well-known/agent-card.json ## How to pay (x402, no signup) 1. POST to any tool URL with a JSON body. 2. If the response is HTTP 402, the PAYMENT-REQUIRED header (base64 JSON) tells you the price in USDC on Base (eip155:8453). 3. Sign an EIP-3009 USDC transferWithAuthorization for that amount to 0x318d34fa0bd69eff17fac648d2df8cf7a88b3dbe and retry the same request with the PAYMENT-SIGNATURE header. 4. You are only charged when the tool returns 2xx. Errors (4xx/5xx) are never settled. Easiest: wrap your HTTP client — JS: `wrapFetchWithPaymentFromConfig` from @x402/fetch; Python: `x402` package; or run the MCP server: `npx toll402-mcp` with TOLL402_WALLET_KEY set. ## Free trial (no wallet needed) 25 calls per day per IP on tools priced up to $0.005 (read_url, fx_rate, verify_email, business_search, community tools…). Just POST; no payment header. Header x-toll402-trial-remaining shows what's left. After that, pay with x402. ## Referrals (agents recommending agents) Send `x-toll402-ref: ` and `x-toll402-agent: ` on your calls. 10% of your settled calls are paid on-chain to the recommender (who must be a paying wallet here), and you get +25 free-trial calls/day. No signup, no payouts: the pay-to address alternates. ## Start here (one endpoint for everything) POST https://toll402.dev/v1/do { "need": "", "input": { ... } } — routes to the best tool and runs it (≤ maxPriceUsd, default $0.01). GET https://toll402.dev/v1/find?need= — free: ranked tools with schemas and prices. POST https://toll402.dev/v1/forge — create a tool that doesn't exist yet (generated, sandbox-tested, published for everyone). Pass creator=: 70% of every paid call to your tool goes straight to you. ## Verified business directory (engine 4) POST https://toll402.dev/v1/biz/search — businesses by city/category/text/proximity with dated verification scores and evidence. POST https://toll402.dev/v1/biz/verify — is this business real and live? (works for businesses not in the directory too) GET https://toll402.dev/v1/biz/ — free machine-readable profile (hours, services, booking, payments) when the owner has claimed it. Owners: POST /v1/biz/claim { id, domain } → DNS TXT → POST /v1/biz/claim/verify → PUT /v1/biz//profile (Bearer token). Free. ## GET works too Every tool accepts GET with the input as query parameters (e.g. GET /v1/fx?base=USD"e=MXN&amount=100), same price and 402 flow as POST. ## Tool kinds - builtin: first-party, tested (14) - forged: community tools created via /v1/forge, sandboxed (10) - external: other x402 services from the Bazaar, curated and listed with their direct URL (proxy disabled on this instance) (2023) ## Tools ### read_url [builtin] — $0.002 POST https://toll402.dev/v1/read Fetch any public web page (or PDF) and return clean, LLM-ready Markdown with title, metadata and links. Boilerplate, ads and scripts removed. Input schema: {"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL to read","format":"uri"},"format":{"type":"string","enum":["markdown","text","both"],"default":"markdown","description":"Which body format(s) to return"},"includeLinks":{"type":"boolean","default":true},"includeImages":{"type":"boolean","default":false},"maxChars":{"type":"integer","minimum":500,"maximum":500000,"default":200000,"description":"Truncate body to this many characters"}},"required":["url"],"additionalProperties":false} Example body: {"url":"https://en.wikipedia.org/wiki/HTTP_402"} ### pdf_to_text [builtin] — $0.005 POST https://toll402.dev/v1/pdf Download a PDF from a URL and return its full text, page count and title. Input schema: {"type":"object","properties":{"url":{"type":"string","description":"Public URL of a PDF file","format":"uri"},"maxChars":{"type":"integer","minimum":500,"maximum":1000000,"default":300000}},"required":["url"],"additionalProperties":false} Example body: {"url":"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"} ### verify_email [builtin] — $0.001 POST https://toll402.dev/v1/email/verify Validate an email address: syntax, MX/A records, disposable-domain, free-provider and role-account detection, with a 0-100 score. Input schema: {"type":"object","properties":{"email":{"type":"string","description":"Email address to verify","minLength":3,"maxLength":254}},"required":["email"],"additionalProperties":false} Example body: {"email":"support@github.com"} ### fx_rate [builtin] — $0.001 POST https://toll402.dev/v1/fx Exchange rate between two ISO currencies (ECB reference rates), optionally converting an amount. Input schema: {"type":"object","properties":{"base":{"type":"string","maxLength":3,"minLength":3,"default":"USD","description":"ISO 4217 base currency"},"quote":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 quote currency; omit for all rates"},"amount":{"type":"number","minimum":0,"default":1}},"additionalProperties":false} Example body: {"base":"USD","quote":"MXN","amount":100} ### extract_structured [builtin] — $0.06 POST https://toll402.dev/v1/extract Turn a web page or raw text into JSON that matches YOUR JSON Schema. LLM-powered, schema-constrained output — no parsing needed. Input schema: {"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Page to read and extract from"},"text":{"type":"string","maxLength":400000,"description":"Raw text/markdown/HTML to extract from (alternative to url)"},"schema":{"type":"object","additionalProperties":true,"description":"JSON Schema (object) describing the output you want"},"instructions":{"type":"string","maxLength":4000,"description":"Extra guidance, e.g. 'prices in USD', 'dates as ISO 8601'"}},"required":["schema"],"additionalProperties":false} Example body: {"url":"https://news.ycombinator.com","schema":{"type":"object","properties":{"stories":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"points":{"type":"integer"}}}}}}} ### summarize [builtin] — $0.05 POST https://toll402.dev/v1/summarize Faithful summary of a URL or text in the style, length and language you choose. Input schema: {"type":"object","properties":{"url":{"type":"string","format":"uri"},"text":{"type":"string","maxLength":400000},"style":{"type":"string","enum":["bullets","paragraph","tldr","detailed"],"default":"bullets"},"maxWords":{"type":"integer","minimum":20,"maximum":1500,"default":200},"language":{"type":"string","maxLength":40,"default":"same as source","description":"Output language, e.g. 'es', 'en'"},"focus":{"type":"string","maxLength":1000,"description":"What to focus on"}},"additionalProperties":false} Example body: {"url":"https://en.wikipedia.org/wiki/HTTP_402","style":"tldr","language":"es"} ### judge_output [builtin] — $0.07 POST https://toll402.dev/v1/judge Independent LLM-as-judge: scores a candidate output against a task and criteria (0-100), with pass/fail, issues and suggestions. Use it for self-verification, best-of-N, or QA gates. Input schema: {"type":"object","properties":{"task":{"type":"string","description":"The task/instructions the candidate was supposed to fulfil","maxLength":20000},"candidate":{"type":"string","description":"The output to evaluate","maxLength":100000},"reference":{"type":"string","maxLength":100000,"description":"Optional gold/reference answer"},"criteria":{"type":"array","items":{"type":"string","maxLength":300},"minItems":1,"maxItems":10,"default":["correctness","completeness","clarity"]}},"required":["task","candidate"],"additionalProperties":false} Example body: {"task":"Write a haiku about the sea","candidate":"Waves fold into foam / salt wind combs the sleeping dunes / gulls stitch the grey sky","criteria":["is a haiku (5-7-5)","imagery"]} ### provenance [builtin] — $0.01 POST https://toll402.dev/v1/provenance Human or synthetic? Provenance evidence for a URL: archive first-capture date, domain age, authorship markup, curated source tier, AI disclosures and stylometric signals, aggregated into a calibrated 0-100 human-origin score with every piece of evidence. Add deep=true for an LLM stylometric assessment. Input schema: {"type":"object","properties":{"url":{"type":"string","description":"Public URL to assess","format":"uri"},"deep":{"type":"boolean","default":true,"description":"Also run an LLM stylometric assessment (only when the server has an LLM key)"}},"required":["url"],"additionalProperties":false} Example body: {"url":"https://en.wikipedia.org/wiki/Turing_test","deep":false} ### trusted_lookup [builtin] — $0.01 POST https://toll402.dev/v1/lookup Answer from TRUSTED sources only (Wikipedia, Wikidata, arXiv, Crossref/DOI, World Bank): returns passages with URL, reliability tier and retrieval time for citation. With synthesize=true you also get an LLM answer that cites the passages and admits when they don't contain the answer. Input schema: {"type":"object","properties":{"query":{"type":"string","description":"Question or topic","minLength":2,"maxLength":500},"language":{"type":"string","maxLength":10,"default":"en","description":"Wikipedia language edition (en, es, de, fr, pt, ...)"},"sources":{"type":"array","items":{"type":"string","enum":["wikipedia","wikidata","arxiv","crossref","worldbank"]},"default":["wikipedia","wikidata","arxiv","crossref"]},"maxPassages":{"type":"integer","minimum":1,"maximum":20,"default":6},"synthesize":{"type":"boolean","default":true,"description":"Return a cited answer synthesized by an LLM (when the server has an LLM key)"}},"required":["query"],"additionalProperties":false} Example body: {"query":"HTTP 402 payment required","language":"en","sources":["wikipedia","wikidata"],"synthesize":false} ### business_search [builtin] — $0.005 POST https://toll402.dev/v1/biz/search Verified local-business directory for agents. Search by city, category, text or proximity; every result carries a dated verification score (0-100), level (unverified/listed/corroborated/verified/owner_verified) and, on request, the evidence behind it. Open data + live checks + owner claims, never scraped review sites. Input schema: {"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Free text: name, cuisine, service…"},"category":{"type":"string","enum":["restaurant","cafe","bar","hotel","pharmacy","clinic","dentist","lawyer","accountant","gym","salon","bakery","supermarket","hardware","electronics","bank","coworking","school","other"]},"city":{"type":"string","maxLength":80,"description":"City label, e.g. 'Ciudad de México'"},"cityKey":{"type":"string","maxLength":60,"description":"Coverage key, e.g. 'cdmx' or one returned in `coverage` (see GET /v1/biz/coverage)"},"country":{"type":"string","maxLength":2,"minLength":2,"description":"ISO 3166-1 alpha-2"},"near":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"radiusKm":{"type":"number","minimum":0.1,"maximum":50,"default":3}},"required":["lat","lon"],"additionalProperties":false},"minScore":{"type":"integer","minimum":0,"maximum":100,"default":0,"description":"Only businesses with verification score ≥ this"},"minLevel":{"type":"string","enum":["unverified","listed","corroborated","verified","owner_verified"]},"claimedOnly":{"type":"boolean","default":false},"includeEvidence":{"type":"boolean","default":false},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10},"offset":{"type":"integer","minimum":0,"default":0}},"additionalProperties":false} Example body: {"cityKey":"cdmx","category":"dentist","minLevel":"corroborated","limit":5} ### business_verify [builtin] — $0.01 POST https://toll402.dev/v1/biz/verify Is this business real, and is its contact info live? Give an id, website, phone or name: matches it against the directory and runs live checks now (site up, name on site, phone on site, domain age, phone format). Returns evidence, score and verdict. Input schema: {"type":"object","properties":{"id":{"type":"string","maxLength":120,"description":"Business id from search (re-runs live checks now)"},"name":{"type":"string","maxLength":200},"website":{"type":"string","maxLength":300},"phone":{"type":"string","maxLength":40},"address":{"type":"string","maxLength":300},"city":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":2,"minLength":2}},"additionalProperties":false} Example body: {"name":"Wikimedia Foundation","website":"https://wikimediafoundation.org","phone":"+14158396885"} ### business_details [builtin] — $0.08 POST https://toll402.dev/v1/biz/details Deep profile of a business from its OWN website: crawls up to 5 relevant pages (menu, services, prices, hours, contact, booking) and returns a machine-readable profile — summary, hours (OSM syntax), services with prices, booking channels, payments, languages, social links. First-party data only, cached 30 days per business (force=true re-crawls). Input schema: {"type":"object","properties":{"id":{"type":"string","description":"Business id from business_search","maxLength":120},"force":{"type":"boolean","default":false,"description":"Re-crawl even if a fresh (≤30 days) profile is cached"}},"required":["id"],"additionalProperties":false} Example body: {"id":"wd:Q180"} ### forge_tool [builtin] — $0.25 POST https://toll402.dev/v1/forge Create a NEW tool from a description, an input schema and test examples. The code is generated, run in a sandbox against your examples (up to 3 attempts), and on success published as a paid endpoint /v1/t/ for every agent. Infinite tools, on demand. Input schema: {"type":"object","properties":{"name":{"type":"string","description":"Tool name (becomes the endpoint slug)","minLength":3,"maxLength":40},"description":{"type":"string","description":"What the tool does, precisely. Mention data sources (public URLs/APIs without keys) if any.","minLength":20,"maxLength":1000},"inputSchema":{"type":"object","additionalProperties":true,"description":"JSON Schema (type object) for the input"},"outputSchema":{"type":"object","additionalProperties":true,"description":"JSON Schema for the output (recommended)"},"examples":{"type":"array","items":{"type":"object","properties":{"input":{"type":"object","additionalProperties":true},"expectedOutput":{}},"required":["input"],"additionalProperties":false},"description":"Test cases; the tool must pass them to be published","minItems":1,"maxItems":5},"allowNetwork":{"type":"boolean","default":true,"description":"Whether the tool may call public HTTP endpoints"},"priceUsd":{"type":"number","minimum":0.001,"maximum":0.05,"default":0.005,"description":"Price per call for other agents (you never pay to use your own tool's endpoint less than this either)"},"tags":{"type":"array","items":{"type":"string","maxLength":30},"maxItems":8,"default":[]},"creator":{"type":"string","maxLength":80,"description":"Your wallet address or agent id, for attribution"}},"required":["name","description","inputSchema","examples"],"additionalProperties":false} Example body: {"name":"hn_top","description":"Return the top N Hacker News story titles and URLs from https://hacker-news.firebaseio.com/v0/topstories.json and /v0/item/.json","inputSchema":{"type":"object","properties":{"n":{"type":"integer"}},"required":["n"]},"examples":[{"input":{"n":3}}],"priceUsd":0.005} ### do [builtin] — $0.02 POST https://toll402.dev/v1/do One endpoint for everything (OpenRouter-style): describe what you need and pass the input; Toll402 picks the best tool from the whole catalog (built-in, community-forged, external x402 services) and runs it. Tools priced above maxPriceUsd are returned as a match instead of executed. Input schema: {"type":"object","properties":{"need":{"type":"string","description":"What you need, in plain language","minLength":3,"maxLength":500},"input":{"type":"object","additionalProperties":true,"description":"Input for the chosen tool (must match its schema)"},"maxPriceUsd":{"type":"number","minimum":0,"maximum":1,"default":0.01,"description":"Do not execute tools priced above this; return the match instead"},"tool":{"type":"string","description":"Force a specific tool id (skip routing)"}},"required":["need","input"],"additionalProperties":false} Example body: {"need":"convert 100 US dollars to Mexican pesos","input":{"base":"USD","quote":"MXN","amount":100}} ### ip_geolocate [forged] — $0.002 POST https://toll402.dev/v1/t/ip_geolocate Country, region, city, timezone and ASN for an IPv4/IPv6 address via https://ipapi.co//json/ Input schema: {"type":"object","properties":{"ip":{"type":"string"}},"required":["ip"]} Example body: {"ip":"8.8.8.8"} ### text_stats [forged] — $0.001 POST https://toll402.dev/v1/t/text_stats Word/sentence/paragraph counts, reading time (200 wpm), top 10 keywords (stopwords removed) for a text Input schema: {"type":"object","properties":{"text":{"type":"string"}},"required":["text"]} Example body: {"text":"Agents pay agents. Agents build tools for agents."} ### json_schema_validate [forged] — $0.001 POST https://toll402.dev/v1/t/json_schema_validate Validate a JSON value against a JSON Schema subset (type, properties, required, enum, minimum/maximum, minLength/maxLength, items) and return errors Input schema: {"type":"object","properties":{"schema":{"type":"object"},"value":{}},"required":["schema","value"]} Example body: {"schema":{"type":"object","properties":{"a":{"type":"integer"}},"required":["a"]},"value":{"a":"x"}} ### rss_latest [forged] — $0.003 POST https://toll402.dev/v1/t/rss_latest Parse an RSS/Atom feed URL and return the latest N items (title, link, published) Input schema: {"type":"object","properties":{"url":{"type":"string"},"n":{"type":"integer","default":10}},"required":["url"]} Example body: {"url":"https://hnrss.org/frontpage","n":3} ### url_status [forged] — $0.001 POST https://toll402.dev/v1/t/url_status HTTP status, final content-type and response size for a URL (HEAD then GET fallback) Input schema: {"type":"object","properties":{"url":{"type":"string"}},"required":["url"]} Example body: {"url":"https://example.com"} ### crypto_price [forged] — $0.002 POST https://toll402.dev/v1/t/crypto_price Spot price in USD for a crypto asset symbol using https://api.coinbase.com/v2/prices/-USD/spot Input schema: {"type":"object","properties":{"symbol":{"type":"string"}},"required":["symbol"]} Example body: {"symbol":"ETH"} ### npm_package_info [forged] — $0.003 POST https://toll402.dev/v1/t/npm_package_info Latest version, description, license, weekly downloads (via api.npmjs.org) and homepage for an npm package Input schema: {"type":"object","properties":{"name":{"type":"string"}},"required":["name"]} Example body: {"name":"hono"} ### github_repo_stats [forged] — $0.003 POST https://toll402.dev/v1/t/github_repo_stats Stars, forks, open issues, license and last push for a GitHub repo via https://api.github.com/repos// Input schema: {"type":"object","properties":{"owner":{"type":"string"},"repo":{"type":"string"}},"required":["owner","repo"]} Example body: {"owner":"coinbase","repo":"x402"} ### hn_top [forged] — $0.005 POST https://toll402.dev/v1/t/hn_top Top N Hacker News stories (title, url, score) via https://hacker-news.firebaseio.com/v0/topstories.json and /v0/item/.json Input schema: {"type":"object","properties":{"n":{"type":"integer","minimum":1,"maximum":30}},"required":["n"]} Example body: {"n":3} ### wikipedia_summary [forged] — $0.002 POST https://toll402.dev/v1/t/wikipedia_summary Summary extract and canonical URL for a Wikipedia topic via https://.wikipedia.org/api/rest_v1/page/summary/ Input schema: {"type":"object","properties":{"title":{"type":"string"},"lang":{"type":"string","default":"en"}},"required":["title"]} Example body: {"title":"HTTP 402"} ## Response envelope { "ok": true, "tool": "<name>", "ms": <latency>, "result": { ... } } Errors: { "ok": false, "error": "<code>", "message": "..." }