IRL Gateway

IRL Gateway

AI エージェントに、不正に使えない取引口座と、書き換えられないすべての判断の記録を与えます。

IRL Gateway は、AI エージェント（Claude、ChatGPT、または独自のエージェント）と取引所口座の間に位置するMCPサーバーです。エージェントが行うすべての注文は、IRL Engineを通過します。

1. 実行前にポリシーを確認します。 IRL は、注文が取引所に送られる前に、エージェントの権限（有効なステータス、注文金額の上限、許可された資産と取引所）に照らして注文を確認します。権限の範囲外であれば、注文は行われません。
2. 取引理由を封印します。 エージェントは、取引する理由を説明する必要があります。ゲートウェイは、その理由を取引の入力情報とともにハッシュ化し、IRL の改ざん検知可能なトレースに封印します。このトレースは毎日 Bitcoin にアンカーされます。平文はローカルジャーナルに保存されます。
3. 意図と約定を照合します。 取引所で注文が約定した後、IRL は承認された内容と実行された内容を比較し、MATCHED または DIVERGENT を記録します。

問題が発生した場合、エージェントに許可されていた内容、エージェントが実行すると説明した内容、実際に起きたことを証明できます。

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

ツール

エージェントが想定できる動作：

• フェイルクローズ。 IRL に接続できない場合、または IRL が意図を拒否した場合、注文は送信されません。
• キルスイッチ。 ファイル ~/.irl-gateway/KILL を作成すると、IRL を呼び出す前にすべての取引が拒否されます。再開するには、ファイルを削除してください。
• 約定を隠しません。 取引所で約定しても IRL への紐付けに失敗した場合、結果には約定が報告され、照合が必要であることが示されます。
• 封印された内容が送信されます。 IRL が注文を封印する前に、注文サイズは取引所の刻みに合わせて丸められ、最小注文数量を満たしているか確認されます。そのため、封印された数量がそのまま取引所に送られます。取引所が拒否する注文は、代わりに明確な理由とともにブロックされます。

クイックスタート（ペーパー取引、約1分）

uvx irl-gateway init

このコマンドを実行すると、norve.devから無料のペーパーティアトークンを取得し、スターター権限（BTC/USDT と ETH/USDT、1注文あたり最大 1,000 USDT、paper-binance）を設定してエージェントを登録します。認証情報は ~/.irl-gateway/agent.json に保存され、次の内容が表示されます。

• Claude Code 用の claude mcp add irl-gateway ... の行、および
• Claude Desktop、Cursor、または任意の MCP クライアント用の mcpServers ブロック。

いずれかを貼り付けてから、エージェントに get_policy を呼び出させ、初めてのペーパー取引を行うよう依頼してください。ペーパー取引の約定は、Binance の公開リアルタイム価格と、Binance の実際の注文サイズ規則に基づいてシミュレートされるため、取引所の API キーは不要です。

オプション：--name、--assets BTC/USDT,SOL/USDT、--max-notional 250、--contact [email protected]（連絡先として）、--server（独自の IRL エンジン）。

無料プランの制限： ペーパー取引所のみ、トークンあたり最大 3 エージェント、1日あたり 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 に対応予定です。投資助言ではなく、戦略も含まれていません。ゲートウェイはエージェントの動作を制御・記録しますが、判断は行いません。

MIT ライセンスです。