BTSE · AsyncAPI Specification
Futures WebSocket API
Version 3.2.0
Futures WebSocket streams for real-time market data and private user events. **OSS Endpoint (Orderbook):** `wss://ws.btse.com/ws/oss/futures` **Main Endpoint:** `wss://ws.btse.com/ws/futures` **Testnet OSS:** `wss://testws.btse.io/ws/oss/futures` **Testnet Main:** `wss://testws.btse.io/ws/futures` **Authentication:** Private topics require sending an `authKeyExpires` message with HMAC-SHA384 signature: `HMAC-SHA384(secret, "/ws/futures" + nonce)`
View Spec
View on GitHub
CompanyCryptocurrencyExchangeTradingDigital AssetsFuturesWebSocketAsyncAPIEventsWebSockets
Channels
ping
Ping
Send a plain text `ping` to keep the connection alive. The server responds with `pong`.
subscription
Subscribe / Unsubscribe
Subscribe or unsubscribe from any topic.
auth
WebSocket Authentication
Authenticate the session to access private topics (Notifications, User Trade Fills, Positions). Signature: `HMAC-SHA384(secret, "/ws/futures" + nonce)`
snapshotL1:{symbol}
Subscribe to the best bid / best ask (Level 1) for a market. **Topic format:** `snapshotL1:` (e.g. `snapshotL1:BTC-PERP`) Each message is a full snapshot of the current best bid / best ask. The `bids` and `asks` arrays each contain a single `[price, size]` tuple representing the top of book, and the `type` field is always `snapshotL1`. Bids and asks are sent in `price` and `size` tuples as strings to preserve precision; clients should parse them with a high-precision type (e.g. `BigDecimal`, `decimal.js`) before performing arithmetic. Because every push is a full snapshot, clients can simply overwrite the local copy on each message — there is no sequence number, and no delta merging is required. If the connection drops, re-subscribe to the topic to resume receiving updates.
update:{symbol}_{grouping}
Subscribe to orderbook incremental updates through the `update` topic. **Topic format:** `update:_` (e.g. `update:BTC-PERP_0`) The `_grouping` suffix represents the granularity of price-level aggregation. Valid values are `0` to `8`. If the suffix is omitted (e.g. `update:BTC-PERP`), `_0` is used by default. Different grouping values produce independent topic subscriptions and caches. The first response received will be a snapshot of the current orderbook (indicated by the `type` field) with up to 50 levels. Incremental updates will be sent in subsequent packets with type `delta`. Bids and asks will be sent in `price` and `size` tuples. The size sent will be the new updated size for the price. If a value of `"0"` is sent, the price should be removed from the local copy of the orderbook. To ensure that the updates are received in sequence, `seqNum` indicates the current sequence and `prevSeqNum` refers to the packet before. `seqNum` will always be one after the `prevSeqNum`. If the sequence is out of order, unsubscribe and re-subscribe to the topic again. Also, if a [crossed orderbook](https://en.wikipedia.org/wiki/Order_book#Crossed_book) ever occurs (best bid is higher than or equal to best ask), unsubscribe and re-subscribe to the topic again.
tradeHistoryApiV3:{symbol}
Public Trade Fills
Real-time public trade feed for a market. **Topic:** `tradeHistoryApiV3:` — no authentication required.
notificationApiV4
Notifications
Real-time order status updates. Requires WebSocket authentication. **Topic:** `notificationApiV4` Carries the full v2.3 size set (`originalOrderSize`, `currentOrderSize`, `filledSize`, `totalFilledSize`, `remainingSize`) plus `positionId` and `postOnly`, so partial fills and post-only orders are represented faithfully.
fillsV2
User Trade Fills
Notification whenever a trade is executed for the authenticated user. Requires WebSocket authentication. **Topic:** `fillsV2`
allPositionV4
All Position
Pushed whenever any position changes. Requires WebSocket authentication. **Topic:** `allPositionV4`
positionsV3
Positions
Pushed when a position changes. Includes a zero-value snapshot when a position is closed. Requires WebSocket authentication. **Topic:** `positionsV3` Response structure is the same as All Position with additional raw internal fields.
Messages
L1Subscribe
L1Subscribe
L1Unsubscribe
L1Unsubscribe
L2Subscribe
L2Subscribe
L2Unsubscribe
L2Unsubscribe
OrderbookSnapshot
OrderbookSnapshot
OrderbookDelta
OrderbookDelta
PublicTradeMessage
PublicTradeMessage
NotificationMessage
NotificationMessage
UserFillMessage
UserFillMessage
AllPositionMessage
AllPositionMessage
Servers
wss
oss-production
wss://ws.btse.com/ws/oss/futures
Production — Order Stream Service (orderbook data)
wss
oss-testnet
wss://testws.btse.io/ws/oss/futures
Testnet — Order Stream Service
wss
main-production
wss://ws.btse.com/ws/futures
Production — Main WebSocket (trades, auth, notifications)
wss
main-testnet
wss://testws.btse.io/ws/futures
Testnet — Main WebSocket
AsyncAPI Specification
Work with this as data
Every AsyncAPI spec here is available over the APIs.io API and to AI agents over MCP.