REST API

快照

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

对 AI 智能体而言，快照只需一次 MCP 调用：MCP 服务器的 get_pair_data 工具在一次请求中返回一个交易对快照字段的当前值，只计一次配额；比较最多十个交易对时，每个交易对一次请求。

#原理

GET/v1/snapshotdata_type · snapshot完整参考

请求的每个参数是一个字段名，其值是请求的深度（视字段而定，可以是行数、分钟数或秒数）。只有当前值的字段用 =1 请求（或 =true，含义相同）。symbol 为必填。快照从 Traders 方案起提供。

curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/snapshot?symbol=BTCUSDT\
&funding_rate=1\
&basis=1\
&fear_greed=1\
&cvd@1h=2"

未请求任何字段时，响应返回空的 data 以及你的方案所包含内容的目录：available_fields（不带周期的字段）、available_multi_tf_fields（以 name@tf 形式请求）、timeframes 和 max_depth（每个字段的上限）。客户端无需阅读本页即可据此构建请求。

#52 个字段

三十七个字段以裸名称请求（发现接口 /v1/snapshot?symbol=BTCUSDT 会列出它们）。每个字段的名称与内容都与其路由相同：路由返回对象的字段以该对象返回，用 =1（或 =true）请求——更大的深度会返回指向其 /history 路由的 422；事件类字段（逐笔成交、爆仓事件、秒级 K 线）是列表，上限见深度列。

价格与成交量

字段	类型	说明
`trades_kline_futures_seconds`	1000 seconds	/v1/trades-kline/futures/seconds 的数据行：按秒聚合的永续合约成交——成交量、笔数、买入和卖出量。
`trades_spot`	10,000 笔成交	逐笔现货成交，即 /v1/trades/spot 的数据行。
`trades_futures`	10,000 笔成交	逐笔合约成交，即 /v1/trades/futures 的数据行。
`price_change`	当前值	八个周期的涨跌幅（%），按需计算。

衍生品与持仓

字段	类型	说明
`oi_change`	当前值	持仓量变化及其百分比。
`funding_next`	当前值	下一期预估资金费率，折算为 8 小时等效。
`funding_rate`	当前值	最近一次结算费率，按持仓量加权。
`funding_cumulative`	当前值	24 小时累计，即最近三个窗口之和。
`liquidations_events`	10,000 个事件	最近 N 笔爆仓，即 /v1/liquidations/events 的行。数量由套餐决定：超出则 403 history_depth。
`liquidations_cumulative`	当前值	按 5 分钟窗口累计的强平。
`basis`	当前值	期货相对现货的价差，按持仓量加权。

全市场与附属数据

字段	类型	说明
`tokenomics`	当前值	该交易对资产的供应量、市值和 FDV。
`global`	当前值	总市值、成交量、BTC 和 ETH 占比。
`fear_greed`	当前值	0-100 情绪指数及其分类。
`options_summary`	当前值	由交易对推断的资产的期权摘要（仅 BTC 或 ETH）。
`macro_series, macro_correlations, macro_net_liquidity, macro_momentum, macro_risk`	当前值	宏观序列及四个衍生指标。
`btc_network, btc_mempool, btc_fees, btc_mining`	当前值	比特币网络状态。
`btc_mvrv, btc_nvt, btc_active_addresses, btc_revenue_per_difficulty`	当前值	比特币链上估值，日度数据。
`eth_supply, eth_gas, eth_gas_momentum, eth_staking, eth_deflation, eth_defi, eth_squeeze, eth_price_btc`	当前值	以太坊的八个市场数据族。
`fear_greed_cmc, altcoin_season, cmc20, cmc100`	当前值	CMC 情绪指标：CMC 恐惧与贪婪指数、山寨季指数，以及 CMC20 和 CMC100 指数。

#多周期字段

有十一个字段按时间周期存在。请求时必须带 @tf 后缀，必填，键名原样出现在 data 中（data["cvd@1h"]）。klines 还支持 1w（见目录中的 timeframes_by_field）。带 @tf 的字段始终是列表，即使深度为 1；不带周期的字段是其路由的对象（仅深度 1），事件类字段（成交、强平、秒级数据）除外，它们是列表。

1m5m15m30m1h4h1d

