面向代码与 LLM 的 API 约定

#交易对

共跟踪 104 种资产：102 个 USDT 本位永续合约和两种稳定币，后者仅限现货。实时列表由 /v1/symbols 提供，以其为准。

#周期

大多数按区间的接口有七个取值：

1m5m15m30m1h4h1d

K 线（/v1/klines）和技术指标还接受第八个取值——周线（从周一 00:00 UTC 开始），因为它们直接基于 K 线构建：

1m5m15m30m1h4h1d1w

例外情况：期权接口不接受 1m（其快照大约每分钟一次），日内宏观品种不接受 30m，/v1/btc/fees/history 和 /v1/global/history 的可选周期为 1h、4h 或 1d。合约为每个接口给出确切列表（enum），市场数据族目录（/v1/macro/intraday/series）给出每个品种的周期。

不在列表中的值会返回 422 invalid_timeframe 并列出可接受的值，绝不会悄悄回退到其他周期。所有校验错误都是 422，包括 POST /v1/indicators 的正文和期权历史接口。请依据 error.code 进行分支处理：它会指明出错的参数。与 symbol 一样，timeframe 和 order 不区分大小写（1H 即 1h），但 1M 除外：它在别处表示一个月，这里会被拒绝，因为 1m 表示一分钟。

#多交易所聚合

任何响应都不会标明交易所。多交易所指标到达时已经合并：这是平台的约定，也是多个集成变成一个集成的原因。按数量性质分为三种合并规则：

整个 BytNode 中唯一的例外：/v1/spread/interexchange 会标明交易所，因为价差离开交易所就没有意义。其他地方都不存在 exchange 参数：传入会返回 422。

#已收盘 K 线与进行中的周期

所有按窗口切分数据的路由都在每一行带有 is_closed 布尔值，无论你是否请求：K 线、成交 K 线、CVD、买卖比、成交规模、大小额爆仓、订单簿、跨交易所价差——以及所有 /history 路由的每一行（基差、持仓量、资金费率、爆仓、宏观、链上……）。它们的最新值是 timeframe（必填）最近一个已收盘的分桶。基于滚动窗口计算的最新值（累计爆仓、持仓量变化、累计资金费率、期权持仓量变化）始终为最终值，不带 is_closed：time 是窗口终点，window_start_at 与 window_s 给出起点与时长。

默认只提供已收盘的窗口。要查看进行中的周期，请添加 ?live=1：

# The latest CLOSED hourly candle: its value will not move again.
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h"

# The candle IN PROGRESS: provisional, flagged is_closed: false.
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h&live=1"

#单位与刻度

同一个比例绝不会有两种写法。字段的后缀决定其刻度，这一规则适用于所有市场数据族，从市场核心到外围数据：

#时间戳与排序

• 数据的时间戳采用 ISO 8601 格式，UTC 时区，带 Z 后缀，毫秒固定为三位：2026-08-29T11:38:00.000Z。time 始终采用此格式，日度序列也不例外（某一天记为当天 UTC 零点），且不再另设 date 键；单独的日期（2026-08-29）只出现在表示业务日期的键中，例如 filed_date 或 oldest_input_date。time 遵循两条规则之一，每个接口的参考文档会说明是哪一条：对于按 bucket 划分的序列（K 线、CVD、按 bucket 的订单簿、按 8 小时周期的资金费率），它是 bucket 的起点，而不是终点；对于时点值（最新值、滚动窗口、预测、综合指标），它是该值所对应的时刻——滚动窗口的终点、预测所针对的结算时刻、综合指标中最新的输入（同时给出 oldest_input_date）。按 bucket 划分的路由，其最新值是最近一个已收盘的 bucket，与其 /history 的第一行一样以 bucket 的起点为时间：/v1/klines、/v1/cvd、/v1/buy-sell-ratio、/v1/trades/avg-size、/v1/liquidations/big-small-ratio、/v1/orderbook（均必须提供 timeframe）。/v1/options/max-pain/history 的响应包装以到期日（YYYY-MM-DD）回显 expiry，无论你发送的是哪种形式。
• 请求边界（since_ms、until_ms 和 before_ms）以自 Unix 纪元起的毫秒表示。since_ms 与 until_ms 是包含的（精确到毫秒），before_ms 是不包含的。since_ms=0 表示数据的起点。负数边界、since_ms 大于 until_ms（相等时读取该毫秒）或大于等于 before_ms、同时给出 until_ms 与 before_ms、以秒、微秒或纳秒给出的边界，或任何其他早于 2009-01-03（比特币第一个区块）的边界，都会在执行前返回 422。
• 值数组（指标的序列、CVD 的内部序列）按从旧到新排列。
• 历史列表默认按从新到旧返回（最新的一行排在最前面），使用 order=asc 时则按从旧到新返回。
• 一天从 UTC 午夜开始：这是日度序列的对齐点。