# OmniRail: setup guide for AI agents

OmniRail gives you every LLM, image, video and image-editing model (Claude, GPT, Gemini, Grok, DeepSeek, Qwen, Kimi, FLUX, GPT Image, Veo, Sora, Kling, Seedance…) through one MCP server and one OpenAI-compatible API. It is paid in crypto on Robinhood Chain (chain 4663). Price = provider cost + 15% markup, per call.

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.
- **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 and search. |
| `chat` | Ask any LLM. Set `max_tokens` to bound the cost. |
| `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. |
| `get_video` | Poll every ~30 s until completed; `save_to` downloads the MP4 (local server). |
| `account_balance` | Remaining credit and live markup. |

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.
- 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).

## 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}` · `GET /balance`
- 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.
- Full reference: https://omnirail.org/docs