# OmniRail: setup guide for AI agents

OmniRail gives you every LLM, image, video, image-editing, voice, embedding, rerank, decision model (Claude, GPT, Gemini, Grok, DeepSeek, Qwen, Kimi, FLUX, GPT Image, Veo, Sora, Kling, Seedance, Whisper, Deepgram, MiniMax speech, Voyage, Cohere Rerank, Jev…) through one MCP server and one OpenAI-compatible API. It is paid in crypto on Robinhood Chain (chain 4663). Prices are list prices per call (GET /api/v1/models); while the $RAIL pool is funded they sit about 7% below what the provider itself charges.

Follow these steps in order. Ask your human only where it says so.

## 1. Choose how you will pay (ask your human)

Ask exactly one question: **"Do you want to give me a prepaid OmniRail API key, or a dedicated wallet with USDG on Robinhood Chain that I can spend from myself?"**

- **A. API key** (recommended for humans): they open https://omnirail.org/dashboard, connect a wallet, top up with USDG or ETH, create a key (optionally with a spend limit) and give you the `orl_…` secret. On a phone without a wallet they can sign in by approving it from a signed-in computer at https://omnirail.org/link, or use the Android app (https://omnirail.org/app). They can also top up with $RAIL (valued at its on-chain pool price; live rate: GET https://omnirail.org/api/rail/quote?usd=25).
  Suggest a **scoped key** sized to the task, for example: *"Please create a key for me that is text only, limited to `anthropic/*` and `openai/gpt-5*`, with a $5 limit, expiring tomorrow."* Keys can be restricted to modalities (text, image, video, voice, embeddings, rerank, decisions, autopilot, trade), models (exact ids or patterns ending in `*`), a max text output price, IP addresses and an expiry date.
  To trade, also ask for **trade limits** on that key: allowed tokens, a max USD per trade and per day, a max slippage, and an amount above which they approve each trade themselves. A scoped key also needs the `trade` modality. For Stock Tokens, the key owner must also tick **Stock Tokens eligibility** on that key (they confirm they are not a US person and not in a restricted country): only they can, never you.
- **B. Agent wallet (x402)**: they give you the private key of a **new, dedicated** wallet holding a small amount of USDG (0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168) on Robinhood Chain. You buy credit yourself with x402, within a daily budget. No ETH is needed for gas.

Never ask for, accept or store the key of their main wallet. If they paste one, tell them to create a dedicated wallet instead.

## 2. Install the MCP server

Pick the block for the client you run in. Replace placeholders with what your human gave you. Prefer writing secrets to the client's config or environment, never to files that are committed.

### Claude Code
A (key):
```bash
claude mcp add --transport http omnirail https://omnirail.org/api/mcp --header "Authorization: Bearer orl_YOUR_KEY"
```
B (wallet):
```bash
claude mcp add omnirail -e OMNIRAIL_WALLET_KEY=0xDEDICATED_WALLET_KEY -e OMNIRAIL_DAILY_BUDGET_USD=20 -- npx -y https://omnirail.org/downloads/omnirail-mcp.tgz
```

### Codex CLI (~/.codex/config.toml)
```toml
[mcp_servers.omnirail]
command = "npx"
args = ["-y", "https://omnirail.org/downloads/omnirail-mcp.tgz"]
env = { OMNIRAIL_API_KEY = "orl_YOUR_KEY" }   # or OMNIRAIL_WALLET_KEY = "0x…"
```

### Cursor, Windsurf, Claude Desktop, and other JSON configs
Remote (key):
```json
{ "mcpServers": { "omnirail": { "url": "https://omnirail.org/api/mcp", "headers": { "Authorization": "Bearer orl_YOUR_KEY" } } } }
```
Local (key or wallet, also enables saving files to disk):
```json
{ "mcpServers": { "omnirail": { "command": "npx", "args": ["-y", "https://omnirail.org/downloads/omnirail-mcp.tgz"], "env": { "OMNIRAIL_API_KEY": "orl_YOUR_KEY" } } } }
```

The local server (npx) accepts: `OMNIRAIL_API_KEY`, `OMNIRAIL_WALLET_KEY`, `OMNIRAIL_TOPUP_USD` (default 5), `OMNIRAIL_DAILY_BUDGET_USD` (default 20). The remote server needs a key.

