REST API

快照

一个按需组合的接口：你指定字段，它在一次请求中全部返回。它是仪表盘或为模型供数的理想入口：每个周期一次调用，而不是十次。

#原理

GET/v1/snapshotdata_type · snapshot

请求的每个参数是一个字段名，其值是请求的深度（视字段而定，可以是行数、分钟数或秒数）。只有当前值的字段用 =1 请求。symbol 为必填。

curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/snapshot?symbol=BTCUSDT\
&klines_1h=24\
&funding_rate_8h=1\
&oi_delta=60\
&liq_cumulative=120\
&cvd@1h=24\
&options=1\
&fear_greed=1"

未请求任何字段时，响应返回空的 data 和 available_fields 列表，便于从客户端发现字段目录。

#61 个字段

五十三个字段直接用名称请求。深度一列给出单位和上限；未注明上限的字段只有当前值，用 =1 请求。

价格与成交量

字段	类型	说明
`klines_1m … klines_1w`	1000 candles	八个周期。每行：时间戳、开盘、最高、最低、收盘、成交量、taker_buy、taker_sell。
`taker_combined`	1440 minutes	每分钟的买入和卖出成交量，汇总所有交易所。
`trades_raw`	3600 seconds	每秒成交聚合：总成交量、笔数、taker 分布。
`spot_ticks`	10,000 rows	逐笔现货成交。
`futures_ticks`	10,000 rows	逐笔期货成交。
`price_change`	current value	八个周期的涨跌幅（%），按需计算。

衍生品与持仓

字段	类型	说明
`oi_snapshots`	current value	总持仓量，汇总各交易所。
`oi_history`	1440 minutes	总持仓量历史，按分钟。
`oi_delta`	60 minutes	持仓量变化及其百分比。
`funding_next`	current value	下一期预估资金费率，折算为 8 小时等效。
`funding_rate_8h`	current value	最近一次结算费率，按持仓量加权。
`funding_cumulative`	current value	24 小时累计，即最近三个窗口之和。
`liquidations`	1440 minutes	搜索窗口内的逐笔事件。
`liq_cumulative`	1440 minutes	按 5 分钟窗口累计的强平。
`liq_ratio`	current value	大额强平与小额强平对比。
`basis`	60 minutes	期货相对现货的价差，按持仓量加权。

订单簿与微观结构

字段	类型	说明
`orderbook`	current value	买卖盘深度汇总及失衡度。
`vwap`	60 minutes	日内 VWAP，自 UTC 午夜起累计。
`buysell_ratio`	current value	买卖比，5 分钟窗口。
`trade_size`	current value	平均成交规模，按笔数加权。
`heatmap`	current value	价格上方和下方的强平聚集区。

全市场与附属数据

字段	类型	说明
`tokenomics`	current value	该交易对资产的供应量、市值和 FDV。
`global_market`	current value	总市值、成交量、BTC 和 ETH 占比。
`fear_greed`	current value	0-100 情绪指数及其分类。
`options`	current value	由交易对推断的资产的期权摘要（仅 BTC 或 ETH）。
`macro, macro_correlations, net_liquidity, macro_momentum, macro_risk`	current value	宏观序列及四个衍生指标。
`btc_network, btc_mempool, btc_fees, btc_mining`	current value	比特币网络状态。
`onchain_mvrv, onchain_nvt, onchain_active_addresses, onchain_miner_stress`	current value	比特币链上估值，日度数据。
`eth_supply, eth_gas, eth_gas_momentum, eth_staking, eth_deflation, eth_defi, eth_squeeze, eth_ratio`	current value	以太坊的八个数据族。

#多周期字段

有八个字段按周期提供。请求时需加 @tf 后缀（必填），键会原样出现在 data 中（data["cvd@1h"]）。

1m5m15m30m1h4h1d

字段	类型	说明
`cvd@tf`	200 windows	累计成交量差（CVD）及其内部序列。
`orderbook_aggregated@tf`	1000 windows	聚合订单簿：失衡度的均值、最小值、最大值和标准差。
`vwap_window@tf`	1000 windows	窗口 VWAP，不同于日内 VWAP。
`spread_interexchange@tf`	50 windows	各交易所的溢价。唯一列出交易所名称的字段。
`trade@tf`	1440 candles	成交 K 线，现货与期货合计。
`trade_spot@tf`	1440 candles	成交 K 线，仅现货。
`trade_future@tf`	1440 candles	成交 K 线，仅期货。
`ls_ratio@tf`	500 windows	综合多空比。没有 1m。

请求多周期字段而不加后缀会返回 422，反之亦然：给单一形式字段加上 @1h 后缀也会被拒绝。

#附加键

partial

始终存在。一旦响应的某部分无法构建，它就变为 true：相关字段的值为 {"error": "..."}，其他字段正常返回。局部故障只影响局部：不会因为七个数据族中有一个不可用而得到空响应。

unavailable

仅当至少一个请求的字段为空时出现。它说明原因，这是单独一个 null 做不到的。

响应

{
  "data": { "funding_rate_8h": null, "options": null, "heatmap": [] },
  "unavailable": {
    "funding_rate_8h": "not_applicable",
    "options": "not_applicable",
    "heatmap": "no_data"
  }
}

三个值，按优先级排序：not_applicable（该资产不存在此现象）、no_api_key（上游数据源未接入，从未采集过）、no_data（窗口内确实没有数据）。只有第三种可以用于得出市场结论。

coverage

有多少交易所参与了该数值，以及缺失的影响。实际数量逐行放在 venue_count 中；coverage 携带所有行共有的信息。取值详情见约定页面。

out_of_plan_fields

快照返回其他数据族的内容，并按你的套餐过滤：所属数据族不在套餐内的字段会从 data 中移除，其名称列在 out_of_plan_fields 中（仅在此情况下出现）。其他字段正常返回；请求不会被拒绝。

响应

{
  "status": "ok",
  "data_type": "snapshot",
  "partial": false,
  "data": {
    "funding_rate_8h": { "bucket": "...", "rate": 0.000082, "apr": 0.0898 },
    "basis": [ { "timestamp": "...", "basis_pct": 0.059 } ]
  },
  "out_of_plan_fields": ["fear_greed", "onchain_mvrv"]
}

未请求任何字段时，available_fields 只列出你套餐内的字段。所有字段都超出套餐的快照会返回空的 data，并在 out_of_plan_fields 中给出完整列表，绝不会返回没有说明的空结果。数据族与套餐的对应关系见套餐页面；快照本身从 Traders 起开放。

#错误

情形	状态码
缺少 `symbol`	`422`
未知或已停用的交易对	`400`，并附上可用交易对列表
多周期字段未加后缀，或反之	`422`
未知周期	`422`
深度不是整数或小于 1	`400`
深度超过该字段上限	单一形式字段返回 `400`，多周期字段返回 `422`
深度超出套餐的历史窗口	`403`，并在 `detail` 中给出最大 `limit`
超出套餐的数据族字段	不是错误：该字段被移除并列在 `out_of_plan_fields` 中

套餐的历史窗口对带日期的字段与 REST 接口同样适用：klines_1m=1000 请求十六小时的 1 分钟 K 线，Free（1m 仅一小时）会以明确的 403 拒绝，而不是以一千根的名义返回六十根。

403

{
  "detail": "Profondeur d'historique hors offre : 16 heure(s) demandes en 1m, votre offre en autorise 1 heure(s) (soit limit=60 au maximum sur ce timeframe, et aucune borne since_ms/until_ms au-dela de cette fenetre)."
}