Risk observations
Query open-interest observations for supported perpetual listings.
Available data
- Returns
- Query open-interest observations for supported perpetual listings.
- What each request returns
- One object, metric and observation time per record
Authentication
Requires an API key with Risk permission.
Query Parameters
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"}]requiredURL-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
Enum values describe accepted inputs; available data depends on the queried object and metric
risk_typestringqueryoptionalFilter by risk category. · market / liquidity / credit / operational / protocol / security / regulatory / macro
metric_codestringqueryExample["open_interest"]optionalMetric codes as a JSON array string, up to 20 items; for example ["open_interest"]. MCP takes an array
record_kindstringqueryoptionalRecord kinds: disclosed_fact, derived_metric, alert, incident. Multiple values use a JSON array string; MCP accepts an array
start and end must be supplied together. as_of is the observation cutoff, not the returned observation time
startstringqueryExample2026-11-04T20:00:00ZoptionalInclusive RFC3339 UTC start time. Supply start and end together
endstringqueryExample2026-11-05T00:00:00ZoptionalInclusive RFC3339 UTC end time, not earlier than start. Supply both bounds together
as_ofstringqueryoptionalRFC3339 UTC cutoff, default current UTC time. Returned observations may be older; check resolved_as_of
limit is 1–200. Reuse metadata.next_cursor without changing other filters
limitintegerqueryExample5optionalMaximum rows returned. · Default: 50 · ≥ 1 · ≤ 200
cursorstringqueryoptionalOpaque 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.
[
{
"type": "listing",
"id": "listing_gate_BTC_USDT_perp"
}
][
{
"type": "chain_contract",
"chain_id": "ethereum",
"contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
]Response
Business data; shape is specific to this endpoint
itemsobject[]Task-specific risk rows
metric_codestringMetric identifier, such as open_interest
object_resolution_statusstringObject matching status
observation_endstringObservation end time
observation_startstringObservation start time
published_atstring | nullSource publication time, or null
record_kindstringRecord kind
risk_observation_idstringObservation identifier
risk_typestring | nullRisk category
source_locatorstringSource field and interval
source_record_idstring | nullSource record identifier, or null
source_task_idstringSource task identifier
source_urlstring | nullSource evidence URL, or null
target_ref_keystring | nullResolved target identifier; use returned values rather than constructing it from symbols
unitstring | nullValue unit; the verified OI example uses usd
value_boolboolean | nullBoolean value, or null
value_jsonunknown | nullStructured value, or null
value_numericnumber | nullNumeric observation value; interpret with unit
value_textstring | nullText value, or null
missing_metricsstring[]Requested metric codes that are not covered
data_statusDataStatusBusiness status: verified/ok, partial, no_data or not_ready. HTTP 200 alone does not establish coverage
empty_reasonstring | nullReason for an empty or unavailable result; may be absent
Null on success; otherwise an error string or object
codestringError code
detailsobjectAdditional error details
messagestringError explanation
retryablebooleanWhether the error can be retried
generated_atstringResponse generation time, not the observation time
Response metadata
has_morebooleanWhether a subsequent page is available
next_cursorstring | nullOpaque cursor; null when no next page is available
object_refsobject[]Matched object references
asset_entity_idstring | nullAsset entity identifier
asset_idstring | nullCanonical asset identifier
chain_idstring | nullCanonical chain identifier
contract_addressstring | nullToken contract address associated with chain_id
idstring | nullCanonical object identifier
instrument_idstring | nullInstrument identifier
listing_idstring | nullListing identifier
quote_currencystring | nullQuote currency hint
symbolstring | nullAsset or pool token symbol
typeObjectRefTypeReference type: listing, instrument, asset, asset_entity or chain_contract
venue_idstring | nullVenue identifier
requested_as_ofstring | nullRequested cutoff time
resolved_as_ofstring | nullLatest available observation at or before the cutoff; can be older than the request
unresolved_object_refsobject[]References that could not be resolved
asset_entity_idstring | nullAsset entity identifier
asset_idstring | nullCanonical asset identifier
chain_idstring | nullCanonical chain identifier
contract_addressstring | nullToken contract address associated with chain_id
idstring | nullCanonical object identifier
instrument_idstring | nullInstrument identifier
listing_idstring | nullListing identifier
quote_currencystring | nullQuote currency hint
symbolstring | nullAsset or pool token symbol
typestringReference type: listing, instrument, asset, asset_entity or chain_contract
venue_idstring | nullVenue identifier
request_idstringRequest trace identifier