Most clients load new MCP servers on restart. Tell your human if a restart is needed.

## 3. Verify

1. Call `list_models` (works without a key) and confirm you see models.
2. Call `account_balance`. With a wallet (B) the first paid call tops up automatically; the balance appears after it.

## 4. Tools

| Tool | Use it for |
|---|---|
| `list_models` | Find a model id and its live price. Filter with kind=text/image/video/tts/stt/embedding/rerank/decision and search. |
| `chat` | Ask any LLM. Set `max_tokens` to bound the cost. Model `auto` (or `auto:cheap`, `auto:fast`, `auto:best`) lets OmniRail pick per request; the answer names the model used. `web: true` grounds with live search; `files` attaches PDFs; `images` attaches pictures. |
| `generate_image` | Images from a prompt, optional reference images. `save_to` writes the file (local server). |
| `edit_image` | Change existing images (paths or URLs). Needs a model marked "edits". |
| `generate_video` | Starts a video job and returns an id + token. Add `webhook_url` to get a signed POST when it ends instead of polling. |
| `get_video` | Poll every ~30 s until completed; `save_to` downloads the MP4 (local server). |
| `embed` | Vectors for semantic search / RAG (Voyage, Gemini Embedding, OpenAI, BGE…); multimodal models take images. |
| `rerank` | Score documents against a query (Cohere, Voyage, Qwen rerankers); use after a search. |
| `decide` | Ask a decision model (Jev) typed questions about a state: `noul` (probability of yes), `choice` (one of your options), `score` (your ordered levels), `box` (where in an image). Use it to gate a risky tool call, triage or classify, then branch on the probability with your own threshold. Answers are free, input tokens are billed. |
| `build` | Autopilot: one brief → OmniRail plans and produces copy, images, edits, video and voice, picking a model per step. Returns a job id. Takes `webhook_url` too. |
| `get_job` | Poll a build job every ~20 s: texts inline, URLs for images/audio/videos; `save_to` downloads everything (local server). |
| `speak` | Text to speech (mp3) with any voice model; `save_to` writes the file (local server). |
| `transcribe` | Speech to text from a file path (local), URL or data URL; `timestamps` adds segments. |
| `account_balance` | Remaining credit and live markup. |
| `market_tokens` / `market_price` / `wallet_balances` | Robinhood Chain market data: tradable tokens (ETH, WETH, USDG, $RAIL, the listed Pons launchpad tokens, curated Stock Tokens for eligible holders), spot + 30-min average price, wallet balances. |
| `trade_quote` | Quote a swap for YOUR wallet (taker): route, price, impact, min received, fee, gas, and the transactions to sign (approve, Permit2 signature, swap). Routes across every DEX on Robinhood Chain through Uniswap's Aggregator Hooks: `sources` names the venues, `vs_uniswap_only` what Uniswap alone would give. |
| `trade_submit` | Hand over the swap signed by your own wallet (or its tx hash); OmniRail checks it matches the quote and broadcasts it. |
| `trade_status` | Pending / confirmed / failed, the amounts actually received and the explorer link. |

Every call reserves its worst-case cost first and charges the real cost after. Failed calls are free.

## 5. Rules for you

- Before a single action that could cost more than $1 (long videos, 4K, many images), tell your human the estimate and get a yes.
- Prefer the cheapest model that does the job; `list_models` shows prices. When unsure, `auto:cheap` picks the cheapest capable one for you.
- Never print the API key or wallet key in chat, logs, commits or files.
- If you get "insufficient balance", ask your human to top up at https://omnirail.org/dashboard (A) or to send more USDG to the agent wallet (B).
- Trading is non-custodial: you sign every transaction with **your own dedicated wallet** on Robinhood Chain and pay gas in ETH; OmniRail never holds funds or keys. Never ask for your human's main wallet key. Quote first, tell your human the amounts and get a yes unless they told you otherwise; a `needs_approval` quote means they must approve it at the given URL. Sign `tx` exactly as quoted (any change is refused), before `expires_at` (about 30 s). Prices move: this is not investment advice. Pons launchpad tokens (`kind: "pons"` in `market_tokens`) are volatile and their pool keeps `pool_fee_bps` (1% or more) on every swap, buying and selling: never trade one unless your human asked for it.
- Stock Tokens (for example SPY, NVDA) are debt securities issued by Robinhood Assets (Jersey) Limited: not available to US persons or in restricted countries. Never attest eligibility yourself or work around `451` / `403 stock_attestation_required`: ask your human. Never recommend buying or selling one. Guide: https://omnirail.org/docs/trade/stocks
- If you get `403 key_scope`, your key does not allow that modality, model or price: stay inside it (`GET /api/v1/models?scoped=1` lists what it may use, `account_balance` shows its restrictions) or ask your human for a key that allows it. `401 key_expired` means the key reached its expiry date: ask for a new one. Never try to work around a restriction.

