User Data Stream

User Data Streams provide real-time updates for your account activities, including order status changes, trade executions, balance updates, and withdrawal status changes.

What is User Data Stream?

User Data Streams are private WebSocket streams that deliver real-time notifications about your account activities. Unlike public market data streams, these streams require authentication and provide user-specific information.

Use Cases

User Data Streams are useful for:

• Order Management - Receive real-time updates when orders are created, filled, partially filled, or canceled
• Trade Tracking - Get notified immediately when your orders are executed
• Balance Monitoring - Monitor account balance changes in real-time
• Withdrawal Tracking - Track withdrawal status changes from initiation to completion
• Portfolio Management - Keep your local portfolio state synchronized with the exchange

How to Subscribe

User Data Streams are subscribed to via URL query parameters when establishing the WebSocket connection. You specify which streams you want to receive in the connection URL.

Connection URL Format

wss://dev.yimmit.com/api/v3/ranger/private/?stream=<stream1>&stream=<stream2>&stream=<stream3>

Available User Data Streams

• trade - Trade execution updates for your account
• order - Order status updates (new, filled, canceled, etc.)
• balance - Account balance updates
• withdraw - Withdrawal status updates

Example Connection

const WebSocket = require('ws');
const crypto = require('crypto');

const apiKey = 'your-api-key';
const secretKey = 'your-secret-key';
const nonce = Date.now();

// Generate signature
const message = `${nonce}${apiKey}`;
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(message)
  .digest('hex');

// Connect to private streams with multiple stream subscriptions
const ws = new WebSocket(
  'wss://dev.yimmit.com/api/v3/ranger/private/?stream=trade&stream=order&stream=balance&stream=withdraw',
  {
    headers: {
      'X-Auth-Apikey': apiKey,
      'X-Auth-Nonce': nonce.toString(),
      'X-Auth-Signature': signature
    }
  }
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Stream:', data.stream || Object.keys(data)[0]);
  console.log('Data:', data.data || data[Object.keys(data)[0]]);
};

Subscription Confirmation

When you successfully connect and subscribe to streams, you'll receive a confirmation response:

{
    "success": {
        "message": "subscribed",
        "streams": [
            "trade",
            "order",
            "withdraw"
        ]
    }
}

Event Format

User Data Stream events are returned as JSON objects. The format depends on the stream type:

Order Events

{
    "order": {
        "id": 23515,
        "market": "ethusdc",
        "side": "buy",
        "ord_type": "limit",
        "price": "2021.97",
        "state": "wait",
        "origin_volume": "0.0029",
        "remaining_volume": "0.0029",
        "executed_volume": "0.0",
        "created_at": 1773294648,
        "updated_at": 1773294648
    }
}

Trade Events

{
    "trade": {
        "id": 789,
        "price": "2500.00",
        "amount": "0.1",
        "total": "250.00",
        "market": "ethusdt",
        "side": "buy",
        "created_at": 1741400000,
        "order_id": 23515
    }
}

Withdraw Events

{
    "withdraw": {
        "id": 55,
        "currency": "usdt",
        "amount": "3.0",
        "fee": "1.2",
        "state": "processing",
        "created_at": "2026-03-12 05:51:23 UTC",
        "updated_at": "2026-03-12 05:51:25 UTC"
    }
}

Balance Events

{
    "stream": "balance",
    "data": {
        "currency": "BTC",
        "free": "1.00000000",
        "locked": "0.50000000",
        "total": "1.50000000"
    }
}

Important Notes

• Authentication Required - User Data Streams require authentication using X-Auth-Apikey, X-Auth-Nonce, and X-Auth-Signature headers. See General WebSocket API Information for authentication details.
• Real-time Updates - Events are sent asynchronously as they occur in real-time.
• Chronological Order - Events are delivered in chronological order.
• Connection Management - A single connection is valid for 24 hours. You'll need to reconnect after that period.
• Multiple Streams - You can subscribe to multiple streams in a single connection by adding multiple stream parameters to the URL.

tip

For detailed examples, trigger conditions, state tables, and complete response payloads for Order, Trade, and Withdraw events, please refer to the Private Stream Events page.