systemr

Python SDK for agents.systemr.ai — Trading & Investment Operating System for AI agents.

47 tools for position sizing, risk validation, regime detection, Greeks analysis, equity curves, Monte Carlo simulation, signal scoring, trade planning, compliance checks, and more.

Install

pip install systemr

Quick Start

from systemr import SystemRClient

client = SystemRClient(api_key="sr_agent_...")

# Pre-trade gate: sizing + risk + health in one call ($0.01)
gate = client.pre_trade_gate(
    symbol="AAPL",
    direction="long",
    entry_price="185.50",
    stop_price="180.00",
    equity="100000",
)
if gate["gate_passed"]:
    print(f"Buy {gate['sizing']['shares']} shares")

Three Ways to Use Tools

1. Named Methods (common operations)

# Position sizing ($0.003)
size = client.calculate_position_size(
    equity="100000", entry_price="185.50",
    stop_price="180.00", direction="long",
)

# Risk validation ($0.004)
risk = client.check_risk(
    symbol="AAPL", direction="long",
    entry_price="185.50", stop_price="180.00",
    quantity="100", equity="100000",
)

# Pre-trade gate ($0.01)
gate = client.pre_trade_gate(
    symbol="AAPL", direction="long",
    entry_price="185.50", stop_price="180.00",
    equity="100000", r_multiples=["1.5", "-1.0", "2.0"],
)

# System assessment ($2.00)
assessment = client.assess_system(
    r_multiples=["1.5", "-1.0", "2.0", "-0.5", "1.8",
                 "0.8", "-0.3", "2.5", "-1.0", "1.2"],
)
print(assessment["verdict"])  # STRONG_SYSTEM, VIABLE_SYSTEM, etc.

2. Generic Tool Call (all 47 tools)

# Equity curve from R-multiples ($0.004)
curve = client.call_tool("calculate_equity_curve",
    r_multiples=["1.5", "-1.0", "2.0", "-0.5", "1.8"],
    starting_equity="100000",
)
print(curve["total_return"], curve["max_drawdown_pct"])

# Signal quality scoring ($0.003)
signal = client.call_tool("score_signal",
    conditions_met=4, total_conditions=5,
    regime_aligned=True, indicator_confluence=3,
    volume_confirmed=True, risk_reward_ratio="2.5",
)

# Regime detection ($0.006)
regime = client.call_tool("detect_regime",
    prices=["180", "182", "179", "185", "188", "186"],
)

# Greeks analysis ($0.006)
greeks = client.call_tool("analyze_greeks",
    chain=[{
        "symbol": "AAPL240315C00185000",
        "underlying_symbol": "AAPL",
        "strike": "185", "expiration": "2024-03-15",
        "option_type": "CALL", "bid": "5.20", "ask": "5.50",
        "last": "5.35", "volume": 1000, "open_interest": 5000,
        "implied_volatility": "0.25",
    }],
    underlying_price="185.50",
)

# List all available tools
tools = client.list_tools()
print(f"{tools['tool_count']} tools available")

3. Workflow Chains (multi-tool sequences)

# Full backtest diagnostic (6 tools, ~$0.032)
diag = client.run_backtest_diagnostic(
    r_multiples=["1.5", "-1.0", "2.0", "-0.5", "1.8",
                 "0.8", "-0.3", "2.5", "-1.0", "1.2"],
    starting_equity="100000",
)
print(diag["system_r_score"]["grade"])       # A, B, C, D, F
print(diag["equity_curve"]["total_return"])   # total return
print(diag["monte_carlo"]["median_final_equity"])
print(diag["variance_killers"])              # what's hurting G

# Post-trade analysis (2 tools, $0.006)
post = client.run_post_trade_analysis(
    realized_pnl="500.00", realized_r="1.50",
    mfe="800.00", one_r_dollars="333.33",
    entry_price="180.00", exit_price="185.00",
    quantity=100, direction="LONG",
)
print(post["outcome"]["outcome"])            # WIN/LOSS/BREAKEVEN
print(post["outcome"]["efficiency_score"])   # how much R captured

