IRL Gateway MCP server

IRL Gateway

<!-- mcp-name: io.github.norve-labs/irl-gateway -->

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:

1. 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.
2. 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.
3. 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

Tools

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 you@example.com (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.

Doing it by hand instead

Shortened. The full README is on GitHub.