Agent task recipes

These recipes use the live catalog and one shared payment lifecycle. First read GET /v1/models and GET /v1/pricing. Then create and persist one idempotency key, send a valid unsigned request, validate the request-specific HTTP 402 challenge, sign locally through an official x402 exact buyer, and retry the identical request. A successful response is released only after its result, settlement, and receipt are durable.

An empty, incomplete, or malformed unsigned JSON request returns a discovery-only inspection challenge. It has X-Onchain-Router-Challenge-Kind: inspection and price.type: inspection. Do not sign it. Submit one of the valid bodies below to receive the request-specific exact price first.

Answer a question with Chat Completions

Use POST /v1/chat/completions when an application already uses OpenAI-shaped messages and choices.

{
  "model": "gemini-3.6-flash",
  "messages": [{ "role": "user", "content": "Explain x402 in two short sentences." }],
  "max_tokens": 256,
  "stream": false
}

Read the answer from choices[0].message.content. Pricing uses a conservative input estimate plus 10% of requested output and the published fixed/minimum policy. Set a realistic max_tokens. If the provider or settlement outcome is unknown, recover with the same body and idempotency key. Never create a second paid job automatically.

Use the Anthropic Messages shape

Use POST /v1/messages when the caller already expects Anthropic-shaped content blocks. This is a compatibility format, not a claim that the selected provider is Anthropic.

{
  "model": "gemini-3.6-flash",
  "system": "Answer concisely.",
  "messages": [{ "role": "user", "content": "Explain x402 in two short sentences." }],
  "max_tokens": 256,
  "stream": false
}

Read text blocks from content. The payment and recovery rules are identical to Chat Completions.

Generate one image

Use POST /v1/images/generations. Select a model whose category is image_generation; supported sizes and aspect ratios are model-specific.

{
  "model": "gemini-3.1-flash-lite-image",
  "prompt": "A geometric blue bridge on a white background",
  "n": 1,
  "image_size": "1K",
  "aspect_ratio": "1:1",
  "response_format": "url"
}

The response contains one hosted URL by default, its expiry, and the settled price. Hosted image URLs are bearer capabilities and expire after seven days. Download the image before expiry without putting the complete URL in logs. Image pricing varies by selected model and image size; refresh /v1/pricing before a request.

Generate speech

Use POST /v1/audio/speech. Select a text_to_speech model and a public voice alias from GET /v1/audio/voices.

{
  "model": "elevenlabs/flash-v2.5",
  "input": "Hello from Onchain Router.",
  "voice": "reader",
  "response_format": "mp3",
  "speed": 1
}

The response is JSON with a hosted MP3 capability URL, not an OpenAI binary-audio response. The URL expires after 24 hours. Billing uses the normalized input character count and the published model rate.

Transcribe speech

Use POST /v1/audio/transcriptions with canonical Base64 JSON or multipart form data. For an agent-safe JSON call:

{
  "model": "elevenlabs/scribe-v2",
  "audio_base64": "BASE64_MP3_WITHOUT_A_DATA_URL_PREFIX",
  "file_format": "other",
  "response_format": "json"
}

The server validates the audio locally before payment verification and bills by measured duration. The CLI/SDK requires explicit human acknowledgement of provider retention before sending audio. Onchain Router deletes its staging copy after a definite outcome; the provider may retain audio and transcripts independently. Never upload sensitive or third-party audio without permission.

Change models safely

Do not guess aliases or reuse a model copied from an old example. Read GET /v1/models, select a model from the required category, confirm its supported endpoint and options, and ensure the human-owned Buyer Runtime policy permits it. Changing the model changes the effective request: create a new idempotency key and obtain a new 402 challenge.

Inspect without spending

This command sends no signature and cannot settle USDC:

curl -i https://onchainrouter.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  --data '{}'

Expect HTTP 402, PAYMENT-REQUIRED, and the inspection marker. For the full five-route compatibility matrix, run the repository validator against a local or explicitly selected origin:

GITHUB_SHA="$(git rev-parse HEAD)" pnpm agent:discovery-check \
  --origin https://onchainrouter.dev \
  --profile production

The validator never creates or sends a payment signature. It derives the checked-out commit and, when GITHUB_SHA is set, requires it to match that exact HEAD, so the report stays bound to reviewed source. A green result does not prove a paid settlement, provider response, wallet integration, or external marketplace indexing.

Recover and verify

On success, retain the original idempotency key, response, X-Receipt-ID, actual atomic USDC charge, transaction, and verified receipt in private application state. On an ambiguous outcome, use the Buyer Runtime receipt/recovery method with the same key. Do not blindly retry, change the request, or expose the receipt capability.