# Gate.io 交割合约 WebSocket v4

    Gate.io 提供简单而强大的 Websocket API,将 gate.io BTC/USDT 交割合约交易状态集成到您的业务或应用程序中。

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

    # 服务地址

    我们提供 BTC/USDT 结算交割合约交易服务器地址,您可以根据自己的情况选择其中之一

    # USDT Contract

    地址列表:

    • 线上交易: wss://fx-ws.gateio.ws/v4/ws/delivery/usdt
    • 模拟盘交易: wss://fx-ws-testnet.gateio.ws/v4/ws/delivery/usdt

    # BTC Contract

    Base URLs:

    • 线上交易: wss://fx-ws.gateio.ws/v4/ws/delivery/btc
    • 模拟盘交易: wss://fx-ws-testnet.gateio.ws/v4/ws/delivery/btc

    # Changelog

    # !/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_20230630'], False)
    
    
    if __name__ == "__main__":
        logging.basicConfig(format="%(asctime)s - %(message)s", level=logging.DEBUG)
        app = GateWebSocketApp("wss://fx-ws-testnet.gateio.ws/v4/ws/delivery/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/delivery/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_20230630"})
    	err = orderBookMsg.send(c)
    	if err != nil {
    		panic(err)
    	}
    
    	// subscribe positions
    	positionsMsg := NewMsg("futures.positions", "subscribe", t, []string{"USERID", "BTC_USDT_20230630"})
    	positionsMsg.sign()
    	err = positionsMsg.send(c)
    	if err != nil {
    		panic(err)
    	}
    
    	select {}
    }
    

    2021-08-06

    • 支持 BTC 交割合约

    2020-08-08

    • 添加完整代码 demo(golang, python)

    2020-08-07

    • 新增自动订单通道

    # Websocket API 概述

    # 事件

    每个通用订阅通道/channel(例如tickerorder_book等)都支持一些不同的事件消息,它们是:

    1. subscribe (推荐使用)

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

    2. unsubscribe

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

    3. update

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

    4. all

    如果有新订阅的数据(所有数据)可用,服务器将向客户端发送通知。

    # 请求参数

    每个请求都遵循通用格式,其中包含timechanneleventpayload

    名称 类型 必选 描述
    id Integer 可选的请求 ID,将由服务器发回,以帮助您识别服务器响应哪个请求
    time Integer 请求时间
    channel String 请求 subscribe/unsubscribe 通道
    auth String 请求身份验证信息,请参阅身份验证部分了解详细信息
    event String 请求 event (subscribe/unsubscribe/update/all/api)
    payload Array 请求详细参数

    # 推送参数

    与请求类似,响应遵循以下通用格式,其中包含: time, channel, event , errorresult.

    名称 类型 必选 描述
    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/delivery/usdt")
    ws.send('{"time" : 123456, "channel" : "futures.ping"}')
    print(ws.recv())
    

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

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

    # 请求参数

    • channel

      futures.ping

    # Ticker 频道

    Ticker 是合约的高层概览, 它向您显示最高、最低、最近的交易价格。还包括每日交易量以及价格在过去一天内的波动情况等信息。

    # 订阅 Ticker

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

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

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

    订阅交割合约的 Ticker

    # 请求参数

    • channel

      futures.tickers

    • event

      subscribe

    • params

      参数 类型 必选 描述
      payload Array 合约列表

    # Tickers 推送

    {
      "time": 1541659086,
      "channel": "futures.tickers",
      "event": "update",
      "error": null,
      "result": [
        {
          "contract": "BTC_USDT_20230630",
          "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"
        }
      ]
    }
    

    推送已订阅的 Tickers

    # 通知

    • channel

      futures.tickers

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »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_usd String 24 小时 USD 的成交量
      »volume_24h_quote String 24 小时报价货币交易量
      »volume_24h_settle String 24 小时结算货币交易量
      »volume_24h_base String 24 小时基础货币交易量

    # 取消订阅

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

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

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

    取消订阅 Ticker

    # 请求参数

    • channel

      futures.tickers

    • event

      unsubscribe

    # 交易频道

    该通道在 gate.io 上发生交易时发送交易消息,它包括交易的详细信息,如价格、数量、时间和类型。

    # 订阅 Trades

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

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

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

    Trades 推送

    # 请求参数

    • channel

      futures.trades

    • event

      subscribe

    • params

      参数 类型 必选 描述
      payload Array 合约列表

    # Trades 推送

    正数表示 taker 是 buyer, 复数则是 seller.

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

    推送 Trades 更新

    # Notify

    • channel

      futures.trades

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »contract String 交割合约名称
      »size int 交易大小
      »id int 交易的唯一标识
      »create_time int 交易的创建时间,单位秒
      »create_time_ms int 交易的创建时间,单位毫秒
      »price string 交易价格

    # 取消订阅

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

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

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

    取消订阅 Trades

    # 请求参数

    • channel

      futures.trades

    • event

      unsubscribe

    # 订单簿频道

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

    支持三种不同的订单簿订阅通道:

    • futures.order_book

    传统通道,使用 all 推送完整的有限级别订单簿,使用 update 发送每个订单簿变动事件。

    • futures.book_ticker

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

    • futures.order_book_update

    推送用户指定更新频率的订单簿变动。

    WARNING

    不建议通过 futures.order_book 接收订单簿更新。futures.order_book_update 可以提供更及时的更新,而且流量更少。

    如何维护本地订单簿:

    1. 订阅 futures.order_book_update,并指定级别和更新频率,例如 ["BTC_USDT_20230630", "1000ms", "10"] 每秒推送 BTC_USDT 订单簿的前 10 个级别的更新。
    2. 缓存 WebSocket 通知。每个通知使用 Uu 来告知上次通知以来的第一个和最后一个更新 ID。
    3. 使用 REST API 检索基础订单簿,并确保记录了订单簿 ID(在下面被称为 baseID)。例如,https://api.gateio.ws/api/v4/delivery/usdt/order_book?contract=BTC_USDT_20230630&limit=10&with_id=true 可以检索到 BTC_USDT_20230630 的前 10 级基础订单簿。
    4. 遍历缓存的 WebSocket 通知,并找到第一个包含 baseID 的通知,即 U <= baseId+1u >= baseId+1,然后从这里开始消费。注意通知中的大小都是绝对值。使用它们来替换相应价格的原始大小。如果大小等于 0,则从订单簿中删除该价格。
    5. 删除满足 u < baseID+1 的所有通知。如果 aseID+1 < 第一个通知 U,则表示当前基础订单簿落后于通知。从步骤 3 开始检索更新的基础订单簿。
    6. 如果发现满足 U > baseID+1 的任何后续通知,表示已丢失一些更新。从步骤 3 重新构建本地订单簿。

    # 深度全量更新频道

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

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

    {
      "time": 1545405058,
      "time_ms": 1545405058123,
      "channel": "futures.order_book",
      "event": "subscribe",
      "error": null,
      "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_USDT_20230630",
        "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": "update",
      "time": 1541500167,
      "time_ms": 1541500167123,
      "result": [
        {
          "p": "97.5",
          "s": 6541,
          "contract": "BTC_USDT_20230630",
          "id": 93973512
        }
      ]
    }
    

    推送订单簿更新信息

    # 通知

    • channel

      futures.order_book

    • event

      update/all

    • params

      字段 type 描述
      result Array 结果
      »contract String 交割合约名称
      »s Integer 最终计算的结果,正数表示多头(买单),负数表示空头(卖单)
      »p String 订单簿价格
      »id Integer 订单簿唯一标识

    # 取消传统订单簿

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

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

    {
      "time": 1545445847,
      "time_ms": 1545445847123,
      "channel": "futures.order_book",
      "event": "unsubscribe",
      "error": null,
      "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/delivery/usdt")
    ws.send(
        '{"time" : 123456, "channel" : "futures.book_ticker", "event": "subscribe", "payload" : ["BTC_USDT_20230630"]}')
    print(ws.recv())
    

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

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

    订阅订单簿标价

    # 请求参数

    • channel

      futures.book_ticker

    • event

      subscribe

    • params

      payload 是指感兴趣的交割合约列表。

    # 推送订单簿标记信息

    如果 a 是空字符串,表示卖单为空;如果 b 是空字符串,表示买单为空。

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

    通知合约最佳买/卖单

    # 通知

    • channel

      futures.book_ticker

    • event

      update

    • params

      字段 类型 描述
      result object 结果
      »t Integer 订单簿标价生成的时间戳
      »u Integer 订单簿更新的唯一标识符
      »s String 交割合约名称
      »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/delivery/usdt")
    ws.send(
        '{"time" : 123456, "channel" : "futures.book_ticker", "event": "unsubscribe", "payload" : ["BTC_USDT_20230630"]}')
    print(ws.recv())
    

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

    {
      "time": 1545445847,
      "time_ms": 1545445847123,
      "channel": "futures.book_ticker",
      "event": "unsubscribe",
      "error": null,
      "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/delivery/btc")
    ws.send(
        '{"time" : 123456, "channel" : "futures.order_book_update", "event": "subscribe", "payload" : ["BTC_USDT_20230630", "1000ms", "20"]}')
    print(ws.recv())
    

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

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

    订阅订单簿更新

    # 请求参数

    • channel

      futures.order_book_update

    • event

      subscribe

    • payload

      参数 类型 必选 描述
      contract String 交割合约名称
      frequency String 更新频率: 100ms 或者 1000ms
      level String 可选级别,仅会通知所选择的更新,支持 1005020105

    # 订单簿更新通知

    {
      "time": 1615366381,
      "time_ms": 1615366381123,
      "channel": "futures.order_book_update",
      "event": "update",
      "error": null,
      "result": {
        "t": 1615366381417,
        "s": "BTC_USDT_20230630",
        "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 String 交割合约名称
      »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/delivery/btc")
    ws.send(
        '{"time" : 123456, "channel" : "futures.order_book_update", "event": "unsubscribe", "payload" : ["BTC_USDT_20230630", "100ms"]}')
    print(ws.recv())
    

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

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

    退订指定交割合约的订单簿

    # 请求参数

    • channel

      futures.order_book_update

    • event

      unsubscribe

    # K 线频道

    提供一种获取 K 线信息的方式

    # 订阅 K 线

    如果合约字段 contract 包含 mark_ 前缀的话, 将订阅合同的标记价格 K 线数据。

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

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

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

    # 请求参数

    • channel

      futures.candlesticks

    • event

      subscribe

    • params

      字段 类型 描述
      interval String 间隔:"10s", "1m", "5m", "15m", "30m", "1h", "4h", "8h", "1d", "7d"
      contract String 交割合约名称

    # 推送 K 线消息

    {
      "time": 1542162490,
      "channel": "futures.candlesticks",
      "event": "update",
      "error": null,
      "result": [
        {
          "t": 1545129300,
          "v": 27525555,
          "c": "95.4",
          "h": "96.9",
          "l": "89.5",
          "o": "94.3",
          "n": "1m_BTC_USDT_20230630"
        },
        {
          "t": 1545129300,
          "v": 27525555,
          "c": "95.4",
          "h": "96.9",
          "l": "89.5",
          "o": "94.3",
          "n": "1m_BTC_USDT_20230630"
        }
      ]
    }
    

    推送 K 线信息

    # 通知

    • channel

      futures.candlesticks

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »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/delivery/usdt")
    ws.send(
        '{"time" : 123456, "channel" : "futures.candlesticks", "event": "unsubscribe", "payload" : ["1m", "BTC_USDT_20230630"]}')
    print(ws.recv())
    

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

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

    退订指定交割合约的 K 线信息

    # 请求参数

    • channel

      futures.candlesticks

    • event

      unsubscribe

    # 订单频道

    提供一种获取用户已关闭的订单的方法

    WARNING

    需要认证

    # 订阅订单消息

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

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

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

    订阅用户订单消息

    # 请求参数

    • channel

      futures.orders

    • event

      subscribe

    • params

      参数 类型 必选 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 订单推送信息

    {
      "channel": "futures.orders",
      "event": "update",
      "time": 1541505434,
      "result": [
        {
          "contract": "BTC_USDT_20230630",
          "user": "200XX",
          "create_time": 1545141817,
          "create_time_ms": 1545141817123,
          "fill_price": 4120,
          "finish_as": "filled",
          "iceberg": 0,
          "id": 93282759,
          "is_reduce_only": false,
          "status": "finished",
          "is_close": 0,
          "is_liq": 0,
          "left": 0,
          "mkfr": -0.00025,
          "price": 4120,
          "refu": 0,
          "size": 10,
          "text": "-",
          "tif": "gtc",
          "finish_time": 1545640868,
          "finish_time_ms": 1545640868123,
          "tkfr": 0.00075
        }
      ]
    }
    

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

    # 通知

    • channel

      futures.orders

    • event

      update

    • params

      以下字段的具体意思,请查阅 HTTP 接口。

      字段 类型 描述
      result Array 结果
      »create_time Integer 创建时间戳,单位秒
      »create_time_ms Integer 创建时间戳,单位毫秒
      »fill_price Float 成交价格
      »finish_as String 完成状态
      »iceberg Integer 冰山订单
      »id Integer 订单唯一标识
      »is_close Integer 是否平仓
      »is_liq Integer 是否强平
      »left Integer 订单剩余数量
      »mkfr Integer -
      »is_reduce_only Bool 是否减仓
      »status String 订单状态
      »tkfr Integer -
      »price Integer 订单价格
      »refu Integer -
      »size Integer 订单大小
      »text String -
      »tif String -
      »finish_time Integer 完成时间戳,单位秒
      »finish_time_ms Integer 完成时间戳,单位毫秒
      »user String 用户唯一标识
      »contract String 交割订单名称

    # 取消订阅

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

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

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

    退订所有交割合约的订单更新数据

    # 请求参数

    • channel

      futures.orders

    • event

      unsubscribe

    # 用户交易频道

    提供一种获取用户交易数据的方式。

    WARNING

    需要认证

    # 订阅用户交易数据

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

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

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

    订阅用户交易更新数据

    # 请求参数

    • channel

      futures.usertrades

    • event

      subscribe

    • params

      参数 类型 必选 描述
      user id String 用户唯一标识
      contract String 交易合约名称

    # 推送用户交易数据

    {
      "time": 1543205083,
      "channel": "futures.usertrades",
      "event": "update",
      "error": null,
      "result": [
        {
          "contract": "BTC_USDT_20230630",
          "create_time": 1545140672,
          "create_time_ms": 1545140672371,
          "id": "12651269",
          "order_id": "56945246",
          "price": "113.6",
          "size": 10,
          "role": "maker"
        }
      ]
    }
    

    推送用户交易更新数据

    # 通知

    • channel

      futures.usertrades

    • event

      update

    • params

      字段 type 描述
      result Array 结果
      »contract String 交割合约名称
      »create_time Integer 创建时间
      »create_time_ms Integer 创建时间
      »id String 交易唯一标识
      »order_id String 订单唯一标识
      »price String 价格
      »size Integer 交易大小
      »role String 用户角色 (maker/taker)

    # 取消订阅

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

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

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

    退订用户交易更新数据

    # 请求参数

    • channel

      futures.usertrades

    • event

      unsubscribe

    # 强平频道

    提供一种获取强平的方式。

    WARNING

    需要认证

    # 订阅清算信息

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

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

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

    订阅用户清算更新

    # 请求

    • channel

      futures.liquidates

    • event

      subscribe

    • params

      参数 type 必选 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 清算通知

    {
      "channel": "futures.liquidates",
      "event": "update",
      "time": 1541505434,
      "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_USDT_20230630",
          "user": "1040"
        }
      ]
    }
    

    通知清算更新消息

    # 通知

    • channel

      futures.liquidates

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »entry_price Float 平均入场价格
      »fill_price Float 平均执行价格
      »leverage Float 杠杆
      »liq_price Float 清算价格
      »margin Float 保证金
      »mark_price Float 标记价格
      »order_id Integer 订单唯一标识
      »order_price Float 佣金价格
      »left Integer 订单未成交数量
      »size Integer 持仓的原始大小
      »time Integer 时间
      »time_ms Integer 时间,毫秒
      »user String 用户唯一标识
      »contract String 交割合约名称

    # 取消订阅

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

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

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

    退订用户清算更新

    # 请求

    • channel

      futures.liquidates

    • event

      unsubscribe

    # 自动减仓频道

    WARNING

    需要认证

    # 订阅自动减仓更新

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

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

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

    订阅用户自动检查更新数据

    # 请求

    • channel

      futures.auto_deleverages

    • event

      subscribe

    • params

      参数 类型 必选 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 自动减仓通知

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

    通知自动检查更新信息

    # 通知

    • channel

      futures.auto_deleverages

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »entry_price Float 入场价格
      »fill_price Float 执行价格
      »position_size Integer 持仓大小
      »trade_size Integer 交易大小
      »time Integer 时间,单位秒
      »time_ms Integer 时间,单位毫秒
      »user String 用户唯一标识
      »contract String 交割合约名称

    # 取消订阅

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

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

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

    退订自动减仓更新

    # 请求

    • channel

      futures.auto_deleverages

    • event

      unsubscribe

    # 平仓信息频道

    提供接收用户平仓的方式

    WARNING

    需要认证

    # 订阅平仓更新数据

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

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

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

    订阅用户平仓更新信息

    # 请求

    • channel

      futures.position_closes

    • event

      subscribe

    • params

      参数 类型 必选 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 平仓通知

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

    通知平仓更新

    # Notify

    • channel

      futures.position_closes

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »contract String 交割合约名称
      »pnl Number 盈亏金额
      »side String 方向,多头或空头
      »text String 消息内容
      »time Integer 时间,单位秒
      »time_ms Integer 时间,单位毫秒
      »user String 用户唯一标识

    # 取消订阅

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

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

    {
      "time": 1545459681,
      "channel": "futures.position_closes",
      "event": "unsubscribe",
      "error": null,
      "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/delivery/usdt")
    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,
      "channel": "futures.balances",
      "event": "subscribe",
      "error": null,
      "result": {
        "status": "success"
      }
    }
    

    订阅用户余额更新

    # 请求

    • channel

      futures.balances

    • event

      subscribe

    • params

      参数 类型 必填 描述
      user id String 用户唯一标识

    # 余额通知

    {
      "channel": "futures.balances",
      "event": "update",
      "time": 1541505434,
      "result": [
        {
          "balance": 9.998739899488,
          "change": -0.000002074115,
          "text": "BTC_USDT_20230630:3914424",
          "time": 1547199246,
          "time_ms": 1547199246123,
          "type": "fee",
          "user": "20011"
        }
      ]
    }
    

    通知余额更新

    # 通知

    • channel

      futures.balances

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »balance Number 变更后的余额
      »change Number 变动的金额
      »text String 消息内容
      »time Integer 时间,单位秒
      »time_ms Integer 时间,单位毫秒
      »type String 类型
      »user String 用户唯一标识

    # 取消订阅

    import json
    from websocket import create_connection
    
    ws = create_connection("wss://fx-ws-testnet.gateio.ws/v4/ws/delivery/usdt")
    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,
      "channel": "futures.balances",
      "event": "unsubscribe",
      "error": null,
      "result": {
        "status": "success"
      }
    }
    

    # 减少风险限额频道

    提供一种接收用户减少风险限额信息的方式。

    WARNING

    需要认证

    # 订阅减少风险限额

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

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

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

    **订阅用户减少风险限额的更新数据 **

    # 请求

    • channel

      futures.reduce_risk_limits

    • event

      subscribe

    • params

      参数 类型 必选 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 减少风险限额通知

    {
      "time": 1551858330,
      "channel": "futures.reduce_risk_limits",
      "event": "update",
      "error": null,
      "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 结果
      »cancel_orders Number 取消订单数
      »contract String 合约名称
      »leverage_max Number 最大杠杆
      »liq_price Number 清算价格
      »maintenance_rate Number 维持保证金率
      »risk_limit Number 风险限额
      »time Number 时间,单位秒
      »time_ms Number 时间,单位毫秒
      »user String 用户唯一标识

    # 取消订阅

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

    Unsubscribe reduce risk limits update.

    # 请求

    • channel

      futures.reduce_risk_limits

    • event

      unsubscribe

    # 仓位频道

    提供接受用户仓位信息的方式。

    WARNING

    需要认证

    # 订阅仓位信息

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

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

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

    **订阅用户的仓位更新数据 **

    # 请求

    • channel

      futures.positions

    • event

      subscribe

    • params

      参数 类型 必填 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 推送仓位更新数据

    {
      "time": 1588212926,
      "channel": "futures.positions",
      "event": "update",
      "error": null,
      "result": [
        {
          "contract": "BTC_USDT_20230630",
          "entry_price": 5999,
          "history_pnl": 9.99872821972,
          "history_point": -0.02954299895,
          "last_close_pnl": -0.00011406187,
          "leverage": 10,
          "leverage_max": 100,
          "liq_price": 5508.28,
          "maintenance_rate": 0.005,
          "margin": 0.001112608124,
          "realised_pnl": -0.000072631078,
          "realised_point": 0,
          "risk_limit": 100,
          "size": 70,
          "time": 1588212925,
          "time_ms": 1588212925123,
          "user": "10003"
        }
      ]
    }
    

    通知仓位更新

    # 通知

    • channel

      futures.positions

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »contract String 交割合约名称
      »entry_price Number 入场价格
      »history_pnl Number 历史盈亏
      »history_point Number 历史点数
      »last_close_pnl Number 最后平仓盈亏
      »leverage Number 杠杆
      »leverage_max Number 最大支持的杠杆
      »liq_price Number 强平价格
      »maintenance_rate Number 维持保证金率
      »margin Number 保证金
      »realised_pnl Number 已实现盈亏
      »realised_point Number 已实现点数
      »risk_limit Number 风险限额
      »size Number 合约大小
      »time Number 更新时间,单位秒
      »time_ms Number 更新时间,单位毫秒
      »user String 用户唯一标识

    # 取消订阅

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

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

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

    退订仓位更新数据

    # 请求参数

    • channel

      futures.positions

    • event

      unsubscribe

    # 自动下单频道

    提供一种获取用户自动下单数据的方式。

    WARNING

    需要认证

    # 订阅自动下单

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

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

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

    订阅自动下单更新数据

    # 请求参数

    • channel

      futures.autoorders

    • event

      subscribe

    • params

      参数 类型 必选 描述
      user id String 用户唯一标识
      contract String 交割合约名称

    # 自动下单推送通知

    {
      "time": 1596798126,
      "channel": "futures.autoorders",
      "event": "update",
      "error": null,
      "result": [
        {
          "user": 1543255,
          "trigger": {
            "strategy_type": 0,
            "price_type": 0,
            "price": "10000",
            "rule": 2,
            "expiration": 86400
          },
          "initial": {
            "contract": "BTC_USDT_20230630",
            "size": 10,
            "price": "10000",
            "tif": "gtc",
            "text": "web",
            "iceberg": 0,
            "is_close": false,
            "is_reduce_only": false
          },
          "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": ""
          }
        }
      ]
    }
    

    通知自动下单更新数据

    # 通知

    • channel

      futures.autoorders

    • event

      update

    • params

      字段 类型 描述
      result Array 结果
      »user Number 用户唯一标识
      »trigger Object 触发器
      »initial Object 起势
      »id Number 自动订单的唯一标识
      »trade_id Number 交易唯一标识
      »status String 订单状态
      »reason String 变更原因
      »create_time Number 创建时间
      »name String 名称
      »is_stop_order boolean 是否停止订单
      »stop_trigger Object 停止触发器

    # 取消订阅

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

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

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

    退订自动订单数据

    # 请求参数

    • channel

      futures.autoorders

    • event

      unsubscribe