First API Call

The pre_trade_gate

The best first call is pre_trade_gate. It combines three operations (position sizing, risk validation, system health) into one call for $0.01.

from systemr import SystemRClient

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

result = client.pre_trade_gate(
    symbol="AAPL",
    direction="long",
    entry_price="185.50",
    stop_price="180.00",
    equity="100000",
)

Reading the response

{
  "gate_passed": true,
  "sizing": {
    "shares": 363,
    "risk_amount": "2000.00",
    "risk_percent": "0.02",
    "notional": "67351.50",
    "one_r_dollars": "2000.00",
    "direction": "long"
  },
  "risk": {
    "approved": true,
    "score": 82,
    "errors": [],
    "warnings": [],
    "risk_amount": "2000.00",
    "risk_percent": "0.02"
  },
  "system_health": null
}

Field breakdown

Top level:

Field	Type	Description
gate_passed	bool	true if both sizing and risk check succeeded.
sizing	object	Position sizing result from the G-formula.
risk	object	Iron Fist risk validation result.
system_health	object or null	System health check. Present only if you pass r_multiples.

Sizing:

Field	Type	Description
shares	int	Number of shares to buy.
risk_amount	string	Dollar amount at risk.
risk_percent	string	Risk as a fraction of equity (0.02 = 2%).
notional	string	Total position value in dollars.
one_r_dollars	string	Dollar value of one R-unit.
direction	string	Trade direction (long or short).

Risk:

Field	Type	Description
approved	bool	true if the trade passes all risk rules.
score	int	Risk score from 0 (worst) to 100 (best).
errors	string[]	Blocking issues that prevented approval.
warnings	string[]	Non-blocking concerns.

Adding system health

Pass your recent R-multiples to include a system health check:

result = 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.3", "-0.5", "1.8", "-1.0", "3.2", "0.8"],
)

if result["system_health"]:
    print(f"G Score: {result['system_health']['g']}")
    print(f"Verdict: {result['system_health']['verdict']}")

How billing works

Every tool call deducts from your compute credit balance:

1. System R checks your balance before executing the tool.
2. If the balance is sufficient, the call executes and the cost is deducted.
3. If the balance is insufficient, you receive a 402 error. No charge.

Check your balance:

balance = client.get_balance()
print(f"Balance: ${balance['balance']}")
print(f"Low balance warning: {balance['is_low']}")

The is_low flag turns true when your balance drops below $0.01.

Using the generic tool call

Every tool can be called through the universal endpoint:

# Named method (convenience)
result = client.pre_trade_gate(symbol="AAPL", ...)

# Generic tool call (works for all 55 tools)
result = client.call_tool(
    "pre_trade_gate",
    symbol="AAPL",
    direction="long",
    entry_price="185.50",
    stop_price="180.00",
    equity="100000",
)

The generic call_tool method maps to POST /v1/tools/call:

curl -X POST https://agents.systemr.ai/v1/tools/call \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "pre_trade_gate",
    "arguments": {
      "symbol": "AAPL",
      "direction": "long",
      "entry_price": "185.50",
      "stop_price": "180.00",
      "equity": "100000"
    }
  }'

Next calls to try

Tool	Cost	What it does
calculate_position_size	$0.003	G-formula position sizing alone.
check_trade_risk	$0.004	Iron Fist risk validation alone.
evaluate_performance	$0.10	G-metric analysis from R-multiples.
run_monte_carlo	$0.008	Simulate 1,000 future equity paths.
assess_trading_system	$2.00	Complete system diagnostic (7 tools in one).

See the full tools reference for all 55 tools.