System R AI Docs

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 position sizing, risk validation, and optional system health inputs into one structured response.

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']}")

System R AI uses usage-based credits for paid workflows. Billing can depend on the operation, provider path, and current metering rules. Use the live pricing endpoint as the source of truth before production use.

For paid operations:

System R checks your balance before executing the operation.
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 reflects the current account threshold returned by the billing service.

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
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	What it does
`calculate_position_size`	Position sizing from account, entry, stop, direction, and risk inputs.
`check_trade_risk`	Pre-trade risk validation from supplied trade details.
`evaluate_performance`	Performance diagnostics from R-multiples.
`run_monte_carlo`	Simulate possible equity paths from supplied assumptions.
`assess_trading_system`	System diagnostics from supplied performance data.

See the tools reference and live discovery output for current tools, schemas, and pricing.

System R AI

Python SDK	`pip install systemr`
MCP Server	agents.systemr.ai/mcp/sse
OpenAPI Spec	agents.systemr.ai/v1/openapi.json
Machine Docs	agents.systemr.ai/llms.txt
GitHub	System-R-AI
X	@Systemrai
YouTube	@systemr_ai
Email	hello@systemr.ai
Phone	`628 333 6693`
Address	`7901 4TH ST N, STE 28529, ST PETERSBURG, FL 33702`
Terms	Terms of Service
Privacy	Privacy Policy
Security	Security Policy

First API Call