v4.0.0 · Stable #Gate Futures WebSocket v4.0.0 Gate 提供简单而强大的 Websocket API，将 Gate BTCUSDT 永续合约交易状态集成到您的业务或应用程序中。 我们在 Python 和 Golang 中有语言绑定，将来还会有更多！您可以在右侧的深色区域中查看代码示例，并且可以通过右上角的选项卡切换示例的编程语言 #服务地址 我们提供 BTC/USDT 结算永续合约交易服务器地址，您可以根据自己的情况选择其中之一 #BTC Contract 地址列表: 线上交易: wss://fx-ws.gateio.ws/v4/ws/btc 模拟盘交易: wss://fx-ws-testnet.gateio.ws/v4/ws/btc #USDT Contract 地址列表: 线上交易: wss://fx-ws.gateio.ws/v4/ws/usdt 线上SBE: wss://fx-ws.gateio.ws/v4/ws/usdt/sbe 模拟盘交易: wss://ws-testnet.gate.com/v4/ws/futures/usdt 建议使用SBE以获取更快的行情和更小的带宽成本 如果你使用老的服务地址(wss://fx-ws.gateio.ws/v4/ws 或 wss://fx-ws-testnet.gateio.ws/v4/ws), 将默认是 BTC 结算的 websocket 服务. #变更日志 2026-04-14 部分频道支持SBE数据推送: futures.trades、futures.obu、futures.book_ticker、futures.tickers、futures.candlesticks、futures.order_book、futures.order_book_update、futures.usertrades、futures.positions、futures.orders。 具体的使用查看SBE 数据推送章节 2026-03-30 futures.order_place 下单请求：iceberg 字段说明修正为类型 string（原文档为 int64）、可选（原文档为必填） 2026-02-09 模拟盘部分频道支持SBE数据推送 正式环境实装另行同步 2026-02-04 futures.obu 模拟盘新增立即的首次快照推送，该次快照推送将会在订阅请求的响应之前推送。此行为与之前快照在订阅请求的响应之后推送不同，请注意该行为变更。 正式环境实装另行同步 2026-01-07 futures.orders 新增字段 market_order_slip_ratio (市价单的预设滑点比例) futures.order_place futures.order_batch_place 入参新增字段market_order_slip_ratio (允许自定义市价单的最大滑点) 2025-12-09 合约的张数支持小数，所有的推送的张数、成交量等均改为字符串（可能是小数）。 如何对接websocket的小数支持： 在请求链接websocket时，加入："X-Gate-Size-Decimal": "1" 的header即可，推送的张数、成交量等将会是字符串（可能是小数）。 如果在链接websocket时，不加入："X-Gate-Size-Decimal": "1" 的header，推送将保持原始的字段类型（整形）。 请尽快切换到字符串的推送支持，后续整形的推送将会下线(下线时间会另行通知)。 如果出现小数的size，用户如果还是在使用整形的推送，那么推送出来的size将会是向下取整，例如1.1、1.5、1.7的size推送出去都将会是1。 将影响到以下的推送频道，和对应的字段。 频道 字段 futures.trades size futures.tickers total_size futures.book_ticker A B futures.order_book_update a.s、b.s futures.order_book a.s、b.s futures.obu size 会有小数 futures.candlesticks v futures.liquidates left、size、 order_size futures.public_liquidates size futures.contract_stats long_liq_size、short_liq_size、open_interest futures.orders iceberg、left、size futures.usertrades size futures.auto_deleverages position_size、trade_size futures.positions size futures.autoorders position_size、 trade_size 将影响到以下的API请求频道，主要涉及张数，成交量等字段。 频道 字段 futures.order_place size、left futures.order_batch_place size futures.order_cancel size、left futures.order_cancel_cp size、left futures.order_amend size、left futures.order_list size、left futures.order_status size、left 2025-09-25 新增 仓位 Adl 排名频道 文档 2025-05-22 新增深度频道V2文档说明 futures.order_book_update 新增字段 full 2025-04-25 账户交易API新增通道 futures.order_cancel_ids futures.order_book 和 futures.order_book_update 新增深度档位字段 l 2025-04-18 补充文档代码示例 2025-03-24 修复了深度频道部分文档的错误描述 修复了订单频道部分文档的错误描述 2025-03-21 更新了频道 futures.orders 文档, 新增了 update_id, update_time, biz_info, stop_profit_price 和 stop_loss_price 等字段的说明 2025-03-12 合约统计信息频道增加 contract 字段 更新账户交易 API，新增了 x-gate-exptime 字段 修复了账户交易 API 部分文档描述性错误 2025-02-19 新增频道 futures.public_liquidates 用于推送合约强平订单的快照信息 2025-02-10 更新账户交易 API，新增了 x_in_time, x_out_time, conn_trace_id, trace_id 字段 futures.order_place, futures.order_batch_place, futures.order_cancel, futures.order_cancel_cp 和 futures.order_amend 新增了 x_gate_ratelimit_requests_remain, x_gate_ratelimit_limit 和 x_gat_ratelimit_reset_timestamp 字段 2024-11-18 在频道 futures.order_book_update 移除 10 档位 1000ms 推送间隔支持 2023-09-21 在频道futures.trades推送参数中新增is_internal字段 2023-08-18 添加 WebSocket API 操作 WebSocket API 允许通过 WebSocket 连接创建、取消、修改、查询订单。 2023-07-07 在频道futures.order_book_update中添加新的间隔“20ms”，请注意，20ms 的间隔仅支持 20 档位 2023-06-20 在频道 futures.positions 增加update_id 字段 2022-12-22 在频道 futures.autoorders 初始结构中添加新字段 auto_size，将字段详细信息添加到 http api 2022-11-22 在通用的返回结果中添加新字段“time_ms”，以表示创建消息的时间 2022-08-11 在频道futures.autoorders通知中添加新字段text 在频道futures.tickers通知中添加新字段low_24h和high_24h 2022-04-15 在频道futures.balances通知中添加新字段 currency 2021-03-31 在频道futures.book_ticker和futures.order_book推送中添加毫秒字段t 2021-03-10 添加新的订单簿频道 futures.book_ticker 以实时推送最佳卖价/买价 添加新的订单簿频道 futures.order_book_update 以与用户推送订单簿更改 指定更新频率 添加本地订单簿维护文档 2021-03-01 在通用的返回结果中添加以_ms结尾的新毫秒精度时间戳 在futures.book all通知中添加新字段id 2020-8-08 添加完整代码 demo(golang, python) 2020-8-07 添加futures.autoorders频道 2020-7-07 添加futures.order_book频道 2020-4-30 添加futures.position频道 2019-11-06 新增 USDT 结算永续合约的 websocket 推送 为futures.tickers添加volume_24h_base字段、volume_24h_settle字段、volume_24h_quote字段 删除旧服务器地址（wss://fx-ws.gateio.ws/v4/ws 或 wss://fx-ws-testnet.gateio.ws/v4/ws） 如果您使用旧的服务器地址（wss://fx-ws.gateio.ws/v4/ws 或 wss://fx-ws-testnet.gateio.ws/v4/ws），我们 将为您使用 BTC 结算永续合约的 websocket 推送 2019-10-22 添加应用层 ping/pong 消息 2019-04-30 添加index和mark futures.candlesticks 订阅 为futures.tickers添加funding_rate_indicative字段 为futures.orders添加 is_reduce_only 和状态字段 2019-02-13 更改 webSocket 基本 url 为futures.tickers添加volume_24h_usd字段和volume_24h_btc字段 2019-01-11 添加futures.position_closes 和 futures.balance 订阅 删除频道 futures.auto_deleverages 和futures.liquidates的 finish_time 字段 为频道 futures.auto_deleverages 和futures.liquidates 添加 time字段 WebSocket 应用示例 # !/usr/bin/env python # coding: utf-8 import hashlib import hmac import json import logging import time import threading from websocket import WebSocketApp logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) event = threading.Event() class GateWebSocketApp(WebSocketApp): def __init__(self, url, api_key, api_secret, **kwargs): super(GateWebSocketApp, self).__init__(url, **kwargs) self._api_key = api_key self._api_secret = api_secret def _send_ping(self): while not event.wait(10): self.last_ping_tm = time.time() if self.sock: try: self.sock.ping() except Exception as ex: logger.warning("send_ping routine terminated: {}".format(ex)) break try: self._request("futures.ping", auth_required=False) except Exception as e: raise e def _request(self, channel, event=None, payload=None, auth_required=True): current_time = int(time.time()) data = { "time": current_time, "channel": channel, "event": event, "payload": payload, } if auth_required: message = 'channel=%s&event=%s&time=%d' % (channel, event, current_time) data['auth'] = { "method": "api_key", "KEY": self._api_key, "SIGN": self.get_sign(message), } data = json.dumps(data) logger.info('request: %s', data) self.send(data) def get_sign(self, message): h = hmac.new(self._api_secret.encode("utf8"), message.encode("utf8"), hashlib.sha512) return h.hexdigest() def subscribe(self, channel, payload=None, auth_required=True): self._request(channel, "subscribe", payload, auth_required) def unsubscribe(self, channel, payload=None, auth_required=True): self._request(channel, "unsubscribe", payload, auth_required) def on_message(ws, message): # type: (GateWebSocketApp, str) -> None # handle message received logger.info("message received from server: {}".format(message)) def on_open(ws): # type: (GateWebSocketApp) -> None # subscribe to channels interested logger.info('websocket connected') ws.subscribe("futures.tickers", ['BTC_USDT'], False) # custom header custom_headers = { "X-Gate-Size-Decimal": "1" } if __name__ == "__main__": logging.basicConfig(format="%(asctime)s - %(message)s", level=logging.DEBUG) app = GateWebSocketApp("wss://fx-ws.gateio.ws/v4/ws/usdt", "YOUR_API_KEY", "YOUR_API_SECRET", on_open=on_open, on_message=on_message, header=custom_headers) app.run_forever(ping_interval=5) Copy #Websocket API 概述 #事件 每个通用 订阅频道/channel（例如ticker、order_book等）都支持一些不同的事件消息，它们是： subscribe (推荐使用) 订阅，接受服务器的新数据通知。 unsubscribe 如果取消订阅，服务器将不会发送新数据通知。 update 服务器将向客户端发送新的订阅数据（增量数据）。 all 如果有新订阅的数据（所有数据）可用，服务器将向客户端发送通知。 #请求 每个请求都遵循通用格式，其中包含time、channel、event和payload。 请求 名称 类型 必选 描述 id Integer 否 可选的请求 ID，将由服务器发回，以帮助您识别服务器响应哪个请求 time Integer 是 请求时间 channel String 是 请求 subscribe/unsubscribe 频道 auth String 否 请求身份验证信息，请参阅身份验证部分了解详细信息 event String 是 请求event (subscribe/unsubscribe/update/all/api) payload Array 是 请求详细参数 #响应 与请求类似，响应遵循以下通用格式，其中包含： time, channel, event , error 和 result. 响应 名称 类型 必选 描述 time Integer 是 响应时间 time_ms Integer 是 毫秒响应时间 channel String 是 响应频道 event String 是 响应频道事件 (update/all) error Object 是 响应错误 result Any 是 返回来自服务端的新数据通知 或 对客户端请求的响应。如果有错误返回则error 不为空，没有错误则此字段为空。 注意：如果它是服务端发起的数据更新通知 那么 result 的类型是基于 channel 的，不同 channel 的 result 类型有所不同。 但如果是对客户端订阅请求的响应，那么 result 为固定的 {"status": "success"}。 验证订阅请求是否成功，您只需要检查 error 字段是否为空即可，不需要再解析 result 字段。 为了简单起见，下面的频道（channel）描述只给出对应频道的 payload 格式。 #错误 如果出现错误，您会收到error字段，其中包含错误代码和错误的类型。 错误 Code Message 1 invalid argument struct 2 invalid argument 3 service error 4 authentication fail #鉴权 如果频道是私有的，则请求体需要携带认证信息， 例如futures.usertrades WebSocket 认证使用与 HTTP API 相同的签名计算方法，但具有 以下差异： 签名字符串拼接方式：channel=&event=&time=