Gate.hk 永续合约 WebSocket v4

Gate.hk提供简单而强大的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服务.

变更日志

# !/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)

package main

import (
  "crypto/hmac"
  "crypto/sha512"
  "crypto/tls"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "io"
  "net/url"
  "time"

  "github.com/gorilla/websocket"
)

type Msg struct {
  Time    int64    `json:"time"`
  Channel string   `json:"channel"`
  Event   string   `json:"event"`
  Payload []string `json:"payload"`
  Auth    *Auth    `json:"auth"`
}

type Auth struct {
  Method string `json:"method"`
  KEY    string `json:"KEY"`
  SIGN   string `json:"SIGN"`
}

const (
  Key    = "YOUR_API_KEY"
  Secret = "YOUR_API_SECRETY"
)

func sign(channel, event string, t int64) string {
  message := fmt.Sprintf("channel=%s&event=%s&time=%d", channel, event, t)
  h2 := hmac.New(sha512.New, []byte(Secret))
  io.WriteString(h2, message)
  return hex.EncodeToString(h2.Sum(nil))
}

func (msg *Msg) sign() {
  signStr := sign(msg.Channel, msg.Event, msg.Time)
  msg.Auth = &Auth{
    Method: "api_key",
    KEY:    Key,
    SIGN:   signStr,
  }
}

func (msg *Msg) send(c *websocket.Conn) error {
  msgByte, err := json.Marshal(msg)
  if err != nil {
    return err
  }
  return c.WriteMessage(websocket.TextMessage, msgByte)
}

func NewMsg(channel, event string, t int64, payload []string) *Msg {
  return &Msg{
    Time:    t,
    Channel: channel,
    Event:   event,
    Payload: payload,
  }
}

func main() {
  u := url.URL{Scheme: "wss", Host: "fx-ws.gateio.ws", Path: "/v4/ws/usdt"}
  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)
    }
  }()

  t := time.Now().Unix()
  pingMsg := NewMsg("futures.ping", "", t, []string{})
  err = pingMsg.send(c)
  if err != nil {
    panic(err)
  }

  // subscribe order book
  orderBookMsg := NewMsg("futures.order_book", "subscribe", t, []string{"BTC_USDT"})
  err = orderBookMsg.send(c)
  if err != nil {
    panic(err)
  }

  // subscribe positions
  positionsMsg := NewMsg("futures.positions", "subscribe", t, []string{"USERID", "BTC_USDT"})
  positionsMsg.sign()
  err = positionsMsg.send(c)
  if err != nil {
    panic(err)
  }

  select {}
}

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字段

Websocket API概述

事件

每个通用 订阅频道/channel（例如ticker、order_book等）都支持一些不同的事件消息，它们是：

1. subscribe (推荐使用)

   订阅，接受服务器的新数据通知。

2. unsubscribe

   如果取消订阅，服务器将不会发送新数据通知。

3. update

   服务器将向客户端发送新的订阅数据（增量数据）。

4. 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	Array	是	响应详细参数

错误

如果出现错误，您会收到error字段，其中包含错误代码和错误的类型。

Code	Message
1	invalid argument struct
2	invalid argument
3	service error

鉴权

如果频道是私有的，则请求体需要携带认证信息， 例如futures.usertrades

WebSocket认证使用与HTTP API相同的签名计算方法，但具有 以下差异：

1. 签名字符串拼接方式：channel=<channel>&event=<event>&time=<time>, 其中<channel>、<event>、<time>是对应的请求信息
2. 身份验证信息在请求正文中的auth字段中发送。

# 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

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

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

System API

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

Ping/Pong

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

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

websocket rfc 协议 (opens new window)

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

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
}

请求参数

• 频道

  futures.ping

ticker频道

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

订阅操作

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"
  }
}

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

请求参数

• channel

  futures.tickers

• event

  subscribe

• params

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

ticker推送

{
  "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"
    }
  ]
}

永续合约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	下一期参考资金费率
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小时最高交易价

取消订阅

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"
  }
}

取消订阅

请求参数

• channel

  futures.tickers

• event

  unsubscribe

公有成交频道

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

公有成交订阅

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

  subscribe

• params

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

公有成交推送

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

  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线上。如果不是内部交易，则该字段不会被返回。

取消订阅

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"
  }
}

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

请求参数

• channel

  futures.trades

