# Onchain Router — complete documentation > This file contains the complete public documentation needed to understand, integrate with, and safely call Onchain Router without crawling the website. Generated from the same reviewed Markdown and machine-readable contracts as the human-readable website. For compact discovery, read [llms.txt](https://onchainrouter.dev/llms.txt). For exact schemas, read [OpenAPI](https://onchainrouter.dev/openapi.json). For live payment terms, always use the runtime HTTP 402 response. --- # Onchain Router overview Canonical source: [https://onchainrouter.dev/](https://onchainrouter.dev/) Onchain Router is an x402-native AI model router with one provider-neutral interface for text, image, and speech requests. A buyer sends a request, receives an HTTP 402 payment requirement, checks the terms, signs through an official x402 client, and retries the identical request with the same idempotency key. The service settles USDC on Base mainnet and returns a durable receipt. Gemini serves text and image generation; ElevenLabs serves the current public MP3 speech routes. The Onchain Router brand and public contract remain stable as providers are added. ## Production environment Onchain Router uses Base mainnet USDC and the x402 v2 exact EIP-3009 scheme. Agents must validate the network, asset, recipient, expiry, EIP-712 domain, and exact amount and must enforce local per-request and per-session limits. Ordinary requests need no Base ETH or token approval. ## Core safety contract - The model provider is not called before successful payment verification. - A known failed model request is not settled. - A response is not released before the result, settlement, and receipt are durable. - A successful request settles the signed exact amount. - Ambiguous provider or settlement outcomes are not blindly retried. - Wallet private keys remain in the buyer's local process and are never sent to Onchain Router. ## Supported public scope The public contract lists paid Chat Completions, Messages, Image Generations, Text to Speech, and Speech to Text endpoints, plus free voice, model, pricing, and Base USDC balance discovery. Operational health, x402 discovery, quote, media delivery, and private receipt routes remain functional support surfaces but are intentionally omitted from the public endpoint showcase. Only categories returned by the model catalog are available. Streaming, Solana, video generation, image editing, marketplace features, and arbitrary provider routing are outside the current release. The current speech scope is Flash v2.5 MP3 text to speech and Scribe v2 MP3 speech to text. Hosted image URLs expire after seven days and hosted TTS audio URLs after 24 hours. Onchain Router attempts to delete STT staging after every definite outcome; ElevenLabs processes STT in standard retained mode. ## Authoritative sources Use the live model catalog for current categories and model aliases, the pricing endpoint for detailed rates, the live HTTP 402 response for the exact payment requirement, and the durable receipt for settlement and normalized usage. Use the OpenAPI document for the nine public request and response schemas. ## Integration availability AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. - [Choose an integration](https://onchainrouter.dev/docs/index.md): Direct API, MCP, SDKs, proxy, CLI, OpenClaw, Hermes, and Agent Skill. - [Buyer Runtime](https://onchainrouter.dev/docs/buyer-runtime.md): Human-owned wallet, budgets, recovery, and receipts. - [Install and availability](https://onchainrouter.dev/docs/installation.md): Exact npm and host-native GitHub alpha commands and platform support. - [Browser Workbench](https://onchainrouter.dev/docs/workbench.md): Included in this build; local read-only previews cannot pay. - [Product manifest](https://onchainrouter.dev/products.json): Machine-readable publication and integration status. Local stdio MCP is not a hosted ChatGPT connector. OpenClaw and Hermes are GitHub-installable public alphas, not claimed ClawHub or PyPI listings; funded host acceptance remains unverified. The local proxy cache is not public API caching. Automatic routing is experimental source-only. --- # Build with Onchain Router Canonical source: [https://onchainrouter.dev/docs](https://onchainrouter.dev/docs) Last reviewed: 2026-09-04. Onchain Router by AgenticFI 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. ## Choose how you connect | Integration | Best for | Availability | Source | | --- | --- | --- | --- | | [Direct API](https://onchainrouter.dev/docs/direct-api) | You already have an x402 buyer | Public API | Use the public API | | [TypeScript SDK](https://onchainrouter.dev/docs/sdk-examples) | You are building a Node.js application | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [Buyer CLI](https://onchainrouter.dev/docs/cli) | You work in a terminal | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [MCP](https://onchainrouter.dev/docs/mcp) | Your agent uses native tools | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [Local OpenAI proxy](https://onchainrouter.dev/docs/proxy) | Your app accepts an OpenAI base URL | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [Agent Skill](https://onchainrouter.dev/docs/agent-skill) | Your coding agent follows reusable instructions | MIT source · alpha | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [OpenClaw](https://onchainrouter.dev/docs/openclaw) | You use OpenClaw agents | GitHub alpha · 0.1.0 | [GitHub](https://github.com/AgenticFI/onchain-router-openclaw) | | [Hermes Agent](https://onchainrouter.dev/docs/hermes) | You use Hermes Agent | GitHub alpha · 0.1.0 | [GitHub](https://github.com/AgenticFI/onchain-router-hermes) | > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. Buyer Runtime is the shared wallet and payment foundation for the local tools, not another endpoint to choose. Read [how the runtime works](https://onchainrouter.dev/docs/buyer-runtime). ## Start building today If you already have an official x402 buyer supporting Base USDC `exact`, follow the [first-request guide](https://onchainrouter.dev/docs/quickstart). A standard OpenAI client alone cannot pay the public API: it needs an x402-capable transport or our local proxy. For our client tools, review [installation and availability](https://onchainrouter.dev/docs/installation), then install the `0.1.2` npm alpha or a `0.1.0` host-native GitHub alpha. OpenClaw and Hermes Agent have dedicated copyable install guides. For a browser walkthrough, see [Workbench](https://onchainrouter.dev/docs/workbench). ## Choose a capability - [Text](https://onchainrouter.dev/docs/text): Chat Completions or Anthropic-style Messages. - [Images](https://onchainrouter.dev/docs/images): one generated image with a hosted URL or Base64 output. - [Text to speech](https://onchainrouter.dev/docs/speech): hosted MP3 audio with a curated voice. - [Speech to text](https://onchainrouter.dev/docs/transcription): an MP3 transcript, with provider-retention disclosure. The 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. ## Source of truth Use [live models](https://onchainrouter.dev/v1/models), [live pricing](https://onchainrouter.dev/v1/pricing), and [OpenAPI](https://onchainrouter.dev/openapi.json). The HTTP 402 challenge determines the exact request price; the receipt confirms payment and normalized usage. See [pricing](https://onchainrouter.dev/pricing) for the 0% service fee launch promotion and the separate fixed fee. For agents, [llms.txt](https://onchainrouter.dev/llms.txt) is the compact index and [llms-full.txt](https://onchainrouter.dev/llms-full.txt) is the complete Markdown documentation. [products.json](https://onchainrouter.dev/products.json) records publication and build availability, not live uptime. --- # Choose the right endpoint Canonical source: [https://onchainrouter.dev/docs/endpoints](https://onchainrouter.dev/docs/endpoints) Last reviewed: 2026-08-21. 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`. ## Paid AI requests - `POST /v1/chat/completions` — OpenAI-compatible text, vision, tools, and structured output. - `POST /v1/messages` — Anthropic-compatible text, vision, and tool requests. - `POST /v1/images/generations` — Generate one image and receive a hosted URL or Base64 result. - `POST /v1/audio/speech` — Turn text into an MP3 with a public voice. - `POST /v1/audio/transcriptions` — Transcribe one MP3 supplied as canonical Base64 JSON or multipart form data. Every 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. ## Free discovery - `GET /v1/models` — Find available capability categories, model aliases, limits, and compatible endpoints. - `GET /v1/pricing` — Read current model rates, billing units, and the 0% service fee promotion. - `GET /v1/audio/voices` — Choose from the 20 public text-to-speech voice aliases. - `GET /v1/balance?address=0x...` — Read a public wallet's Base USDC balance without connecting or signing. These 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. ## Start with the matching guide - [Chat Completions](https://onchainrouter.dev/docs/api/chat-completions) for OpenAI-compatible clients. - [Messages](https://onchainrouter.dev/docs/api/messages) for Anthropic-compatible clients. - [Image Generations](https://onchainrouter.dev/docs/api/image-generations) for image output. - [Text to Speech](https://onchainrouter.dev/docs/api/audio-speech) and [Voices](https://onchainrouter.dev/docs/api/audio-voices) for hosted MP3 audio. - [Speech to Text](https://onchainrouter.dev/docs/api/audio-transcriptions) for MP3 transcription. - [Models](https://onchainrouter.dev/docs/api/models), [Pricing](https://onchainrouter.dev/docs/api/pricing), and [Balance](https://onchainrouter.dev/docs/api/balance) for machine-readable discovery. Health, 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. --- # Installation & availability Canonical source: [https://onchainrouter.dev/docs/installation](https://onchainrouter.dev/docs/installation) Last reviewed: 2026-09-04. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. ## Fastest safe start Requirements: Node.js 20.18 or newer, macOS or Linux, and a human-controlled terminal. ```bash npm install --global @agenticfi/onchain-router-cli@alpha onchain-router --version onchain-router setup onchain-router policy show onchain-router unlock onchain-router models ``` Version `0.1.2` is the current bounded public alpha. Install with the explicit npm `alpha` tag so your configuration communicates that release boundary. Before installation, verify that the package is under the `@agenticfi` scope and links to [AgenticFI/onchain-router-clients](https://github.com/AgenticFI/onchain-router-clients). Setup, 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. ## Choose a public package | Product | Install | Status | | -------------- | ------------------------------------------------------------ | ------------------------------------------------- | | TypeScript SDK | `npm install @agenticfi/onchain-router@alpha` | Public npm alpha `0.1.2` | | Buyer CLI | `npm install --global @agenticfi/onchain-router-cli@alpha` | Public npm alpha `0.1.2` | | MCP server | `npm install --global @agenticfi/onchain-router-mcp@alpha` | Public npm alpha `0.1.2` | | Local proxy | `npm install --global @agenticfi/onchain-router-proxy@alpha` | Public npm alpha `0.1.2` | | Buyer Runtime | `npm install @agenticfi/onchain-router-buyer-core@alpha` | Public npm alpha `0.1.2`; trusted-adapter authors | | Smart routing | `npm install @agenticfi/onchain-router-routing@alpha` | Public npm alpha `0.1.2`; experimental | The Python SDK remains a source package that delegates paid execution to the matching CLI. It is not on PyPI. | Integration | Best for | Availability | Source | | --- | --- | --- | --- | | [Direct API](https://onchainrouter.dev/docs/direct-api) | You already have an x402 buyer | Public API | Use the public API | | [TypeScript SDK](https://onchainrouter.dev/docs/sdk-examples) | You are building a Node.js application | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [Buyer CLI](https://onchainrouter.dev/docs/cli) | You work in a terminal | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [MCP](https://onchainrouter.dev/docs/mcp) | Your agent uses native tools | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [Local OpenAI proxy](https://onchainrouter.dev/docs/proxy) | Your app accepts an OpenAI base URL | npm alpha · 0.1.2 | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [Agent Skill](https://onchainrouter.dev/docs/agent-skill) | Your coding agent follows reusable instructions | MIT source · alpha | [GitHub](https://github.com/AgenticFI/onchain-router-clients) | | [OpenClaw](https://onchainrouter.dev/docs/openclaw) | You use OpenClaw agents | GitHub alpha · 0.1.0 | [GitHub](https://github.com/AgenticFI/onchain-router-openclaw) | | [Hermes Agent](https://onchainrouter.dev/docs/hermes) | You use Hermes Agent | GitHub alpha · 0.1.0 | [GitHub](https://github.com/AgenticFI/onchain-router-hermes) | ## Agent-host integrations - [OpenClaw](https://onchainrouter.dev/docs/openclaw) `0.1.0` is a public MIT alpha installed from its immutable [GitHub release](https://github.com/AgenticFI/onchain-router-openclaw/releases/tag/v0.1.0) with OpenClaw's native Git installer: `openclaw plugins install git:github.com/AgenticFI/onchain-router-openclaw@v0.1.0 --force`. It is not yet listed on ClawHub. - [Hermes Agent](https://onchainrouter.dev/docs/hermes) `0.1.0` is a public MIT alpha installed from [AgenticFI/onchain-router-hermes](https://github.com/AgenticFI/onchain-router-hermes/releases/tag/v0.1.0) with Hermes' native Git installer: `hermes plugins install AgenticFI/onchain-router-hermes --enable`. It is not a PyPI release, and PyPI is not required for this host-native path. - The portable [Agent Skill](https://onchainrouter.dev/docs/agent-skill) is public in the client repository and requires the matching Buyer CLI. Verify the exact organization, repository, version, and release commit before installation. These public-alpha installs do not prove a funded request in either host; complete the human-owned Buyer Runtime setup and acceptance flow separately. ## Browser Workbench [Open Workbench](https://onchainrouter.dev/workbench/). This build includes the browser UI. A read-only local preview cannot submit paid requests; use only an explicitly enabled deployment for payments. ## Update and verify Pin the `alpha` tag or exact `0.1.2` version. Review release notes before updating, rerun `onchain-router doctor`, and confirm that the local wallet profile, policy, and receipts remain intact. The [product manifest](https://onchainrouter.dev/products.json) records current publication facts; the live [models](https://onchainrouter.dev/v1/models), [pricing](https://onchainrouter.dev/v1/pricing), and HTTP 402 challenge remain authoritative for service behavior. --- # Buyer Runtime Canonical source: [https://onchainrouter.dev/docs/buyer-runtime](https://onchainrouter.dev/docs/buyer-runtime) Last reviewed: 2026-08-31. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. Buyer 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. ## Wallet and authority Wallet 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. Use 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. ## Budgets The 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. A request authorization is not the final charge. The runtime refuses a challenge outside the configured policy. Only the human can widen authority. ## Recovery and receipts A 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. Follow the returned retry directive. `ProviderOutcomeUnknown` and `SettlementOutcomeUnknown` require human review, not a new payment. See [errors and recovery](https://onchainrouter.dev/docs/errors-retries). ## What the runtime is not It is not a hosted wallet, a generic signing tool, or a replacement for the provider API. The browser Workbench uses an injected browser wallet and has a separate, in-memory session. Runtime administration APIs include backup/restore primitives, but do not assume a complete CLI restore/rotation workflow exists. Continue with [wallet setup](https://onchainrouter.dev/docs/wallet-security), [CLI](https://onchainrouter.dev/docs/cli), or [SDK examples](https://onchainrouter.dev/docs/sdk-examples). --- # What happens during a paid request Canonical source: [https://onchainrouter.dev/docs/how-it-works](https://onchainrouter.dev/docs/how-it-works) Last reviewed: 2026-08-21. 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. The 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. ## Lifecycle 1. Send a non-streaming request without payment. 2. Receive Hypertext Transfer Protocol (HTTP) status 402 with an x402 `exact` payment requirement that is tied to the request. 3. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, and exact amount. 4. Sign the payment authorization locally with an official x402 client. 5. Retry the identical body with the same idempotency key, which prevents duplicate work and charges. 6. Onchain Router verifies the payment and reserves exactly one execution record in PostgreSQL. 7. The verified prompt is screened, redacted where required, encrypted, and retained for seven days. 8. The private gateway calls the selected model deployment and validates reported usage plus any returned image or audio bytes. 9. Generated image or TTS media enters encrypted private storage before settlement. STT input is encrypted while staged and deleted after a definite outcome. 10. 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. 11. The result, settlement, ledger entries, and receipt become durable before text, media URLs, or transcripts are released. Every HTTP response includes an `X-Trace-ID`. Keep it when reporting a problem. Onchain Router logs the trace ID, normalized route, method, status and safe error code, duration, content type and size, and catalog version. The normal `402 Payment Required` challenge is tracked separately from endpoint errors. Completed model requests also record non-content routing signals such as model, message and tool counts, request size, requested output limit, capability flags, provider duration, token usage, charge, and provider cost. Request and response text is never copied into these logs. ## Safety boundaries - PostgreSQL is the authoritative record for preventing payment replay and duplicate requests. - Redis can improve speed, but it is never the only system protecting financial correctness. - Known provider failures are not settled. - Provider-unknown or settlement-unknown outcomes are frozen for inspection, not blindly retried. - Settlement equals the signed exact amount. - Prompts, completions, raw payment payloads, private keys, and provider credentials are excluded from telemetry and receipts. --- # Buyer CLI Canonical source: [https://onchainrouter.dev/docs/cli](https://onchainrouter.dev/docs/cli) Last reviewed: 2026-09-03. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. Install the public npm alpha, then complete setup in a human-controlled terminal: ```bash npm install --global @agenticfi/onchain-router-cli@alpha onchain-router setup \ --origin https://onchainrouter.dev \ --models gemini-3.6-flash \ --agent founder-cli \ --per-call-usdc 0.02 \ --session-usdc 0.06 \ --hour-usdc 0.06 \ --day-usdc 0.10 \ --max-output-tokens 256 \ --confirm-each true \ --wallet-mode create \ --yes onchain-router funding onchain-router balance onchain-router unlock onchain-router models onchain-router pricing ``` The setup command supplies every non-secret policy choice at once. The CLI still requests the new wallet passphrase twice through no-echo terminal input. Setup and unlock remain human-only actions. Fund only the wallet address you verify, on Base, with USDC. The public exact flow requires no Base ETH or token approval. A passphrase or import key must never appear in arguments, environment values, agent prompts, shell history, or support bundles. ## Make a request Save 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. ```bash onchain-router chat \ --model gemini-3.6-flash --max-output-tokens 1024 \ --idempotency-key "${REQUEST_ID:?Set a persisted request ID}" \ --json < request.json ``` Paid 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. When request JSON is piped on standard input and confirmation is enabled, the CLI opens the controlling terminal for the yes/no decision. The JSON and human confirmation therefore cannot consume the same stream. The normal exact flow signs through official x402 primitives and needs no approval transaction. Messages, 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](https://onchainrouter.dev/docs/endpoints) and command help for required options. ## Recover and finish ```bash onchain-router receipt "$REQUEST_ID" onchain-router status onchain-router lock ``` Keep the same body 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. --- # Production environment and funding Canonical source: [https://onchainrouter.dev/docs/environments](https://onchainrouter.dev/docs/environments) Last reviewed: 2026-08-21. ## Base mainnet - Network: `eip155:8453` - Payment asset: United States Dollar Coin (USDC) on Base, contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` - Scheme: x402 v2 `exact` with EIP-3009 - Capabilities: enabled Gemini text and image models plus the available ElevenLabs MP3 speech models in `GET /v1/models` - Recipient: `0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d` Any 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. ## Funding and wallet safety Fund 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. --- # Local MCP integration Canonical source: [https://onchainrouter.dev/docs/mcp](https://onchainrouter.dev/docs/mcp) Last reviewed: 2026-09-01. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. Use MCP when your host supports a local stdio server. This is not a hosted ChatGPT connector or an HTTP MCP endpoint. ## What the agent can do Nine 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. The 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. ## Install After human [CLI setup and unlock](https://onchainrouter.dev/docs/cli), install the public npm alpha and print its configuration: ```bash npm install --global @agenticfi/onchain-router-mcp@alpha onchain-router-mcp --print-config ``` Use the generated absolute command and arguments in your host's local stdio configuration. Do not add wallet secrets to that configuration. ## Requests and limits Choose 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. Transcriptions 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](https://onchainrouter.dev/docs/transcription). Return the output and verified receipt privately, with any media expiry. Treat all complete media and receipt capability URLs as secrets. See [agent contracts](https://onchainrouter.dev/docs/agents) for outcomes and tool boundaries. --- # Local OpenAI proxy Canonical source: [https://onchainrouter.dev/docs/proxy](https://onchainrouter.dev/docs/proxy) Last reviewed: 2026-09-01. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. The 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. ## Install After human [CLI setup and unlock](https://onchainrouter.dev/docs/cli), install and inspect the public npm alpha: ```bash npm install --global @agenticfi/onchain-router-proxy@alpha onchain-router-proxy --print-config onchain-router-proxy ``` Use 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. The proxy accepts only loopback requests with its local bearer. It has no arbitrary upstream target, wallet admin route, public listener, or browser CORS permission. ## Compatibility Chat Completions supports the tested OpenAI-style non-streaming shape. Messages, images, speech, transcription, models, and pricing are also available through the allowlist. Hosted 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. ## Retries and caching Disable 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. An 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](https://onchainrouter.dev/docs/caching). Unknown provider or settlement outcomes return a non-retryable conflict and require human review. The proxy is not a way to bypass runtime limits. --- # Make your first paid AI request Canonical source: [https://onchainrouter.dev/docs/quickstart](https://onchainrouter.dev/docs/quickstart) Last reviewed: 2026-09-04. 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](https://onchainrouter.dev/docs/installation) first; six npm packages are public under the `alpha` tag, OpenClaw and Hermes have public host-native GitHub alphas, and Python and the Agent Skill retain the source boundaries documented there. The optional browser workflow and its build availability are described in [Workbench](https://onchainrouter.dev/docs/workbench). ## Recommended public-alpha path The package is public, but funded Buyer Runtime acceptance on a fresh external host remains pending. Start with a dedicated low-balance API wallet and review every local policy limit. Use 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. ```bash npm install --global @agenticfi/onchain-router-cli@alpha onchain-router setup onchain-router funding onchain-router policy show onchain-router unlock onchain-router models onchain-router pricing REQUEST_ID="$(node -p 'require("node:crypto").randomUUID()')" onchain-router chat "Explain x402 in two sentences." \ --model gemini-3.6-flash \ --max-output-tokens 256 \ --idempotency-key "$REQUEST_ID" onchain-router lock ``` Persist `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](https://onchainrouter.dev/docs/recipes) for Messages, images, speech, transcription, and direct no-spend inspection. ## 1. Prepare a dedicated wallet For 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. Never use a primary or highly funded wallet. ## 2. Choose what to call The 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](https://onchainrouter.dev/docs/endpoints), then use `GET /v1/models` to select a compatible model and `GET /v1/pricing` to inspect its current billing unit. Gemini 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. ## 3. Use an official x402 buyer Call 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. Coinbase 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. ## 4. Send production-shaped JSON Chat 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. ```json { "model": "gemini-3.6-flash", "messages": [ { "role": "user", "content": "Explain in two short sentences why the sky appears blue." } ], "max_tokens": 1024, "stream": false } ``` Preview 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. ## 5. Authorize and read the result Confirm the request-specific USDC authorization. The signature permits only the advertised exact transfer and never requires you to reveal your private key. Read the visible answer from: ```text choices[0].message.content ``` Then record the receipt ID, exact amount, normalized usage, and BaseScan transaction. Do not publish the prompt, completion, receipt access token, or payment payload. ## Common results - A `finish_reason` value of `"stop"` means the answer completed normally. - 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. - HTTP status 402 is the expected response before payment authorization. - An `empty_provider_response` error is not charged. The model used the available output budget without returning visible text. - If the provider or payment result is unknown, recover the existing request before starting a new one. --- # Portable Agent Skill Canonical source: [https://onchainrouter.dev/docs/agent-skill](https://onchainrouter.dev/docs/agent-skill) Last reviewed: 2026-09-01. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. The [Onchain Router Skill](https://onchainrouter.dev/skill/onchain-router/SKILL.md) is public MIT source in [AgenticFI/onchain-router-clients](https://github.com/AgenticFI/onchain-router-clients). It contains instructions and thin CLI bridge scripts and requires the matching public-alpha Buyer CLI. Downloading the instructions alone does not provide a payment runtime. ## How to use it Use a host that supports portable Agent Skills and local commands. Read [agent entry points](https://onchainrouter.dev/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. The 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. ## Safe request flow Read 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. Inline 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. Keep 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. --- # OpenClaw integration Canonical source: [https://onchainrouter.dev/docs/openclaw](https://onchainrouter.dev/docs/openclaw) Last reviewed: 2026-09-04. The [AgenticFI OpenClaw extension](https://github.com/AgenticFI/onchain-router-openclaw) `0.1.0` is a public MIT alpha with an immutable [GitHub release](https://github.com/AgenticFI/onchain-router-openclaw/releases/tag/v0.1.0). It is directly installable through OpenClaw's native Git plugin path. It is not yet a ClawHub listing or a production-qualified funded integration. ## What it adds - a native `onchain-router` provider with live policy-filtered chat models; - read-only tools for models, pricing, and voices; - bounded paid tools for images, MP3 speech, and MP3 transcription; - an authenticated `/onchain-router` command for redacted status, diagnostics, and recovery guidance; - one deterministic Buyer Runtime idempotency key across host retries of the same transport turn; - optional lifecycle management for the exact installed `@agenticfi/onchain-router-proxy@0.1.2` dependency. It 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. ## Requirements and install - Node.js `>=24.15.0 <25`; - OpenClaw `2026.8.1`; - macOS or Linux; - a Buyer Runtime profile created and unlocked by a human; - the exact proxy version declared by the extension. ```bash openclaw plugins install git:github.com/AgenticFI/onchain-router-openclaw@v0.1.0 --force openclaw plugins enable onchain-router --accept-capabilities openclaw plugins inspect onchain-router --runtime --json ``` `--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. ## Local trust boundary The 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. Native 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. The 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/AgenticFI/onchain-router-openclaw). A funded OpenClaw request remains an explicit operator acceptance step because it spends from the operator's Buyer Runtime wallet. --- # Hermes Agent integration Canonical source: [https://onchainrouter.dev/docs/hermes](https://onchainrouter.dev/docs/hermes) Last reviewed: 2026-09-04. The [AgenticFI Hermes plugin](https://github.com/AgenticFI/onchain-router-hermes) `0.1.0` is a public MIT alpha with an immutable [GitHub release](https://github.com/AgenticFI/onchain-router-hermes/releases/tag/v0.1.0). It is directly installable through Hermes' native GitHub plugin path. It is not a PyPI release or a production-qualified funded integration; PyPI is not required for the native installation. ## What it adds - native provider `onchain-router` for chat with one explicit live model; - free discovery tools and commands for models, prices, and voices; - bounded paid tools for images, MP3 speech, and MP3 transcription; - redacted status and diagnostics commands; - explicit recovery guidance and stable idempotency across host retries; - human-run setup, update, status, stop, and client-removal commands. The 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. ## Requirements and install - Python `>=3.11,<3.14`; - Hermes Agent `0.21.0`; - Node.js 20.18 or newer and npm; - macOS or Linux; - a Buyer Runtime profile created and unlocked by a human. ```bash hermes plugins install AgenticFI/onchain-router-hermes --enable hermes plugins doctor onchain-router --ci hermes onchain-router setup ``` Hermes records the installed Git commit. For a reproducible install, append `--ref c9a5ea5e73003c4286a13b0aa81e99259e0a9b14` 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. ## Local trust boundary The plugin uses exact pinned versions of the AgenticFI 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. The current public alpha pins both `@agenticfi/onchain-router-cli@0.1.2` and `@agenticfi/onchain-router-proxy@0.1.2`. Native 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. The complete setup lifecycle, media examples, retention disclosure, tool list, and troubleshooting are in the [public repository](https://github.com/AgenticFI/onchain-router-hermes). A funded Hermes request remains an explicit operator acceptance step because it spends from the operator's Buyer Runtime wallet. --- # Direct x402 API Canonical source: [https://onchainrouter.dev/docs/direct-api](https://onchainrouter.dev/docs/direct-api) Last reviewed: 2026-08-31. 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. ## Discover first ```bash curl https://onchainrouter.dev/v1/models curl https://onchainrouter.dev/v1/pricing curl https://onchainrouter.dev/openapi.json ``` These GET requests do not sign or spend USDC. Use [voices](https://onchainrouter.dev/v1/audio/voices) before speech generation. [Balance](https://onchainrouter.dev/docs/api/balance) is a public address query, not wallet authentication. ## Request, authorize, recover 1. Select a live model and save one stable idempotency key. 2. Send the exact request without payment to receive HTTP 402. 3. Validate network, official USDC asset, expected recipient, scheme, expiry, and exact amount against your local policy. 4. Use official x402 verification/signing primitives to authorize locally. Retry the identical effective body and key. 5. Save the result and verified receipt. A transport error after signing may require recovery, not a new payment. See [complete examples](https://onchainrouter.dev/docs/sdk-examples) for an unpaid challenge and [first request](https://onchainrouter.dev/docs/quickstart) for the payment checklist. The website never needs a private key. ## Payment and support surfaces Five 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. The 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. For exact fields and status codes, use [OpenAPI](https://onchainrouter.dev/openapi.json) and [endpoint reference](https://onchainrouter.dev/docs/endpoints). --- # Protect the wallet that pays for requests Canonical source: [https://onchainrouter.dev/docs/wallet-security](https://onchainrouter.dev/docs/wallet-security) Last reviewed: 2026-09-02. Your wallet signs the payment authorization on your device. Onchain Router receives the authorization but never receives your seed phrase or wallet private key. ## Local Buyer Runtime setup > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. After [installing the CLI](https://onchainrouter.dev/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. Use 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. The optional [browser Workbench](https://onchainrouter.dev/docs/workbench) uses an injected wallet instead. Connecting a browser wallet does not unlock the local runtime, and the browser's in-memory session is not its durable ledger. ## Safe mainnet wallet policy - Create a new account used only for Onchain Router. - Hold only the USDC needed for the next few requests; ordinary exact payments need no Base ETH gas. - For an old `upto` profile, migrate with `onchain-router policy set --scheme exact`. Legacy Permit2 commands remain available only for explicit compatibility and limit any allowance to the reviewed daily policy. - Set a hard limit for each request in atomic USDC units. `1000000` means `1.000000` USDC; choose your own appropriate limit. The live server may enforce a lower limit independently. - Set a separate session cap for autonomous use. - Allow only Base mainnet (`eip155:8453`), official Base USDC, and the expected recipient. - 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. - Disconnect or revoke site access when testing is complete. ## Before every signature Read 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. Do not infer payment terms from this page. Runtime terms and the current public catalog are authoritative. ## Switching wallet accounts In 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. --- # Browser Workbench Canonical source: [https://onchainrouter.dev/docs/workbench](https://onchainrouter.dev/docs/workbench) Last reviewed: 2026-09-02. [Open Workbench](https://onchainrouter.dev/workbench/). This build includes the browser UI. A read-only local preview cannot submit paid requests; use only an explicitly enabled deployment for payments. ## What it covers The 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. Choose 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. ## Wallet boundary The 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. Read-only development previews reject paid requests. Connecting a wallet does not make a read-only preview a payment environment. ## Results and recovery Inspect 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. Before 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. Closing 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. HTTP 402 is normal before authorization. After signing, never assume a timeout or 503 means nothing happened. Follow [errors and recovery](https://onchainrouter.dev/docs/errors-retries), and do not preview a new payment to recover an ambiguous one. The 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. The hosted page sends its signed follow-up through a bounded same-origin Workbench relay so browser custom-header transport cannot drop the authorization. The relay reconstructs the unchanged standard x402 request only on the private API hop and does not persist or log the signature. Direct API clients still use the official `PAYMENT-SIGNATURE` header. --- # Choose an agent entry point Canonical source: [https://onchainrouter.dev/docs/agents](https://onchainrouter.dev/docs/agents) Last reviewed: 2026-09-04. > Public alpha: six AgenticFI client packages are available on npm at version `0.1.2` under the alpha tag. OpenClaw and Hermes version `0.1.0` are public MIT alphas installable through their hosts' native GitHub installers. 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. ## Choose one primary path | Use | Choose it when | Current capability categories | Authority boundary | | ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | All 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. ## One shared contract - Canonical origin: `https://onchainrouter.dev`. - Network: Base mainnet `eip155:8453`. - Asset: official Base USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. - Models and prices: always read `/v1/models` and `/v1/pricing`; never copy a price or assume an alias remains enabled. - Paid endpoints: `/v1/chat/completions`, `/v1/messages`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`. - Example text model at generation time: `gemini-3.6-flash`. Confirm it against live discovery before a call. - Idempotency: create one stable key before the unpaid request and retain it through signing, recovery, and receipt lookup. - 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. - Success: return `ok`, `outcome`, `idempotencyKey`, `body`, `receipt`, `payment`. - Failure: return `ok`, `outcome`, `retry`, `idempotencyKey`, `message`, `reference` without secret-bearing diagnostics. Every 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. The 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. ## Human-owned setup The following actions are human-only and must run in a direct terminal: - wallet create or import - wallet unlock - funding - legacy Permit2 profile migration - policy widening - confirmation-policy changes - backup or restore - key rotation - wallet export or exit Do 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. Installed-client and public-source entry points are: | Entry point | Artifact | Inspect or start | | ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------ | | Focused MCP | `@agenticfi/onchain-router-mcp` | `onchain-router-mcp --print-config` | | Loopback proxy | `@agenticfi/onchain-router-proxy` | `onchain-router-proxy --print-config` | | TypeScript or Python SDK | `@agenticfi/onchain-router or onchain-router` | `OnchainRouterBuyer.connect() or OnchainRouterBuyer()` | | Buyer CLI | `@agenticfi/onchain-router-cli` | `onchain-router help` | | Portable Agent Skill | `skills/onchain-router` | `node scripts/models.mjs` | | OpenClaw extension | `AgenticFI/onchain-router-openclaw` | `openclaw plugins install git:github.com/AgenticFI/onchain-router-openclaw@v0.1.0 --force` | | Hermes Agent plugin | `AgenticFI/onchain-router-hermes` | `hermes plugins install AgenticFI/onchain-router-hermes --enable` | Install npm packages only from the `@agenticfi` scope with the `alpha` tag. Install OpenClaw and Hermes only from the exact AgenticFI GitHub repositories and pinned release references shown above. Host-native Git installability is independent of ClawHub or PyPI listing status. ## Stable outcomes | Outcome | Retry directive | | ------------------------------- | ---------------------------- | | `PaymentPolicyRejected` | `do_not_retry` | | `UnsupportedNetwork` | `do_not_retry` | | `UnexpectedAsset` | `do_not_retry` | | `UnexpectedRecipient` | `do_not_retry` | | `AuthorizationAboveLocalCap` | `do_not_retry` | | `InsufficientFunds` | `retry_unpaid_request` | | `Permit2ApprovalRequired` | `do_not_retry` | | `Permit2ApprovalOutcomeUnknown` | `human_review` | | `PaymentVerificationRejected` | `retry_unpaid_request` | | `ProviderOutcomeUnknown` | `human_review` | | `SettlementOutcomeUnknown` | `human_review` | | `IdempotencyConflict` | `do_not_retry` | | `ResultRecoveryExpired` | `do_not_retry` | | `ReceiptVerificationFailed` | `retry_same_idempotency_key` | | `WalletLocked` | `unlock_wallet` | | `RuntimeUnavailable` | `retry_same_idempotency_key` | `ProviderOutcomeUnknown` 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. ## Receipt and output Return 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. ## Public API discovery Read `/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. The portable skill source is available at `/skill/onchain-router/SKILL.md` and requires the public-alpha Buyer CLI. The `llms.txt` convention and Agent Skills are discovery and workflow mechanisms, not access-control or wallet-authority systems. --- # TypeScript, CLI, MCP & HTTP examples Canonical source: [https://onchainrouter.dev/docs/sdk-examples](https://onchainrouter.dev/docs/sdk-examples) Last reviewed: 2026-09-01. > AgenticFI client packages version 0.1.2 are public MIT-licensed alphas on npm under the alpha tag. OpenClaw and Hermes version 0.1.0 are public MIT alphas installable through their hosts’ native GitHub installers. The Python SDK remains source-only; ClawHub and PyPI listings are not claimed. Verify the package scope, `alpha` tag, version, and repository before installation. ## Before you run a client example Follow [installation](https://onchainrouter.dev/docs/installation), then complete [human CLI setup and unlock](https://onchainrouter.dev/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. The TypeScript SDK, CLI, and MCP server are public npm alphas. The Python SDK remains a source-only bounded subprocess bridge to the matching CLI; it has no independent wallet or signer. For a task-first request and response guide, including images and both speech directions, use [Agent task recipes](https://onchainrouter.dev/docs/recipes). For third-party wallet and discovery status, use [Wallet and agent compatibility](https://onchainrouter.dev/docs/wallet-compatibility). Set `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. ## TypeScript Public npm alpha · requires human setup and an unlocked Buyer Runtime. ```ts npm install @agenticfi/onchain-router@alpha import { OnchainRouterBuyer } from '@agenticfi/onchain-router'; const requestKey = process.env.REQUEST_ID; if (!requestKey) throw new Error('Set a persisted REQUEST_ID'); const buyer = await OnchainRouterBuyer.connect(); try { const result = await buyer.chat({ "model": "gemini-3.6-flash", "messages": [ { "role": "user", "content": "Explain x402 in one sentence." } ], "max_tokens": 128, "stream": false }, requestKey); if (!result.ok) throw new Error(`${result.outcome}: ${result.message}`); console.log(result.body); console.log(result.receipt.id, result.payment.actualAtomic); } finally { buyer.close(); } ``` ## CLI Public npm alpha · setup, unlock, and policy changes stay human-only. ```bash npm install --global @agenticfi/onchain-router-cli@alpha onchain-router setup onchain-router policy show onchain-router unlock onchain-router models ``` ## MCP Public npm alpha · prints a local stdio configuration without exposing wallet secrets. ```bash npm install --global @agenticfi/onchain-router-mcp@alpha onchain-router-mcp --print-config ``` ## HTTP Public API · this plain request inspects the unpaid challenge and does not sign or spend USDC. ```bash request_key="$(node -p 'require("node:crypto").randomUUID()')" curl -i https://onchainrouter.dev/v1/chat/completions \ -H 'content-type: application/json' \ -H "x-idempotency-key: $request_key" \ --data '{"model":"gemini-3.6-flash","messages":[{"role":"user","content":"Explain x402 in one sentence."}],"max_tokens":128,"stream":false}' ``` ## Read the result and recover TypeScript returns a discriminated result: `ok`, `outcome`, `idempotencyKey`, and either a result body, payment and verified receipt, or a safe retry directive. `ProviderOutcomeUnknown` 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. The examples do not print prompts, completions, signatures, receipt capabilities, or media URLs into diagnostics. Handle output inside your application. ## Other capabilities The same buyer exposes `messages`, `images`, `speech`, and `transcriptions`. Use each capability's documented request shape. - [Text formats](https://onchainrouter.dev/docs/text): OpenAI Chat Completions or Anthropic Messages. - [Images](https://onchainrouter.dev/docs/images): hosted URL or Base64 delivery; hosted URL expires after seven days. - [Speech](https://onchainrouter.dev/docs/speech): hosted MP3 JSON, not an OpenAI binary audio response. - [Transcription](https://onchainrouter.dev/docs/transcription): bounded MP3 and explicit retained-provider consent. Do not implement EIP-712, Permit2, payment signing, or settlement in application code. Buyer Runtime uses official x402 primitives. --- # Agent task recipes Canonical source: [https://onchainrouter.dev/docs/recipes](https://onchainrouter.dev/docs/recipes) Last reviewed: 2026-09-01. These 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. An 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. ## Answer a question with Chat Completions Use `POST /v1/chat/completions` when an application already uses OpenAI-shaped messages and choices. ```json { "model": "gemini-3.6-flash", "messages": [{ "role": "user", "content": "Explain x402 in two short sentences." }], "max_tokens": 256, "stream": false } ``` Read 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. ## Use the Anthropic Messages shape Use `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. ```json { "model": "gemini-3.6-flash", "system": "Answer concisely.", "messages": [{ "role": "user", "content": "Explain x402 in two short sentences." }], "max_tokens": 256, "stream": false } ``` Read text blocks from `content`. The payment and recovery rules are identical to Chat Completions. ## Generate one image Use `POST /v1/images/generations`. Select a model whose category is `image_generation`; supported sizes and aspect ratios are model-specific. ```json { "model": "gemini-3.1-flash-lite-image", "prompt": "A geometric blue bridge on a white background", "n": 1, "image_size": "1K", "aspect_ratio": "1:1", "response_format": "url" } ``` The 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. ## Generate speech Use `POST /v1/audio/speech`. Select a `text_to_speech` model and a public voice alias from `GET /v1/audio/voices`. ```json { "model": "elevenlabs/flash-v2.5", "input": "Hello from Onchain Router.", "voice": "reader", "response_format": "mp3", "speed": 1 } ``` 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. ## Transcribe speech Use `POST /v1/audio/transcriptions` with canonical Base64 JSON or multipart form data. For an agent-safe JSON call: ```json { "model": "elevenlabs/scribe-v2", "audio_base64": "BASE64_MP3_WITHOUT_A_DATA_URL_PREFIX", "file_format": "other", "response_format": "json" } ``` The 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. ## Change models safely Do 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. ## Inspect without spending This command sends no signature and cannot settle USDC: ```bash curl -i https://onchainrouter.dev/v1/chat/completions \ -H 'content-type: application/json' \ --data '{}' ``` Expect 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: ```bash GITHUB_SHA="$(git rev-parse HEAD)" pnpm agent:discovery-check \ --origin https://onchainrouter.dev \ --profile production ``` The validator never creates or sends a payment signature. It derives the checked-out commit and, when `GITHUB_SHA` is set, requires it to match that exact `HEAD`, so the report stays bound to reviewed source. A green result does not prove a paid settlement, provider response, wallet integration, or external marketplace indexing. ## Recover and verify On 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. --- # Wallet and agent compatibility Canonical source: [https://onchainrouter.dev/docs/wallet-compatibility](https://onchainrouter.dev/docs/wallet-compatibility) Last reviewed: 2026-09-03. 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. ## Current matrix | Buyer or discovery surface | Current status | What is still required | | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AgenticFI Buyer Runtime, CLI, TypeScript SDK, MCP, and proxy | Public npm alpha. 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. | | 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. | | [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. | | [x402scan](https://www.x402scan.com/resources/register) | The previous hostname was registered. The new `onchainrouter.dev` origin is not claimed as listed until its separate ownership and registration flow completes. | Register the new origin, verify ownership, confirm all nine resources, and record the resulting server page before measuring search rank. | | 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. | | 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. | | [Coinbase Bazaar discovery](https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d) | The recipient has prior merchant evidence, but the five new absolute resource URLs must be independently validated and indexed after the canonical-origin deployment. | Require `valid: true` and `simulation.outcome: "accepted"` for each new URL, then complete only explicitly approved paid calls and recheck metadata and ranking. | | 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. | | 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. | This 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. ## What every buyer must validate 1. The first valid unsigned request returns HTTP 402 and an official `PAYMENT-REQUIRED` header. 2. 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. 3. The exact request body and stable idempotency key are retained through signing and retry. 4. No provider work occurs before successful payment verification. 5. The final settled amount equals the signed exact amount. 6. A result is released only with durable settlement and receipt evidence. 7. Unknown provider or settlement outcomes enter recovery; they are never blindly retried. ## Inspection versus authorization Agents 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. ## Surface-specific no-spend checks Use each surface's own check rather than treating the repository validator as universal proof: ```bash npx -y @agentcash/discovery@latest discover https://onchainrouter.dev npx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/chat/completions npx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/messages npx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/images/generations npx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/audio/speech npx -y @agentcash/discovery@latest check https://onchainrouter.dev/v1/audio/transcriptions GITHUB_SHA="$(git rev-parse HEAD)" pnpm agent:discovery-check \ --origin https://onchainrouter.dev \ --profile production curl -sS -X POST https://api.cdp.coinbase.com/platform/v2/x402/validate \ -H 'content-type: application/json' \ -d '{"resource":"https://onchainrouter.dev/v1/chat/completions","method":"POST"}' ``` AgentCash `discover` accepts the API origin, while `check` requires one complete endpoint URL. The repository validator derives the checked-out commit and, when `GITHUB_SHA` is set, requires it to match that exact `HEAD`. This binds the saved report to the source under review. The Coinbase validation call is read-only and requires no API key. Continue only when its response contains `valid: true` and `simulation.outcome: "accepted"`; review every preflight failure and advisory before any funded call. Poncho and awal are buyer acceptance paths, not catalog validators. Coinbase Bazaar is a separate seller-indexing path: after an authorized CDP-facilitated settlement, decode and retain the sanitized `EXTENSION-RESPONSES` Bazaar result (`success`, `processing`, or `rejected`), then check catalog, semantic search, and merchant discovery for every canonical paid resource. Record validation, settlement-extension evidence, catalog, search, and merchant results separately. Each runtime challenge also supplies the x402 v2 ResourceInfo fields used by capable directories: `serviceName: "Onchain Router"`, an absolute public logo URL, a nonempty route description, JSON media type, and route-specific tags for chat, image generation, text-to-speech, or transcription. These hints improve machine classification but do not substitute for genuine independent buyer usage. The current x402scan registration and Coinbase validation results are external observations, not permanent guarantees; recheck them against the exact deployed release. ## Honest external validation sequence Run 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. Marketplace listing and search placement are external results. A successful payment does not by itself prove that x402scan or Coinbase Bazaar indexed the resource. --- # How authorization, charges, and receipts work Canonical source: [https://onchainrouter.dev/docs/payment-receipts](https://onchainrouter.dev/docs/payment-receipts) Last reviewed: 2026-09-03. 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. ## Pricing terms - **Exact request price:** the amount in the x402 challenge and EIP-3009 authorization. A successful request pays this amount. - **Text reserve:** the conservative input estimate plus 10% of requested `max_tokens`; it is priced before signing. - **Provider cost:** catalog rates multiplied by actual normalized token usage for text; the fixed image-output accounting floor plus any reported prompt or residual output usage for images. - **Service fee:** 0% during the launch promotion, recorded as zero integer basis points. - **Fixed successful-call fee:** `1000` atomic USDC units, or `0.001000` USDC. - **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. - **Text payment:** the calculated exact request price, including the applicable floor and fixed fee. - **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. Image token counts are optional upstream telemetry and do not affect the fixed image price. A zero image token count in a receipt means the provider compatibility layer did not report that field; it does not mean that image generation used no computation. The 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. The 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](https://onchainrouter.dev/v1/pricing) and the current 402 challenge rather than copying prices from a guide. ## Local client recovery Buyer Runtime retains a durable request ledger. Preserve the original key and use its receipt lookup or an explicitly permitted same-key retry. If the provider or settlement outcome is unknown, stop and seek human review. A browser reload does not reverse a payment, and the Workbench may lose its temporary session state. See [recovery](https://onchainrouter.dev/docs/errors-retries). ## Receipt evidence The 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. The durable receipt contains the public model name, normalized usage, pricing policy, signed exact amount, settled amount (equal to that signed price for a successful exact payment), payment network, payment asset, and transaction reference. It never contains the prompt, model answer, wallet key, provider credential, raw signature, complete payment payload, or receipt token. The x402 transaction proves that payment occurred. The usage section is an Onchain Router record, not a separate provider-signed proof. Text usage is normalized from mandatory provider telemetry; image usage retains optional provider telemetry and uses zero when a field was not reported. --- # Text generation & Messages Canonical source: [https://onchainrouter.dev/docs/text](https://onchainrouter.dev/docs/text) Last reviewed: 2026-08-31. ## Choose a format, not a different provider `POST /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. Choose 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. ## Models and parameters Read [models](https://onchainrouter.dev/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. Start with [Chat Completions](https://onchainrouter.dev/docs/api/chat-completions) or [Messages](https://onchainrouter.dev/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. ## Truncation and recovery A `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. Lost 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. --- # Generate images Canonical source: [https://onchainrouter.dev/docs/images](https://onchainrouter.dev/docs/images) Last reviewed: 2026-08-31. Use `POST /v1/images/generations` with a model from the `image_generation` category. Read [the live catalog](https://onchainrouter.dev/v1/models) before choosing a size or aspect ratio; only advertised options are accepted. ## Request and price The 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. The 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. ## Output and retention Default 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. Base64 output is available where the route contract supports it. Do not log image bodies or complete hosted URLs. See [request schema and example](https://onchainrouter.dev/docs/api/image-generations) for exact fields. The current scope is image generation, not image editing or video. All adapters still use the same Buyer Runtime payment and recovery rules. --- # Understand errors and retry safely Canonical source: [https://onchainrouter.dev/docs/errors-retries](https://onchainrouter.dev/docs/errors-retries) Last reviewed: 2026-08-11. An idempotency key identifies one logical request. Reusing the same key with the same request lets Onchain Router recover the existing result without calling the model or charging the wallet again. ## Safe to correct and retry - Invalid JSON, model, or output ceiling: fix the request and obtain a new quote. - Hypertext Transfer Protocol (HTTP) status 402: check the payment terms, sign, and retry the identical body. - Expired authorization: obtain a new quote and authorization. - `empty_provider_response`: increase `max_tokens`, obtain a fresh quote, and retry; the failed attempt is not settled. - Definite provider rejection before acceptance: correct the cause and retry with a new idempotency key. - `wallet_request_cap_exceeded`: lower the requested output ceiling and obtain a new quote, or ask the operator to review the policy. ## Do not retry blindly - `provider_outcome_unknown` - `settlement_unknown` - lost connection after wallet authorization - timeout after the provider or facilitator may have accepted work Retry the same request with the same idempotency key to recover the stored state. Do not create a new request until the existing operation is known to have failed definitively. ## Idempotency rules The first-party clients send `x-idempotency-key`, and x402 payment identifiers may provide an additional protocol identity. Repeating an identical request returns the original result or stored state without a second model call or charge. Reusing the key with a changed request returns HTTP status 409. Redis loss does not weaken these guarantees because PostgreSQL owns the execution lease and authorization fingerprint. --- # Generate speech Canonical source: [https://onchainrouter.dev/docs/speech](https://onchainrouter.dev/docs/speech) Last reviewed: 2026-08-31. Use `POST /v1/audio/speech`. Discover the `text_to_speech` model in [models](https://onchainrouter.dev/v1/models) and select a voice from [voices](https://onchainrouter.dev/v1/audio/voices). The current provider is ElevenLabs Flash v2.5. ## Input and output Supply `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. The 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. ## Pricing and privacy Speech 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. Text-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. See [full speech reference](https://onchainrouter.dev/docs/api/audio-speech) and [privacy](https://onchainrouter.dev/docs/privacy). --- # Transcribe speech Canonical source: [https://onchainrouter.dev/docs/transcription](https://onchainrouter.dev/docs/transcription) Last reviewed: 2026-08-31. Use `POST /v1/audio/transcriptions` with the `speech_to_text` model from [discovery](https://onchainrouter.dev/v1/models). The current provider is ElevenLabs Scribe v2. > 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. ## Choose a transport The 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. The 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. Our 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. ## Billing and output The response contains transcript text and validated `usage.input_audio_ms`. Published duration pricing uses a billing quantum; inspect [live pricing](https://onchainrouter.dev/v1/pricing), not a guess from the filename. See [API reference](https://onchainrouter.dev/docs/api/audio-transcriptions). Local encrypted staging is deleted after definite outcomes where possible. Ambiguous outcomes and physical storage deletion have separate expiry behavior described in [privacy](https://onchainrouter.dev/docs/privacy). Local deletion does not delete the provider's copy. --- # Local response caching Canonical source: [https://onchainrouter.dev/docs/caching](https://onchainrouter.dev/docs/caching) Last reviewed: 2026-09-01. Caching is implemented in the public-alpha 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. ## Eligible text only The 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. Tools, 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. ## Cache hit meaning `x-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. ## Control and recovery - An explicit `Idempotency-Key` always bypasses the cache. Keep stable keys for requests that need durable recovery. - `Cache-Control: no-cache` requests a fresh answer. - `Cache-Control: no-store`, `cache: false`, or `no_cache: true` bypasses cache reads and writes. - Proxy `--no-cache` disables it for the process. Do not omit a recovery key just to get cache hits. Simultaneous fresh misses may each execute; this is not request coalescing. See [local proxy](https://onchainrouter.dev/docs/proxy). --- # How request content is stored and deleted Canonical source: [https://onchainrouter.dev/docs/privacy](https://onchainrouter.dev/docs/privacy) Last reviewed: 2026-08-21. 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. ## Retained - verified text from the prompt, limited by the maximum request size; - an encrypted and redacted review excerpt together with the review decision; - the deletion date and an audit record for each individual access. Detected 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. ## Not placed in telemetry or receipts - prompts or completions; - raw wallet signatures; - complete payment payloads; - receipt access tokens; - wallet private keys; - provider credentials; - cloud project identifiers. Completed 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. Generated images use a separate encrypted private-media store. Every image response includes `url_retention_days: 7` and an exact `url_expires_at` timestamp. The capability URL stops serving the image at that timestamp. Azure lifecycle management permanently deletes the encrypted object after it becomes seven days old; the physical deletion completes on Azure's next lifecycle scan. Download the image before expiration if it must be kept longer. Text-to-speech requests use ElevenLabs Zero Retention Mode. Speech-to-text uses ElevenLabs standard retained mode: ElevenLabs receives the uploaded audio and transcript output and may retain both under the applicable agreement, account settings, and privacy policy. Onchain Router encrypts STT staging only after payment authorization and attempts to delete its local copy after every definite provider success or failure. After an ambiguous provider outcome, 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 by Onchain Router does not delete data held by ElevenLabs. ## Processing and deletion Google Vertex AI processes requests to generate text or images. ElevenLabs processes text-to-speech and speech-to-text requests under the route-specific retention behavior above. Coinbase Developer Platform verifies and settles x402 payments, and Base records the public transaction. Each service receives only the information needed for its role. Encrypted prompt-review records and generated images follow their separate seven-day deletion controls. An authorized operator can review only one prompt-review record at a time, and every access is audited. ## Public alpha boundaries This page describes the implemented data flow and retention behavior for the guarded public alpha. The current public speech scope accepts MP3 through ElevenLabs Flash v2.5 text to speech and Scribe v2 speech to text. In particular, do not submit personal, confidential, regulated, biometric, or third-party audio to speech-to-text. For every route, submit content only when you have the right to process it through the named providers and public-chain payment flow. --- # Product changes and model retirement policy Canonical source: [https://onchainrouter.dev/docs/changelog](https://onchainrouter.dev/docs/changelog) Last reviewed: 2026-09-04. ## 2026-09-04 — OpenClaw and Hermes GitHub alphas - Published immutable MIT `v0.1.0` GitHub releases for the OpenClaw and Hermes adapters after their repository CI and release workflows passed. - Added native host install paths: OpenClaw's pinned external-Git plugin command and Hermes' GitHub plugin command, with the exact Hermes release commit available for reproducible installs. - Published built OpenClaw, Hermes wheel, and Hermes source-distribution assets with recorded SHA-256 digests. - Kept ClawHub listing, PyPI publication, funded host acceptance, and general availability as separate unverified states. The adapters still delegate all wallet and payment authority to the local Buyer Runtime. - Corrected the AgentCash no-spend instructions: discovery accepts the API origin, while compatibility checks require a complete route URL. ## 2026-09-03 — Branded x402 resource discovery - Added the stable Onchain Router service name, public mark, and route-specific search tags to the x402 v2 ResourceInfo for all five paid endpoints. - Kept the official Coinbase Bazaar input/output schemas on every route and extended the no-spend 25-probe validator to fail on missing, incorrect, or cross-route discovery metadata. - Documented x402scan ownership registration and Coinbase validation/indexing as separate external evidence; this release does not create a signature, payment, ranking, or directory claim. - After protected deployment, registered the canonical origin on x402scan, confirmed its public nine-resource server page, verified AgentCash OpenAPI discovery, and observed all five Coinbase routes as active with `valid: true` and `simulation.outcome: "accepted"`. Funded per-route refresh and independent-buyer search ranking remain separate evidence. ## 2026-09-03 — AgenticFI npm alpha 0.1.2 - Published all six MIT AgenticFI client packages as npm alpha `0.1.2` from the public client repository with provenance. - Verified a clean isolated installation of all six packages, `0.1.2` CLI/MCP/proxy binaries, library imports, 78 registry signatures, and 35 attestations. - Updated the OpenClaw and Hermes source adapters to pin the corrected `0.1.2` proxy and CLI dependencies while retaining their independent `0.1.0` source-alpha versions. ## 2026-09-03 — Exact Base USDC payments - Simplified all five paid routes to one official x402 v2 `exact` EIP-3009 authorization. Ordinary requests need Base USDC only—no Base ETH and no token approval. - Fixed each text request's price from a conservative input estimate plus 10% of requested output, the published minimum and fixed fee, and the 0% service-fee promotion. Media keeps its cataloged request-specific price. - Kept provider-reported usage in durable receipts and cost controls while preserving payment-first execution, idempotency, recovery, and result-settlement-receipt ordering. - New Buyer Runtime profiles use exact automatically. Existing `upto` profiles remain readable and can migrate only through an authenticated `policy set --scheme exact` action. ## 2026-09-03 — Explicit buyer-funded Permit2 approval - Removed the unsupported gas-sponsorship declaration from every paid challenge. Coinbase does not pay or reimburse the buyer's approval gas. - Added an explicit canonical Permit2 approval step to the Buyer Runtime, CLI, SDK, and browser workbench. The CLI bounds approval to the reviewed daily policy; the workbench bounds it to the verified request maximum. - Added a pre-signing allowance check so a missing approval fails before an x402 payment signature, provider call, settlement, or receipt. ## 2026-09-02 — Buyer CLI first-use payment correction - Gave the short-lived Buyer Runtime signer a read-only Base client so the official x402 `upto` implementation can attach the server-advertised EIP-2612 permit for a first-use wallet with zero Permit2 allowance. No payment cryptography was reimplemented. - Added one-command setup flags for models, agent identity, all four USDC budgets, output-token limits, confirmation policy, and wallet mode. Private keys, seed phrases, and passphrases remain no-echo terminal-only inputs. - Separated piped request JSON from human authorization by reading confirmations from the controlling terminal, and surfaced only safe token-shaped rejection codes from the updated official payment header. - Added first-wallet, payment-error, controlling-terminal, one-command setup, and secret-flag regression coverage. This source correction does not publish a package, deploy production, sign a production request, or spend USDC. - A proposed facilitator-sponsored approval path was shipped in source but disproved by funded production verification and superseded by the 2026-09-03 correction above. ## 2026-09-01 — strict inspection and independent discovery evidence - Limited inspection `402` responses to absent, required-root-field-incomplete, or syntactically malformed unsigned JSON. Complete unsupported models, options, media, and content types now fail with `400/415` before a payment challenge or provider work. - Bound the no-spend validator to the exact production origin, network, USDC asset, recipient, canonical URL, positive nonzero facilitator address, route timeout, inspection header, and response-body marker, and reject malformed or noncanonical challenge encoding. - Labeled client-family funnel data as caller-claimed and carried the same allowlisted dimension through every stage from discovery to durable receipt and response release. - Separated AgentCash discovery, Poncho acceptance, awal acceptance, and Coinbase Bazaar indexing; corrected public npm alpha documentation and portable request-key examples. - Restored the approved static Buyer Runtime hero. This corrective source release does not deploy production, use a wallet, spend USDC, or change any marketplace. ## 2026-09-01 — payment-first agent discovery - Added official x402 inspection challenges for unsigned empty, incomplete, and malformed JSON on all five paid routes. Inspection responses are clearly marked and must not be signed; valid bodies still receive request-specific maxima. - Kept signed invalid requests, oversized bodies, and malformed media fail-closed before payment verification, provider execution, settlement, or receipt creation. - Added task recipes, an honest wallet/client compatibility matrix, and a 15-probe no-spend validator for Chat, Messages, Images, Text to Speech, and Speech to Text. - Added privacy-safe aggregate counters from discovery through durable receipt and response release. Telemetry stores only allowlisted client families and route/stage labels, never caller identifiers or request/payment content. - Reconciled package READMEs with the recorded public npm alpha while preserving this backend monorepo's non-publishable workspace manifests. No deployment, paid canary, or marketplace submission is performed by this change. ## 2026-09-01 — public client and platform update - Added task-oriented guides for Buyer Runtime, CLI, TypeScript/Python, local MCP, local OpenAI proxy, Agent Skill, and browser Workbench, with explicit public-alpha availability. - Reconciled the website with the initial public npm alpha and MIT client, OpenClaw, and Hermes repositories. - Rebuilt the landing page around controlled agent spending, live capabilities, exact integration status, install commands, and verifiable source links. - Reorganized text, image, speech, and transcription documentation around what you want to build. - Replaced outdated payment-wrapper snippets and clarified fees, media expiry, recovery, local caching, and speech transport differences. - Added a product publication manifest and artifact-backed Workbench links. This documentation update does not itself publish client packages or deploy a new payment service. ## 2026-08-21 - Published the exact five paid AI endpoints and four free discovery endpoints on the homepage, endpoint overview, `llms.txt`, complete agent corpus, sitemap, and portable Agent Skill. - Deployed and indexed the guarded Flash v2.5/Scribe v2 MP3 speech scope after exact-build dark activation, one non-retried provider/storage qualification, and public no-spend parity checks. x402scan now resolves all nine public resources; the release automation did not spend USDC. - Added canonical Base64 JSON input to the existing speech-to-text endpoint while retaining the standard multipart upload. Both forms decode and inspect the same bounded MP3 bytes before any payment challenge, provider call, or settlement. - Published the JSON schema and a valid unpaid probe example so JSON-only agent directories can verify and list speech to text without adding another public endpoint. ## 2026-08-19 - Prepared the guarded speech catalog with `elevenlabs/flash-v2.5` for MP3 text to speech and `elevenlabs/scribe-v2` for MP3 speech to text. Multilingual TTS and every other audio format remain unavailable until their qualification gates pass. - Corrected the generated TTS guide to use the actual `expires_at` response field and added a complete multipart STT request example that preserves the body across the unpaid and paid calls. - Updated OpenAPI, pricing, x402 discovery, the portable Agent Skill, privacy language, and model documentation to describe measured speech usage and ElevenLabs' route-specific retention modes. - Clarified that ambiguous encrypted STT staging becomes inaccessible at its one-hour logical expiry, while physical deletion can complete later through Azure storage lifecycle management. ## 2026-08-14 - Matched Gemini 3.1 Flash-Lite Image's fixed-1K Vertex contract by retaining the selected aspect ratio but omitting the redundant private provider `imageSize` field. Public requests still select and receive a validated 1K image at the same $0.035 promotional total. - Corrected the private Vertex `generateContent` adapter so image size and aspect ratio use its official `generationConfig.imageConfig` fields. The public image endpoint and request format do not change. - Kept the service dark until the corrected immutable build passes one non-retried Flash-Lite provider and encrypted-storage qualification. No USDC is used by that qualification. - Kept text-to-speech in ElevenLabs Zero Retention Mode and changed speech-to-text to the provider's standard retained mode after the protected Scribe v2 qualification confirmed that STT ZRM was unavailable for the production account. Onchain Router's encrypted STT staging is still deleted after a definite result, while ElevenLabs may retain audio and transcripts under its own policy. - Kept every speech model and voice dark until the revised adapter passes one new non-retried qualification and the remaining media, privacy, and release gates are complete. ## 2026-08-13 - Selected `gemini-3.1-flash-lite-image` as the guarded Base-mainnet image model at 1K/1:1 after the newer immutable Flash Image builds failed returned-aspect validation. The endpoint remains `POST /v1/images/generations`; Flash Image and Pro Image remain dark. - Set the promotional successful-image total to $0.035: $0.034 catalog-fixed provider image price plus the existing $0.001 successful-call fee and 0% service fee. - Kept the public service dark until this exact Flash-Lite build passes its one-shot provider and encrypted-storage qualification. That qualification uses provider credit and no USDC. ## 2026-08-12 - Added provider-neutral `POST /v1/images/generations` with the first Gemini image model, one 1024×1024 image per request, OpenAI-compatible URL or Base64 delivery, and a fixed $0.068 successful-call price during the 0% service fee launch promotion. - Added repository support for model-specific `image_size` and `aspect_ratio`, with 1K/1:1 defaults and exact integer price tiers. Additional Flash specifications plus Gemini 3.1 Flash-Lite Image and Gemini 3 Pro Image are enabled only for non-production qualification; the Base mainnet catalog remains on its approved Flash 1K/1:1 route until expansion gates pass. - Added private AES-256-GCM encrypted image storage and capability URLs. Every response reports `url_retention_days: 7` and the exact `url_expires_at`; URLs stop serving at expiration and Azure lifecycle management deletes the encrypted object after seven days. - Preserved the financial ordering for images: payment authorization is verified and durable before generation, while settlement occurs only after the image and result are durable. Known failed generations are not charged. - Updated the durable product description from an LLM-only router to an AI model router so the brand remains stable as image, video, and audio capabilities are added. - 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. - Organized `/v1/models` around available capability categories and endpoint compatibility. Text and image generation are now available; video, speech-to-text, and text-to-speech categories will appear only when those capabilities are released. - Added a readable unpaid-402 JSON explanation while retaining the official `PAYMENT-REQUIRED` header as the authoritative payment challenge. - 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. - 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. - 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. - Activated a catalog-versioned 0% service fee launch promotion across production billing, pricing pages, endpoint descriptions, OpenAPI, model discovery, quotes, and receipts. - Corrected discovery's minimum successful price to include both the $0.001 minimum usage charge and the separate $0.001 fixed successful-call fee. - Simplified the local production buyer so it connects directly to the public endpoint without the retired dark-release canary credential. - 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. ## 2026-08-11 - 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. - 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. - 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. - 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. - Reworked the website into a wider editorial layout that uses large screens more effectively. - Reduced heading sizes across the home page, documentation, model catalog, pricing, status, and legal pages. - 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. - Applied the same font to the wordmark, navigation, and Base Mainnet label, and refreshed search as a modern command palette. - Added content-versioned stylesheet and script URLs so a browser cannot combine updated page markup with stale interface styles. - 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. - 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. - 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. - Added local browser checks for wide desktop, laptop, tablet, and mobile layouts. This local review does not publish or activate the paid service. ## 2026-08-10 - Published the first custom single-origin website and documentation build. - Added HTML, per-page Markdown, `llms.txt`, `llms-full.txt`, OpenAPI, sanitized catalog, and Agent Skill surfaces. - Set the current paid-inference minimum to `1000` atomic USDC (`0.001000` USDC). - Qualified the initial Gemini text candidates before selecting the production catalog. - Added explicit handling for reasoning-token output ceilings, empty visible responses, actual settlement, and durable receipts. - 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. - Removed payer registration and payer allowlisting; every facilitator-verified wallet may purchase under the same limits. - Kept automated payment conformance fixtures outside the documented production environment. - Approved seven GA Gemini text aliases for mainnet-alpha routing. The `gemini-3.1-pro-preview` route remains disabled on mainnet. - Added fail-closed production configuration, a one-origin site/API deployment, public per-receipt capabilities, a least-privilege provider federation role, and a separately approved production infrastructure workflow. Synthetic reconciliation is now forbidden in production. - Revalidated the public catalog against current Google model and pricing sources, including the 65,536-token output limit for `gemini-3.1-flash-lite`. - Expanded the privacy and service-terms release candidates and added automated checks for stale test/private-alpha language, operator-only configuration, enabled-model count, and legal sections. ## Deprecation policy Model 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. Clients 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. The 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. --- # Models and pricing Canonical source: [https://onchainrouter.dev/models](https://onchainrouter.dev/models) Catalog 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. ## Available categories - **Text generation** (`text_generation`): `POST /v1/chat/completions` (openai), `POST /v1/messages` (anthropic) - **Image generation** (`image_generation`): `POST /v1/images/generations` (openai) - **Text to speech** (`text_to_speech`): `POST /v1/audio/speech` (openai-shaped) - **Speech to text** (`speech_to_text`): `POST /v1/audio/transcriptions` (openai) ## Available models | Model | Capability | Availability | Published price | Delivery and limit | |---|---|---|---|---| | `gemini-3.6-flash` | Text generation | ga | $1.5 input · $7.5 output per 1M tokens | 65,536 maximum output tokens | | `gemini-3.5-flash-lite` | Text generation | ga | $0.3 input · $2.5 output per 1M tokens | 65,536 maximum output tokens | | `gemini-3.5-flash` | Text generation | ga | $1.5 input · $9 output per 1M tokens | 65,536 maximum output tokens | | `gemini-3.1-flash-lite` | Text generation | ga | $0.25 input · $1.5 output per 1M tokens | 65,536 maximum output tokens | | `gemini-3.1-flash-lite-image` | Image generation | ga | 1K (default) $0.035000 | One image · 1 aspect ratios · hosted URL 7 days · optional Base64 | | `gemini-2.5-flash` | Text generation | ga | $0.3 input · $2.5 output per 1M tokens | 65,536 maximum output tokens | | `gemini-2.5-pro` | Text generation | ga | $1.25 input · $10 output per 1M tokens | 65,536 maximum output tokens | | `gemini-2.5-flash-lite` | Text generation | ga | $0.1 input · $0.4 output per 1M tokens | 65,536 maximum output tokens | | `elevenlabs/flash-v2.5` | Text to speech | ga | $0.05 per 1K characters | 2,000 maximum characters | | `elevenlabs/scribe-v2` | Speech to text | ga | $0.22 per audio hour | 30 maximum minutes | A 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. --- # Create an OpenAI-compatible LLM response Canonical source: [https://onchainrouter.dev/docs/api/chat-completions](https://onchainrouter.dev/docs/api/chat-completions) **POST /v1/chat/completions** Operation ID: `createChatCompletion`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Request body Choose 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. ```json { "model": "gemini-3.6-flash", "messages": [ { "role": "user", "content": "Explain in two short sentences why the sky appears blue." } ], "max_tokens": 1024, "stream": false } ``` ## Payment lifecycle The 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. After 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. ## Read the response Visible 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. ## Responses - **200:** Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers - **400:** Invalid or unsupported request - **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. - **409:** Idempotency key reused with a different effective request - **415:** Unsupported request content type. This fails before a payment challenge or verification. - **503:** Provider, payment, or safety dependency unavailable --- # Create an Anthropic-compatible LLM response Canonical source: [https://onchainrouter.dev/docs/api/messages](https://onchainrouter.dev/docs/api/messages) **POST /v1/messages** Operation ID: `createMessage`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Request body Choose 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. ```json { "model": "gemini-3.6-flash", "messages": [ { "role": "user", "content": "Explain why the sky appears blue." } ], "max_tokens": 1024, "stream": false } ``` ## Payment lifecycle The 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. After 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. ## Read the response Read Anthropic-compatible content blocks and normalized usage. The public alias is preserved even though the private gateway resolves an internal Vertex deployment. ## Responses - **200:** Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers - **400:** Invalid or unsupported request - **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. - **409:** Idempotency key reused with a different effective request - **415:** Unsupported request content type. This fails before a payment challenge or verification. - **503:** Provider, payment, or safety dependency unavailable --- # Generate an image from a text prompt Canonical source: [https://onchainrouter.dev/docs/api/image-generations](https://onchainrouter.dev/docs/api/image-generations) **POST /v1/images/generations** Operation ID: `createImageGeneration`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Request body Choose 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. ```json { "model": "gemini-3.1-flash-lite-image", "prompt": "A small observatory beneath a clear night sky, editorial illustration", "n": 1, "image_size": "1K", "aspect_ratio": "1:1", "response_format": "url" } ``` ## Payment lifecycle The 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. After 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. ## Read the response Read 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. ## Responses - **200:** Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers - **400:** Invalid or unsupported request - **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. - **409:** Idempotency key reused with a different effective request - **415:** Unsupported request content type. This fails before a payment challenge or verification. - **503:** Provider, payment, or safety dependency unavailable --- # List enabled curated text-to-speech voices Canonical source: [https://onchainrouter.dev/docs/api/audio-voices](https://onchainrouter.dev/docs/api/audio-voices) **GET /v1/audio/voices** Operation ID: `listAudioVoices`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Responses - **200:** Curated public voice aliases; upstream voice IDs are private. --- # Generate a hosted speech audio asset Canonical source: [https://onchainrouter.dev/docs/api/audio-speech](https://onchainrouter.dev/docs/api/audio-speech) **POST /v1/audio/speech** Operation ID: `createSpeech`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Request body The 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. ```json { "model": "elevenlabs/flash-v2.5", "input": "Your text to speak.", "voice": "darian", "response_format": "mp3", "speed": 1 } ``` ## Payment lifecycle The 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. After 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. ## Read the response Read 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`. ## Responses - **200:** Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers - **400:** Invalid or unsupported request - **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. - **409:** Idempotency key reused with a different effective request - **415:** Unsupported request content type. This fails before a payment challenge or verification. - **503:** Provider, payment, or safety dependency unavailable --- # Transcribe one bounded audio upload Canonical source: [https://onchainrouter.dev/docs/api/audio-transcriptions](https://onchainrouter.dev/docs/api/audio-transcriptions) **POST /v1/audio/transcriptions** Operation ID: `createTranscription`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Request body The 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. ### JSON for agents ```json { "audio_base64": "", "model": "elevenlabs/scribe-v2", "file_format": "other", "response_format": "json" } ``` Do not include a data-URL prefix or whitespace in `audio_base64`. ### Multipart file upload ```bash curl --request POST https://onchainrouter.dev/v1/audio/transcriptions \ --header "x-idempotency-key: 11111111-1111-4111-8111-111111111111" \ --form "file=@speech.mp3;type=audio/mpeg" \ --form "model=elevenlabs/scribe-v2" \ --form "response_format=json" ``` An 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. ## Payment lifecycle The 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. After 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. ## Read the response Read 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. ## Provider retention ElevenLabs 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. ## Responses - **200:** Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers - **400:** Invalid or unsupported request - **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. - **409:** Idempotency key reused with a different effective request - **415:** Unsupported request content type. This fails before a payment challenge or verification. - **503:** Provider, payment, or safety dependency unavailable --- # List available capability categories, endpoints, and models Canonical source: [https://onchainrouter.dev/docs/api/models](https://onchainrouter.dev/docs/api/models) **GET /v1/models** Operation ID: `listModels`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Choose a capability Use 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. ## Responses - **200:** Current categorized catalog. Only returned categories and endpoints are available. --- # List detailed pricing for all available models Canonical source: [https://onchainrouter.dev/docs/api/pricing](https://onchainrouter.dev/docs/api/pricing) **GET /v1/pricing** Operation ID: `listPricing`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Read pricing Each 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. ## Responses - **200:** Current model rates and pricing policy --- # Check a Base wallet USDC balance Canonical source: [https://onchainrouter.dev/docs/api/balance](https://onchainrouter.dev/docs/api/balance) **GET /v1/balance** Operation ID: `getWalletBalance`. The canonical machine-readable schema is [OpenAPI](https://onchainrouter.dev/openapi.json). ## Check a wallet Pass 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. ## Responses - **200:** Current Base USDC wallet balance - **400:** Invalid or missing Base wallet address - **503:** Base balance lookup temporarily unavailable --- # Service status Canonical source: [https://onchainrouter.dev/status](https://onchainrouter.dev/status) **Base mainnet:** Onchain Router accepts USDC payments from any wallet with a valid x402 authorization; no payer registration or pre-approved wallet list is used. Check the live payment response and apply a local spending limit before signing. This page describes the production payment environment. It is not a live uptime monitor. --- # Public alpha privacy notice Canonical source: [https://onchainrouter.dev/legal/privacy](https://onchainrouter.dev/legal/privacy) Last reviewed: 2026-08-31. Onchain Router processes request content to provide paid model responses, prevent abuse, recover a previous result without charging twice, settle payment, and operate the service. This notice describes the implemented technical behavior of the guarded public alpha. ## Request content After payment verification and before calling the model provider, the service screens verified prompt text and stores an encrypted, redacted review copy for seven days. Detected credentials and obvious personal identifiers are removed before encryption. Authorized operators may review only one record at a time, and every access is recorded. The retention worker automatically deletes expired encrypted content. The selected model provider processes request content to produce the response. Prompts and completions are excluded from application logs, metrics, alerts, receipts, and outbox payloads. ## Operational records The service retains the minimum payment, receipt, request-state, usage, security, and audit metadata needed for financial correctness, replay prevention, reconciliation, incident response, and legal obligations. Raw wallet signatures, complete payment payloads, receipt access tokens, wallet private keys, provider credentials, and cloud project identifiers are not placed in telemetry or receipts. Completed responses are encrypted for short idempotent recovery: 15 minutes after successful release and up to one hour while settlement is ambiguous. This is separate from the seven-day prompt-review record. Generated images are encrypted in a separate private-media store. Every image response includes `url_retention_days: 7` and an exact `url_expires_at` timestamp. The capability URL stops serving the image at that timestamp. Azure lifecycle management permanently deletes the encrypted object after it becomes seven days old; physical deletion completes on Azure's next lifecycle scan. Buyers must download an image before expiration if they need to keep it longer. Text-to-speech requests use ElevenLabs Zero Retention Mode. Speech-to-text is different: ElevenLabs 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 encrypts STT staging only after payment authorization and attempts to delete that local staging after every definite success or failure. After an ambiguous provider outcome, 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. Onchain Router's local deletion does not delete provider-held data. ## Service providers and chains Google processes text and image requests through Vertex AI. ElevenLabs processes text-to-speech and speech-to-text requests under the route-specific retention behavior above. Coinbase CDP verifies and settles x402 authorizations. Base records settlement transactions publicly. Azure hosts the application and operational data. Each service receives information required for its role and is governed by its own terms. ## Public-chain notice Wallet addresses, token transfers, transaction hashes, amounts, and block data written to Base are public and cannot be deleted by Onchain Router. ## Alpha notice Do not submit personal, confidential, regulated, or third-party content unless you have the right to process it through the named providers and public-chain payment flow. The service may change this notice as the alpha evolves; the date below identifies the version that applies. Last reviewed: 2026-08-31. --- # Public alpha service terms Canonical source: [https://onchainrouter.dev/legal/terms](https://onchainrouter.dev/legal/terms) Last reviewed: 2026-08-31. Onchain Router provides experimental, non-streaming model inference paid per request with USDC on Base mainnet. By using the guarded public alpha, buyers accept the payment, wallet, output, failure, and acceptable-use rules below. ## Payment and pricing The first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Before signing, the buyer must check the payment network, asset, recipient, expiry time, payment scheme, and exact amount. The buyer signs one request-specific EIP-3009 authorization. Text prices use a conservative input estimate plus 10% of requested output; text-to-speech prices validated characters; speech-to-text prices validated audio duration; and image requests use the fixed model/size catalog price. Settlement occurs only after the result is safely stored. A 0% service fee launch promotion is active. Current model rates, the $0.001 fixed successful-call fee, and the separate minimum are published in the live catalog. Provider-reported usage remains in the receipt and does not create a later refund. Ordinary payments need Base USDC only, without Base ETH or a token approval. ## Wallet responsibility The buyer controls its wallet and signs locally. Onchain Router never requests a seed phrase or private key. Buyers are responsible for wallet security, sufficient funds, local spending caps, validating every 402 challenge, and complying with laws that apply to them. Any successfully verified wallet may submit a request; this does not waive sanctions, fraud, abuse, or provider-policy screening. ## Model output Model output can be incomplete, inaccurate, unsafe, or unsuitable for a particular purpose. A `finish_reason` of `length` is a valid but truncated result. Buyers must independently review output before relying on it, especially for legal, financial, medical, safety-critical, or high-impact decisions. Hosted generated-image URLs expire exactly seven days after generation. The response includes both `url_retention_days: 7` and the exact `url_expires_at` timestamp. Buyers are responsible for downloading results they need to retain beyond that time. Hosted text-to-speech URLs are bearer capabilities and expire at the exact `expires_at` timestamp returned with the result, 24 hours after generation. Speech-to-text sends the uploaded audio and transcript output to ElevenLabs in standard retained mode; do not submit sensitive, regulated, biometric, or third-party audio without the necessary rights and consent. ## Failures, receipts, and disputes A model request that definitely failed is not charged. A successful answer is released only after the result, payment, and receipt are safely stored. The receipt records the signed exact amount, normalized usage, and settlement reference. The service does not automatically repeat a request when the model or payment outcome is uncertain. Buyers should preserve the request identifier, receipt identifier, and transaction hash and avoid starting a new request until the recorded state is resolved. The alpha has no uptime or response-time guarantee and may be paused without notice. For a payment or recovery dispute, preserve the request ID, receipt ID, and transaction hash; never send a seed phrase, private key, raw signature, complete payment payload, or receipt capability in a support message. ## Acceptable use Do not use the service to violate law, sanctions, third-party rights, model-provider policies, network rules, or to abuse, disrupt, probe, evade limits, distribute malware, expose credentials, or process content without required rights and consent. Requests may be blocked before provider execution and without settlement when policy screening rejects them. ## Changes and availability Models, limits, rates, lifecycle status, and availability can change. The live model catalog, status page, and HTTP 402 payment response are authoritative for each request. The service is provided on an experimental, as-available basis; independently verify model output and payment terms before relying on either. ## Alpha changes These terms may change as the alpha evolves. The date below identifies the version that applies. Stop using the service if you do not accept an updated version. Last reviewed: 2026-08-31. --- # Portable Agent Skill Canonical source: [https://onchainrouter.dev/skill/onchain-router/SKILL.md](https://onchainrouter.dev/skill/onchain-router/SKILL.md) Delegate every financial action to the local Buyer Runtime. This skill contains workflow guidance and thin CLI bridge scripts only. It does not implement signing, x402, wallet custody, budgets, settlement, or receipt verification. This version is public MIT source and requires the matching local Buyer CLI. The CLI, TypeScript SDK, MCP, proxy, Buyer Runtime, and routing packages are public npm `0.1.2` alphas; use the explicit `alpha` tag. Python remains source-only. OpenClaw and Hermes `0.1.0` are public MIT GitHub alphas installable through their hosts' native Git installers; they are not claimed as ClawHub or PyPI listings, and funded host acceptance remains unverified. Check the canonical site's `/docs/installation` and `/products.json` for current publication facts. Reading this skill does not authorize wallet setup, funding, publication, or a paid call. ## Choose the entry point Read [references/entrypoints.md](https://onchainrouter.dev/skill/onchain-router/references/entrypoints.md), then use exactly one primary path: - Use focused MCP when the host supports local stdio MCP and native tools. - Use the loopback proxy when an existing OpenAI-compatible client can set a base URL and local API key but cannot perform x402. - Use the TypeScript or Python SDK when writing application code. - Use the CLI for human setup, unlock, funding, policy, diagnostics, or shell automation. - Use this skill when the host supports portable Agent Skills and local commands; its scripts call the same CLI bridge as the Python SDK. - Use the dedicated OpenClaw or Hermes adapter when that is the agent host; both still delegate financial authority to Buyer Runtime. - Use the public HTTP API directly only when the host already has an independently reviewed official x402 buyer. Do not recreate the removed payment scripts. MCP, proxy, SDKs, CLI, and this skill support the five paid JSON endpoints. MCP/skill use small inline MP3 inputs, not arbitrary paths or URLs; use the human CLI's explicit file upload for larger audio. Speech returns hosted JSON, not the OpenAI SDK's binary audio stream; multipart uploads through the proxy are not implemented. Read [references/api.md](https://onchainrouter.dev/skill/onchain-router/references/api.md) for the live API contract and [references/entrypoints.md](https://onchainrouter.dev/skill/onchain-router/references/entrypoints.md) for adapter limits. ## Safe workflow 1. Ask the human to run `onchain-router setup`, fund the dedicated Base mainnet wallet, and run `onchain-router unlock` in a direct terminal. Never request or accept a private key, seed phrase, passphrase, or broker capability. 2. Run `node scripts/wallet-status.mjs`. Stop if the profile is missing, locked, expired, or outside the intended policy. 3. Run `node scripts/models.mjs` and `node scripts/pricing.mjs`. Select only a live model also allowed by the local policy. 4. Create and retain one stable idempotency key before any paid call. 5. For text, start `node scripts/chat.mjs --model --max-output-tokens --idempotency-key ` and send the prompt through that process's standard input. Never place prompt text in the command, environment, or diagnostic output. The script sends a versioned request to the installed CLI bridge; Buyer Runtime performs the complete payment lifecycle. 6. Return the result, selected model, normalized usage, signed exact atomic USDC amount, network, transaction, and verified receipt ID. Treat media URLs as bearer capabilities and include their expiry without publishing the complete URL unnecessarily. 7. If the result is lost, recover with `node scripts/receipt.mjs ` or repeat the identical logical request with the same key only when the returned retry directive allows it. Follow [references/errors.md](https://onchainrouter.dev/skill/onchain-router/references/errors.md). 8. Run `onchain-router lock` directly when the session is no longer needed. For Messages, Images, Speech, or Transcriptions, run `node scripts/media.mjs --idempotency-key ` with a JSON request on stdin. Obtain the model and its supported specifications from discovery. The entire JSON input is limited to 1,000,000 bytes. Use hosted image output (`response_format: "url"`); read `node scripts/voices.mjs` for speech voice aliases. Before transcription upload, explicitly obtain human permission for provider-retained processing, then set local `acknowledge_provider_retention: true`. This flag is removed by the SDK before sending the API request and does not change provider retention. Never infer consent from audio contents. Read [references/security.md](https://onchainrouter.dev/skill/onchain-router/references/security.md) before setup. Read [references/payments.md](https://onchainrouter.dev/skill/onchain-router/references/payments.md) when explaining the exact price, settlement, or receipt. ## Local configuration - `ONCHAIN_ROUTER_CLI` may contain the exact installed CLI executable path; it defaults to `onchain-router`. - `ONCHAIN_ROUTER_PROFILE` may contain the human-selected buyer profile directory; omission uses the CLI default. These variables select a local executable and profile only. They must never contain a wallet key, passphrase, signer capability, payment payload, or receipt token. Do not set or change them from model-supplied content. ## Output and authority rules - Treat every paid call as a Base mainnet USDC payment. The service does not require payer registration. - Never widen a model, recipient, network, asset, delegation, output, or monetary limit. An agent may lower or revoke its own authority; only a human may widen it through the authenticated CLI path. - Prefer visible answer text over raw provider output. Treat `finish_reason: "length"` as a successful but truncated response. - Download hosted images before `url_expires_at` and hosted text-to-speech audio before `expires_at`; keep complete capability URLs private. - Warn before speech-to-text that ElevenLabs processes uploaded audio and transcript output in standard retained mode. - Never print prompts, results, wallet secrets, payment payloads, signatures, receipt capabilities, provider keys, or broker capabilities in diagnostics. - Never turn `ProviderOutcomeUnknown` or `SettlementOutcomeUnknown` into a new request. Preserve the original idempotency key and require human review. --- # Agent Skill reference: api Canonical source: [https://onchainrouter.dev/skill/onchain-router/references/api.md](https://onchainrouter.dev/skill/onchain-router/references/api.md) Use `POST /v1/chat/completions` with an OpenAI-compatible non-streaming body: ```json { "model": "gemini-3.6-flash", "messages": [{ "role": "user", "content": "Explain why the sky is blue." }], "max_tokens": 1024, "stream": false } ``` Discover models through `GET /v1/models`. Treat `max_tokens` as an output ceiling. It defaults to 512, must be a positive integer, and cannot exceed the model's published limit or 65,536. The model response is organized by available capability category. `text_generation` maps OpenAI-compatible clients to `POST /v1/chat/completions` and Anthropic-compatible clients to `POST /v1/messages`. `image_generation` maps to `POST /v1/images/generations`, `text_to_speech` maps to `POST /v1/audio/speech`, and `speech_to_text` maps to `POST /v1/audio/transcriptions`, which accepts canonical Base64 JSON or multipart form data. Use only categories, model aliases, formats, and endpoints returned by the live catalog. The public speech catalog exposes ElevenLabs Flash v2.5 TTS and Scribe v2 STT, both for MP3 only; other speech models and formats remain unavailable. Use `POST /v1/images/generations` with an OpenAI-compatible body: ```json { "model": "gemini-3.1-flash-lite-image", "prompt": "A small observatory beneath a clear night sky, editorial illustration", "n": 1, "size": "1024x1024", "response_format": "url" } ``` The current public endpoint accepts one 1024×1024 image. The default response includes a capability URL, `backed_up: true`, `url_retention_days: 7`, and the exact `url_expires_at`. Download it before expiration and avoid exposing the complete URL in logs. Request `b64_json` only when inline bytes are required; the response still includes the seven-day URL. Use `POST /v1/audio/speech` with an OpenAI-shaped JSON body: ```json { "model": "elevenlabs/flash-v2.5", "input": "Your text to speak.", "voice": "darian", "response_format": "mp3", "speed": 1 } ``` Choose a public voice alias from `GET /v1/audio/voices`; omitting `voice` uses Darian. Read the hosted MP3 from `data[0].url`, its exact 24-hour deadline from `data[0].expires_at`, and measured characters from `usage.input_characters`. Download the file before expiration and keep the complete capability URL out of logs and public messages. Use `POST /v1/audio/transcriptions` with canonical Base64 JSON when a client cannot construct a file upload: ```json { "audio_base64": "SUQzBAAAAA...", "model": "elevenlabs/scribe-v2", "response_format": "json" } ``` The `audio_base64` value must be canonical RFC 4648 Base64 with no data-URL prefix or whitespace. Alternatively, send one complete multipart body: ```bash curl --request POST https://onchainrouter.dev/v1/audio/transcriptions \ --header "x-idempotency-key: 11111111-1111-4111-8111-111111111111" \ --form "file=@speech.mp3;type=audio/mpeg" \ --form "model=elevenlabs/scribe-v2" \ --form "response_format=json" ``` The ordinary JSON or multipart request receives HTTP 402 and does not pay. The service validates the MP3 before quoting so it can derive the maximum from inspected duration. Validate and sign the challenge with an official x402 client, then retry the identical body and idempotency key with the payment header. Read the transcript from `text` and measured duration from `usage.input_audio_ms`. ElevenLabs processes the upload and transcript output in standard retained mode; do not submit sensitive or regulated audio. Read detailed rates from `GET /v1/pricing`. Check public Base USDC chain state with `GET /v1/balance?address=0x...`; this lookup never connects a wallet or requests a signature. Read visible Chat Completions output from `choices[0].message.content`, completion state from `choices[0].finish_reason`, and normalized counts from `usage`. Ignore provider-specific thought signatures unless raw output was explicitly requested. Use the live `/openapi.json` for the concise public Chat Completions, Messages, Image Generations, Text to Speech, Speech to Text, Voices, Models, Pricing, and Balance schemas. Quote, receipt, media delivery, protocol-discovery, and health routes are support surfaces rather than separate agent-directory products. --- # Agent Skill reference: payments Canonical source: [https://onchainrouter.dev/skill/onchain-router/references/payments.md](https://onchainrouter.dev/skill/onchain-router/references/payments.md) HTTP 402 is the expected first response inside Buyer Runtime. The local CLI, SDKs, MCP, proxy, and skill delegate requirement validation, official x402 signing, identical-body retry, durable recovery, and receipt verification to that one implementation. Do not parse, sign, or retry the challenge again in an adapter. An empty, incomplete, or malformed unsigned JSON probe can receive an inspection-only 402. Do not sign it. Submit a valid request body and let Buyer Runtime obtain and validate the request-specific challenge before authorizing payment. A caller that already uses the public HTTP API directly must use reviewed official x402 primitives, validate the live requirement, and preserve the identical body and idempotency identity. The portable skill no longer supplies an independent direct-payment runtime. The supported payment network is Base mainnet (`eip155:8453`), and settlement uses USDC through the official x402 v2 `exact` EIP-3009 scheme. An ordinary payment requires Base USDC only, not Base ETH or a token approval. The exact amount is request-specific: text prices a conservative input estimate plus 10% of `max_tokens`, TTS uses validated character length, STT uses locally inspected audio duration, and image generation uses the selected specification price. The published minimum and fixed fee apply. Provider-reported usage remains receipt and cost-control evidence; it does not create a later refund. Return the settlement amount from the standard `PAYMENT-RESPONSE`, plus `X-Receipt-ID` and transaction hash. Confirm that it agrees with the signed exact amount. The payment transaction proves settlement. The usage portion of the receipt is an Onchain Router attestation based on normalized provider usage. --- # Agent Skill reference: errors Canonical source: [https://onchainrouter.dev/skill/onchain-router/references/errors.md](https://onchainrouter.dev/skill/onchain-router/references/errors.md) All local adapters return the Buyer Runtime outcome plus a retry directive. Correct malformed input or local policy deliberately; do not infer retry safety from HTTP status alone. Treat HTTP 402 inside Buyer Runtime as the normal authorization step, not an error exposed for an adapter to reimplement. Stop on `AuthorizationAboveLocalCap` or `PaymentPolicyRejected`. Reduce the request only when it remains within the existing human-owned model, output, recipient, and monetary envelope; an agent may not widen policy. Hourly, daily, session, and delegation exhaustion require reset or operator review. `Permit2ApprovalRequired` indicates an explicitly retained legacy `upto` profile. It is definite-unpaid. Ask the human operator to authenticate and migrate with `onchain-router policy set --scheme exact`; an agent must never fund gas, approve a token, or change payment policy. `Permit2ApprovalOutcomeUnknown` from a prior legacy approval still requires human review before any retry. Retry `empty_provider_response` only after increasing `max_tokens`; the known unusable inference is not customer-settled. Treat `finish_reason: "length"` as a paid, valid, truncated response rather than an error. Never create a new paid request after `provider_outcome_unknown`, `settlement_unknown`, a post-authorization timeout, or a lost connection. Retry the identical request with the same idempotency identity to recover durable state, then wait for receipt/reconciliation or operator resolution. HTTP 409 means an idempotency key was reused with a different effective request. Do not override it. The stable local outcomes are `PaymentPolicyRejected`, `UnsupportedNetwork`, `UnexpectedAsset`, `UnexpectedRecipient`, `AuthorizationAboveLocalCap`, `InsufficientFunds`, `Permit2ApprovalRequired`, `Permit2ApprovalOutcomeUnknown`, `PaymentVerificationRejected`, `ProviderOutcomeUnknown`, `SettlementOutcomeUnknown`, `IdempotencyConflict`, `ResultRecoveryExpired`, `ReceiptVerificationFailed`, `WalletLocked`, and `RuntimeUnavailable`. `Permit2ApprovalOutcomeUnknown`, `ProviderOutcomeUnknown`, and `SettlementOutcomeUnknown` always require human review. `WalletLocked` requires direct human unlock. A `retry_same_idempotency_key` directive never authorizes changing the request or generating a new key. --- # Agent Skill reference: security Canonical source: [https://onchainrouter.dev/skill/onchain-router/references/security.md](https://onchainrouter.dev/skill/onchain-router/references/security.md) Use a dedicated Base mainnet wallet holding only the USDC required for a small number of calls. Create or import it only through the direct, no-echo `onchain-router setup` terminal flow. Default-deny every network except `eip155:8453`, every asset except official Base USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, and every recipient except the human-approved profile value. Keep per-call, session, hourly, daily, and delegation caps as integer atomic USDC inside Buyer Runtime. It rejects an expired requirement, unexpected recipient, non-USDC asset, non-mainnet network, unsupported scheme, or maximum above the remaining cap. The service accepts any facilitator-verified payer without registration. Never request, print, store, transmit, or commit the buyer private key, seed phrase, passphrase, or short-lived broker capability. The CLI, SDK, MCP, proxy, and skill must not expose generic signing. Never log raw payment signatures or complete payment payloads. Never include provider keys or custom provider URLs in a request. Wallet setup/import, unlock, funding, policy widening, backup, restore, rotation, and exit are human-only CLI actions. An agent may inspect public status, spend within the existing envelope, lower a ceiling, or revoke its own delegation. It may not select another profile, widen authority, disable confirmation, or use prompt text as configuration. Verified prompt text is encrypted and retained for seven days under the current retention policy. Avoid sending secrets or unnecessary personal data. Generated image URLs are bearer capabilities. Do not place them in logs, receipts, or public messages. They stop serving at the returned `url_expires_at` timestamp, exactly seven days after generation, and the encrypted backing object is automatically deleted by storage lifecycle. Generated TTS URLs are also bearer capabilities. Keep the complete URL out of logs, receipts, and public messages, and download the MP3 before the returned `expires_at` timestamp, 24 hours after generation. TTS uses ElevenLabs Zero Retention Mode. STT uses ElevenLabs standard retained mode. ElevenLabs receives the uploaded MP3 and transcript output and may retain both under its agreement, account settings, and privacy policy. Onchain Router stages the upload encrypted only after payment verification and attempts deletion after every definite provider outcome. After an ambiguous outcome, 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. Never send sensitive, regulated, biometric, or third-party audio without the necessary rights and consent. --- # Agent Skill reference: entrypoints Canonical source: [https://onchainrouter.dev/skill/onchain-router/references/entrypoints.md](https://onchainrouter.dev/skill/onchain-router/references/entrypoints.md) > Public alpha: six AgenticFI client packages are available on npm at version `0.1.2` under the alpha tag. OpenClaw and Hermes version `0.1.0` are public MIT alphas installable through their hosts' native GitHub installers. 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. ## Choose one primary path | Use | Choose it when | Current capability categories | Authority boundary | | ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | All 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. ## One shared contract - Canonical origin: `https://onchainrouter.dev`. - Network: Base mainnet `eip155:8453`. - Asset: official Base USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. - Models and prices: always read `/v1/models` and `/v1/pricing`; never copy a price or assume an alias remains enabled. - Paid endpoints: `/v1/chat/completions`, `/v1/messages`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`. - Example text model at generation time: `gemini-3.6-flash`. Confirm it against live discovery before a call. - Idempotency: create one stable key before the unpaid request and retain it through signing, recovery, and receipt lookup. - 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. - Success: return `ok`, `outcome`, `idempotencyKey`, `body`, `receipt`, `payment`. - Failure: return `ok`, `outcome`, `retry`, `idempotencyKey`, `message`, `reference` without secret-bearing diagnostics. Every 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. The 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. ## Human-owned setup The following actions are human-only and must run in a direct terminal: - wallet create or import - wallet unlock - funding - legacy Permit2 profile migration - policy widening - confirmation-policy changes - backup or restore - key rotation - wallet export or exit Do 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. Installed-client and public-source entry points are: | Entry point | Artifact | Inspect or start | | ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------ | | Focused MCP | `@agenticfi/onchain-router-mcp` | `onchain-router-mcp --print-config` | | Loopback proxy | `@agenticfi/onchain-router-proxy` | `onchain-router-proxy --print-config` | | TypeScript or Python SDK | `@agenticfi/onchain-router or onchain-router` | `OnchainRouterBuyer.connect() or OnchainRouterBuyer()` | | Buyer CLI | `@agenticfi/onchain-router-cli` | `onchain-router help` | | Portable Agent Skill | `skills/onchain-router` | `node scripts/models.mjs` | | OpenClaw extension | `AgenticFI/onchain-router-openclaw` | `openclaw plugins install git:github.com/AgenticFI/onchain-router-openclaw@v0.1.0 --force` | | Hermes Agent plugin | `AgenticFI/onchain-router-hermes` | `hermes plugins install AgenticFI/onchain-router-hermes --enable` | Install npm packages only from the `@agenticfi` scope with the `alpha` tag. Install OpenClaw and Hermes only from the exact AgenticFI GitHub repositories and pinned release references shown above. Host-native Git installability is independent of ClawHub or PyPI listing status. ## Stable outcomes | Outcome | Retry directive | | ------------------------------- | ---------------------------- | | `PaymentPolicyRejected` | `do_not_retry` | | `UnsupportedNetwork` | `do_not_retry` | | `UnexpectedAsset` | `do_not_retry` | | `UnexpectedRecipient` | `do_not_retry` | | `AuthorizationAboveLocalCap` | `do_not_retry` | | `InsufficientFunds` | `retry_unpaid_request` | | `Permit2ApprovalRequired` | `do_not_retry` | | `Permit2ApprovalOutcomeUnknown` | `human_review` | | `PaymentVerificationRejected` | `retry_unpaid_request` | | `ProviderOutcomeUnknown` | `human_review` | | `SettlementOutcomeUnknown` | `human_review` | | `IdempotencyConflict` | `do_not_retry` | | `ResultRecoveryExpired` | `do_not_retry` | | `ReceiptVerificationFailed` | `retry_same_idempotency_key` | | `WalletLocked` | `unlock_wallet` | | `RuntimeUnavailable` | `retry_same_idempotency_key` | `ProviderOutcomeUnknown` 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. ## Receipt and output Return 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.