NAV Navbar
Python JavaScript Golang

Gate.io Futures WebSocket v4

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.

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.

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'], False)


if __name__ == "__main__":
  logging.basicConfig(format="%(asctime)s - %(message)s", level=logging.DEBUG)
  app = GateWebSocketApp("wss://fx-ws.gateio.ws/v4/ws/usdt",
                         "YOUR_API_KEY",
                         "YOUR_API_SECRET",
                         on_open=on_open,
                         on_message=on_message)
  app.run_forever(ping_interval=5)

package main

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

    "github.com/gorilla/websocket"
)

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

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

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

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

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

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

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

func main() {
    u := url.URL{Scheme: "wss", Host: "fx-ws.gateio.ws", Path: "/v4/ws/usdt"}
    websocket.DefaultDialer.TLSClientConfig = &tls.Config{RootCAs: nil, InsecureSkipVerify: true}
    c, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
    if err != nil {
        panic(err)
    }
    c.SetPingHandler(nil)

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

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

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

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

    select {}
}

2021-03-31

2021-03-10

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

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.

  1. unsubscribe

Server will not send new data notification if unsubscribed.

  1. update

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

  1. 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.

There are three different order book channels for subscription:

Legacy channel, which uses all to push full limited-level order book, and update to send every order book change event.

Push best bid and ask in real-time.

Push order book change with user-specified update frequency.

How to maintain local order book:

  1. Subscribe futures.order_book_update with specified level and update frequency, e.g. ["BTC_USDT", "1000ms", "10"] pushes the first 10 levels' update in BTC_USDT order book every 1s
  2. Cache WebSocket notifications. Every notification use U and u to tell the first and last update ID since last notification.
  3. Retrieve base order book using REST API, and make sure the order book ID is recorded(referred as baseID below) e.g. https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT&limit=10&with_id=true retrieves the 10-level base order book of BTC_USDT
  4. Iterate the cached WebSocket notifications, and find the first one which contains the baseID, i.e. U <= baseId+1 and u >= baseId+1, then start consuming from it. Note that sizes in notifications are all absolute values. Use them to replace original sizes in corresponding price. If size equals to 0, delete the price from the order book.
  5. Dump all notifications which satisfy u < baseID+1. If baseID+1 < first notification U, it means current base order book falls behind notifications. Start from step 3 to retrieve newer base order book.
  6. If any subsequent notification which satisfy U > baseID+1 is found, it means some updates are lost. Reconstruct local order book from step 3.

Legacy 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

Legacy order book notification

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

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

Legacy order book unsubscription


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

Unsubscribe specified contract order book.

Request

futures.order_book

unsubscribe

Best ask/bid subscription


from websocket import create_connection

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

The above command returns JSON structured like this:

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

Subscribe book_ticker.

Request

futures.book_ticker

subscribe

payload is an array contains contracts interested.

Best ask/bid notification

If a is empty string, it means empty asks; if b is empty string, it means empty bids.

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

Notify contract order book best bid and ask

Notify

futures.book_ticker

update

field type description
result object Best bid and ask
» t Integer Book ticker generated timestamp in milliseconds
» u String Order book update ID
» s Integer Contract name
» b String Best bid price. If no bids, it's empty string
» B Integer Best bid size. If no bids, it will be 0
» a String Best ask price. If no asks, it's empty string
» A Integer Best ask size. If no asks, it will be 0

Best ask/bid unsubscription


from websocket import create_connection

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

The above command returns JSON structured like this:

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

Unsubscribe specified contract order book.

Request

futures.book_ticker

unsubscribe

Order book update 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_update", "event": "subscribe", "payload" : ["BTC_USD", "1000ms", "20"]}')
print(ws.recv())

The above command returns JSON structured like this:

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

Subscribe order_book_update.

Request

futures.order_book_update

subscribe

parameter type required description
contract String Yes Contract name
frequency String Yes Update frequency, 100ms or 1000ms
level String No Optional level interested. Only updates within are notified. Allowed values: "20", "10" or "5"

Order book update notification

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

Notify contract order book update

Notify

futures.order_book_update

update

field type description
result object Changed asks and bids since last update
» t Integer Order book generation timestamp in milliseconds
» s Integer Contract name
» U Integer First order book update ID since last update
» u Integer Last order book update ID since last update
» b String Changed bids
»» p String Changed price
»» s String Absolute size value after change. If 0, remove this price from order book
» a String Changed asks
»» p String Changed price
»» s String Absolute size value after change. If 0, remove this price from order book

Order book update unsubscription


from websocket import create_connection

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

The above command returns JSON structured like this:

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

Unsubscribe specified contract order book.

Request

futures.order_book_update

unsubscribe

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