外汇实时行情API接入：WebSocket重连后，怎样避免显示旧报价？

TickDB Research ·

摘要：给外汇看板、汇率监控或价格提醒接入实时行情，连接恢复以后，页面什么时候才能重新显示“正常更新”？本文面向负责这些功能的开发者，以 TickDB 的 EUR/USD 真实订阅为例，走完连接、订阅、主动断开与重连的过程，讲清报价时间、心跳和页面状态怎样配合，帮团队少被旧数据误导。文章里的恢复顺序和验收清单，产品经理和技术同事可以一起对照检查页面表现。

行情页上的连接灯重新变绿，EUR/USD 却还停在断线前的价格。如果价格提醒跟着恢复运行，它使用的可能仍是上一条旧记录。用户关心的是“这条报价更新到什么时候”，页面却只告诉他“网络又连上了”。

接入时，最好把连接状态和报价状态分开处理：重新订阅目标货币对，收到时间可用的新报价，再恢复正常提示。TickDB 的 WebSocket 行情订阅可以持续提供 EURUSD 报价及其报价时间；下面用一段真实运行记录，把这条恢复路径完整走一遍。

美联储官网列出的下一次 FOMC 会议安排在 2026 年 10 月 27—28 日。重要日程前的外汇监控，除了配好价格提醒，也值得提前检查：数据中断后页面会怎么恢复。美联储会议日历

图1：连接恢复后，还要检查目标报价及其时间。

image.png

一分钟看懂：绿灯亮了，为什么还要等报价

行情页的恢复过程，可以拆成下面几个时刻：

客户端已经收到什么页面知道了什么接下来还要看什么
新连接打开连接通道已建立是否重新订阅了 EURUSD
订阅确认或心跳回复请求得到了回应是否收到目标货币对的报价
EURUSD 报价有了可检查的数据时间是否推进，是否落在页面允许的时间范围内

产品需求也可以写得更具体一点：断线时保留最后价格和报价时间，显示“连接中断”；重新连上以后，先显示“等待 EURUSD 报价”；等报价通过检查，再切回正常状态。

这样，用户能看到数据停在了哪里，技术同事也有明确的恢复条件。

实测记录：从主动断开，到收到新报价

2026 年 10 月 22 日，我们使用 Node.js 26.0.0 和 ws 8.22.0，订阅了 TickDB 的 EURUSD 行情。最终这次运行持续约 25 秒，收到 62 条通过基础检查的报价，经历两次连接和一次本客户端主动断开。脚本最长运行时间设为 90 秒。

下面是日志里的恢复顺序。时间统一使用 UTC，北京时间需要加 8 小时。

客户端事件UTC时间
请求主动断开13:57:39.322
新连接打开13:57:42.018
再次发送 EURUSD 订阅13:57:42.018
收到订阅确认13:57:42.381
记录应用层 pong 事件13:57:42.383
收到通过恢复检查的新报价13:57:42.509

主动断开前，最后一条报价为 1.11953。恢复后第一条通过检查的新报价为 1.11952，它携带的报价时间是 13:57:42.469Z。

这次断开是测试脚本主动发起的。原始消息和事件日志都留着，可以对照查看重连后先收到了什么、页面为什么恢复正常状态。

image.png

图2：从新连接打开到收到通过检查的新报价，相隔 491 毫秒，中间包含重新订阅和等待报价的客户端流程。

先把 EUR/USD 报价接进来

TickDB 当前文档给出的 WebSocket 地址是：

wss://api.tickdb.ai/v1/realtime

认证使用 api_key 查询参数。密钥从后端安全环境读取，日志里不要输出带密钥的完整连接地址。TickDB连接实践

每次连接成功打开后，示例脚本发送下面的订阅消息：

{
  "cmd": "subscribe",
  "data": {
    "channel": "ticker",
    "symbols": ["EURUSD"]
  }
}

连接重新建立后，也要再发一次。示例不会默认上一次连接的订阅还有效。

读懂第一条报价

这是最终运行中保存的第一条 EURUSD 行情消息：

{
  "cmd": "ticker",
  "data": {
    "symbol": "EURUSD",
    "type": "forex",
    "last_price": "1.11950",
    "bid_price": "1.11950",
    "ask_price": "1.11951",
    "spread": "0.00001",
    "timestamp": 1792677449581
  }
}

这里的 timestamp 是毫秒时间戳，对应 2026-10-22T13:57:29.581Z；客户端收到这条消息的时间是 13:57:29.745Z。

