NAV Navbar
Python JavaScript
  • General
  • Public channels
  • System API
  • Ticker API
  • Trade API
  • Depth API
  • Kline API
  • Private channels
  • Auth API
  • Order API
  • Balance API
  • General

    Introduction

    gate.io provides a simple and robust Websocket API to integrate gate.io trade status into your business or application.

    We have language bindings in JavaScript and Python, more in 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 3.1.

    Current API doc is built at 2018-11-14.19:17:45

    Server URL

    We provide two alternative server urls, you can choose one of them according to your condition.

    In code examples, we use ws.gate.io/v3 to present.

    API Overview

    Method

    Each general api (such as ticker, depth, kline, etc) supports 4 different method messages, they are:

    1. query

      Active inquiry information of gate.io trade status. e.g. ticker.query

    2. subscribe (RECOMMENDED TO USE)

      Subscribe to receive notification from server when new data is available. e.g. ticker.subscribe

    3. unsubscribe

      Server will not send new data notification if unsubscribed. e.g. ticker.unsubscribe

    4. update (CLIENT SHOULD NEVER SEND)

      If new subscribed data is avalilable, server will send a notificaiton to client. e.g. ticker.update

    Request

    Each request follows a common format, which contains id, method and params.

    Server doesn't have strict restriction for request ID, but we strongly recommend you use different id for different api in one websocket connection.

    parameter type required description
    id Integer Yes the request ID
    method String Yes the method of request
    params Array Yes detail parameters

    Response

    Similar with request, response follows a common format compose of id, error and result.

    field type description
    id Integer corresponding to request ID
    error JSON object null for success
    object with code and message for failure
    result JSON object result object, null for failure

    Notification

    A notification message is sent for subscribed channels.

    parameter type required description
    id null Yes the request id, null for notification
    method String Yes method
    params Array Yes 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
    2 internal error
    3 service unavailable
    4 method not found
    5 service timeout

    Authentication

    User can connect pulbic channels without any particular authentication.

    For private channels, gate.io provides a signature based authentication method. See Auth API for detail.

    Limitation

    System API

    Provides system status check, such as ping-pong and server time query.

    Ping

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'server.ping');
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"server.ping", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
      "error": null,
      "result": "pong",
      "id": 1000
    }
    

    Check server connectivity.

    Request

    Response

    Time

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'server.time');
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"server.time", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
       "error": null,
       "result": 1523348055,
       "id": 12312
    }
    

    Acquire server time.

    Request

    Response

    Ticker API

    The ticker is a high level overview of the state of the market. 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.

    Ticker query

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'ticker.query', ["EOS_USDT", 86400]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"ticker.query", "params":["EOS_USDT", 86400]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null,
        "result": {
            "period": 86400,
            "open": "5.9606",
            "close": "5.9606",
            "high": "5.9606",
            "low": "5.9606",
            "last": "5.9606",
            "change": "0",
            "quoteVolume": "4",
            "baseVolume": "23.8424"
        },
        "id": 12312
    }
    

    Query ticker of specified market, including price, deal volume etc in certain period.

    Request

    Response

    Ticker subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'ticker.subscribe', ["BOT_USDT"]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"ticker.subscribe", "params":["BOT_USDT"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Subscribe market ticker.

    Request

    Ticker notification

    The above command returns JSON structured like this:

    {
        "method": "ticker.update", 
        "params": 
            [
                "BOT_USDT", 
                    {
                        "period": 86400, 
                        "open": "0",
                        "close": "0",
                        "high": "0",
                        "low": "0",
                        "last": "0.2844",
                        "change": "0",
                        "quoteVolume": "0",
                        "baseVolume": "0"
                    }
         ],
         "id": null
    }
    

    Notify subscribed market ticker.

    Notify

    Cancel subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'ticker.unsubscribe', []);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"ticker.unsubscribe", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Unsubscribe market ticker.

    Request

    Trade 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 query

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'trade.query', ["EOS_USDT", 2, 7177813]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12309, "method":"trades.query", "params":["EOS_USDT", 2, 7177813]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null,
        "result": [
            {
                "id": 7177814,
                "time": 1523887673.562782,
                "price": "6.05",
                "amount": "20",
                "type": "buy"
            },
            {
                "id": 7177813,
                "time": 1523887354.256974,
                "price": "6.05",
                "amount": "15",
                "type": "buy"
            },
        ],
        "id": 12309
    }
    

    Query latest trades information, including time, price, amount, type and so on.

    Request

    Response

    Trades subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'trades.subscribe', ["ETH_USDT", "BTC_USDT"]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"trades.subscribe", "params":["ETH_USDT", "BTC_USDT"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Subscribe trades update notification.

    Request

    Trades notification

    The above command returns JSON structured like this:

    {
        "method": "trades.update",
        "params": 
            [
                 "ETH_USDT", 
                 [
                     {
                     "id": 7172173,
                     "time": 1523339279.761838,
                     "price": "398.59",
                     "amount": "0.027",
                     "type": "buy"
                     }
                 ]
             ],
         "id": null
     }
    
    

    Notify latest trades update.

    Notify

    Cancel subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'trades.unsubscribe', []);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"trades.unsubscribe", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Unsubscribe trades update notification.

    Request

    Depth API

    The depth 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.

    Query depth

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'depth.query', ["EOS_USDT", 5, "0.0001"]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"depth.query", "params":["EOS_USTD", 5, "0.0001"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

     {
        "error": null,
        "result": {
            "asks": [
                [
                    "15.72",
                    "811.7089610788"
                ],
                [
                    "15.76",
                    "18.45"
                ]
            ],
            "bids": [
                [
                    "15.71",
                    "1544.941002"
                ],
                [
                    "15.7",
                    "355.017"
                ]
            ]
        },
        "id": 12312
    }
    

    Query specified market depth.

    Request

    Response

    Depth subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    // single-market mode subscription
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'depth.subscribe', ["ETH_USDT", 5, "0.0001"]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    // ----------------------------------------------------------------------------------
    // If you want to subscribe multi market depth, just replace socket.onopen as below.
    // ----------------------------------------------------------------------------------
    // multi-market mode subscription
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'depth.subscribe', [["BTC_USDT", 5, "0.01"], ["ETH_USDT", 5, "0"]]);
    };
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    # single-market mode subscription
    ws.send('{"id":12312, "method":"depth.subscribe", "params":["ETH_USDT", 5, "0.0001"]}')
    print(ws.recv())
    
    # ---------------------------------------------------------------------------------
    # If you want to subscribe multi market depth, just replace ws.send as below.
    # ---------------------------------------------------------------------------------
    # multi-market mode subscription
    ws.send('{"id":12312, "method":"depth.subscribe", "params":[["BTC_USDT", 5, "0.01"], ["ETH_USDT", 5, "0"]]}')
    print(ws.recv())
    

    The above command(Both single-market and multi-market mode) returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Subscribe depth.

    Request

    Depth notification

    The above command returns JSON structured like this:

    {
        "method": "depth.update", 
        "params": [
            true, 
            {
                "asks": [
                    [                    
                        "8000.00",
                        "9.6250"
                    ]
                ],
                "bids": [                
                    [                    
                        "8000.00",
                        "9.6250"
                    ]                
                ]
             }, 
             "EOS_USDT"
        ],
        "id": null
     }
    

    Notify market depth update information

    Notify

    Cancel subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'depth.unsubscribe', []);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"depth.unsubscribe", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    

    Unsbscribe specified market depth.

    Request

    Kline API

    Provides a way to access charting candlestick info.

    Kline query

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'kline.query', ["BTC_USDT", 1, 1516951219, 1800]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"kline.query", "params":["BTC_USDT", 1, 1516951219, 1800]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": [
            [
                1492358400, time
                "7000.00",  open
                "8000.0",   close
                "8100.00",  highest
                "6800.00",  lowest
                "1000.00"   volume
                "123456.00" amount
                "BTC_USDT"  market name
            ]
            ...
        ]
        "id": 12312
    }
    

    Query specified market kline information

    Request

    Response

    Kline subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'kline.subscribe', ["BTC_USDT", 1800]);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"kline.subscribe", "params":["BTC_USDT", 1800]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
            {
            "status": "success"
            }, 
        "id": 12312
    }
    

    Subscribe specified market kline information.

    Request

    Kline notification

    The above command returns JSON structured like this:

    {
        "method": "kline.update",
        "params":
            [
                [
                    1492358400, time
                    "7000.00",  open
                    "8000.0",   close
                    "8100.00",  highest
                    "6800.00",  lowest
                    "1000.00"   volume
                    "123456.00" amount
                    "BTC_USDT"  market name
                ]
            ]
        "id": null
    }
    

    Notify kline information of subscribed market.

    Notify

    Cancel subscription

    function socket_send_cmd(socket, cmd, params) {
        if (!params) 
        params = [];
        var msg = {
        id: client_id,
        method: cmd,    
        params: params
        };
        socket.send(JSON.stringify(msg));
    }
    
    var socket = new WebSocket('wss://ws.gate.io/v3');
    
    socket.onopen = function () {
        console.log("Connected");
        socket_send_cmd(socket, 'kline.unsubscribe', []);
    };
    socket.onmessage = function (e) {
        console.log('Server: ' + e.data);
    }
    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"kline.unsubscribe", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    

    Unsubsribe specified market kline information.

    Request

    Auth API

    import hmac
    import base64
    import hashlib
    
    secret_key = 'your secret key'
    
    def get_sign(secret_key, message):
        h = hmac.new(secret_key, message, hashlib.sha512)
        return base64.b64encode(h.digest())
    

    gate.io provides a signature based authorization on private channels.

    The algorithm can be simply described as below pseudo code.

    base64(hmac_sha512(secret_key, nonce))

    You can refer to code example at the right.

    Send authentication

    import json
    import time
    from websocket import create_connection
    
    api_key = 'your api key'
    secret_key = 'your secret key'
    
    ws = create_connection("wss://ws.gate.io/v3/")
    
    nonce = int(time.time() * 1000)
    signature = get_sign(secret_key, str(nonce))
    
    ws.send(json.dumps({
        "id": 12312, 
        "method": "server.sign",
        "params": [api_key, signature, nonce]
        })
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Signature based authorization.

    Request

    parameter type required description
    apikey String yes user apikey
    signature String yes user sign data
    nonce Integer yes timestamp, for milliseconds spent from Unix epoch to current time

    Order API

    Order query

    
    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"order.query", "params":["EOS_USDT", 0, 10]}')
    print (ws.recv())
    

    The above command returns JSON structured like this:

    {
        "result": {
            "limit": 10,
            "offset": 0,
            "total": 1, 
            "records": [{
                "id": 796563387, 
                "market": "EOS_USDT", 
                "user": 1336974, 
                "ctime": 1527082744.51649, 
                "mtime": 1527082744.51649, 
                "price": "0.1", 
                "amount": "100", 
                "left": "100", 
                "dealFee": "0", 
                "orderType": 1,
                "type": 2,
                "filledAmount": "0",
                "filledTotal": "0"
            }]
        },
        "error": null, 
        "id": 12312
    }
    

    Query user unexecuted orders

    Request

    Response

    Order subscription

    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"order.subscribe", "params":["EOS_USDT"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Subscribe user orders update

    Request

    Order notification

    The above command returns JSON structured like this:

    {
      "method": "order.update",
      "params": [
        3,
        {
          "id": 34628963,
          "market": "EOS_USDT",
          "orderType": 1,
          "type": 2,
          "user": 602123,
          "ctime": 1523013969.6271579,
          "mtime": 1523013969.6271579,
          "price": "0.1",
          "amount": "1000",
          "left": "1000",
          "filledAmount": "0",
          "filledTotal": "0",
          "dealFee": "0",
        }
      ],
      "id": null
    }
    

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

    Notify

    order.update

    Response

    Cancel subscription

    from websocket import create_connection
    ws = create_connection("wss://ws_server_host/v3/websocket/")
    ws.send('{"id":12312, "method":"order.unsubscribe", "params":["EOS_USDT"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Unubscribe user orders update notification, for all markets.

    Request

    Balance API

    Balance query

    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"balance.query", "params":[]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null,
        "result": {
            "EOS": {
                "available": "13200.82187609",
                "freeze": "0"
            }
        },
        "id": 12312
    }
    

    Acquire user balance information of specified asset or assets.

    Request

    Response

    Balance subscription

    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"balance.subscribe", "params":["EOS"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Subscribe for user balance update.

    Request

    Balance notification

    The above command returns JSON structured like this:

    {
        'method': 'balance.update', 
        'params': [{'EOS': {'available': '96.765323611874', 'freeze': '11'}}],
        'id': None
    }
    

    Notify user balance update.

    Notify

    Cancel subscription

    from websocket import create_connection
    ws = create_connection("wss://ws.gate.io/v3/")
    ws.send('{"id":12312, "method":"balance.unsubscribe", "params":["EOS"]}')
    print(ws.recv())
    

    The above command returns JSON structured like this:

    {
        "error": null, 
        "result": 
        {
            "status": "success"
        },
        "id": 12312
    }
    
    

    Unsubscribe user balance update.

    Request