NAV Navbar
Python JavaScript Golang

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
    # 处理收到的消息
    logger.info("message received from server: {}".format(message))


def on_open(ws):
    # type: (GateWebSocketApp) -> None
    # 订阅需要的频道
    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",
                           "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 {}
}

2021-03-01

2020-8-08

2020-8-07

2020-7-07

2020-4-30

2019-11-06

If you use old server urls(wss://fx-ws.gateio.ws/v4/ws or wss://fx-ws-testnet.gateio.ws/v4/ws), we will use BTC contract for you.

2019-10-22

2019-04-30

2019-02-13

2019-01-11

General

Introduction

gate.io provides a simple and robust Websocket API to integrate gate.io BTC/USDT futures contract trade status into your business or application.

We have language bindings in JavaScript and Python, more in the future! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Current Version

Websocket API version is 0.01.

Current API doc is built at 2020-08-08 23:49:33

Server URL

We provide BTC/USDT futures contract trade server urls, you can choose one of them according to your condition.

BTC Contract

Base URLs:

USDT Contract

Base URLs:

If you use old server urls(wss://fx-ws.gateio.ws/v4/ws or wss://fx-ws-testnet.gateio.ws/v4/ws), we will use BTC contract for you.

API Overview

Method

Each general api (such as ticker, orderbook etc) supports 4 different event messages, they are:

  1. subscribe (RECOMMENDED TO USE)

    Subscribe to receive notification from server when new data is available.

  2. unsubscribe

    Server will not send new data notification if unsubscribed.

  3. update

    If new subscribed data(incremental data) is avalilable, server will send a notificaiton to client.

  4. all

    If new subscribed data(all data) is avalilable, server will send a notificaiton to client.

Request

Each request follows a common format, which contains time, channel, event and payload.

parameter type required description
time Integer Yes request time
channel String Yes request subscribe/unsubscribe channel
auth String no request auth info, see Authentication section for details
event String Yes request event (subscribe/unsubscribe/update/all)
payload Array Yes request detail parameters

Response

Similar with request, response follows a common format composed of time, channel, event, error and result.

field type required description
time Integer Yes response time
channel String Yes response channel
event String Yes response channel event (update/all)
error Object Yes response channel event (update/all)
result Array Yes response detail parameters

Error

In case of error, you receive a message containing the proper error code and message within a error object.

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

Authentication

Request body needs to carry authentication information if channels are private, e.g. futures.usertrades

WebSocket authentication uses the same signature calculation method with HTTP API, but has the following differences:

  1. Signature string concatenation method: channel=<channel>&event=<event>&time=<time>, where <channel>, <event>, <time> are corresponding request information
  2. Authentication information are sent in request body in field 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

You can log into the console to retrieve futures API key and secret.

field type description
method String allowed value: api_key
KEY String user key string
SIGN String user sign string

System API

Provides system status check, such as ping-pong.

Ping and Pong

Check Server/Client connectivity.

gate.io futures contract use the protocol layer ping/pong message.The server will initiate a ping message actively. If the client does not reply, the client will be disconnected.

websocket rfc

if you want to actively detect the connection status, you can send application layer ping message and receive pong message.


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

The above command returns JSON structured like this:

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

Request

Tickers API

The ticker is a high level overview of the state of the contract. It shows you the highest, lowest, last trade price. It also includes information such as daily volume and how much the price has moved over the last day.

Tickers subscription


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

The above command returns JSON structured like this:

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

Subscribe futures contract ticker.

Request

Tickers notification

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

Notify subscribed contract ticker.

Notify

Cancel subscription

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": "unsubscribe", "payload" : ["BTC_USD"]}')
print(ws.recv())

The above command returns JSON structured like this:

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

Unsubscribe contract ticker.

Request

Trades API

This channel sends a trade message whenever a trade occurs at gate.io. It includes details of the trade, such as price, amount, time and type.

Trades subscription

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

The above command returns JSON structured like this:

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

Subscribe trades update notification.

Request

Trades notification

{
  "channel": "futures.trades",
  "event": "update",
  "time": 1541503698,
  "result": [
    {
      "size": -108,
      // + taker is buyer,- taker is seller
      "id": 27753479,
      "create_time": 1545136464,
      "create_time_ms": 1545136464123,
      "price": "96.4",
      "contract": "BTC_USD"
    }
  ]
}

Notify latest trades update.

Notify

update

field type description
result Array Array of objects
field type description
contract String futures contract name
size int trades size
id int trades id
create_time int trades msg create time
create_time_ms int trades msg create time in milliseconds
price string trades price

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe trades update notification.

Request

futures.trades

unsubscribe

Order_book API

The order_book channel allow you to keep track of the state of the gate.io order book depth. It is provided on a price aggregated basis, with customizable precision.

How to maintain local order book:

  1. Subscribe to futures.order_book
  2. On successful subscription, wait for the first all message to use as a base order book.
  3. On any subsequent update message received, check the id field in each update message first. Consume from the first message whose id equals to (base ID + 1)
  4. If the first message's id is larger than (baseID + 1) or the IDs of update messages received are not consecutive. Wait for another all message to replace your local order book

Order_book subscription


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

The above command returns JSON structured like this:

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

Subscribe order_book.

Request

Order_book notification

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

Or:

{
    "channel":"futures.order_book",
    "event":"update",
    "time":1541500167,
    "result":[{
        "p":"97.5",
        "s":6541,  // +-   -:short(asks) +:long(bids)
        "c":"BTC_USD",  // p: price, s: size , c contract
        "id":93973512
    },]
}

Notify contract order book update information

Notify

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsbscribe specified contract order book.

Request

Candlesticks API

Provides a way to access charting candlestick info.

Candlesticks subscription

If prefix contract with mark_, the contract's mark price candlesticks will be subscribed; if prefix with index_, index price candlesticks will be subscribed.


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

The above command returns JSON structured like this:

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

Request

Candlesticks notification

{
        "time":1542162490,
        "channel":"futures.candlesticks",
        "event":"update",
        "error":null,
        "result":[
            {
                // t : time , v : volume , c : close , h : high, l: low , o : open , n: name
                "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"
            }
        ]
    }

Notify kline information of subscribed contract.

Notify

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubsribe specified contract kline information.

Request

Orders API

Provides a way to receive user closed orders.

Orders subscription


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

The above command returns JSON structured like this:

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

Subscribe user orders update

Request

Orders notification

{
  "channel": "futures.orders",
  "event": "update",
  "time": 1541505434,
  "result": [
    {
      "contract": "BTC_USD",
      "user": "200XX",
      "create_time": 1545141817,
      "create_time_ms": 1545141817123,
      "fill_price": 4120,
      "finish_as": "filled",
      //close reason
      "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
    }
  ]
}

Notify user orders information when an order is put, updated or finished.

Notify

update

For the meaning of parameters, please refer to http interface.

field type description
result Array Array of objects
field type description
create_time Integer
create_time_ms Integer create unix timestamp in milliseconds
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 order update unix timestamp in milliseconds
finish_time_ms Integer order update unix timestamp in milliseconds
user String
contract String

Cancel subscription

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

The above command returns JSON structured like this:

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

Unubscribe user orders update notification, for all contract.

Request

Usertrades API

Provides a way to receive user trades.

Usertrades subscription


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

The above command returns JSON structured like this:

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

Subscribe for user trades update.

Request

Usertrades notification

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

Notify usertrades update.

Notify

update

field type description
result Array Array of objects
field type description
contract String futures contract name
create_time Integer create time
create_time_ms Integer create time in milliseconds
id String trades id
order_id String Order Id
price String price
size Integer trades size
role String user role (maker/taker)

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe usertrades update.

Request

Liquidates API

Provides a way to receive user liquidates info.

Liquidates subscription


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

The above command returns JSON structured like this:

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

Subscribe for user liquidates update.

Request

Liquidates notification

    {
  "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_USD",
      "user": "1040"
    }
  ]
}

