IRL Gateway

io.github.norve-labsv0.3.0更新于 Oct 7, 2026

An AI agent's trading mandate it can't break: checked before every order, reasoning sealed in IRL.

已验证STDIO仅桌面Security & MonitoringFinance

概览

AI 生成的概览

让 AI 代理通过受策略校验的网关下现货市价单，并把每笔交易的理由封存为防篡改记录。

功能
IRL Gateway 位于 AI 代理与交易所账户之间，在订单到达交易所之前，先按代理已注册的授权（启用状态、名义金额上限、允许的资产与交易场所）进行校验。主要工具 execute_trade 依次执行授权、下单与绑定，并返回 filled、denied、blocked 或 failed 以及 trace id。其他工具可读取授权与本地终止开关状态、报价、余额、某笔交易的封存记录，以及本地近期交易日志。交易理由经哈希后封存进 IRL 记录，明文只留在本地日志中。
适用场景
当助手被允许进行交易，但需要受预先注册的授权约束，并留下可核验的记录——证明它被允许做什么、声称在做什么、实际成交了什么——时适用。模拟盘模式无需交易所密钥，适合低风险试用。
运行要求
以 stdio 方式在本地运行，从 PyPI 安装并用 uvx 启动。需要 IRL_BASE_URL、IRL_AGENT_ID、IRL_MODEL_HASH 以及密钥 IRL_API_TOKEN，并能访问 IRL 服务器。GATEWAY_BROKER 选择 paper（默认）或 exchange；exchange 模式还需 EXCHANGE_API_KEY 与 EXCHANGE_API_SECRET。仅支持桌面端。
安装前请注意
execute_trade 是唯一会动用资金的工具，在 exchange 模式下可在真实账户下单。它需要密钥 IRL_API_TOKEN，实盘交易还需交易所 API 密钥与密钥串。理由明文留在本地，但交易上下文的哈希会发送到 IRL 服务器并在外部锚定。终止开关是本地文件；项目处于早期（0.1），仅支持现货市价单。

安装

在 SourceWeft 中

  1. 打开 控制台中的 IRL Gateway，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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

ToolWhat it does
execute_trade(symbol, side, rationale, quantity | notional)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)

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

Doing it by hand instead
bash
curl -X POST https://norve.dev/irl/signup -H "Content-Type: application/json" -d '{"client_name": "my-claude-trader"}'# -> {"token": "...", "tier": "paper", ...}  (shown once)
curl -X POST https://norve.dev/irl/agents -H "Authorization: Bearer $IRL_API_TOKEN"   -H "Content-Type: application/json" -d '{    "name": "my-claude-trader",    "model_hash_hex": "<sha256 of your agent config>",    "max_notional": 100,    "allowed_assets": ["BTC/USDT", "ETH/USDT"],    "allowed_venues": ["paper-binance"]  }'

Then add the gateway to your MCP client:

json
{  "mcpServers": {    "irl-gateway": {      "command": "uvx",      "args": ["irl-gateway"],      "env": {        "IRL_BASE_URL": "https://norve.dev",        "IRL_API_TOKEN": "…",        "IRL_AGENT_ID": "<agent_id from registration>",        "IRL_MODEL_HASH": "<the same model_hash_hex>",        "AGENT_MODEL_ID": "claude-opus-5-5",        "PAPER_BALANCES": "USDT=1000"      }    }  }}

Configuration

VariableDefaultMeaning
IRL_BASE_URL, IRL_API_TOKENrequiredIRL server and bearer token
IRL_AGENT_ID, IRL_MODEL_HASHrequiredThe registered agent and its model hash
AGENT_MODEL_IDunspecified-modelModel name sealed into each trace (the agent can override it per trade)
AGENT_CONFIG_CHECKSUMnoneOptional checksum of the agent's configuration, sealed into each trace
IRL_L2_MODEoffregime if your IRL server requires Layer 2 regime binding
GATEWAY_BROKERpaperpaper or exchange
EXCHANGE_IDbinanceAny ccxt exchange id; also the price source for paper trading
EXCHANGE_API_KEY, EXCHANGE_API_SECRETRequired for exchange
EXCHANGE_TESTNETtrueUse the exchange's testnet
PAPER_BALANCESUSDT=1000Starting paper balances (used only until paper_state.json exists; the paper account then persists across restarts)
IRL_GATEWAY_HOME~/.irl-gatewayJournal (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.

Development

bash
python -m venv .venv && .venv/bin/pip install -e ".[dev]"pytest --cov=irl_gatewayruff check src tests && black --check src tests && isort --check-only src tests && mypy src

Status

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.

MIT licensed.

来源：README.md，提交 2e6fd99

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.3.0最新Oct 7, 2026