风险快照

查询不晚于指定时点的最新可用风险观测。

GET/api/v1/risk/snapshot
数据域
风险与合规
解析层级
每个对象和指标在截止时点前的最新可用观测
MCP 工具
risk_compliance_query (task=snapshot)

可查询数据

返回数据
查询不晚于指定时点的最新可用风险观测。
每次返回什么
每个对象和指标在截止时点前的最新可用观测

认证

所有请求需携带 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可选

风险类别筛选

metric_codestringquery示例["open_interest"]可选

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

快照时点

查询不晚于as_of的最新可用观测;实际观测可能早于该时点

as_ofstringquery示例2026-11-04T22:30:00Z可选

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

对象输入模板

以下为输入形状,不代表已有数据覆盖。已覆盖的未平仓量查询可使用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]
history_endstring

已覆盖历史的最后时刻

history_startstring

已覆盖历史的最早时刻

latest_observation_idstring

快照选中的观测记录 ID

latest_value_boolboolean | null

最新布尔值或 null

latest_value_jsonunknown | null

最新结构化值或 null

latest_value_numericnumber | null

不晚于 as_of 的最新数值观测,须同时读取 unit

latest_value_textstring | null

最新文本值或 null

metric_codestring

指标代码,例如 open_interest

requested_as_ofstring

请求的截止时点

resolved_as_ofstring

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

risk_typestring | null

风险类别

source_task_idstring

源任务 ID

target_ref_keystring | null

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

unitstring | null

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

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 权限。