IRL Gateway

IRL Gateway

为 AI Agent 提供一个无法被滥用的交易账户，并留下每个无法篡改的决策记录。

IRL Gateway 是一个 MCP 服务，位于 AI Agent（Claude、ChatGPT 或你自己的 Agent）与交易所账户之间。Agent 下达的每笔订单都会经过 IRL Engine：

1. 执行前先检查策略。 IRL 会先根据 Agent 的授权范围（启用状态、名义金额上限、允许的资产和交易场所）检查订单，再将订单发送到交易所。超出授权范围就不会下单。
2. 交易理由会被封存。 Agent 必须说明交易理由。网关会将该理由与交易输入一并哈希，并把哈希封存到 IRL 的防篡改追踪记录中，每日锚定到 Bitcoin。明文会保留在你的本地日志中。
3. 核对意图与成交情况。 交易所成交后，IRL 会比较已授权的内容与实际执行的内容，并记录为 MATCHED 或 DIVERGENT。

出现问题时，你可以证明 Agent 获准执行哪些操作、声称自己在做什么，以及实际发生了什么。

AI agent ── MCP ──> irl-gateway ──> IRL: authorize (policy + sealed rationale)
                         │
                         ├──────> exchange: market order (client id = sealed intent)
                         │
                         └──────> IRL: bind fill -> MATCHED / DIVERGENT

工具

Agent 可以依赖以下行为：

• 故障时拒绝执行。 如果 IRL 无法访问或拒绝该意图，就不会发送订单。
• 紧急停止开关。 创建文件 ~/.irl-gateway/KILL 后，每笔交易都会在调用 IRL 前被拒绝。删除该文件即可恢复。
• 不会悄悄成交。 如果交易所已成交，但 IRL 绑定失败，结果仍会报告成交情况，并标记为需要核对。
• 封存的数量就是发送的数量。 在 IRL 封存订单数量之前，数量会按交易场所的步长取整，并检查是否满足其最低要求，因此封存的数量与发送到交易所的数量完全一致。交易场所会拒绝的订单会被拦截，并给出明确原因。

快速开始（模拟交易，大约一分钟）

uvx irl-gateway init

这条命令会从 norve.dev 获取免费的模拟交易层级令牌，为你的 Agent 注册带有初始授权范围的账户（BTC/USDT 和 ETH/USDT，每笔订单最多 1,000 USDT，在 paper-binance 上交易），将凭证保存到 ~/.irl-gateway/agent.json，并输出：

• 一行用于 Claude Code 的 claude mcp add irl-gateway ... 命令；以及
• 一个适用于 Claude Desktop、Cursor 或任何 MCP 客户端的 mcpServers 配置块。

粘贴其中一项，然后让 Agent 调用 get_policy 并进行首次模拟交易。模拟成交基于 Binance 实时公开价格，并遵循 Binance 的实际订单数量规则，因此无需交易所密钥。

选项：--name、--assets BTC/USDT,SOL/USDT、--max-notional 250、--contact [email protected]（方便我们联系你）、--server（使用你自己的 IRL 引擎）。

免费层级限制： 仅限模拟交易场所；每个令牌最多支持 3 个 Agent，每日最多进行 500 次授权。想进行实盘交易或不受限制地运行？请自托管引擎，或申请完整令牌。

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"]
  }'

{
  "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"
      }
    }
  }
}

IRL 看到的交易场所是交易所 ID（binance），或模拟交易时的 paper-<exchange>，因此授权许可可以允许模拟交易，同时禁止真实账户交易。

如何封存理由

对于每笔交易，网关都会构建一个包含理由、交易对、方向、数量、参考价格、交易场所、模型 ID 和客户端订单 ID 的上下文。它会将此上下文作为规范 JSON（键排序、不含空格）使用 SHA-256 哈希，并将哈希作为 prompt_version = "ctx-sha256:<hex>" 发送给 IRL，IRL 会将其封存到轨迹的 reasoning_hash 中。

日志会在哈希旁存储完整上下文，因此任何持有日志行的人都可以重新计算哈希，并将其与已封存的轨迹进行比对。IRL 本身永远不会看到理由文本。

开发

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

状态

早期版本（0.1）。仅支持现货市价单。支持模拟交易和 ccxt 交易所；接下来将支持 Alpaca。不构成投资建议，也不包含任何策略：网关负责控制和记录 Agent 的操作，但不负责做出决策。

采用 MIT 许可。