现货&杠杆
永续合约
交割合约
期权
公告

# 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（例如ticker、order_book等）都支持一些不同的事件消息，它们是：

subscribe (推荐使用)

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

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

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

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

# 请求参数

每个请求都遵循通用格式，其中包含time、channel、event和payload。

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

# 推送参数

与请求类似，响应遵循以下通用格式，其中包含： time, channel, event , error 和 result.

名称	类型	必选	描述
`time`	Integer	是	响应时间
`time_ms`	Integer	是	毫秒响应时间
`channel`	String	是	响应通道
`event`	String	是	响应通道事件 (update/all)
`error`	Object	是	响应错误
`result`	Array	是	响应详细参数

# 错误

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

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

# 鉴权

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

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

签名字符串拼接方式：channel=<channel>&event=<event>&time=<time>, 其中<channel>、<event>、<time>是对应的请求信息
身份验证信息在请求正文中的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 是合约列表

参数	类型	必选	描述
`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 是合约列表

参数	类型	必选	描述
`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 可以提供更及时的更新，而且流量更少。

如何维护本地订单簿：

订阅 futures.order_book_update，并指定级别和更新频率，例如 ["BTC_USDT_20230630", "1000ms", "10"] 每秒推送 BTC_USDT 订单簿的前 10 个级别的更新。
缓存 WebSocket 通知。每个通知使用 U 和 u 来告知上次通知以来的第一个和最后一个更新 ID。
使用 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 级基础订单簿。
遍历缓存的 WebSocket 通知，并找到第一个包含 baseID 的通知，即 U <= baseId+1 且 u >= baseId+1，然后从这里开始消费。注意通知中的大小都是绝对值。使用它们来替换相应价格的原始大小。如果大小等于 0，则从订单簿中删除该价格。
删除满足 u < baseID+1 的所有通知。如果 aseID+1 < 第一个通知 U，则表示当前基础订单簿落后于通知。从步骤 3 开始检索更新的基础订单簿。
如果发现满足 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`	String	订单簿更新的唯一标识符
»`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/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	否	可选级别，仅会通知所选择的更新，支持 `100`、`50`、`20`、`10` 或 `5`

# 订单簿更新通知

{
  "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`	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/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 交割合约名称

字段	类型	描述
`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 是交割合约名称

参数	类型	必选	描述
`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 是交易合约名称

参数	类型	必选	描述
`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 是交割合约名称

参数	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 是交割合约名称

参数	类型	必选	描述
`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 是交割合约名称

参数	类型	必选	描述
`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 是用户唯一标识

参数	类型	必填	描述
`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 是交割合约名称

参数	类型	必选	描述
`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 是交割合约名称

参数	类型	必填	描述
`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 是交割合约名称

参数	类型	必选	描述
`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

Last Updated: 1/16/2024, 4:36:50 PM