字段	类型	说明
`klines@tf`	1000 根 K 线	/v1/klines 的 K 线，1m 至 1w（klines@1w 也可），字段与路由相同：time、open、high、low、close、volume（现货 + 永续合约）及其买入和卖出部分、各市场的同类字段（volume_spot、volume_futures…）、is_*_estimated 标志和 is_closed。成交量以基础资产为单位。
`oi@tf`	1000 个窗口	每个已收盘 bucket 的总持仓量，即 /v1/oi/history 的行。oi@1m=1 给出最近一分钟。
`cvd@tf`	200 个窗口	累计成交量差（CVD）及其内部序列。
`buy_sell_ratio@tf`	1000 个窗口	每个已收盘分桶的买卖比（与 cvd 相同的分桶）。
`trades_avg_size@tf`	1000 个窗口	每个已收盘分桶的平均成交规模，按笔数加权。
`liquidations_big_small_ratio@tf`	1000 个窗口	每个已收盘分桶的大额强平与小额强平对比。
`orderbook@tf`	1000 个窗口	每个 bucket 结束时按价格区间统计的订单簿，现货与永续合约求和：即 /v1/orderbook/history 的数据行。
`spread_interexchange@tf`	50 个窗口	各交易所的溢价。唯一列出交易所名称的字段。
`trades_kline@tf`	1440 根 K 线	成交 K 线（/v1/trades-kline），现货与合约求和。
`trades_kline_spot@tf`	1440 根 K 线	成交 K 线，仅现货（/v1/trades-kline/spot）。
`trades_kline_futures@tf`	1440 根 K 线	成交 K 线，仅合约（/v1/trades-kline/futures）。

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

#附加键

is_partial

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

unavailable

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

响应

{
  "status": "ok",
  "server_time": "2026-10-13T02:18:41.507Z",
  "data_type": "snapshot",
  "symbol": "USDCUSDT",
  "is_partial": false,
  "data": { "funding_rate": null, "options_summary": null, "basis": null },
  "unavailable": {
    "funding_rate": "not_applicable",
    "options_summary": "not_applicable",
    "basis": "not_applicable"
  }
}

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

out_of_plan_fields

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

响应

{
  "status": "ok",
  "server_time": "2026-10-13T02:30:56.839Z",
  "data_type": "snapshot",
  "symbol": "BTCUSDT",
  "is_partial": false,
  "data": {
    "funding_rate": {"time": "2026-10-12T16:00:00.000Z", "period_end_at": "2026-10-13T00:00:00.000Z", "settled_at": "2026-10-13T00:00:00.005Z", "rate_pct": 0.0038949161538, "apr_pct": 4.26493318841, "is_closed": true},
    "basis": {"time": "2026-10-13T02:30:14.102Z", "basis_value": -33.9427339947, "basis_pct": -0.0410036905061, "futures_price": 82743.8733191, "spot_price": 82777.8160531}
  },
  "out_of_plan_fields": ["fear_greed", "btc_mvrv"]
}

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

#错误

情形	状态码
缺少 `symbol`	`422`
未知或已停用的交易对	`422`，并附上可用交易对列表
多周期字段未加后缀，或反之	`422`
未知周期	`422`
深度不是整数或小于 1	`422` `invalid_depth`
深度超过该字段上限	`422` `depth_too_large`
深度超出套餐的历史窗口	`403`，带 `X-Deny-Reason: history_depth`，并在 `error.message` 中给出最大 `limit`
未知的键，或重复的键	`422`，并建议最接近的字段
超出套餐的市场数据族字段	不是错误：该字段被移除并列在 `out_of_plan_fields` 中

套餐的历史窗口对带日期的字段与 REST 接口同样适用：klines@1h=1000 请求一千根 1 小时 K 线，Traders（1h 为一周）会以明确的 403 history_depth 拒绝，而不是以一千根的名义返回 168 根。

403

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "history_depth",
    "message": "History depth beyond your plan: 1000 hour(s) requested on 1h, your plan allows 7 day(s) (i.e. at most limit=168 on this timeframe, and no since_ms/until_ms bound beyond that window).",
    "param": "limit",
    "details": {
      "window_s": 604800,
      "earliest_ms": 1791273600000,
      "max_limit": 168,
      "timeframe": "1h"
    }
  }
}