风险观测历史

查询已覆盖永续合约的未平仓量历史观测。

GET/api/v1/risk/observations
数据域
风险与合规
解析层级
每条记录对应一个对象、一个指标和一个观测时点
MCP 工具
risk_compliance_query (task=observations)

可查询数据

返回数据
查询已覆盖永续合约的未平仓量历史观测。
每次返回什么
每条记录对应一个对象、一个指标和一个观测时点

认证

所有请求需携带 Authorization: Bearer YOUR_API_KEY 或 X-API-KEY。

需要具备 Risk 权限的 API Key。

请求参数

查询对象

REST传URL编码的JSON数组字符串;MCP直接传JSON数组。标识有效不代表已有数据覆盖

object_refsstringquery示例[{"type":"listing","id":"listing_gate_BTC_USDT_perp"}]必填

URL 编码的 JSON 数组字符串。支持 listing、instrument、asset、asset_entity、chain_contract;链合约必须包含 chain_id 与 contract_address。MCP 直接传数组;输入有效不代表已有覆盖

指标与记录筛选

枚举表示接受的输入;实际覆盖取决于查询对象与指标

risk_typestringquery可选

风险类别筛选。 · market / liquidity / credit / operational / protocol / security / regulatory / macro

metric_codestringquery示例["open_interest"]可选

指标代码,最多 20 项。REST 传 JSON 数组字符串,例如 ["open_interest"];MCP 传数组

record_kindstringquery可选

记录类型:disclosed_fact、derived_metric、alert、incident。REST 多值用 JSON 数组字符串,MCP 用数组

查询时间

start与end须同时填写。as_of为观测截止时点,不等于实际返回的观测时间

startstringquery示例2026-11-04T20:00:00Z可选

RFC3339 UTC 起始时刻,包含边界;必须与 end 成对传入

endstringquery示例2026-11-05T00:00:00Z可选

RFC3339 UTC 结束时刻,包含边界,不早于 start;必须成对传入

as_ofstringquery可选

RFC3339 UTC 截止时刻,默认当前 UTC。观测可能更早,请检查 resolved_as_of

通用筛选与分页

limit为1–200;续页使用metadata.next_cursor,其他筛选条件保持不变

limitintegerquery示例5可选

每页最多返回条数,范围 1–200。 · 默认: 50 · ≥ 1 · ≤ 200

cursorstringquery可选

上一页的 metadata.next_cursor;续查时保持其他筛选参数不变

对象输入模板

以下为输入形状,不代表已有数据覆盖。已覆盖的未平仓量查询可使用listing示例。

标识对象
JSON
[
  {
    "type": "listing",
    "id": "listing_gate_BTC_USDT_perp"
  }
]
链合约对象
JSON
[
  {
    "type": "chain_contract",
    "chain_id": "ethereum",
    "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
]

响应

dataobject | null

本 task 的业务数据;Token Security 为对象,其他查询通过 items 返回

itemsobject[]

该 task 对应的风险记录

items[]array[object]
metric_codestring

指标代码,例如 open_interest

object_resolution_statusstring

对象匹配状态

observation_endstring

观测结束时刻

observation_startstring

观测起始时刻

published_atstring | null

源发布时间,可为 null

record_kindstring

记录类型

risk_observation_idstring

观测记录 ID

risk_typestring | null

风险类别

source_locatorstring

源字段和采样周期

source_record_idstring | null

源记录 ID,可为 null

source_task_idstring

源任务 ID

source_urlstring | null

源证据 URL,可为 null

target_ref_keystring | null

已解析的目标引用键,不要自行用符号拼接

unitstring | null

数值单位;已验证 OI 样例为 usd

value_boolboolean | null

布尔值或 null

value_jsonunknown | null

结构化值或 null

value_numericnumber | null

数值观测,须同时读取 unit

value_textstring | null

文本值或 null

missing_metricsstring[]

未覆盖的请求指标

data_statusDataStatus

ok / partial / no_data / upstream_error / not_ready;HTTP 200 不代表数据覆盖完整

empty_reasonstring | null

成功时为 null;空结果读取 not_covered 或 object_unresolved 等原因

errorobject | null

成功时为 null;参数或上游错误为结构化对象

codestring

错误代码

detailsobject

错误详情

messagestring

错误说明

retryableboolean

是否可以重试

generated_atstring

响应生成时刻,不是数据观测时刻

metadataobject

对象解析、分页和实际观测时点

has_moreboolean

是否仍有下一页

next_cursorstring | null

下一页游标,无下一页时为 null

object_refsobject[]

已匹配对象引用

object_refs[]array[object]
asset_entity_idstring | null

资产实体 ID

asset_idstring | null

资产标识,标识股票、加密资产等资产对象

chain_idstring | null

链标识

contract_addressstring | null

该链上的代币合约地址

idstring | null

对象标识,标识 type 指定的具体对象

instrument_idstring | null

交易工具标识,标识股票、现货交易对或合约等具体交易产品

listing_idstring | null

交易场所挂牌标识,标识某个交易品种在特定交易场所的挂牌记录

quote_currencystring | null

报价币种线索

symbolstring | null

资产符号线索

对象类型:listing、instrument、asset、asset_entity、chain_contract

venue_idstring | null

交易场所标识,标识交易所或交易平台

requested_as_ofstring | null

请求的截止时点

resolved_as_ofstring | null

不晚于截止时点的最新可用观测时间,可能早于请求时间

unresolved_object_refsobject[]

未解析的对象引用

unresolved_object_refs[]array[object]
asset_entity_idstring | null

资产实体 ID

asset_idstring | null

资产标识,标识股票、加密资产等资产对象

chain_idstring | null

链标识

contract_addressstring | null

该链上的代币合约地址

idstring | null

对象标识,标识 type 指定的具体对象

instrument_idstring | null

交易工具标识,标识股票、现货交易对或合约等具体交易产品

listing_idstring | null

交易场所挂牌标识,标识某个交易品种在特定交易场所的挂牌记录

quote_currencystring | null

报价币种线索

symbolstring | null

资产符号线索

typestring

对象类型:listing、instrument、asset、asset_entity、chain_contract

venue_idstring | null

交易场所标识,标识交易所或交易平台

request_idstring

请求追踪标识

错误与降级

200
返回所查数据。
200
部分覆盖;缺失指标见 data.missing_metrics,其他缺失查看返回字段。
200
对象已解析,但没有覆盖的数据;不代表无风险。
200
对象未解析;核对对象 ID 与 metadata.unresolved_object_refs。
400
参数格式、成对时间或范围不合法;limit 必须在 1–200。
401
检查 API Key。
403
检查 Key 的 Risk 权限。