Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

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

Tool What 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.

Quick start (paper trading)

You need an IRL server and an agent registered on it. Paper trading is the default: fills are simulated at live public Binance prices, and no exchange keys are needed.

pip install irl-gateway      # or run it without installing: uvx irl-gateway

Register the agent once, with its mandate:

curl -X POST "$IRL_BASE_URL/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, for example Claude Code or Claude Desktop:

{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": ["irl-gateway"],
      "env": {
        "IRL_BASE_URL": "https://irl.example.com",
        "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"
      }
    }
  }
}

Ask the agent to check get_policy, then trade.

Configuration

Variable Default Meaning
IRL_BASE_URL, IRL_API_TOKEN required IRL server and bearer token
IRL_AGENT_ID, IRL_MODEL_HASH required The registered agent and its model hash
AGENT_MODEL_ID unspecified-model 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.

Development

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

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.

Metadata

Release files for irl-gateway 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for irl-gateway 0.2.1
File Size Uploaded Provenance Actions
irl_gateway-0.2.1.tar.gz 24.4 kB With provenance Details for irl_gateway-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for irl-gateway 0.2.1
File Interpreter ABI Platform Actions
irl_gateway-0.2.1-py3-none-any.whl Python 3 none any Details for irl_gateway-0.2.1-py3-none-any.whl

Total release size: 43.7 kB

Release files / irl_gateway-0.2.1.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL irl_gateway-0.2.1.tar.gz
Size 24.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8bcb7a895e5f2e362d69eed538358112409de5f1be28c272e13efa1635466e00
BLAKE2b-256 checksum
How to use checksums
daf835b860b35980a73a563f215edb03e4be5abdf88dde9c200bcf5f9e9c3a3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Release files / irl_gateway-0.2.1-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL irl_gateway-0.2.1-py3-none-any.whl
Size 19.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4951155c158c7bd59b684db857ee1f1ed2b2b6435f49a106cb7a953d7539b944
BLAKE2b-256 checksum
How to use checksums
e0d6da4dbdabf07d0297b54a7b9c6d21a4b2ea943625096f978532a2402d6511
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Security for irl-gateway 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Change of provenance

The repository and configuration that created this release differ from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for irl_gateway-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page