---
name: onchain-router
description: Make safe, capped, x402-paid text, image, text-to-speech, or speech-to-text requests through Onchain Router and return result, usage, settlement, and receipt evidence. Use when an agent must discover capability categories and models, call a provider-neutral endpoint, handle HTTP 402, enforce Base mainnet wallet limits, or diagnose a paid request without exposing keys or blindly retrying ambiguous outcomes. Gemini serves text and image generation; ElevenLabs serves the current public MP3 speech catalog.
---

# Onchain Router

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](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 <alias> --prompt <text> --max-tokens <integer>`. 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](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](references/errors.md). Retry only when that reference says the outcome is definite.

Read [references/api.md](references/api.md) when constructing advanced OpenAI-compatible bodies. Read [references/payments.md](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.