Evaluate exposure

curl --request POST \
  --url https://api.rook.pm/v1/evaluations:run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "positions": [
    {
      "position_id": "inventory_cut",
      "instrument": {
        "outcome_id": "out_fed_dec_2026_cut_yes"
      },
      "position_type": "HELD",
      "quantity": "1000"
    },
    {
      "position_id": "inventory_hold",
      "instrument": {
        "outcome_id": "out_fed_dec_2026_hold_yes"
      },
      "position_type": "HELD",
      "quantity": "300"
    }
  ],
  "candidates": [
    {
      "candidate_id": "sell_250_cut",
      "trades": [
        {
          "trade_id": "trade_cut_250",
          "instrument": {
            "outcome_id": "out_fed_dec_2026_cut_yes"
          },
          "quantity_delta": "-250"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.rook.pm/v1/evaluations:run"

payload = {
    "positions": [
        {
            "position_id": "inventory_cut",
            "instrument": { "outcome_id": "out_fed_dec_2026_cut_yes" },
            "position_type": "HELD",
            "quantity": "1000"
        },
        {
            "position_id": "inventory_hold",
            "instrument": { "outcome_id": "out_fed_dec_2026_hold_yes" },
            "position_type": "HELD",
            "quantity": "300"
        }
    ],
    "candidates": [
        {
            "candidate_id": "sell_250_cut",
            "trades": [
                {
                    "trade_id": "trade_cut_250",
                    "instrument": { "outcome_id": "out_fed_dec_2026_cut_yes" },
                    "quantity_delta": "-250"
                }
            ]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    positions: [
      {
        position_id: 'inventory_cut',
        instrument: {outcome_id: 'out_fed_dec_2026_cut_yes'},
        position_type: 'HELD',
        quantity: '1000'
      },
      {
        position_id: 'inventory_hold',
        instrument: {outcome_id: 'out_fed_dec_2026_hold_yes'},
        position_type: 'HELD',
        quantity: '300'
      }
    ],
    candidates: [
      {
        candidate_id: 'sell_250_cut',
        trades: [
          {
            trade_id: 'trade_cut_250',
            instrument: {outcome_id: 'out_fed_dec_2026_cut_yes'},
            quantity_delta: '-250'
          }
        ]
      }
    ]
  })
};

fetch('https://api.rook.pm/v1/evaluations:run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "evaluation_id": "eval_rates_sell_250_cut",
  "baseline": {
    "groups": [
      {
        "scenario_pins": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1"
          }
        ],
        "scenario_columns": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_cut"
          },
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_hold"
          },
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_hike"
          }
        ],
        "currency": "USDC",
        "total_scenario_count": 3,
        "terminal_payouts": [
          "1000",
          "300",
          "0"
        ],
        "minimum_payout": "0",
        "maximum_payout": "1000",
        "minimum_witnesses": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_hike"
          }
        ],
        "maximum_witnesses": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_cut"
          }
        ],
        "minimum_tie_count": 1,
        "maximum_tie_count": 1,
        "contributions": [
          {
            "position_id": "inventory_cut",
            "outcome_id": "out_fed_dec_2026_cut_yes",
            "values": [
              "1000",
              "0",
              "0"
            ]
          },
          {
            "position_id": "inventory_hold",
            "outcome_id": "out_fed_dec_2026_hold_yes",
            "values": [
              "0",
              "300",
              "0"
            ]
          }
        ]
      }
    ],
    "whole_book": [
      {
        "status": "EXACT",
        "currency": "USDC",
        "minimum": "0",
        "maximum": "1000",
        "minimum_witness": {
          "family_id": "fam_fed_dec_2026",
          "scenario_version": "1",
          "scenario_id": "scn_hike"
        },
        "maximum_witness": {
          "family_id": "fam_fed_dec_2026",
          "scenario_version": "1",
          "scenario_id": "scn_cut"
        }
      }
    ]
  },
  "candidates": [
    {
      "candidate_id": "sell_250_cut",
      "after": {
        "groups": [
          {
            "scenario_pins": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1"
              }
            ],
            "scenario_columns": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_cut"
              },
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_hold"
              },
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_hike"
              }
            ],
            "currency": "USDC",
            "total_scenario_count": 3,
            "terminal_payouts": [
              "750",
              "300",
              "0"
            ],
            "minimum_payout": "0",
            "maximum_payout": "750",
            "minimum_witnesses": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_hike"
              }
            ],
            "maximum_witnesses": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_cut"
              }
            ],
            "minimum_tie_count": 1,
            "maximum_tie_count": 1,
            "contributions": [
              {
                "position_id": "inventory_cut",
                "outcome_id": "out_fed_dec_2026_cut_yes",
                "values": [
                  "750",
                  "0",
                  "0"
                ]
              },
              {
                "position_id": "inventory_hold",
                "outcome_id": "out_fed_dec_2026_hold_yes",
                "values": [
                  "0",
                  "300",
                  "0"
                ]
              }
            ]
          }
        ],
        "whole_book": [
          {
            "status": "EXACT",
            "currency": "USDC",
            "minimum": "0",
            "maximum": "750",
            "minimum_witness": {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_hike"
            },
            "maximum_witness": {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_cut"
            }
          }
        ]
      },
      "delta_groups": [
        {
          "scenario_columns": [
            {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_cut"
            },
            {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_hold"
            },
            {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_hike"
            }
          ],
          "currency": "USDC",
          "payout_deltas": [
            "-250",
            "0",
            "0"
          ],
          "improved_count": 0,
          "worsened_count": 1
        }
      ]
    }
  ],
  "coverage": {
    "complete": true,
    "submitted_count": 2,
    "supported_count": 2,
    "items": [
      {
        "input_reference": "out_fed_dec_2026_cut_yes",
        "outcome_id": "out_fed_dec_2026_cut_yes",
        "status": "SUPPORTED",
        "family_ids": [
          "fam_fed_dec_2026"
        ]
      },
      {
        "input_reference": "out_fed_dec_2026_hold_yes",
        "outcome_id": "out_fed_dec_2026_hold_yes",
        "status": "SUPPORTED",
        "family_ids": [
          "fam_fed_dec_2026"
        ]
      }
    ]
  },
  "versions": {
    "market_versions": [
      {
        "market_id": "mkt_fed_dec_2026_cut",
        "version": "1"
      },
      {
        "market_id": "mkt_fed_dec_2026_hold",
        "version": "1"
      }
    ],
    "mapping_version": "1",
    "scenario_pins": [
      {
        "family_id": "fam_fed_dec_2026",
        "scenario_version": "1"
      }
    ],
    "as_of": "2026-10-19T12:00:00Z"
  },
  "pricing": [],
  "warnings": []
}

