POST /v1/outcome

Record the outcome of a completed trade. This enables the risk engine to track prediction accuracy and improve calibration over time.

Request

POST https://api.canonprotocol.org/v1/outcome

Headers

Header	Required	Value
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes	application/json

Body

{
  "trade_id": "trade_abc123",
  "asset": "BTC",
  "action": "long",
  "entry_price": 67500.00,
  "exit_price": 68200.00,
  "size": 50000,
  "leverage": 10,
  "risk_score_at_entry": 35,
  "calibration_hash": "a1b2c3d4...",
  "pnl_usd": 518.50,
  "pnl_pct": 10.37,
  "holding_period_hours": 4.5,
  "fees_paid_usd": 35.00,
  "funding_paid_usd": 12.30
}

Field	Type	Required	Description
trade_id	string	Yes	Unique identifier for this trade
asset	string	Yes	Asset ticker
action	string	Yes	"long" or "short"
entry_price	number	Yes	Average entry price
exit_price	number	Yes	Average exit price
size	number	Yes	Position size in USD
leverage	number	Yes	Leverage used
risk_score_at_entry	number	Yes	Risk score returned by /v1/validate at trade entry
calibration_hash	string	Yes	Calibration hash from the validate response's model_version
pnl_usd	number	Yes	Realized profit/loss in USD
pnl_pct	number	Yes	Realized profit/loss as percentage of margin
holding_period_hours	number	Yes	How long the position was held
fees_paid_usd	number	No	Total fees paid (default: 0)
funding_paid_usd	number	No	Total funding paid (default: 0)

Response

{
  "status": "recorded",
  "trade_id": "trade_abc123"
}

Outcome Statistics

Retrieve aggregate accuracy metrics from recorded outcomes:

GET https://api.canonprotocol.org/v1/outcomes/stats

Response

{
  "total_outcomes": 1250,
  "brier_score": 0.18,
  "calibration_curve": [
    {
      "predicted_risk_range": "0-10",
      "count": 320,
      "actual_loss_rate": 0.08,
      "avg_pnl_pct": 4.2
    }
  ],
  "band_stats": [
    {
      "recommendation": "proceed",
      "count": 680,
      "profitable_pct": 72.5,
      "avg_pnl_pct": 3.8,
      "avg_pnl_usd": 450.20
    },
    {
      "recommendation": "caution",
      "count": 410,
      "profitable_pct": 48.2,
      "avg_pnl_pct": -1.2,
      "avg_pnl_usd": -180.50
    },
    {
      "recommendation": "abort",
      "count": 160,
      "profitable_pct": 22.0,
      "avg_pnl_pct": -12.5,
      "avg_pnl_usd": -2100.00
    }
  ]
}

Field	Type	Description
total_outcomes	number	Total recorded trade outcomes
brier_score	number	Brier score (0 = perfect calibration, 1 = worst). Measures how well risk scores predict actual losses
calibration_curve	array	Per-decile breakdown of predicted risk vs actual loss rate
band_stats	array	Accuracy statistics grouped by recommendation band (proceed/caution/abort)