Integrating WebSockets

Important Note:

• To track transactions on-chain (e.g., via Aptos Explorer or Aptos Scan), you must use your profile address, 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:

{
  "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.

---

Available Topics

1. Order History

Track your order history with the following subscription:

{
  "topic": "order_history",
  "address": "user_address"
}

Response:

{
  "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:

{
  "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:

{
  "topic": "trade_history",
  "address": "user_address"
}

Response:

{
  "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:

{
  "topic": "positions",
  "address": "user_address"
}

Response:

{
  "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:

{
  "topic": "open_orders",
  "address": "user_address"
}

Response:

{
  "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:

{
  "topic": "orderbook",
  "market_id": "market_id"
}

Response:

{
  "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:

{
  "topic": "recent_trades",
  "market_id": "market_id"
}

Response:

{
  "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:

{
    "topic": "live_funding_rate"
}

Response:

{
  "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):

{
  "topic": "live_order_history",
  "address": "{{user_address}}"
}

Response:

{
  "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):

{
  "topic": "live_trade_history",
  "address": "{{user_address}}"
}

Response:

{
  "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:

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.