现货&杠杆
永续合约
交割合约
期权
统一账户
公告

Python
Golang

# Gate.io 永续合约 WebSocket v4

Gate.io 提供简单而强大的 Websocket API，将 gate.io BTCUSDT 永续合约交易状态集成到您的业务或应用程序中。

我们在Python中有语言绑定，将来还会有更多！您可以在右侧的深色区域中查看代码示例，并且可以通过右上角的选项卡切换示例的编程语言

# 服务地址

我们提供 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
模拟盘交易: wss://fx-ws-testnet.gateio.ws/v4/ws/usdt

WARNING

如果你使用老的服务地址(wss://fx-ws.gateio.ws/v4/ws 或 wss://fx-ws-testnet.gateio.ws/v4/ws), 将默认是 BTC 结算的 websocket 服务.

# 变更日志

2025-03-12

合约统计信息频道增加 contract 字段
更新账户交易 API，新增了 x-gate-exptime 字段
修复了账户交易 API 部分文档描述性错误

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.auto_orders频道

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）

TIP

如果您使用旧的服务器地址（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字段

# !/usr/bin/env python
# coding: utf-8

import hashlib
import hmac
import json
import logging
import time

from websocket import WebSocketApp

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


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, interval, event):
    while not event.wait(interval):
      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)


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)
  app.run_forever(ping_interval=5)

# 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=<channel>&event=<event>&time=<time>, 其中<channel>、<event>、<time>是对应的请求信息
身份验证信息在请求正文中的auth字段中发送。

您可以登录账户获取永续合约账户的 api_key 和 secret。

名称	类型	描述
`method`	String	验证方式:`api_key`
`KEY`	String	apiKey 的值
`SIGN`	String	签名结果

# example WebSocket signature calculation implementation in Python
import hmac, hashlib, time

## api_key method generate secret
secret = 'xxxx'
message = 'channel=%s&event=%s&time=%s' % ('futures.orders', 'subscribe', int(time.time()))
print(hmac.new(secret, message, hashlib.sha512).hexdigest())  ## Generating signature

# System API

提供系统状态检查，如 ping/pong.

# Ping/Pong

检查服务器/客户端连接.

gateway.io websocket 使用协议层 ping/pong 消息。服务器会发起 ping 操作。如果客户端没有回复，客户端将被断开。

websocket rfc 协议 (opens new window)

如果想主动检测连接状态，可以发送应用层 ping 消息，并接收 pong 消息。

# 请求参数

频道

futures.ping

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.ping"}')
print(ws.recv())

futures.ping操作返回 JSON 结构如下：

{
  "time": 1545404023,
  "time_ms": 1545404023123,
  "channel": "futures.pong",
  "event": "",
  "result": null
}

# ticker 频道

ticker是合约状态的高级概述。它向你展示了最高的，最低的、最后的交易价格。它还包括每日交易量和价格等信息

# 订阅操作

订阅永续合约 24hr 价格变动情况.

# 请求参数

channel

futures.tickers
event

subscribe
params

名称	类型	必选	描述
`payload`	Array	是	合约列表

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.tickers",
        "event": "subscribe", "payload" : ["BTC_USD"]}')
print(ws.recv())

上面的订阅请求返回 JSON 结构如下：

