API

SDK

两个官方客户端（Python 和 TypeScript），由 OpenAPI 合约生成：每个接口都是以其路径命名的类型化方法，分页自动跟进，错误是带有稳定 error.code 的类型化异常，重试遵守 Retry-After，WebSocket 数据流会自动重连。

#安装

安装包作为公开仓库 github.com/bytnode/bytnode-SDK 每个版本的附件发布，附源代码和更新日志。它们尚未发布到 PyPI 和 npm：请通过 URL 安装版本附件。

pip install https://github.com/bytnode/bytnode-SDK/releases/download/v0.2.1/bytnode-0.2.1-py3-none-any.whl
# with pandas: pip install "bytnode[pandas] @ https://github.com/bytnode/bytnode-SDK/releases/download/v0.2.1/bytnode-0.2.1-py3-none-any.whl"
export BYTNODE_API_KEY="your_key"

两者都从环境变量 BYTNODE_API_KEY 读取密钥，本文档所有示例都使用这个名称。

#首次调用

from bytnode import Bytnode

client = Bytnode()  # reads BYTNODE_API_KEY

rate = client.funding.rate("BTCUSDT")
print(rate.data.rate_pct, rate.data.time)

# every page of a history, followed for you, into one DataFrame
df = client.klines.iter("BTCUSDT", "1h", since="2026-10-01").to_pandas()

#客户端为你做了什么

  • URL 即方法。/v1/funding/rate/history 对应 client.funding.rate.history(...)；每一行都是使用 API 字段名的类型化模型，日期已转换。
  • 分页。.iter() 逐页跟进 next，直到其为 null，并使用该接口允许的最大页；时间边界可为日期、ISO 字符串或 epoch 毫秒。
  • 错误。每种情况一种异常（请求无效、访问被拒、超出速率……），携带 code、param 和 API 的消息。
  • 重试。429 和 503 等待 Retry-After；502、503、504 和网络错误以随机退避重试；月度配额用尽时立即失败。
  • 数据流。带退避的重连、重新订阅、类型化消息，并根据 seq 检测丢失。

#生成你自己的客户端

合约专为代码生成器设计：每个操作都有可读的 operationId（getFundingRateHistory），每个响应都有命名的模式（FundingRate、Kline、Trade……），封闭取值都是 enum（timeframe、asset、order）。其他语言可从 https://api.bytnode.com/openapi.json 生成：

bash
# TypeScript types
npx openapi-typescript https://api.bytnode.com/openapi.json -o bytnode.d.ts

# Python client
pipx run openapi-python-client generate --url https://api.bytnode.com/openapi.json

#版本

SDK 的版本遵循其自身的更新日志；每个版本由某一版合约生成，API 的每个响应都在 BytNode-Contract-Version 响应头中给出该合约版本。比较两者即可知道自生成客户端以来 API 是否有变化。见版本与迁移。

bytnode 0.2.1 · contract 2.0.0