Notify liquidates update.

Notify

update

field type description
result Array Array of objects
field type description
entry_price Float average entry price
fill_price Float average execution price
leverage Float leverage
liq_price Float liquidates price
margin Float margin
mark_price Float mark price
order_id Integer order id
order_price Float commission price
left Integer order unfilled quantity
size Integer position original size
time Integer time
time_ms Integer time in milliseconds
user String user id
contract String futures contract name

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe liquidates update.

Request

Auto_deleverages API

Provides a way to receive user auto deleverages info.

Auto_deleverages subscription


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

The above command returns JSON structured like this:

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

Subscribe for user auto_deleverages update.

Request

Auto_deleverages notification

    {
  "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_USD",
      "user": "1040"
    }
  ]
}

Notify auto_deleverages update.

Notify

update

field type description
result Array Array of objects
field type description
entry_price Float entry price
fill_price Float execution price
position_size Integer position size
trade_size Integer trade size
time Integer time
time_ms Integer time in milliseconds
user String user id
contract String futures contract name

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe auto_deleverages update.

Request

Position_closes API

Provides a way to receive user position closes info.

Position_closes subscription


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

The above command returns JSON structured like this:

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

Subscribe for user position_closes update.

Request

Position_closes notification

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

Notify position_closes update.

Notify