Payouts and exposure

Evaluate exposure

Calculate what supplied positions pay at settlement, and compare the effect of explicitly supplied hypothetical trades. Positions identify a Rook outcome/listing, a positive exact quantity and HELD or OWED convention. Candidates supply signed quantity changes; each candidate is evaluated separately against the same baseline.

Results include baseline and after-candidate payout groups, candidate deltas, best/worst cases with feasible witnesses, and requested contributions or rankings. Contributions reconcile to totals. Unrelated families or currencies remain separate; whole-book extrema are exact only when compatible joint witnesses exist.

Terminal payout is the settlement cash flow, not a probability or historical-entry P&L. Optional MIDPOINT or LIQUIDATION pricing uses Rook observations and reports missing or stale valuation inputs. No candidate fills, inventory writes or hedge discovery occur. Pin scenario versions to reproduce a result.

POST

evaluations:run

Evaluate exposure

curl --request POST \
  --url https://api.rook.pm/v1/evaluations:run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "positions": [
    {
      "position_id": "inventory_cut",
      "instrument": {
        "outcome_id": "out_fed_dec_2026_cut_yes"
      },
      "position_type": "HELD",
      "quantity": "1000"
    },
    {
      "position_id": "inventory_hold",
      "instrument": {
        "outcome_id": "out_fed_dec_2026_hold_yes"
      },
      "position_type": "HELD",
      "quantity": "300"
    }
  ],
  "candidates": [
    {
      "candidate_id": "sell_250_cut",
      "trades": [
        {
          "trade_id": "trade_cut_250",
          "instrument": {
            "outcome_id": "out_fed_dec_2026_cut_yes"
          },
          "quantity_delta": "-250"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.rook.pm/v1/evaluations:run"

payload = {
    "positions": [
        {
            "position_id": "inventory_cut",
            "instrument": { "outcome_id": "out_fed_dec_2026_cut_yes" },
            "position_type": "HELD",
            "quantity": "1000"
        },
        {
            "position_id": "inventory_hold",
            "instrument": { "outcome_id": "out_fed_dec_2026_hold_yes" },
            "position_type": "HELD",
            "quantity": "300"
        }
    ],
    "candidates": [
        {
            "candidate_id": "sell_250_cut",
            "trades": [
                {
                    "trade_id": "trade_cut_250",
                    "instrument": { "outcome_id": "out_fed_dec_2026_cut_yes" },
                    "quantity_delta": "-250"
                }
            ]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    positions: [
      {
        position_id: 'inventory_cut',
        instrument: {outcome_id: 'out_fed_dec_2026_cut_yes'},
        position_type: 'HELD',
        quantity: '1000'
      },
      {
        position_id: 'inventory_hold',
        instrument: {outcome_id: 'out_fed_dec_2026_hold_yes'},
        position_type: 'HELD',
        quantity: '300'
      }
    ],
    candidates: [
      {
        candidate_id: 'sell_250_cut',
        trades: [
          {
            trade_id: 'trade_cut_250',
            instrument: {outcome_id: 'out_fed_dec_2026_cut_yes'},
            quantity_delta: '-250'
          }
        ]
      }
    ]
  })
};

fetch('https://api.rook.pm/v1/evaluations:run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "evaluation_id": "eval_rates_sell_250_cut",
  "baseline": {
    "groups": [
      {
        "scenario_pins": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1"
          }
        ],
        "scenario_columns": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_cut"
          },
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_hold"
          },
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_hike"
          }
        ],
        "currency": "USDC",
        "total_scenario_count": 3,
        "terminal_payouts": [
          "1000",
          "300",
          "0"
        ],
        "minimum_payout": "0",
        "maximum_payout": "1000",
        "minimum_witnesses": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_hike"
          }
        ],
        "maximum_witnesses": [
          {
            "family_id": "fam_fed_dec_2026",
            "scenario_version": "1",
            "scenario_id": "scn_cut"
          }
        ],
        "minimum_tie_count": 1,
        "maximum_tie_count": 1,
        "contributions": [
          {
            "position_id": "inventory_cut",
            "outcome_id": "out_fed_dec_2026_cut_yes",
            "values": [
              "1000",
              "0",
              "0"
            ]
          },
          {
            "position_id": "inventory_hold",
            "outcome_id": "out_fed_dec_2026_hold_yes",
            "values": [
              "0",
              "300",
              "0"
            ]
          }
        ]
      }
    ],
    "whole_book": [
      {
        "status": "EXACT",
        "currency": "USDC",
        "minimum": "0",
        "maximum": "1000",
        "minimum_witness": {
          "family_id": "fam_fed_dec_2026",
          "scenario_version": "1",
          "scenario_id": "scn_hike"
        },
        "maximum_witness": {
          "family_id": "fam_fed_dec_2026",
          "scenario_version": "1",
          "scenario_id": "scn_cut"
        }
      }
    ]
  },
  "candidates": [
    {
      "candidate_id": "sell_250_cut",
      "after": {
        "groups": [
          {
            "scenario_pins": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1"
              }
            ],
            "scenario_columns": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_cut"
              },
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_hold"
              },
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_hike"
              }
            ],
            "currency": "USDC",
            "total_scenario_count": 3,
            "terminal_payouts": [
              "750",
              "300",
              "0"
            ],
            "minimum_payout": "0",
            "maximum_payout": "750",
            "minimum_witnesses": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_hike"
              }
            ],
            "maximum_witnesses": [
              {
                "family_id": "fam_fed_dec_2026",
                "scenario_version": "1",
                "scenario_id": "scn_cut"
              }
            ],
            "minimum_tie_count": 1,
            "maximum_tie_count": 1,
            "contributions": [
              {
                "position_id": "inventory_cut",
                "outcome_id": "out_fed_dec_2026_cut_yes",
                "values": [
                  "750",
                  "0",
                  "0"
                ]
              },
              {
                "position_id": "inventory_hold",
                "outcome_id": "out_fed_dec_2026_hold_yes",
                "values": [
                  "0",
                  "300",
                  "0"
                ]
              }
            ]
          }
        ],
        "whole_book": [
          {
            "status": "EXACT",
            "currency": "USDC",
            "minimum": "0",
            "maximum": "750",
            "minimum_witness": {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_hike"
            },
            "maximum_witness": {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_cut"
            }
          }
        ]
      },
      "delta_groups": [
        {
          "scenario_columns": [
            {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_cut"
            },
            {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_hold"
            },
            {
              "family_id": "fam_fed_dec_2026",
              "scenario_version": "1",
              "scenario_id": "scn_hike"
            }
          ],
          "currency": "USDC",
          "payout_deltas": [
            "-250",
            "0",
            "0"
          ],
          "improved_count": 0,
          "worsened_count": 1
        }
      ]
    }
  ],
  "coverage": {
    "complete": true,
    "submitted_count": 2,
    "supported_count": 2,
    "items": [
      {
        "input_reference": "out_fed_dec_2026_cut_yes",
        "outcome_id": "out_fed_dec_2026_cut_yes",
        "status": "SUPPORTED",
        "family_ids": [
          "fam_fed_dec_2026"
        ]
      },
      {
        "input_reference": "out_fed_dec_2026_hold_yes",
        "outcome_id": "out_fed_dec_2026_hold_yes",
        "status": "SUPPORTED",
        "family_ids": [
          "fam_fed_dec_2026"
        ]
      }
    ]
  },
  "versions": {
    "market_versions": [
      {
        "market_id": "mkt_fed_dec_2026_cut",
        "version": "1"
      },
      {
        "market_id": "mkt_fed_dec_2026_hold",
        "version": "1"
      }
    ],
    "mapping_version": "1",
    "scenario_pins": [
      {
        "family_id": "fam_fed_dec_2026",
        "scenario_version": "1"
      }
    ],
    "as_of": "2026-10-19T12:00:00Z"
  },
  "pricing": [],
  "warnings": []
}

