Gate API 合约时间校验,是 Gate 为加强合约交易请求在撮合引擎(ME)侧的时间校验能力而在 REST API 与 WebSocket API 中新增的请求头字段机制。客户端用两个请求头标记发送时刻和有效时间窗口,单位均为微秒。本次更新仅适用于 Gate 3.0 交易架构。
这个机制解决的是量化交易和程序化下单中的具体问题:一笔订单在网络上排队、重试或因本地时钟漂移而延迟到达时,市场价格可能已经变了。有了时间校验,客户端可以明确声明过期时间,把过期控制放在撮合引擎层面,防止过期请求进入撮合链路。
Gate 合约接口新增两个请求头:X-Gate-Client-Send-Us(客户端发送时间戳,微秒)和 X-Gate-Timeout-Window-Us(请求有效时间窗口,微秒)。
发送时间戳以 Unix 纪元起的微秒数表示。服务器用它和本地接收时间做差,得出请求的实际耗时。
时间窗口定义请求允许的最大延迟。差值超出窗口,服务器拒绝该请求。
REST 接口 2026 年 11 月 16 日上线;WebSocket 接口 11 月 19 日上线。
接入步骤为:同步本地时钟 → 计算微秒时间戳 → 写入两个请求头 → 按最新字段名称检查及更新相关 API 集成逻辑。
这个字段携带客户端发送请求时的 Unix 时间戳,单位是微秒。1794794400123456 对应一个精确到微秒的时刻。注意单位是微秒,不是毫秒或秒——这是最常见的接入错误,会导致服务器算出"时间戳过早"或"时间戳超前"的报错。
服务器用这个值计算请求离开客户端的时刻,再用本地接收时间减去它,得到实际耗时。如果客户端时钟和服务器有显著偏差,这个差值就不准确,即使网络延迟本身很正常。
这个字段定义请求允许的最大有效窗口,单位同样是微秒。5000000 对应五秒;500000 对应零点五秒,适合对延迟敏感的下单场景。
窗口大小由客户端自己决定。窗口越小,过期请求被拒绝的概率越高,可以防止在已经变化的市场条件下成交;窗口越大,对网络波动和时钟漂移的容忍度越高,但允许更多时间让价格偏离下单时的预期。
合约市场价格在毫秒级别就能发生变化。一笔按当前价格意图发出的订单,如果延迟几秒才到达撮合引擎,成交价格可能已经偏离用户预期。有了时间校验,客户端可以声明请求在多长时间内有效,撮合引擎在校验阶段就处理过期请求。
官方公告指出,本次更新加强了撮合引擎(ME)侧的时间校验能力,请使用 Gate 3.0 交易架构的 API 用户关注本次字段调整,并根据最新字段名称检查及更新相关 API 集成逻辑。时间校验覆盖三种典型场景:
网络延迟突增。 请求耗时超过预期时,服务器在校验阶段就拒绝它,防止在用户不再认可的价格上成交。
本地时钟漂移。 客户端时钟快了或慢了,服务器算出的耗时就不准确。客户端可以通过报错响应发现问题,然后调整时钟同步。
请求重放。 被截获并在窗口过期后重发的请求,会因为耗时超出窗口而被拒绝。这在签名鉴权之上增加了一层防重放能力。
在写入时间戳之前,先把客户端系统时钟校准到可靠的时间源。用 NTP 定期同步,或者查询 Gate 服务器时间接口并记录本地与服务器的时间偏移量。标准 NTP 配置通常能将偏差控制在几毫秒以内,对于一到五秒的时间窗口来说足够。
每次准备请求时,取当前时间的微秒表示:
import time
send_us = int(time.time() * 1_000_000)
const sendUs = Date.now() * 1000;
把这个值写入 X-Gate-Client-Send-Us 请求头。
根据策略的延迟容忍度选择窗口值。做市或剥头皮等对延迟敏感的策略,可以用 500000 微秒(零点五秒);网格交易或组合再平衡等较慢的策略,可以用 5000000 微秒(五秒)。
把这个值写入 X-Gate-Timeout-Window-Us 请求头。
当服务器拒绝一个因为耗时超出窗口的请求时,客户端应该:
每次重试都必须用新的时间戳和窗口,不能复用原始值。
随时间推移,客户端时钟可能偏离服务器。可以定期同步 NTP,或者查询服务器时间接口来校准偏移量。在监控面板或控制台上加一个轻量检查,报告每次部署时本地时间与服务器时间的偏移。同时把时间校验失败率作为运维健康信号——失败率持续上升通常意味着时钟漂移,而不是网络问题。
REST 接口于 11 月 16 日上线,WebSocket 接口于 11 月 19 日上线。两个请求头对两者都适用,但接入方式不同。
每个 HTTP 请求独立携带两个请求头。客户端在准备请求的那一刻计算发送时间戳。没有连接状态需要维护——每个请求自带完整的时间信息。
WebSocket 是持久连接。客户端在已建立的连接上发送消息。发送时间戳应该反映消息写入套接字的时刻,而不是连接建立的时刻。
| 维度 | REST API | WebSocket API |
|---|---|---|
| 发布日期 | 2026 年 11 月 16 日 | 2026 年 11 月 19 日 |
| 连接模型 | 无状态(逐请求) | 持久(逐连接) |
| 时间戳时机 | 请求准备时 | 消息写入套接字时 |
| 适用范围 | 仅 Gate 3.0 合约交易 | 仅 Gate 3.0 合约交易 |
| 接入要点 | 每次请求都设置两个请求头 | 按每条消息分别计算时间戳 |
WebSocket 的下单和订阅管理同样受益于时间校验:一个过期的订阅请求或延迟的订单消息,如果超出了声明的窗口,会被服务器拒绝。
最常见的错误是把毫秒或秒当成微秒发送。毫秒级时间戳比微秒级小三倍数量级,服务器会算出负耗时或"远在过去"的时间。从秒出发要乘以一百万,从毫秒出发要乘以一千。
如果客户端时钟比服务器快或慢的幅度超过了时间窗口本身,所有请求都会被拒绝。解决方法是同步时钟。无法运行 NTP 时,可以从服务器时间接口计算偏移量,在生成发送时间戳前应用。
100000 微秒(零点一秒)的窗口在跨区域网络路径或延迟波动较大的客户端上可能太紧。如果频繁出现拒绝报错,逐步扩大窗口直到失败率降到可接受水平。大多数策略从 1000000 微秒(一秒)开始。
非常大的窗口(例如 60000000 微秒即六十秒)对过期执行几乎没有保护。在快速变化的合约交易市场里,六十秒前的请求几乎必然在远离当前价格的位置成交。把窗口匹配到策略的实际延迟容忍度。
缺少任一请求头时,API 的行为取决于具体端点的配置——查阅官方文档确认。作为通用做法,两个请求头始终一起设置。
Gate API 合约时间校验为合约交易接口在撮合引擎(ME)侧增加了时间校验能力。本次更新仅适用于 Gate 3.0 交易架构。客户端通过 X-Gate-Client-Send-Us(微秒级发送时间戳)和 X-Gate-Timeout-Window-Us(微秒级有效窗口)告诉服务器请求应在多长时间内有效。超出窗口的请求被拒绝,防止网络延迟导致的误成交、时钟漂移和请求重放。
接入需要四步:同步时钟、计算微秒时间戳、每次请求设置两个请求头、校验失败时重新计算时间戳并重试。REST 接口 2026 年 11 月 16 日上线,WebSocket 接口 11 月 19 日上线,覆盖 Gate 3.0 合约交易接口。
Gate API 合约时间校验是 Gate 为加强合约交易请求在撮合引擎(ME)侧的时间校验能力而新增的机制。两个请求头——X-Gate-Client-Send-Us 和 X-Gate-Timeout-Window-Us——配合使用,确认请求在有效窗口内发送。本次更新仅适用于 Gate 3.0 交易架构。
合约市场价格在毫秒级别就能发生变化。延迟到达的订单可能在用户不再认可的价格上成交。时间校验让客户端可以声明请求在多长时间内有效,防止网络延迟、时钟漂移和请求重放导致的过期执行。
两个请求头设计为配合使用。X-Gate-Client-Send-Us 提供发送时间戳,X-Gate-Timeout-Window-Us 提供有效窗口。缺少任一个,服务器无法完成时间比较。具体端点的要求以官方文档为准。
省略 X-Gate-Timeout-Window-Us 时的默认行为取决于端点配置。官方 Gate API 文档指定了默认值。需要精确控制的客户端应始终主动设置该字段,而不是依赖默认值。
两个请求头都使用 Unix 纪元起的微秒数。一秒等于一百万微秒,一毫秒等于一千微秒。
API 返回的错误信息表明请求的耗时超出时间窗口。具体错误码和消息格式见官方 Gate API 错误参考。客户端收到后应重新计算时间戳并重试。
不发送新请求头的现有客户端继续按原有方式工作。希望获得时间校验保护的客户端可以在下次更新时接入。该机制是增量式的,不改变现有请求格式。
本次更新仅适用于 Gate 3.0 交易架构下的合约交易接口,其他架构暂不支持。现货交易、钱包和其他 API 分组有各自的规范。查阅官方文档确认每个端点的适用范围。
免责声明: 以上内容仅供信息和教育目的,不构成金融、投资或交易建议。合约和衍生品交易存在重大亏损风险。最新的接口规范、错误码和字段要求请以 Gate 官方 API 文档为准。
* 投资有风险,入市须谨慎。本文不作为 Gate 提供的投资理财建议或其他任何类型的建议。
* 在未提及 Gate 的情况下,复制、传播或抄袭本文将违反《版权法》,Gate 有权追究其法律责任。





