Docs

Rail A · prepaid credits (API key)

For people who run agents and have a card.

1. Go to /credits, choose an amount (min $5) and pay with Stripe Checkout. You get a key tk_… shown once. Programmatic: POST https://toll402.dev/v1/credits/checkout {"usd": 20, "email": "…"} → { url, apiKey }.
2. Send the key on every call as the header x-toll402-key: tk_… (or Authorization: Bearer tk_…). In toll402-mcp set TOLL402_API_KEY.
3. Each 2xx response carries x-toll402-charged and x-toll402-balance. GET /v1/account returns balance and ledger; POST /v1/account/rotate replaces the key. Humans: sign in with the key at /credits to open the account dashboard (balance, activity, top-ups, key rotation).
4. When the balance cannot cover a call you get 402 insufficient_credits with the price and a top-up link. Nothing is charged for 4xx/5xx.
5. Top up with USDC instead of a card: POST https://toll402.dev/v1/credits/x402/<accountId>/<usd> paid via x402 (min $1, max $1000); the credits are added the moment the transfer settles on Base. An agent with a wallet can fund its operator's account this way.

One key per agent, with a daily cap

The key you get at checkout is the owner key: it signs in to the dashboard and manages the account. Create agent keys for each agent (dashboard, or POST /v1/keys {"name":"research-bot","dailyCapUsd":2} with the owner key). They share the balance, spend up to their cap per UTC day, cannot manage the account, and see only their own calls. Over the cap a call answers 402 key_daily_cap with the reset time. PATCH /v1/keys/<id> renames, re-caps or disables ({"disabled":true} answers 401 key_disabled); POST /v1/keys/<id>/rotate; DELETE /v1/keys/<id>.

Call history and stored answers

Every charged response carries x-toll402-call-id. GET /v1/calls?days=7&tool=…&key=…&limit=…&before=… lists paid calls with cost, key and input summary; GET /v1/calls/<id> returns the stored answer for 24 hours, so a response your code dropped after paying for it is not lost.

Reviews

After using an answer, rate it: POST /v1/calls/<id>/review {"useful": true, "reason": "…"} (credits) or POST /v1/reviews {"tx": "<settlement tx>", "useful": false} (x402). Tools with good reviews rank higher in /v1/find and /v1/do; each tool's stats.usefulRate is public. Over MCP: the toll402_review tool.

Automatic top-up

Optional. In the dashboard choose an amount and a threshold; the first top-up goes through Stripe Checkout and saves the card, then the card is charged automatically whenever the balance drops below the threshold (at most 5 a day, one every 10 minutes). A call that would not fit the balance triggers it and goes through once the payment clears. It switches off after a failed charge and emails you. API (owner key): POST /v1/account/auto-topup {"usd":20,"belowUsd":5}, {"enabled":false}.

curl https://toll402.dev/v1/account -H 'x-toll402-key: tk_…'
{"ok":true,"account":{"id":"acc_…","balanceUsd":19.98,"ledger":[{"usd":-0.002,"tool":"read_url","balanceUsd":19.98,…}]}}

Rail B · x402 (wallet, no account)

For autonomous agents. Fund an EVM wallet with a few USDC on Base (eip155:8453); no ETH needed, the facilitator pays gas.

1. POST to any tool. The answer is 402 with a PAYMENT-REQUIRED header (base64 JSON: amount, asset, pay-to 0x318d34fa0bd69eff17fac648d2df8cf7a88b3dbe).
2. Sign an EIP-3009 transferWithAuthorization for that amount and retry with PAYMENT-SIGNATURE. Libraries: @x402/fetch (JS), x402 (Python), toll402-client, toll402-mcp.
3. Settlement happens only after a 2xx. Errors are never settled.

# any tool, same price either way · key from https://toll402.dev/credits
curl -X POST https://toll402.dev/v1/do \
  -H 'x-toll402-key: tk_…' -H 'content-type: application/json' \
  -d '{"need":"keyword search volume for iphone in the US","input":{"keywords":["iphone"]}}'