# Market scan + signal scoring (2+ tools, $0.005+)
scan = client.run_market_scan(
    symbols=["AAPL", "MSFT", "GOOGL"],
    conditions=["rsi_oversold", "volume_spike"],
    market_data={
        "AAPL": {"indicators": {"rsi_14": "25", "relative_volume": "2.0"},
                 "current_price": "180.00", "regime": "RANGING", "atr": "3.50"},
        "MSFT": {"indicators": {"rsi_14": "55", "relative_volume": "0.8"},
                 "current_price": "400.00", "regime": "TRENDING_UP", "atr": "5.00"},
    },
)
for signal in scan["scored_signals"]:
    print(f"{signal['symbol']}: confidence={signal['signal_confidence']}")

Trade Journal

# Record a completed trade (billed via MCP)
client.record_trade(
    symbol="AAPL",
    direction="long",
    entry_price="180.00",
    exit_price="185.50",
    stop_price="177.00",
    quantity="100",
    r_multiple="1.83",
    pnl="550.00",
    trade_date="2026-03-09",
    notes="Breakout above resistance with volume confirmation",
)

# Get journal stats (free)
stats = client.get_journal_stats()
print(stats["win_rate"])       # e.g. "0.62"
print(stats["avg_r_multiple"]) # e.g. "0.85"
print(stats["total_pnl"])      # e.g. "4250.00"

# Feed journal R-multiples into system assessment
r_data = client.get_journal_r_multiples(limit=100)
assessment = client.assess_system(r_multiples=r_data["r_multiples"])
print(assessment["verdict"])

All 47 Tools

Use client.list_tools() for the full list with descriptions and input schemas.

Workflow Cookbook

See examples/workflow_cookbook.py for 5 complete runnable workflows:

1. Pre-Trade Gate — call before every trade ($0.01)
2. Backtest Diagnostic — 6-tool chain for system analysis (~$0.032)
3. Post-Trade Analysis — execution quality review ($0.006)
4. Market Scan — watchlist screening + signal scoring ($0.005+)
5. System Assessment — comprehensive edge evaluation ($2.00)

Plus a full agent loop combining all workflows.

Get an API Key

import httpx

resp = httpx.post("https://agents.systemr.ai/v1/agents/register", json={
    "owner_id": "your-id",
    "agent_name": "my-trading-agent",
    "agent_type": "trading",
})
data = resp.json()
print(data["api_key"])  # sr_agent_... (save this, shown only once)

Free tier: $30 USDC credited on registration (~10,000+ basic tool calls).

Error Handling

from systemr import SystemRClient, AuthenticationError, InsufficientBalanceError, SystemRError

client = SystemRClient(api_key="sr_agent_...")

try:
    result = client.call_tool("detect_regime", prices=["180", "182", "179"])
except AuthenticationError:
    print("Invalid API key or agent inactive")
except InsufficientBalanceError:
    print("Deposit USDC to continue")
except SystemRError as e:
    print(f"API error {e.status_code}: {e.detail}")

Context Manager

with SystemRClient(api_key="sr_agent_...") as client:
    gate = client.pre_trade_gate(
        symbol="AAPL", direction="long",
        entry_price="185.50", stop_price="180.00",
        equity="100000",
    )

MCP (Model Context Protocol)

System R is also available as an MCP server in the official MCP Registry. Any MCP-compatible agent (Claude, ChatGPT, etc.) can connect directly:

{
  "mcpServers": {
    "systemr": {
      "url": "https://agents.systemr.ai/mcp/sse",
      "transport": "sse"
    }
  }
}

Links

• Live API — Production endpoint
• Demo Agent — Reference implementation with workflow examples
• MCP Registry — MCP server listing

License

MIT