{
  "time": 1545404023,
  "time_ms": 1545404023123,
  "channel": "futures.tickers",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# ticker 推送

永续合约 24hr 价格变动情况推送

# 推送参数

channel

futures.tickers
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`contract`	String	合约名称
`last`	String	最新成交价
`change_percentage`	String	涨跌幅
`funding_rate`	String	资金费率
`funding_rate_indicative`	String	下一周期预测资金费率（已弃用，改用funding_rate）
`mark_price`	String	标记价格
`index_price`	String	指数价格
`total_size`	String	总数量
`volume_24h`	String	24 小时成交量
`quanto_base_rate`	String	双币种合约中基础货币与结算货币的汇率。不存在于其他类型的合同中
`volume_24h_btc`	String	近 24 小时 BTC 交易量（已弃用，请使用`volume_24h_base`、`volume_24h_quote`、`volume_24h_settle`代替）
`volume_24h_usd`	String	近 24 小时美元交易量（已弃用，请使用`volume_24h_base`、`volume_24h_quote`、`volume_24h_settle` 代替）
`volume_24h_quote`	String	近 24 小时交易量，以计价货币计
`volume_24h_settle`	String	近 24 小时交易量，以结算货币计
`volume_24h_base`	String	近 24 小时交易量，以基础货币计
`low_24h`	String	近 24 小时最低交易价
`high_24h`	String	近 24 小时最高交易价

{
  "time": 1541659086,
  "time_ms": 1541659086123,
  "channel": "futures.tickers",
  "event": "update",
  "result": [
    {
      "contract": "BTC_USD",
      "last": "118.4",
      "change_percentage": "0.77",
      "funding_rate": "-0.000114",
      "funding_rate_indicative": "0.01875",
      "mark_price": "118.35",
      "index_price": "118.36",
      "total_size": "73648",
      "volume_24h": "745487577",
      "volume_24h_btc": "117",
      "volume_24h_usd": "419950",
      "quanto_base_rate": "",
      "volume_24h_quote": "1665006",
      "volume_24h_settle": "178",
      "volume_24h_base": "5526",
      "low_24h": "99.2",
      "high_24h": "132.5"
    }
  ]
}

# 取消订阅

取消订阅

# 请求参数

channel

futures.tickers
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.tickers",
  "event": "unsubscribe",
  "payload": ["BTC_USD"]
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545404900,
  "time_ms": 1545404900123,
  "channel": "futures.tickers",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 公有成交频道

每当 gateway.io 发生交易时，该频道都会发送交易消息。它包括价格、金额、时间和类型等交易信息

# 公有成交订阅

订阅公有成交更新通知

# 请求参数

channel

futures.trades
event

subscribe
params

名称	类型	必选	描述
`payload`	Array	是	合约列表

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.trades",
        "event": "subscribe", "payload" : ["BTC_USD"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545405058,
  "time_ms": 1545405058123,
  "channel": "futures.trades",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 公有成交推送

通知最新交易更新

# 推送参数

channel

futures.trades
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`contract`	String	合约名称
`size`	int	交易数量
`id`	int	交易 ID
`create_time`	int	交易消息创建时间
`create_time_ms`	int	交易消息创建时间（以毫秒为单位）
`price`	string	交易价格
`is_internal`	bool	是否为内部成交。内部成交是指保险资金和 ADL 用户对强平指令的接管。由于不是市场深度上的正常撮合，交易价格可能会出现偏差，不会记录在 K 线上。如果不是内部交易，则该字段不会被返回。

size 正数表示买家，负数表示卖家

{
  "channel": "futures.trades",
  "event": "update",
  "time": 1541503698,
  "time_ms": 1541503698123,
  "result": [
    {
      "size": -108,
      "id": 27753479,
      "create_time": 1545136464,
      "create_time_ms": 1545136464123,
      "price": "96.4",
      "contract": "BTC_USD",
      "is_internal": true
    }
  ]
}

# 取消订阅

取消订阅公有成交更新通知

# 请求参数

channel

futures.trades
event

unsubscribe

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send(
  '{"time" : 123456, "channel" : "futures.trades", "event": "subscribe", "payload" : ["BTC_USD"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545404900,
  "time_ms": 1545404900123,
  "channel": "futures.trades",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 深度频道

order_book 频道允许您跟踪 gate.io 订单簿深度的状态。它以价格聚合的方式提供，可自定义精度。

共有三种不同的订单簿渠道可供订阅:

futures.order_book

全量频道，定期使用all推送完整的有限级别订单簿.
futures.book_ticker

实时推送最佳买价和卖价.
futures.order_book_update

以指定的更新频率向用户订单簿推送订单簿的更新内容.

WARNING

不建议通过futures.order_book接收订单簿更新，使用 futures.order_book_update 可以以更少的流量提供更及时的更新

如何维护本地订单簿:

订阅 futures.order_book_update 并指定级别和更新频率，例如 ["BTC_USDT", "100ms", "100"] 每 1s 推送 BTC_USDT 订单簿前 10 个级别的更新
缓存 WebSocket 通知。每个通知都使用“U”和“u”来告诉第一个和最后一个自上次通知以来更新 ID。
使用 REST API 检索基本订单簿，并确保记录了订单簿 ID（参考如下面的“baseID”）例如https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT&limit=10&with_id=true 获取 BTC_USDT 的 10 级基础订单簿
迭代缓存的 WebSocket 通知，找到第一个包含 baseID 的通知，即 U <= baseId+1 和 u >= baseId+1，然后开始从中消费。请注意，size为通知都是全量的 size，即应该使用它们覆盖替换原始的size。如果 size 等于 0，则从订单簿中删除价格。
转储所有满足 u < baseID+1 的通知。如果 baseID+1 < 第一个通知 U，则意味着当前的基本订单簿落后于通知。从步骤 3 开始检索更新的内容基本订单簿。
如果后续发现满足 U > baseID+1 的通知，则说明有更新丢失的。从步骤 3 重建本地订单簿。

# 深度全量更新频道

订阅深度.

# 请求参数

channel

futures.order_book
event

subscribe
params

名称	类型	必选	描述
`contract`	String	是	合约名称
`limit`	String	是	深度档位: 100, 50, 20, 10, 5, 1
`interval`	String	是	价格合并精度: "0"

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.order_book",
        "event": "subscribe", "payload" : ["BTC_USD", "20", "0"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545405058,
  "time_ms": 1545405058123,
  "channel": "futures.order_book",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 全量深度推送

全量深度更新推送

# 推送参数

channel

futures.order_book
event

all
params

名称	类型	描述
`result`	object	深度信息
»`t`	Integer	深度生成时间戳（以毫秒为单位）
»`contract`	String	合约名称
»`id`	Integer	深度 ID
»`asks`	Array	深度卖方的档位列表
»»`p`	String	档位价格
»»`s`	String	档位的数量
»`bids`	Array	深度买方的档位列表
»»`p`	String	档位价格
»»`s`	String	档位的数量

{
  "channel": "futures.order_book",
  "event": "all",
  "time": 1541500161,
  "time_ms": 1541500161123,
  "result": {
    "t": 1541500161123,
    "contract": "BTC_USD",
    "id": 93973511,
    "asks": [
      {
        "p": "97.1",
        "s": 2245
      },
      {
        "p": "97.1",
        "s": 2245
      }
    ],
    "bids": [
      {
        "p": "97.1",
        "s": 2245
      },
      {
        "p": "97.1",
        "s": 2245
      }
    ]
  }
}

# 全量深度取消订阅

取消订阅指定市场的深度

# 请求参数

channel

futures.order_book
event

unsubscribe

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.order_book",
        "event": "unsubscribe", "payload" : ["BTC_USD", "20", "0"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545445847,
  "time_ms": 1545445847123,
  "channel": "futures.order_book",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 最佳买卖价订阅

订阅深度最佳买卖价

# 请求参数

channel

futures.book_ticker
event

subscribe
params

payload是一个包含合约市场的列表.

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.book_ticker",
        "event": "subscribe", "payload" : ["BTC_USD"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545405058,
  "time_ms": 1545405058123,
  "channel": "futures.book_ticker",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 最佳买卖价的推送

如果 a 为空字符串，则表示空买价；如果 b 为空字符串，则表示空卖价。

最新买卖价的推送

# 推送参数

channel

futures.book_ticker
event

update
params

名称	类型	描述
`result`	object	深度的最佳买卖价
»`t`	Integer	最佳买卖价行情生成的时间戳（以毫秒为单位）
»`u`	Integer	深度的 ID
»`s`	String	合约名称
»`b`	String	最佳买方的价格，如果没有买方，则为空串
»`B`	Integer	最佳买方的数量，如果没有买方，则为 0
»`a`	String	最佳卖方的价格，如果没有卖方，则为空串
»`A`	Integer	最佳卖方的数量，如果没有卖方，则为 0

{
  "time": 1615366379,
  "time_ms": 1615366379123,
  "channel": "futures.book_ticker",
  "event": "update",
  "result": {
    "t": 1615366379123,
    "u": 2517661076,
    "s": "BTC_USD",
    "b": "54696.6",
    "B": 37000,
    "a": "54696.7",
    "A": 47061
  }
}

# 最佳买卖价的取消订阅

取消指定合约市场的最佳买卖订阅

# 请求

channel

futures.book_ticker
event

unsubscribe

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.book_ticker",
        "event": "unsubscribe", "payload" : ["BTC_USD"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545445847,
  "time_ms": 1545445847123,
  "channel": "futures.book_ticker",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 合约深度更新推送订阅

订阅深度更新推送

# 请求参数

channel

futures.order_book_update
event

subscribe
params

名称	类型	必选	描述
`contract`	String	是	合约名称
`frequency`	String	是	更新频率, `20ms` or `100ms`
`level`	String	否	可选的深度档位。允许以下档位：`100`、`50`、`20`；`20ms`频率只支持 `20`档位

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.order_book_update",
        "event": "subscribe", "payload" : ["BTC_USD", "100ms", "100"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545405058,
  "time_ms": 1545405058123,
  "channel": "futures.order_book_update",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 深度更新推送

深度更新推送

# 推送参数

channel

futures.order_book_update
event

update
params

名称	类型	描述
`result`	Object	自上次更新以来发生变更要价和出价
»`t`	Integer	订单簿生成时间戳（以毫秒为单位）
»`s`	String	合约名称
»`U`	Integer	本次更新开始的订单簿更新 ID
»`u`	Integer	本次更新结束的订单簿更新 ID
»`b`	Array	买方变动列表
»»`p`	String	变更的档位价格
»»`s`	Integer	档位的待成交数量。如果为 0，则从订单簿中删除该价格
»`a`	Array	买方变动列表
»»`p`	String	变更的档位价格
»»`s`	Integer	档位的待成交数量。如果为 0，则从订单簿中删除该价格

{
  "time": 1615366381,
  "time_ms": 1615366381123,
  "channel": "futures.order_book_update",
  "event": "update",
  "result": {
    "t": 1615366381417,
    "s": "BTC_USD",
    "U": 2517661101,
    "u": 2517661113,
    "b": [
      {
        "p": "54672.1",
        "s": 0
      },
      {
        "p": "54664.5",
        "s": 58794
      }
    ],
    "a": [
      {
        "p": "54743.6",
        "s": 0
      },
      {
        "p": "54742",
        "s": 95
      }
    ]
  }
}

# 深度更新取消订阅

取消指定合约的市场的深度更新订阅

# 请求参数

channel

futures.order_book_update
event

unsubscribe

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send(
  '{"time" : 123456, "channel" : "futures.order_book_update", "event": "unsubscribe", "payload" : ["BTC_USD", "100ms"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545445847,
  "time_ms": 1545445847123,
  "channel": "futures.order_book_update",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# K 线频道

提供一种访问 K 线信息的方法.

# K 线订阅

如果在contract前面加上mark_，则将订阅合约的标记价格 K 线；如果前缀为“index_”，将订阅指数价格 K 线.

# 请求参数

channel

futures.candlesticks
event

subscribe
params

名称	类型	描述
`interval`	String	Interval : "10s", "1m", "5m", "15m", "30m", "1h", "4h", "8h", "1d", "7d"
`contract`	String	合约名称

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.candlesticks",
        "event": "subscribe", "payload" : ["1m", "BTC_USD"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545445847,
  "time_ms": 1545445847123,
  "channel": "futures.candlesticks",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# k 线消息推送

k 线的消息推送

# 推送参数

channel

futures.candlesticks
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`t`	Integer	时间
`o`	String	开盘价格
`c`	String	收盘价格
`h`	String	最高价格
`l`	String	最低价格
`v`	Integer	成交量
`n`	String	合约名称
`a`	String	成交原始币种数量

{
  "time": 1542162490,
  "time_ms": 1542162490123,
  "channel": "futures.candlesticks",
  "event": "update",
  "result": [
    {
      "t": 1545129300,
      "v": 27525555,
      "c": "95.4",
      "h": "96.9",
      "l": "89.5",
      "o": "94.3",
      "n": "1m_BTC_USD",
      "a": "314732.87412"
    },
    {
      "t": 1545129300,
      "v": 27525555,
      "c": "95.4",
      "h": "96.9",
      "l": "89.5",
      "o": "94.3",
      "n": "1m_BTC_USD",
      "a": "314732.87412"
    }
  ]
}

# 取消订阅

取消订阅指定市场 K 线信息

# 请求参数

channel

futures.candlesticks
event

unsubscribe

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send(
  '{"time" : 123456, "channel" : "futures.candlesticks", "event": "unsubscribe", "payload" : ["1m", "BTC_USD"]}')
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545445847,
  "time_ms": 1545445847123,
  "channel": "futures.candlesticks",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 合约统计信息频道

contract_stats 通道允许您获取合约统计信息

# 订阅操作

订阅合约统计信息

# 请求参数

channel

futures.contract_stats
event

subscribe
params

名称类型必选描述

contract String Yes 合约名称

interval String Yes Interval : "1s", "10s", "1m", "5m", "15m", "30m", "1h", "4h", "8h", "1d", "7d"

名称	类型	必选	描述
`contract`	String	Yes	合约名称
`interval`	String	Yes	Interval : "1s", "10s", "1m", "5m", "15m", "30m", "1h", "4h", "8h", "1d", "7d"

from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
ws.send('{"time" : 123456, "channel" : "futures.contract_stats",
    "event": "subscribe", "payload" : ["BTC_USD","10s"]}')
print(ws.recv())

上面的订阅请求返回 JSON 结构如下:

{
  "time": 1545404023,
  "time_ms": 1545404023123,
  "channel": "futures.contract_stats",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# contract_stats 推送

合约统计信息推送

# 推送参数

channel

futures.contract_stats
event

update

params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`time`	Integer	统计时间（时间戳）
`contract`	string	合约名称
`mark_price`	Float	当前标记价格
`lsr_taker`	Float	多空吃单比
`lsr_account`	Float	多空持仓用户比
`long_liq_size`	Integer	做多爆仓量（张）
`long_liq_amount`	Float	做多爆仓量（交易币种）
`long_liq_usd`	Float	做多爆仓量（计价币种）
`short_liq_size`	Integer	做空爆仓量（张）
`short_liq_amount`	Float	做空爆仓量（交易币种）
`short_liq_usd`	Float	做空爆仓量（计价币种）
`open_interest`	Integer	总持仓量（张）
`open_interest_usd`	Float	总持仓量（计价币种）
`top_lsr_account`	Float	大户多空账户比
`top_lsr_size`	Float	大户多空持仓比

{
  "time": 1541659086,
  "time_ms": 1541659086123,
  "channel": "futures.contract_stats",
  "event": "update",
  "result": [
    {
      "time": 1603865400,
      "contract":"BTC_USDT",
      "lsr_taker": 100,
      "lsr_account": 0.5,
      "long_liq_size": 0,
      "short_liq_size": 0,
      "open_interest": 124724,
      "short_liq_usd": 0,
      "mark_price": "8865",
      "top_lsr_size": 1.02,
      "short_liq_amount": 0,
      "long_liq_amount": 0,
      "open_interest_usd": 1511,
      "top_lsr_account": 1.5,
      "long_liq_usd": 0
    }
  ]
}

# 取消订阅

取消订阅

# 请求参数

channel

futures.contract_stats
event

unsubscribe
params

名称类型必选描述

contract String Yes 合约名称

interval String Yes Interval : "1s", "10s", "1m", "5m", "15m", "30m", "1h", "4h", "8h", "1d", "7d"

名称	类型	必选	描述
`contract`	String	Yes	合约名称
`interval`	String	Yes	Interval : "1s", "10s", "1m", "5m", "15m", "30m", "1h", "4h", "8h", "1d", "7d"

注意：contract为unsub_all，表示全部取消

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.contract_stats",
    "event": "unsubscribe",
    "payload": ["BTC_USD","10s"]
}
ws.send(json.dumps(req))
print(ws.recv())

上面的请求返回 JSON 结构如下:

{
  "time": 1545404900,
  "time_ms": 1545404900123,
  "channel": "futures.contract_stats",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 订单频道

提供接收用户订单的推送

WARNING

需要认证.

# 订单订阅

如果您想订阅所有合约中的订单更新，请在合约列表中使用 !all。

订阅订单更新推送

# 请求参数

channel

futures.orders
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.orders",
  "event": "subscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.orders",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 订单推送

下单、更新或完成时通知用户订单信息

# 推送参数

channel

futures.orders
event

update
params

推送结果参数含义请参考http接口.

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`create_time`	Integer	订单创建时间（已弃用）
`create_time_ms`	Integer	订单创建时间戳（以毫秒为单位）
`fill_price`	Float	订单成交价格
`finish_as`	String	订单是如何完成的。 - `filled`：全部成交 - `cancelled`：手动取消 - `liquidated`：因清算而取消 - `ioc`：生效时间为 IOC，立即完成 - `auto_deleveraging`：ADL 完成 - `reduce_only`：因减仓设置而增仓而取消 - `position_close`：因平仓而取消 - `stp`：订单发生自成交限制而被撤销 - `_new`：新建 - `_update`：成交或部分成交或更新订单 - `reduce_out`: 只减仓被排除的不容易成交的挂单
`iceberg`	Integer	冰山下单显示的数量，不指定或传 0 都默认为普通下单。目前不支持全部冰山。
`id`	Integer	订单 ID
`is_close`	Bool	该订单是否为 close position
`is_liq`	Bool	该订单是否为 liquidation
`left`	Integer	剩余可交易数量
`mkfr`	Float	Maker 费用
`is_reduce_only`	Bool	该订单是否为 reduce-only
`status`	String	订单状态 - open: 等待交易 - finished: 完成
`tkfr`	Float	taker 费用
`price`	Float	订单价格。 0 表示市价订单，tif 设置为 ioc
`refu`	Integer	推荐用户 ID
`refr`	Float
`size`	Integer	订单大小。指定正数进行出价，指定负数进行询问
`text`	String	用户定义的信息
`tif`	String	有效时间 - gtc：GoodTillCancelled - ioc：ImmediateOrCancelled，仅接受者 - poc：PendingOrCancelled，只进行后订单，始终享受挂单费用 - fok： FillOrKill，完全填充或不填充 type=market 时仅支持 ioc 和 fok
`finish_time`	Integer	订单更新 unix 时间戳（以秒为单位）
`finish_time_ms`	Integer	订单更新 unix 时间戳（以毫秒为单位）
`user`	String	用户 ID
`contract`	String	合约名称
`stp_id`	String	同一 stp_id 组内的用户之间的订单不允许自交易 1.如果匹配的两个订单的 stp_id 非零且相等，则不会被执行。而是根据 taker 的 stp_act 执行相应的策略。 2.对于未设置 STP 组的订单，stp_id 默认返回 0
`stp_act`	String	自我交易预防行动。用户可以通过该字段设置自我交易防范策略 1.用户加入 STP Group 后，可以通过 stp_act 来限制用户的自我交易防范策略。如果不传 stp_act，则默认为 cn 策略。 2.当用户没有加入 STP 组时，传递 stp_act 参数时会返回错误。 3.如果用户下单时没有使用'stp_act'，'stp_act'将返回'-' - cn: 取消最新订单，取消新订单并保留旧订单 - co: 取消最旧订单，取消旧订单并保留新订单 - cb：取消两者，新旧订单都会被取消
`amend_text`	String	用户修改订单时备注的自定义数据

{
  "channel": "futures.orders",
  "event": "update",
  "time": 1541505434,
  "time_ms": 1541505434123,
  "result": [
    {
      "contract": "BTC_USD",
      "create_time": 1628736847,
      "create_time_ms": 1628736847325,
      "fill_price": 40000.4,
      "finish_as": "filled",
      "finish_time": 1628736848,
      "finish_time_ms": 1628736848321,
      "iceberg": 0,
      "id": 4872460,
      "is_close": false,
      "is_liq": false,
      "is_reduce_only": false,
      "left": 0,
      "mkfr": -0.00025,
      "price": 40000.4,
      "refr": 0,
      "refu": 0,
      "size": 1,
      "status": "finished",
      "text": "-",
      "tif": "gtc",
      "tkfr": 0.0005,
      "user": "110xxxxx"
    }
  ]
}

# 取消订阅

取消订阅订单更新通知

# 请求参数

channel

futures.orders
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.orders",
  "event": "unsubscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.orders",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 用户私有成交频道

提供接收用户交易的方式

WARNING

需要认证

# 用户私有成交订阅

如果您想订阅所有的市场交易更新，请在请求参数列表中使用!all。

订阅私有成交更新

# 请求参数

channel

futures.usertrades
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.usertrades",
  "event": "subscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.usertrades",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 用户私有成交推送

推送用户私有成交更新

# 推送参数

channel

futures.usertrades
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`contract`	String	合约名称
`create_time`	Integer	创建时间
`create_time_ms`	Integer	创建时间（以毫秒为单位）
`id`	String	交易 ID
`order_id`	String	订单 ID
`price`	String	交易价格
`size`	Integer	交易数量
`role`	String	用户角色 (maker/taker)
`text`	String	用户自定义信息
`fee`	Float	手续费
`point_fee`	Float	点卡手续费

{
  "time": 1543205083,
  "time_ms": 1543205083123,
  "channel": "futures.usertrades",
  "event": "update",
  "result": [
    {
      "id": "3335259",
      "create_time": 1628736848,
      "create_time_ms": 1628736848321,
      "contract": "BTC_USD",
      "order_id": "4872460",
      "size": 1,
      "price": "40000.4",
      "role": "maker",
      "text": "api",
      "fee": 0.0009290592,
      "point_fee": 0
    }
  ]
}

# 取消订阅

取消私有成交订阅

# 请求参数

channel

futures.usertrades
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.usertrades",
  "event": "unsubscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.usertrades",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 强制平仓频道

提供一种接收用户强制平仓信息的方式

WARNING

需要认证

# 清算订阅

如果您想订阅所有合约中的强制平仓推送，请在订阅请求列表中使用 !all

订阅用户强制平仓推送

# 请求参数

channel

futures.liquidates
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.liquidates",
  "event": "subscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.liquidates",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 强制平仓推送

推送强制平仓更新

# 推送参数

channel

futures.liquidates
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`entry_price`	Float	平均入场价
`fill_price`	Float	平均执行价格
`leverage`	Float	杠杆大小
`liq_price`	Float	清算价格
`margin`	Float	Margin
`mark_price`	Float	标记价格
`order_id`	Integer	订单 ID
`order_price`	Float	订单价格
`left`	Integer	订单未完成数量
`size`	Integer	原始订单数量
`time`	Integer	时间
`time_ms`	Integer	时间（以毫秒为单位）
`user`	String	用户 ID
`contract`	String	合约名称

{
  "channel": "futures.liquidates",
  "event": "update",
  "time": 1541505434,
  "time_ms": 1541505434123,
  "result": [
    {
      "entry_price": 209,
      "fill_price": 215.1,
      "left": 0,
      "leverage": 0.0,
      "liq_price": 213,
      "margin": 0.007816722941,
      "mark_price": 213,
      "order_id": 4093362,
      "order_price": 215.1,
      "size": -124,
      "time": 1541486601,
      "time_ms": 1541486601123,
      "contract": "BTC_USD",
      "user": "1040xxxx"
    }
  ]
}

# 取消订阅

取消订阅清算更新

# 请求参数

channel

futures.liquidates
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.liquidates",
  "event": "unsubscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.liquidates",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 自动减仓频道

提供一种接收用户自动减仓信息的方法

WARNING

需要认证

# 自动减仓订阅

如果您想订阅所有合约的自动减仓更新，请在请求参数列表中使用!all

订阅用户自动减仓更新

# 请求参数

channel

futures.auto_deleverages
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.auto_deleverages",
  "event": "subscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.auto_deleverages",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 自动减仓推送

自动减仓消息

# 推送参数

channel

futures.auto_deleverages
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`entry_price`	Float	入场价格
`fill_price`	Float	执行价格
`position_size`	Integer	持仓规模
`trade_size`	Integer	交易数量
`time`	Integer	时间
`time_ms`	Integer	时间（以毫秒为单位）
`user`	String	用户 ID
`contract`	String	合约名称

{
  "channel": "futures.auto_deleverages",
  "event": "update",
  "time": 1541505434,
  "time_ms": 1541505434123,
  "result": [
    {
      "entry_price": 209,
      "fill_price": 215.1,
      "position_size": 10,
      "trade_size": 10,
      "time": 1541486601,
      "time_ms": 1541486601123,
      "contract": "BTC_USD",
      "user": "1040"
    }
  ]
}

# 取消订阅

取消订阅自动减仓

# 请求参数

channel

futures.auto_deleverages
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.auto_deleverages",
  "event": "unsubscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下：

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.auto_deleverages",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 平仓频道

提供一种接收用户仓位平仓信息的方法

WARNING

需要认证

# 平仓订阅

如果您想订阅所有合约的平仓更新，请在合约列表中使用 !all

订阅用户平仓信息更新

# 请求参数

channel

futures.position_closes
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
  "time": 123456,
  "channel": "futures.position_closes",
  "event": "subscribe",
  "payload": ["20011", "BTC_USD"],
  "auth": {
    "method": "api_key",
    "KEY": "xxxx",
    "SIGN": "xxxx"
  }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.position_closes",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 平仓信息推送

平仓信息推送

# 推送参数

channel

futures.position_closes
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`contract`	String	合约名称
`pnl`	Number	利润损失
`side`	String	方向 (long or short)
`text`	String	附带信息
`time`	Integer	时间
`time_ms`	Integer	时间（以毫秒为单位）
`user`	String	用户 ID

{
  "channel": "futures.position_closes",
  "event": "update",
  "time": 1541505434,
  "time_ms": 1541505434123,
  "result": [
    {
      "contract": "BTC_USD",
      "pnl": -0.000624354791,
      "side": "long",
      "text": "web",
      "time": 1547198562,
      "time_ms": 1547198562123,
      "user": "211xxxx"
    }
  ]
}

# 取消订阅

取消订阅平仓更新

# 请求参数

channel

futures.position_closes
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.position_closes",
    "event": "unsubscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.position_closes",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 余额频道

提供一种接收用户余额信息的方法

WARNING

需要认证

# 余额信息订阅

订阅用户余额更新

# 请求参数

channel

futures.balances
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.balances",
    "event": "subscribe",
    "payload": ["20011"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.balances",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 余额更新推送

通知余额更新信息

# 推送参数

channel

futures.balances
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`balance`	Number	余额最终数量
`change`	Number	余额变化数量
`text`	String	附带信息
`time`	Integer	时间
`time_ms`	Integer	时间（以毫秒为单位）
`type`	String	类型
`user`	String	用户 ID
`currency`	String	币种

{
  "channel": "futures.balances",
  "event": "update",
  "time": 1541505434,
  "time_ms": 1541505434123,
  "result": [
    {
      "balance": 9.998739899488,
      "change": -0.000002074115,
      "text": "BTC_USD:3914424",
      "time": 1547199246,
      "time_ms": 1547199246123,
      "type": "fee",
      "user": "211xxx",
      "currency": "btc"
    }
  ]
}

# 取消订阅

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.balances",
    "event": "unsubscribe",
    "payload": ["20011"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.balances",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 降低风险率频道

推送用户降低风险率信息

WARNING

需要认证

# 降低风险率订阅

如果您想订阅所有合约的降低风险率更新，请在合约列表中使用 !all。

订阅用户降低风险率更新

# 请求参数

channel

futures.reduce_risk_limits
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.reduce_risk_limits",
    "event": "subscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.reduce_risk_limits",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 降低风险率推送

通知降低风险限制更新

# 推送参数

channel

futures.reduce_risk_limits
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`cancel_orders`	Integer	Cancel orders
`contract`	String	合约名称
`leverage_max`	Integer	最大杠杆
`liq_price`	Float	清算价格
`maintenance_rate`	Float	Maintenance rate
`risk_limit`	Integer	风险限额
`time`	Integer	时间
`time_ms`	Integer	时间（以毫秒为单位）
`user`	String	用户 ID

{
  "time": 1551858330,
  "time_ms": 1551858330123,
  "channel": "futures.reduce_risk_limits",
  "event": "update",
  "result": [
    {
      "cancel_orders": 0,
      "contract": "ETH_USD",
      "leverage_max": 10,
      "liq_price": 136.53,
      "maintenance_rate": 0.09,
      "risk_limit": 450,
      "time": 1551858330,
      "time_ms": 1551858330123,
      "user": "20011"
    }
  ]
}

# 取消订阅

退订降低风险限制更新

# 请求参数

channel

futures.reduce_risk_limits
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.reduce_risk_limits",
    "event": "unsubscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

# 仓位频道

提供一种接收用户仓位信息的方法

WARNING

需要认证

# 仓位订阅

如果您想订阅所有合约的持仓更新，请在合约列表中使用 !all

订阅用户仓位更新

# 请求参数

channel

futures.positions
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.positions",
    "event": "subscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.positions",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 仓位信息推送

推送仓位更新.

# 推送参数

channel

futures.positions
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`contract`	String	合约名称
`entry_price`	Float	开仓价格
`history_pnl`	Float	已平仓的仓位总盈亏
`history_point`	Float	已平仓的点卡总盈亏
`last_close_pnl`	Float	最近一次平仓的盈亏
`leverage`	Integer	杠杆倍数，0代表全仓，正数代表逐仓
`leverage_max`	Integer	当前风险限额下，允许的最大杠杆倍数
`liq_price`	Float	爆仓价格
`maintenance_rate`	Float	当前风险限额下，维持保证金比例
`margin`	Float	保证金
`realised_pnl`	Float	已实现盈亏
`realised_point`	Float	点卡已实现盈亏
`risk_limit`	Integer	风险限额
`size`	Integer	合约 size
`time`	Integer	更新 unix 时间戳
`time_ms`	Integer	更新 unix 时间戳（以毫秒为单位）
`user`	String	用户 ID
`update_id`	Integer	消息序列号，每次推送 order 之后会自增 1

{
  "time": 1588212926,
  "time_ms": 1588212926123,
  "channel": "futures.positions",
  "event": "update",
  "result": [
    {
      "contract": "BTC_USD",
      "cross_leverage_limit": 0,
      "entry_price": 40000.36666661111,
      "history_pnl": -0.000108569505,
      "history_point": 0,
      "last_close_pnl": -0.000050123368,
      "leverage": 0,
      "leverage_max": 100,
      "liq_price": 0.1,
      "maintenance_rate": 0.005,
      "margin": 49.999890611186,
      "mode": "single",
      "realised_pnl": -1.25e-8,
      "realised_point": 0,
      "risk_limit": 100,
      "size": 3,
      "time": 1628736848,
      "time_ms": 1628736848321,
      "user": "110xxxxx",
      "update_id": 170919
    }
  ]
}

# 取消订阅

取消订阅仓位更新

# 请求参数

channel

futures.positions
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.positions",
    "event": "unsubscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.positions",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 自动订单频道

提供一种接收用户自动订单信息的方法

WARNING

需要认证

# 自动订单订阅

如果您想订阅所有合约中的自动订单更新，请在合约列表中使用!all

订阅用户自动订单更新

# 请求参数

channel

futures.autoorders
event

subscribe
params

名称	类型	必选	描述
`user id`	String	是	用户 ID
`contract`	String	是	合约名称

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.autoorders",
    "event": "subscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }
}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.autoorders",
  "event": "subscribe",
  "result": {
    "status": "success"
  }
}

# 自动订单消息推送

通知自动订单更新

# 推送参数

channel

futures.autoorders
event

update
params

名称	类型	描述
`result`	Array	Array of objects

名称	类型	描述
`user`	Number	用户 ID
`trigger`	Object
`initial`	Object
`id`	Number	自动订单 ID
`trade_id`	Number	交易 ID
`status`	String	订单状态
`reason`	String	变更原因
`create_time`	Number	创建时间
`name`	String	名称
`is_stop_order`	boolean	是否停止
`stop_trigger`	Object
`order_type`	String	止盈/止损类型，详情参见 http api
`me_order_id`	Number	订单止盈/止损对应订单 ID.

{
  "time": 1596798126,
  "time_ms": 1596798126123,
  "channel": "futures.autoorders",
  "event": "update",
  "result": [
    {
      "user": 123456,
      "trigger": {
        "strategy_type": 0,
        "price_type": 0,
        "price": "10000",
        "rule": 2,
        "expiration": 86400
      },
      "initial": {
        "contract": "BTC_USDT",
        "size": 10,
        "price": "10000",
        "tif": "gtc",
        "text": "web",
        "iceberg": 0,
        "is_close": false,
        "is_reduce_only": false,
        "auto_size": ""
      },
      "id": 9256,
      "trade_id": 0,
      "status": "open",
      "reason": "",
      "create_time": 1596798126,
      "name": "price_autoorders",
      "is_stop_order": false,
      "stop_trigger": {
        "rule": 0,
        "trigger_price": "",
        "order_price": ""
      },
      "order_type": "close-long-order",
      "me_order_id": "213867453823"
    }
  ]
}

# 取消订阅

取消订阅自动订单更新

# 请求参数

channel

futures.autoorders
event

unsubscribe

import json
from websocket import create_connection

ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/btc")
req = {
    "time": 123456,
    "channel": "futures.autoorders",
    "event": "unsubscribe",
    "payload": ["20011", "BTC_USD"],
    "auth": {
        "method": "api_key",
        "KEY": "xxxx",
        "SIGN": "xxxx"
    }}
ws.send(json.dumps(req))
print(ws.recv())

上面的命令返回 JSON 结构如下:

{
  "time": 1545459681,
  "time_ms": 1545459681123,
  "channel": "futures.autoorders",
  "event": "unsubscribe",
  "result": {
    "status": "success"
  }
}

# 账户交易 API

# Websocket 交易 API

WebSocket API 允许通过 WebSocket 连接下单、取消、修改、查询订单.

# Websocket API 客户端请求

客户端发起的 api 请求遵循通用的 JSON 格式，包含以下字段:

名称	类型	必选	描述
`time`	Integer	是	请求时间（以秒为单位）。请求时间和服务器时间之间的差距不得超过 60 秒
`id`	Integer	否	可选的请求 ID，将由服务器发回，以帮助您识别服务器响应哪个请求
`channel`	String	是	要访问的 WebSocket 频道
`event`	String	是	固定为 `api`
`payload`	Object	是	可选请求详细参数
»`req_id`	String	是	消息的唯一标识符由客户端提供，将在响应消息中返回，用于标识相应的请求。
»`timestamp`	String	是	签名时间（秒）
»`api_key`	String	是	Gate APIv4 APIKey
»`signature`	String	是	使用 GateAPIv4 密钥和请求信息生成的身份验证签名，详细信息请参见[Websocket API 身份验证](#Websocket API 身份验证)部分
»`req_param`	[]Byte	是	请求 api 参数

请注意，payload.req_param 的类型是与频道（channel字段）绑定的，频道不同payload.req_param 的字段也不同，以 futures.order_place 为例，payload.req_param 与 apiv4 /futures/{settle}/orders (opens new window)。例如，您可以对 BTC_USDT 下限价单

请求示例

package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"crypto/tls"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"github.com/gorilla/websocket"
	"net/url"
	"strconv"
	"time"
)

func GetApiSignature(secret, channel string, requestParam []byte, ts int64) string {
	hash := hmac.New(sha512.New, []byte(secret))
	key := fmt.Sprintf("%s\n%s\n%s\n%d", "api", channel, string(requestParam), ts)
	hash.Write([]byte(key))
	return hex.EncodeToString(hash.Sum(nil))
}

func main() {

	// 1. login
	apiKey := "xxxxx"
	secret := "xxxxx"
	requestParam := ""
	channel := "futures.login"
	ts := time.Now().Unix()
	requestId := fmt.Sprintf("%d-%d", time.Now().UnixMilli(), 1)

	req := ApiRequest{
		Time:    ts,
		Channel: "futures.login",
		Event:   "api",
		Payload: ApiPayload{
			ApiKey:       apiKey,
			Signature:    GetApiSignature(secret, channel, []byte(requestParam), ts),
			Timestamp:    strconv.FormatInt(ts, 10),
			RequestId:    requestId,
			RequestParam: []byte(requestParam),
		},
	}

	fmt.Println(GetApiSignature(secret, channel, []byte(requestParam), ts))
	marshal, _ := json.Marshal(req)
	fmt.Println(string(marshal))

	// connect the ws
	u := url.URL{Scheme: "ws", Host: "xx.xx.xxx.xx:xxx", Path: "xxx"}
	websocket.DefaultDialer.TLSClientConfig = &tls.Config{RootCAs: nil, InsecureSkipVerify: true}
	c, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
	if err != nil {
		panic(err)
	}
	c.SetPingHandler(nil)

	// read msg
	go func() {
		for {
			_, message, err := c.ReadMessage()
			if err != nil {
				c.Close()
				panic(err)
			}
			fmt.Printf("recv: %s\n", message)
		}
	}()

	err = c.WriteMessage(websocket.TextMessage, marshal)

	//ws create an order
	orderParam := orderParam{
		Contract: "BTC_USDT",
		size:     6024,
		Iceberg:  0,
		Price:    "3765",
		Tif:      "gtc",
		Text:     "t-my-custom-id",
		Stp_act:  "-",
	}
	orderParamBytes, _ := json.Marshal(orderParam)

	order_place := ApiRequest{
		Time:    ts,
		Channel: "futures.order_place",
		Event:   "api",
		Payload: ApiPayload{
			RequestId:    requestId,
			RequestParam: []byte(orderParamBytes),
		},
	}
	orderReqByte, _ := json.Marshal(order_place)
	err = c.WriteMessage(websocket.TextMessage, orderReqByte)

	if err != nil {
		panic(err)
	}

	select {}
}

type ApiRequest struct {
	App     string     `json:"app,omitempty"`
	Time    int64      `json:"time"`
	Id      *int64     `json:"id,omitempty"`
	Channel string     `json:"channel"`
	Event   string     `json:"event"`
	Payload ApiPayload `json:"payload"`
}
type ApiPayload struct {
	ApiKey       string          `json:"api_key,omitempty"`
	Signature    string          `json:"signature,omitempty"`
	Timestamp    string          `json:"timestamp,omitempty"`
	RequestId    string          `json:"req_id,omitempty"`
	RequestParam json.RawMessage `json:"req_param,omitempty"`
}

type OrderParam struct {
	Contract   string `json:"Contract,contract"`
	Size       int64  `json:"size,omitempty"`
	Iceberg    int64  `json:"iceberg,omitempty"`
	Price      string `json:"price,omitempty"`
	Close      bool   `json:"close,omitempty"`
	ReduceOnly bool   `json:"reduce_only,omitempty"`
	Tif        string `json:"tif,omitempty"`
	Text       string `json:"text,omitempty"`
	AutoSize   string `json:"auto_size,omitempty"`
	StpAct     bool   `json:"stp_act,omitempty"`
}

{
  "time": 1680772890,
  "channel": "futures.order_place",
  "event": "api",
  "payload": {
    "req_id": "xxxx",
    "req_param": {
      "contract": "BTC_USDT",
      "size": 10,
      "price": "80048.240000",
      "tif": "gtc",
      "text": "t-my-custom-id"
    }
  }
}

# Websocket API 服务响应

服务器响应包括对客户端请求的 ack 响应和 api 结果消息推送。服务器响应遵循通用的 JSON 格式，其中包含以下字段:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`x_gate_ratelimit_requests_remain`	Integer	(仅涉及下单/改单/撤单)当前时间窗口剩余可用请求数(为0不展示)
»`x_gate_ratelimit_limit`	Integer	(仅涉及下单/改单/撤单)当前频率限制上限(为0不展示)
»`x_gat_ratelimit_reset_timestamp`	Integer	(仅涉及下单/改单/撤单)已超过当前窗口频率限制，表示下个可用时间窗口的时间戳（毫秒），即什么时候可以恢复访问；未超过当前窗口频率限制，表示返回的是当前服务器时间（毫秒）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
`data`	Object	请求响应的数据
»`result`	Object	如果这是 ack 响应，则结果是请求的`payload`，否则结果是 api 的响应
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

服务器回声确认响应示例（目前仅在下单请求中有回声响应）

{
  "request_id": "request-id-1",
  "ack": true,
  "header": {
    "response_time": "1681195121499",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140031563c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gate_ratelimit_reset_timestamp": 1681195121499
  },
  "data": {
    "result": {
      "req_id": "request-id-1",
      "req_param": {
        "contract": "BTC_USDT",
        "size": 10,
        "price": "31503.280000",
        "tif": "gtc",
        "text": "t-my-custom-id"
      }
    }
  }
}

服务器 API 响应示例

{
  "request_id": "request-id-1",
  "ack": false,
  "header": {
    "response_time": "1681195121639",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140031563c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gate_ratelimit_reset_timestamp": 1681195121639
  },
  "data": {
    "result": {
      "id": 74046511,
      "user": 6790020,
      "create_time": 1681195121.754,
      "finish_time": 1681195121.754,
      "finish_as": "filled",
      "status": "finished",
      "contract": "BTC_USDT",
      "size": 10,
      "price": "31503.3",
      "tif": "gtc",
      "fill_price": "31500",
      "text": "t-my-custom-id",
      "tkfr": "0.0003",
      "mkfr": "0",
      "stp_id": 2,
      "stp_act": "cn",
      "amend_text": "-"
    }
  }
}

# 错误

错误响应详情具有以下格式:

名称	类型	描述
`label`	String	错误类型
`message`	String	详细错误信息

限频相关的错误码说明:

错误码	描述
`100`	限流内部异常错误
`311`	合约限流
`312`	合约引擎限流

错误响应通知示例

{
  "request_id": "request-id-1",
  "ack": false,
  "header": {
    "response_time": "1681195360034",
    "status": "401",
    "channel": "futures.login",
    "event": "api",
    "client_id": "::1-0x140001a2600",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d"
  },
  "data": {
    "errs": {
      "label": "INVALID_KEY",
      "message": "Invalid key provided"
    }
  }
}

Error 推送示例（限速）

{
  "request_id": "xxxx",
  "header": {
    "response_time": "1677816784084",
    "status": "429",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x14002ba2300",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_limit": 100,
    "x_gate_ratelimit_reset_timestamp": 1677816785084
  },
  "data": {
    "errs": {
      "label": "TOO_MANY_REQUESTS",
      "message": "Request Rate limit Exceeded (311)"
    }
  }
}

# 登陆

WARNING

注意：您使用的 GateAPIv4 密钥对必须具有合约账户对应的权限（例如：order-place 频道必须具有合约账户写入权限），如果启用了密钥的白名单，则您的出站 IP 地址必须在密钥的 IP 白名单中.

# 登录请求

客户端 API 请求

payload参数:

名称	类型	必选	描述
`req_id`	`string`	是	请求 id，将由服务器发回，以帮助您识别服务器响应哪个请求，它与外部的`id`不同
`api_key`	`string`	是	Apiv4 key
`req_header`	`object`	是	Apiv4 自定义 header
`signature`	`string`	是	Apiv4 签名
`timestamp`	`string`	是	Unix 时间戳（以秒为单位）

WebSocket api 操作认证使用与 Gate APIv4 API 相同的签名计算方法，即 HexEncode(HMAC_SHA512(secret,signature_string))，但有以下区别：

签名字符串拼接方式：<event>\n<channel>\n<req_param>\n<timestamp>, 其中<event>、<channel>、<req_param>、<timestamp>是对应的请求信息
login频道中的 req_param始终为空字符串
身份验证信息在请求正文中的payload字段中发送。

代码示例

package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"crypto/tls"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"github.com/gorilla/websocket"
	"net/url"
	"strconv"
	"time"
)

func GetApiSignature(secret, channel string, requestParam []byte, ts int64) string {
	hash := hmac.New(sha512.New, []byte(secret))
	key := fmt.Sprintf("%s\n%s\n%s\n%d", "api", channel, string(requestParam), ts)
	hash.Write([]byte(key))
	return hex.EncodeToString(hash.Sum(nil))
}

// example WebSocket signature calculation implementation in go
func main() {
	apiKey := "YOUR_API_KEY"
	secret := "YOUR_API_SECRET"
	requestParam := ""
	channel := "futures.login"
	ts := time.Now().Unix()
	requestId := fmt.Sprintf("%d-%d", time.Now().UnixMilli(), 1)

	req := ApiRequest{
		Time:    ts,
		Channel: "",
		Event:   "api",
		Payload: ApiPayload{
			ApiKey:       apiKey,
			Signature:    GetApiSignature(secret, channel, []byte(requestParam), ts),
			Timestamp:    strconv.FormatInt(ts, 10),
			RequestId:    requestId,
			RequestParam: []byte(requestParam),
		},
	}

	fmt.Println(GetApiSignature(secret, channel, []byte(requestParam), ts))

	marshal, _ := json.Marshal(req)
	fmt.Println(string(marshal))

	// connect the ws
	u := url.URL{Scheme: "ws", Host: "xx.xx.xxx.xx:xxx", Path: "xxx"}
	websocket.DefaultDialer.TLSClientConfig = &tls.Config{RootCAs: nil, InsecureSkipVerify: true}
	c, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
	if err != nil {
		panic(err)
	}
	c.SetPingHandler(nil)

	// read msg
	go func() {
		for {
			_, message, err := c.ReadMessage()
			if err != nil {
				c.Close()
				panic(err)
			}
			fmt.Printf("recv: %s\n", message)
		}
	}()

	err = c.WriteMessage(websocket.TextMessage, marshal)
	if err != nil {
		panic(err)
	}

	select {}
}

type ApiRequest struct {
	App     string     `json:"app,omitempty"`
	Time    int64      `json:"time"`
	Id      *int64     `json:"id,omitempty"`
	Channel string     `json:"channel"`
	Event   string     `json:"event"`
	Payload ApiPayload `json:"payload"`
}
type ApiPayload struct {
	ApiKey       string          `json:"api_key,omitempty"`
	Signature    string          `json:"signature,omitempty"`
	Timestamp    string          `json:"timestamp,omitempty"`
	RequestId    string          `json:"req_id,omitempty"`
	RequestParam json.RawMessage `json:"req_param,omitempty"`
}

请求示例

{
  "time": 1681984544,
  "channel": "futures.login",
  "event": "api",
  "payload": {
    "api_key": "ea83fad2604399da16bf97e6eea772a6",
    "signature": "6fa3824c8141f2b2283108558ec50966d7caf749bf04a3b604652325b50b47d2343d569d848373d58e65c49d9622ba2e73dc25797abef11c9f20c07da741591e",
    "timestamp": "1681984544",
    "req_id": "request-1"
  }
}

# 登录响应

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
`data`	Object	请求响应的数据
»`result`	Object	如果这是 ack 响应，则结果是请求的`payload`，否则结果是 api 的响应
»»`api_key`	String	登录成功的 apikey
»»`uid`	String	登录成功的用户 ID
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

登录响应示例

{
  "request_id": "request-1",
  "header": {
    "response_time": "1681985856666",
    "status": "200",
    "channel": "futures.login",
    "event": "api",
    "clientId": "",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d"
  },
  "data": {
    "result": {
      "api_key": "ea83fad2604399da16bf97e6eea772a6",
      "uid": "110284739"
    }
  }
}

# 下单

futures.order_place

您可以通过此频道进行下单操作.

本频道和以下的 APIV4 功能相同:

POST /futures/{
  settle
}/orders

# 下单请求

payload参数:

名称	类型	必选	描述
`req_id`	`string`	是	Request id which will be sent back by the server to help you identify which request the server responds to, it's different from outside's`id`
`req_param`	`object`	是	使用 api 下单参数； api 下单参数详细信息api (opens new window)
`req_header`	`object`	否	Apiv4 自定义请求头

req_param API 订单模型的 JSON 字节数据:

字段	类型	必选	描述
`contract`	`string`	是	合约
`size`	`int64`	是	订单大小。指定正数进行出价，指定负数进行询问
`iceberg`	`int64`	是	冰山订单的显示尺寸。0 表示非冰山。请注意，您需要支付隐藏尺寸的接受者费用
`price`	`string`	否	订单价格。0 表示市价订单，`tif`设置为`ioc`
`close`	`bool`	否	设置为`true`平仓，`size`设置为 0
`reduce_only`	`bool`	否	设置为`true`仅减少订单
`tif`	`string`	否	有效时间
`text`	`string`	否	用户定义的信息。如果不为空，则必须遵循以下规则：
`auto_size`	`string`	否	将侧面设置为关闭双模式位置。`close_long`闭合长边；而`close_short`短的。注意`size`还需要设置为 0
`stp_act`	`string`	否	自我交易预防行动。用户可以通过该字段设置自助交易防范策略

req_header 自定义 header 数据:

字段	类型	必选	描述
`x-gate-exptime`	`string`	否	指定过期的时间戳（毫秒）。如果 ws 收到请求的时间大于过期时间，请求将被拒绝

# 详细描述

tif: 有效时间

gtc：取消前有效
ioc: ImmediateOrCancelled, 仅接受者
poc：PendingOrCancelled，仅发布订单，始终享受挂单费用
fok：FillOrKill，完全填充或不填充

text: 订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

必须以 t- 开头
不计算 t- ，长度不能超过 28 字节
输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
不填，默认 apiv4-ws,来自 ws
web：来自网络
api：来自 API
app：来自手机
auto_deleveraging：来自 ADL
liquidation：来自清算
insurance：来自保险

stp_act：自我交易预防行动。用户可以通过该字段设置自助交易防范策略用户加入后STP Group，他可以通过stp_act限制用户的自我交易防范策略。如果stp_act不通过则默认为cn策略。当用户没有加入时STP group，传递参数时会返回错误stp_act。如果用户下单时没有使用stp_act，stp_act将返回-

cn：取消最新订单，取消新订单并保留旧订单
co：取消最旧的订单，取消旧订单并保留新订单
cb：取消两者，新旧订单都会被取消

代码示例 warn: 下单前要先登陆

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_place",
    "event": "api",
    "payload": {
        "req_header":{
            "x-gate-channel-id":"xxxx",
        },
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_order)
    }
))

print(ws.recv())

package main

import (
    "crypto/hmac"
    "crypto/sha512"
    "crypto/tls"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "github.com/gorilla/websocket"
    "net/url"
    "strconv"
    "time"
)

func main() {

	// warn: you should login first before order

	// connect the ws
	u := url.URL{Scheme: "ws", Host: "xx.xx.xxx.xx:xxx", Path: "xxx"}
	websocket.DefaultDialer.TLSClientConfig = &tls.Config{RootCAs: nil, InsecureSkipVerify: true}
	c, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
	if err != nil {
		panic(err)
	}
	c.SetPingHandler(nil)

	// read msg
	go func() {
		for {
			_, message, err := c.ReadMessage()
			if err != nil {
				c.Close()
				panic(err)
			}
			fmt.Printf("recv: %s\n", message)
		}
	}()

	err = c.WriteMessage(websocket.TextMessage, marshal)

	//ws create an order
	orderParam := orderParam{
		Contract: "BTC_USDT",
		size:     6024,
		Iceberg:  0,
		Price:    "3765",
		Tif:      "gtc",
		Text:     "t-my-custom-id",
		Stp_act:  "-",
	}
	orderParamBytes, _ := json.Marshal(orderParam)
	requestId := fmt.Sprintf("%d-%d", time.Now().UnixMilli(), 1)
	order_place := ApiRequest{
		Time:    time.Now().Unix(),
		Channel: "futures.order_place",
		Event:   "api",
		Payload: ApiPayload{
			RequestId:    requestId,
			RequestParam: []byte(orderParamBytes),
		},
	}
	orderReqByte, _ := json.Marshal(order_place)
	err = c.WriteMessage(websocket.TextMessage, orderReqByte)

	if err != nil {
		panic(err)
	}

	select {}
}

请求示例

{
  "time": 1681195484,
  "channel": "futures.order_place",
  "event": "api",
  "payload": {
    "req_id": "request-id-1",
    "req_param": {
      "contract": "BTC_USDT",
      "size": 10,
      "price": "31503.280000",
      "tif": "gtc",
      "text": "t-my-custom-id"
    }
  }
}

# 订单请求回声消息

订单确认回声通知示例

{
  "request_id": "request-id-1",
  "ack": true,
  "header": {
    "response_time": "1681195484268",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140001a2600",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": {
      "req_id": "request-id-1",
      "req_header": null,
      "req_param": {
        "contract": "BTC_USDT",
        "size": 10,
        "price": "31503.280000",
        "tif": "gtc",
        "text": "t-my-custom-id"
      }
    }
  }
}

# 下单结果通知

下单时返回订单信息响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`ack`	Bool	"ack"消息的返回表示 WebSocket 的确认消息(目前在下单接口中存在)。如果`ack`为 false(false 该字段不会出现在响应中)，则说明该消息是响应消息，可以判断请求是否成功<br / >通过检查`data.errs`。
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
»`x_gate_ratelimit_requests_remain`	Integer	当前时间窗口剩余可用请求数(为0不展示)
»`x_gate_ratelimit_limit`	Integer	当前频率限制上限(为0不展示)
»`x_gat_ratelimit_reset_timestamp`	Integer	已超过当前窗口频率限制，表示下个可用时间窗口的时间戳（毫秒），即什么时候可以恢复访问；未超过当前窗口频率限制，表示返回的是当前服务器时间（毫秒）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
`data`	Object	请求响应的数据
»`result`	Object	如果这是 ack 响应，则结果是请求的`payload`，否则结果是 api 的响应
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

响应返回示例

{
  "request_id": "request-id-1",
  "ack": false,
  "header": {
    "response_time": "1681195484360",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140001a2600",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": {
      "id": 74046514,
      "user": 6790020,
      "create_time": 1681195484.462,
      "finish_time": 1681195484.462,
      "finish_as": "filled",
      "status": "finished",
      "contract": "BTC_USDT",
      "size": 10,
      "price": "31503.3",
      "tif": "gtc",
      "fill_price": "31500",
      "text": "t-my-custom-id",
      "tkfr": "0.0003",
      "mkfr": "0",
      "stp_id": 2,
      "stp_act": "cn",
      "amend_text": "-"
    }
  }
}

# 批量下单

futures.order_batch_place

您可以通过该频道批量下单

本频道和以下的 APIV4 功能相同:

POST /futures/{
  settle
}/batch_orders

# 批量下单请求

payload 参数:

名称	类型	必选	描述
`req_id`	`string`	是	请求 id，服务器会发回，帮助你识别服务器响应的是哪个请求，它与外部的`id`不同
`req_param`	`object`	是	参考 api 批量下单的请求数组； api 批量下单详情 api (opens new window)
`req_header`	`object`	否	Apiv4 自定义 header

req_param API 订单模型的 JSON 字节数据可以参考单个下单，是多个单个下单数组，详情参考下单

req_header 自定义 header 数据:

字段	类型	必选	描述
`x-gate-exptime`	`string`	否	指定过期的时间戳（毫秒）。如果 ws 收到请求的时间大于过期时间，请求将被拒绝

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_batch_place",
    "event": "api",
    "payload": {
        "header":{
            "x-gate-channel-id":"xxxx",
        },
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_order)
    }
))

print(ws.recv())

请求示例

{
  "time": 1681196536,
  "channel": "futures.order_batch_place",
  "event": "api",
  "payload": {
    "req_id": "request-id-6",
    "req_param": [
      {
        "contract": "BTC_USDT",
        "size": 10,
        "price": "31403.180000",
        "tif": "gtc",
        "text": "t-my-custom-id"
      }
    ]
  }
}

# 批量下单确认通知

确认通知示例

{
  "request_id": "request-id-6",
  "ack": true,
  "header": {
    "response_time": "1681196536283",
    "status": "200",
    "channel": "futures.order_batch_place",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": {
      "req_id": "request-id-6",
      "req_header": null,
      "req_param": [
        {
          "contract": "BTC_USDT",
          "size": 10,
          "price": "31403.180000",
          "tif": "gtc",
          "text": "t-my-custom-id"
        }
      ]
    }
  }
}

# 批量下单结果通知

批量下单订单信息返回

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`ack`	Bool	"ack"消息的返回表示 WebSocket 的确认消息(目前在下单接口中存在)。如果`ack`为 false(false 该字段不会出现在响应中)，则说明该消息是响应消息，可以判断请求是否成功<br / >通过检查`data.errs`。
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
»`x_gate_ratelimit_requests_remain`	Integer	当前时间窗口剩余可用请求数(为0不展示)
»`x_gate_ratelimit_limit`	Integer	当前频率限制上限(为0不展示)
»`x_gat_ratelimit_reset_timestamp`	Integer	已超过当前窗口频率限制，表示下个可用时间窗口的时间戳（毫秒），即什么时候可以恢复访问；未超过当前窗口频率限制，表示返回的是当前服务器时间（毫秒）
`data`	Object	请求响应的数据
»`result`	Object	如果这是 ack 响应，则结果是请求的`payload`，否则结果是 api 的响应
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

响应返回示例

{
  "request_id": "request-id-6",
  "ack": false,
  "header": {
    "response_time": "1681196536532",
    "status": "200",
    "channel": "futures.order_batch_place",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": [
      {
        "succeeded": true,
        "id": 74046545,
        "user": 6790020,
        "create_time": 1681196536.592,
        "status": "open",
        "contract": "BTC_USDT",
        "size": 10,
        "price": "31403.2",
        "tif": "gtc",
        "left": 10,
        "fill_price": "0",
        "text": "t-my-custom-id",
        "tkfr": "0.0003",
        "mkfr": "0"
      }
    ]
  }
}

# 订单取消

futures.order_cancel

您可以通过此频道取消订单

本频道和以下的 APIV4 功能相同:

DELETE /futures/{
  settle
}/orders/{
  order_id
}

# 订单取消请求

payload 参数:

名称	类型	必选	描述
`req_id`	`string`	是	请求 id，服务器会发回，帮助你识别服务器响应的是哪个请求，它与外部的`id`不同
`req_param`	`object`	是	API 取消订单，详情至api (opens new window)
`req_header`	`object`	否	Apiv4 自定义请求头

req_param API 订单模型的 JSON 字节数据:

字段	类型	必选	描述
`order_id`	`string`	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 `text` 字段）。

req_header 自定义 header 数据:

字段	类型	必选	描述
`x-gate-exptime`	`string`	否	指定过期的时间戳（毫秒）。如果 ws 收到请求的时间大于过期时间，请求将被拒绝

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_cancel",
    "event": "api",
    "payload": {
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_cancel_order)
    }
))