• event

  unsubscribe

深度频道

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

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

• futures.order_book

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

• futures.book_ticker

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

• futures.order_book_update

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

WARNING

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

如何维护本地订单簿:

1. 订阅 futures.order_book_update 并指定级别和更新频率，例如 ["BTC_USDT", "1000ms", "10"] 每 1s 推送 BTC_USDT 订单簿前 10 个级别的更新
2. 缓存WebSocket通知。每个通知都使用“U”和“u”来告诉第一个和最后一个 自上次通知以来更新 ID。
3. 使用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级基础订单簿
4. 迭代缓存的WebSocket通知，找到第一个包含baseID的通知， 即 U <= baseId+1 和 u >= baseId+1，然后开始从中消费。请注意，size为 通知都是全量的size，即应该使用它们覆盖替换原始的size。 如果 size 等于 0，则从订单簿中删除价格。
5. 转储所有满足 u < baseID+1 的通知。如果 baseID+1 < 第一个通知 U，则 意味着当前的基本订单簿落后于通知。从步骤 3 开始检索更新的内容基本订单簿。
6. 如果后续发现满足 U > baseID+1 的通知，则说明有更新 丢失的。从步骤 3 重建本地订单簿。

深度全量更新频道

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

  subscribe

• params

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

全量深度推送

{
  "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

  all

• params

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

全量深度取消订阅

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.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.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"
  }
}

订阅深度最佳买卖价

请求参数

• channel

  futures.book_ticker

• event

  subscribe

• params

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

最佳买卖价的推送

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

{
  "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

  update

• params

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

最佳买卖价的取消订阅

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.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.order_book_update",
        "event": "subscribe", "payload" : ["BTC_USD", "1000ms", "20"]}')
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

  subscribe

• params

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

深度更新推送

{
  "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

  update

• params

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

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

请求参数

• channel

  futures.order_book_update

• event

  unsubscribe

K线频道

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

K线订阅

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

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"
  }
}

请求参数

• channel

  futures.candlesticks

• event

  subscribe

• params

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

k线消息推送

{
  "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"
    },
    {
      "t": 1545129300,
      "v": 27525555,
      "c": "95.4",
      "h": "96.9",
      "l": "89.5",
      "o": "94.3",
      "n": "1m_BTC_USD"
    }
  ]
}

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	合约名称

取消订阅

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"
  }
}

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

请求参数

• channel

  futures.candlesticks

• event

  unsubscribe

订单频道

提供接收用户订单的推送

WARNING

需要认证.

订单订阅

如果您想订阅所有合约中的订单更新，请在合约列表中使用 !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.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

  subscribe

• params

名称	类型	必选	描述
user id	String	是	用户ID
contract	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

  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：因自我交易阻止而取消
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	用户修改订单时备注的自定义数据

取消订阅

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"
  }
}

取消订阅订单更新通知

请求参数

• channel

  futures.orders

• event

  unsubscribe

用户私有成交频道

提供接收用户交易的方式

WARNING

需要认证

用户私有成交订阅

如果您想订阅所有的市场交易更新，请在请求参数列表中使用!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.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

  subscribe

• params

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

用户私有成交推送

{
  "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

  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	点卡手续费

取消订阅

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"
  }
}

取消私有成交订阅

请求参数

• channel

  futures.usertrades

• event

  unsubscribe

强制平仓频道

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

WARNING

需要认证

清算订阅

如果您想订阅所有合约中的强制平仓推送，请在订阅请求列表中使用 !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.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

  subscribe

• params

名称	类型	必选	描述
user id	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

  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	合约名称

取消订阅

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"
  }
}

取消订阅清算更新

请求参数

• channel

  futures.liquidates

• event

  unsubscribe

自动减仓频道

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

WARNING

需要认证

自动减仓订阅

如果您想订阅所有合约的自动减仓更新，请在请求参数列表中使用!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.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

  subscribe

• params

名称	类型	必选	描述
user id	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

  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	合约名称

取消订阅

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"
  }
}

取消订阅自动减仓

请求参数

• channel

  futures.auto_deleverages

• event

  unsubscribe

平仓频道

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

WARNING

需要认证

平仓订阅

如果您想订阅所有合约的平仓更新，请在合约列表中使用 !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.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

  subscribe

• params

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

平仓信息推送

{
  "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

  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

取消订阅

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"
  }
}