这两个时间都值得保存。前者是报价自带的时间，后者是消息到达本客户端的时刻。两者之差还包含时钟偏差和链路处理，不能直接当成单程网络延迟。

价格按返回的字符串保存。需要双边报价的页面，还要分别保留买价 bid_price 和卖价 ask_price。这些外汇行情消息应当作报价更新来用，不要改写成已经发生的外汇成交记录。TickDB行情订阅文档

价格没变，也可能一直在更新

判断数据有没有更新，只看价格跳不跳，很容易看走眼。

原始记录中有这样两条相邻报价：

价格报价自带的UTC时间客户端接收UTC时间
1.1195213:57:30.39313:57:30.440
1.1195213:57:30.48113:57:30.527

价格相同，报价时间却向前推进了。对用户来说，屏幕上的数字没有变化；对程序来说，它已经收到了新的观察记录。

所以，监控要同时记录消息时间和报价时间。只看“这个数字多久没跳”，很难判断连接是否正常、报价还在不在更新。

重连以后，心跳为什么不能替报价过关

这次运行中，新连接打开以后，先收到订阅确认和应用层 pong，随后才收到 EURUSD 报价。

示例脚本会继续等待，并检查报价是否满足以下条件：

  • 标的是 EURUSD；
  • 价格和毫秒时间戳可用；
  • 报价时间晚于主动断开前的最后一条报价；
  • 落在示例设定的时间范围内。

恢复后的第一条报价，报价时间是 13:57:42.469Z，客户端在 13:57:42.509Z 收到，随后记录恢复。

心跳回复不会更新页面上的报价。WebSocket 协议本身的 Ping/Pong 控制帧，和 TickDB 的 JSON ping、pong 消息要分开看。日志里的这次 pong 是应用层消息；目标货币对的价格仍然从 ticker 消息里取。IETF WebSocket协议、TickDB心跳文档

没有新消息时，旧报价也会继续变老

如果程序只在收到消息时检查时间，一旦没消息了，这段检查就不会跑。最后一条报价可能一直挂着“正常”状态。

本次运行的脚本每秒重新判断当前显示状态。即使连接还开着、没有新消息，旧报价超过设定时间后也会转入相应提示。

本示例把报价过期阈值设为 5 秒；如果报价时间比本地时钟还快，也留 5 秒容忍范围，避免因时钟偏差误判。这些是示例里设的参数，实际项目要按看板、提醒规则和时钟环境调整。

页面可以继续保留最后价格，同时显示报价时间和等待提示。这样，用户既能看到最后一次记录，也能知道当前状态。

连续重试时，等待时间怎样安排

TickDB 当前连接指南采用分阶段等待：

重试次数每次等待
第1—3次1秒
第4—6次5秒
第7次及以后30秒

示例按这个顺序安排重试；连接成功打开后重置计数，并重新订阅。认证或权限错误要先处理具体原因，一直重试解决不了权限问题。TickDB重连指南

日志还为每次连接记录独立编号，方便把断线前后的消息分开查看。

报价恢复了，断流的那一段仍要留下

CSV 逐条保存连接编号、接收时间、报价时间、价格和检查状态。事件日志另外记录主动断开、连接打开、发送订阅和收到新报价的时刻。

这些记录可以用来给看板或下游数据标出中断窗口。后面重新收到报价，也不会自动补出中间每一次更新。

比如，从断线前的 1.11953 到恢复后的 1.11952，只能比较这两个观察点；仅凭它们，还原不了期间的每次变化、价格穿过某个阈值的准确时刻，也说不清具体漏了多少条消息。

需要历史 K 线时，要另外查询对应时间窗口，并检查返回结果。K 线汇总的是一个周期里的数据；补上 K 线以后，也要保留实时订阅曾经中断的记录。

给产品与技术同事的页面验收清单

检查时刻页面应当怎样表现核对重点
连接中断保留最后价格和报价时间，提示中断不把最后一次记录继续显示成正在更新
新连接打开显示等待目标货币对报价已重新发送订阅
只有确认或心跳继续等待报价不因收到控制消息就清除提示
新报价到达按标的和报价时间检查后更新状态同时保存报价时间与接收时间
连接正常但长时间没有新报价根据应用设定调整提示时间检查仍持续运行
后续复盘能定位中断窗口不把恢复后的两个端点当作全部过程

这张表可以直接放进需求文档。先约定页面要告诉用户什么，再让技术实现对应检查，比只写一句“支持断线重连”更容易验收。

常见问题

第一次接外汇实时行情，从哪里开始？

