System R AI

Walk through your first tool call, understand the response, and see how billing works.

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:

System R checks your balance before executing the tool.
If the balance is sufficient, the call executes and the cost is deducted.
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.