print(ws.recv())

订单取消请求示例

{
  "time": 1681195485,
  "channel": "futures.order_cancel",
  "event": "api",
  "payload": {
    "req_id": "request-id-5",
    "req_param": {
      "order_id": "74046514"
    }
  }
}

# 订单取消通知

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
»`x_gate_ratelimit_requests_remain`	Integer	当前时间窗口剩余可用请求数(为0不展示)
»`x_gate_ratelimit_limit`	Integer	当前频率限制上限(为0不展示)
»`x_gat_ratelimit_reset_timestamp`	Integer	已超过当前窗口频率限制，表示下个可用时间窗口的时间戳（毫秒），即什么时候可以恢复访问；未超过当前窗口频率限制，表示返回的是当前服务器时间（毫秒）
`data`	Object	请求响应的数据
»`result`	Object	订单取消参数，详情至 api (opens new window)
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

订单取消返回示例

{
  "request_id": "request-id-5",
  "header": {
    "response_time": "1681196536282",
    "status": "200",
    "channel": "futures.order_cancel",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": {
      "id": 74046543,
      "user": 6790020,
      "create_time": 1681196535.01,
      "finish_time": 1681196536.343,
      "finish_as": "cancelled",
      "status": "finished",
      "contract": "BTC_USDT",
      "size": 10,
      "price": "31303.2",
      "tif": "gtc",
      "left": 10,
      "fill_price": "0",
      "text": "t-my-custom-id",
      "tkfr": "0.0003",
      "mkfr": "0",
      "stp_id": 2,
      "stp_act": "cn",
      "amend_text": "-"
    }
  }
}

