Skip to content

Latest commit

 

History

History
841 lines (681 loc) · 14.2 KB

public-websocket.md

File metadata and controls

841 lines (681 loc) · 14.2 KB

Public WebSocket API

Methods

Public WebSocket endpoint is wss://api.whitebit.com/ws

The API is based on JSON RPC of WebSocket protocol.

⚠️ Connection will be closed by server in cause of inactivity after 60s.

⤴️ Request message

JSON Structure of request message:

  • id - Integer. Should be unique to handle response for your request.
  • method - String. Name of request.
  • params - Array. Here you pass params for method.

🚫 WebSocket connection will be closed if invalid JSON was sent.

Types of request messages

  • Query (ping, candles_request, etc)
  • Subscription (candles_subscribe, lastprice_subscribe, etc). Repeated subscription will be cancelled for the same data type.

⤵️ Response message

JSON Structure of response message:

  • id - Integer. Id of request.
  • result - Null for failure, for success - look for responses below
  • error - Null for success, JSON Object for failure:
    • message - Detailed text
    • code - Error code
Code Message
1 invalid argument
2 internal error
3 service unavailable
4 method not found
5 service timeout

Types of response messages

  • Query result
  • Subscription status (success/failed)
  • Update events

Examples

Example messages for request with response:

⤴️ Request:

{
    "id": 0,
    "method": "ping",
    "params": []
}

⤵️ Response:

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

Example subscription:

⤴️ Request:

{
    "id": 0,
    "method": "candles_subscribe",
    "params": []
}

⤵️ Response:

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

🔄 Update events:

{
    "id": null,
    "method": "candles_update",
    "params": [] // look below for params 
}

API

Service

Ping

⤴️ Request:
{
    "id": 0,
    "method": "ping",
    "params": []
}
⤵️ Response:
{
    "id": 0,
    "result": "pong",
    "error": null
}

Time

⤴️ Request:
{
    "id": 1,
    "method": "time",
    "params": []
}
⤵️ Response:
{
    "id": 1,
    "result": 1493285895,
    "error": null
}

Kline

Query

⤴️ Request:
{
    "id": 2,
    "method": "candles_request",
    "params": [
        "ETH_BTC",  // market
        1579569940, // start time 
        1580894800, // end time 
        900         // interval in seconds 
    ]
}
⤵️ Response:
{
    "id": 2,
    "result": [
        [
            1580860800,       // time
            "0.020543",       // open
            "0.020553",       // close
            "0.020614",       // highest
            "0.02054",        // lowest
            "7342.597",       // volume in stock
            "151.095481849",  // volume in deal
            "ETH_BTC"         // market
        ],
        ...
    ],
    "error": null
}

Subscribe

⤴️ Request:
{
    "id": 3,
    "method": "candles_subscribe",
    "params": [
        "BTC_USD", // market
        900        // interval in seconds
    ]
}
⤵️ Response:
{
    "id": 3,
    "result": {
        "status": "success"
    },
    "error": null
}
🔄 Update events:
{
    "id": null,
    "method": "candles_update",
    "result": [
        1580895000,     // time
        "0.020683",     // open
        "0.020683",     // close
        "0.020683",     // high
        "0.020666",     // low
        "504.701",      // volume in stock
        "10.433600491", // volume in money (deal)
        "ETH_BTC"       // market
    ]
}

Unsubscribe

⤴️ Request:
{
    "id": 4,
    "method": "candles_unsubscribe",
    "params": []
}
⤵️ Response:
{
    "id": 4,
    "result": {
        "status": "success"
    },
    "error": null
}

Last price

Query

⤴️ Request:
{
    "id": 5,
    "method": "lastprice_request",
    "params": [
        "ETH_BTC", // market
    ]
}
⤵️ Response:
{
    "id": 5,
    "result": "0.020553",
    "error": null
}

Subscribe

⤴️ Request:
{
    "id": 6,
    "method": "lastprice_subscribe",
    "params": [
        "ETH_BTC", // markets
        "BTC_USDT",
        ...
    ]
}
⤵️ Response:
{
    "id": 6,
    "result": {
        "status": "success"
    },
    "error": null
}
🔄 Update events:
{
    "id": null,
    "method": "lastprice_update",
    "result": [
        "ETH_BTC",  // market
        "0.020683", // price
    ]
}

Unsubscribe

⤴️ Request:
{
    "id": 7,
    "method": "lastprice_unsubscribe",
    "params": []
}
⤵️ Response:
{
    "id": 7,
    "result": {
        "status": "success"
    },
    "error": null
}

Market statistics

Query

⤴️ Request:
{
    "id": 5,
    "method": "market_request",
    "params": [
        "ETH_BTC", // market
        86400      // period in seconds
    ]
}
⤵️ Response:
{
    "id": 5,
    "result": {
        "period": 86400,         // period in seconds 
        "last": "0.020981",      // last price
        "open": "0.02035",       // open price that was at 'now - period' time
        "close": "0.020981",     // price that closes this period
        "high": "0.020988",      // highest price
        "low": "0.020281",       // lowest price
        "volume": "135220.218",  // volume in stock
        "deal": "2776.587022649" // volume in money
    },
    "error": null
}

Subscribe

You can subscribe only for 86400s (24h from now).