取消订阅平仓更新

请求参数

• channel

  futures.position_closes

• event

  unsubscribe

余额频道

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

WARNING

需要认证

余额信息订阅

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

  subscribe

• params

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

余额更新推送

{
  "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"
    }
  ]
}

通知余额更新信息

推送参数

• 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	币种

取消订阅

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。

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

  subscribe

• params

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

降低风险率推送

{
  "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

  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

取消订阅

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())

退订降低风险限制更新

请求参数

• channel

  futures.reduce_risk_limits

• event

  unsubscribe

仓位频道

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

WARNING

需要认证

仓位订阅

如果您想订阅所有合约的持仓更新，请在合约列表中使用 !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.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

  subscribe

• params

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

仓位信息推送

{
  "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

  update

• params

名称	类型	描述
result	Array	Array of objects

名称	类型	描述
contract	String	合约名称
entry_price	Float
history_pnl	Float
history_point	Float
last_close_pnl	Float
leverage	Integer
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	消息序列号

取消订阅

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"
  }
}

取消订阅仓位更新

请求参数

• channel

  futures.positions

• event

  unsubscribe

自动订单频道

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

WARNING

需要认证

自动订单订阅

如果您想订阅所有合约中的自动订单更新，请在合约列表中使用!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.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

  subscribe

• params

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

自动订单消息推送

{
  "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

  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.

取消订阅

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"
  }
}

取消订阅自动订单更新

请求参数

• channel

  futures.autoorders

• event

  unsubscribe

账户交易 API

Websocket 交易 API

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

Websocket API 客户端请求

请求示例

{
  "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"
    }
  }
}

客户端发起的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 下限价单

Websocket API 服务响应

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

{
  "request_id": "request-id-1",
  "ack": true,
  "header": {
    "response_time": "1681195121499",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140031563c0"
  },
  "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"
  },
  "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": "-"
    }
  }
}

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

名称	类型	描述
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
data	Object
»result	Object	如果这是 ack 响应，则结果是请求的payload，否则结果是 api 的响应
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

错误

错误响应通知示例

{
  "request_id": "request-id-1",
  "ack": false,
  "header": {
    "response_time": "1681195360034",
    "status": "401",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140001a2600"
  },
  "data": {
    "errs": {
      "label": "INVALID_KEY",
      "message": "Invalid key provided"
    }
  }
}

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

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

登陆

WARNING

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

登录请求

客户端API请求

代码示例

package main

import (
   "crypto/hmac"
   "crypto/sha512"
   "encoding/hex"
   "encoding/json"
   "fmt"
   "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))
}

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"
  }
}

payload参数:

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

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

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

登录响应

登录响应示例

{
  "request_id": "request-1",
  "ack": false,
  "header": {
    "response_time": "1681985856666",
    "status": "200",
    "channel": "futures.login",
    "event": "api",
    "clientId": ""
  },
  "data": {
    "result": {
      "api_key": "ea83fad2604399da16bf97e6eea772a6",
      "uid": "110284739"
    }
  }
}

响应参数:

名称	类型	描述
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
data	Object
»result	Object	如果这是 ack 响应，则结果是请求的payload，否则结果是 api 的响应
»»api_key	String	登录成功的apikey
»»uid	String	登录成功的用户ID
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

下单

futures.order_place

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

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

POST /futures/{settle}/orders

下单请求

代码示例

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": {
        "header":{
            "x-gate-channel-id":"xxxx",
        },
        "req_id": "1ewq-3123w-5",
        "req_param": json.dumps(api_order)
    }
))

print(ws.recv())

请求示例

{
  "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"
    }
  }
}

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'sid
req_param	object	是	使用api下单参数； api下单参数详细信息api (opens new window)
headers	object	是	Apiv4 自定义请求头

订单请求回声消息

订单确认回声通知示例

{
  "request_id": "request-id-1",
  "ack": true,
  "header": {
    "response_time": "1681195484268",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140001a2600"
  },
  "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": "request-id-1",
  "ack": false,
  "header": {
    "response_time": "1681195484360",
    "status": "200",
    "channel": "futures.order_place",
    "event": "api",
    "client_id": "::1-0x140001a2600"
  },
  "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": "-"
    }
  }
}

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

名称	类型	描述
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
data	Object	订单信息
»result	Object	如果这是 ack 响应，则结果是请求的payload，否则结果是 api 的响应
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