# 取消匹配的未结束订单

futures.order_cancel_cp

您可以通过此渠道取消所有匹配的未结束的订单

本频道和以下的 APIV4 功能相同:

DELETE /futures/{
  settle
}/orders

# 请求

payload 参数:

名称	类型	必选	描述
`req_id`	string	是	请求 id，服务器会发回，帮助你识别服务器响应的是哪个请求，它与外部的`id`不同
`req_param`	object	是	详情至 api (opens new window)
`req_header`	`object`	否	Apiv4 自定义请求头

req_param API 订单模型的 JSON 字节数据:

字段	类型	必选	描述
`contract`	`string`	是	合约
`side`	`string`	否	所有出价或要价。如果没有特别说明，两者都包括在内。

req_header 自定义 header 数据:

字段	类型	必选	描述
`x-gate-exptime`	`string`	否	指定过期的时间戳（毫秒）。如果 ws 收到请求的时间大于过期时间，请求将被拒绝

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_cancel_cp",
    "event": "api",
    "payload": {
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_cancel_all_order)
    }
))

print(ws.recv())

客户请求示例

{
  "time": 1681196537,
  "channel": "futures.order_cancel_cp",
  "event": "api",
  "payload": {
    "req_id": "request-id-7",
    "req_param": {
      "contract": "BTC_USDT",
      "side": "bid"
    }
  }
}

