API 通用约定
适用于所有端点的规则：URL 结构、响应封装、代码标识、单位、时间戳、分页和缓存。
基础 URL 与版本管理
所有端点都位于同一个基础 URL 下，并通过 HTTPS GET 调用。当前路径为 v1 版本。在 v1 内，变更只增不改：可能新增字段和端点，已有字段的名称、类型和含义保持不变。破坏性变更会在新路径下发布，并事先在更新日志中公告。
基础 URL
https://www.coinboss.com/api响应封装
每个 JSON 响应都有顶层的 success 标志。自采数据层的端点（/api/sd 下的路径）还共用以下附加块：
| 字段 | 说明 |
|---|---|
| success | 调用成功时为 true。请务必检查。 |
| schema | 响应结构的标识符和主版本号。 |
| now | 响应组装时的服务器时间，单位为毫秒。 |
| coverage | 哪些交易所已计入，哪些不可用及其原因，哪些因数据过期而被剔除。 |
| method | 响应中每个聚合值背后的公式或规则。 |
| meta | 数据来源、时间戳、时间窗口、质量评级、过期标志、缓存有效期以及回退行为。 |
旧版端点返回 success 和一个 data 字段，可能不包含 coverage、method 或 meta。具体字段见各自的参考页面。
币种、合约与交易所
- coin 参数取大写的基础币种代码，例如 BTC 或 PEPE。
- 1000PEPE、kPEPE 等乘数合约会并入其基础币种，数量已做相应换算。
- 交易所标识符为小写，例如 binance、okx、bybit、hyperliquid。
- 合约代码按交易所的原始命名返回。当某个端点混合返回 USDT 本位、USDC 本位、币本位合约和交割合约时，通过合约类型字段加以区分。
- 与加密资产代码相同的代币化股票和商品永续合约不计入加密货币聚合值。
单位
- 以 _usd 结尾的字段为美元名义价值。
- 资金费率为小数而非百分比：0.0001 表示 0.01%。以 _8h 结尾的字段已归一化到 8 小时周期；原始周期会与原始费率一并返回。
- 以 _pct 结尾的字段为百分比：1.5 表示 1.5%。
- 除非字段说明另有注明，持仓量均为以 USD 计的单边名义价值。公布双边数值的交易所会在 method 块中注明。
- 部分旧版端点以字符串形式返回小数以保留精度。字段表中其类型显示为 string(decimal)。
时间戳
- 除非字段说明另有注明，时间戳均为 UTC 的 Unix 纪元毫秒数。
- observed_at 是所含最新记录的交易所自身时间戳；交易所未提供时为 null。
- received_at 是 CoinBoss 采集器存储该记录的时间。
- fetched_at 是响应组装的时间。对于缓存的响应，它会早于你的调用时间，最多相差一个缓存 TTL。
- 日线序列以 UTC 日界划分。
时间窗口与周期
- 时间窗口参数使用简短的标记：1h、4h、12h、24h，部分端点还支持 3d、7d、30d、90d。每个端点可接受的取值见其参考页面。
- 未知的时间窗口取值要么以 INVALID_PARAM 被拒绝，要么回退到文档记载的默认值，具体行为见各参数的说明。
- 时间序列的分桶粒度取决于时间窗口，在参考页面中注明。
分页与排序
- 列表端点使用 limit 和 offset，或 page 和 size，具体见各端点文档。limit 设有上限；超出上限的值会被压低到上限。
- 响应中如包含 total，它表示分页前的总行数。
- 除非端点文档记载了排序参数，否则排序顺序是固定的。
null、0 与缺失
- null 表示数值未知或不可用。0 表示实测为零。
- 图表必须把 null 显示为缺口。不要插值。
- 字段表中标记为“可能缺失”的字段可能在对象中完全不存在；请按 null 处理。
缓存
- 每个端点都有服务端缓存 TTL，显示在其参考页面上，并通过 meta.cache_ttl_s 返回。X-Cache 响应头给出 HIT、STALE 或 MISS。
- 大多数 GET 端点前面还有一层约十秒的短时边缘缓存。
- 轮询频率高于 TTL 只会得到相同的数据，并白白消耗你的速率限制额度。
WebSocket
WebSocket
wss://www.coinboss.com/ws- 数据流为仅推送的 JSON。每条消息都有 type 字段。
- 断线后请延迟重连，并通过对应的 HTTP 端点回补数据。
机器可读的文档
端点目录、每个端点的参数与字段表、服务状态和质量矩阵均以 JSON 形式在 /api/meta 下提供，整个目录另有一份 OpenAPI 3 文档。