⤴️ Request:
{
    "id": 6,
    "method": "market_subscribe",
    "params": [
        "ETH_BTC", // markets
        "BTC_USDT",
        ...
    ]
}
⤵️ Response:
{
    "id": 6,
    "result": {
        "status": "success"
    },
    "error": null
}
🔄 Update events:
{
    "id": null,
    "method": "market_update",
    "result": [
        "ETH_BTC",                   // market
         {                           // response same as 'market_request'
            "period": 86400,         // period in seconds 
            "last": "0.020964",      // last price
            "open": "0.020349",      // open price that was at 'now - period' time
            "close": "0.020964",     // price that closes this period
            "high": "0.020997",      // highest price
            "low": "0.020281",       // lowest price
            "volume": "135574.476",  // volume in stock
            "deal": "2784.413999488" // volume in money
        }
    ]
}

Unsubscribe

⤴️ Request:
{
    "id": 7,
    "method": "market_unsubscribe",
    "params": []
}
⤵️ Response:
{
    "id": 7,
    "result": {
        "status": "success"
    },
    "error": null
}

Market statistics for current day UTC

Query

⤴️ Request:
{
    "id": 14,
    "method": "marketToday_query",
    "params": [
        "ETH_BTC" // only one market per request
    ]
}
⤵️ Response:
{
    "id": 14,
    "result": {
        "last": "0.020981",      // last price
        "open": "0.02035",       // open price that was at 'now - period' time
        "high": "0.020988",      // highest price
        "low": "0.020281",       // lowest price
        "volume": "135220.218",  // volume in stock
        "deal": "2776.587022649" // volume in money
    },
    "error": null
}

Subscribe

⤴️ Request:
{
    "id": 15,
    "method": "marketToday_subscribe",
    "params": [
        "ETH_BTC", // markets
        "BTC_USDT",
        ...
    ]
}
⤵️ Response:
{
    "id": 15,
    "result": {
        "status": "success"
    },
    "error": null
}
🔄 Update events:
{
    "id": null,
    "method": "marketToday_update",
    "result": [
        "ETH_BTC",                   // market
         {                           // response same as 'market_request'
            "last": "0.020964",      // last price
            "open": "0.020349",      // open price that was at 'now - period' time
            "high": "0.020997",      // highest price
            "low": "0.020281",       // lowest price
            "volume": "135574.476",  // volume in stock
            "deal": "2784.413999488" // volume in money
        }
    ]
}

Unsubscribe

⤴️ Request:
{
    "id": 16,
    "method": "marketToday_unsubscribe",
    "params": []
}
⤵️ Response:
{
    "id": 16,
    "result": {
        "status": "success"
    },
    "error": null
}

Market trades

Query

⤴️ Request:
{
    "id": 8,
    "method": "trades_request",
    "params": [
        "ETH_BTC", // market
        100,       // limit
        41358445   // largest id from which you want to request trades
    ]
}
⤵️ Response:
{
    "id": 8,
    "result": [
        {
            "id": 41358530,           // trade id
            "time": 1580905394.70332, // time in milliseconds
            "price": "0.020857",      // trade price
            "amount": "5.511",        // trade amount
            "type": "sell"            // type of trade (buy/sell)
        },
        ...
    ],
    "error": null
}

Subscribe

⤴️ Request:
{
    "id": 9,
    "method": "trades_subscribe",
    "params": [
        "ETH_BTC", // markets
        "BTC_USDT",
        ...
    ]
}
⤵️ Response:
{
    "id": 9,
    "result": {
        "status": "success"
    },
    "error": null
}
🔄 Update events:
{
    "id": null,
    "method": "trades_update",
    "result": [
        "ETH_BTC",                         // market
         [                                 // response same as 'market_request'
             {                            
                 "id": 41358530,           // trade id
                 "time": 1580905394.70332, // time in milliseconds
                 "price": "0.020857",      // trade price
                 "amount": "5.511",        // trade amount
                 "type": "sell"            // type of trade (buy/sell)
             },
             ...
         ]
    ]
}

Unsubscribe

⤴️ Request:
{
    "id": 10,
    "method": "trades_unsubscribe",
    "params": []
}
⤵️ Response:
{
    "id": 10,
    "result": {
        "status": "success"
    },
    "error": null
}

Market depth

Query

⤴️ Request:
{
    "id": 11,
    "method": "depth_request",
    "params": [
        "ETH_BTC", // market
        100,       // limit, max value is 100
        "0"        // price interval units. "0" - no interval, available values - "0.00000001", "0.0000001", "0.000001", "0.00001", "0.0001", "0.001", "0.01", "0.1"
    ]
}
⤵️ Response:
{
    "id": 11,
    "result": {
        "asks": [                   // sorted ascending         
            ["0.020846", "29.369"], // [price, amount]
            ...
        ],
        "bids": [                   // sorted descending 
            ["0.02083", "9.598"],   // [price, amount]
            ...
        ]
    },
    "error": null
}

Subscribe

⤴️ Request:
{
    "id": 12,
    "method": "depth_subscribe",
    "params": [
        "ETH_BTC", // market
        100,       // limit, max value is 100
        "0"        // price interval units. "0" - no interval, available values - "0.00000001", "0.0000001", "0.000001", "0.00001", "0.0001", "0.001", "0.01", "0.1"
    ]
}
⤵️ Response:
{
    "id": 12,
    "result": {
        "status": "success"
    },
    "error": null
}
🔄 Update events:
{
    "id": null,
    "method": "depth_update",
    "result": [
        false,                          // true - full reload, false - partial update
        {
            "asks": [
                ["0.020861", "0"],      // for partial update - finished orders will be [price, "0"]
                ...
            ],
            "bids": [
                ["0.020844", "5.949"],
                ...
            ]
        },
        "ETH_BTC"                       // market
    ]
}

Unsubscribe

⤴️ Request:
{
    "id": 13,
    "method": "depth_unsubscribe",
    "params": []
}
⤵️ Response:
{
    "id": 13,
    "result": {
        "status": "success"
    },
    "error": null
}