FastTick 行情分发接口协议规范 (API Specification)

本文档面向接入 FastTick 行情分发系统的下游商业客户、量化交易员及技术团队。协议版本 v1。

1. 通用约定

1.1 每次响应都携带的字段

{
  "code": 0,
  "msg": "success",
  "data": {},
  "request_id": "6f1c2a9e-7d4b-4a1e-9c2f-1b3d5e7a9c01",
  "timestamp": 1700000000123
}

request_id 用于排查问题，客户反馈时请提供。

1.2 限流响应头

所有 REST 响应都带有：

限流按订阅统计（同一订阅下的所有 Token 共享套餐配额）。

2. 认证鉴权：Token 接入

2.1 凭证体系

购买套餐后，客户只拿到一个 Token，直接在请求里使用，没有换取步骤：

为什么 Token 不设过期时间：行情接入是长期运行的服务端程序，让客户每隔几小时刷新一次凭证，会显著增加对接成本，而且客户往往把凭证写死在配置里，定时刷新反而更容易写错。因此 FastTick 采用「凭证长期有效 + 服务端实时控制」的模式：能不能用，不取决于 Token 自身的有效期，而取决于它所属订阅的当前状态。

代价是 Token 一旦泄露就是长期有效，所以必须配合 2.6 节的重置、白名单与告警机制。

2.2 获取 Token

1. 支付成功、订阅开通后，系统自动生成一个名为 default 的 Token，并邮件通知客户到控制台查看。
2. 客户在控制台「接入凭证」页面可以随时查看完整 Token（需要两步验证），支持一键复制。
3. 客户也可以为不同用途创建多个 Token 并分别命名。

Token 属于订阅，订阅终止后全部 Token 同时失效。

2.3 使用 Token 访问 REST

GET /api/v1/ticker?symbol=BTC/USDT HTTP/1.1
Host: api.example.com
Authorization: Bearer ft_live_9f2c1d7a4b8e5061c3d2e7f8a9b0c1d2

也可以是专门的请求头（二选一）：

X-API-Token: ft_live_9f2c1d7a4b8e5061c3d2e7f8a9b0c1d2

• 只接受请求头传递。不支持 ?token=、?apikey= 等 URL 参数，出现即返回 401，避免凭证进入网关日志和浏览器历史。
• Token 错误时统一返回 token_invalid，不区分"不存在"与"已删除"，避免被用于探测。

权限范围（scopes）分为两条独立产品线，令牌上可以同时签入，但每个接口只认自己那一个：

资讯类 scope 与行情类 scope 互不影响：

• 只买行情的套餐只能签 ticker / kline / depth，打资讯接口返回 403 scope_not_allowed；
• 只买资讯的套餐只能签 news / calendar，打行情接口同样 403；
• 同一订阅可签发多个 Token（如「生产行情」「内部资讯」分开），各自最小授权。

两层判定：接口权限 = Token 上的 scope 且 订阅快照里的套餐开关。套餐降级或后台关闭资讯后，旧 Token 上残留的 news/calendar 立即失效（403 scope_not_allowed），无需客户重置 Token。

2.4 WebSocket 接入

连接 wss://api.example.com/ws/v1 后，在 5 秒内发送鉴权帧，否则服务端以 4001 关闭：

{
  "action": "auth",
  "token": "ft_live_9f2c1d7a4b8e5061c3d2e7f8a9b0c1d2",
  "format": "json"
}

服务端确认：

{
  "event": "auth",
  "code": 0,
  "msg": "Authenticated",
  "subscription_id": 88,
  "plan": "forex_pro",
  "scopes": ["ticker", "kline", "depth"],
  "subscription_expire_time": 1798761600000,
  "seq_epoch": 1792800000000
}

subscription_expire_time 是订阅到期时间，仅供客户端展示和提前提醒，服务端不依赖客户端遵守它。

seq_epoch 表示本条连接上的序列号从该值开始计数，客户端可用它识别连接是否重建。

2.5 到期与停用控制

这是「Token 不设过期」能够成立的关键。控制分四层，任何一层生效都能停止服务。

第一层：每个请求都校验订阅状态

引擎不在每个请求上查库，而是在本地内存中维护一份凭证状态表：

token_hash → { subscription_id, status, expire_time, grace_endtime, scopes, ip_whitelist, version }

校验链（全部在内存中完成，无网络往返）：

1. Token 格式合法 → 否则 401 token_invalid
2. 哈希命中状态表 → 未命中则 401 token_invalid（可能是已删除或从未存在）
3. 状态为 normal → 为 disabled 则 401 token_disabled
4. now < expire_time + grace → 否则 402 subscription_expired
5. 订阅状态属于 trial / active / grace → 否则 402 subscription_expired
6. scopes 包含本次所需权限 → 否则 403 scope_not_allowed
7. IP 在白名单内 → 否则 403 ip_not_allowed

