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

快速开始|十分钟完成首次 API 调用 - FTLib

本指南帮助你用最短路径完成首次调用:确认密钥、发出一个 REST 请求、理解响应结构,再建立一条推送连接。示例使用命令行工具 curl,你可以用任意 HTTP 客户端复现。

准备工作

接入前需要准备三件事:有效的 API Key、可访问外网的开发环境,以及明确的证券代码。证券代码采用 代码.交易所 格式,例如 600519.SH、000001.SZ。

接入前检查项
项目说明
API Key通过接入咨询获取,按数据域与配额授权
网络可访问 api.ftlib.com 与 push.ftlib.com
时区所有时间戳为毫秒级 epoch,展示时使用 Asia/Shanghai
代码优先使用带交易所后缀的完整代码
密钥不要写入代码仓库 请通过环境变量或密钥管理服务注入 API Key,不要提交到 Git 仓库,也不要在前端代码中暴露。

第一个请求

将密钥放入环境变量,然后请求一只证券的快照。响应会返回最新价、成交量与五档盘口。

bash
export FTLIB_API_KEY="your_api_key"

curl -H "Authorization: Bearer $FTLIB_API_KEY" \
  "https://api.ftlib.com/v1/quote/snapshot?symbols=600519.SH"

如果密钥有效且代码格式正确,HTTP 状态码为 200,响应体中的 code 为 0。若返回 401 或 403,请检查密钥与授权范围;若返回 400,请检查证券代码格式。

解析响应

所有 REST 接口使用统一响应封装。data 为业务数据,request_id 用于排查问题。

json
{
  "code": 0,
  "message": "ok",
  "request_id": "req_7f3c9a21",
  "data": [
    {
      "symbol": "600519.SH",
      "name": "贵州茅台",
      "ts": 1794794400000,
      "last": 1688.00,
      "volume": 2154300,
      "amount": 3635123400.00,
      "bids": [{ "price": 1687.90, "volume": 300 }],
      "asks": [{ "price": 1688.00, "volume": 200 }]
    }
  ]
}

建议在客户端统一处理三件事:检查 code 是否为 0、记录 request_id、对缺失字段做显式判断。不要假设所有品种都返回相同字段。

接入推送

实时行情通过 WebSocket 推送。连接建立后先发送鉴权消息,再发送订阅消息。seq 表示期望的续传位置,首次连接可设为 0。

json
{
  "op": "subscribe",
  "channel": "quote.l1",
  "symbols": ["600519.SH", "000001.SZ"],
  "seq": 0
}

客户端应处理心跳、序列号缺口与断线重连。生产环境建议为每条消息记录 seq,并在重连时携带最后处理的序列号。

下一步