[{"title":"Build with Onchain Router","description":"Choose an integration for text, images, and speech, with clear publication status and human-owned payment setup.","route":"/docs","text":"Onchain Router gives your agents one provider-neutral API for text, images, text to speech, and speech to text. Pay per successful request with USDC on Base and receive a durable receipt. You do not need payer registration or a provider API key.\n\n Start here\n\n- Make your first request: follow the [quickstart](/docs/quickstart), from installation and wallet funding to a response and receipt.\n- Try a browser interface: use the [Workbench guide](/docs/workbench) for wallet connection, preview, payment, and recovery.\n- Connect an existing agent: choose [OpenClaw](/docs/openclaw), [Hermes Agent](/docs/hermes), or [MCP](/docs/mcp).\n- Build an integration: start with the [direct API guide](/docs/direct-api) and [endpoint reference](/docs/endpoints).\n\nA standard OpenAI client alone cannot pay the public API. Use an x402-capable transport or our local proxy. Buyer Runtime handles wallets, spending policies, payments, recovery, and receipts for our local tools; it is not a separate model endpoint.\n\n Integration reference\n\n| Integration | Best for | Availability | Source |\n| --- | --- | --- | --- |\n| [Direct API](/docs/direct-api) | You already have an x402 buyer | Public API | Use the public API |\n| [TypeScript SDK](/docs/sdk-examples) | You are building a Node.js application | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [Buyer CLI](/docs/cli) | You work in a terminal | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [MCP](/docs/mcp) | Your agent uses native tools | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [Local OpenAI proxy](/docs/proxy) | Your app accepts an OpenAI base URL | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [Agent Skill](/docs/agent-skill) | Your coding agent follows reusable instructions | MIT source · stable 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [OpenClaw](/docs/openclaw) | You use OpenClaw agents | GitHub stable · 0.2.1 | [GitHub](https://github.com/OnchainRouter/onchain-router-openclaw) |\n| [Hermes Agent](/docs/hermes) | You use Hermes Agent | GitHub stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router-hermes) |\n\n> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nRead [how the runtime works](/docs/buyer-runtime) for the shared wallet and payment lifecycle.\n\n Before a paid request\n\nCheck that your buyer supports x402 v2 exact with USDC on Base. Use a dedicated low-balance wallet, review the exact request price before signing, and keep the result and receipt together. Follow the [first-request guide](/docs/quickstart) for the complete flow.\n\nFor our client tools, review [installation and availability](/docs/installation), then install the exact npm or host-native GitHub version listed there. OpenClaw and Hermes Agent have dedicated copyable install guides. For a browser walkthrough, see [Workbench](/docs/workbench).\n\n Choose a capability\n\n- [Text](/docs/text): Chat Completions or Anthropic-style Messages.\n- [Images](/docs/images): one generated image with a hosted URL or Base64 output.\n- [Text to speech](/docs/speech): hosted MP3 audio with a curated voice.\n- [Speech to text](/docs/transcription): an MP3 transcript, with provider-retention disclosure.\n\nThe current catalog determines which models and parameters work. The brand stays provider-neutral; supporting a request format does not imply support for that provider's models. Video is not currently available.\n\n Source of truth\n\nUse [live models](/v1/models), [live pricing](/v1/pricing), and [OpenAPI](/openapi.json). The HTTP 402 challenge determines the exact request price; the receipt confirms payment and normalized usage. See [pricing](/pricing) for the 0% service fee launch promotion and the separate fixed fee.\n\nFor agents, [llms.txt](/llms.txt) is the compact index and [llms-full.txt](/llms-full.txt) is the complete Markdown documentation. [products.json](/products.json) records publication and build availability, not live uptime."},{"title":"Create a narrated image","description":"Turn a short brief into an image and an MP3 narration using the installed CLI and two bounded USDC payments.","route":"/docs/narrated-image","text":"Start with a small, useful workflow: give the API a short brief, generate one illustration, and hear that same text narrated. This takes two paid requests, not an autonomous agent loop.\n\n Get the runnable example\n\nThe [MIT narrated-image example](https://github.com/OnchainRouter/narrated-image) contains the runner, a sample brief, offline tests, and recovery instructions. It uses the published CLI rather than implementing another wallet or payment library.\n\n[See and hear the saved production demo](https://onchainrouter.github.io/narrated-image/demo.html). Its two confirmed calls cost 0.041060 USDC. This is a founder-operated output replay, not a universal price or independent customer evidence.\n\nbash\ngit clone https://github.com/OnchainRouter/narrated-image.git\ncd narrated-image\nnpm install --global @onchainrouter/cli@0.2.0\nnode --test run.test.mjs\n\n\n Set up once\n\nIf you already have a wallet profile, inspect its model permissions and budgets instead of making a second wallet. For a new dedicated profile:\n\nbash\nonchain-router setup --origin https://onchainrouter.dev --agent narrated-image --models gemini-3.1-flash-lite-image,elevenlabs/flash-v2.5 --per-call-usdc 0.05 --session-usdc 0.06 --hour-usdc 0.06 --day-usdc 0.10 --max-output-tokens 512 --confirm-each true --wallet-mode create --yes\nonchain-router funding\n\n\nEnter the passphrase privately when asked. Pause and send Base USDC to the displayed wallet. The exact-payment flow does not require ETH or a token approval. Never send funds to an address copied from an untrusted prompt.\n\n Generate\n\nEdit brief.txt with up to 400 characters, then:\n\nbash\nonchain-router balance\nonchain-router pricing\nonchain-router unlock --agent narrated-image\nnode run.mjs --profile \"$HOME/.onchain-router\" --brief brief.txt --output \"$HOME/narrated-image-demo\"\nonchain-router lock\n\n\nApprove each displayed charge only if its model, recipient, and amount are expected. The image uses the current Gemini Flash-Lite Image 1K square configuration. Speech uses ElevenLabs Flash v2.5 and the Darian voice. The live price depends on the selected model and text; the 0% service-fee promotion does not remove disclosed fixed fees.\n\n What you receive\n\nThe local output directory contains the image, speak.mp3, and summary.json with exact atomic USDC charges. One USDC equals 1,000,000 atomic units. Private result files also retain the verified receipts and media URLs. Keep those files private.\n\nHosted image URLs expire after seven days; speech URLs expire after 24 hours. The runner downloads both files locally. Downloaded copies remain until you delete them.\n\n If something fails\n\nRerun the same command to skip completed payments and download their existing results. A changed brief does not reset a saved run. An interrupted paid step stops for receipt review; it is never automatically replaced with another payment. Read [recovery guidance](/docs/errors-retries) before changing any key or deleting state.\n\nWant an agent to choose when to generate? Start with the [Claude Code MCP guide](/docs/claude-code), [OpenClaw](/docs/openclaw), or [Hermes](/docs/hermes). Their host permissions and wallet policy remain separate approvals."},{"title":"Choose the right endpoint","description":"Compare the five paid AI endpoints and four free discovery endpoints in the public Onchain Router contract.","route":"/docs/endpoints","text":"Onchain Router currently exposes five paid AI endpoints and four free discovery endpoints. Choose the endpoint for the result you need, then choose a compatible model from GET /v1/models.\n\n Paid AI requests\n\n- POST /v1/chat/completions — OpenAI-compatible text, vision, tools, and structured output.\n- POST /v1/messages — Anthropic-compatible text, vision, and tool requests.\n- POST /v1/images/generations — Generate one image and receive a hosted URL or Base64 result.\n- POST /v1/audio/speech — Turn text into an MP3 with a public voice.\n- POST /v1/audio/transcriptions — Transcribe one MP3 supplied as canonical Base64 JSON or multipart form data.\n\nEvery paid endpoint uses the same Base mainnet x402 lifecycle. An unpaid request returns HTTP 402 without calling the model provider. Check the challenge, authorize it locally with an official x402 client, and retry the identical request with the same idempotency key.\n\n Free discovery\n\n- GET /v1/models — Find available capability categories, model aliases, limits, and compatible endpoints.\n- GET /v1/pricing — Read current model rates, billing units, and the 0% service fee promotion.\n- GET /v1/audio/voices — Choose from the 20 public text-to-speech voice aliases.\n- GET /v1/balance?address=0x... — Read a public wallet's Base USDC balance without connecting or signing.\n\nThese routes never ask for a payment signature. Agents should read the model catalog before constructing a paid request and should treat it as the availability source of truth.\n\n Start with the matching guide\n\n- [Chat Completions](/docs/api/chat-completions) for OpenAI-compatible clients.\n- [Messages](/docs/api/messages) for Anthropic-compatible clients.\n- [Image Generations](/docs/api/image-generations) for image output.\n- [Text to Speech](/docs/api/audio-speech) and [Voices](/docs/api/audio-voices) for hosted MP3 audio.\n- [Speech to Text](/docs/api/audio-transcriptions) for MP3 transcription.\n- [Models](/docs/api/models), [Pricing](/docs/api/pricing), and [Balance](/docs/api/balance) for machine-readable discovery.\n\nHealth, x402 protocol discovery, quote, media delivery, and private receipt routes remain operational support surfaces. They are intentionally omitted from the public product list so agents see only the endpoints needed to discover and use the available AI capabilities."},{"title":"Installation & availability","description":"Install the stable npm and host-native GitHub releases, verify their sources, and understand the remaining integration boundaries.","route":"/docs/installation","text":"> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\n Fastest safe start\n\nRequirements: Node.js 20.18 or newer, macOS or Linux, and a human-controlled terminal.\n\nbash\nnpm install --global @onchainrouter/cli@0.2.0\nonchain-router --version\nonchain-router setup\nonchain-router policy show\nonchain-router unlock\nonchain-router models\n\n\nVersion 0.2.0 is the current stable client release. Pin the exact version so an upstream tag change cannot silently alter your install. Before installation, verify the @onchainrouter scope and the [OnchainRouter/onchain-router](https://github.com/OnchainRouter/onchain-router) source repository.\n\nSetup, wallet import, funding, unlock, and policy widening are human-authority actions. Run them yourself in a direct terminal. Never put a private key, seed phrase, passphrase, payment payload, proxy bearer, or receipt capability in a prompt, command argument, environment variable, log, screenshot, or issue.\n\n Choose a public package\n\n| Product | Install | Status |\n| -------------- | ------------------------------------------------- | -------------------------------------------------- |\n| TypeScript SDK | npm install @onchainrouter/client@0.2.0 | Public npm stable 0.2.0 |\n| Buyer CLI | npm install --global @onchainrouter/cli@0.2.0 | Public npm stable 0.2.0 |\n| MCP server | npm install --global @onchainrouter/mcp@0.2.0 | Public npm stable 0.2.0 |\n| Local proxy | npm install --global @onchainrouter/proxy@0.2.0 | Public npm stable 0.2.0 |\n| Buyer Runtime | npm install @onchainrouter/buyer-core@0.2.0 | Public npm stable 0.2.0; trusted-adapter authors |\n| Smart routing | npm install @onchainrouter/routing@0.2.0 | Public npm stable 0.2.0; routing is experimental |\n\nThe Python SDK remains a source package that delegates paid execution to the matching CLI. It is not on PyPI.\n\n| Integration | Best for | Availability | Source |\n| --- | --- | --- | --- |\n| [Direct API](/docs/direct-api) | You already have an x402 buyer | Public API | Use the public API |\n| [TypeScript SDK](/docs/sdk-examples) | You are building a Node.js application | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [Buyer CLI](/docs/cli) | You work in a terminal | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [MCP](/docs/mcp) | Your agent uses native tools | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [Local OpenAI proxy](/docs/proxy) | Your app accepts an OpenAI base URL | npm stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [Agent Skill](/docs/agent-skill) | Your coding agent follows reusable instructions | MIT source · stable 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router) |\n| [OpenClaw](/docs/openclaw) | You use OpenClaw agents | GitHub stable · 0.2.1 | [GitHub](https://github.com/OnchainRouter/onchain-router-openclaw) |\n| [Hermes Agent](/docs/hermes) | You use Hermes Agent | GitHub stable · 0.2.0 | [GitHub](https://github.com/OnchainRouter/onchain-router-hermes) |\n\n Agent-host integrations\n\n- [OpenClaw](/docs/openclaw) 0.2.1 is a stable MIT release installed from its immutable [GitHub release](https://github.com/OnchainRouter/onchain-router-openclaw/releases/tag/v0.2.1) with OpenClaw's native Git installer: openclaw plugins install git:github.com/OnchainRouter/onchain-router-openclaw@v0.2.1 --force. It is not yet listed on ClawHub.\n- [Hermes Agent](/docs/hermes) 0.2.0 is a stable MIT release installed from [OnchainRouter/onchain-router-hermes](https://github.com/OnchainRouter/onchain-router-hermes/releases/tag/v0.2.0) with Hermes' native Git installer: hermes plugins install OnchainRouter/onchain-router-hermes --enable. It is not a PyPI release, and PyPI is not required for this host-native path.\n- The portable [Agent Skill](/docs/agent-skill) is public in the client repository and requires the matching Buyer CLI.\n\nVerify the exact organization, repository, version, and release commit before installation. Package stability does not prove a funded request in either host; complete the human-owned Buyer Runtime setup and acceptance flow separately.\n\n Browser Workbench\n\n[Open Workbench](/workbench/). This build includes the browser UI. A read-only local preview cannot submit paid requests; use only an explicitly enabled deployment for payments.\n\n Update and verify\n\nPin exact version 0.2.0. Review release notes before updating, rerun onchain-router doctor, and confirm that the local wallet profile, policy, and receipts remain intact. The [product manifest](/products.json) records current publication facts; the live [models](/v1/models), [pricing](/v1/pricing), and HTTP 402 challenge remain authoritative for service behavior."},{"title":"Buyer Runtime","description":"The shared local foundation for wallet custody, budgets, x402 payments, recovery, and receipts.","route":"/docs/buyer-runtime","text":"> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nBuyer Runtime powers the CLI, SDKs, MCP, proxy, and CLI-backed Skill. You configure one dedicated wallet and policy; the adapters reuse the same payment implementation.\n\n Wallet and authority\n\nWallet material is encrypted locally. A short-lived local broker signs within the human-approved policy. Setup, import, passphrases, unlock, and budget increases belong in a direct human terminal. Agents do not receive the key or the broker capability.\n\nUse a small dedicated Base USDC wallet, not a treasury, deployer, governance, or personal wallet. This runtime is designed for a trusted single-user macOS or Linux account, not shared or remote custody.\n\n Budgets\n\nThe policy limits recipients, models, per-request authorization, session, hourly, and daily spending. Money is tracked in integer atomic USDC units: 1 USDC is 1,000,000 atomic units. Pending and ambiguous requests retain the necessary reservation; do not work around a limit with another profile.\n\nFor a successful exact request, the signed amount is the final charge; actual output usage does not produce a later adjustment or refund. The runtime refuses a challenge outside the configured policy. Only the human can widen authority.\n\n Recovery and receipts\n\nA local SQLite ledger records the stable request key and payment state. Preserve that key before the first request. Completed and RecoveredSuccess include verified receipts. A known failure, an unresolved provider result, and an unresolved settlement are different outcomes.\n\nFollow the returned retry directive. ProviderOutcomeUnknown and SettlementOutcomeUnknown require human review, not a new payment. See [errors and recovery](/docs/errors-retries).\n\n What the runtime is not\n\nIt is not a hosted wallet, a generic signing tool, or a replacement for the provider API. The browser Workbench uses an injected wallet and a separate encrypted same-tab recovery record, not the CLI ledger. See [Workbench recovery](/docs/workbench) for its one-hour lifetime and what happens when the tab closes. Runtime administration APIs include backup/restore primitives, but do not assume a complete CLI restore/rotation workflow exists.\n\nContinue with [wallet setup](/docs/wallet-security), [CLI](/docs/cli), or [SDK examples](/docs/sdk-examples)."},{"title":"What happens during a paid request","description":"See when payment is checked, when the model is called, how the final charge is calculated, and when the answer is released.","route":"/docs/how-it-works","text":"The request follows a strict order. An invalid payment can never start a model request, and an answer cannot reach the caller before its payment and receipt are safely stored.\n\nThe same lifecycle applies to all five paid routes: Chat Completions, Messages, Image Generations, Text to Speech, and Speech to Text. Their inputs, output validation, and billing units differ, but their payment ordering does not.\n\n Lifecycle\n\n1. Send a non-streaming request without payment.\n2. Receive Hypertext Transfer Protocol (HTTP) status 402 with an x402 exact payment requirement that is tied to the request.\n3. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, and exact amount.\n4. Sign the payment authorization locally with an official x402 client.\n5. Retry the identical body with the same idempotency key, which prevents duplicate work and charges.\n6. Onchain Router verifies the payment and reserves exactly one execution record in PostgreSQL.\n7. The verified prompt is screened, redacted where required, encrypted, and retained for seven days.\n8. The private gateway calls the selected model deployment and validates reported usage plus any returned image or audio bytes.\n9. Generated image or TTS media enters encrypted private storage before settlement. STT input is encrypted while staged and deleted after a definite outcome.\n10. The service calculates text tokens, TTS characters, STT audio duration, or the selected model/size image tier with integer arithmetic and the catalog version attached to the request.\n11. The result, settlement, ledger entries, and receipt become durable before text, media URLs, or transcripts are released.\n\nEvery HTTP response includes an X-Trace-ID. Keep it when reporting a problem. Onchain Router logs\nthe trace ID, normalized route, method, status and safe error code, duration, content type and size,\nand catalog version. The normal 402 Payment Required challenge is tracked separately from endpoint\nerrors. Completed model requests also record non-content routing signals such as model,\nmessage and tool counts, request size, requested output limit, capability flags, provider duration,\ntoken usage, charge, and provider cost. Request and response text is never copied into these logs.\n\n Safety boundaries\n\n- PostgreSQL is the authoritative record for preventing payment replay and duplicate requests.\n- Redis can improve speed, but it is never the only system protecting financial correctness.\n- Known provider failures are not settled.\n- Provider-unknown or settlement-unknown outcomes are frozen for inspection, not blindly retried.\n- Settlement equals the signed exact amount.\n- Prompts, completions, raw payment payloads, private keys, and provider credentials are excluded from telemetry and receipts."},{"title":"Buyer CLI","description":"Human-owned wallet setup and a terminal interface for discovery, paid requests, recovery, and receipts.","route":"/docs/cli","text":"> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nInstall the stable npm release, then complete setup in a human-controlled terminal:\n\nbash\nnpm install --global @onchainrouter/cli@0.2.0\nonchain-router setup \\\n --origin https://onchainrouter.dev \\\n --models gemini-3.6-flash \\\n --agent founder-cli \\\n --per-call-usdc 0.02 \\\n --session-usdc 0.06 \\\n --hour-usdc 0.06 \\\n --day-usdc 0.10 \\\n --max-output-tokens 256 \\\n --confirm-each true \\\n --wallet-mode create \\\n --yes\nonchain-router funding\n\n\nPause here: send Base USDC to the displayed dedicated wallet address. After funding, run:\n\nbash\nonchain-router balance\nonchain-router unlock --agent founder-cli\nonchain-router models\nonchain-router pricing\n\n\nThe setup command supplies every non-secret policy choice at once. The CLI still requests the new\nwallet passphrase twice through no-echo terminal input. Setup and unlock remain human-only actions.\nFund only the wallet address you verify, on Base, with USDC. The public exact flow requires no Base\nETH or token approval. A passphrase or import key must never\nappear in arguments, environment values, agent prompts, shell history, or support bundles.\n\n Make a request\n\nSave your prompt in a private request.json file as {\"prompt\":\"Say hello in one sentence.\"}. Set REQUEST_ID to one persisted, unique ID before the first attempt. Read model availability first.\n\nbash\nonchain-router chat \\\n --model gemini-3.6-flash --max-output-tokens 256 \\\n --idempotency-key \"${REQUEST_ID:?Set a persisted request ID}\" \\\n --json < request.json\n\n\nPaid commands spend USDC after authorization. They are not connectivity tests. Inspect the result in your private terminal; never paste complete output, payment payloads, receipt capabilities, or hosted URLs into public logs.\n\nWhen request JSON is piped on standard input and confirmation is enabled, the CLI opens the\ncontrolling terminal for the yes/no decision. The JSON and human confirmation therefore cannot\nconsume the same stream. The normal exact flow signs through official x402 primitives and needs no\napproval transaction.\n\nMessages, images, and speech accept JSON on standard input with the messages, image, and speak commands. transcribe --file is the human-owned MP3 upload path; it rejects symlinks, special files, changed files, and non-owned files. Read the [capability guides](/docs/endpoints) and command help for required options.\n\n Recover and finish\n\nbash\nonchain-router receipt \"$REQUEST_ID\"\nonchain-router status\nonchain-router lock\n\n\nKeep the same body, payment authorization, and key during allowed recovery. A lost response is not proof that no payment occurred. Unknown provider or settlement outcomes require human review. doctor --out creates a redacted, owner-only diagnostic file; review it before sharing."},{"title":"Production environment and funding","description":"Understand the Base mainnet payment environment and how to fund a wallet with USDC.","route":"/docs/environments","text":" Base mainnet\n\n- Network: eip155:8453\n- Payment asset: United States Dollar Coin (USDC) on Base, contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\n- Scheme: x402 v2 exact with EIP-3009\n- Capabilities: enabled Gemini text and image models plus the available ElevenLabs MP3 speech models in GET /v1/models\n- Recipient: 0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d\n\nAny wallet may pay after successful x402 verification. The service does not require registration or a pre-approved wallet list. We still recommend a dedicated wallet with the smallest practical balance and local limits for each request and each session. Check the payment recipient shown by the live endpoint before every signature.\n\n Funding and wallet safety\n\nFund the buyer wallet with only the USDC required for the next few requests. Ordinary public payments need no Base ETH or token approval. Validate the network, USDC contract, recipient, expiry, scheme, EIP-712 domain, and exact amount in every live HTTP 402 response before signing; another buyer or payment scheme may differ."},{"title":"Local MCP integration","description":"Nine focused tools for agents, with wallet setup and authority kept outside the model.","route":"/docs/mcp","text":"For a host-specific walkthrough, use [Claude Code with MCP](/docs/claude-code). For a complete terminal workflow, use [Create a narrated image](/docs/narrated-image).\n\n> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nUse MCP when your host supports a local stdio server. This is not a hosted ChatGPT connector or an HTTP MCP endpoint.\n\n What the agent can do\n\nNine tools cover discovery, Chat Completions, Messages, images, speech, transcriptions, voices, wallet status, and receipts. Wallet status is read-only; tools cannot import a wallet, unlock it, fund it, or increase a budget.\n\nThe human sets up and unlocks Buyer Runtime first. If policy requires a per-request human confirmation that the MCP channel cannot provide, a paid call fails closed.\n\n Install\n\nAfter human [CLI setup and unlock](/docs/cli), install the stable npm release and print its configuration:\n\nbash\nnpm install --global @onchainrouter/mcp@0.2.0\nonchain-router-mcp --print-config\n\n\nUse the generated absolute command and arguments in your host's local stdio configuration. Do not add wallet secrets to that configuration.\n\n Requests and limits\n\nChoose live models that the local policy allows. Each paid tool call needs a stable idempotency_key. Never change it just because a tool call timed out or was cancelled after financial handoff.\n\nTranscriptions accept at most 1,048,576 Base64 characters, about 768 KiB decoded MP3, and require explicit human permission for retained provider processing. Arbitrary URLs and file paths are not accepted. Use the CLI for larger uploads. See [speech-to-text guidance](/docs/transcription).\n\nReturn the output and verified receipt privately, with any media expiry. Treat all complete media and receipt capability URLs as secrets. See [agent contracts](/docs/agents) for outcomes and tool boundaries."},{"title":"Claude Code with MCP","description":"Add Onchain Router as a local Claude Code tool server, verify free discovery first, and keep payment authority in your local wallet policy.","route":"/docs/claude-code","text":"Use your existing Claude Code model to call Onchain Router tools for images, speech and text. This integration adds tools; it does not replace Claude Code's inference provider or give it a wallet key.\n\n Install the server\n\nComplete [CLI wallet setup](/docs/cli) first, then:\n\nbash\nnpm install --global @onchainrouter/mcp@0.2.0\nonchain-router-mcp --version\nclaude mcp add --transport stdio --scope user onchain-router -- onchain-router-mcp\nclaude mcp get onchain-router\n\n\nFor a non-default wallet profile, append --profile /absolute/path/to/profile after onchain-router-mcp. The profile path is configuration, not a secret. Never add a passphrase, wallet key or signer capability to MCP configuration. These commands follow the [official Claude Code local-server configuration](https://code.claude.com/docs/en/mcp).\n\n Verify without paying\n\nStart Claude Code, inspect /mcp, and ask:\n\ntext\nUse only onchain_router_models to list the available image and speech models and local limits. Do not make a paid call or change any wallet setting.\n\n\nSuccess means the real tool returns current discovery. A natural-language answer without a tool call is not a connectivity test.\n\n Allow a bounded task\n\nThe default per-call confirmation policy intentionally prevents unattended MCP payments. MCP is not a trusted wallet-confirmation channel. If you want agent-driven spending, make a separate deliberate decision in your own terminal: inspect the profile, restrict its models and session/hour/day limits, and then use onchain-router policy set --confirm-each false. This requires human authentication. Keep a dedicated low-balance wallet and unlock only for a short session. Do not ask Claude to perform these authority changes.\n\nThen ask for one specific output:\n\ntext\nGenerate one 1K square illustration of a yellow chicken in a garden using onchain_router_images and the enabled image model. Make exactly one paid tool call with a persistent idempotency key. Report the verified charge and expiry privately. If the outcome is uncertain, stop and inspect the same key; do not retry with another key or model.\n\n\nApprove the host tool permission separately. The host's permission does not override the wallet's monetary limits. At the end run onchain-router lock in your terminal.\n\n Boundaries and troubleshooting\n\n- This is local stdio MCP, not a remote ChatGPT connector.\n- Nine focused tools are available; they cannot unlock, fund or expand a wallet policy.\n- A locked wallet or per-call confirmation rejection is not a server outage.\n- Tool registration is not proof that every host/model combination has funded acceptance.\n- Native model-provider tool loops and streaming are separate from calling MCP media tools; do not infer their support from an image demo.\n- Media and receipt URLs are bearer capabilities. Keep them out of public chats and bug reports.\n\nSee the [tool contracts and upload limits](/docs/mcp), [wallet policy](/docs/wallet-security), and [narrated-image example](/docs/narrated-image)."},{"title":"Local OpenAI proxy","description":"Connect an OpenAI-compatible application to a payment-aware loopback adapter.","route":"/docs/proxy","text":"> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nThe proxy lets an existing application use a familiar OpenAI base URL while Buyer Runtime handles x402 locally. Merely pointing an ordinary SDK at the public HTTPS API does not add payments.\n\n Install\n\nAfter human [CLI setup and unlock](/docs/cli), install and inspect the stable npm release:\n\nbash\nnpm install --global @onchainrouter/proxy@0.2.0\nonchain-router-proxy --print-config\nonchain-router-proxy\n\n\nUse base URL http://127.0.0.1:8402/v1 and the contents of the generated owner-only proxy-token file as the local API key. The process reports the file path, not its secret contents. Do not expose the port, token, or broker to another user or a browser.\n\nThe proxy accepts only loopback requests with its local bearer. It has no arbitrary upstream target, wallet admin route, public listener, or browser CORS permission.\n\n Compatibility\n\nChat Completions supports the tested OpenAI-style non-streaming shape. Messages, images, speech, transcription, models, and pricing are also available through the allowlist.\n\nHosted speech returns JSON containing an MP3 capability URL, not the OpenAI SDK binary audio response. Transcription through the proxy uses Base64 JSON, not multipart. Check the capability guide before reusing a generic SDK method.\n\n Retries and caching\n\nDisable your application's automatic retries (maxRetries: 0 for the official OpenAI TypeScript client). Persist one explicit Idempotency-Key for requests that need durable recovery. Reuse it only for the identical request.\n\nAn explicit key bypasses the local response cache. Eligible text requests without one may reuse an identical answer within the same local session for up to ten minutes. A hit costs no new USDC and returns source-receipt metadata, not a new settlement. Read [caching](/docs/caching).\n\nUnknown provider or settlement outcomes return a non-retryable conflict and require human review. The proxy is not a way to bypass runtime limits."},{"title":"Make your first paid AI request","description":"Choose a text, image, or speech route, check its exact price, send one request on Base mainnet, and save the result and receipt.","route":"/docs/quickstart","text":"This guide uses an official x402 buyer and the Base mainnet payment contract. It spends USDC. Any wallet may pay after successful x402 verification, and no payer registration is required. If you are choosing one of our client tools, check [installation and availability](/docs/installation) first; six npm packages and Hermes are stable 0.2.0 releases, and OpenClaw is 0.2.1, while Python retains the source boundary documented there. The optional browser workflow and its build availability are described in [Workbench](/docs/workbench).\n\n Recommended client path\n\nThe package is public, but funded Buyer Runtime acceptance on a fresh external host remains\npending. Start with a dedicated low-balance API wallet and review every local policy limit.\n\nUse the Buyer CLI unless an existing application specifically needs the TypeScript SDK, MCP, local proxy, OpenClaw, Hermes, or direct x402 HTTP. Wallet creation/import, funding, unlock, and policy changes remain human-only terminal actions.\n\nbash\nnpm install --global @onchainrouter/cli@0.2.0\nonchain-router setup\nonchain-router funding\n\n\nPause here and fund the displayed wallet address with a small amount of Base USDC. Then run the\nfollowing in your private terminal. If you chose a custom Agent ID during setup, pass that same\nvalue to unlock --agent YOUR_AGENT_ID instead of using the default cli below.\n\nbash\nonchain-router balance\nonchain-router policy show\nonchain-router unlock --agent cli\nonchain-router models\nonchain-router pricing\nREQUEST_ID=\"$(node -p 'require(\"node:crypto\").randomUUID()')\"\nonchain-router chat \"Explain x402 in two sentences.\" \\\n --model gemini-3.6-flash \\\n --max-output-tokens 256 \\\n --idempotency-key \"$REQUEST_ID\"\nonchain-router lock\n\n\nPersist REQUEST_ID privately before the paid call. If the provider or settlement outcome is unknown, inspect onchain-router receipt \"$REQUEST_ID\"; do not generate a new key or automatically repeat the payment. See [task recipes](/docs/recipes) for Messages, images, speech, transcription, and direct no-spend inspection.\n\n 1. Prepare a dedicated wallet\n\nFor tighter wallet isolation, create a separate wallet account and fund it with only the small amount of Base mainnet USDC needed for the next few requests. The public exact flow uses EIP-3009: an ordinary request needs no Base ETH and no token approval. The service does not require a separate wallet, but we strongly recommend one.\n\nNever use a primary or highly funded wallet.\n\n 2. Choose what to call\n\nThe five paid routes are Chat Completions, Messages, Image Generations, Text to Speech, and Speech to Text. The Models, Pricing, Voices, and Balance routes are free. Read the [endpoint overview](/docs/endpoints), then use GET /v1/models to select a compatible model and GET /v1/pricing to inspect its current billing unit.\n\nGemini currently serves text and image generation. ElevenLabs Flash v2.5 serves MP3 text to speech, and Scribe v2 serves MP3 speech to text. The API contract remains provider-neutral as the catalog expands.\n\n 3. Use an official x402 buyer\n\nCall the official Hypertext Transfer Protocol Secure (HTTPS) address with an x402 buyer that supports the Base mainnet exact EIP-3009 payment scheme. Start with GET /v1/models, then send the request below to POST /v1/chat/completions. The first unpaid response has HTTP status 402. The buyer checks the payment terms, signs locally, and retries the identical request.\n\nCoinbase Developer Platform and Google Vertex credentials belong only on the server. A buyer never supplies, receives, or stores them. Stop immediately if any website or agent asks you for a Coinbase secret, Google credential, wallet seed phrase, or wallet private key.\n\n 4. Send production-shaped JSON\n\nChat Completions is a simple first request. Choose any compatible text model from GET /v1/models; the same payment lifecycle also protects the image and speech routes.\n\njson\n{\n \"model\": \"gemini-3.6-flash\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Explain in two short sentences why the sky appears blue.\"\n }\n ],\n \"max_tokens\": 1024,\n \"stream\": false\n}\n\n\nPreview the payment in your buyer. Confirm that the request uses Base mainnet (eip155:8453), official Base USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), recipient 0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d, the exact payment scheme, and an amount no higher than your local spending limit. For text, choose a realistic max_tokens value because it affects the fixed price.\n\n 5. Authorize and read the result\n\nConfirm the request-specific USDC authorization. The signature permits only the advertised exact transfer and never requires you to reveal your private key.\n\nRead the visible answer from:\n\ntext\nchoices[0].message.content\n\n\nThen record the receipt ID, exact amount, normalized usage, and BaseScan transaction. Do not publish the prompt, completion, receipt access token, or payment payload.\n\n Common results\n\n- A finish_reason value of \"stop\" means the answer completed normally.\n- A finish_reason value of \"length\" means the model reached the output limit. An intentionally longer answer is a new request: choose a new key and authorize again. Never change the body under the original key.\n- HTTP status 402 is the expected response before payment authorization.\n- An empty_provider_response error is not charged. The model used the available output budget without returning visible text.\n- If the provider or payment result is unknown, recover the existing request before starting a new one."},{"title":"Portable Agent Skill","description":"Reusable agent guidance over the local Buyer CLI, without a second signer.","route":"/docs/agent-skill","text":"> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nThe [Onchain Router Skill](/skill/onchain-router/SKILL.md) is public MIT source in [OnchainRouter/onchain-router](https://github.com/OnchainRouter/onchain-router). It contains instructions and thin CLI bridge scripts and requires the matching stable Buyer CLI. Downloading the instructions alone does not provide a payment runtime.\n\n How to use it\n\nUse a host that supports portable Agent Skills and local commands. Read [agent entry points](/docs/agents) first. Have the human complete CLI setup and unlock in a direct terminal, then give the agent only the approved profile and installed executable location.\n\nThe skill discovers current models, reads wallet status, sends bounded requests, classifies outcomes, and retrieves receipts. It never implements payment cryptography or accepts a seed phrase, key, passphrase, or broker capability.\n\n Safe request flow\n\nRead discovery; choose a model allowed by policy; persist one request key; call the CLI-backed helper; follow the retry directive. Prompts and media JSON travel on stdin, not the command line or environment.\n\nInline media JSON is limited to 1,000,000 bytes. Use the human CLI upload path for larger MP3s. Transcription requires explicit permission for provider-retained audio and transcript processing.\n\nKeep the receipt ID and exact media expiry with the private result. Do not publish capability URLs. The skill does not install itself, unlock a wallet, or widen a budget."},{"title":"OpenClaw integration","description":"Use Onchain Router as an OpenClaw model provider with policy-filtered models, bounded media tools, and local payment authority.","route":"/docs/openclaw","text":"The [Onchain Router OpenClaw extension](https://github.com/OnchainRouter/onchain-router-openclaw) 0.2.1 is a stable MIT release with an immutable [GitHub release](https://github.com/OnchainRouter/onchain-router-openclaw/releases/tag/v0.2.1). It is directly installable through OpenClaw's native Git plugin path. It is not yet a ClawHub listing, and funded host acceptance remains a separate operator check.\n\n What it adds\n\n- a native onchain-router provider with live policy-filtered chat models;\n- read-only tools for models, pricing, and voices;\n- bounded paid tools for images, MP3 speech, and MP3 transcription;\n- an authenticated /onchain-router command for redacted status, diagnostics, and recovery guidance;\n- one deterministic Buyer Runtime idempotency key across host retries of the same transport turn;\n- optional lifecycle management for the exact installed @onchainrouter/proxy@0.2.0 dependency.\n\nIt does not create, import, inspect, unlock, fund, or back up a wallet. It does not implement x402, choose a paid fallback, download packages at runtime, or connect OpenClaw directly to the public payment service.\n\n Requirements and install\n\n- Node.js >=24.15.0 <25;\n- OpenClaw 2026.8.1;\n- macOS or Linux;\n- a Buyer Runtime profile created and unlocked by a human;\n- the exact proxy version declared by the extension.\n\nbash\nopenclaw plugins install git:github.com/OnchainRouter/onchain-router-openclaw@v0.2.1 --force\nopenclaw plugins enable onchain-router --accept-capabilities\nopenclaw plugins inspect onchain-router --runtime --json\n\n\n--force acknowledges the external GitHub source; it does not bypass host policy or capability consent. The version tag prevents a later branch update from silently replacing the reviewed release. Review the declared local-file and process capabilities, then choose an onchain-router/ returned by the live picker.\n\n First-session acceptance checklist\n\n1. Complete the public repository's setup and verify the loopback proxy is running before selecting the provider.\n2. Ask the host to call the free model/pricing tools. Confirm it actually used a tool and returned the policy-filtered catalog.\n3. For an initial bounded media task, request one square image with one saved idempotency key. The host permission and human-configured wallet spending policy must both allow it.\n4. Inspect the verified receipt and image expiry privately, then lock the wallet. Do not count native installation as a paid-call success.\n\nIf you prefer a directly testable terminal example first, use [Create a narrated image](/docs/narrated-image). Streaming and native tool-loop acceptance are separate from the media tools; a successful basic response does not establish them.\n\n Local trust boundary\n\nThe extension connects only to the authenticated proxy on exact loopback http://127.0.0.1:8402. Its bearer must be a regular owner-only file at mode 0600. Never expose the proxy through a tunnel, reverse proxy, LAN bind, or container host port.\n\nNative chat retries preserve the same financial identity for one transport turn. Do not configure model fallbacks for this provider: an ambiguous paid result requires receipt inspection and deliberate same-key recovery, not a new request or model.\n\nThe release workflow builds and tests the adapter, runs OpenClaw archive and native-Git lifecycle qualification, and publishes the packed artifact. The complete setup, build, tool, configuration, and troubleshooting instructions are in the [public repository](https://github.com/OnchainRouter/onchain-router-openclaw). A funded OpenClaw request remains an explicit operator acceptance step because it spends from the operator's Buyer Runtime wallet."},{"title":"Hermes Agent integration","description":"Use Onchain Router as a Hermes model provider with media tools, diagnostics, and deliberate recovery over the local Buyer Runtime.","route":"/docs/hermes","text":"The [Onchain Router Hermes plugin](https://github.com/OnchainRouter/onchain-router-hermes) 0.2.0 is a stable MIT release with an immutable [GitHub release](https://github.com/OnchainRouter/onchain-router-hermes/releases/tag/v0.2.0). It is directly installable through Hermes' native GitHub plugin path. It is not a PyPI release, and PyPI is not required for the native installation; funded host acceptance remains a separate operator check.\n\n What it adds\n\n- native provider onchain-router for chat with one explicit live model;\n- free discovery tools and commands for models, prices, and voices;\n- bounded paid tools for images, MP3 speech, and MP3 transcription;\n- redacted status and diagnostics commands;\n- explicit recovery guidance and stable idempotency across host retries;\n- human-run setup, update, status, stop, and client-removal commands.\n\nThe plugin connects only to the authenticated Buyer Runtime proxy on 127.0.0.1. Wallet and payment authority remain outside Hermes. The plugin does not create, import, inspect, unlock, fund, or back up a wallet; implement x402; download during a model call; choose a fallback; or blindly retry a paid request.\n\n Requirements and install\n\n- Python >=3.11,<3.14;\n- Hermes Agent 0.21.0;\n- Node.js 20.18 or newer and npm;\n- macOS or Linux;\n- a Buyer Runtime profile created and unlocked by a human.\n\nbash\nhermes plugins install OnchainRouter/onchain-router-hermes --enable\nhermes plugins doctor onchain-router --ci\nhermes onchain-router setup\n\n\nHermes records the installed Git commit. For a reproducible install, append --ref cec74e695fdbcad7212a9d97dc5132b9d3a7ff80 to the first command. The release page also provides the wheel and source distribution for inspection. Repository qualification checks provider/plugin discovery against Hermes 0.21.0, build/install/update/uninstall behavior, and makes no paid request.\n\n First-session acceptance checklist\n\n1. Run the plugin setup and doctor commands, then verify the authenticated local proxy is running.\n2. Use the plugin's free model/pricing tools before any paid request. Choose an explicitly enabled model, not an automatic fallback.\n3. Request one short MP3 narration with a saved idempotency key. Both host permission and the human-owned wallet policy must allow that call.\n4. Confirm the receipt, exact USDC charge, and 24-hour hosted URL expiry. Download privately and lock the wallet afterward.\n\nUse [Create a narrated image](/docs/narrated-image) for a terminal-based baseline. A passing plugin doctor is installation evidence, not a funded completion or proof of every native agent loop.\n\n Local trust boundary\n\nThe plugin uses exact pinned versions of the Onchain Router CLI and proxy and keeps the non-wallet proxy bearer in an owner-only local file. Never expose the proxy outside loopback or put its bearer in a prompt, log, screenshot, or source file.\n\nThe current stable release pins both @onchainrouter/cli@0.2.0 and @onchainrouter/proxy@0.2.0.\n\nNative chat retries reuse one deterministic idempotency key for the same logical call. Media tools require a caller-supplied stable key. A timeout, disconnect, ambiguous 409, provider-unknown, settlement-unknown, or receipt-verification failure is not permission for a fresh request.\n\nThe complete setup lifecycle, media examples, retention disclosure, tool list, and troubleshooting are in the [public repository](https://github.com/OnchainRouter/onchain-router-hermes). A funded Hermes request remains an explicit operator acceptance step because it spends from the operator's Buyer Runtime wallet."},{"title":"Direct x402 API","description":"Use the public HTTPS API with an official Base USDC payment-aware buyer.","route":"/docs/direct-api","text":"The public origin is https://onchainrouter.dev. No payer registration is needed. The client must support the live Base USDC exact EIP-3009 flow; an ordinary OpenAI API key or transport alone is not sufficient.\n\n Discover first\n\nbash\ncurl https://onchainrouter.dev/v1/models\ncurl https://onchainrouter.dev/v1/pricing\ncurl https://onchainrouter.dev/openapi.json\n\n\nThese GET requests do not sign or spend USDC. Use [voices](/v1/audio/voices) before speech generation. [Balance](/docs/api/balance) is a public address query, not wallet authentication.\n\n Request, authorize, recover\n\n1. Select a live model and save one stable idempotency key.\n2. Send the exact request without payment to receive HTTP 402.\n3. Validate network, official USDC asset, expected recipient, scheme, expiry, and exact amount against your local policy.\n4. Use official x402 verification/signing primitives to authorize locally. Retry the identical effective body and key.\n5. Save the result and verified receipt. A transport error after signing may require recovery, not a new payment.\n\nSee [complete examples](/docs/sdk-examples) for an unpaid challenge and [first request](/docs/quickstart) for the payment checklist. The website never needs a private key.\n\n Payment and support surfaces\n\nFive paid AI routes share the payment lifecycle; four free discovery routes help you select inputs. Supporting quote, receipt, x402 discovery, and health routes still serve integration and operations but are not extra paid products.\n\nThe internal quote preview does not run a model or pay. The buyer can obtain payment terms directly from the initial 402 response. A receipt lookup requires its appropriate access capability and is not a public browsing endpoint.\n\nFor exact fields and status codes, use [OpenAPI](/openapi.json) and [endpoint reference](/docs/endpoints)."},{"title":"Protect the wallet that pays for requests","description":"Use a dedicated wallet with a small balance, set firm spending limits, and check every payment term before signing.","route":"/docs/wallet-security","text":"Your wallet signs the payment authorization on your device. Onchain Router receives the authorization but never receives your seed phrase or wallet private key.\n\n Local Buyer Runtime setup\n\n> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\nAfter [installing the CLI](/docs/installation), run setup in your own direct terminal. You may pass all non-secret model, agent, and integer-USDC policy choices in one command; wallet import and passphrases remain private no-echo prompts. Never put passphrases or keys in an argument, environment value, agent prompt, standard input, or HTTP request.\n\nUse the CLI's funding instructions to verify the wallet address and Base network before sending USDC. Check balance, then unlock for a bounded session. The SDK, local MCP, proxy, and Skill reuse that profile; the agent cannot widen its policy. Lock when finished. A policy increase requires human authentication and locks the existing broker first.\n\nThe optional [browser Workbench](/docs/workbench) uses an injected wallet instead. Connecting a browser wallet does not unlock the local runtime. Its encrypted same-tab recovery record can survive a reload for up to one hour, but it is separate from the CLI ledger; closing the tab loses the browser recovery key.\n\n Safe mainnet wallet policy\n\n- Create a new account used only for Onchain Router.\n- Hold only the USDC needed for the next few requests; ordinary exact payments need no Base ETH\n gas.\n- For an old upto profile, migrate with onchain-router policy set --scheme exact. Legacy\n Permit2 commands remain available only for explicit compatibility and limit any allowance to\n the reviewed daily policy.\n- Set a hard limit for each request in atomic USDC units. 1000000 means 1.000000 USDC;\n choose your own appropriate limit. The live server may enforce a lower limit independently.\n- Set a separate session cap for autonomous use.\n- Allow only Base mainnet (eip155:8453), official Base USDC, and the expected recipient.\n- No operator registration is required. The server applies a per-request maximum and a global estimated-loss breaker. These server controls protect the service; they do not replace your local wallet limits.\n- Disconnect or revoke site access when testing is complete.\n\n Before every signature\n\nRead the scheme, network, asset, payTo, amount, EIP-712 domain, and expiry fields from the live Hypertext Transfer Protocol (HTTP) 402 response. Reject the payment if the request body changed, the recipient is unexpected, the network is not Base mainnet, the asset is not official Base USDC, the quote expired, or the exact amount exceeds your local limit.\n\nDo not infer payment terms from this page. Runtime terms and the current public catalog are authoritative.\n\n Switching wallet accounts\n\nIn the repository's optional local acceptance UI, use Change buyer, select the new account in the wallet, and verify the complete address. The UI clears the old quote when the exposed account changes. Other x402 buyers must provide an equivalent account-change and quote-invalidation safeguard. Always preview again after switching."},{"title":"Browser Workbench","description":"Try the request flow with a browser wallet and inspect output, charges, receipts, and expiry.","route":"/docs/workbench","text":"[Open Workbench](/workbench/). This build includes the browser UI. A read-only local preview cannot submit paid requests; use only an explicitly enabled deployment for payments.\n\n What it covers\n\nThe Workbench has five paid request choices: Chat Completions, Messages, image generation, text to speech, and speech to text. It also supports free models, pricing, voices, and wallet balance discovery.\n\nChoose the capability and a compatible model, review or edit the request, preview the payment, then approve in your injected browser wallet only when you intend to spend USDC. Network and model options come from the service contract.\n\n Wallet boundary\n\nThe browser uses your injected wallet. It does not import a seed phrase or share the local CLI wallet. Browser wallet approval is not the same as unlocking Buyer Runtime.\n\nRead-only development previews reject paid requests. Connecting a wallet does not make a read-only preview a payment environment.\n\n Results and recovery\n\nInspect the actual charge, receipt, transaction, and output. Download images before the seven-day URL expiry and speech audio before its 24-hour expiry. Keep the exact returned timestamp.\n\nBefore a signed request is sent, the browser saves one encrypted recovery copy for up to one hour. The ciphertext is stored in browser IndexedDB and its encryption key remains in same-tab session storage. Reloading the same tab restores the exact request, payment header, and request key without opening the wallet again. Verified completion or an authoritative failure without settlement clears it.\n\nClosing the tab discards the browser key, and corrupt, missing, or expired recovery data keeps new payments blocked for operator review. It is not evidence that the request failed. The durable server receipt and PostgreSQL payment state remain authoritative.\n\nHTTP 402 is normal before authorization. After signing, never assume a timeout or 503 means nothing happened. Follow [errors and recovery](/docs/errors-retries), and do not preview a new payment to recover an ambiguous one.\n\nThe recovery action always reuses the original signed payload, request body, and key. A settled recovery verifies the durable receipt and standard payment response before showing the result. A still-pending or uncertain reply keeps the attempt locked and shows only a safe HTTP state and trace reference. Only an authoritative operation_failed_without_settlement reply releases the attempt for a fresh preview. Use the canonical same-origin /workbench/ page for real payments; the localhost proxy remains a development tool.\n\nThe hosted page sends its signed follow-up through a bounded same-origin Workbench relay so browser\ncustom-header transport cannot drop the authorization. The relay reconstructs the unchanged\nstandard x402 request only on the private API hop and does not persist or log the signature. Direct\nAPI clients still use the official PAYMENT-SIGNATURE header."},{"title":"Choose an agent entry point","description":"Select npm clients, OpenClaw, Hermes, or the portable skill without widening wallet authority.","route":"/docs/agents","text":"\n\n> Stable distribution: six Onchain Router client packages are available on npm at version 0.2.0 under the @onchainrouter scope. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts' native GitHub paths. They are not claimed as ClawHub or PyPI listings, and funded host acceptance remains unverified. Review /docs/installation and /products.json before installation. Publication never grants permission to create, import, fund, or unlock a wallet.\n\n Choose one primary path\n\n| Use | Choose it when | Current capability categories | Authority boundary |\n| ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| Focused MCP | The agent host supports local stdio MCP and should receive narrow native tools. | text_generation, image_generation, text_to_speech, speech_to_text | Nine bounded tools; every payment uses the shared Buyer Runtime. |\n| Loopback proxy | An OpenAI-compatible client can set a local base URL and API key but cannot perform x402. | text_generation, image_generation, text_to_speech, speech_to_text | Authenticated loopback, five non-streaming paid JSON routes; speech returns hosted JSON, not binary audio. |\n| TypeScript or Python SDK | Application code needs typed discovery, all paid JSON endpoints, recovery, and receipts. | text_generation, image_generation, text_to_speech, speech_to_text | Calls an already-unlocked Buyer Runtime and has no wallet-secret constructor. |\n| Buyer CLI | A human is setting up, unlocking, funding, changing policy, diagnosing, or running shell automation. | text_generation, image_generation, text_to_speech, speech_to_text | Human wallet authority plus bounded JSON media and explicit owned-file MP3 upload. |\n| Portable Agent Skill | The agent host supports portable skills and can invoke an installed local Buyer CLI. | text_generation, image_generation, text_to_speech, speech_to_text | Thin CLI-only workflows; no independent wallet or payment implementation. |\n| OpenClaw extension | The agent runs in OpenClaw and should use a native provider plus bounded media tools. | text_generation, image_generation, text_to_speech, speech_to_text | Native host adapter over the authenticated local proxy; no wallet admin or second signer. |\n| Hermes Agent plugin | The agent runs in Hermes and needs a native provider, media tools, and recovery commands. | text_generation, image_generation, text_to_speech, speech_to_text | Native host adapter over the authenticated local proxy; no wallet admin or automatic paid retry. |\n\nAll seven local entry points cover the four current capability categories through direct methods, host providers, or bounded tools. Media uses live model/option validation and the same durable buyer lifecycle. MCP provides nine narrow tools: discovery, chat, messages, images, speech, transcriptions, voices, wallet status, and receipt lookup. MCP limits MP3 Base64 to 1,048,576 characters; portable skill JSON is bounded to 1,000,000 bytes. CLI/SDK/proxy accept at most 25 MiB decoded MP3. The CLI explicit-file path rejects symlinks, special files, non-owned files, and changed files. Speech-to-text requires human permission for provider-retained audio/transcript processing and local acknowledge_provider_retention: true; the SDK removes that flag before sending the API request. Images default to hosted URLs. The proxy returns hosted speech JSON, not OpenAI binary audio, and does not yet support multipart transcription. Do not claim those transport forms work.\n\n One shared contract\n\n- Canonical origin: https://onchainrouter.dev.\n- Network: Base mainnet eip155:8453.\n- Asset: official Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.\n- Models and prices: always read /v1/models and /v1/pricing; never copy a price or assume an alias remains enabled.\n- Paid endpoints: /v1/chat/completions, /v1/messages, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions.\n- Example text model at generation time: gemini-3.6-flash. Confirm it against live discovery before a call.\n- Idempotency: create one stable key before the unpaid request and retain it through signing, recovery, and receipt lookup.\n- Inspection: empty, incomplete, or malformed unsigned JSON returns a discovery-only 402. Do not sign an inspection challenge; submit a valid body to obtain the request-specific exact price first.\n- Success: return ok, outcome, idempotencyKey, body, receipt, payment.\n- Failure: return ok, outcome, retry, idempotencyKey, message, reference without secret-bearing diagnostics.\n\nEvery adapter delegates wallet custody, integer-atomic budgets, official x402 payment, ambiguity, recovery, and receipt verification to Buyer Runtime. None may contain a second signer or payment implementation.\n\nThe private loopback proxy additionally reuses eligible identical text answers within one wallet/agent/session/policy/catalog for up to ten minutes in bounded memory. Explicit idempotency keys bypass this cache and retain the durable recovery path; keep using them when recovery is required. A cache hit is the proxy-only outcome CachedResponse, with x-onchain-router-cache: HIT, x-onchain-router-charge-atomic: 0, the original source idempotency key, and x-onchain-router-source-receipt-id. It is not a new Buyer Runtime success, receipt, or settlement; body usage refers to the original inference. Ordinary payment/receipt headers are omitted on hits. Use Cache-Control: no-cache to refresh, Cache-Control: no-store or JSON cache: false / no_cache: true to bypass, or proxy --no-cache to disable. Tools/media are excluded. Direct SDK/CLI/MCP/public API and provider cached-token pricing are unchanged.\n\n Human-owned setup\n\nThe following actions are human-only and must run in a direct terminal:\n\n- wallet create or import\n- wallet unlock\n- funding\n- legacy Permit2 profile migration\n- policy widening\n- confirmation-policy changes\n- backup or restore\n- key rotation\n- wallet export or exit\n\nDo not send a wallet key, seed phrase, passphrase, broker capability, payment payload, or receipt capability through an agent tool, prompt, environment value, or HTTP request.\n\nInstalled-client and public-source entry points are:\n\n| Entry point | Artifact | Inspect or start |\n| ------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| Focused MCP | @onchainrouter/mcp | onchain-router-mcp --print-config |\n| Loopback proxy | @onchainrouter/proxy | onchain-router-proxy --print-config |\n| TypeScript or Python SDK | @onchainrouter/client or onchain-router | OnchainRouterBuyer.connect() or OnchainRouterBuyer() |\n| Buyer CLI | @onchainrouter/cli | onchain-router help |\n| Portable Agent Skill | skills/onchain-router | node scripts/models.mjs |\n| OpenClaw extension | OnchainRouter/onchain-router-openclaw | openclaw plugins install git:github.com/OnchainRouter/onchain-router-openclaw@v0.2.1 --force |\n| Hermes Agent plugin | OnchainRouter/onchain-router-hermes | hermes plugins install OnchainRouter/onchain-router-hermes --enable |\n\nInstall npm packages only from the @onchainrouter scope at exact version 0.2.0. Install OpenClaw and Hermes only from the exact OnchainRouter GitHub repositories and release references shown above. Host-native Git installability is independent of ClawHub or PyPI listing status.\n\n Stable outcomes\n\n| Outcome | Retry directive |\n| ------------------------------- | ---------------------------- |\n| PaymentPolicyRejected | do_not_retry |\n| UnsupportedNetwork | do_not_retry |\n| UnexpectedAsset | do_not_retry |\n| UnexpectedRecipient | do_not_retry |\n| AuthorizationAboveLocalCap | do_not_retry |\n| InsufficientFunds | retry_unpaid_request |\n| Permit2ApprovalRequired | do_not_retry |\n| Permit2ApprovalOutcomeUnknown | human_review |\n| PaymentVerificationRejected | retry_unpaid_request |\n| ProviderOutcomeUnknown | human_review |\n| SettlementOutcomeUnknown | human_review |\n| IdempotencyConflict | do_not_retry |\n| ResultRecoveryExpired | do_not_retry |\n| ReceiptVerificationFailed | retry_same_idempotency_key |\n| WalletLocked | unlock_wallet |\n| RuntimeUnavailable | retry_same_idempotency_key |\n\nProviderOutcomeUnknown and SettlementOutcomeUnknown always require human review. A retry_same_idempotency_key directive means identical request and identical key; it never authorizes a fresh logical request. WalletLocked requires a direct human unlock.\n\n Receipt and output\n\nReturn the requested content, selected model, normalized usage, signed exact atomic USDC amount, Base network, transaction, and verified receipt. Hosted media URLs are bearer capabilities: disclose their expiry but avoid logs or public messages containing the complete URL. A receipt proves Onchain Router's settlement and attested usage; it is not an upstream-provider attestation.\n\n Public API discovery\n\nRead /llms.txt, then /v1/models, /v1/pricing, and /openapi.json. Use /v1/audio/voices before text to speech and /v1/balance?address=0x... for a free Base USDC balance check. The public API accepts direct official x402 buyers whether or not a Release B local adapter is installed.\n\nThe portable skill source is available at /skill/onchain-router/SKILL.md and requires the stable Buyer CLI. The llms.txt convention and Agent Skills are discovery and workflow mechanisms, not access-control or wallet-authority systems."},{"title":"TypeScript, CLI, MCP & HTTP examples","description":"Stable client examples over Buyer Runtime, plus a public unpaid HTTP challenge.","route":"/docs/sdk-examples","text":"> Six Onchain Router client packages version 0.2.0 are public, MIT-licensed stable releases on npm. OpenClaw 0.2.1 and Hermes 0.2.0 are stable MIT releases installable through their hosts’ native GitHub paths. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the @onchainrouter scope, exact version, and repository before installation.\n\n Before you run a client example\n\nFollow [installation](/docs/installation), then complete [human CLI setup and unlock](/docs/cli). Choose a dedicated funded wallet and a policy that allows the model. Paid SDK and CLI calls spend USDC; the HTTP example below only inspects the unpaid challenge.\n\nThe TypeScript SDK, CLI, and MCP server are public npm 0.2.0 stable releases. The Python SDK remains a source-only bounded subprocess bridge to the matching CLI; it has no independent wallet or signer.\n\nFor a task-first request and response guide, including images and both speech directions, use [Agent task recipes](/docs/recipes). For third-party wallet and discovery status, use [Wallet and agent compatibility](/docs/wallet-compatibility).\n\nSet REQUEST_ID to a stable application job identifier before a paid example. Save it privately with the exact body. Do not create a different key because the original call timed out.\n\n TypeScript\n\nPublic npm stable 0.2.0 · requires human setup and an unlocked Buyer Runtime.\n\nts\nnpm install @onchainrouter/client@0.2.0\n\nimport { OnchainRouterBuyer } from '@onchainrouter/client';\n\nconst requestKey = process.env.REQUEST_ID;\nif (!requestKey) throw new Error('Set a persisted REQUEST_ID');\nconst buyer = await OnchainRouterBuyer.connect();\ntry {\n const result = await buyer.chat({\n \"model\": \"gemini-3.6-flash\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Explain x402 in one sentence.\"\n }\n ],\n \"max_tokens\": 128,\n \"stream\": false\n }, requestKey);\n if (!result.ok) throw new Error(${result.outcome}: ${result.message});\n console.log(result.body);\n console.log(result.receipt.id, result.payment.actualAtomic);\n} finally {\n buyer.close();\n}\n\n\n CLI\n\nPublic npm stable 0.2.0 · setup, unlock, and policy changes stay human-only.\n\nbash\nnpm install --global @onchainrouter/cli@0.2.0\nonchain-router setup\nonchain-router policy show\nonchain-router unlock\nonchain-router models\n\n\n MCP\n\nPublic npm stable 0.2.0 · prints a local stdio configuration without exposing wallet secrets.\n\nbash\nnpm install --global @onchainrouter/mcp@0.2.0\nonchain-router-mcp --print-config\n\n\n HTTP\n\nPublic API · this plain request inspects the unpaid challenge and does not sign or spend USDC.\n\nbash\nrequest_key=\"$(node -p 'require(\"node:crypto\").randomUUID()')\"\ncurl -i https://onchainrouter.dev/v1/chat/completions \\\n -H 'content-type: application/json' \\\n -H \"x-idempotency-key: $request_key\" \\\n --data '{\"model\":\"gemini-3.6-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain x402 in one sentence.\"}],\"max_tokens\":128,\"stream\":false}'\n\n\n Read the result and recover\n\nTypeScript returns a discriminated result: ok, outcome, idempotencyKey, and either a result body, payment and verified receipt, or a safe retry directive.\n\nProviderOutcomeUnknown and SettlementOutcomeUnknown need human review. A retry directive permitting the same key requires the identical request. Do not wrap paid calls in a general-purpose retry loop.\n\nThe examples display result bodies in your private terminal or application. Those bodies may contain completions, transcripts, or hosted media capability URLs. Do not forward them to public logs or diagnostics, and never log signatures or receipt access tokens.\n\n Other capabilities\n\nThe same buyer exposes messages, images, speech, and transcriptions. Use each capability's documented request shape.\n\n- [Text formats](/docs/text): OpenAI Chat Completions or Anthropic Messages.\n- [Images](/docs/images): hosted URL or Base64 delivery; hosted URL expires after seven days.\n- [Speech](/docs/speech): hosted MP3 JSON, not an OpenAI binary audio response.\n- [Transcription](/docs/transcription): bounded MP3 and explicit retained-provider consent.\n\nDo not implement EIP-712, Permit2, payment signing, or settlement in application code. Buyer Runtime uses official x402 primitives."},{"title":"Agent task recipes","description":"Copy complete request shapes for text, images, and speech, then recover the same paid operation safely.","route":"/docs/recipes","text":"For a complete runnable workflow rather than individual request bodies, start with [Create a narrated image](/docs/narrated-image): two bounded paid calls, local downloads, verified receipts, and saved request identities.\n\nThese recipes use the live catalog and one shared payment lifecycle. First read GET /v1/models and GET /v1/pricing. Then create and persist one idempotency key, send a valid unsigned request, validate the request-specific HTTP 402 challenge, sign locally through an official x402 exact buyer, and retry the identical request. A successful response is released only after its result, settlement, and receipt are durable.\n\nAn empty, incomplete, or malformed unsigned JSON request returns a discovery-only inspection challenge. It has X-Onchain-Router-Challenge-Kind: inspection and price.type: inspection. Do not sign it. Submit one of the valid bodies below to receive the request-specific exact price first.\n\n Answer a question with Chat Completions\n\nUse POST /v1/chat/completions when an application already uses OpenAI-shaped messages and choices.\n\njson\n{\n \"model\": \"gemini-3.6-flash\",\n \"messages\": [{ \"role\": \"user\", \"content\": \"Explain x402 in two short sentences.\" }],\n \"max_tokens\": 256,\n \"stream\": false\n}\n\n\nRead the answer from choices[0].message.content. Pricing uses a conservative input estimate plus 10% of requested output and the published fixed/minimum policy. Set a realistic max_tokens. If the provider or settlement outcome is unknown, recover with the same body and idempotency key. Never create a second paid job automatically.\n\n Use the Anthropic Messages shape\n\nUse POST /v1/messages when the caller already expects Anthropic-shaped content blocks. This is a compatibility format, not a claim that the selected provider is Anthropic.\n\njson\n{\n \"model\": \"gemini-3.6-flash\",\n \"system\": \"Answer concisely.\",\n \"messages\": [{ \"role\": \"user\", \"content\": \"Explain x402 in two short sentences.\" }],\n \"max_tokens\": 256,\n \"stream\": false\n}\n\n\nRead text blocks from content. The payment and recovery rules are identical to Chat Completions.\n\n Generate one image\n\nUse POST /v1/images/generations. Select a model whose category is image_generation; supported sizes and aspect ratios are model-specific.\n\njson\n{\n \"model\": \"gemini-3.1-flash-lite-image\",\n \"prompt\": \"A geometric blue bridge on a white background\",\n \"n\": 1,\n \"image_size\": \"1K\",\n \"aspect_ratio\": \"1:1\",\n \"response_format\": \"url\"\n}\n\n\nThe response contains one hosted URL by default, its expiry, and the settled price. Hosted image URLs are bearer capabilities and expire after seven days. Download the image before expiry without putting the complete URL in logs. Image pricing varies by selected model and image size; refresh /v1/pricing before a request.\n\n Generate speech\n\nUse POST /v1/audio/speech. Select a text_to_speech model and a public voice alias from GET /v1/audio/voices.\n\njson\n{\n \"model\": \"elevenlabs/flash-v2.5\",\n \"input\": \"Hello from Onchain Router.\",\n \"response_format\": \"mp3\",\n \"speed\": 1\n}\n\n\nThis example omits voice to use the model's current default; to choose another, supply an alias returned by GET /v1/audio/voices. The response is JSON with a hosted MP3 capability URL, not an OpenAI binary-audio response. The URL expires after 24 hours. Billing uses the normalized input character count and the published model rate.\n\n Transcribe speech\n\nUse POST /v1/audio/transcriptions with canonical Base64 JSON or multipart form data. For an agent-safe JSON call:\n\njson\n{\n \"model\": \"elevenlabs/scribe-v2\",\n \"audio_base64\": \"BASE64_MP3_WITHOUT_A_DATA_URL_PREFIX\",\n \"file_format\": \"other\",\n \"response_format\": \"json\"\n}\n\n\nThe server validates the audio locally before payment verification and bills by measured duration. The CLI/SDK requires explicit human acknowledgement of provider retention before sending audio. Onchain Router deletes its staging copy after a definite outcome; the provider may retain audio and transcripts independently. Never upload sensitive or third-party audio without permission.\n\n Change models safely\n\nDo not guess aliases or reuse a model copied from an old example. Read GET /v1/models, select a model from the required category, confirm its supported endpoint and options, and ensure the human-owned Buyer Runtime policy permits it. Changing the model changes the effective request: create a new idempotency key and obtain a new 402 challenge.\n\n Inspect without spending\n\nThis command sends no signature and cannot settle USDC:\n\nbash\ncurl -i https://onchainrouter.dev/v1/chat/completions \\\n -H 'content-type: application/json' \\\n --data '{}'\n\n\nExpect HTTP 402, PAYMENT-REQUIRED, and the inspection marker. For the full five-route compatibility matrix, run the repository validator against a local or explicitly selected origin:\n\nbash\nGITHUB_SHA=\"$(git rev-parse HEAD)\" pnpm agent:discovery-check \\\n --origin https://onchainrouter.dev \\\n --profile production\n\n\nThe validator never creates or sends a payment signature. It derives the checked-out commit and,\nwhen GITHUB_SHA is set, requires it to match that exact HEAD, so the report stays bound to\nreviewed source. A green result does not prove a paid settlement, provider response, wallet\nintegration, or external marketplace indexing.\n\n Recover and verify\n\nOn success, retain the original idempotency key, response, X-Receipt-ID, actual atomic USDC charge, transaction, and verified receipt in private application state. On an ambiguous outcome, use the Buyer Runtime receipt/recovery method with the same key. Do not blindly retry, change the request, or expose the receipt capability."},{"title":"Wallet and agent compatibility","description":"Understand which x402 buyers fit the current Base exact contract and which integrations still need external proof.","route":"/docs/wallet-compatibility","text":"Onchain Router's five paid resources use official x402 v2, Base mainnet USDC, the EVM exact scheme, EIP-3009 authorization, request-specific fixed prices, stable idempotency keys, and durable receipts with normalized usage. Compatibility depends on that complete contract—not merely on a wallet being able to hold USDC.\n\n Current matrix\n\n| Buyer or discovery surface | Current status | What is still required |\n| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Onchain Router Buyer Runtime, CLI, TypeScript SDK, MCP, and proxy | Public npm stable 0.2.0. Implements the complete current contract with local budgets, official x402 signing, recovery, and receipt verification. | Founder-operated funded acceptance remains separate from install and no-spend tests. |\n| Any official x402 v2 EVM buyer with exact and EIP-3009 | Protocol-compatible in principle. No payer allowlist is used. | Validate network, asset, recipient, amount, expiry, identical retry behavior, and ambiguous-outcome recovery in that buyer. |\n| [AgentCash](https://agentcash.dev/discovery) | Its public discovery client resolves the canonical OpenAPI document and all nine advertised routes. Paid wallet compatibility is not yet claimed. | Complete one explicitly approved paid call with receipt/recovery verification. |\n| [x402scan](https://www.x402scan.com/resources/register) | The legacy hostname has a listing. Verify that the server page being viewed lists onchainrouter.dev; a legacy-domain record does not establish the new origin’s registration or transaction attribution. | Confirm the canonical server page and all nine resources. Complete ownership or registration only if still required; assess transaction attribution and search separately. |\n| Poncho | The prior hostname had a merchant record. The new onchainrouter.dev origin is not claimed until Poncho independently refreshes or creates its record. No paid invocation, receipt, or recovery result has been independently verified. | Create or refresh the listing with provider-neutral text, image, text-to-speech, and transcription metadata, then complete one explicitly approved call with receipt and recovery evidence. |\n| awal | Candidate Coinbase wallet integration; it is not evidence of marketplace indexing. | Use the official awal x402 pay flow once explicitly authorized and verify the identical request, exact amount, settlement, and receipt. |\n| [Coinbase Bazaar discovery](https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d) | Verified on 2026-09-04: the merchant record lists all five https://onchainrouter.dev paid routes with Onchain Router branding and capability tags. Indexing does not prove search rank or buyer compatibility. | Recheck each URL with Coinbase validation (valid: true, simulation.outcome: \"accepted\"), and verify search visibility and client acceptance separately. |\n| Circle or other compliant EVM exact buyers | Protocol-compatible in principle when they implement x402 v2 EIP-3009 on Base USDC. | Run that buyer's own no-spend validation and one explicitly approved paid acceptance test before naming it as verified. |\n| pay.sh and Solana-only buyers | Not supported. Onchain Router currently accepts Base mainnet USDC only. | A future Solana release requires an intentional payment, ledger, policy, settlement, and recovery design. No compatibility shim is claimed. |\n\nThis table records verified product boundaries, not endorsements or partnership claims. External client and marketplace behavior can change. Re-run the compatibility matrix against the exact deployed release before publishing a claim.\n\n What every buyer must validate\n\n1. The first valid unsigned request returns HTTP 402 and an official PAYMENT-REQUIRED header.\n2. The challenge uses x402 version 2, scheme exact, network eip155:8453, official Base USDC, the expected recipient, the official USDC EIP-712 domain, a future expiry, and an amount within local policy.\n3. The exact request body and stable idempotency key are retained through signing and retry.\n4. No provider work occurs before successful payment verification.\n5. The final settled amount equals the signed exact amount.\n6. A result is released only with durable settlement and receipt evidence.\n7. Unknown provider or settlement outcomes enter recovery; they are never blindly retried.\n\n Inspection versus authorization\n\nAgents and crawlers may send empty, structurally incomplete, or syntactically malformed unsigned JSON to discover that a route is paid. The response carries an inspection marker and a standards-valid x402 challenge, but its amount is not a quote for that invalid body. A complete request with an unsupported model, media type, category, or option returns 400 or 415 before any challenge. Submit a valid body and obtain the request-specific challenge before signing. A signed invalid request also fails before verification, settlement, or provider execution.\n\n Surface-specific no-spend checks\n\nUse each surface's own check rather than treating the repository validator as universal proof:\n\nbash\nnpx -y @agentcash/discovery@latest discover https://onchainrouter.dev\nnpx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/chat/completions\nnpx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/messages\nnpx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/images/generations\nnpx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/audio/speech\nnpx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/audio/transcriptions\n\nGITHUB_SHA=\"$(git rev-parse HEAD)\" pnpm agent:discovery-check \\\n --origin https://onchainrouter.dev \\\n --profile production\n\ncurl -sS -X POST https://api.cdp.coinbase.com/platform/v2/x402/validate \\\n -H 'content-type: application/json' \\\n -d '{\"resource\":\"https://onchainrouter.dev/v1/chat/completions\",\"method\":\"POST\"}'\n\n\nAgentCash discover accepts the API origin, while check requires one complete endpoint URL. The\nrepository validator derives the checked-out commit and, when GITHUB_SHA is set, requires it\nto match that exact HEAD. This binds the saved report to the source under review. The Coinbase\nvalidation call is read-only and requires no API key. Continue only when its response\ncontains valid: true and simulation.outcome: \"accepted\"; review every preflight failure and\nadvisory before any funded call. Poncho and awal are buyer acceptance paths, not catalog validators.\nCoinbase Bazaar is a separate seller-indexing path: after an authorized CDP-facilitated settlement,\ndecode and retain the sanitized EXTENSION-RESPONSES Bazaar result (success, processing, or\nrejected), then check catalog, semantic search, and merchant discovery for every canonical paid\nresource. Record validation, settlement-extension evidence, catalog, search, and merchant results\nseparately.\n\nEach runtime challenge also supplies the x402 v2 ResourceInfo fields used by capable directories:\nserviceName: \"Onchain Router\", an absolute public logo URL, a nonempty route description, JSON\nmedia type, and route-specific tags for chat, image generation, text-to-speech, or transcription.\nThese hints improve machine classification but do not substitute for genuine independent buyer\nusage. The current x402scan registration and Coinbase validation results are external observations,\nnot permanent guarantees; recheck them against the exact deployed release.\n\n Honest external validation sequence\n\nRun the no-spend validator first. After the corrected release is deployed, repeat it against https://onchainrouter.dev. Only then, with explicit wallet and USDC authorization, run one non-retried paid canary per third-party buyer. Save sanitized evidence: client/version, endpoint, catalog version, outcome class, receipt ID reference, settlement transaction, and recovery result. Never record a seed phrase, private key, payment signature, complete payment payload, prompt, completion, receipt capability, or hosted media URL.\n\nMarketplace listing and search placement are external results. A successful payment does not by itself prove that x402scan or Coinbase Bazaar indexed the resource."},{"title":"How authorization, charges, and receipts work","description":"Understand the exact price you approve, the amount paid, and the payment evidence saved in the receipt.","route":"/docs/payment-receipts","text":"For text, max_tokens sets the largest response the model may return and affects the exact request price. The server prices a conservative input estimate plus 10% of that output limit. Image generation selects one disclosed fixed price from the requested model and image_size; aspect_ratio does not change the tier. Text to speech prices validated characters; transcription prices validated audio duration using the catalog's duration quantum. Each includes the applicable published fees.\n\n Pricing terms\n\n- Exact request price: the amount in the x402 challenge and EIP-3009 authorization. A successful request pays this amount.\n- Text reserve: the conservative input estimate plus 10% of requested max_tokens; it is priced before signing.\n- Provider cost: catalog rates multiplied by actual normalized token usage for text; the fixed\n image-output accounting floor plus any reported prompt or residual output usage for images.\n- Service fee: 0% during the launch promotion, recorded as zero integer basis points.\n- Fixed successful-call fee: 1000 atomic USDC units, or 0.001000 USDC.\n- Minimum request charge: 1000 atomic USDC units, or 0.001000 USDC, before the separate fixed successful-call fee. This is not the complete minimum successful charge.\n- Text payment: the calculated exact request price, including the applicable floor and fixed fee.\n- Image payment: the selected model/size catalog price plus the fixed successful-call fee. The current Base mainnet Gemini 3.1 Flash-Lite Image 1K/1:1 total is 0.035000 USDC.\n\nImage token counts are optional upstream telemetry and do not affect the fixed image price. A zero\nimage token count in a receipt means the provider compatibility layer did not report that field; it\ndoes not mean that image generation used no computation.\n\nThe server uses integer arithmetic and rounds once when converting to six-decimal USDC. Provider-reported usage is retained for receipts, cost controls, and route health; it does not produce a later refund.\n\nThe 0% service fee promotion means no percentage markup; it does not mean that the fixed fee, request-price minimum, wallet costs, or network fees disappear. Always use [live pricing](/v1/pricing) and the current 402 challenge rather than copying prices from a guide.\n\n Local client recovery\n\nBuyer Runtime retains a durable request ledger. Preserve the original key and use its receipt lookup or an explicitly permitted same-request recovery. If the provider or settlement outcome is unknown, stop and seek human review. The Workbench keeps an encrypted recovery record for up to one hour and restores it on a same-tab reload; closing the tab discards its decryption key. Neither reloading nor closing a tab reverses a payment. See [recovery](/docs/errors-retries) and [Workbench](/docs/workbench).\n\n Receipt evidence\n\nThe successful response includes the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, X-Receipt-Token, and X-Catalog-Version headers, plus a receipt link. Retrieve the receipt with GET /v1/receipts/{receipt_id} and the X-Receipt-Token header. Treat the receipt token like a password: store it securely and never log or share it. The server stores only a one-way hash of the token.\n\nThe durable receipt contains the public model name, normalized usage, pricing policy, signed exact\namount, settled amount (equal to that signed price for a successful exact payment), payment\nnetwork, payment asset, and transaction reference. It never contains the prompt, model answer,\nwallet key, provider credential, raw signature, complete payment payload, or receipt token.\n\nThe x402 transaction proves that payment occurred. The usage section is an Onchain Router record,\nnot a separate provider-signed proof. Text usage is normalized from mandatory provider telemetry;\nimage usage retains optional provider telemetry and uses zero when a field was not reported."},{"title":"Text generation & Messages","description":"Two familiar request formats for the same text capability.","route":"/docs/text","text":"When a Messages response contains tool_use, return its id verbatim as the matching\ntool_result.tool_use_id. IDs may be long opaque strings carrying provider continuation data;\ndo not shorten, decode, normalize or log them. Keep the assistant tool-use block in the next turn.\n\n Choose a format, not a different provider\n\nPOST /v1/chat/completions accepts OpenAI-compatible messages and returns choices. POST /v1/messages accepts Anthropic-compatible messages and returns content blocks. Both use the same enabled text models and USDC payment lifecycle.\n\nChoose Chat Completions for an OpenAI-style client; choose Messages for an Anthropic-style client. Neither format means that OpenAI or Anthropic models are currently offered. Gemini serves the current text catalog.\n\n Models and parameters\n\nRead [models](/v1/models) for compatible IDs and limits. Supply an explicit model, messages, and an output-token request within that model's advertised limits. Text supports the documented vision, tools, and structured-output shapes. Streaming is not available.\n\nStart with [Chat Completions](/docs/api/chat-completions) or [Messages](/docs/api/messages). Text uses a fixed exact request price based on conservative input estimation, 10% of requested output, and published fees. Provider-reported usage remains visible in the receipt.\n\n Supported generation controls\n\nChat Completions forwards temperature (0–2), top_p (0–1), stop (one string or up to four strings),\ntool_choice, parallel_tool_calls, seed, frequency_penalty, and presence_penalty.\nmax_completion_tokens is an alias for max_tokens; supplying different values for both is rejected.\nOnly one completion (n: 1) is supported. Unsupported controls such as reasoning_effort, thinking,\ntop_k, and log-probability options are rejected rather than silently ignored. Model-specific provider\nsupport still applies; accepting a transport field does not guarantee every model implements it.\n\nMessages translates Anthropic system, image blocks, tools[].input_schema, assistant tool_use,\nand user tool_result blocks into the private provider format. temperature (0–1), top_p,\nstop_sequences, and tool_choice (auto, any, tool, or none) are supported, including\ndisable_parallel_tool_use where applicable. Tool results keep their tool_use_id; do not replace\nthem with ordinary text when continuing a conversation.\n\nMessages responses preserve text and tool-use blocks, tool IDs, and parsed JSON inputs. A tool request\nends with stop_reason: \"tool_use\"; output truncation is \"max_tokens\". Malformed tool arguments are\na failed provider response and are not settled as a successful answer. Provider usage still counts\ntowards our internal provider-cost controls.\n\n Truncation and recovery\n\nA finish_reason of length can be a successful, charged but truncated answer. If you intentionally request a longer answer, that is a new logical request with a new key and authorization. Do not change the body under the old key.\n\nLost responses and ambiguous outcomes must follow the original request's recovery directive. Automatic model selection is experimental source-only; the public endpoint does not silently choose a provider for you."},{"title":"Generate images","description":"Select an image model and supported specifications, then retrieve hosted or Base64 output.","route":"/docs/images","text":"Use POST /v1/images/generations with a model from the image_generation category. Read [the live catalog](/v1/models) before choosing a size or aspect ratio; only advertised options are accepted.\n\n Request and price\n\nThe JSON includes model, prompt, n, image_size, aspect_ratio, and response_format. One image is supported per request. 1K and 1:1 are the defaults, but do not infer that larger sizes or all Gemini image models are currently enabled.\n\nThe selected image tier determines its published price plus the fixed successful-call fee. The 0% service fee promotion does not remove that fixed fee. Confirm live payment terms before signing.\n\n Output and retention\n\nDefault hosted output is a capability URL. The response includes url_retention_days: 7 and the exact url_expires_at timestamp. Download before expiry. The URL is not a permanent public image host, and anyone with the capability URL may access it while valid.\n\nBase64 output is available where the route contract supports it. Do not log image bodies or complete hosted URLs. See [request schema and example](/docs/api/image-generations) for exact fields.\n\nThe current scope is image generation, not image editing or video. All adapters still use the same Buyer Runtime payment and recovery rules."},{"title":"Understand errors and retry safely","description":"Learn which failures are safe to retry and how one idempotency key prevents duplicate model requests and charges.","route":"/docs/errors-retries","text":"An idempotency key identifies one logical request. When recovery is permitted and the result is still retained, reuse the original body, payment authorization, and key to retrieve the existing result without another model call or charge. Follow the client's returned retry directive; a key alone is not permission to sign a new payment.\n\n Safe to correct and retry\n\n- Before signing, correct invalid JSON, the model, or the output ceiling and obtain a request-specific challenge.\n- An unsigned HTTP 402 is expected. If X-Onchain-Router-Challenge-Kind or price.type is inspection, do not sign it: first submit a complete valid body. For a request-specific challenge, validate every payment term before signing and sending the identical body.\n- An expired authorization may be replaced only if it was never sent or the server authoritatively confirms failure without settlement. Expiry alone does not prove that an earlier payment failed.\n- A definite empty_provider_response is not settled. If you choose to try again, increase max_tokens within your policy, use a new request key, and obtain a fresh challenge for the changed body.\n- Definite provider rejection before acceptance: correct the cause and retry with a new idempotency key.\n- wallet_request_cap_exceeded: lower the requested output ceiling and obtain a new quote, or ask the operator to review the policy.\n\n Do not retry blindly\n\n- provider_outcome_unknown\n- settlement_unknown\n- lost connection after wallet authorization\n- timeout after the provider or facilitator may have accepted work\n\nKeep the original request identity and inspect its receipt or stored state. Use the client's explicit same-request recovery action only when allowed; it reuses the saved body and payment authorization rather than signing again. ProviderOutcomeUnknown and SettlementOutcomeUnknown require human review. Do not create a new payment while the outcome is unresolved. An expired response buffer is not proof of nonpayment.\n\n Idempotency rules\n\nThe first-party clients send x-idempotency-key, and x402 payment identifiers may provide an additional protocol identity. Repeating an identical authorized request returns the original result or stored state while recovery remains available, without a second model call or charge. Reusing the key with a changed request returns HTTP status 409. See [retention](/docs/privacy) for the result-recovery window.\n\nRedis loss does not weaken these guarantees because PostgreSQL owns the execution lease and authorization fingerprint."},{"title":"Generate speech","description":"Turn text into hosted MP3 audio using a live model and public voice alias.","route":"/docs/speech","text":"Use POST /v1/audio/speech. Discover the text_to_speech model in [models](/v1/models) and select a voice from [voices](/v1/audio/voices). The current provider is ElevenLabs Flash v2.5.\n\n Input and output\n\nSupply model, input, voice, and response_format: \"mp3\", with optional supported speed. The current input limit is 2,000 characters; consult the live catalog if it changes.\n\nThe response is JSON containing a hosted audio asset, not an OpenAI binary audio stream. Read data[0].url, data[0].expires_at, and usage.input_characters. A generic OpenAI SDK binary-audio method is not interchangeable with this JSON route.\n\n Pricing and privacy\n\nSpeech billing uses validated character usage and the published fees. The hosted audio URL expires after 24 hours at the exact returned timestamp. Download it before expiry and keep the full capability URL private.\n\nText-to-speech uses ElevenLabs Zero Retention Mode. Do not confuse that provider setting with the separate 24-hour hosted output lifetime, or with speech-to-text's retained mode.\n\nSee [full speech reference](/docs/api/audio-speech) and [privacy](/docs/privacy)."},{"title":"Transcribe speech","description":"Send one bounded MP3 with an explicit understanding of provider retention.","route":"/docs/transcription","text":"Use POST /v1/audio/transcriptions with the speech_to_text model from [discovery](/v1/models). The current provider is ElevenLabs Scribe v2.\n\n> ElevenLabs processes uploaded audio and transcript output in standard retained mode. It may retain both independently of Onchain Router's local staging cleanup. Only upload audio you have the right and permission to process.\n\n Choose a transport\n\nThe public HTTP API accepts MP3 via canonical Base64 JSON or multipart form data. The local proxy accepts JSON only. MCP and Agent Skill have smaller inline payload limits than the public upload route.\n\nThe current server limit is 25 MiB, with duration from 250 ms to 30 minutes. MCP accepts 1,048,576 Base64 characters (about 768 KiB MP3); Skill JSON is bounded to 1,000,000 bytes. Use human CLI file upload for larger files. Never hand an agent an arbitrary URL to fetch or a private filesystem path through a media tool.\n\nOur local clients require acknowledge_provider_retention: true after human permission. This local flag is removed before the API call. It does not turn retention off.\n\n Billing and output\n\nThe response contains transcript text and validated usage.input_audio_ms. Published duration pricing uses a billing quantum; inspect [live pricing](/v1/pricing), not a guess from the filename. See [API reference](/docs/api/audio-transcriptions).\n\nLocal encrypted staging is deleted after definite outcomes where possible. Ambiguous outcomes and physical storage deletion have separate expiry behavior described in [privacy](/docs/privacy). Local deletion does not delete the provider's copy."},{"title":"Local response caching","description":"What is cached, when a cache hit costs nothing new, and how to preserve recovery.","route":"/docs/caching","text":"Caching is implemented in the local OpenAI proxy. The public API, direct SDK, CLI, and MCP do not provide this response cache. This is not provider prompt-prefix caching or a cached-token price discount.\n\n Eligible text only\n\nThe proxy can reuse an identical successful text answer for up to ten minutes inside the same wallet, agent, session, policy, origin, and catalog. It keeps bounded memory: at most 200 entries, 1 MiB per item, and 16 MiB serialized data in total. Shutdown clears it.\n\nTools, media, streaming, refusals, incomplete output, unknown extensions, and confirmation-only policies are excluded. Repeated stochastic prompts can return the same answer; refresh when you need a new sample or current information.\n\n Cache hit meaning\n\nx-onchain-router-cache: HIT and x-onchain-router-charge-atomic: 0 mean no new paid execution. The source receipt identifies the original request. There is no new settlement or receipt; body usage belongs to the original inference.\n\n Control and recovery\n\n- An explicit Idempotency-Key always bypasses the cache. Keep stable keys for requests that need durable recovery.\n- Cache-Control: no-cache requests a fresh answer.\n- Cache-Control: no-store, cache: false, or no_cache: true bypasses cache reads and writes.\n- Proxy --no-cache disables it for the process.\n\nDo not omit a recovery key just to get cache hits. Simultaneous fresh misses may each execute; this is not request coalescing. See [local proxy](/docs/proxy).\n\nOpenClaw and Hermes intentionally send stable turn idempotency keys and no-store, so their paid\nturns do not use this response cache. The proxy coalesces concurrent _discovery reads_ only and avoids\nfetching pricing when only models are needed. It still checks the live catalog and current local\npolicy before reusing an answer; there is no stale-catalog TTL and no coalescing of signed payments."},{"title":"How request content is stored and deleted","description":"See which request content is stored, why it is needed, when it is deleted, and which sensitive values never enter logs or receipts.","route":"/docs/privacy","text":"After payment verification and before calling the model provider, Onchain Router screens the verified request text and stores an encrypted review copy for seven days. This short retention period supports abuse review, compliance with model-provider policies, security investigations, and product analysis.\n\n Retained\n\n- verified text from the prompt, limited by the maximum request size;\n- an encrypted and redacted review excerpt together with the review decision;\n- the deletion date and an audit record for each individual access.\n\nDetected credentials and obvious personal identifiers are removed before encryption. If the request matches a configured policy block, the service stops before calling the model provider and does not charge the customer.\n\n Not placed in telemetry or receipts\n\n- prompts or completions;\n- raw wallet signatures;\n- complete payment payloads;\n- receipt access tokens;\n- wallet private keys;\n- provider credentials;\n- cloud project identifiers.\n\nCompleted model answers use a separate encrypted recovery buffer. They are kept for 15 minutes after a successful response, or for up to one hour if the payment result is uncertain. This recovery buffer is separate from the seven-day prompt-review record.\n\nGenerated images use a separate encrypted private-media store. Every image response includes\nurl_retention_days: 7 and an exact url_expires_at timestamp. The capability URL stops serving\nthe image at that timestamp. Azure lifecycle management permanently deletes the encrypted object\nafter it becomes seven days old; the physical deletion completes on Azure's next lifecycle scan.\nDownload the image before expiration if it must be kept longer.\n\nGenerated speech audio has a separate 24-hour capability URL lifetime, shown by the response's\nexpires_at timestamp. Download before expiry; anyone holding the complete URL may retrieve it\nwhile it is valid. Provider Zero Retention Mode does not remove this hosted output storage.\n\nText-to-speech requests use ElevenLabs Zero Retention Mode. Speech-to-text uses ElevenLabs standard\nretained mode: ElevenLabs receives the uploaded audio and transcript output and may retain both\nunder the applicable agreement, account settings, and privacy policy. Onchain Router encrypts STT\nstaging only after payment authorization and attempts to delete its local copy after every definite\nprovider success or failure. After an ambiguous provider outcome, local staging becomes logically\ninaccessible at its one-hour expiry. Encrypted bytes may remain beyond the one-day storage-lifecycle\nthreshold until Azure completes its next lifecycle scan. Local deletion by Onchain Router does not\ndelete data held by ElevenLabs.\n\n Processing and deletion\n\nGoogle Vertex AI processes requests to generate text or images. ElevenLabs processes text-to-speech\nand speech-to-text requests under the route-specific retention behavior above. Coinbase Developer\nPlatform verifies and settles x402 payments, and Base records the public transaction. Each service\nreceives only the information needed for its role. Encrypted prompt-review records and generated\nimages follow their separate seven-day deletion controls. An authorized operator can review only\none prompt-review record at a time, and every access is audited.\n\n Public service boundaries\n\nThis page describes the implemented data flow and retention behavior for the public service.\nThe current public speech scope accepts MP3 through ElevenLabs Flash v2.5 text to speech and Scribe v2\nspeech to text. In particular, do not submit personal, confidential, regulated, biometric, or\nthird-party audio to speech-to-text. For every route, submit content only when you have the right to\nprocess it through the named providers and public-chain payment flow."},{"title":"Product changes and model retirement policy","description":"Review dated changes to the public interface, model catalog, pricing, payments, and documentation.","route":"/docs/changelog","text":" 2026-09-04 — Independent stable client distribution 0.2.0\n\n- Published all six MIT client packages under the independent @onchainrouter npm scope at exact\n version 0.2.0, with npm provenance and a clean anonymous-install verification.\n- Published the matching source release at\n [OnchainRouter/onchain-router](https://github.com/OnchainRouter/onchain-router/releases/tag/v0.2.0).\n- Released the OpenClaw and Hermes adapters as stable v0.2.0 GitHub distributions after their\n native host-install qualifications passed on the exact merged commits.\n- Moved all current install, support, source, and machine-readable product links to the\n OnchainRouter organization and onchainrouter.dev identity. Historical entries below remain a\n dated record and are not current installation instructions.\n- Kept funded OpenClaw/Hermes host acceptance, ClawHub listing, and PyPI publication as separate\n unverified states. Stable package publication does not widen wallet authority or production API\n payment behavior.\n\n 2026-09-04 — Landing and documentation fidelity pass\n\n- Rebuilt the landing surface around the measured Aoutive frame, section rhythm, typography,\n pricing, FAQ, CTA, and responsive composition while retaining Onchain Router product content.\n- Rebuilt documentation around the measured Docly 280/820/340 desktop shell, mobile navigation,\n article actions, right outline, light code/table treatments, and compact footer.\n- Self-hosted Space Grotesk and Inter for the landing surface, Satoshi and Inter for documentation,\n and Fragment Mono for code. No public font CDN or hotlinked reference asset is required.\n- Added an original isometric request/payment/receipt illustration and verified paired reference\n and implementation captures at 1440 × 960 and 390 × 844.\n- Reconciled the design with the independent @onchainrouter stable release and current GitHub\n links. Corrected CLI setup/unlock identity, example token limits, exact-price explanations,\n browser reload recovery, and the speech recipe's default voice.\n- Kept the HTML, Markdown, search index, and agent documentation synchronized; reduced the icon\n stylesheet to the glyphs used by the website.\n\n 2026-09-04 — OpenClaw and Hermes GitHub alphas\n\n- Published immutable MIT v0.1.0 GitHub releases for the OpenClaw and Hermes adapters after their\n repository CI and release workflows passed.\n- Added native host install paths: OpenClaw's pinned external-Git plugin command and Hermes'\n GitHub plugin command, with the exact Hermes release commit available for reproducible installs.\n- Published built OpenClaw, Hermes wheel, and Hermes source-distribution assets with recorded\n SHA-256 digests.\n- Kept ClawHub listing, PyPI publication, funded host acceptance, and general availability as\n separate unverified states. The adapters still delegate all wallet and payment authority to the\n local Buyer Runtime.\n- Corrected the AgentCash no-spend instructions: discovery accepts the API origin, while\n compatibility checks require a complete route URL.\n\n 2026-09-03 — Branded x402 resource discovery\n\n- Added the stable Onchain Router service name, public mark, and route-specific search tags to the\n x402 v2 ResourceInfo for all five paid endpoints.\n- Kept the official Coinbase Bazaar input/output schemas on every route and extended the no-spend\n 25-probe validator to fail on missing, incorrect, or cross-route discovery metadata.\n- Documented x402scan ownership registration and Coinbase validation/indexing as separate external\n evidence; this release does not create a signature, payment, ranking, or directory claim.\n- After protected deployment, registered the canonical origin on x402scan, confirmed its public\n nine-resource server page, verified AgentCash OpenAPI discovery, and observed all five Coinbase\n routes as active with valid: true and simulation.outcome: \"accepted\". Funded per-route refresh\n and independent-buyer search ranking remain separate evidence.\n\n 2026-09-03 — AgenticFI npm alpha 0.1.2\n\n- Published all six MIT AgenticFI client packages as npm alpha 0.1.2 from the public client\n repository with provenance.\n- Verified a clean isolated installation of all six packages, 0.1.2 CLI/MCP/proxy binaries,\n library imports, 78 registry signatures, and 35 attestations.\n- Updated the OpenClaw and Hermes source adapters to pin the corrected 0.1.2 proxy and CLI\n dependencies while retaining their independent 0.1.0 source-alpha versions.\n\n 2026-09-03 — Exact Base USDC payments\n\n- Simplified all five paid routes to one official x402 v2 exact EIP-3009 authorization. Ordinary\n requests need Base USDC only—no Base ETH and no token approval.\n- Fixed each text request's price from a conservative input estimate plus 10% of requested output,\n the published minimum and fixed fee, and the 0% service-fee promotion. Media keeps its cataloged\n request-specific price.\n- Kept provider-reported usage in durable receipts and cost controls while preserving payment-first\n execution, idempotency, recovery, and result-settlement-receipt ordering.\n- New Buyer Runtime profiles use exact automatically. Existing upto profiles remain readable and\n can migrate only through an authenticated policy set --scheme exact action.\n\n 2026-09-03 — Explicit buyer-funded Permit2 approval\n\n- Removed the unsupported gas-sponsorship declaration from every paid challenge. Coinbase does not\n pay or reimburse the buyer's approval gas.\n- Added an explicit canonical Permit2 approval step to the Buyer Runtime, CLI, SDK, and browser\n workbench. The CLI bounds approval to the reviewed daily policy; the workbench bounds it to the\n verified request maximum.\n- Added a pre-signing allowance check so a missing approval fails before an x402 payment signature,\n provider call, settlement, or receipt.\n\n 2026-09-02 — Buyer CLI first-use payment correction\n\n- Gave the short-lived Buyer Runtime signer a read-only Base client so the official x402 upto\n implementation can attach the server-advertised EIP-2612 permit for a first-use wallet with zero\n Permit2 allowance. No payment cryptography was reimplemented.\n- Added one-command setup flags for models, agent identity, all four USDC budgets, output-token\n limits, confirmation policy, and wallet mode. Private keys, seed phrases, and passphrases remain\n no-echo terminal-only inputs.\n- Separated piped request JSON from human authorization by reading confirmations from the\n controlling terminal, and surfaced only safe token-shaped rejection codes from the updated\n official payment header.\n- Added first-wallet, payment-error, controlling-terminal, one-command setup, and secret-flag\n regression coverage. This source correction does not publish a package, deploy production, sign\n a production request, or spend USDC.\n- A proposed facilitator-sponsored approval path was shipped in source but disproved by funded\n production verification and superseded by the 2026-09-03 correction above.\n\n 2026-09-01 — strict inspection and independent discovery evidence\n\n- Limited inspection 402 responses to absent, required-root-field-incomplete, or syntactically\n malformed unsigned JSON. Complete unsupported models, options, media, and content types now fail\n with 400/415 before a payment challenge or provider work.\n- Bound the no-spend validator to the exact production origin, network, USDC asset, recipient,\n canonical URL, positive nonzero facilitator address, route timeout, inspection header, and\n response-body marker, and reject malformed or noncanonical challenge encoding.\n- Labeled client-family funnel data as caller-claimed and carried the same allowlisted dimension\n through every stage from discovery to durable receipt and response release.\n- Separated AgentCash discovery, Poncho acceptance, awal acceptance, and Coinbase Bazaar indexing;\n corrected public npm alpha documentation and portable request-key examples.\n- Restored the approved static Buyer Runtime hero. This corrective source release does not deploy\n production, use a wallet, spend USDC, or change any marketplace.\n\n 2026-09-01 — payment-first agent discovery\n\n- Added official x402 inspection challenges for unsigned empty, incomplete, and malformed JSON on\n all five paid routes. Inspection responses are clearly marked and must not be signed; valid bodies\n still receive request-specific maxima.\n- Kept signed invalid requests, oversized bodies, and malformed media fail-closed before payment\n verification, provider execution, settlement, or receipt creation.\n- Added task recipes, an honest wallet/client compatibility matrix, and a 15-probe no-spend\n validator for Chat, Messages, Images, Text to Speech, and Speech to Text.\n- Added privacy-safe aggregate counters from discovery through durable receipt and response release.\n Telemetry stores only allowlisted client families and route/stage labels, never caller identifiers\n or request/payment content.\n- Reconciled package READMEs with the recorded public npm alpha while preserving this backend\n monorepo's non-publishable workspace manifests. No deployment, paid canary, or marketplace\n submission is performed by this change.\n\n 2026-09-01 — public client and platform update\n\n- Added task-oriented guides for Buyer Runtime, CLI, TypeScript/Python, local MCP, local OpenAI\n proxy, Agent Skill, and browser Workbench, with explicit public-alpha availability.\n- Reconciled the website with the initial public npm alpha and MIT client, OpenClaw, and Hermes repositories.\n- Rebuilt the landing page around controlled agent spending, live capabilities, exact integration status, install commands, and verifiable source links.\n- Reorganized text, image, speech, and transcription documentation around what you want to build.\n- Replaced outdated payment-wrapper snippets and clarified fees, media expiry, recovery, local\n caching, and speech transport differences.\n- Added a product publication manifest and artifact-backed Workbench links. This documentation\n update does not itself publish client packages or deploy a new payment service.\n\n 2026-08-21\n\n- Published the exact five paid AI endpoints and four free discovery endpoints on the homepage,\n endpoint overview, llms.txt, complete agent corpus, sitemap, and portable Agent Skill.\n- Deployed and indexed the guarded Flash v2.5/Scribe v2 MP3 speech scope after exact-build dark\n activation, one non-retried provider/storage qualification, and public no-spend parity checks.\n x402scan now resolves all nine public resources; the release automation did not spend USDC.\n- Added canonical Base64 JSON input to the existing speech-to-text endpoint while retaining the\n standard multipart upload. Both forms decode and inspect the same bounded MP3 bytes before any\n payment challenge, provider call, or settlement.\n- Published the JSON schema and a valid unpaid probe example so JSON-only agent directories can\n verify and list speech to text without adding another public endpoint.\n\n 2026-08-19\n\n- Prepared the guarded speech catalog with elevenlabs/flash-v2.5 for MP3 text to speech and\n elevenlabs/scribe-v2 for MP3 speech to text. Multilingual TTS and every other audio format remain\n unavailable until their qualification gates pass.\n- Corrected the generated TTS guide to use the actual expires_at response field and added a\n complete multipart STT request example that preserves the body across the unpaid and paid calls.\n- Updated OpenAPI, pricing, x402 discovery, the portable Agent Skill, privacy language, and model\n documentation to describe measured speech usage and ElevenLabs' route-specific retention modes.\n- Clarified that ambiguous encrypted STT staging becomes inaccessible at its one-hour logical\n expiry, while physical deletion can complete later through Azure storage lifecycle management.\n\n 2026-08-14\n\n- Matched Gemini 3.1 Flash-Lite Image's fixed-1K Vertex contract by retaining the selected aspect\n ratio but omitting the redundant private provider imageSize field. Public requests still select\n and receive a validated 1K image at the same $0.035 promotional total.\n- Corrected the private Vertex generateContent adapter so image size and aspect ratio use its\n official generationConfig.imageConfig fields. The public image endpoint and request format do\n not change.\n- Kept the service dark until the corrected immutable build passes one non-retried Flash-Lite\n provider and encrypted-storage qualification. No USDC is used by that qualification.\n- Kept text-to-speech in ElevenLabs Zero Retention Mode and changed speech-to-text to the provider's\n standard retained mode after the protected Scribe v2 qualification confirmed that STT ZRM was\n unavailable for the production account. Onchain Router's encrypted STT staging is still deleted\n after a definite result, while ElevenLabs may retain audio and transcripts under its own policy.\n- Kept every speech model and voice dark until the revised adapter passes one new non-retried\n qualification and the remaining media, privacy, and release gates are complete.\n\n 2026-08-13\n\n- Selected gemini-3.1-flash-lite-image as the guarded Base-mainnet image model at 1K/1:1 after\n the newer immutable Flash Image builds failed returned-aspect validation. The endpoint remains\n POST /v1/images/generations; Flash Image and Pro Image remain dark.\n- Set the promotional successful-image total to $0.035: $0.034 catalog-fixed provider image price\n plus the existing $0.001 successful-call fee and 0% service fee.\n- Kept the public service dark until this exact Flash-Lite build passes its one-shot provider and\n encrypted-storage qualification. That qualification uses provider credit and no USDC.\n\n 2026-08-12\n\n- Added provider-neutral POST /v1/images/generations with the first Gemini image model, one\n 1024×1024 image per request, OpenAI-compatible URL or Base64 delivery, and a fixed $0.068\n successful-call price during the 0% service fee launch promotion.\n- Added repository support for model-specific image_size and aspect_ratio, with 1K/1:1\n defaults and exact integer price tiers. Additional Flash specifications plus Gemini 3.1\n Flash-Lite Image and Gemini 3 Pro Image are enabled only for non-production qualification; the\n Base mainnet catalog remains on its approved Flash 1K/1:1 route until expansion gates pass.\n- Added private AES-256-GCM encrypted image storage and capability URLs. Every response reports\n url_retention_days: 7 and the exact url_expires_at; URLs stop serving at expiration and Azure\n lifecycle management deletes the encrypted object after seven days.\n- Preserved the financial ordering for images: payment authorization is verified and durable before\n generation, while settlement occurs only after the image and result are durable. Known failed\n generations are not charged.\n- Updated the durable product description from an LLM-only router to an AI model router so the brand\n remains stable as image, video, and audio capabilities are added.\n- Curated the public agent endpoint showcase to OpenAI-compatible Chat Completions, Anthropic-compatible Messages, categorized Models, detailed Pricing, and a Base USDC Balance lookup. Operational and private support routes remain functional but are no longer presented as separate products.\n- Organized /v1/models around available capability categories and endpoint compatibility. Text and\n image generation are now available; video, speech-to-text, and text-to-speech categories will\n appear only when those capabilities are released.\n- Added a readable unpaid-402 JSON explanation while retaining the official PAYMENT-REQUIRED header as the authoritative payment challenge.\n- Corrected Bazaar discovery identity so each paid challenge names the canonical public Onchain Router endpoint instead of the private Azure API hostname. This does not change payment amounts or settlement behavior.\n- Corrected Base mainnet payment persistence for the official x402 Permit2 upto payload emitted by the wallet client. The authorization nonce is now durable before any model request is sent.\n- Improved the wallet test page's phase-specific errors for nested wallet rejections, payment-persistence failures, and uncertain settlement. Server traces now include only a safe failure category, never signatures, payment payloads, prompts, or completions.\n- Activated a catalog-versioned 0% service fee launch promotion across production billing, pricing pages, endpoint descriptions, OpenAPI, model discovery, quotes, and receipts.\n- Corrected discovery's minimum successful price to include both the $0.001 minimum usage charge and the separate $0.001 fixed successful-call fee.\n- Simplified the local production buyer so it connects directly to the public endpoint without the retired dark-release canary credential.\n- Kept each request's signed spending limit and truthful dynamic discovery range. The final charge still uses measured usage and never exceeds the amount authorized by the buyer.\n\n 2026-08-11\n\n- Made the durable product identity provider-neutral: Onchain Router is now described as the x402-native LLM router, while Gemini remains clearly identified as the current MVP catalog rather than the brand itself.\n- Published the progressive-branch mark through root favicon, manifest, Open Graph, Twitter, and OpenAPI logo metadata so discovery directories and social previews can resolve the intended logo.\n- Declared explicit OpenAPI auth modes for public, receipt-protected, and x402-paid operations so x402scan can register supporting resources without treating free endpoints as broken paywalls.\n- Simplified every customer-facing payment reference to Base mainnet and USDC, removing internal-network explanations, redundant payment-value wording, and the pre-launch unavailability notice.\n- Reworked the website into a wider editorial layout that uses large screens more effectively.\n- Reduced heading sizes across the home page, documentation, model catalog, pricing, status, and legal pages.\n- Replaced the operating-system font fallbacks with a self-hosted Plus Jakarta Sans variable font and a sharper, more consistent weight system across the public site.\n- Applied the same font to the wordmark, navigation, and Base Mainnet label, and refreshed search as a modern command palette.\n- Added content-versioned stylesheet and script URLs so a browser cannot combine updated page markup with stale interface styles.\n- Replaced the temporary letter tile with the selected progressive-branch logo, representing one interface expanding into multiple onchain capabilities, and added a matching favicon asset.\n- Rewrote page titles, descriptions, navigation labels, and introductory copy in clearer language. Technical abbreviations are now explained on first use when the surrounding page is intended for a broad reader.\n- Expanded llms-full.txt into a one-request package containing the product overview, every guide, generated endpoint references, the model catalog, service status, legal drafts, and portable Agent Skill references. Added HTML discovery links and an XML sitemap so agents can find these surfaces without guessing paths.\n- Added local browser checks for wide desktop, laptop, tablet, and mobile layouts. This local review does not publish or activate the paid service.\n\n 2026-08-10\n\n- Published the first custom single-origin website and documentation build.\n- Added HTML, per-page Markdown, llms.txt, llms-full.txt, OpenAPI, sanitized catalog, and Agent Skill surfaces.\n- Set the current paid-inference minimum to 1000 atomic USDC (0.001000 USDC).\n- Qualified the initial Gemini text candidates before selecting the production catalog.\n- Added explicit handling for reasoning-token output ceilings, empty visible responses, actual settlement, and durable receipts.\n- Published the Base mainnet public-alpha contract using USDC, an authoritative per-request cap, and a global conservative estimated-loss breaker. Hourly and daily payer caps were later removed by ADR-024.\n- Removed payer registration and payer allowlisting; every facilitator-verified wallet may purchase under the same limits.\n- Kept automated payment conformance fixtures outside the documented production environment.\n- Approved seven GA Gemini text aliases for mainnet-alpha routing. The gemini-3.1-pro-preview route remains disabled on mainnet.\n- Added fail-closed production configuration, a one-origin site/API deployment, public per-receipt\n capabilities, a least-privilege provider federation role, and a separately approved production\n infrastructure workflow. Synthetic reconciliation is now forbidden in production.\n- Revalidated the public catalog against current Google model and pricing sources, including the\n 65,536-token output limit for gemini-3.1-flash-lite.\n- Expanded the privacy and service-terms release candidates and added automated checks for stale\n test/private-alpha language, operator-only configuration, enabled-model count, and legal sections.\n\n Deprecation policy\n\nModel aliases can change only through an immutable catalog version. A retiring model shows its retirement date in /v1/models and /models. The service does not silently map an alias to a more expensive tier.\n\nClients should discover models rather than hard-code them indefinitely. Before each deployment and periodically during long-running sessions, refresh the catalog and reject an alias that is unavailable, past retirement, or outside the caller's model allowlist.\n\nThe Gemini 2.5 compatibility routes have a conservative operational removal date of 2026-10-16. gemini-3.1-pro-preview is a testing-only preview and cannot become a production default without a new approved catalog and provider gate."},{"title":"Create an OpenAI-compatible LLM response","description":"Endpoint request and response reference","route":"/docs/api/chat-completions","text":" Create an OpenAI-compatible LLM response\n\nPOST /v1/chat/completions\n\nOperation ID: createChatCompletion. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Request body\n\nChoose an available model value from GET /v1/models. The max_tokens value limits the model's output and helps calculate the fixed exact price. A successful request pays the amount shown in the HTTP 402 challenge; shorter output does not create a later refund. Streaming must remain false.\n\njson\n{\n \"model\": \"gemini-3.6-flash\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Explain in two short sentences why the sky appears blue.\"\n }\n ],\n \"max_tokens\": 1024,\n \"stream\": false\n}\n\n\n Payment lifecycle\n\nThe first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, exact scheme, EIP-712 domain, and amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.\n\nAfter success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.\n\n Read the response\n\nVisible text is in choices[0].message.content. A finish_reason value of \"stop\" means the answer completed normally. A value of \"length\" means the answer is valid but ended at the output limit. Usage includes input, output, total, and provider-supported reasoning-token counts. Ignore large provider-specific fields unless the raw response was explicitly requested.\n\n Responses\n\n- 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers\n- 400: Invalid or unsupported request\n- 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge. Empty, structurally incomplete, or syntactically malformed unsigned JSON receives an inspection challenge; a complete semantic error returns 400/415. Submit a valid body to receive its fixed request price before signing.\n- 409: Idempotency key reused with a different effective request\n- 415: Unsupported request content type. This fails before a payment challenge or verification.\n- 503: Provider, payment, or safety dependency unavailable"},{"title":"Create an Anthropic-compatible LLM response","description":"Endpoint request and response reference","route":"/docs/api/messages","text":" Create an Anthropic-compatible LLM response\n\nPOST /v1/messages\n\nOperation ID: createMessage. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Request body\n\nChoose an available model value from GET /v1/models. The max_tokens value limits the model's output and helps calculate the fixed exact price. A successful request pays the amount shown in the HTTP 402 challenge; shorter output does not create a later refund. Streaming must remain false.\n\njson\n{\n \"model\": \"gemini-3.6-flash\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Explain why the sky appears blue.\"\n }\n ],\n \"max_tokens\": 1024,\n \"stream\": false\n}\n\n\n Payment lifecycle\n\nThe first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, exact scheme, EIP-712 domain, and amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.\n\nAfter success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.\n\n Read the response\n\nRead Anthropic-compatible content blocks and normalized usage. The public alias is preserved even though the private gateway resolves an internal Vertex deployment.\n\n Responses\n\n- 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers\n- 400: Invalid or unsupported request\n- 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge. Empty, structurally incomplete, or syntactically malformed unsigned JSON receives an inspection challenge; a complete semantic error returns 400/415. Submit a valid body to receive its fixed request price before signing.\n- 409: Idempotency key reused with a different effective request\n- 415: Unsupported request content type. This fails before a payment challenge or verification.\n- 503: Provider, payment, or safety dependency unavailable"},{"title":"Generate an image from a text prompt","description":"Endpoint request and response reference","route":"/docs/api/image-generations","text":" Generate an image from a text prompt\n\nPOST /v1/images/generations\n\nOperation ID: createImageGeneration. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Request body\n\nChoose an available image-generation model from GET /v1/models. The first release accepts one 1024×1024 image. Use response_format: \"url\" for the default hosted result or \"b64_json\" when inline bytes are also required.\n\njson\n{\n \"model\": \"gemini-3.1-flash-lite-image\",\n \"prompt\": \"A small observatory beneath a clear night sky, editorial illustration\",\n \"n\": 1,\n \"image_size\": \"1K\",\n \"aspect_ratio\": \"1:1\",\n \"response_format\": \"url\"\n}\n\n\n Payment lifecycle\n\nThe first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, exact scheme, EIP-712 domain, and amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.\n\nAfter success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.\n\n Read the response\n\nRead the generated image from data[0].url. The capability-protected hosted URL is available for exactly seven days; data[0].url_retention_days is 7 and data[0].url_expires_at gives the precise expiration time. Download the image before then. When response_format is b64_json, the same item also contains inline bytes, but the hosted URL still expires at the disclosed time.\n\n Responses\n\n- 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers\n- 400: Invalid or unsupported request\n- 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge. Empty, structurally incomplete, or syntactically malformed unsigned JSON receives an inspection challenge; a complete semantic error returns 400/415. Submit a valid body to receive its fixed request price before signing.\n- 409: Idempotency key reused with a different effective request\n- 415: Unsupported request content type. This fails before a payment challenge or verification.\n- 503: Provider, payment, or safety dependency unavailable"},{"title":"List enabled curated text-to-speech voices","description":"Endpoint request and response reference","route":"/docs/api/audio-voices","text":" List enabled curated text-to-speech voices\n\nGET /v1/audio/voices\n\nOperation ID: listAudioVoices. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Responses\n\n- 200: Curated public voice aliases; upstream voice IDs are private."},{"title":"Generate a hosted speech audio asset","description":"Endpoint request and response reference","route":"/docs/api/audio-speech","text":" Generate a hosted speech audio asset\n\nPOST /v1/audio/speech\n\nOperation ID: createSpeech. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Request body\n\nThe public endpoint uses elevenlabs/flash-v2.5 and returns MP3 audio. Choose a public voice alias from GET /v1/audio/voices; omission uses the model's Darian default. The live catalog and HTTP 402 response remain authoritative.\n\njson\n{\n \"model\": \"elevenlabs/flash-v2.5\",\n \"input\": \"Your text to speak.\",\n \"voice\": \"darian\",\n \"response_format\": \"mp3\",\n \"speed\": 1\n}\n\n\n Payment lifecycle\n\nThe first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, exact scheme, EIP-712 domain, and amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.\n\nAfter success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.\n\n Read the response\n\nRead the generated MP3 from data[0].url. The URL is a bearer capability: keep it out of logs and public messages, download it promptly, and treat data[0].expires_at as its exact 24-hour access deadline. The JSON response also reports the validated format, content type, duration, and exact input-character count in usage.input_characters.\n\n Responses\n\n- 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers\n- 400: Invalid or unsupported request\n- 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge. Empty, structurally incomplete, or syntactically malformed unsigned JSON receives an inspection challenge; a complete semantic error returns 400/415. Submit a valid body to receive its fixed request price before signing.\n- 409: Idempotency key reused with a different effective request\n- 415: Unsupported request content type. This fails before a payment challenge or verification.\n- 503: Provider, payment, or safety dependency unavailable"},{"title":"Transcribe one bounded audio upload","description":"Endpoint request and response reference","route":"/docs/api/audio-transcriptions","text":" Transcribe one bounded audio upload\n\nPOST /v1/audio/transcriptions\n\nOperation ID: createTranscription. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Request body\n\nThe public endpoint accepts one MP3 file between the limits published by GET /v1/models. Agents may send canonical Base64 JSON; file-upload clients may use standard multipart form data. The service decodes and inspects the audio before calculating its duration-based exact price. Use a fresh, stable x-idempotency-key and repeat the identical effective request after signing the HTTP 402 challenge.\n\n JSON for agents\n\njson\n{\n \"audio_base64\": \"\",\n \"model\": \"elevenlabs/scribe-v2\",\n \"file_format\": \"other\",\n \"response_format\": \"json\"\n}\n\n\nDo not include a data-URL prefix or whitespace in audio_base64.\n\n Multipart file upload\n\nbash\ncurl --request POST https://onchainrouter.dev/v1/audio/transcriptions \\\n --header \"x-idempotency-key: 11111111-1111-4111-8111-111111111111\" \\\n --form \"file=@speech.mp3;type=audio/mpeg\" \\\n --form \"model=elevenlabs/scribe-v2\" \\\n --form \"response_format=json\"\n\n\nAn ordinary command-line request receives HTTP 402 and does not pay. Validate and sign that challenge with an official x402 client, then repeat the same JSON or multipart request with the payment header. Do not replace the MP3 or change any option between attempts.\n\n Payment lifecycle\n\nThe first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, exact scheme, EIP-712 domain, and amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.\n\nAfter success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.\n\n Read the response\n\nRead the transcript from text and measured duration from usage.input_audio_ms. The JSON response can also include detected language, language probability, word timestamps, speaker labels when diarization is enabled, and tagged non-speech events. The uploaded audio is not returned.\n\n Provider retention\n\nElevenLabs receives the uploaded audio and transcript output in its standard retained mode and may retain both under the applicable agreement, account settings, and privacy policy. Onchain Router attempts to delete its own encrypted staging after every definite provider result. After an ambiguous result, local staging becomes logically inaccessible at its one-hour expiry; encrypted bytes may remain beyond the one-day storage-lifecycle threshold until Azure completes its next lifecycle scan. Local deletion does not delete ElevenLabs' copy. Do not submit sensitive or regulated audio.\n\n Responses\n\n- 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers\n- 400: Invalid or unsupported request\n- 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge. Empty, structurally incomplete, or syntactically malformed unsigned JSON receives an inspection challenge; a complete semantic error returns 400/415. Submit a valid body to receive its fixed request price before signing.\n- 409: Idempotency key reused with a different effective request\n- 415: Unsupported request content type. This fails before a payment challenge or verification.\n- 503: Provider, payment, or safety dependency unavailable"},{"title":"List available capability categories, endpoints, and models","description":"Endpoint request and response reference","route":"/docs/api/models","text":" List available capability categories, endpoints, and models\n\nGET /v1/models\n\nOperation ID: listModels. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Choose a capability\n\nUse only categories whose status is available. The catalog lists text generation, image generation, text to speech, and speech to text with their callable endpoint paths. Each model repeats its category, input and output modalities, and supported endpoints.\n\n Responses\n\n- 200: Current categorized catalog. Only returned categories and endpoints are available."},{"title":"List detailed pricing for all available models","description":"Endpoint request and response reference","route":"/docs/api/pricing","text":" List detailed pricing for all available models\n\nGET /v1/pricing\n\nOperation ID: listPricing. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Read pricing\n\nEach row is keyed by model and capability category. Text uses token rates, text to speech uses character rates, speech to text uses audio-duration rates, and image generation uses a published specification price. Fee and minimum fields remain integer atomic-USDC strings where applicable. The live HTTP 402 challenge remains authoritative for a specific request.\n\n Responses\n\n- 200: Current model rates and pricing policy"},{"title":"Check a Base wallet USDC balance","description":"Endpoint request and response reference","route":"/docs/api/balance","text":" Check a Base wallet USDC balance\n\nGET /v1/balance\n\nOperation ID: getWalletBalance. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json).\n\n Check a wallet\n\nPass a public Base wallet address as the required address query parameter, for example GET /v1/balance?address=0x1111111111111111111111111111111111111111. This free, rate-limited chain read does not connect the wallet or request a signature.\n\n Responses\n\n- 200: Current Base USDC wallet balance\n- 400: Invalid or missing Base wallet address\n- 503: Base balance lookup temporarily unavailable"},{"title":"Models and pricing","description":"Current model catalog and rates","route":"/models","text":"# Models and pricing\n\nCatalog version: `c1f92fac4f1daa37003a8867c9b64b20d27ef935b6d7154c52de18f64cce0fdc`. The catalog is organized by capability. Only categories returned by `GET /v1/models` are available. Text generation, image generation, text to speech, and speech to text are available in this catalog; video generation remains unavailable. The public speech catalog exposes ElevenLabs Flash v2.5 for MP3 text to speech and Scribe v2 for MP3 speech to text. Other speech models and formats remain unavailable until they pass their release gates.\n\n## Available categories\n\n- **Text generation** (`text_generation`): `POST /v1/chat/completions` (openai), `POST /v1/messages` (anthropic)\n- **Image generation** (`image_generation`): `POST /v1/images/generations` (openai)\n- **Text to speech** (`text_to_speech`): `POST /v1/audio/speech` (openai-shaped)\n- **Speech to text** (`speech_to_text`): `POST /v1/audio/transcriptions` (openai)\n\n## Available models\n\n| Model | Capability | Availability | Published price | Delivery and limit |\n|---|---|---|---|---|\n| `gemini-3.6-flash` | Text generation | ga | $1.5 input · $7.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.5-flash-lite` | Text generation | ga | $0.3 input · $2.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.5-flash` | Text generation | ga | $1.5 input · $9 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.1-flash-lite` | Text generation | ga | $0.25 input · $1.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.1-flash-lite-image` | Image generation | ga | 1K (default) $0.035000 | One image · 1 aspect ratios · hosted URL 7 days · optional Base64 |\n| `gemini-2.5-flash` | Text generation | ga | $0.3 input · $2.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-2.5-pro` | Text generation | ga | $1.25 input · $10 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-2.5-flash-lite` | Text generation | ga | $0.1 input · $0.4 output per 1M tokens | 65,536 maximum output tokens |\n| `elevenlabs/flash-v2.5` | Text to speech | ga | $0.05 per 1K characters | 2,000 maximum characters |\n| `elevenlabs/scribe-v2` | Speech to text | ga | $0.22 per audio hour | 30 maximum minutes |\n\nA 0% service fee launch promotion is active. Every successful call adds the disclosed 1000-atomic-USDC ($0.001000) fixed fee. The separate minimum usage charge applies to text and speech prices. Hosted image URLs expire after seven days and hosted TTS audio URLs after 24 hours; download them before their returned expiry. Read detailed rates from `GET /v1/pricing`, the exact amount from the live HTTP 402 response before signing, and payment plus normalized usage from the durable receipt."}]