irl-sdk — Python SDK for the IRL Engine

Async Python client for the IRL Engine — the cryptographic pre-execution compliance gateway for autonomous AI trading agents.

• Optionally fetches a signed Layer 2 heartbeat from a regime operator (MTA), when your IRL server uses one
• Constructs and signs the authorize request
• Returns a sealed trace_id and reasoning_hash before any order reaches the exchange

What's new in 0.3.0

• No regime operator required: mta_url is optional. Without it the SDK sends no heartbeat, which is what an IRL server with MTA_MODE=none (agent caps only) expects. IRLClient(IRL_URL, API_TOKEN) is enough.
• Retry + circuit breaker: All API calls retry on 5xx responses with exponential backoff (default: 3 retries, 0.5 s base delay). Configurable via max_retries and backoff_base.
• Multi-agent trace linking: AuthorizeRequest.parent_trace_id links a sub-agent call to its orchestrator, enabling full causal chain audits via get_trace_chain().
• Extended order types: OrderType now includes VWAP, IOC, FOK, POST_ONLY, PEGGED, TRAILING_STOP, ICEBERG.
• bind_execution() + get_trace() + get_trace_chain(): Full post-trade and audit chain methods.

Install

pip install irl-sdk

Requires Python 3.10+.

Quick Start

import asyncio
from irl_sdk import IRLClient, AuthorizeRequest, TradeAction, OrderType

IRL_URL   = "https://norve.dev"
API_TOKEN = "your-irl-api-token"
AGENT_ID  = "your-agent-uuid"           # from POST /irl/agents
MODEL_HASH = "your-model-sha256-hex"    # 64-char hex

async def main():
    async with IRLClient(IRL_URL, API_TOKEN) as client:
        req = AuthorizeRequest(
            agent_id=AGENT_ID,
            model_id="my-model-v1",
            model_hash_hex=MODEL_HASH,
            action=TradeAction.LONG,
            asset="BTC-USD",
            order_type=OrderType.MARKET,
            venue_id="coinbase",
            quantity=0.1,
            notional=6500.0,
            notional_currency="USD",
        )
        result = await client.authorize(req)

        if result.authorized:
            print(f"AUTHORIZED  trace_id={result.trace_id}")
            print(f"reasoning_hash={result.reasoning_hash[:24]}...")
            # embed trace_id in your exchange order metadata, then place the order
        else:
            print("HALTED — IRL blocked the trade")

asyncio.run(main())

End-to-End Demo

The demo registers nothing — it uses a pre-seeded demo agent in the public sandbox:

cd examples
pip install -e ..
python demo_e2e.py

Expected output:

IRL Engine : https://norve.dev
MTA        : https://api.macropulse.live
Agent ID   : 00000000-0000-4000-a000-000000000001

Fetching heartbeat and submitting authorize request...

AUTHORIZED
  trace_id      : <uuid>
  reasoning_hash: <first 24 chars>...
  shadow_blocked: False

API Reference

IRLClient(irl_url, api_token, mta_url, timeout, max_retries, backoff_base)

Async context manager. All parameters are positional.

client.authorize(req: AuthorizeRequest) → AuthorizeResult

1. If mta_url is set, fetches a fresh signed heartbeat from {mta_url}/v1/irl/heartbeat
2. POSTs to {irl_url}/irl/authorize with the request payload (and the heartbeat, if any)
3. Returns AuthorizeResult

AuthorizeRequest fields

AuthorizeResult fields

TradeAction

from irl_sdk import TradeAction

TradeAction.LONG     # "Long"
TradeAction.SHORT    # "Short"
TradeAction.NEUTRAL  # "Neutral"

OrderType

from irl_sdk import OrderType

OrderType.MARKET        # "MARKET"
OrderType.LIMIT         # "LIMIT"
OrderType.STOP          # "STOP"
OrderType.TWAP          # "TWAP"
OrderType.VWAP          # "VWAP"
OrderType.IOC           # "IOC"
OrderType.FOK           # "FOK"
OrderType.POST_ONLY     # "POST_ONLY"
OrderType.PEGGED        # "PEGGED"
OrderType.TRAILING_STOP # "TRAILING_STOP"
OrderType.ICEBERG       # "ICEBERG"

client.get_trace_chain(trace_id: str) → dict

Returns the full causal ancestry chain for a trace. Useful for multi-agent audit trails where sub-agent decisions trace back to an orchestrator.

chain = await client.get_trace_chain(result.trace_id)
# {"trace_id": "...", "ancestry": [...], "children": [...]}

Error Handling

The SDK raises httpx.HTTPStatusError on non-2xx responses. The response body contains {"error": "ERROR_CODE", "message": "..."}. Common codes:

Layer 2 (Heartbeat) Details

Only relevant when the engine runs with a regime operator and LAYER2_ENABLED=true: every authorize request must then carry a SignedHeartbeat, which the SDK fetches from {mta_url}/v1/irl/heartbeat when you pass mta_url.

The heartbeat binds each request to a specific MTA broadcast:

• sequence_id — strictly monotone (anti-replay)
• timestamp_ms — must be within MAX_HEARTBEAT_DRIFT_MS of txn_time
• mta_ref — SHA-256 of the raw /v1/regime/current HTTP response body
• signature — Ed25519 signature by the MTA operator

With MTA_MODE=none or LAYER2_ENABLED=false (the public IRL server runs this way), leave mta_url unset: no heartbeat is sent and only the agent's own mandate applies.

Ecosystem

License

MIT