---
name: omnirail
description: "OmniRail (omnirail.org): one API key or crypto wallet for every AI model, through an MCP server and an OpenAI-compatible API. Use when the user asks to call any LLM (Claude, GPT, Gemini, DeepSeek, Qwen...) or get a second opinion from another model, generate or edit images, make videos, turn text into speech or transcribe audio, search the web, read PDFs, embed or rerank documents, make a yes/no, choice or score decision with probabilities, check prices or swap tokens on Robinhood Chain, run Claude Code on non-Claude models or pay per call from a crypto wallet (x402), or when a task needs a model or capability you do not have yourself. Also use to set OmniRail up, check the balance or explain what a call cost."
compatibility: "Needs HTTPS access to OmniRail. Best with the OmniRail MCP server; plain curl works too. Paid calls need an OmniRail API key (orl_...) or a dedicated x402 wallet."
---

# OmniRail

OmniRail (https://omnirail.org) gives you every LLM, image, video, image-editing, voice, embedding, rerank, decision model through one MCP server and one OpenAI-compatible API, paid from a prepaid balance (an API key) or per call by a dedicated crypto wallet (x402, USDG on Robinhood Chain). It also lets you trade tokens on Robinhood Chain with your own wallet. Every call reserves its worst-case cost first and charges the real cost after; failed calls are free.

## 1. Check the connection first

1. **MCP tools present?** Look for the OmniRail MCP server's tools (server `omnirail`; in Claude Code they look like `mcp__omnirail__list_models`, or `mcp__plugin_omnirail_omnirail__list_models` from the plugin). If you have them, call `account_balance` once: a balance means you are ready.
2. **No MCP, but a key in the environment?** If `OMNIRAIL_KEY` (or `OMNIRAIL_API_KEY`) is set, call the HTTP API directly (section 4). Never print the key.
3. **Nothing yet?** Ask your human 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?"* Then follow [references/setup.md](references/setup.md) for your client. Claude Code with a key, in one line:

```bash
claude mcp add --transport http omnirail https://omnirail.org/api/mcp --header "Authorization: Bearer orl_YOUR_KEY"
```

Replace `orl_YOUR_KEY` with the key they give you; most clients load a new MCP server after a restart (in Claude Code, check with `/mcp`). `list_models` and `GET https://omnirail.org/api/v1/models` work without a key.

## 2. Rules

- **Budget.** Before one action that could cost more than $1 (long or 4K videos, many images, big batches), tell your human the estimate and get a yes. Bound text calls with `max_tokens`.
- **Cheapest model that does the job.** `list_models` shows live prices. When unsure, model `auto:cheap` picks the cheapest capable one.
- **Say what it cost.** Read the real cost from the answer, never guess: `usage.cost` (USD) on chat, embeddings, rerank, decision answers, `cost` on a finished video, the `X-OmniRail-Charge` header on every paid HTTP call; MCP tools print it.
- **Secrets.** Never print the API key or a wallet key in chat, logs, commits or files. Never ask for, accept or store the key of your human's main wallet: only a new, dedicated wallet with a small balance.
- **Trades.** You sign with your own dedicated wallet and pay gas; OmniRail never holds funds. Quote first, tell your human the amounts and get a yes unless they told you otherwise. Never present a trade as advice. Read [references/trade.md](references/trade.md) before your first swap.
- **Errors.** `402` or "insufficient balance": ask your human to top up at https://omnirail.org/dashboard (key) or to send USDG to the agent wallet (x402). `403 key_scope`: your key does not allow that model, modality or price; stay inside it or ask for another key. `401 key_expired`: ask for a new key. `429`: wait the `Retry-After` seconds. Never work around a limit or a refusal.

## 3. What to use for what

| Task | MCP tool | HTTP (base `https://omnirail.org/api/v1`) |
|---|---|---|
| Find a model id and its live price | `list_models` (kind, search) | `GET /models?kind=text` |
| Ask any LLM, a second opinion, cheap bulk work (model `auto:cheap` picks for you) | `chat` | `POST /chat/completions` |
| Answer with live web results | `chat` with `web: true` | `POST /chat/completions` with `web_search: true` |
| Read PDFs | `chat` with `files` | `POST /chat/completions` with `file` content parts |
| Generate images | `generate_image` | `POST /images` |
| Edit existing images | `edit_image` | `POST /images/edits` |
| Make a video (async), or get called back | `generate_video` then `get_video` | `POST /videos` then `GET /videos/{id}` |
| Text to speech | `speak` | `POST /audio/speech` |
| Speech to text | `transcribe` | `POST /audio/transcriptions` |
| Vectors for search / RAG | `embed` | `POST /embeddings` |
| Rank documents against a query | `rerank` | `POST /rerank` |
| Decide before acting: yes/no, choice, score, box | `decide` | `POST /decisions` |
| One brief, many models (copy, images, video, voice) | `build` then `get_job` | `POST /jobs` then `GET /jobs/{id}` |
| Market data, balances | `market_tokens`, `market_price`, `wallet_balances` | `GET /markets/tokens`, `/markets/price`, `/wallets/{address}/balances` |
| Swap tokens (you sign with your own wallet) | `trade_quote`, `trade_submit`, `trade_status` | `POST /trade/quote`, `POST /trade/submit`, `GET /trade/{id}` |
| Anthropic SDKs / Claude Code on any model | (not an MCP tool) | `POST /messages` |
| Balance and key restrictions | `account_balance` | `GET /balance` |

Model ids look like `provider/model` (for example `anthropic/claude-opus-5.5`, `google/gemini-3.8-flash`); take them from `list_models`, never invent one. Videos and Autopilot jobs are asynchronous: poll `get_video` every ~30 s and `get_job` every ~20 s, or pass `webhook_url`.

## 4. Direct HTTP (no MCP)

OpenAI-compatible: any OpenAI SDK works with `baseURL: "https://omnirail.org/api/v1"`. One call with curl:

```bash
curl https://omnirail.org/api/v1/chat/completions \
  -H "Authorization: Bearer $OMNIRAIL_KEY" -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.8-flash","messages":[{"role":"user","content":"Hello"}],"max_tokens":300}'
```

The answer's `usage.cost` is what you paid, in USD.

## 5. References

Read one only when the task needs it:

- [references/setup.md](references/setup.md): installing the MCP server in your client, the two ways to pay, verifying (the same guide as /agents.md).
- [references/models-and-media.md](references/models-and-media.md): parameters and examples for chat, web search, PDFs, images, edits, video, voice, Autopilot, embeddings, rerank.
- [references/payments-and-keys.md](references/payments-and-keys.md): balance, costs, top-ups, x402, key limits, scoped keys and every error code.
- [references/decisions.md](references/decisions.md): decision models (Jev): typed questions, probabilities, thresholds.
- [references/trade.md](references/trade.md): swaps on Robinhood Chain: quote, sign, submit, status, limits and rules.
- [references/webhooks.md](references/webhooks.md): signed callbacks instead of polling, and how to verify them.
- [references/claude-code.md](references/claude-code.md): Claude Code and the Anthropic SDKs on any model through /v1/messages.

Full API reference: https://omnirail.org/docs. Live catalog and prices: https://omnirail.org/api/v1/models.