> For the complete documentation index, see [llms.txt](https://docs.kanalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kanalabs.io/perpetual-futures/kana-perps/for-developers-and-mms/integrating-websockets.md).
# Integrating WebSockets
#### Important Note:
* To track transactions on-chain (e.g., via Aptos Explorer or Aptos Scan), you **must** use your [**profile address**](https://docs.kanalabs.io/perpetual-futures/kana-perps/for-developers-and-mms/pages/OKw87YCpbRTEWOkODG2z#id-1.-trade-profiles), as all on-chain trades are executed using this address.
* To obtain your profile address, call the **`/getProfileAddress`** endpoint with your wallet address as the `userAddress` parameter.
***
### WebSocket URLs
#### Testnet URL:
```
wss://perpetuals-indexer-ws-develop.kanalabs.io/ws/
```
#### Mainnet URL:
```
wss://perpetuals-indexer-ws.kana.trade/ws/
```
***
### Parameters to Subscribe:
To connect to a WebSocket and subscribe to the relevant topics, send a subscription message in the following format:
#### Example:
```json
{
"topic": "topic_name",
"address": "user_address"
"market_id": "market_id" (*only for getting orderbook)
}
```
You can replace `topic_name` with any of the supported topics (listed below), and `user_address` with your [profile address](https://docs.kanalabs.io/perpetual-futures/kana-perps/for-developers-and-mms/pages/OKw87YCpbRTEWOkODG2z#id-1.-trade-profiles).
***
## Available Topics
### 1. **Order History**
Track your order history with the following subscription:
```json
{
"topic": "order_history",
"address": "user_address"
}
```
#### Response:
```json
{
"message": "order_history",
"data": [
{
"address": "0x51f531abefc697845eabae4ba20c7cc26b1f849561bb016c4d90707c4ede1912",
"order_id": "11905620858892513160724480",
"market_id": "14",
"order_type": 9,
"is_market_order": true,
"size": "10",
"price": "5.75789140",
"order_value": "57.57891400",
"leverage": 20,
"status": "Filled",
"timestamp": 1747075649,
"last_updated": 1747075650,
"trade_id": "737648402019497550020622",
"transaction_version": 2713317408
}
// ...more orders
]
}
```
### 2. **Deposit/Withdraw History**
Subscribe to track deposit and withdraw events:
```json
{
"topic": "deposit_withdraw_history",
"address": "user_address"
}
```
#### Response:
{
"message": "deposit_withdraw_history",
"data": [
{
"address": "0x51f531abefc697845eabae4ba20c7cc26b1f849561bb016c4d90707c4ede1912",
"amount": "10",
"is_deposit": true,
"timestamp": 1745995346,
"last_updated": 1746027625,
"transaction_version": 2665483307
}
// ...more transactions
]
}
### 3. **Trade History**
Subscribe to get updates on your past trades:
```json
{
"topic": "trade_history",
"address": "user_address"
}
```
#### Response:
```json
{
"message": "trade_history",
"data": [
{
"address": "0x51f531abefc697845eabae4ba20c7cc26b1f849561bb016c4d90707c4ede1912",
"trade_id": "737648402019497550020622",
"market_id": "14",
"order_type": 9,
"size": "10",
"price": "5.75789140",
"order_value": "57.57891400",
"leverage": 20,
"fee": "0.0287894570000000005993009656",
"pnl": "-1.0143854570000000005993009656",
"timestamp": 1747075649,
"last_updated": 1747075650,
"transaction_version": 2713317408
}
// ...more trades
]
}
```
#### 4. **Positions**
Subscribe to track your current positions:
```json
{
"topic": "positions",
"address": "user_address"
}
```
#### Response:
```json
{
"message": "positions",
"data": [
{
"address": "0xf05bbcfcb4b1cd144600ee179210d478ed141adb57dd6eb411ff85854f78d7aa",
"market_id": "1338",
"trade_id": "208485101521065352365370",
"size": "6.90",
"entry_price": "5.8370434782608695652173913043",
"value": "40.27560",
"leverage": 2,
"margin": "20.08478",
"liq_price": "3.001",
"available_order_size": "6.90",
"trade_side": true,
"sl": null,
"tp": null,
"timestamp": 1747075629,
"transaction_version": 6719222371
}
// ...more positions
]
}
```
#### 5. **Open Orders**
Track open orders in real-time:
```json
{
"topic": "open_orders",
"address": "user_address"
}
```
#### Response:
```json
{
"message": "open_orders",
"data": [
{
"address": "0x725c8b51b2c1b3d17336c48d75c56c19253f70e1de00e26c8138a29722d82da",
"order_id": "55066334967796803229980238",
"market_id": "1338",
"order_type": 1,
"price": "5.71",
"total_size": "1",
"remaining_size": "1",
"order_value": "5.71",
"leverage": 2,
"timestamp": 1747078972,
"last_updated": 1747078973,
"trade_id": "210735604298057917662522",
"transaction_version": 6719284743
}
]
}
```
#### 6. **Orderbook**
Monitor the orderbook for a specific market:
```json
{
"topic": "orderbook",
"market_id": "market_id"
}
```
#### Response:
```json
{
"message": "orderbook",
"data": [
{
"market_id": "1338",
"price": 5.768,
"size": "487.649",
"is_ask": true,
"last_updated": 1747079061,
"transaction_version": 6719285834
}
// ...more order book entries
]
}
```
#### 7. **Recent Trades**
Subscribe to view recent trades for a given market:
```json
{
"topic": "recent_trades",
"market_id": "market_id"
}
```
#### Response:
```json
{
"message": "recent_trades",
"data": [
{
"address": "0x2cdbf0dabbb0d769d2b01acd1b8b69a2712345044ff93e7d2d5fcb0cf7936842",
"market_id": "1338",
"trade_id": "95996856159584506611002",
"order_type": 9,
"price": "5.658",
"size": "67",
"order_value": "379.086",
"leverage": 5,
"fee": "0.1895430000000000039456563184",
"pnl": "7.2094569999999999960543436821",
"timestamp": 1747075851,
"last_updated": 1747075852,
"transaction_version": 6719250247
}
// ...more recent trades
]
}
```
#### 8. **Live Funding Rate**
Subscribe to view live funding rate:
```json
{
"topic": "live_funding_rate"
}
```
#### Response:
```json
{
"message": "live_funding_rate",
"data": [
{
"funding_rate": "-0.0002642469135802469135802469",
"funding_timestamp": 0,
"last_updated": 1749453746,
"market_id": "14",
"transaction_timestamp": 1749453741,
"transaction_version": 2848764162
},
{
"funding_rate": "0",
"funding_timestamp": 0,
"last_updated": 1749453746,
"market_id": "16",
"transaction_timestamp": 1749453743,
"transaction_version": 2848764254
},
{
"funding_rate": "0",
"funding_timestamp": 0,
"last_updated": 1749453746,
"market_id": "15",
"transaction_timestamp": 1749453742,
"transaction_version": 2848764211
}
]
}
```
#### 9. **Live Order History**
Subscribe to view live order history for a given user address (It will update only latest single data):
```json
{
"topic": "live_order_history",
"address": "{{user_address}}"
}
```
#### Response:
```json
{
"message": "live_order_history",
{
"data": {
"address": "0x725c8b51b2c1b3d17336c48d75c56c19253f70e1de00e26c8138a29722d82da",
"is_market_order": true,
"last_updated": 1749454518,
"leverage": 2,
"market_id": "1338",
"order_id": "81291775866809905605246976",
"order_type": 7,
"order_value": "4.652",
"price": "4.652",
"size": "1",
"status": "Open",
"timestamp": 1749454517,
"trade_id": "334291896103764494386490",
"transaction_version": 6780532763
}
}
}
```
#### 10. **Live Trade History**
Subscribe to view live trade history for a given user address (It will update only latest single data):
```json
{
"topic": "live_trade_history",
"address": "{{user_address}}"
}
```
#### Response:
```json
{
"message": "live_trade_history",
{
"data": {
"address": "0x725c8b51b2c1b3d17336c48d75c56c19253f70e1de00e26c8138a29722d82da",
"fee": "0.0023305000000000000485132769",
"last_updated": 1749454657,
"leverage": 2,
"market_id": "1338",
"order_id": "81295631236321310901534720",
"order_type": 1,
"order_value": "4.661",
"pnl": "-0.0023305000000000000485132769",
"price": "4.661",
"size": "1",
"timestamp": 1749454656,
"trade_id": "334347236335985623041338",
"transaction_version": 6780534260
}
}
}
```
***
## Example of Subscribing to WebSocket Endpoints
To connect to the WebSocket and subscribe to multiple topics, use the following example approach:
1. **Connect to the WebSocket URL** (Choose either Testnet or Mainnet URLs depending on your environment).
2. **Send a subscription message** for each topic you want to subscribe to (e.g., order history, positions, etc.).
Here is a JavaScript example using WebSocket:
```javascript
const socket = new WebSocket('wss://perpetuals-indexer-ws.kana.trade/ws/');
socket.onopen = function() {
// Subscribe to order history
socket.send(JSON.stringify({
topic: "order_history",
address: "your_profile_address"
}));
// Subscribe to trade history
socket.send(JSON.stringify({
topic: "trade_history",
address: "your_profile_address"
}));
};
socket.onmessage = function(event) {
console.log('Received data:', event.data);
};
socket.onerror = function(error) {
console.error('WebSocket Error:', error);
};
```
***
### Error Handling
If your WebSocket connection fails, check the following:
* Ensure you're using the correct WebSocket URL (Testnet vs Mainnet).
* Double-check your **profile address** to ensure it is valid and associated with your wallet.
If you encounter any errors in subscription requests, the server may send a response indicating the issue (e.g., invalid topic or missing parameters). Handle these responses appropriately in your code.