第二层：订阅到期时主动断开已建立的连接

引擎加载凭证时已经知道 expire_time，因此为每个订阅在本地注册一个到期定时器：

• 到达 expire_time：进入宽限期（默认 24 小时），期间正常服务，但推送帧中带 expiring: true，提示客户端续费。
• 到达 grace_endtime：立即执行
  • 该订阅下所有 WebSocket 连接以 4004 关闭
  • 该订阅下所有 Token 从状态表中标记为过期，之后任何 REST 请求返回 402
• 这一步不依赖 phpback 通知，也不依赖数据库可用性，即使业务库暂时不可用，到期也会在秒级内准时生效。

第三层：后台操作即时生效（事件驱动）

客户续费、升级、退款、被后台停用时，phpback 在事务提交后向 Redis 发布变更：

{"type": "subscription", "subscription_id": 88, "op": "upsert", "version": 1793059200123}

引擎收到后立即更新状态表。需要立刻断开的场景（停用、退款终止、重置 Token）会附带 op: "revoke"，引擎在收到后立即断开对应连接，延迟通常在 100 毫秒以内。

第四层：兜底轮询

Redis Pub/Sub 不保证送达（节点重启、网络抖动期间的消息会丢），因此引擎另外每 30 秒按 updatetime 增量拉取一次变更，并用全局 config_version 比对。任何一层遗漏都会在 30 秒内被纠正。

整体时效

边界情况

2.6 重置、吊销与安全

因为 Token 长期有效，泄露后的处置必须简单可靠：

其他安全措施

• IP 白名单：Token 可绑定单个 IP 或 CIDR 网段，非白名单来源直接 403。
• 域名白名单（可选）：如果客户要在浏览器里直连 WebSocket，可绑定来源域名，服务端校验 Origin 头，降低 Token 被复制到其他网站的风险。但仍然强烈建议 Token 只放服务端，因为长期 Token 放进前端等于对所有人公开。
• 异常使用告警：同一 Token 在短时间内出现多个地理位置、或调用量突增时，控制台与后台都会显示风险提示，并可一键停用。
• 查看完整 Token 需要两步验证，避免后台账号被盗后直接获取凭证。
• 日志脱敏：FastTick 自己的访问日志只记录 Token 前 12 位（如 ft_live_9f2c…），不记录完整值。

Token 长度固定为 40 字符：ft_live_（8 字符）+ 16 字节随机值的 32 位小写十六进制。其他文档中的示例若与此不一致，以本节为准。

泄露后的标准处置（文档中会提供给客户的应急步骤）：

1. 控制台重置 Token，旧 Token 立即失效；
2. 检查用量与在线连接记录，确认是否有异常调用；
3. 绑定 IP 白名单，缩小可用范围；
4. 如产生超额调用，按服务协议处理。

2.7 鉴权失败

{
  "code": 401,
  "msg": "Unauthorized: token invalid",
  "reason": "token_invalid",
  "data": null,
  "request_id": "…",
  "timestamp": 1700000000000
}

注意 subscription_expired 与凭证无关：客户续费后，原来的 Token 立刻恢复可用，不需要重新生成，这是长期 Token 方案的重要体验优势。

3. HTTP REST API

3.1 单个品种实时快照

GET /api/v1/ticker?symbol=BTC/USDT

{
  "code": 0,
  "msg": "success",
  "data": {
    "symbol": "BTC/USDT",
    "category": "crypto",
    "digits": 2,
    "bid": "67520.50",
    "ask": "67521.10",
    "last": "67520.80",
    "bid_size": "2.40",
    "ask_size": "1.85",
    "volume_24h": "12845.62",
    "high_24h": "68100.00",
    "low_24h": "66400.00",
    "change_24h": "+1.65",
    "source": "binance",
    "ts": 1700000000123,
    "server_ts": 1700000000125,
    "stale": false,
    "seq": 918273645
  },
  "request_id": "…",
  "timestamp": 1700000000126
}

3.2 批量快照

GET /api/v1/tickers?symbols=BTC/USDT,ETH/USDT,EUR/USD&compact=1

• symbols 省略时返回套餐权限内的全部品种。
• compact=1 时只返回 symbol、bid、ask、last、ts、stale、seq，用于行情列表页。
• 响应为 data: [ … ] 数组，单个品种的字段与 3.1 相同。
• 单次请求最多 200 个品种，超出返回 400。

3.3 L2 深度

GET /api/v1/depth?symbol=BTC/USDT&limit=10

