IBKR Agent Gateway

ibkr-agent-gateway is an unofficial Rust CLI, SDK, and MCP gateway for Interactive Brokers workflows.

It gives agents and operator tools a controlled way to inspect IBKR accounts, stage order workflows, and keep every sensitive boundary explicit: typed requests, scoped access, deterministic risk gates, idempotency, and redacted audit records.

This project is not affiliated with, endorsed by, or supported by Interactive Brokers.

Why This Exists

Use it when you want an agent, internal tool, or operator workflow to inspect an IBKR account through CLI or MCP without exposing broker session material.

The gateway keeps broker access behind explicit scopes, typed requests, safe output shapes, and append-only audit evidence. Order workflows are staged on purpose: preview first, paper trading behind approval and idempotency, then live trading only when an operator explicitly enables the full gate stack.

It is not a trading strategy engine, autonomous bot, or shortcut around IBKR authentication. It is an audited control plane for broker operations.

At a Glance

What Works Today

The package is a single Cargo crate with two supported entrypoints:

Implemented surfaces include:

• ✅ offline fake backend fixtures for fast development and CI;
• ✅ local Client Portal Gateway read calls for session, accounts, portfolio, positions, contracts, market data, read-only orders, and executions;
• ✅ local MCP stdio serving, scope-filtered tool discovery, consultative and contextual read tools, preview/paper/live-gated order tools, bracket tools, MCP approval creation, and tool-call audit;
• ✅ remote MCP HTTP serving for POST /mcp with OAuth/OIDC, RS256 JWKS validation, protected-resource metadata, generic auth denials, and JSON-RPC tool routing;
• ✅ order preview and deterministic risk checks;
• ✅ paper submit/cancel/modify lifecycle gates with approval and idempotency;
• ✅ live submit/cancel/modify and MCP bracket safety gates, kill switch, limits, server-side rate counters, lifecycle reconciliation, and paper-to-live checklist checks;
• ✅ pluggable live order writer with a bundled Client Portal Gateway implementation that returns broker-generated order ids and handles the IBKR reply-chain confirmation protocol.

The live CLI commands default to a local-candidate writer so the full gate stack (kill switch, allowlist, approval, idempotency, paper-to-live) is exercised end-to-end offline — see the live-submit row in Common CLI Commands for the complete invocation. Use --live-broker client-portal with a Client Portal Gateway config to call the bundled production writer — see docs/production-readiness.md.

The MCP registry currently exposes 45 explicit tools when all scopes are enabled. The full tool and scope matrix is documented in docs/mcp-local.md and docs/scopes.md.

Safety Model 🛡️

Defaults are deliberately conservative:

• 🔒 broker credentials, cookies, bearer tokens, raw headers, and local session material must never be returned to agents, CLI output, logs, fixtures, or audit payloads;
• 🧪 fake backend is available for offline development;
• 🚪 remote MCP, sidecar relay, paper trading, and live trading all require explicit enablement;
• 👀 order preview is non-executable;
• 🧾 paper workflows require approval and idempotency;
• 🚨 live workflows require scope, config, approval, risk, kill switch, audit, durable idempotency, and paper-to-live migration gates.

Quick Start 🚀

Smoke-test the local fake backend from a checkout:

cargo run --bin ibkr-agent -- health --json
cargo run --bin ibkr-agent -- accounts list --json
cargo run --bin ibkr-agent -- mcp serve --transport stdio --describe --json

Install the CLI from the checkout:

cargo install --path .
ibkr-agent health --json

Or install the binary from crates.io:

cargo install ibkr-agent-gateway
ibkr-agent health --json

Use the SDK from another Rust project:

cargo add ibkr-agent-gateway

Or, while developing from this checkout:

cargo add ibkr-agent-gateway --path /path/to/ibkr-agent-gateway

Minimal embedded usage:

use ibkr_agent_gateway::prelude::*;

#[tokio::main]
async fn main() -> Result<(), GatewayError> {
    let gateway = Gateway::new(GatewayConfig::fake_local())?;
    let session = gateway.session_status().await?;
    let accounts = gateway.list_accounts().await?;

    println!("session={:?} accounts={}", session.status, accounts.len());
    Ok(())
}

Common CLI Commands

Developer Checks ✅

Use the repo-native gates before changing public behavior:

cargo fmt --check
cargo clippy --workspace --all-targets --features unstable-internal-test-support -- -D warnings
cargo test --workspace --features unstable-internal-test-support
# Focused replay of secret-scan and redaction tests by name filter:
cargo test --workspace --features unstable-internal-test-support secret

Useful packaging checks:

cargo package --allow-dirty --no-verify --list
cargo publish --dry-run --locked

Documentation

Start with docs/README.md. The main developer path is:

• Developer Guide
• Production Readiness
• Public API
• MCP
• Scopes
• Audit Log
• Testing
• Changelog

The linked docs above are the developer-facing source of truth for current behavior; this README is a high-level entry point.

Contributing 🤝

• Contribution Guide: workflow, branching, versioning, and safety areas requiring code-owner review.
• Security Policy: report vulnerabilities through GitHub Security Advisories — do not file public issues for credential exposure, live-gate bypasses, audit-redaction flaws, or OAuth validation issues.
• Code owners are listed in .github/CODEOWNERS; changes in src/internal/orders/, src/internal/audit/, src/internal/cpapi/, and src/internal/oauth/ require explicit review.