irl-sdk

TypeScript/JavaScript SDK for the IRL Engine — cryptographic pre-execution compliance rail for autonomous trading agents.

What's new in 0.2.0

L2 heartbeat auto-fetch — IRLClient now fetches and attaches a signed MTA heartbeat on every authorize() call. bindExecution() added to close the cryptographic chain.

Install

npm install irl-sdk
# or
pnpm add irl-sdk
# or
yarn add irl-sdk

Node.js ≥ 18 required (uses native fetch and AbortSignal.timeout).

Quickstart

import { IRLClient } from "irl-sdk";

const client = new IRLClient({
  irlUrl: "https://irl.macropulse.live",
  apiToken: process.env.IRL_API_TOKEN!,
});

// 1. Authorize a trade intent — fetches a fresh heartbeat automatically
const result = await client.authorize({
  agent_id: "550e8400-e29b-41d4-a716-446655440000",
  model_id: "btc-momentum-v2",
  model_hash_hex: "a3f2e1d4...".padEnd(64, "0"),  // SHA-256 of model config
  action: "Long",
  asset: "BTC-USD",
  venue_id: "CBSE",
  quantity: 0.5,
  notional: 32500,
});

if (result.authorized) {
  // 2. Place the order — attach reasoning_hash to exchange metadata
  const exchangeTxId = await placeOrder({
    asset: "BTC-USD",
    quantity: 0.5,
    irlTraceId: result.trace_id,
    irlReasoningHash: result.reasoning_hash,
  });

  // 3. Bind execution — closes the cryptographic chain
  await client.bindExecution({
    trace_id: result.trace_id,
    exchange_tx_id: exchangeTxId,
    execution_status: "Filled",
    asset: "BTC-USD",
    executed_quantity: 0.5,
    execution_price: 65000,
  });
}

await client.close();

API

new IRLClient(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | irlUrl | string | Yes | IRL Engine base URL | | apiToken | string | Yes | Bearer token from IRL admin | | mtaUrl | string | No | MTA base URL (default: https://api.macropulse.live) | | timeoutMs | number | No | Request timeout in ms (default: 5000) |

client.authorize(req) → Promise<AuthorizeResult>

Fetches a fresh heartbeat and submits the trade intent.

AuthorizeRequest key fields:

| Field | Type | Description | |-------|------|-------------| | agent_id | string | UUID — must be registered in the MAR | | model_hash_hex | string | 64-char SHA-256 of the model config | | action | "Long" \| "Short" \| "Neutral" | Trade direction | | asset | string | e.g. "BTC-USD" | | venue_id | string | e.g. "CBSE" | | quantity | number | Units | | notional | number | USD notional |

AuthorizeResult:

{
  trace_id: string;        // Attach to exchange order metadata
  reasoning_hash: string;  // SHA-256 of the sealed reasoning snapshot
  authorized: boolean;     // false = blocked by policy engine
  shadow_blocked: boolean; // true = would have been blocked (shadow mode)
}

client.bindExecution(params) → Promise<{ final_proof, status }>

Closes the cryptographic chain after exchange confirmation.

client.getTrace(trace_id) → Promise<Record<string, unknown>>

Retrieve a full trace for forensic replay or regulator review.

client.fetchHeartbeat() → Promise<Heartbeat>

Fetch the latest signed heartbeat manually (normally handled by authorize).

Error handling

import { IRLClient, IRLError, IRLHeartbeatError } from "irl-sdk";

try {
  const result = await client.authorize(req);
} catch (err) {
  if (err instanceof IRLHeartbeatError) {
    // MTA heartbeat fetch failed — check api.macropulse.live
  } else if (err instanceof IRLError) {
    console.error(err.status, err.body);  // 4xx/5xx from IRL Engine
  }
}

Layer 2 anti-replay

The client fetches a fresh heartbeat before every authorize call. Do not cache or reuse heartbeats — each must be consumed once. Reuse will result in a HEARTBEAT_REPLAY rejection from the engine.

MtaMode::None

If the IRL Engine is deployed with MTA_MODE=none, heartbeat fetching is skipped by the engine but the client still sends one. For none-mode deployments you can call the engine directly without configuring mtaUrl:

const client = new IRLClient({
  irlUrl: "https://your-private-irl-deployment.internal",
  apiToken: "your-token",
  mtaUrl: "https://api.macropulse.live",  // still fetched; engine ignores it in none mode
});

Ecosystem

| Repo | Description | |---|---| | irl-engine | Core IRL Engine | | irl-sdk-python | Python SDK | | irl-public-docs | Public documentation hub | | macropulse | MacroPulse — MTA operator |

Links

• IRL Engine product page
• Developer Guide
• Live Sandbox + Swagger UI
• Python SDK on PyPI