# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.kanalabs.io/perpetual-futures/kana-perps/for-developers-and-mms/integrating-websockets.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.