# 响应结果

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
»`x_gate_ratelimit_requests_remain`	Integer	当前时间窗口剩余可用请求数(为0不展示)
»`x_gate_ratelimit_limit`	Integer	当前频率限制上限(为0不展示)
»`x_gat_ratelimit_reset_timestamp`	Integer	已超过当前窗口频率限制，表示下个可用时间窗口的时间戳（毫秒），即什么时候可以恢复访问；未超过当前窗口频率限制，表示返回的是当前服务器时间（毫秒）
`data`	Object	请求响应的数据
»`result`	Object	详情至api (opens new window)
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

订单取消返回示例

{
  "request_id": "request-id-7",
  "header": {
    "response_time": "1681196537567",
    "status": "200",
    "channel": "futures.order_cancel_cp",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": [
      {
        "id": 74046545,
        "user": 6790020,
        "create_time": 1681196536.592,
        "finish_time": 1681196537.626,
        "finish_as": "cancelled",
        "status": "finished",
        "contract": "BTC_USDT",
        "size": 10,
        "price": "31403.2",
        "tif": "gtc",
        "left": 10,
        "fill_price": "0",
        "text": "t-my-custom-id",
        "tkfr": "0.0003",
        "mkfr": "0",
        "stp_id": 2,
        "stp_act": "cn",
        "amend_text": "-"
      }
    ]
  }
}