# response headers: x-toll402-charged: 0.0128  x-toll402-balance: 19.9872

# no account: the 402 carries the price, your x402 client signs a USDC authorization and retries
curl -i -X POST https://toll402.dev/v1/read -H 'content-type: application/json' -d '{"url":"https://example.com"}'
# HTTP/2 402 · PAYMENT-REQUIRED: eyJ4NDAy…  → pay with @x402/fetch, x402 (Python) or toll402-client

{ "mcpServers": { "toll402": { "command": "npx", "args": ["-y", "toll402-mcp"],
  "env": { "TOLL402_API_KEY": "tk_…" } } } }
// or with a wallet: "env": { "TOLL402_WALLET_KEY": "0x…", "TOLL402_MAX_USD": "0.25" }
// remote (no install): https://toll402.dev/mcp — send x-toll402-key as a header

import { Toll402 } from "toll402-client";
const t = new Toll402({ walletKey: process.env.WALLET_KEY, maxUsdPerCall: 0.25 });
const page = await t.read("https://example.com");                                   // $0.002
const biz  = await t.business.search({ city: "Guadalajara", category: "dentist" });  // $0.005
const kw   = await t.call("p/dataforseo.x.ai-optimization-ai-keyword-data-keywords-search-volume-live", { keywords: ["iphone"], location_code: 2840 });

# pip install x402 httpx eth-account  (or just send the x-toll402-key header with httpx)
import httpx
r = httpx.get("https://toll402.dev/v1/find", params={"need": "backlinks for a domain"})       # free: ranked tools + prices
r = httpx.post("https://toll402.dev/v1/p/moz.web.url.metrics", headers={"x-toll402-key": "tk_…"}, json={"targets": ["moz.com"]})

Calling tools

• Envelope: { "ok": true, "tool": "<id>", "kind": "builtin|forged|provider|external", "ms": 412, "result": … }. Errors: { "ok": false, "error": "<code>", "message": "…" }.
• GET works too: GET /v1/fx?base=USD&quote=MXN&amount=100, same price and flow.
• Specs are free: /v1/catalog (curated), /v1/tools?kind=&q=&platform=&category=&limit=&offset= (everything, paged), /v1/spec/t/<slug>, /v1/spec/p/<id>, /v1/spec/x/<id>.
• Price per request: a few tools price by input (e.g. provenance deep, trusted_lookup synthesized); the 402 or the credits debit always uses the exact price for that body.
• Idempotency (credits rail): send Idempotency-Key: <unique>; a retry with the same key within 24 h returns the stored answer with x-toll402-replayed: true and is not charged again. Reusing a key for a different tool answers 409.
• Reliability signals: every catalog entry carries stats (calls in the last 7 days, success rate, average latency) measured on this gateway; /v1/find ranks reliable endpoints higher.

Find & route

• GET /v1/find?need=verify+a+dentist+in+Monterrey — free, ranked matches with schema and price across all kinds.
• POST /v1/do { "need": "…", "input": {…}, "maxPriceUsd": 0.05 } — $0.02 + the tool: picks the best executable tool under the cap and runs it, returning alternatives.

Provider APIs (2,496 endpoints, 76 platforms)

Third-party APIs resold through one key/wallet: SEO (Semrush, DataForSEO, Moz, SerpApi…), social data (TikTok, Instagram, YouTube, LinkedIn, X, Reddit, Douyin…), people and company enrichment (Hunter, Apollo, Crunchbase…), ads, stocks and crypto, image and video generation. Price = vendor rate + 25%, never below $0.001.

• Endpoint: POST https://toll402.dev/v1/p/<endpoint id> with the vendor's own parameters as JSON (GET endpoints accept them as query params). The response's result.data is the vendor's response unchanged; result.upstreamCostUsd is what the vendor billed.
• Find one: catalog (by category and platform), /v1/find, or /v1/tools?kind=provider&q=…&platform=…&category=….
• Some endpoints bill per result or per success (see meta.pricing); the price you are charged is fixed per call as shown, and a miss (empty result with 200) is still a successful call.
• Availability follows the upstream: a vendor error returns 502 upstream_error (not charged); when the gateway's daily provider budget is exhausted you get 503 provider_daily_cap with retryAfterSec.

