NAV Navbar
Python JavaScript

Changelog

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 2019-04-30 11:35:49

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,
            "price":"96.4",
            "contract":"BTC_USD"
        }]
}

Notify latest trades 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.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

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.

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",
        "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,  // +-   asks:- 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,
                "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,
                "tkfr":0.00075
            }
        ],
    }

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

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.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,
                "id": "12651269",
                "order_id": "56945246",
                "price": "113.6",
                "size": 10,
                "role": "maker" // taker
            }
        ]
    }

Notify usertrades 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.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,
                "contract":"BTC_USD",
                "user":"1040"
        },]
    }

Notify liquidates 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.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, // int
                "trade_size" : 10 // int
                "time":1541486601,
                "contract":"BTC_USD",
                "user":"1040"
        },]
    }

Notify auto_deleverages 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.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,
                "user":"20011"
        },]
    }

Notify position_closes 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.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,
                "type":"fee",
                "user":"20011"
        },]
    }

Notify balances 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.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,
      "user": "20011"
    }
  ]
}

Notify reduce risk limits 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.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