批量下单

futures.order_batch_place

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

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

POST /futures/{settle}/batch_orders

批量下单请求

代码示例

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"
      }
    ]
  }
}

payload 参数:

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

批量下单确认通知

确认通知示例

{
  "request_id": "request-id-6",
  "ack": true,
  "header": {
    "response_time": "1681196536283",
    "status": "200",
    "channel": "futures.order_batch_place",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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": "request-id-6",
  "ack": false,
  "header": {
    "response_time": "1681196536532",
    "status": "200",
    "channel": "futures.order_batch_place",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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"
      }
    ]
  }
}

批量下单订单信息返回

响应参数:

名称	类型	描述
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
data	Object	订单信息
»result	Object	如果这是 ack 响应，则结果是请求的payload，否则结果是 api 的响应
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

订单取消

futures.order_cancel

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

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

DELETE /futures/{settle}/orders/{order_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_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"
    }
  }
}

payload 参数:

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

订单取消通知

订单取消返回示例

{
  "request_id": "request-id-5",
  "ack": false,
  "header": {
    "response_time": "1681196536282",
    "status": "200",
    "channel": "futures.order_cancel",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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": "-"
    }
  }
}

响应参数:

名称	类型	描述
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
data	Object
»result	Object	订单取消参数，详情至 api (opens new window)
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

取消匹配的未结束订单

futures.order_cancel_cp

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

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

DELETE /futures/{settle}/orders

请求

代码示例

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"
    }
  }
}

payload 参数:

名称	类型	必选	描述
req_id	string	是	请求id，服务器会发回，帮助你识别服务器响应的是哪个请求， 它与外部的id不同
req_param	object	是	详情至 api (opens new window)
api_key	string	是	Apiv4 key
signature	string	是	Apiv4 签名
timestamp	string	是	Unix 时间戳（以秒为单位）

响应结果

订单取消返回示例

{
  "request_id": "request-id-7",
  "ack": false,
  "header": {
    "response_time": "1681196537567",
    "status": "200",
    "channel": "futures.order_cancel_cp",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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": "-"
      }
    ]
  }
}

响应参数:

名称	类型	描述
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
data	Object
»result	Object	详情至api (opens new window)
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

修改订单

futures.order_amend

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

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

PUT /futures/{settle}/orders/{order_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_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"
    }
  }
}

payload 参数:

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

响应结果

订单修改返回示例

{
  "request_id": "request-id-4",
  "ack": false,
  "header": {
    "response_time": "1681196536251",
    "status": "200",
    "channel": "futures.order_amend",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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": "-"
    }
  }
}

响应参数:

名称	类型	描述
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
data	Object
»result	Object	详情至 api (opens new window)
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

获取订单列表

futures.order_list

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

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

GET /futures/{settle}/orders

订单列表请求

代码示例

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"
    }
  }
}

payload 参数:

名称	类型	必选	描述
req_id	string	是	请求id，服务器会发回，帮助你识别服务器响应的是哪个请求， 它与外部的id不同
req_param	object	是	API请求订单列表参数，详情至 api (opens new window)
api_key	string	是	Apiv4 key
signature	string	是	APIV4 签名
timestamp	string	是	Unix 时间戳（以秒为单位）

订单列表响应

订单列表返回示例

{
  "request_id": "request-id-3",
  "ack": false,
  "header": {
    "response_time": "1681196536017",
    "status": "200",
    "channel": "futures.order_list",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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": "-"
      }
    ]
  }
}

响应参数:

名称	类型	描述
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
data	Object
»result	Object	详情至 api (opens new window)
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息

查询订单详情

futures.order_status

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

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

GET /futures/{settle}/orders/{order_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_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"
    }
  }
}

payload 参数:

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

订单详情响应

订单详情返回示例

{
  "request_id": "request-id-2",
  "ack": false,
  "header": {
    "response_time": "1681196535985",
    "status": "200",
    "channel": "futures.order_status",
    "event": "api",
    "client_id": "::1-0x14002cfa0c0"
  },
  "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": "-"
    }
  }
}

响应参数:

名称	类型	描述
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
data	Object
»result	Object	详情至 api (opens new window)
»errs	Object	仅当请求失败时可用
»»label	String	错误类型
»»message	String	详细错误信息