Risk observations

Query open-interest observations for supported perpetual listings.

GET/api/v1/risk/observations
Domain
Risk & Compliance
Level
One object, metric and observation time per record
MCP tool
risk_compliance_query (task=observations)

Available data

Returns
Query open-interest observations for supported perpetual listings.
What each request returns
One object, metric and observation time per record

Authentication

Send Authorization: Bearer YOUR_API_KEY or X-API-KEY on every request.

Requires an API key with Risk permission.

Query Parameters

Query objects

REST uses a URL-encoded JSON array; MCP uses a JSON array directly. Valid identifiers do not guarantee data coverage

object_refsstringqueryExample[{"type":"listing","id":"listing_gate_BTC_USDT_perp"}]required

URL-encoded JSON array of listing, instrument, asset, asset_entity or chain_contract references. MCP takes an array directly. chain_contract requires chain_id and contract_address; a valid reference does not guarantee coverage

Metrics and records

Enum values describe accepted inputs; available data depends on the queried object and metric

risk_typestringqueryoptional

Filter by risk category. · market / liquidity / credit / operational / protocol / security / regulatory / macro

metric_codestringqueryExample["open_interest"]optional

Metric codes as a JSON array string, up to 20 items; for example ["open_interest"]. MCP takes an array

record_kindstringqueryoptional

Record kinds: disclosed_fact, derived_metric, alert, incident. Multiple values use a JSON array string; MCP accepts an array

Time range

start and end must be supplied together. as_of is the observation cutoff, not the returned observation time

startstringqueryExample2026-11-04T20:00:00Zoptional

Inclusive RFC3339 UTC start time. Supply start and end together

endstringqueryExample2026-11-05T00:00:00Zoptional

Inclusive RFC3339 UTC end time, not earlier than start. Supply both bounds together

as_ofstringqueryoptional

RFC3339 UTC cutoff, default current UTC time. Returned observations may be older; check resolved_as_of

Filters and pagination

limit is 1–200. Reuse metadata.next_cursor without changing other filters

limitintegerqueryExample5optional

Maximum rows returned. · Default: 50 · ≥ 1 · ≤ 200

cursorstringqueryoptional

Opaque metadata.next_cursor from the previous response. Keep the other filters unchanged

Object input templates

These are input shapes, not proof of coverage. Use the verified listing example for covered open-interest observations.

Identifier object
JSON
[
  {
    "type": "listing",
    "id": "listing_gate_BTC_USDT_perp"
  }
]
Chain contract object
JSON
[
  {
    "type": "chain_contract",
    "chain_id": "ethereum",
    "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
]

Response

dataobject | null

Business data; shape is specific to this endpoint

itemsobject[]

Task-specific risk rows

items[]array[object]
metric_codestring

Metric identifier, such as open_interest

object_resolution_statusstring

Object matching status

observation_endstring

Observation end time

observation_startstring

Observation start time

published_atstring | null

Source publication time, or null

record_kindstring

Record kind

risk_observation_idstring

Observation identifier

risk_typestring | null

Risk category

source_locatorstring

Source field and interval

source_record_idstring | null

Source record identifier, or null

source_task_idstring

Source task identifier

source_urlstring | null

Source evidence URL, or null

target_ref_keystring | null

Resolved target identifier; use returned values rather than constructing it from symbols

unitstring | null

Value unit; the verified OI example uses usd

value_boolboolean | null

Boolean value, or null

value_jsonunknown | null

Structured value, or null

value_numericnumber | null

Numeric observation value; interpret with unit

value_textstring | null

Text value, or null

missing_metricsstring[]

Requested metric codes that are not covered

data_statusDataStatus

Business status: verified/ok, partial, no_data or not_ready. HTTP 200 alone does not establish coverage

empty_reasonstring | null

Reason for an empty or unavailable result; may be absent

errorobject | null

Null on success; otherwise an error string or object

codestring

Error code

detailsobject

Additional error details

messagestring

Error explanation

retryableboolean

Whether the error can be retried

generated_atstring

Response generation time, not the observation time

metadataobject

Response metadata

has_moreboolean

Whether a subsequent page is available

next_cursorstring | null

Opaque cursor; null when no next page is available

object_refsobject[]

Matched object references

object_refs[]array[object]
asset_entity_idstring | null

Asset entity identifier

asset_idstring | null

Canonical asset identifier

chain_idstring | null

Canonical chain identifier

contract_addressstring | null

Token contract address associated with chain_id

idstring | null

Canonical object identifier

instrument_idstring | null

Instrument identifier

listing_idstring | null

Listing identifier

quote_currencystring | null

Quote currency hint

symbolstring | null

Asset or pool token symbol

Reference type: listing, instrument, asset, asset_entity or chain_contract

venue_idstring | null

Venue identifier

requested_as_ofstring | null

Requested cutoff time

resolved_as_ofstring | null

Latest available observation at or before the cutoff; can be older than the request

unresolved_object_refsobject[]

References that could not be resolved

unresolved_object_refs[]array[object]
asset_entity_idstring | null

Asset entity identifier

asset_idstring | null

Canonical asset identifier

chain_idstring | null

Canonical chain identifier

contract_addressstring | null

Token contract address associated with chain_id

idstring | null

Canonical object identifier

instrument_idstring | null

Instrument identifier

listing_idstring | null

Listing identifier

quote_currencystring | null

Quote currency hint

symbolstring | null

Asset or pool token symbol

typestring

Reference type: listing, instrument, asset, asset_entity or chain_contract

venue_idstring | null

Venue identifier

request_idstring

Request trace identifier

Errors & fallback

200
The requested data is returned.
200
Partial coverage; inspect data.missing_metrics for missing metrics and the returned fields.
200
Object resolved, but data is not covered; this does not establish absence of risk.
200
Object unresolved; check IDs and metadata.unresolved_object_refs.
400
Invalid parameters, time-bound pairing or range; limit must be 1–200.
401
Check the API key.
403
Check Risk permission for the key.