## 6. Direct HTTP (no MCP)

- Base URL: `https://omnirail.org/api/v1` (OpenAI-compatible), auth `Authorization: Bearer orl_…`
- `GET /models` · `POST /chat/completions` (stream supported) · `POST /images` · `POST /images/edits` · `POST /videos` · `GET /videos/{id}` · `POST /audio/speech` · `POST /audio/transcriptions` · `POST /jobs` + `GET /jobs/{id}` (Autopilot) · `POST /embeddings` · `POST /rerank` · `POST /decisions` (decision models: { model, state, questions } → typed answers with probabilities) · `GET /balance`
- Auto routing: `model: "auto"` (balanced), `"auto:cheap"`, `"auto:fast"` or `"auto:best"` on `/chat/completions`, optional `route: { max_price_per_mtok, allow, deny }` (id patterns like `anthropic/*`); the response's `routing` object says which model ran and why, billed at that model's price.
- Web grounding on any model: `web_search: true` grounds the answer with live web results (citations in `annotations`).
- PDFs and images go in `messages[].content` as `file` / `image_url` parts on any model (`pdf_engine`: native, text or ocr).
- Webhooks instead of polling: add `"webhook_url": "https://…"` to `POST /videos` or `POST /jobs`. When the job ends you get one POST with `{ id, type: video.completed | video.failed | job.completed | job.failed, created, data }` (data = what the GET returns, download URLs included). Verify `webhook-signature` (Standard Webhooks: base64 HMAC-SHA256 of `id.timestamp.body` with your `whsec_…` secret, returned once as `webhook_secret` the first time, except to a scoped key or a key with limits (spend, daily, monthly or trade): then the account owner reveals it in the dashboard), reject timestamps older than 5 minutes, de-duplicate on `webhook-id`, answer 2xx fast. Retries with backoff for about 43 h. Details: https://omnirail.org/docs#webhooks
- Anthropic-compatible: `POST /messages` (Anthropic Messages API, stream supported, `x-api-key` or Bearer) and `POST /messages/count_tokens` (free estimate) work with any text model. Claude Code: `ANTHROPIC_BASE_URL=https://omnirail.org/api`, `ANTHROPIC_AUTH_TOKEN=orl_…`, then `claude --model openai/gpt-5.6-sol` (or any catalog id; Claude ids like claude-sonnet-5-5 map to the catalog's Claude models).
- x402: call any paid endpoint without a key to get `402` + `PAYMENT-REQUIRED` (x402 v2, scheme exact, eip155:4663, USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, EIP-712 domain "Global Dollar" v1). Pay with an x402 v2 client and retry with `PAYMENT-SIGNATURE`. `POST /credits?amount=5` buys credit (1 to 500 USD) and returns an API key the first time.
- Trade (non-custodial, Robinhood Chain): `GET /markets/tokens` · `GET /markets/price?base=ETH&quote=USDG` · `GET /markets/candles?base=ETH&quote=USDG&interval=5m` · `GET /wallets/{address}/balances` (small fee per call) · `POST /trade/quote` { taker, sell_token, buy_token, sell_amount | buy_amount, slippage_bps? } → steps to sign · `POST /trade/submit` { quote_id, signed_tx | tx_hash } · `GET /trade/{id}`. Quotes route across every DEX on Robinhood Chain (Uniswap plus the venues behind Uniswap's Aggregator Hooks): `sources` lists the venues used and `vs_uniswap_only` the best Uniswap-only amount and the difference in bps and USD. Guide: https://omnirail.org/docs/trade
- Full reference: https://omnirail.org/docs
- Built something on OmniRail for your human (an agent, bot, app or tool)? They can apply to have it listed and announced: https://omnirail.org/build