update

field type description
result Array Array of objects
field type description
contract String futures contract name
pnl Number profit & loss
side String side (long or short)
text String messages
time Integer time
time_ms Integer time in milliseconds
user String user id

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe position_closes update.

Request

Balances API

Provides a way to receive user balances info.

Balances subscription


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

The above command returns JSON structured like this:

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

Subscribe for user balances update.

Request

balances notification

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

Notify balances update.

Notify

update

field type description
result Array Array of objects
field type description
balance Number balance after changed
change Number change
text String messages
time Integer time
time_ms Integer time in milliseconds
type String type
user String user id

Cancel subscription


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

The above command returns JSON structured like this:

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

Reduce_risk_limits API

Provides a way to receive user reduce risk limits info.

Reduce_risk_limits subscription


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

The above command returns JSON structured like this:

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

Subscribe for user reduce_risk_limits update.

Request

Reduce_risk_limits notification

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

Notify reduce risk limits update.

Notify

update

field type description
result Array Array of objects
field type description
cancel_orders Number cancel orders
contract String contract name
leverage_max Number leverage max
liq_price Number liquidates price
maintenance_rate Number maintenance rate
risk_limit Number risk limit
time Number time
time_ms Number time in milliseconds
user String user id

Cancel subscription


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

Unsubscribe reduce risk limits update.

Request

Positions API

Provides a way to receive user positions info.

Positions subscription


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

The above command returns JSON structured like this:

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

Subscribe for user positions update.

Request

Positions notification

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

Notify positions update.

Notify

update

field type description
result Array Array of objects
field type description
contract String futures contract name
entry_price Number watch http api
history_pnl Number watch http api
history_point Number watch http api
last_close_pnl Number watch http api
leverage Number watch http api
leverage_max Number watch http api
liq_price Number watch http api
maintenance_rate Number watch http api
margin Number watch http api
realised_pnl Number watch http api
realised_point Number watch http api
risk_limit Number watch http api
size Number contract size
time Number update unix timestamp
time_ms Number update unix timestamp in milliseconds
user String user id

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe positions update.

Request

Autoorders API

Provides a way to receive user autoorders info.

Autoorders subscription


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

The above command returns JSON structured like this:

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

Subscribe for user autoorders update.

Request

Autoorders notification

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

Notify autoorders update.

Notify

Cancel subscription


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

The above command returns JSON structured like this:

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

Unsubscribe autoorders update.

Request