Trade

trade Channel

Track executed trades for specific accounts in real-time.

Subscribe

Parameter	Required	Description
`account`	No	EOA or Smart account address (42 characters with `0x` prefix)
`pair`	No	Trading pair (e.g., `"BTC_USDC"`)
`direction`	No	`"buy"` or `"sell"`

{
  "channel": "trade",
  "query": {
    "account": "0x1234567890abcdef1234567890abcdef12345678",
    "pair": "BTC_USDC",
    "direction": "buy"
  }
}

The account address must include the 0x prefix and be exactly 42 characters total.

📘
Learn More: For detailed explanations of how order_id and trade_id relate across trading scenarios, see the Order ID vs Trade ID Guide.

Event: trade

{
  "kind": "event",
  "type": "trade",
  "timestamp_ms": 1677721600000,
  "data": {
    "margin_account_id": "550e8400-e29b-41d4-a716-446655440000",
    "smart_account_address": "0x1234567890abcdef1234567890abcdef12345678",
    "trade_id": "1234567890abcdef1234567890abcdef",
    "order_id": "abcdef1234567890abcdef1234567890",
    "size": 1.5,
    "timestamp": 1677721600000,
    "direction": "buy",
    "index_price": 45000.5,
    "instrument_name": "BTC_USDC-31OCT25-130000-C",
    "average_price": 2500.25,
    "limit_price": 2505.0,
    "liquidation": false,
    "iv": 0.65,
    "taker_fee": 0.0002,
    "maker_fee": 0.0001,
    "systemic_risk_fee": 0.0001,
    "liquidation_fee": 0,
    "realised_funding": 0
  },
  "subscription": {
    "channel": "trade",
    "query": {
      "account": "0x1234567890abcdef1234567890abcdef12345678"
    }
  }
}

Field	Type	Description
`margin_account_id`	string	Margin account UUID
`smart_account_address`	string	Smart account Ethereum address
`trade_id`	string	Unique trade identifier (32 hex characters)
`order_id`	string	Associated order identifier (32 hex characters)
`size`	number	Trade size
`timestamp`	number	Trade execution time in milliseconds
`direction`	string	`"buy"` or `"sell"`
`index_price`	number	Index price at time of trade
`instrument_name`	string	Instrument traded
`average_price`	number	Average execution price
`limit_price`	number	Limit price of the order
`liquidation`	boolean	Whether this is a liquidation trade
`iv`	number	Implied volatility (options only)
`taker_fee`	number	Taker fee
`maker_fee`	number	Maker fee
`systemic_risk_fee`	number	Systemic risk fee
`liquidation_fee`	number	Liquidation fee (0 if not a liquidation)
`realised_funding`	number	Realized funding (perpetuals only)

Trade events contain execution data only. For order lifecycle metadata including user_id, total order size, and filled_amount, subscribe to order events (post_order, update_order, cancel_order) via the orderbook channels.

Example: Monitor Account Activity

Track trades, transfers, and other account activities.

import WebSocket from 'ws';

const wsUrl = 'wss://staging.kyan.sh/ws';
const API_KEY = 'your-api-key-here';
const ACCOUNT_ADDRESS = '0x1234567890abcdef1234567890abcdef12345678';

const ws = new WebSocket(wsUrl);

// First authenticate
ws.onopen = () => {
  console.log('WebSocket connection open');
  const authMessage = {
    type: 'auth',
    api_key: API_KEY,
  };
  ws.send(JSON.stringify(authMessage));
};

// Handle authentication response and subscribe to account activity
ws.onmessage = (event) => {
  const message = JSON.parse(event.data.toString());

  if (message.type === 'auth' && message.success) {
    console.log('Authentication successful');

    // Subscribe to account trades and transfers
    const subscribeMessage = {
      type: 'subscribe',
      subscriptions: [
        {
          channel: 'trade',
          query: {
            account: ACCOUNT_ADDRESS,
          },
        },
        {
          channel: 'transfer',
          query: {
            account: ACCOUNT_ADDRESS,
          },
        },
      ],
    };

    ws.send(JSON.stringify(subscribeMessage));

    // Update the onmessage handler to process events
    ws.onmessage = handleMessages;
  } else if (message.type === 'auth' && !message.success) {
    console.error('Authentication failed:', message.error);
  }
};

// Process incoming messages after subscription
function handleMessages(event: WebSocket.MessageEvent) {
  const message = JSON.parse(event.data.toString());

  // Handle subscription confirmation
  if (message.type === 'subscribe' && message.success) {
    console.log('Successfully subscribed to account activity');
  }

  // Handle account events
  if (message.event === 'trade') {
    console.log('New trade:', message.data);
  } else if (message.event === 'deposit') {
    console.log('New deposit:', message.data);
  } else if (message.event === 'withdrawal') {
    console.log('New withdrawal:', message.data);
  }
}

Updated about 15 hours ago