版本 v1.4
最后更新:2026-11-13
REST 接口规范|请求、响应、分页与单位 - FTLib
REST 接口用于历史查询、批量快照与元数据获取。所有接口使用 HTTPS、JSON 与统一响应封装,路径中的 /v1 表示主版本。
基础地址与版本
| 环境 | 地址 |
|---|---|
| 生产 REST | https://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 使用指数退避。