See the integration guide for the workflow and interpretation of this response.

Authorizations

Authorization

string

header

required

Proposed server-to-server API key. No client request HMAC signing scheme is specified.

Headers

X-Client-Request-Id

string

Caller correlation reference; not an idempotency guarantee.

Body

application/json

Option 1
Option 2

At least one position or candidate is required. Empty positions is valid for standalone candidate analysis. All supplied holdings and candidates use a common comparison scope; selected scenarios condition the result.

positions

object[]

required

Current client positions with HELD/OWED convention and positive exact quantities; may be empty for standalone candidates.

Minimum array length: 1

Show child attributes

candidates

object[]

Optional independently evaluated alternatives; trades inside each candidate form one simultaneous package.

Show child attributes

scenario_pins

object[]

Optional family/version pins for the supplied book plus all candidates; current compatible versions chosen once otherwise.

Show child attributes

scenarios

object[]

Optional selected column references; conditions results on exactly that scenario domain.

Minimum array length: 1

Option 1
Option 2

Show child attributes

include

enum<string>[]

Requested result detail; default SUMMARY. Full vectors must fit declared scope or fail explicitly.

Available options:

SUMMARY,

PAYOUTS,

CONTRIBUTIONS,

OFFSETS,

SCENARIOS

ranking

object

Metric, direction and positive result limit; ranks the whole stated domain before limiting returned results.

Show child attributes

pricing

object

Rook price convention and optional maximum quote age; default mode NONE means payout-only.

Show child attributes

require_complete_coverage

boolean

default:true

True rejects incomplete structural coverage; false preserves explicitly scoped partial results.

Response

200 - application/json

Success.

Trace ID does not imply a saved portfolio or GET-able evaluation. Full-scope extrema are not calculated from a truncated response page.

evaluation_id

string

required

Opaque text identifier. Preserve its exact value.

Minimum string length: 1

baseline

object

required

Show child attributes

candidates

object[]

required

Show child attributes

coverage

object

required

Show child attributes

versions

object

required

Show child attributes

pricing

object[]

required

Show child attributes

warnings

string[]

required

Reference data

Families and scenarios

Relationships and Combos

Payouts and exposure

Market data

Fair values · future

Coverage and updates

Evaluate exposure

Authorizations

Headers

Body

Response