# 修改订单

futures.order_amend

您可以通过此频道修改未结束的订单

本频道和以下的 APIV4 功能相同:

PUT /futures/{settle}/orders/{order_id}

# 请求

payload 参数:

名称	类型	必选	描述
`req_id`	`string`	是	请求 id，服务器会发回，帮助你识别服务器响应的是哪个请求，它与外部的`id`不同
`req_param`	`object`	是	API 修改订单参数，详情至 api (opens new window)
`req_header`	`object`	否	Apiv4 自定义请求头

req_param API 订单模型的 JSON 字节数据:

字段	类型	必选	描述
`order_id`	`string`	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 `text` 字段）。
`size`	`int64`	否	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为 0。
`price`	`string`	否	价格
`amend_text`	`int64`	否	修改订单时的自定义信息

req_header 自定义 header 数据:

字段	类型	必选	描述
`x-gate-exptime`	`string`	否	指定过期的时间戳（毫秒）。如果 ws 收到请求的时间大于过期时间，请求将被拒绝

# 详细描述

=> size: 新订单尺寸，包括已填充部分。

如果新尺寸小于或等于已填充尺寸，订单将被取消。
订单面必须与原始面相同。
平仓订单大小无法更改。
对于仅减少订单，增加尺寸可能会导致其他仅减少订单被取消。
如果价格不变，减少数量不会改变其在订单簿中的优先级，而增加数量则会以当前价格将其移至最后。

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_amend",
    "event": "api",
    "payload": {
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_amend_order)
    }
))

