From e67100888f614a372b5f34526656878458be9c7e Mon Sep 17 00:00:00 2001
From: Nour Alharithi <nour.alharithi@gmail.com>
Date: Sat, 16 Dec 2023 09:24:55 -0800
Subject: [PATCH] websockets

---
 source/includes/_websockets.md | 84 ++++++++++++++++++++++++++++++++++
 source/index.html.md           |  1 +
 2 files changed, 85 insertions(+)
 create mode 100644 source/includes/_websockets.md

diff --git a/source/includes/_websockets.md b/source/includes/_websockets.md
new file mode 100644
index 0000000..64b77eb
--- /dev/null
+++ b/source/includes/_websockets.md
@@ -0,0 +1,84 @@
+# Websockets
+
+Drift currently offers websocket streaming for two data streams: orderbooks and trades. The data streams are constructed from blockhain data. More data sources and user specific feeds will be added as this functionality is expanded.
+
+mainnet-beta: `wss://dlob.drift.trade/ws`
+
+devnet: `wss://master.dlob.drift.trade/ws`
+
+## Subscribing
+
+Clients must send subscribe messages over the websocket connection in order to start receiving messages.
+
+### Orderbook
+
+Each market currently requires its own subscribe message. The two examples below show subscribe messages for a perp and spot market:
+
+#### Perp markets
+`
+{
+  type: 'subscribe',
+  marketType: 'perp',
+  channel: 'orderbook',
+  market: 'SOL-PERP'
+}
+`
+
+#### Spot markets
+`
+{
+  type: 'subscribe',
+  marketType: 'spot',
+  channel: 'orderbook',
+  market: 'SOL'
+}
+`
+
+#### Update frequency
+
+Currently, orderbook websockets send messages every 1000ms. Connections that contain frequent updates are coming soon.
+
+### Trades
+
+Trades feed subscribe messages take a similar form to orderbook data, just change the channel.
+
+#### Perp markets
+`
+{
+  type: 'subscribe',
+  marketType: 'perp',
+  channel: 'trades',
+  market: 'SOL-PERP'
+}
+`
+
+#### Spot markets
+`
+{
+  type: 'subscribe',
+  marketType: 'spot',
+  channel: 'trades',
+  market: 'SOL'
+}
+`
+
+## Unsubscribing
+
+To unsubscribe to a channel, send a subscribe-like message, with the message type set to `unsubscribe`. Unsubscribe requests to channels not previously subscribed to will have no impact.
+
+## Liveness measure
+
+To alleviate backpressure on websocket servers, drift websockets stop sending messages to clients that have more than 50 messages unproccessed in their buffer, until the buffer is cleared and the messages are processed. We recommend listening for heartbeat messages from the server to determine if your client is still receiving messages. 
+
+Heartbeat messages are sent every 5 seconds and take the following form:
+`
+  {channel: 'heartbeat'}
+`
+
+### Ping/pong
+
+No ping messages are sent from the websocket server. Unsolicited ping messages are allowed and will receive pongs back.
+
+## Feedback
+
+For any feedback on websockets, please reach out on discord under the channel research-and-dev-chat
\ No newline at end of file
diff --git a/source/index.html.md b/source/index.html.md
index 50f5311..1250215 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -12,6 +12,7 @@ toc_footers:
 includes:
   - examples
   - historicaldata
+  - websockets
   - errors
 
 search: true