先只订阅 EURUSD，确认收到订阅回应和真实的 ticker 消息，再扩展货币对。具体账户权限和可用标的，以当前文档和实际返回为准。

连接恢复了，却一直没有 EURUSD 报价，怎么办？

保留等待状态，依次检查发出去的订阅、确认消息、返回标的、服务端错误和报价时间。收到心跳或其他货币对的数据，都不应该解除 EURUSD 的等待提示。等待状态要一直保持到目标报价通过检查，或者明确转为异常提示。

后续需要当前快照或历史走势，怎样配合？

可以按页面任务另外查询行情快照或历史 K 线，给结果保留各自的时间和用途。快照用来检查某个时点能查到的状态，历史数据用来复盘相应窗口；订阅中断记录继续保留，方便解释数据来源。

把恢复条件写进产品需求

外汇行情接入后，页面应该能解释清楚：订阅了什么、最后收到什么，以及为什么从等待状态恢复正常。

这次实测留下了完整顺序：连接重新打开，客户端再次订阅，随后收到报价时间推进、并通过检查的 EURUSD 报价。对照恢复顺序和时间图，团队可以把“页面什么时候恢复”写进验收条件。

用自己的货币对做一次同样的测试，再决定看板和提醒什么时候恢复。连接灯和报价时间一起看，用户才更容易判断眼前这条数据该怎么用。

数据记录于2026年10月22日，用于演示行情处理，不构成投资建议。

参考资料

  1. TickDB：WebSocket连接与重连实践、行情订阅、心跳消息
  2. IETF：[RFC 6455中Ping/Pong控制帧的定义]
  3. 美联储：[FOMC会议日历]

相关文章

美股API接入指南：实时行情、历史K线，怎样避免显示错价格？

美股行情功能接通以后，产品经理还要回答：页面显示的是哪个时段的价格，历史曲线包含哪些交易，财报之后怎样继续观察？本文以特斯拉三季报为案例，实际调用 TickDB REST API，取得报价、历史日线、分钟线与交易时间信息，解释实时行情、历史K线和盘前盘后数据怎样分工，并提供可运行脚本、原始结果与财报行情观察表，方便产品和技术同事一起验收。

TickDB Research ·

美股数据源怎么选？实时行情、历史回测和AI查询的选型清单

摘要 ：做美股产品、量化研究或 AI 助手，团队最怕“演示时看着都行，真交付了全得返工”。实时行情得卡准时段，历史回测得弄清复权，AI 查询必须能追溯真实数据。本文结合 Yahoo/yfinance、Alpha Vantage、Massive 和 TickDB 的官方资料与真实跑通样本，给你一套选型顺序，并附上能直接扔给技术同事的“需求卡”、原始结果和测试脚本。 假设你们团队要接入苹果（AA…

TickDB Research ·

美股行情数据源怎么选？实测四家平台：别让错乱的“最新价”毁掉你的实时看板与 AI 查询

为美股团队选数据源，最怕“演示能用，交付返工”。本文结合真实自动化实测与官方资料，聚焦 实时看板、历史回测与 AI 查询 三大场景。文章不仅拆解了盘前/盘后价格时点错乱、复权口径不一等五个选型陷阱，还 直接提供了可运行的 Python 验证代码、多市场字段对比明细和复权因子计算公式 。你将看到 TickDB 在同一响应中如何返回三个时点的价格，以及如何通过 MCP 原生协议让 AI 直接取回…

TickDB Research ·

A股回测用前复权还是后复权：同一只股票，两条收益曲线差 34 个百分点

同一个接口、同一只A股、同一段 250 个交易日， adjust 传 none 累计收益是 −29.92%，传 forward 是 +4.50%。差 34.42 个百分点。三条序列都没算错，它们回答的是三个不同的问题。更要紧的是：不传这个参数时默认给的是不复权，而前复权序列每次除权都会整条重算。这篇讲清五种复权取值的差别、哪一条可复现，最后给一段能自检序列类型的代码。 我在 10 月 19…

TickDB Research ·

A股实时数据API：请求成功，不等于名单里每只票都有数据

摘要 ：本文写给负责自选股看板的产品经理，以及参与投研数据源选型的负责人。接入A股实时数据API之后，怎么确认名单里每只股票这一轮都拿到了数据？怎么避免把没返回的行、或者旧价格，当成正常更新？文章用TickDB批量行情快照的真实结果，加上国内外机构资料和反例，把名单核对、数据时间和交易窗口拆开讲，并提供页面检查清单、Python脚本和五项边界自测材料，可以直接转给技术同事验证。 本文回答三个…

TickDB Research ·