Websocket API v2

What Is WebSocket?

WebSocket is a protocol providing full-duplex communications channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011, and the WebSocket API in Web IDL is being standardized by the W3C.

Connection

Bitstamp by Robinhood uses its implementation of websocket server for real time data streaming. Server is accessible on the following address: wss://ws.bitstamp.net.

Documentation about websocket protocol can be found on the following link: https://websockets.readthedocs.io/en/stable/.

Once you open a connection via websocket handshake (using HTTP upgrade header), you can subscribe to desired channels.

After this is accomplished, you will start to receive a stream of live events for every channel you are subscribed to.

Subscriptions

Public channels

To subscribe to a channel, JSON message must be sent to the server. It should have a following structure:

{
    "event": "bts:subscribe",
    "data": {
        "channel": "[channel_name]"
    }
}

Private channels

To subscribe to a channel, JSON message must be sent to the server. It should have a following structure:

{
    "event": "bts:subscribe",
    "data": {
        "channel": "[channel_name]-[user-id]", "auth": "[token]"
    }
}

Token value and user id are generated via HTTP API. See Websockets token section of HTTP API documentation here.

Unsubscriptions

You can also unsubscribe from the channel if you no longer need its stream. Again, you need to send a message to the server.

Its structure is nearly identical to the subscription JSON:

{
    "event": "bts:unsubscribe",
    "data": {
        "channel": "[channel_name]"
    }
}

Note: Messages described and defined in this article are the only ones that will be processed by the server. Any other form of message or correct form of message with unexpected content will result in an error response.

Channels

Markets: 1incheur, 1inchusd, aavebtc, aaveeur, aaveusd, adaeur, adausd, algoeur, algousd, ampeur, ampusd, apeeur, apeusd, arbeur, arbusd, astereur, asterusd, audioeur, audiousd, avaxeur, avaxusd, avnteur, avntusd, axseur, axsusd, bateur, batusd, bcheur, bchusd, bioeur, biousd, blureur, blurusd, bnbeur, bnbusd, bomeeur, bomeusd, bonkeur, bonkusd, btceur, btceurc, btceurcv, btcgbp, btcrlusd, btcusd, btcusd-perp, btcusdc, btcusdt, chzeur, chzusd, compeur, compusd, coreumeur, coreumusd, crveur, crvusd, cspreur, csprusd, ctsieur, ctsiusd, ctxeur, ctxusd, cxteur, cxtusd, daiusd, dogeeur, dogeusd, dogeusd-perp, doteur, dotusd, egldeur, egldusd, enaeur, enausd, enjeur, enjusd, enseur, ensusd, etceur, etcusd, eth2eth, ethbtc, etheur, etheurc, etheurcv, ethgbp, ethrlusd, ethusd, ethusd-perp, ethusdc, ethusdt, eurceur, eurcusdc, eurcveur, eurcvusdc, eurcvusdt, eurusd, fartcoineur, fartcoinusd, feteur, fetusd, flokieur, flokiusd, flreur, flrusd, ftmeur, ftmusd, galaeur, galausd, gbpusd, grteur, grtusd, gyenusd, hbareur, hbarusd, hypeeur, hypeusd, icpeur, icpusd, imxeur, imxusd, injeur, injusd, jupeur, jupusd, knceur, kncusd, ldoeur, ldousd, linkeur, linkgbp, linkusd, lmwreur, lmwrusd, lrceur, lrcusd, ltcbtc, ltceur, ltcusd, manaeur, manausd, melaniaeur, melaniausd, meweur, mewusd, mkreur, mkrusd, mogeur, mogusd, moneur, monusd, moodengeur, moodengusd, neareur, nearusd, ondoeur, ondousd, opeur, opusd, pendleeur, pendleusd, pengueur, penguusd, pepeeur, pepeusd, perpeur, perpusd, pnuteur, pnutusd, poleur, polusd, popcateur, popcatusd, pytheur, pythusd, pyusdeur, pyusdusd, rlusdeur, rlusdusd, rlusdusdt, rndreur, rndrusd, sandeur, sandusd, seieur, seiusd, sgdusd, shibeur, shibusd, skleur, sklusd, smteur, smtusd, snxeur, snxusd, soleur, solusd, solusd-perp, solusdc, spkeur, spkusd, storjeur, storjusd, strkeur, strkusd, suieur, suiusd, suiusd-perp, sushieur, sushiusd, syrupeur, syrupusd, taieur, taiusd, toneur, tonusd, traceur, tracusd, trufeur, trufusd, trumpeur, trumpusd, umaeur, umausd, unieur, uniusd, usdceur, usdcusd, usdcusdt, usdteur, usdtusd, vchfeur, vchfusd, veureur, veurusd, virtualeur, virtualusd, wbtcbtc, wecaneur, wecanusd, weneur, wenusd, wifeur, wifusd, wlfieur, wlfiusd, wooeur, woousd, xchngeur, xchngusd, xcneur, xcnusd, xdceur, xdcusd, xlmeur, xlmgbp, xlmusd, xpleur, xplusd, xrpbtc, xrpeur, xrpgbp, xrprlusd, xrpusd, xrpusd-perp, xrpusdc, xrpusdt, xsgdusd, xsgdusdt, yfieur, yfiusd, zetaeur, zetausd, zoraeur, zorausd, zrxeur, zrxusd, zusdusd

Below tables include definitions of all existing channels you can subscribe to. Replacing [channel_name] placeholder in one of JSON messages defined in previous paragraphs will subscribe or unsubscribe you to a channel. You also need to replace the [market] placeholder with one of the markets defined above.

Public channels

Private channels

Channel JSON structure

Live ticker - JavaScript example: live_trades_v2.html

Live order book - JavaScript example: order_book_v2.html

Live detail order book

Live full order book - JavaScript example: diff_order_book_v2.html

Live orders - JavaScript example: live_orders_v2.html

Live funding rate

Private My Orders

Private My Trades

Private My Settlements

Private Live Trades

Note: Private-live_trades channels only broadcast self_trade events. Self-trade events occur when orders from the same client are matched against each other and offset against each other instead of executing as a trade due to self-trading prevention.

Private Liquidations

Other technical information

1. Heartbeat

If you wish to determine that websocket server is responsive, you should do so by websocket heartbeat. This is a form of control message or "PING / PONG" communication. You can do so by sending the following JSON message to the server:

{
    "event": "bts:heartbeat"
}

2. Forced reconnection

In case of websocket server you are currently connected to is to go under maintenance, you will receive a warning message asking you to reconnect. Such a message will look like this:

{
    "event": "bts:request_reconnect",
    "channel": "",
    "data": ""
}

After you receive this request, you will have a few seconds to reconnect. Without doing so, you will automatically be disconnected. If you send reconnection request, you will be placed to a new server. Consequentially, you can continue without any message loss.

3. Maximum connection age

Maximum connection age is 90 days from the time the connection is established. When that period of time elapses, you will be automatically disconnected and will need to re-connect.