Image and video generation (async tasks)

Generation endpoints (Flux, GPT Image, Gemini Image, Veo, Kling, Hailuo, Seedance…) take seconds to minutes, so they run as tasks. They are paid with prepaid credits, because a failed task is refunded in full.

1. POST https://toll402.dev/v1/p/<id> with the vendor's parameters and your key. The answer is 202 with result.job.id. The price depends on the options (model, duration, resolution, number of images) and is shown in x-toll402-charged; /v1/spec/p/<id> lists the range.
2. Poll GET https://toll402.dev/v1/jobs/<job id> with the same key: about every 10 s for images, every 30-60 s for video. Status is pending, succeeded (with result.urls) or failed (credits refunded, reason in error).
3. Download the media promptly: provider links expire (the job says when). Over MCP use toll402_job. GET /v1/jobs lists your tasks.

Verified business directory

• POST /v1/biz/search ($0.005): by city, country, category, text or proximity; dated verification score and evidence; contact channels; B2B filters (hasWebsite, hasEmail, minEmployees…). Unknown cities are seeded on demand (503 region_seeding means come back in a few minutes; not charged).
• POST /v1/biz/verify ($0.01) live check of any business; POST /v1/biz/details ($0.08) crawls the business's own site into hours/services/prices/booking; business_shortlist ($0.25) ranked options for a need.
• Owners: POST /v1/biz/claim → DNS TXT → POST /v1/biz/claim/verify → PUT /v1/biz/<id>/profile. Free. Browse: /directory.

Forge a tool

POST /v1/forge ($0.25): describe the tool and give examples; it is generated, tested in a WebAssembly sandbox and published at /v1/t/<name> for everyone at the price you set. Pass creator: "0x…" to receive 70% of every settled call, paid by the protocol.

MCP

{ "mcpServers": { "toll402": { "command": "npx", "args": ["-y", "toll402-mcp"],
  "env": { "TOLL402_API_KEY": "tk_…" /* or "TOLL402_WALLET_KEY": "0x…" */, "TOLL402_MAX_USD": "0.25" } } } }

Remote, no install: https://toll402.dev/mcp (Streamable HTTP). Send x-toll402-key or x402 headers on the connection; clients that cannot set headers (ChatGPT connectors) can use https://toll402.dev/mcp?key=tk_…. Per-client setup: connect section. Listed in the official MCP Registry and Smithery. Provider endpoints are reached through the find and do tools rather than listed individually.

For agents (machine-readable)

• /llms.txt and /llms-full.txt · /v1/catalog · /openapi.json · agent card (A2A) · mcp.json · /v1/quickstart · /v1/system-prompt.
• Every 402 body explains how to pay; every error body says what to do next. Nothing requires a browser.

Limits & errors

• Unpaid requests: 120 per minute per IP. Paid requests (x402 or key) are not rate-limited by us; upstream vendors have their own limits (429 passes through, not charged).
• Error codes: invalid_input 400 (with example and schema) · payment_required 402 · insufficient_credits 402 · invalid_api_key 401 · not_found 404 · rate_limited 429 · upstream_error 502 · provider_daily_cap / provider_wallet_empty / region_seeding 503 (with retryAfterSec).
• Status: /health · usage: /v1/stats.

Terms in short

Full text: Terms of service · Privacy policy.

Credits are prepaid, non-refundable, non-transferable and consumed per call at the listed price; unused credits do not expire, and every debit is in your ledger (GET /v1/account). Vendor data is relayed unchanged and subject to the vendor's terms; do not use it to break their rate limits or to disguise automated traffic. Directory data aggregates dated public evidence; "unverified" means unknown, not fake. Questions: hello@toll402.dev.