# WebSocket API v2

## What Is WebSocket?

WebSocket is a protocol providing full-duplex communication channels over a single TCP connection.  
Standardized by the IETF as **RFC 6455 (2011)** and by the W3C (WebSocket API).

---

## Connection

Bitstamp WebSocket endpoint:


wss://ws.bitstamp.net


Documentation:  
https://websockets.readthedocs.io/en/stable/

After establishing a connection (HTTP upgrade → WebSocket), you can subscribe to channels and receive live event streams.

---

## Subscriptions

### Public Channels

```json
{
  "event": "bts:subscribe",
  "data": {
    "channel": "[channel_name]"
  }
}
Private Channels
{
  "event": "bts:subscribe",
  "data": {
    "channel": "[channel_name]-[user-id]",
    "auth": "[token]"
  }
}
token and user-id are generated via HTTP API.
Unsubscriptions
{
  "event": "bts:unsubscribe",
  "data": {
    "channel": "[channel_name]"
  }
}

⚠️ Only valid message formats are processed — invalid messages return errors.

Channels
Public Channels
Name	Event	Channel
Live ticker	trade	live_trades_[market]
Live orders	order_created / changed / deleted	live_orders_[market]
Order book	data	order_book_[market]
Detail order book	data	detail_order_book_[market]
Full order book	data	diff_order_book_[market]
Funding rate	funding_rate_saved	funding_rate_[market]
Private Channels
Name	Event	Channel
My Orders	order events + stop events	private-my_orders_[market]-[userId]
My Trades	trade	private-my_trades_[market]-[userId]
My Settlements	settlement	private-my_settlements-[userId]
Live Trades	self_trade	private-live_trades_[market]-[userId]
Liquidations	liquidation + margin alerts	private-my_liquidations-[userId]
Channel Data Structures
Live Trades
Field	Description
id	Trade ID
amount	Trade amount
price	Trade price
type	0 = buy, 1 = sell
timestamp	Trade timestamp
Order Book
Field	Description
bids	Top 100 bids
asks	Top 100 asks
timestamp	Timestamp
Detail Order Book
Field	Description
bids	[price, amount, order_id]
asks	[price, amount, order_id]
Full Order Book (Diff)
Field	Description
bids	Changed bids
asks	Changed asks
Live Orders

Includes:

id, amount, price
order_type (0 = buy, 1 = sell)
order_subtype (limit, market, stop, etc.)
datetime, microtimestamp
event_id, pre_event_id
Funding Rate
Field	Description
funding_rate	Rate
mark_price	Mark price
index_price	Index price
next_funding_time	Next funding
Private My Orders

Includes:

id, amount, price
client_order_id
order_type, order_subtype
stop_price, activation_price
reduce_only
event_id
Private My Trades
Field	Description
id	Trade ID
order_id	Linked order
amount	Trade amount
price	Trade price
fee	Fee
side	buy / sell
Private My Settlements
Field	Description
id	Position ID
price	Settlement price
ccy	Currency
Private Live Trades

Self-trade events only.

Field	Description
buy_order_id	Buy order
sell_order_id	Sell order
amount	Amount
price	Price
Private Liquidations
Field	Description
position_id	Position ID
alert_type	Liquidation stage
margin_mode	ISOLATED / CROSS
initial_margin_ratio	Initial margin
maintenance_margin_ratio	Maintenance margin
Technical Notes
1. Heartbeat
{
  "event": "bts:heartbeat"
}

Used to verify server responsiveness (PING/PONG).

2. Forced Reconnection
{
  "event": "bts:request_reconnect",
  "channel": "",
  "data": ""
}

Reconnect within a few seconds to avoid disconnection.

3. Maximum Connection Age
Max duration: 90 days
After that → automatic disconnect → reconnect required