# Payments, keys and errors

## Two ways to pay

- **API key** (`orl_...`, recommended for humans): your human signs in at https://omnirail.org/dashboard with a wallet, tops up with USDG or ETH (or $RAIL) on Robinhood Chain, creates a key and gives it to you. Keys can carry a spend limit, daily and monthly limits, and scopes (below).
- **Agent wallet (x402)**: a **new, dedicated** wallet holding a little USDG (`0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`) on Robinhood Chain. The local MCP server buys credit itself within `OMNIRAIL_DAILY_BUDGET_USD` (default 20) per day; no ETH is needed for gas. Without the MCP server: call any paid endpoint without a key to get `402` + `PAYMENT-REQUIRED` (x402 v2, scheme exact, eip155:4663), pay with an x402 v2 client and retry with `PAYMENT-SIGNATURE`. `POST /credits?amount=5` buys 1 to 500 USD of credit at once and returns an API key the first time.

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

## Balance and costs

- `GET https://omnirail.org/api/v1/balance` or the MCP tool `account_balance`: remaining credit and the live markup, plus the key's restrictions.
- Every paid answer says what it cost: `usage.cost` (USD), `cost` on finished videos, `X-OmniRail-Charge` on paid HTTP answers. Failed calls are free; the hold is released.
- Tell your human the estimate and get a yes before one action that could cost more than $1.
- Your human sees every call and its cost in the dashboard's Usage tab (https://omnirail.org/dashboard).

## Scoped keys

Ask your human for a 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."* A key can be limited 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. `GET /models?scoped=1` lists what your key may use. Details: https://omnirail.org/docs#scopes

## Errors

| Status | Meaning | What you do |
|---|---|---|
| `400` | Invalid parameter (the message lists the allowed values) | Fix the request |
| `401` | Missing or wrong key; `key_expired`: the key reached its expiry date | Check the key; ask for a new one if expired |
| `402` | Insufficient balance, or x402 payment required | Ask your human to top up, or pay with x402 |
| `403 key_scope` | The key does not allow that modality, model or price | Stay inside it or ask for a key that allows it |
| `429` | Rate limited | Wait `Retry-After` seconds |
| `5xx` | Provider or OmniRail error, not charged | Retry once later, or try another model |