Skip to main content

Risk Score

Every /v1/validate response includes a risk_score (0-100) and a recommendation that summarizes the overall risk of the proposed trade.

Score Ranges​

ScoreRecommendationMeaning
0 - 40proceedRisk is within acceptable bounds. The trade can be executed as proposed.
41 - 70proceed_with_cautionElevated risk detected. Consider reducing size, lowering leverage, or reviewing the specific flags.
71 - 100abortHigh risk. One or more critical risk factors are present. The trade should not be executed as proposed.

How the Score Works​

The risk score is a weighted composite of multiple independent risk models that run in parallel:

  • Liquidation proximity - How close the position would be to liquidation
  • Value-at-Risk - Statistical worst-case loss over 24 hours
  • Open interest utilization - How crowded the asset is relative to its capacity
  • Slippage - Expected execution cost from order book depth
  • Funding cost - Projected funding rate burden
  • Market impact - How much the trade itself would move the price

When multiple risk factors are elevated simultaneously, the score increases non-linearly to reflect compounding risk. For example, high leverage combined with a thin order book is more dangerous than either condition alone.

Close Positions​

When action is "close", the risk score is capped at 30 (always proceed). Closing a position reduces risk, so Canon does not block exits.

Using Recommendations in Your Agent​

A minimal integration gates execution on the recommendation:

result = canon.validate(asset="ETH", action="long", size=50000, leverage=10, wallet="0x...")

if result.recommendation == "proceed":
    execute_trade()
elif result.recommendation == "proceed_with_caution":
    execute_trade_with_reduced_size(result.safe_size)
else:
    log_and_skip(result.flags)

For more nuanced control, use the individual risk model outputs (slippage, liquidation, funding, etc.) to make asset-specific or strategy-specific decisions.