{
  "code": 0,
  "msg": "success",
  "data": {
    "symbol": "BTC/USDT",
    "bids": [["67520.50", "1.520"], ["67519.80", "2.100"]],
    "asks": [["67521.10", "0.950"], ["67522.00", "3.240"]],
    "ts": 1700000000123,
    "stale": false,
    "last_update_id": 88213
  }
}

• limit 默认 10，最大 50，同时受套餐 depth_levels 限制（套餐无深度权益时返回 403）。
• 数组元素为 [价格, 数量]，均为字符串。
• 深度数据依赖上游提供 L2，并非所有品种都有；无深度数据的品种返回 404。

3.4 K 线（历史与实时）

GET /api/v1/klines?symbol=BTC/USDT&interval=1m&limit=100&end_time=1700000000000

{
  "code": 0,
  "msg": "success",
  "data": {
    "symbol": "BTC/USDT",
    "interval": "1m",
    "digits": 2,
    "bars": [
      {
        "open_time": 1700000000,
        "open": "67500.00",
        "high": "67530.00",
        "low": "67490.00",
        "close": "67520.50",
        "volume": "12.8400",
        "tick_count": 214,
        "closed": true
      }
    ]
  },
  "request_id": "…",
  "timestamp": 1700000001000
}

• open_time 为 UTC 秒，即该 K 线的开盘时间；4h、1d 按品种所属市场的交易日起点对齐，因此不一定是 14400 或 86400 的整数倍。
• K 线按 open_time 升序返回。
• closed 为 false 表示这是当前尚未收盘的 K 线（从内存实时合成，不经数据库）。
• 历史深度受套餐 history_days 限制，超出范围返回 400 并在 msg 中说明可查询的最早时间。
• 周期 4h 和 1d 在部分套餐中不可用，见定价页；套餐的 allowed_intervals 为空表示全部周期可用。

3.5 品种列表

GET /api/v1/symbols?category=forex

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "symbol": "EUR/USD",
      "category": "forex",
      "display_name": "Euro / US Dollar",
      "digits": 5,
      "volume_digits": 0,
      "intervals": ["1m", "5m", "15m", "30m", "1h", "4h", "1d"],
      "has_depth": true
    }
  ]
}

只返回当前套餐权限内的品种。此接口的 QPS 与其他接口共享套餐配额。

3.6 资讯：7x24 快讯

GET /api/v1/news/flash?lang=zh-cn&limit=20&before_time=1700000000

需要 scope news。lang 只支持 zh-cn / en；limit 上限 200，同时受套餐 news_max_limit 收紧；before_time 用于翻页。

{
  "code": 0,
  "msg": "success",
  "data": {
    "lang": "zh-cn",
    "items": [
      {"id": 1002433844, "time": 1793288641, "title": "…", "content": "…", "important": false, "tags": []}
    ],
    "updated_at": 1793288641,
    "stale": false,
    "count": 20
  },
  "request_id": "…",
  "timestamp": 1793288641000
}

stale=true 表示上游超过 5 分钟没有新内容，前端应提示"延迟"，不要当成实时流。

3.7 资讯：财经日历

GET /api/v1/news/calendar?lang=zh-cn&start=2026-10-01&end=2026-10-31&tabs=4

需要 scope calendar。start / end 为 YYYY-MM-DD，区间不超过 31 天；tabs 只支持 2,3,4,5,6。

{
  "code": 0,
  "msg": "success",
  "data": {
    "lang": "zh-cn",
    "days": [
      {"date": "2026-10-29", "items": [{"id": "…", "time": "20:30", "title": "…", "importance": 3, "actual": "", "forecast": "…", "previous": "…"}]}
    ],
    "updated_at": 1793288635,
    "stale": false,
    "count": 38
  }
}

资讯接口同样共享套餐 QPS：资讯与行情合计扣减同一个令牌桶，429 与 X-RateLimit-* 响应头口径和行情接口一致。

冷启动（进程刚启动、首轮抓取未完成）返回 503，客户端应退避重试，不要当成"没有数据"。

3.8 资讯：服务状态

GET /api/v1/news/status

运维接口：内部网关 Token，或任意持有 news / calendar 的客户 Token 可读。返回各语言的快讯/日历条数、最近更新时间与各条抓取线路的健康度。

4. WebSocket 实时分发

4.1 连接与鉴权

wss://api.example.com/ws/v1

流程：连接 → 5 秒内发送 auth 帧（见 2.4）→ 收到 auth 确认 → 发送 subscribe。

Token 长期有效，连接建立后不需要定期更换凭证。订阅到期时服务端会主动以 4004 关闭连接。

4.2 客户端指令

