[{"title":"Pay for AI model requests one at a time","description":"Send a text, image, or speech request, approve a clear spending limit, pay in USDC, and receive a durable receipt.","route":"/docs","text":"Onchain Router gives you one provider-neutral interface for text generation, image generation, text to speech, and speech to text. You approve a request-specific spending limit in your wallet and receive the result only after the result, final charge, and receipt are safely stored.\n\n> Payments use USDC on Base mainnet. Any wallet with a valid x402 payment authorization may pay; no payer registration is required.\n\n Choose your path\n\n- Choose a capability: compare all [five paid AI endpoints and four free discovery endpoints](/docs/endpoints).\n- Make your first request: follow the [step-by-step guide](/docs/quickstart) with a dedicated wallet that holds only a small amount of USDC.\n- Connect an autonomous agent: install the [portable Agent Skill](/docs/agents) and set a hard spending limit in atomic USDC units.\n- Connect a backend service: start with the generated guide for [Chat Completions](/docs/api/chat-completions), [Messages](/docs/api/messages), [Image Generations](/docs/api/image-generations), [Text to Speech](/docs/api/audio-speech), or [Speech to Text](/docs/api/audio-transcriptions).\n\n What stays familiar\n\nText requests use the familiar model, messages, max_tokens, and stream fields. Image requests use model, prompt, n, image_size, aspect_ratio, and response_format; 1K and 1:1 are the defaults, and the selected model must advertise the requested values. Text to speech uses JSON with model, input, voice, and response_format. Speech to text accepts one bounded MP3 either as standard multipart form data or as canonical Base64 JSON for agents that cannot construct file uploads. Choose an available capability, endpoint, and model from GET /v1/models; choose a public voice alias from GET /v1/audio/voices.\n\n What x402 adds\n\nThe first unpaid request returns Hypertext Transfer Protocol (HTTP) status 402 with the payment network, asset, recipient, expiry time, and maximum amount. An official x402 buyer signs the authorization locally and retries the identical request. After success, inspect the PAYMENT-RESPONSE header, the X-Receipt-ID header, and the receipt link.\n\nYou do not need an API subscription, and Onchain Router never stores your wallet key. Never send a private key, model-provider key, or custom provider address in the request body."},{"title":"Choose the right endpoint","description":"Compare the five paid AI endpoints and four free discovery endpoints in the public Onchain Router contract.","route":"/docs/endpoints","text":"Onchain Router currently exposes five paid AI endpoints and four free discovery endpoints. Choose the endpoint for the result you need, then choose a compatible model from GET /v1/models.\n\n Paid AI requests\n\n- POST /v1/chat/completions — OpenAI-compatible text, vision, tools, and structured output.\n- POST /v1/messages — Anthropic-compatible text, vision, and tool requests.\n- POST /v1/images/generations — Generate one image and receive a hosted URL or Base64 result.\n- POST /v1/audio/speech — Turn text into an MP3 with a public voice.\n- POST /v1/audio/transcriptions — Transcribe one MP3 supplied as canonical Base64 JSON or multipart form data.\n\nEvery paid endpoint uses the same Base mainnet x402 lifecycle. An unpaid request returns HTTP 402 without calling the model provider. Check the challenge, authorize it locally with an official x402 client, and retry the identical request with the same idempotency key.\n\n Free discovery\n\n- GET /v1/models — Find available capability categories, model aliases, limits, and compatible endpoints.\n- GET /v1/pricing — Read current model rates, billing units, and the 0% service fee promotion.\n- GET /v1/audio/voices — Choose from the 20 public text-to-speech voice aliases.\n- GET /v1/balance?address=0x... — Read a public wallet's Base USDC balance without connecting or signing.\n\nThese routes never ask for a payment signature. Agents should read the model catalog before constructing a paid request and should treat it as the availability source of truth.\n\n Start with the matching guide\n\n- [Chat Completions](/docs/api/chat-completions) for OpenAI-compatible clients.\n- [Messages](/docs/api/messages) for Anthropic-compatible clients.\n- [Image Generations](/docs/api/image-generations) for image output.\n- [Text to Speech](/docs/api/audio-speech) and [Voices](/docs/api/audio-voices) for hosted MP3 audio.\n- [Speech to Text](/docs/api/audio-transcriptions) for MP3 transcription.\n- [Models](/docs/api/models), [Pricing](/docs/api/pricing), and [Balance](/docs/api/balance) for machine-readable discovery.\n\nHealth, x402 protocol discovery, quote, media delivery, and private receipt routes remain operational support surfaces. They are intentionally omitted from the public product list so agents see only the endpoints needed to discover and use the available AI capabilities."},{"title":"What happens during a paid request","description":"See when payment is checked, when the model is called, how the final charge is calculated, and when the answer is released.","route":"/docs/how-it-works","text":"The request follows a strict order. An invalid payment can never start a model request, and an answer cannot reach the caller before its payment and receipt are safely stored.\n\nThe same lifecycle applies to all five paid routes: Chat Completions, Messages, Image Generations, Text to Speech, and Speech to Text. Their inputs, output validation, and billing units differ, but their payment ordering does not.\n\n Lifecycle\n\n1. Send a non-streaming request without payment.\n2. Receive Hypertext Transfer Protocol (HTTP) status 402 with an x402 upto payment requirement that is tied to the request.\n3. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, and maximum amount.\n4. Sign the payment authorization locally with an official x402 client.\n5. Retry the identical body with the same idempotency key, which prevents duplicate work and charges.\n6. Onchain Router verifies the payment and reserves exactly one execution record in PostgreSQL.\n7. The verified prompt is screened, redacted where required, encrypted, and retained for seven days.\n8. The private gateway calls the selected model deployment and validates reported usage plus any returned image or audio bytes.\n9. Generated image or TTS media enters encrypted private storage before settlement. STT input is encrypted while staged and deleted after a definite outcome.\n10. The service calculates text tokens, TTS characters, STT audio duration, or the selected model/size image tier with integer arithmetic and the catalog version attached to the request.\n11. The result, settlement, ledger entries, and receipt become durable before text, media URLs, or transcripts are released.\n\nEvery HTTP response includes an X-Trace-ID. Keep it when reporting a problem. Onchain Router logs\nthe trace ID, normalized route, method, status and safe error code, duration, content type and size,\nand catalog version. The normal 402 Payment Required challenge is tracked separately from endpoint\nerrors. Completed model requests also record non-content routing signals such as model,\nmessage and tool counts, request size, requested output limit, capability flags, provider duration,\ntoken usage, charge, and provider cost. Request and response text is never copied into these logs.\n\n Safety boundaries\n\n- PostgreSQL is the authoritative record for preventing payment replay and duplicate requests.\n- Redis can improve speed, but it is never the only system protecting financial correctness.\n- Known provider failures are not settled.\n- Provider-unknown or settlement-unknown outcomes are frozen for inspection, not blindly retried.\n- Settlement never exceeds the signed maximum.\n- Prompts, completions, raw payment payloads, private keys, and provider credentials are excluded from telemetry and receipts."},{"title":"Production environment and funding","description":"Understand the Base mainnet payment environment and how to fund a wallet with USDC.","route":"/docs/environments","text":" Base mainnet\n\n- Network: eip155:8453\n- Payment asset: United States Dollar Coin (USDC) on Base, contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\n- Scheme: x402 v2 upto\n- Capabilities: enabled Gemini text and image models plus the available ElevenLabs MP3 speech models in GET /v1/models\n- Recipient: 0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d\n\nAny wallet may pay after successful x402 verification. The service does not require registration or a pre-approved wallet list. We still recommend a dedicated wallet with the smallest practical balance and local limits for each request and each session. Check the payment recipient shown by the live endpoint before every signature.\n\n Funding and wallet safety\n\nFund the buyer wallet with only the USDC required for the next few requests. You may also need a small amount of Ether (ETH) on Base if the selected payment path does not cover the network fee. Validate the network, USDC contract, recipient, expiry, scheme, and maximum amount in every live HTTP 402 response before signing."},{"title":"Make your first paid AI request","description":"Choose a text, image, or speech route, check its payment limit, send one request on Base mainnet, and save the result and receipt.","route":"/docs/quickstart","text":"This guide uses an official x402 buyer and the Base mainnet payment contract. It spends USDC. Any wallet may pay after successful x402 verification, and no payer registration is required. The browser buyer included in this repository is an optional local integration tool; it is not a separate public service.\n\n 1. Prepare a dedicated wallet\n\nFor tighter wallet isolation, create a separate wallet account and fund it with only the small amount of Base mainnet USDC needed for the next few requests. You may also need a small amount of Ether (ETH) on Base if the selected payment path does not pay the network fee for you. The service does not require a separate wallet, but we strongly recommend one.\n\nNever use a primary or highly funded wallet.\n\n 2. Choose what to call\n\nThe five paid routes are Chat Completions, Messages, Image Generations, Text to Speech, and Speech to Text. The Models, Pricing, Voices, and Balance routes are free. Read the [endpoint overview](/docs/endpoints), then use GET /v1/models to select a compatible model and GET /v1/pricing to inspect its current billing unit.\n\nGemini currently serves text and image generation. ElevenLabs Flash v2.5 serves MP3 text to speech, and Scribe v2 serves MP3 speech to text. The API contract remains provider-neutral as the catalog expands.\n\n 3. Use an official x402 buyer\n\nCall the official Hypertext Transfer Protocol Secure (HTTPS) address with an x402 buyer that supports the Base mainnet upto payment scheme and Permit2 authorization. Start with GET /v1/models, then send the request below to POST /v1/chat/completions. The first unpaid response has HTTP status 402. The buyer checks the payment terms, signs locally, and retries the identical request.\n\nCoinbase Developer Platform and Google Vertex credentials belong only on the server. A buyer never supplies, receives, or stores them. Stop immediately if any website or agent asks you for a Coinbase secret, Google credential, wallet seed phrase, or wallet private key.\n\n 4. Send production-shaped JSON\n\nChat Completions is a simple first request. Choose any compatible text model from GET /v1/models; the same payment lifecycle also protects the image and speech routes.\n\njson\n{\n  \"model\": \"gemini-3.6-flash\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Explain in two short sentences why the sky appears blue.\"\n    }\n  ],\n  \"max_tokens\": 1024,\n  \"stream\": false\n}\n\n\nPreview the payment in your buyer. Confirm that the request uses Base mainnet (eip155:8453), official Base USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), recipient 0xA7660dea6AadCc87CbB5e79ccd262d391e61dE5d, the upto payment scheme, and a maximum no higher than your local spending limit.\n\n 5. Authorize and read the result\n\nConfirm the wallet signatures. Your first request may require both a request-specific Permit2 authorization and a USDC permit. These signatures approve a limited transfer. They never require you to reveal your private key.\n\nRead the visible answer from:\n\ntext\nchoices[0].message.content\n\n\nThen record the receipt ID, authorized maximum, actual settled amount, and BaseScan transaction. Do not publish the prompt, completion, receipt access token, or payment payload.\n\n Common results\n\n- A finish_reason value of \"stop\" means the answer completed normally.\n- A finish_reason value of \"length\" means the model reached the output limit. Increase max_tokens, obtain a new quote, and retry.\n- HTTP status 402 is the expected response before payment authorization.\n- An empty_provider_response error is not charged. The model used the available output budget without returning visible text.\n- If the provider or payment result is unknown, recover the existing request before starting a new one."},{"title":"Protect the wallet that pays for requests","description":"Use a dedicated wallet with a small balance, set firm spending limits, and check every payment term before signing.","route":"/docs/wallet-security","text":"Your wallet signs the payment authorization on your device. Onchain Router receives the authorization but never receives your seed phrase or wallet private key.\n\n Safe mainnet wallet policy\n\n- Create a new account used only for Onchain Router.\n- Hold only the USDC needed for the next few requests.\n- Set a hard limit for each request in atomic USDC units. The local mainnet acceptance client uses\n  1000000, which means 1.000000 USDC; the live server may enforce a lower limit independently.\n- Set a separate session cap for autonomous use.\n- Allow only Base mainnet (eip155:8453), official Base USDC, and the expected recipient.\n- No operator registration is required. The server applies a per-request maximum and a global estimated-loss breaker. These server controls protect the service; they do not replace your local wallet limits.\n- Disconnect or revoke site access when testing is complete.\n\n Before every signature\n\nRead the scheme, network, asset, payTo, maxAmountRequired, 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 maximum exceeds your local limit.\n\nDo not infer payment terms from this page. Runtime terms and the current public catalog are authoritative.\n\n Switching wallet accounts\n\nIn the repository's optional local acceptance UI, use Change buyer, select the new account in the wallet, and verify the complete address. The UI clears the old quote when the exposed account changes. Other x402 buyers must provide an equivalent account-change and quote-invalidation safeguard. Always preview again after switching."},{"title":"Connect an autonomous agent safely","description":"Give an agent a clear model contract, firm spending limits, official x402 payment signing, and rules that prevent unsafe retries.","route":"/docs/agents","text":"The portable Agent Skill is available at /skill/onchain-router/SKILL.md. It teaches an agent how to discover available models, enforce spending limits, pay with official x402 libraries, and return both the answer and its receipt.\n\n Discovery order\n\n1. Read /llms.txt for a short, curated map of the website and its authoritative resources.\n2. Read /llms-full.txt when the agent needs the complete public documentation in one request instead of visiting each page separately.\n3. Read /v1/models to get the current capability categories, model aliases, limits, and compatible endpoints.\n4. Read /v1/pricing for detailed rates and /v1/audio/voices before a text-to-speech request.\n5. Read /openapi.json to get the machine-readable request and response contract for all nine public routes.\n6. Submit the request and treat Hypertext Transfer Protocol (HTTP) status 402 as the expected payment step.\n7. Check every live payment field before signing.\n\n Endpoint selection\n\n- Use /v1/chat/completions for OpenAI-compatible text and /v1/messages for Anthropic-compatible text.\n- Use /v1/images/generations for an image, /v1/audio/speech for an MP3, and /v1/audio/transcriptions for a transcript.\n- Use /v1/models, /v1/pricing, /v1/audio/voices, and /v1/balance for free discovery. They must never ask the agent to sign.\n\nRead the [endpoint overview](/docs/endpoints) for the exact public surface and the generated endpoint guides for request-specific fields.\n\nThe llms.txt convention is an emerging discovery convention rather than an access-control standard. The website also publishes /sitemap.xml, per-page Markdown alternatives, and HTML discovery links. Access and indexing policy remain in /robots.txt.\n\n Required local policy\n\n- Base mainnet only (eip155:8453); reject every other network.\n- Dedicated, minimally funded mainnet wallet only.\n- Limits for each request and each session, represented as integer atomic United States Dollar Coin (USDC) strings.\n- Explicit model allowlist.\n- Recipient and USDC contract allowlists.\n- No payer registration: any wallet with a valid facilitator-verified authorization may pay.\n- One stable idempotency key across the unpaid request and the signed retry so the service can prevent duplicate work.\n- No blind retry after provider or settlement ambiguity.\n\n Stable output\n\nReturn the requested text, image, audio, or transcript; the selected model; normalized usage; approved maximum; final amount charged; payment asset; network; receipt identifier; and transaction hash. For hosted media, also return the exact expiry field. Hide large provider-specific reasoning fields unless the caller explicitly requests the raw response.\n\n Install\n\nCopy the skills/onchain-router directory into the Agent Skills location supported by the caller. Keep the package lockfile and official x402 dependencies with the executable scripts. Do not add a wallet key to the skill folder."},{"title":"Code examples for text, image, and speech","description":"Use an official x402 client with the public text, image, and speech request formats.","route":"/docs/sdk-examples","text":"Every client uses the same official service address and payment lifecycle. The payment wrapper must use official x402 packages and locally enforce the payment network, asset, recipient, and spending limits in atomic United States Dollar Coin (USDC) units. Request bodies differ by capability; use the generated guide for the selected endpoint.\n\n TypeScript\n\nConstruct paymentFetch with the official @x402/core, @x402/evm, and @x402/fetch client packages. Then pass it to the repository wrapper:\n\nts\nimport { OnchainRouterClient } from '@onchain-router/client';\n\nconst router = new OnchainRouterClient({\n  baseUrl: process.env.ONCHAIN_ROUTER_URL!,\n  paymentFetch,\n});\n\nconst response = await router.chat({\n  model: 'gemini-3.6-flash',\n  messages: [{ role: 'user', content: 'Explain why the sky appears blue.' }],\n  max_tokens: 1024,\n  stream: false,\n});\n\nconst body = await response.json();\nconsole.log(body.choices[0].message.content);\nconsole.log(response.headers.get('x-receipt-id'));\n\n\nThe local payment policy must reject any network other than Base mainnet, an incorrect USDC contract, a changed recipient, an unsupported payment scheme, or a maximum above the caller's spending limit.\n\n Python\n\nThe maintained repository example accepts an httpx.Client that is already wrapped by the official x402 software development kit for Python:\n\npython\nresult = paid_chat(payment_client)\nprint(result[\"choices\"][0][\"message\"][\"content\"])\n\n\nDo not implement Ethereum Improvement Proposal 712 (EIP-712), Permit2, or payment settlement code in your application. Use the official libraries.\n\n Direct Hypertext Transfer Protocol request\n\nAn ordinary unpaid request is useful for inspecting the challenge:\n\nbash\ncurl -i \"$ONCHAIN_ROUTER_URL/v1/chat/completions\" \\\n  -H \"content-type: application/json\" \\\n  -H \"x-idempotency-key: $(uuidgen)\" \\\n  --data '{\"model\":\"gemini-3.6-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hello.\"}],\"max_tokens\":512,\"stream\":false}'\n\n\nExpect Hypertext Transfer Protocol (HTTP) status 402. Do not construct the paid retry by hand. Pass the response to an official x402 buyer client.\n\n Other capabilities\n\nUse the same payment-aware client for every paid route:\n\n- [Messages](/docs/api/messages) accepts the Anthropic-compatible message shape.\n- [Image Generations](/docs/api/image-generations) accepts an image model, prompt, size, aspect ratio, and response format.\n- [Text to Speech](/docs/api/audio-speech) accepts text, model, voice, MP3 response format, and optional speed.\n- [Speech to Text](/docs/api/audio-transcriptions) accepts one MP3 either as canonical Base64 JSON or as multipart form data.\n\nDo not assume that a text-specific wrapper method supports media. Send the exact body shown by OpenAPI through the same official payment-aware HTTP client."},{"title":"How authorization, charges, and receipts work","description":"Understand the spending limit you approve, the final amount charged, and the payment evidence saved in the receipt.","route":"/docs/payment-receipts","text":"For text, max_tokens sets the largest response the model may return. It does not prepay for that many tokens. The server uses the limit to calculate the highest possible charge, while the final charge uses the model provider's reported usage. Image generation instead selects one disclosed fixed price from the requested model and image_size; aspect_ratio does not change the tier.\n\n Pricing terms\n\n- Estimated maximum: the estimated input cost plus the highest possible output cost, a pricing buffer, the active service fee, the fixed successful-call fee, and the minimum usage charge.\n- Authorized maximum: the request-specific spending limit approved by the buyer.\n- Provider cost: catalog rates multiplied by actual normalized token usage for text; the fixed\n  image-output accounting floor plus any reported prompt or residual output usage for images.\n- Service fee: 0% during the launch promotion, recorded as zero integer basis points.\n- Fixed successful-call fee: 1000 atomic USDC units, or 0.001000 USDC.\n- Minimum charge: 1000 atomic United States Dollar Coin (USDC) units, or 0.001000 USDC, for each successful paid model request.\n- Text settlement: the greater of actual provider cost plus the active service fee and the minimum usage charge, plus the fixed successful-call fee, capped by the signed maximum.\n- Image settlement: the selected model/size catalog price plus the fixed successful-call fee, capped by the signed maximum. The current Base mainnet Gemini 3.1 Flash-Lite Image 1K/1:1 total is 0.035000 USDC.\n\nImage token counts are optional upstream telemetry and do not affect the fixed image price. A zero\nimage token count in a receipt means the provider compatibility layer did not report that field; it\ndoes not mean that image generation used no computation.\n\nThe server uses integer arithmetic and rounds once when converting to six-decimal USDC. It never settles above the signed maximum.\n\n Receipt evidence\n\nThe successful response includes the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, X-Receipt-Token, and X-Catalog-Version headers, plus a receipt link. Retrieve the receipt with GET /v1/receipts/{receipt_id} and the X-Receipt-Token header. Treat the receipt token like a password: store it securely and never log or share it. The server stores only a one-way hash of the token.\n\nThe durable receipt contains the public model name, normalized usage, pricing policy, approved maximum, final amount charged, 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.\n\nThe x402 transaction proves that payment occurred. The usage section is an Onchain Router record,\nnot a separate provider-signed proof. Text usage is normalized from mandatory provider telemetry;\nimage usage retains optional provider telemetry and uses zero when a field was not reported."},{"title":"Understand errors and retry safely","description":"Learn which failures are safe to retry and how one idempotency key prevents duplicate model requests and charges.","route":"/docs/errors-retries","text":"An idempotency key identifies one logical request. Reusing the same key with the same request lets Onchain Router recover the existing result without calling the model or charging the wallet again.\n\n Safe to correct and retry\n\n- Invalid JSON, model, or output ceiling: fix the request and obtain a new quote.\n- Hypertext Transfer Protocol (HTTP) status 402: check the payment terms, sign, and retry the identical body.\n- Expired authorization: obtain a new quote and authorization.\n- empty_provider_response: increase max_tokens, obtain a fresh quote, and retry; the failed attempt is not settled.\n- Definite provider rejection before acceptance: correct the cause and retry with a new idempotency key.\n- wallet_request_cap_exceeded: lower the requested output ceiling and obtain a new quote, or ask the operator to review the policy.\n\n Do not retry blindly\n\n- provider_outcome_unknown\n- settlement_unknown\n- lost connection after wallet authorization\n- timeout after the provider or facilitator may have accepted work\n\nRetry 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.\n\n Idempotency rules\n\nThe first-party clients send x-idempotency-key, and x402 payment identifiers may provide an additional protocol identity. Repeating an identical 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.\n\nRedis loss does not weaken these guarantees because PostgreSQL owns the execution lease and authorization fingerprint."},{"title":"How request content is stored and deleted","description":"See which request content is stored, why it is needed, when it is deleted, and which sensitive values never enter logs or receipts.","route":"/docs/privacy","text":"After payment verification and before calling the model provider, Onchain Router screens the verified request text and stores an encrypted review copy for seven days. This short retention period supports abuse review, compliance with model-provider policies, security investigations, and product analysis.\n\n Retained\n\n- verified text from the prompt, limited by the maximum request size;\n- an encrypted and redacted review excerpt together with the review decision;\n- the deletion date and an audit record for each individual access.\n\nDetected credentials and obvious personal identifiers are removed before encryption. If the request matches a configured policy block, the service stops before calling the model provider and does not charge the customer.\n\n Not placed in telemetry or receipts\n\n- prompts or completions;\n- raw wallet signatures;\n- complete payment payloads;\n- receipt access tokens;\n- wallet private keys;\n- provider credentials;\n- cloud project identifiers.\n\nCompleted model answers use a separate encrypted recovery buffer. They are kept for 15 minutes after a successful response, or for up to one hour if the payment result is uncertain. This recovery buffer is separate from the seven-day prompt-review record.\n\nGenerated images use a separate encrypted private-media store. Every image response includes\nurl_retention_days: 7 and an exact url_expires_at timestamp. The capability URL stops serving\nthe image at that timestamp. Azure lifecycle management permanently deletes the encrypted object\nafter it becomes seven days old; the physical deletion completes on Azure's next lifecycle scan.\nDownload the image before expiration if it must be kept longer.\n\nText-to-speech requests use ElevenLabs Zero Retention Mode. Speech-to-text uses ElevenLabs standard\nretained mode: ElevenLabs receives the uploaded audio and transcript output and may retain both\nunder the applicable agreement, account settings, and privacy policy. Onchain Router encrypts STT\nstaging only after payment authorization and attempts to delete its local copy after every definite\nprovider success or failure. After an ambiguous provider outcome, local staging becomes logically\ninaccessible at its one-hour expiry. Encrypted bytes may remain beyond the one-day storage-lifecycle\nthreshold until Azure completes its next lifecycle scan. Local deletion by Onchain Router does not\ndelete data held by ElevenLabs.\n\n Processing and deletion\n\nGoogle Vertex AI processes requests to generate text or images. ElevenLabs processes text-to-speech\nand speech-to-text requests under the route-specific retention behavior above. Coinbase Developer\nPlatform verifies and settles x402 payments, and Base records the public transaction. Each service\nreceives only the information needed for its role. Encrypted prompt-review records and generated\nimages follow their separate seven-day deletion controls. An authorized operator can review only\none prompt-review record at a time, and every access is audited.\n\n Public alpha boundaries\n\nThis page describes the implemented data flow and retention behavior for the guarded public alpha.\nThe current public speech scope accepts MP3 through ElevenLabs Flash v2.5 text to speech and Scribe v2\nspeech to text. In particular, do not submit personal, confidential, regulated, biometric, or\nthird-party audio to speech-to-text. For every route, submit content only when you have the right to\nprocess it through the named providers and public-chain payment flow."},{"title":"Product changes and model retirement policy","description":"Review dated changes to the public interface, model catalog, pricing, payments, and documentation.","route":"/docs/changelog","text":" 2026-08-21\n\n- Published the exact five paid AI endpoints and four free discovery endpoints on the homepage,\n  endpoint overview, llms.txt, complete agent corpus, sitemap, and portable Agent Skill.\n- Deployed and indexed the guarded Flash v2.5/Scribe v2 MP3 speech scope after exact-build dark\n  activation, one non-retried provider/storage qualification, and public no-spend parity checks.\n  x402scan now resolves all nine public resources; the release automation did not spend USDC.\n- Added canonical Base64 JSON input to the existing speech-to-text endpoint while retaining the\n  standard multipart upload. Both forms decode and inspect the same bounded MP3 bytes before any\n  payment challenge, provider call, or settlement.\n- Published the JSON schema and a valid unpaid probe example so JSON-only agent directories can\n  verify and list speech to text without adding another public endpoint.\n\n 2026-08-19\n\n- Prepared the guarded speech catalog with elevenlabs/flash-v2.5 for MP3 text to speech and\n  elevenlabs/scribe-v2 for MP3 speech to text. Multilingual TTS and every other audio format remain\n  unavailable until their qualification gates pass.\n- Corrected the generated TTS guide to use the actual expires_at response field and added a\n  complete multipart STT request example that preserves the body across the unpaid and paid calls.\n- Updated OpenAPI, pricing, x402 discovery, the portable Agent Skill, privacy language, and model\n  documentation to describe measured speech usage and ElevenLabs' route-specific retention modes.\n- Clarified that ambiguous encrypted STT staging becomes inaccessible at its one-hour logical\n  expiry, while physical deletion can complete later through Azure storage lifecycle management.\n\n 2026-08-14\n\n- Matched Gemini 3.1 Flash-Lite Image's fixed-1K Vertex contract by retaining the selected aspect\n  ratio but omitting the redundant private provider imageSize field. Public requests still select\n  and receive a validated 1K image at the same $0.035 promotional total.\n- Corrected the private Vertex generateContent adapter so image size and aspect ratio use its\n  official generationConfig.imageConfig fields. The public image endpoint and request format do\n  not change.\n- Kept the service dark until the corrected immutable build passes one non-retried Flash-Lite\n  provider and encrypted-storage qualification. No USDC is used by that qualification.\n- Kept text-to-speech in ElevenLabs Zero Retention Mode and changed speech-to-text to the provider's\n  standard retained mode after the protected Scribe v2 qualification confirmed that STT ZRM was\n  unavailable for the production account. Onchain Router's encrypted STT staging is still deleted\n  after a definite result, while ElevenLabs may retain audio and transcripts under its own policy.\n- Kept every speech model and voice dark until the revised adapter passes one new non-retried\n  qualification and the remaining media, privacy, and release gates are complete.\n\n 2026-08-13\n\n- Selected gemini-3.1-flash-lite-image as the guarded Base-mainnet image model at 1K/1:1 after\n  the newer immutable Flash Image builds failed returned-aspect validation. The endpoint remains\n  POST /v1/images/generations; Flash Image and Pro Image remain dark.\n- Set the promotional successful-image total to $0.035: $0.034 catalog-fixed provider image price\n  plus the existing $0.001 successful-call fee and 0% service fee.\n- Kept the public service dark until this exact Flash-Lite build passes its one-shot provider and\n  encrypted-storage qualification. That qualification uses provider credit and no USDC.\n\n 2026-08-12\n\n- Added provider-neutral POST /v1/images/generations with the first Gemini image model, one\n  1024×1024 image per request, OpenAI-compatible URL or Base64 delivery, and a fixed $0.068\n  successful-call price during the 0% service fee launch promotion.\n- Added repository support for model-specific image_size and aspect_ratio, with 1K/1:1\n  defaults and exact integer price tiers. Additional Flash specifications plus Gemini 3.1\n  Flash-Lite Image and Gemini 3 Pro Image are enabled only for non-production qualification; the\n  Base mainnet catalog remains on its approved Flash 1K/1:1 route until expansion gates pass.\n- Added private AES-256-GCM encrypted image storage and capability URLs. Every response reports\n  url_retention_days: 7 and the exact url_expires_at; URLs stop serving at expiration and Azure\n  lifecycle management deletes the encrypted object after seven days.\n- Preserved the financial ordering for images: payment authorization is verified and durable before\n  generation, while settlement occurs only after the image and result are durable. Known failed\n  generations are not charged.\n- Updated the durable product description from an LLM-only router to an AI model router so the brand\n  remains stable as image, video, and audio capabilities are added.\n- Curated the public agent endpoint showcase to OpenAI-compatible Chat Completions, Anthropic-compatible Messages, categorized Models, detailed Pricing, and a Base USDC Balance lookup. Operational and private support routes remain functional but are no longer presented as separate products.\n- Organized /v1/models around available capability categories and endpoint compatibility. Text and\n  image generation are now available; video, speech-to-text, and text-to-speech categories will\n  appear only when those capabilities are released.\n- Added a readable unpaid-402 JSON explanation while retaining the official PAYMENT-REQUIRED header as the authoritative payment challenge.\n- Corrected Bazaar discovery identity so each paid challenge names the canonical public Onchain Router endpoint instead of the private Azure API hostname. This does not change payment amounts or settlement behavior.\n- Corrected Base mainnet payment persistence for the official x402 Permit2 upto payload emitted by the wallet client. The authorization nonce is now durable before any model request is sent.\n- Improved the wallet test page's phase-specific errors for nested wallet rejections, payment-persistence failures, and uncertain settlement. Server traces now include only a safe failure category, never signatures, payment payloads, prompts, or completions.\n- Activated a catalog-versioned 0% service fee launch promotion across production billing, pricing pages, endpoint descriptions, OpenAPI, model discovery, quotes, and receipts.\n- Corrected discovery's minimum successful price to include both the $0.001 minimum usage charge and the separate $0.001 fixed successful-call fee.\n- Simplified the local production buyer so it connects directly to the public endpoint without the retired dark-release canary credential.\n- Kept each request's signed spending limit and truthful dynamic discovery range. The final charge still uses measured usage and never exceeds the amount authorized by the buyer.\n\n 2026-08-11\n\n- Made the durable product identity provider-neutral: Onchain Router is now described as the x402-native LLM router, while Gemini remains clearly identified as the current MVP catalog rather than the brand itself.\n- Published the progressive-branch mark through root favicon, manifest, Open Graph, Twitter, and OpenAPI logo metadata so discovery directories and social previews can resolve the intended logo.\n- Declared explicit OpenAPI auth modes for public, receipt-protected, and x402-paid operations so x402scan can register supporting resources without treating free endpoints as broken paywalls.\n- Simplified every customer-facing payment reference to Base mainnet and USDC, removing internal-network explanations, redundant payment-value wording, and the pre-launch unavailability notice.\n- Reworked the website into a wider editorial layout that uses large screens more effectively.\n- Reduced heading sizes across the home page, documentation, model catalog, pricing, status, and legal pages.\n- Replaced the operating-system font fallbacks with a self-hosted Plus Jakarta Sans variable font and a sharper, more consistent weight system across the public site.\n- Applied the same font to the wordmark, navigation, and Base Mainnet label, and refreshed search as a modern command palette.\n- Added content-versioned stylesheet and script URLs so a browser cannot combine updated page markup with stale interface styles.\n- Replaced the temporary letter tile with the selected progressive-branch logo, representing one interface expanding into multiple onchain capabilities, and added a matching favicon asset.\n- Rewrote page titles, descriptions, navigation labels, and introductory copy in clearer language. Technical abbreviations are now explained on first use when the surrounding page is intended for a broad reader.\n- Expanded llms-full.txt into a one-request package containing the product overview, every guide, generated endpoint references, the model catalog, service status, legal drafts, and portable Agent Skill references. Added HTML discovery links and an XML sitemap so agents can find these surfaces without guessing paths.\n- Added local browser checks for wide desktop, laptop, tablet, and mobile layouts. This local review does not publish or activate the paid service.\n\n 2026-08-10\n\n- Published the first custom single-origin website and documentation build.\n- Added HTML, per-page Markdown, llms.txt, llms-full.txt, OpenAPI, sanitized catalog, and Agent Skill surfaces.\n- Set the current paid-inference minimum to 1000 atomic USDC (0.001000 USDC).\n- Qualified the initial Gemini text candidates before selecting the production catalog.\n- Added explicit handling for reasoning-token output ceilings, empty visible responses, actual settlement, and durable receipts.\n- Published the Base mainnet public-alpha contract using USDC, an authoritative per-request cap, and a global conservative estimated-loss breaker. Hourly and daily payer caps were later removed by ADR-024.\n- Removed payer registration and payer allowlisting; every facilitator-verified wallet may purchase under the same limits.\n- Kept automated payment conformance fixtures outside the documented production environment.\n- Approved seven GA Gemini text aliases for mainnet-alpha routing. The gemini-3.1-pro-preview route remains disabled on mainnet.\n- Added fail-closed production configuration, a one-origin site/API deployment, public per-receipt\n  capabilities, a least-privilege provider federation role, and a separately approved production\n  infrastructure workflow. Synthetic reconciliation is now forbidden in production.\n- Revalidated the public catalog against current Google model and pricing sources, including the\n  65,536-token output limit for gemini-3.1-flash-lite.\n- Expanded the privacy and service-terms release candidates and added automated checks for stale\n  test/private-alpha language, operator-only configuration, enabled-model count, and legal sections.\n\n Deprecation policy\n\nModel aliases can change only through an immutable catalog version. A retiring model shows its retirement date in /v1/models and /models. The service does not silently map an alias to a more expensive tier.\n\nClients should discover models rather than hard-code them indefinitely. Before each deployment and periodically during long-running sessions, refresh the catalog and reject an alias that is unavailable, past retirement, or outside the caller's model allowlist.\n\nThe Gemini 2.5 compatibility routes have a conservative operational removal date of 2026-10-16. gemini-3.1-pro-preview is a testing-only preview and cannot become a production default without a new approved catalog and provider gate."},{"title":"Models and pricing","description":"Current model catalog and rates","route":"/models","text":"# Models and pricing\n\nCatalog version: `d815ab0e8989b9e466280031ee859b916a676070cabc0e5b33e30d626957d9c0`. The catalog is organized by capability. Only categories returned by `GET /v1/models` are available. Text generation, image generation, text to speech, and speech to text are available in this catalog; video generation remains unavailable. The public speech catalog exposes ElevenLabs Flash v2.5 for MP3 text to speech and Scribe v2 for MP3 speech to text. Other speech models and formats remain unavailable until they pass their release gates.\n\n## Available categories\n\n- **Text generation** (`text_generation`): `POST /v1/chat/completions` (openai), `POST /v1/messages` (anthropic)\n- **Image generation** (`image_generation`): `POST /v1/images/generations` (openai)\n- **Text to speech** (`text_to_speech`): `POST /v1/audio/speech` (openai-shaped)\n- **Speech to text** (`speech_to_text`): `POST /v1/audio/transcriptions` (openai)\n\n## Available models\n\n| Model | Capability | Availability | Published price | Delivery and limit |\n|---|---|---|---|---|\n| `gemini-3.6-flash` | Text generation | ga | $1.5 input · $7.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.5-flash-lite` | Text generation | ga | $0.3 input · $2.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.5-flash` | Text generation | ga | $1.5 input · $9 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.1-flash-lite` | Text generation | ga | $0.25 input · $1.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-3.1-flash-lite-image` | Image generation | ga | 1K (default) $0.035000 | One image · 1 aspect ratios · hosted URL 7 days · optional Base64 |\n| `gemini-2.5-flash` | Text generation | ga | $0.3 input · $2.5 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-2.5-pro` | Text generation | ga | $1.25 input · $10 output per 1M tokens | 65,536 maximum output tokens |\n| `gemini-2.5-flash-lite` | Text generation | ga | $0.1 input · $0.4 output per 1M tokens | 65,536 maximum output tokens |\n| `elevenlabs/flash-v2.5` | Text to speech | ga | $0.05 per 1K characters | 2,000 maximum characters |\n| `elevenlabs/scribe-v2` | Speech to text | ga | $0.22 per audio hour | 30 maximum minutes |\n\nA 0% service fee launch promotion is active. Every successful call adds the disclosed 1000-atomic-USDC ($0.001000) fixed fee. The separate minimum usage charge applies to measured text and speech usage. 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 final spending limit from the live HTTP 402 response before signing, and the final amount from the durable receipt."}]