Core Tools

The 4 core tools are the foundation of System R. They cover position sizing, risk validation, and performance evaluation.

calculate_position_size

Cost: $0.003 | Calculate optimal position size using the G-formula (geometric growth optimization).

Parameters

Parameter	Type	Required	Description
equity	string	Yes	Account equity in USD (e.g. "100000").
entry_price	string	Yes	Planned entry price (e.g. "185.50").
stop_price	string	Yes	Stop loss price (e.g. "180.00").
direction	string	Yes	"long" or "short".
risk_percent	string	No	Risk as decimal (e.g. "0.02" for 2%). Defaults to 2%.

Example

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

Response

{
  "shares": 363,
  "risk_amount": "2000.00",
  "risk_percent": "0.02",
  "notional": "67351.50",
  "one_r_dollars": "2000.00",
  "direction": "long"
}

Field	Type	Description
shares	int	Number of shares to trade.
risk_amount	string	Dollar amount at risk (equity * risk_percent).
risk_percent	string	Actual risk fraction applied.
notional	string	Total position value (shares * entry_price).
one_r_dollars	string	Dollar value of one R-unit (risk per share * shares).
direction	string	Trade direction.

---

check_trade_risk

Cost: $0.004 | Validate a proposed trade against Iron Fist risk rules.

Checks: single position risk, portfolio-level risk, daily loss limits, and position count constraints.

Parameters

Parameter	Type	Required	Description
symbol	string	Yes	Instrument symbol (e.g. "AAPL").
direction	string	Yes	"long" or "short".
entry_price	string	Yes	Entry price.
stop_price	string	Yes	Stop loss price.
quantity	string	Yes	Number of shares/contracts.
equity	string	Yes	Account equity in USD.
daily_pnl	string	No	Daily P&L so far. Defaults to "0".

Example

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

if result["approved"]:
    print(f"Trade approved. Risk score: {result['score']}")
else:
    print(f"Trade rejected: {result['errors']}")

Response

{
  "approved": true,
  "score": 85,
  "errors": [],
  "warnings": [],
  "risk_amount": "550.00",
  "risk_percent": "0.0055"
}

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. Non-empty means trade rejected.
warnings	string[]	Non-blocking concerns. Trade approved but review recommended.
risk_amount	string	Dollar risk for this trade.
risk_percent	string	Risk as a fraction of equity.

---

evaluate_performance

Cost: $0.10 (basic), $0.50 (full), $1.00 (comprehensive) | Evaluate trading system performance using G-metric analysis.

Three evaluation tiers provide increasing depth of analysis.

Parameters

Parameter	Type	Required	Description
r_multiples	string[]	Yes	R-multiples from trade history (minimum 2).
tier	string	No	"basic", "full", or "comprehensive". Defaults to "basic".
window_size	int	No	Rolling window size. Defaults to 10.

Basic tier ($0.10)

result = client.basic_eval(
    r_multiples=["1.5", "-1.0", "2.3", "-0.5", "1.8", "-1.0", "3.2", "0.8"],
)

{
  "g": "0.0847",
  "expected_r": "0.7875",
  "variance": "2.1543",
  "volatility": "1.4678",
  "trade_count": 8,
  "verdict": "POSITIVE_EDGE"
}

Full tier ($0.50)

Adds System R Score (0 to 100 composite grade) and rolling G trend analysis.

result = client.full_eval(
    r_multiples=["1.5", "-1.0", "2.3", "-0.5", "1.8", "-1.0", "3.2", "0.8"],
    window_size=5,
)

{
  "g": "0.0847",
  "expected_r": "0.7875",
  "variance": "2.1543",
  "volatility": "1.4678",
  "trade_count": 8,
  "verdict": "POSITIVE_EDGE",
  "score": 72,
  "score_grade": "B",
  "rolling_g_trend": "IMPROVING",
  "rolling_g_slope": "0.0032"
}

Comprehensive tier ($1.00)

Adds score component breakdown and next-trade G impact analysis.

{
  "g": "0.0847",
  "expected_r": "0.7875",
  "variance": "2.1543",
  "volatility": "1.4678",
  "trade_count": 8,
  "verdict": "POSITIVE_EDGE",
  "score": 72,
  "score_grade": "B",
  "score_components": {
    "g_metric": 18,
    "consistency": 15,
    "risk_management": 14,
    "expectancy": 13,
    "drawdown_resilience": 12
  },
  "rolling_g_trend": "IMPROVING",
  "rolling_g_slope": "0.0032",
  "g_impact_next_win": "0.0912",
  "g_impact_next_loss": "0.0783"
}

---

get_pricing

Cost: Free | Get current pricing for all operations. No authentication required.

Example

pricing = client.get_pricing()
for operation, cost in pricing["prices"].items():
    print(f"{operation}: ${cost}")

Response

{
  "prices": {
    "position_sizing": "0.003",
    "risk_check": "0.004",
    "basic_eval": "0.10",
    "full_eval": "0.50",
    "comprehensive_eval": "1.00",
    "pre_trade_gate": "0.01",
    "assess_trading_system": "2.00",
    "...": "..."
  },
  "currency": "USDC"
}