FTLib
版本 v1.4 最后更新:2026-11-13

REST 接口规范|请求、响应、分页与单位 - FTLib

REST 接口用于历史查询、批量快照与元数据获取。所有接口使用 HTTPS、JSON 与统一响应封装,路径中的 /v1 表示主版本。

基础地址与版本

服务地址
环境地址
生产 RESThttps://api.ftlib.com/v1
生产推送wss://push.ftlib.com/v1/stream
文档https://ftlib.com/doc/

向后兼容的字段新增不会改变主版本;破坏性变更会通过新版本路径发布,并至少提前一个版本周期在 更新日志 中说明。

请求约定

  • 方法以 GET 为主,查询参数使用 URL 编码。
  • 请求头必须包含 Authorization: Bearer <API_KEY>。
  • 建议携带 Accept: application/json 与稳定的 User-Agent。
  • 证券代码使用带交易所后缀的完整格式。
  • 批量查询使用英文逗号分隔,单次数量以接口说明为准。
bash
curl -H "Authorization: Bearer $FTLIB_API_KEY" \
  -H "Accept: application/json" \
  "https://api.ftlib.com/v1/kline?symbol=600519.SH&period=1d&start=2026-01-01&end=2026-11-13&adjust=forward"

响应结构

所有响应使用同一层封装。code 为业务码,0 表示成功;message 为可读说明;request_id 用于排查。

json
{
  "code": 0,
  "message": "ok",
  "request_id": "req_5d0c8f11",
  "data": {
    "symbol": "600519.SH",
    "period": "1d",
    "bars": []
  }
}

错误响应仍为 JSON,但 data 可能为 null。客户端应先判断 code,再判断 data 是否存在,不要仅依赖 HTTP 状态码。

分页与批量

历史逐笔等大结果集使用游标分页。响应返回 next_seq 与 has_more,客户端用 next_seq 作为下一页起点,直到 has_more 为 false。

bash
curl -H "Authorization: Bearer $FTLIB_API_KEY" \
  "https://api.ftlib.com/v1/l2/trades?symbol=600519.SH&date=2026-11-13&start_seq=0&limit=1000"
不要用页码分页 逐笔数据按序列号增长,页码分页会因新增数据导致重复或遗漏。请使用 start_seq 与 next_seq。

时间与单位

通用约定
项目约定
时间戳毫秒级 epoch,时区 Asia/Shanghai
日期YYYY-MM-DD,交易日语义
价格元;指数为点位
成交量股票为股,可转债为张,基金为份
成交额元
比率百分数,例如 12.40 表示 12.40%
复权none、forward、backward

传输与压缩

  • 支持 gzip 压缩,客户端可发送 Accept-Encoding: gzip。
  • 连接复用与 HTTP/2 可降低批量查询延迟。
  • 历史数据变化不频繁,可在客户端缓存并按交易日失效。
  • 实时性要求高的数据使用推送,不要高频轮询 REST。
  • 遵守 限流规则,对 429 使用指数退避。