print(ws.recv())

客户请求示例

{
  "time": 1681196536,
  "channel": "futures.order_amend",
  "event": "api",
  "payload": {
    "req_id": "request-id-4",
    "req_param": {
      "order_id": "74046543",
      "price": "31303.180000"
    }
  }
}

# 响应结果

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
»`x_gate_ratelimit_requests_remain`	Integer	当前时间窗口剩余可用请求数(为0不展示)
»`x_gate_ratelimit_limit`	Integer	当前频率限制上限(为0不展示)
»`x_gat_ratelimit_reset_timestamp`	Integer	已超过当前窗口频率限制，表示下个可用时间窗口的时间戳（毫秒），即什么时候可以恢复访问；未超过当前窗口频率限制，表示返回的是当前服务器时间（毫秒）
`data`	Object	请求响应的数据
»`result`	Object	详情至 api (opens new window)
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

订单修改返回示例

{
  "request_id": "request-id-4",
  "header": {
    "response_time": "1681196536251",
    "status": "200",
    "channel": "futures.order_amend",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d",
    "x_gate_ratelimit_requests_remain": 99,
    "x_gate_ratelimit_limit": 100,
    "x_gat_ratelimit_reset_timestamp": 1736408263764
  },
  "data": {
    "result": {
      "id": 74046543,
      "user": 6790020,
      "create_time": 1681196535.01,
      "status": "open",
      "contract": "BTC_USDT",
      "size": 10,
      "price": "31303.2",
      "tif": "gtc",
      "left": 10,
      "fill_price": "0",
      "text": "t-my-custom-id",
      "tkfr": "0.0003",
      "mkfr": "0",
      "stp_id": 2,
      "stp_act": "cn",
      "amend_text": "-"
    }
  }
}

