IRL_BASE_URL — IRL server URL. Optional: by default read from ~/.irl-gateway/agent.json; run `uvx irl-gateway init` to create it (free paper token from https://norve.dev)
IRL_API_TOKEN — Bearer token for the IRL server. Optional: by default read from ~/.irl-gateway/agent.json, or run `uvx irl-gateway init`
IRL_AGENT_ID — The agent registered on IRL (its mandate). Optional: by default read from ~/.irl-gateway/agent.json, or run `uvx irl-gateway init`
IRL_MODEL_HASH — The model hash the agent was registered with (64 hex). Optional: by default read from ~/.irl-gateway/agent.json, or run `uvx irl-gateway init`
GATEWAY_BROKER — paper (default, live prices, no keys) or exchange
PAPER_BALANCES — Starting paper balances, e.g. USDT=1000
O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
Give your AI agent a trading account it can't misuse, and a record of every decision it can't rewrite.
IRL Gateway is an MCP server that sits between an AI agent (Claude, ChatGPT, or your own) and an exchange account. Every order the agent places goes through the IRL Engine:
An AI agent's trading mandate it can't break: checked before every order, reasoning sealed in IRL.
Policy before execution. IRL checks the order against the agent's mandate (active status, notional cap, allowed assets and venues) before anything reaches the exchange. Out of mandate means no order.
The rationale is sealed. The agent must say why it is trading. The gateway hashes that rationale together with the trade inputs and seals the hash into IRL's tamper-evident trace, anchored daily to Bitcoin. The plaintext stays in your local journal.
Intent is reconciled with the fill. After the exchange fills the order, IRL compares what was authorized with what executed and records MATCHED or DIVERGENT.
When something goes wrong, you can prove what the agent was allowed to do, what it said it was doing, and what actually happened.
AI agent ── MCP ──> irl-gateway ──> IRL: authorize (policy + sealed rationale)
│
├──────> exchange: market order (client id = sealed intent)
│
└──────> IRL: bind fill -> MATCHED / DIVERGENT
The only tool that moves money. Spot market order through authorize → place → bind. Returns filled, denied, blocked or failed, with the IRL trace_id and verdict.
get_policy()
The agent's mandate as IRL enforces it, plus the local kill-switch state.
get_quote(symbol)
Last price on the gateway's venue.
get_balances()
Free balances (paper or exchange).
get_trace(trace_id)
IRL's sealed record of one trade.
list_recent_trades(limit)
Local journal: rationale, context hash, trace id and outcome per trade.
Behaviour the agent can rely on:
Fail closed. If IRL is unreachable or denies the intent, no order is sent.
Kill switch. Create the file ~/.irl-gateway/KILL and every trade is refused before IRL is even called. Delete it to resume.
No silent fills. If the exchange fills but the IRL bind fails, the result still reports the fill and flags it for reconciliation.
Sealed = sent. Order sizes are rounded to the venue's step and checked against its minimums before IRL seals them, so the sealed quantity is exactly what reaches the exchange. An order the venue would reject is blocked with a plain reason instead.
Quick start (paper trading, about a minute)
uvx irl-gateway init
That one command gets a free paper-tier token from norve.dev, registers your agent with a starter mandate (BTC/USDT and ETH/USDT, at most 1,000 USDT per order, on paper-binance), saves the credentials to ~/.irl-gateway/agent.json, and prints:
a claude mcp add irl-gateway ... line for Claude Code, and
an mcpServers block for Claude Desktop, Cursor or any MCP client.
Paste one of them, then ask the agent to call get_policy and make its first paper trade. Paper fills are simulated at live public Binance prices with Binance's real order-size rules, so no exchange keys are needed.
Options: --name, --assets BTC/USDT,SOL/USDT, --max-notional 250, --contact [email protected] (so we can reach you), --server (your own IRL engine).
Free tier limits: paper venues only, up to 3 agents and 500 authorizations a day per token. Want to trade live, or run without limits? Self-host the engine or ask for a full token.
Model name sealed into each trace (the agent can override it per trade)
AGENT_CONFIG_CHECKSUM
none
Optional checksum of the agent's configuration, sealed into each trace
IRL_L2_MODE
off
regime if your IRL server requires Layer 2 regime binding
GATEWAY_BROKER
paper
paper or exchange
EXCHANGE_ID
binance
Any ccxt exchange id; also the price source for paper trading
EXCHANGE_API_KEY, EXCHANGE_API_SECRET
Required for exchange
EXCHANGE_TESTNET
true
Use the exchange's testnet
PAPER_BALANCES
USDT=1000
Starting paper balances (used only until paper_state.json exists; the paper account then persists across restarts)
IRL_GATEWAY_HOME
~/.irl-gateway
Journal (journal.jsonl), kill switch (KILL) and paper account (paper_state.json) location
The venue IRL sees is the exchange id (binance), or paper-<exchange> for paper trading, so a mandate can allow paper trading while denying the real account.
How the rationale is sealed
For each trade the gateway builds a context of the rationale, symbol, side, quantity, reference price, venue, model id and client order id. It hashes that context as canonical JSON (sorted keys, no whitespace) with SHA-256 and sends the hash to IRL as prompt_version = "ctx-sha256:<hex>", which IRL seals into the trace's reasoning_hash.
The journal stores the full context next to its hash, so anyone holding a journal line can recompute the hash and match it to the sealed trace. IRL itself never sees the rationale's text.
Early (0.1). Spot market orders only. Paper trading and ccxt exchanges are supported; Alpaca is next. Not investment advice, and no strategy is included: the gateway controls and records what your agent does, it does not decide.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo IRL Gateway?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
IRL Gateway precisa de uma chave de API?
O publicador lista estas variáveis de ambiente: IRL_BASE_URL, IRL_API_TOKEN, IRL_AGENT_ID, IRL_MODEL_HASH, GATEWAY_BROKER, PAPER_BALANCES.
Qual transporte IRL Gateway usa?
IRL Gateway roda localmente via stdio.
Quando IRL Gateway foi verificado pela última vez?
Última verificação: 2026-11-17. An AI agent's trading mandate it can't break: checked before every order, reasoning sealed in IRL.