# 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://llm.agenticfi.wtf/llms.txt). For exact schemas, read [OpenAPI](https://llm.agenticfi.wtf/openapi.json). For live payment terms, always use the runtime HTTP 402 response. --- # Onchain Router overview Canonical source: [https://llm.agenticfi.wtf/](https://llm.agenticfi.wtf/) 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 and USDC. Agents must validate the network, asset, recipient, expiry, payment scheme, and maximum amount and must enforce local per-request and per-session limits. ## 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. - The final settlement never exceeds the signed maximum. - 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 signed maximum, and the durable receipt for the final settled amount. Use the OpenAPI document for the nine public request and response schemas. --- # Pay for AI model requests one at a time Canonical source: [https://llm.agenticfi.wtf/docs](https://llm.agenticfi.wtf/docs) Last reviewed: 2026-08-21. 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. > Payments use USDC on Base mainnet. Any wallet with a valid x402 payment authorization may pay; no payer registration is required. ## Choose your path - **Choose a capability:** compare all [five paid AI endpoints and four free discovery endpoints](https://llm.agenticfi.wtf/docs/endpoints). - **Make your first request:** follow the [step-by-step guide](https://llm.agenticfi.wtf/docs/quickstart) with a dedicated wallet that holds only a small amount of USDC. - **Connect an autonomous agent:** install the [portable Agent Skill](https://llm.agenticfi.wtf/docs/agents) and set a hard spending limit in atomic USDC units. - **Connect a backend service:** start with the generated guide for [Chat Completions](https://llm.agenticfi.wtf/docs/api/chat-completions), [Messages](https://llm.agenticfi.wtf/docs/api/messages), [Image Generations](https://llm.agenticfi.wtf/docs/api/image-generations), [Text to Speech](https://llm.agenticfi.wtf/docs/api/audio-speech), or [Speech to Text](https://llm.agenticfi.wtf/docs/api/audio-transcriptions). ## What stays familiar Text 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`. ## What x402 adds The 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. You 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. --- # Choose the right endpoint Canonical source: [https://llm.agenticfi.wtf/docs/endpoints](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/docs/api/chat-completions) for OpenAI-compatible clients. - [Messages](https://llm.agenticfi.wtf/docs/api/messages) for Anthropic-compatible clients. - [Image Generations](https://llm.agenticfi.wtf/docs/api/image-generations) for image output. - [Text to Speech](https://llm.agenticfi.wtf/docs/api/audio-speech) and [Voices](https://llm.agenticfi.wtf/docs/api/audio-voices) for hosted MP3 audio. - [Speech to Text](https://llm.agenticfi.wtf/docs/api/audio-transcriptions) for MP3 transcription. - [Models](https://llm.agenticfi.wtf/docs/api/models), [Pricing](https://llm.agenticfi.wtf/docs/api/pricing), and [Balance](https://llm.agenticfi.wtf/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. --- # What happens during a paid request Canonical source: [https://llm.agenticfi.wtf/docs/how-it-works](https://llm.agenticfi.wtf/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 `upto` payment requirement that is tied to the request. 3. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, and maximum 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 never exceeds the signed maximum. - Prompts, completions, raw payment payloads, private keys, and provider credentials are excluded from telemetry and receipts. --- # Production environment and funding Canonical source: [https://llm.agenticfi.wtf/docs/environments](https://llm.agenticfi.wtf/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 `upto` - 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. 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. --- # Make your first paid AI request Canonical source: [https://llm.agenticfi.wtf/docs/quickstart](https://llm.agenticfi.wtf/docs/quickstart) Last reviewed: 2026-08-21. 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. ## 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. 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. 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://llm.agenticfi.wtf/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 `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. 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 `upto` payment scheme, and a maximum no higher than your local spending limit. ## 5. Authorize and read the result Confirm 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. Read the visible answer from: ```text choices[0].message.content ``` Then record the receipt ID, authorized maximum, actual settled amount, 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. Increase `max_tokens`, obtain a new quote, and retry. - 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. --- # Protect the wallet that pays for requests Canonical source: [https://llm.agenticfi.wtf/docs/wallet-security](https://llm.agenticfi.wtf/docs/wallet-security) Last reviewed: 2026-08-11. Your wallet signs the payment authorization on your device. Onchain Router receives the authorization but never receives your seed phrase or wallet private key. ## Safe mainnet wallet policy - Create a new account used only for Onchain Router. - Hold only the USDC needed for the next few requests. - Set a hard limit for each request in atomic USDC units. The local mainnet acceptance client uses `1000000`, which means `1.000000` USDC; 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`, `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. 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. --- # Connect an autonomous agent safely Canonical source: [https://llm.agenticfi.wtf/docs/agents](https://llm.agenticfi.wtf/docs/agents) Last reviewed: 2026-08-21. 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. ## Discovery order 1. Read `/llms.txt` for a short, curated map of the website and its authoritative resources. 2. Read `/llms-full.txt` when the agent needs the complete public documentation in one request instead of visiting each page separately. 3. Read `/v1/models` to get the current capability categories, model aliases, limits, and compatible endpoints. 4. Read `/v1/pricing` for detailed rates and `/v1/audio/voices` before a text-to-speech request. 5. Read `/openapi.json` to get the machine-readable request and response contract for all nine public routes. 6. Submit the request and treat Hypertext Transfer Protocol (HTTP) status 402 as the expected payment step. 7. Check every live payment field before signing. ## Endpoint selection - Use `/v1/chat/completions` for OpenAI-compatible text and `/v1/messages` for Anthropic-compatible text. - Use `/v1/images/generations` for an image, `/v1/audio/speech` for an MP3, and `/v1/audio/transcriptions` for a transcript. - Use `/v1/models`, `/v1/pricing`, `/v1/audio/voices`, and `/v1/balance` for free discovery. They must never ask the agent to sign. Read the [endpoint overview](https://llm.agenticfi.wtf/docs/endpoints) for the exact public surface and the generated endpoint guides for request-specific fields. The `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`. ## Required local policy - Base mainnet only (`eip155:8453`); reject every other network. - Dedicated, minimally funded mainnet wallet only. - Limits for each request and each session, represented as integer atomic United States Dollar Coin (USDC) strings. - Explicit model allowlist. - Recipient and USDC contract allowlists. - No payer registration: any wallet with a valid facilitator-verified authorization may pay. - One stable idempotency key across the unpaid request and the signed retry so the service can prevent duplicate work. - No blind retry after provider or settlement ambiguity. ## Stable output Return 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. ## Install Copy 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. --- # Code examples for text, image, and speech Canonical source: [https://llm.agenticfi.wtf/docs/sdk-examples](https://llm.agenticfi.wtf/docs/sdk-examples) Last reviewed: 2026-08-21. 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. ## TypeScript Construct `paymentFetch` with the official `@x402/core`, `@x402/evm`, and `@x402/fetch` client packages. Then pass it to the repository wrapper: ```ts import { OnchainRouterClient } from '@onchain-router/client'; const router = new OnchainRouterClient({ baseUrl: process.env.ONCHAIN_ROUTER_URL!, paymentFetch, }); const response = await router.chat({ model: 'gemini-3.6-flash', messages: [{ role: 'user', content: 'Explain why the sky appears blue.' }], max_tokens: 1024, stream: false, }); const body = await response.json(); console.log(body.choices[0].message.content); console.log(response.headers.get('x-receipt-id')); ``` The 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. ## Python The maintained repository example accepts an `httpx.Client` that is already wrapped by the official x402 software development kit for Python: ```python result = paid_chat(payment_client) print(result["choices"][0]["message"]["content"]) ``` Do not implement Ethereum Improvement Proposal 712 (EIP-712), Permit2, or payment settlement code in your application. Use the official libraries. ## Direct Hypertext Transfer Protocol request An ordinary unpaid request is useful for inspecting the challenge: ```bash curl -i "$ONCHAIN_ROUTER_URL/v1/chat/completions" \ -H "content-type: application/json" \ -H "x-idempotency-key: $(uuidgen)" \ --data '{"model":"gemini-3.6-flash","messages":[{"role":"user","content":"Say hello."}],"max_tokens":512,"stream":false}' ``` Expect Hypertext Transfer Protocol (HTTP) status 402. Do not construct the paid retry by hand. Pass the response to an official x402 buyer client. ## Other capabilities Use the same payment-aware client for every paid route: - [Messages](https://llm.agenticfi.wtf/docs/api/messages) accepts the Anthropic-compatible message shape. - [Image Generations](https://llm.agenticfi.wtf/docs/api/image-generations) accepts an image model, prompt, size, aspect ratio, and response format. - [Text to Speech](https://llm.agenticfi.wtf/docs/api/audio-speech) accepts text, model, voice, MP3 response format, and optional speed. - [Speech to Text](https://llm.agenticfi.wtf/docs/api/audio-transcriptions) accepts one MP3 either as canonical Base64 JSON or as multipart form data. Do 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. --- # How authorization, charges, and receipts work Canonical source: [https://llm.agenticfi.wtf/docs/payment-receipts](https://llm.agenticfi.wtf/docs/payment-receipts) Last reviewed: 2026-08-12. 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. ## Pricing terms - **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. - **Authorized maximum:** the request-specific spending limit approved by the buyer. - **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 charge:** `1000` atomic United States Dollar Coin (USDC) units, or `0.001000` USDC, for each successful paid model request. - **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. - **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. 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. It never settles above the signed maximum. ## 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, 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. 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. --- # Understand errors and retry safely Canonical source: [https://llm.agenticfi.wtf/docs/errors-retries](https://llm.agenticfi.wtf/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. --- # How request content is stored and deleted Canonical source: [https://llm.agenticfi.wtf/docs/privacy](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/docs/changelog](https://llm.agenticfi.wtf/docs/changelog) Last reviewed: 2026-08-19. ## 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://llm.agenticfi.wtf/models](https://llm.agenticfi.wtf/models) Catalog 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. ## 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 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. --- # Create an OpenAI-compatible LLM response Canonical source: [https://llm.agenticfi.wtf/docs/api/chat-completions](https://llm.agenticfi.wtf/docs/api/chat-completions) **POST /v1/chat/completions** Operation ID: `createChatCompletion`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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 highest possible charge; it is not the final amount charged. 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, payment scheme, and maximum 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. - **409:** Idempotency key reused with a different effective request - **503:** Provider, payment, or safety dependency unavailable --- # Create an Anthropic-compatible LLM response Canonical source: [https://llm.agenticfi.wtf/docs/api/messages](https://llm.agenticfi.wtf/docs/api/messages) **POST /v1/messages** Operation ID: `createMessage`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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 highest possible charge; it is not the final amount charged. 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, payment scheme, and maximum 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. - **409:** Idempotency key reused with a different effective request - **503:** Provider, payment, or safety dependency unavailable --- # Generate an image from a text prompt Canonical source: [https://llm.agenticfi.wtf/docs/api/image-generations](https://llm.agenticfi.wtf/docs/api/image-generations) **POST /v1/images/generations** Operation ID: `createImageGeneration`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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, payment scheme, and maximum 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. - **409:** Idempotency key reused with a different effective request - **503:** Provider, payment, or safety dependency unavailable --- # List enabled curated text-to-speech voices Canonical source: [https://llm.agenticfi.wtf/docs/api/audio-voices](https://llm.agenticfi.wtf/docs/api/audio-voices) **GET /v1/audio/voices** Operation ID: `listAudioVoices`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/openapi.json). ## Responses - **200:** Curated public voice aliases; upstream voice IDs are private. --- # Generate a hosted speech audio asset Canonical source: [https://llm.agenticfi.wtf/docs/api/audio-speech](https://llm.agenticfi.wtf/docs/api/audio-speech) **POST /v1/audio/speech** Operation ID: `createSpeech`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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, payment scheme, and maximum 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. - **409:** Idempotency key reused with a different effective request - **503:** Provider, payment, or safety dependency unavailable --- # Transcribe one bounded audio upload Canonical source: [https://llm.agenticfi.wtf/docs/api/audio-transcriptions](https://llm.agenticfi.wtf/docs/api/audio-transcriptions) **POST /v1/audio/transcriptions** Operation ID: `createTranscription`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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 a truthful duration-based maximum. 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://llm.agenticfi.wtf/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, payment scheme, and maximum 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. - **409:** Idempotency key reused with a different effective request - **503:** Provider, payment, or safety dependency unavailable --- # List available capability categories, endpoints, and models Canonical source: [https://llm.agenticfi.wtf/docs/api/models](https://llm.agenticfi.wtf/docs/api/models) **GET /v1/models** Operation ID: `listModels`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/docs/api/pricing](https://llm.agenticfi.wtf/docs/api/pricing) **GET /v1/pricing** Operation ID: `listPricing`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/docs/api/balance](https://llm.agenticfi.wtf/docs/api/balance) **GET /v1/balance** Operation ID: `getWalletBalance`. The canonical machine-readable schema is [OpenAPI](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/status](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/legal/privacy](https://llm.agenticfi.wtf/legal/privacy) Last reviewed: 2026-08-21. 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-21. --- # Public alpha service terms Canonical source: [https://llm.agenticfi.wtf/legal/terms](https://llm.agenticfi.wtf/legal/terms) Last reviewed: 2026-08-21. 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 maximum amount. The buyer approves an `upto` maximum. Text requests settle measured token usage, text-to-speech requests settle measured character usage, speech-to-text requests settle validated audio duration, and image requests settle the fixed per-image catalog price. Settlement occurs only after the result is safely stored, and the charge can never exceed the approved maximum. A 0% service fee launch promotion is active. Current model rates, the $0.001 fixed successful-call fee, and the separate measured-usage minimum are published in the live catalog. Network fees and third-party wallet costs may be separate. ## 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 approved maximum and the final amount charged. 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-21. --- # Portable Agent Skill Canonical source: [https://llm.agenticfi.wtf/skill/onchain-router/SKILL.md](https://llm.agenticfi.wtf/skill/onchain-router/SKILL.md) Use the bundled scripts for deterministic discovery and payment. Keep signing inside the official x402 and EVM packages; never construct Permit2 data or payment cryptography manually. ## Workflow 1. Run `node scripts/models.mjs`, choose an available capability category, and select one of its enabled aliases and supported endpoints. 2. Read [references/security.md](https://llm.agenticfi.wtf/skill/onchain-router/references/security.md) before configuring a wallet. 3. Set a Base mainnet buyer, expected recipient, per-call cap, and session cap. A dedicated minimally funded buyer is strongly recommended but not required by the service. 4. Run `node scripts/wallet-status.mjs` and confirm the address, network, and USDC balance. 5. For text, run `node scripts/chat.mjs --model --prompt --max-tokens `. For images or MP3 speech, follow the matching `POST /v1/images/generations`, `POST /v1/audio/speech`, or JSON-or-multipart `POST /v1/audio/transcriptions` contract in [references/api.md](https://llm.agenticfi.wtf/skill/onchain-router/references/api.md) with an official x402 client. 6. Return the result, model, usage, payment, and receipt. For images, also return `url_retention_days` and `url_expires_at`. For TTS, return `expires_at`. Treat every complete media URL as a bearer capability and do not log or share it unnecessarily. 7. If the request fails, classify it using [references/errors.md](https://llm.agenticfi.wtf/skill/onchain-router/references/errors.md). Retry only when that reference says the outcome is definite. Read [references/api.md](https://llm.agenticfi.wtf/skill/onchain-router/references/api.md) when constructing advanced OpenAI-compatible bodies. Read [references/payments.md](https://llm.agenticfi.wtf/skill/onchain-router/references/payments.md) when explaining the maximum, settlement, or receipt. ## Required environment - `ONCHAIN_ROUTER_URL`: one canonical origin; no `/v1` suffix. - `ONCHAIN_ROUTER_RECIPIENT`: exact expected EVM recipient. - `ONCHAIN_ROUTER_BUYER_PRIVATE_KEY`: mainnet buyer key, preferably dedicated and minimally funded, provided only to the local process. - `ONCHAIN_ROUTER_MAINNET_ACKNOWLEDGED`: must equal `true`; confirms that the caller authorizes a Base mainnet USDC payment. - `ONCHAIN_ROUTER_MAX_CALL_USDC_ATOMIC`: positive integer; defaults to `10000`. - `ONCHAIN_ROUTER_MAX_SESSION_USDC_ATOMIC`: positive integer; defaults to the per-call cap. - `ONCHAIN_ROUTER_SESSION_SPENT_USDC_ATOMIC`: already-settled amount in this caller-managed session; defaults to `0`. Never place environment values in the skill directory, source control, logs, prompts, or tool output. ## Output rules - Prefer visible answer text over the raw provider body. - Include the actual settled atomic amount and transaction reference. - Treat `finishReason: "length"` as a successful but truncated answer. - Download hosted images before `url_expires_at`; the URL is served for seven days and behaves like a bearer capability. - Download hosted TTS audio before `expires_at`; the URL is served for 24 hours and behaves like a bearer capability. - Warn before STT that ElevenLabs processes uploaded audio and transcript output in standard retained mode. Do not send sensitive, regulated, biometric, or third-party audio without the necessary rights and consent. - Do not print provider thought signatures by default. - Treat every successful call as a Base mainnet USDC payment. Never use the skill without explicit human authorization and strict local spending caps. The service does not require payer registration. --- # Agent Skill reference: api Canonical source: [https://llm.agenticfi.wtf/skill/onchain-router/references/api.md](https://llm.agenticfi.wtf/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://llm.agenticfi.wtf/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://llm.agenticfi.wtf/skill/onchain-router/references/payments.md](https://llm.agenticfi.wtf/skill/onchain-router/references/payments.md) HTTP 402 is the expected first response. Validate the runtime requirement, sign locally with official x402 primitives, and retry the identical body and idempotency identity. The supported payment network is Base mainnet (`eip155:8453`), and settlement uses USDC. The authorization maximum is request-specific: text reserves output through `max_tokens`, TTS uses a conservative character bound, STT uses locally inspected audio duration, and image generation uses the selected specification price. Actual settlement uses normalized token, character, or audio-duration usage—or the successful image price—plus cataloged fees and the disclosed minimum. It never exceeds the signed maximum. Return the settlement amount from the standard `PAYMENT-RESPONSE`, plus `X-Receipt-ID` and transaction hash. Do not treat the quote or maximum as the actual charge. 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://llm.agenticfi.wtf/skill/onchain-router/references/errors.md](https://llm.agenticfi.wtf/skill/onchain-router/references/errors.md) Correct and retry with a new quote after invalid JSON, invalid model, invalid output ceiling, or expiry. Treat HTTP 402 as the normal authorization step. Stop on `wallet_request_cap_exceeded`, `wallet_hour_cap_exceeded`, or `wallet_day_cap_exceeded`; reduce the request only for a per-request limit, otherwise wait for reset or operator review. These controls apply automatically to every verified payer and run before provider execution. 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. --- # Agent Skill reference: security Canonical source: [https://llm.agenticfi.wtf/skill/onchain-router/references/security.md](https://llm.agenticfi.wtf/skill/onchain-router/references/security.md) Use a dedicated Base mainnet wallet holding only the USDC required for a small number of calls. Default-deny every network except `eip155:8453`, every asset except official Base USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, and every recipient except the configured expected address. Keep per-call and session caps as integer atomic USDC. Reject an expired requirement, unexpected recipient, non-USDC asset, non-mainnet network, unsupported scheme, or maximum above the remaining cap. Require `ONCHAIN_ROUTER_MAINNET_ACKNOWLEDGED=true`. The service accepts any facilitator-verified payer without registration. Never print, store, transmit, or commit the buyer private key. Never log raw payment signatures or complete payment payloads. Never include provider keys or custom provider URLs in a request. 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.