所有指令都带 id，服务端回复会原样带回，便于匹配请求与响应。

订阅

{
  "action": "subscribe",
  "id": "req-1001",
  "symbols": ["BTC/USDT", "ETH/USDT", "EUR/USD"],
  "streams": ["ticker", "kline"],
  "interval": "1m"
}

{
  "event": "subscribe",
  "id": "req-1001",
  "code": 0,
  "msg": "Subscribed successfully",
  "subscribed": ["BTC/USDT", "ETH/USDT", "EUR/USD"],
  "rejected": [{"symbol": "XAU/USD", "code": 403, "msg": "not allowed by plan"}]
}

• 订阅成功后，服务端会立即为每个品种推送一次当前快照（snapshot: true），随后是增量推送。客户端不必再调用 REST 初始化。
• 部分品种无权限时，其余品种照常订阅，被拒绝的放在 rejected 中。

取消订阅

{ "action": "unsubscribe", "id": "req-1002", "symbols": ["ETH/USDT"] }

查询当前订阅

{ "action": "list", "id": "req-1003" }

心跳

{ "action": "ping", "timestamp": 1700000000123 }

{ "event": "pong", "timestamp": 1700000000124 }

• 客户端应在 30 秒内至少发送一次 ping 或任意指令；超过 60 秒无任何数据交互，服务端以 4008 关闭。
• 浏览器无法发送原生 ping 帧，因此业务层 ping 是必需的。
• 服务端也会定期发送协议层 Ping，客户端库通常会自动回复 Pong。

4.3 行情推送帧

Ticker

{
  "stream": "ticker",
  "symbol": "BTC/USDT",
  "snapshot": false,
  "seq": 918273646,
  "data": {
    "symbol": "BTC/USDT",
    "digits": 2,
    "bid": "67520.50",
    "ask": "67521.10",
    "last": "67520.80",
    "bid_size": "2.40",
    "ask_size": "1.85",
    "volume_24h": "12845.62",
    "high_24h": "68100.00",
    "low_24h": "66400.00",
    "change_24h": "+1.65",
    "source": "binance",
    "ts": 1700000000123,
    "server_ts": 1700000000125,
    "stale": false,
    "expiring": false
  }
}

expiring 为 true 表示该订阅已过期并处于宽限期，服务即将停止。客户端收到后应提示客户续费；宽限期结束后连接会被以 4004 关闭。该字段只出现在订阅进入宽限期期间，正常情况恒为 false。

序列号（seq）规则：seq 是每个品种的全局递增整数，与连接无关。

• 客户端发现 seq 不连续，说明中间有帧丢失（正常只会发生在慢客户端被合并的情况下）。
• 丢失后应主动发一次 {"action":"subscribe","symbols":["BTC/USDT"]} 重新获取快照，或调用 REST 快照。
• 服务端对慢客户端只保留每个品种的最新一帧，因此 seq 跳号是预期行为，不会影响价格正确性，但会丢掉中间的 tick。

K 线推送（订阅 kline 流时）

{
  "stream": "kline",
  "symbol": "BTC/USDT",
  "interval": "1m",
  "seq": 918273647,
  "data": {
    "open_time": 1700000000,
    "open": "67500.00",
    "high": "67530.00",
    "low": "67490.00",
    "close": "67520.50",
    "volume": "12.8400",
    "tick_count": 214,
    "closed": false
  }
}

• 未收盘的 K 线按套餐 push_interval_ms 节流推送；收盘时推送一次 closed: true 的最终值，此后该 open_time 不再推送。

深度推送（订阅 depth 流时，需要套餐含深度权益）

{
  "stream": "depth",
  "symbol": "BTC/USDT",
  "seq": 918273648,
  "data": {
    "bids": [["67520.50", "1.520"]],
    "asks": [["67521.10", "0.950"]],
    "last_update_id": 88214,
    "ts": 1700000000123,
    "stale": false
  }
}

深度为全量快照推送（不做增量），档数等于套餐的 depth_levels。

4.4 服务端错误帧

{
  "event": "error",
  "id": "req-1004",
  "code": 429,
  "msg": "rate limit exceeded",
  "timestamp": 1700000000124
}

业务错误（如订阅超限）返回错误帧后连接保持不断开；严重错误才关闭连接。

4.5 关闭码

重连建议：4001～4004 属于凭证或权限问题，不要盲目重连，应先到控制台核实；4008、1011 使用指数退避（1s、2s、4s…上限 30s），并带随机抖动。4004 在客户续费后即可重连成功，无需更换 Token。

5. 状态码与异常

5.1 HTTP 状态码

5.2 业务错误码（响应体 code）

5.3 数据质量约定