# 获取订单列表

futures.order_list

您可以通过此频道获取订单列表

本频道和以下的 APIV4 功能相同:

GET /futures/{settle}/orders

# 订单列表请求

payload 参数:

名称	类型	必选	描述
`req_id`	`string`	是	请求 id，服务器会发回，帮助你识别服务器响应的是哪个请求，它与外部的`id`不同
`req_param`	`object`	是	API 请求订单列表参数，详情至 api (opens new window)

req_param API 订单模型的 JSON 字节数据:

字段	类型	必选	描述
`contract`	`string`	否	合约标识，如果指定则只返回该合约相关数据
`status`	`string`	是	只列出具有此状态的订单
`limit`	`int`	否	单个列表中返回的最大记录数
`offset`	`int`	否	列表偏移量，从 0 开始
`last_id`	`string`	否	使用先前列表查询结果中最后一条记录的 `id` 指定列表起始点

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_list",
    "event": "api",
    "payload": {
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_list_order)
    }
))

print(ws.recv())

客户请求示例

{
  "time": 1681196535,
  "channel": "futures.order_list",
  "event": "api",
  "payload": {
    "req_id": "request-id-3",
    "req_param": {
      "contract": "BTC_USDT",
      "status": "open"
    }
  }
}

# 订单列表响应

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求 `event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
`data`	Object	请求响应的数据
»`result`	Object	详情至 api (opens new window)
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

订单列表返回示例

{
  "request_id": "request-id-3",
  "header": {
    "response_time": "1681196536017",
    "status": "200",
    "channel": "futures.order_list",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d"
  },
  "data": {
    "result": [
      {
        "id": 74046543,
        "user": 6790020,
        "create_time": 1681196535.01,
        "status": "open",
        "contract": "BTC_USDT",
        "size": 10,
        "price": "31403.2",
        "tif": "gtc",
        "left": 10,
        "fill_price": "0",
        "text": "t-my-custom-id",
        "tkfr": "0.0003",
        "mkfr": "0",
        "stp_id": 2,
        "stp_act": "cn",
        "amend_text": "-"
      }
    ]
  }
}

# 查询订单详情

futures.order_status

您可以通过该频道查询订单详情

本频道和以下的 APIV4 功能相同:

GET /futures/{settle}/orders/{order_id}

# 订单详情请求

payload 参数:

名称	类型	必选	描述
`req_id`	`string`	是	请求 id，服务器会发回，帮助你识别服务器响应的是哪个请求，它与外部的`id`不同
`req_param`	`object`	是	详情至 api (opens new window)

req_param` API 订单模型的 JSON 字节数据:

字段	类型	必选	描述
`order_id`	`string`	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 `text` 字段）。

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://fx-ws.gateio.ws/v4/ws/usdt")
ws.send(json.dumps(
    "time": int(time.time()),
    "channel": "futures.order_status",
    "event": "api",
    "payload": {
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_status_order)
    }
))

print(ws.recv())

客户请求示例

{
  "time": 1681196535,
  "channel": "futures.order_status",
  "event": "api",
  "payload": {
    "req_id": "request-id-2",
    "req_param": {
      "order_id": "74046543"
    }
  }
}

# 订单详情响应

响应参数:

名称	类型	描述
`request_id`	String	对应的请求 ID
`header`	Map	响应元信息
»`response_time`	String	响应发送时间(毫秒)
»`channel`	String	请求频道
»`event`	String	请求`event`
»`client_id`	String	唯一的客户端 ID
»`x_in_time`	Integer	ws 接收请求的时间（以微秒为单位）
»`x_out_time`	Integer	ws 返回响应的时间（以微秒为单位）
»`conn_id`	String	与客户端建立连接的链接Id（同一个连接的链接Id保持一致）
»`conn_trace_id`	String	与客户端建立连接的TraceId
»`trace_id`	String	执行下单操作的TraceId
`data`	Object	请求响应的数据
»`result`	Object	详情至 api (opens new window)
»`errs`	Object	仅当请求失败时可用
»»`label`	String	错误类型
»»`message`	String	详细错误信息

订单详情返回示例

{
  "request_id": "request-id-2",
  "header": {
    "response_time": "1681196535985",
    "status": "200",
    "channel": "futures.order_status",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0",
    "x_in_time": 1681985856667508,
    "x_out_time": 1681985856667598,
    "conn_id": "5e74253e9c793974",
    "conn_trace_id": "1bde5aaa0acf2f5f48edfd4392e1fa68",
    "trace_id": "e410abb5f74b4afc519e67920548838d"
  },
  "data": {
    "result": {
      "id": 74046543,
      "user": 6790020,
      "create_time": 1681196535.01,
      "status": "open",
      "contract": "BTC_USDT",
      "size": 10,
      "price": "31403.2",
      "tif": "gtc",
      "left": 10,
      "fill_price": "0",
      "text": "t-my-custom-id",
      "tkfr": "0.0003",
      "mkfr": "0",
      "stp_id": 2,
      "stp_act": "cn",
      "amend_text": "-"
    }
  }
}

Last Updated: 3/12/2025, 10:42:24 AM