ritmex-bot/docs/standx/websocket.md

StandX Perps WebSocket API List

The WebSocket API provides two streams: Market Stream for market data and user account updates, and Order Response Stream for asynchronous order creation responses.

⚠️ This document is under construction.

Connection Management

Both WebSocket streams implement the following connection management behavior:

Connection Duration Limit

• Maximum Duration: A single WebSocket connection can be maintained for a maximum of 24 hours
• After 24 hours, the connection will be automatically terminated
• Clients should implement reconnection logic to handle this gracefully

Ping/Pong Mechanism

• Server Ping Interval: The server sends a WebSocket Ping frame every 10 seconds
• Client Response: Clients must respond with a Pong frame when receiving a Ping
• Timeout: If the server does not receive a Ping/Pong response within 5 minutes, the connection will be terminated with error:

  {
    "code": 408,
    "message": "disconnecting due to not receive Pong within 5 minute period"
  }
  

Note: Most modern browsers and WebSocket libraries automatically handle ping/pong frames, so you might not need to implement this manually. However, if your environment doesn’t support automatic ping/pong handling, you can proactively send ping frames to the server. Example using the npm ws library:

import WebSocket from "ws";
// ...
private ws: WebSocket;
//...
ping(): void {
  this.lastPingTime = Date.now();
  this.ws.ping();
  console.log(\`[${new Date().toISOString()}] Ping server\`);
}

Market Stream

Base Endpoint: wss://perps.standx.com/ws-stream/v1

Available Channels

[
  // public channels
  { channel: "price", symbol: "<symbol>" },
  { channel: "depth_book", symbol: "<symbol>" },
  { channel: "public_trade", symbol: "<symbol>" },
  // user-level authenticated channels
  { channel: "order" },
  { channel: "position" },
  { channel: "balance" },
  { channel: "trade" },
]

Subscribe to Depth Book

⚠️ Note: The sequence of price levels in the asks and bids arrays is not guaranteed. Please implement local sorting on the client side based on your specific requirements.

• Request:
• Response:

  {
    "seq": 3,
    "channel": "depth_book",
    "symbol": "BTC-USD",
    "data": {
      "asks": [
        ["121896.02", "0.839"],
        ["121896.32", "1.051"]
      ],
      "bids": [
        ["121884.22", "0.001"],
        ["121884.52", "0.001"]
      ],
      "symbol": "BTC-USD"
    }
  }
  

Subscribe to Symbol Price

• Request:
• Response:

  {
    "seq": 13,
    "channel": "price",
    "symbol": "BTC-USD",
    "data": {
      "base": "BTC",
      "index_price": "121890.651250",
      "last_price": "121897.95",
      "mark_price": "121897.56",
      "mid_price": "121898.00",
      "quote": "DUSD",
      "spread": ["121897.95", "121898.05"],
      "symbol": "BTC-USD",
      "time": "2025-08-11T07:23:50.923602474Z"
    }
  }
  

Authentication Request

Log in with JWT

• Request:

  {
    "auth": {
      "token": "<your_jwt_token>",
      "streams": [{ "channel": "order" }]
    }
  }
  

auth.streams is Optional, which enables the user to subscribe to specific channels right after authentication.

• Response:

  { "seq": 1, "channel": "auth", "data": { "code": 200, "msg": "success" } }
  

User Orders Subscription

• Request:
• Response:

  {
    "seq": 35,
    "channel": "order",
    "data": {
      "avail_locked": "0",
      "cl_ord_id": "01K2C9H93Y42RW8KD6RSVWVDVV",
      "closed_block": -1,
      "created_at": "2025-08-11T10:06:37.182464902Z",
      "created_block": -1,
      "fill_avg_price": "121245.21",
      "fill_qty": "1.000",
      "id": 2547027,
      "leverage": "15",
      "liq_id": 0,
      "margin": "8083.013333334",
      "order_type": "market",
      "payload": null,
      "position_id": 15,
      "price": "121245.20",
      "qty": "1.000",
      "reduce_only": false,
      "remark": "",
      "side": "buy",
      "source": "user",
      "status": "filled",
      "symbol": "BTC-USD",
      "time_in_force": "ioc",
      "updated_at": "2025-08-11T10:06:37.182465022Z",
      "user": "bsc_0x..."
    }
  }
  

User Position Subscription

• Request:
• Response:

  {
    "seq": 36,
    "channel": "position",
    "data": {
      "created_at": "2025-08-10T09:05:50.265265Z",
      "entry_price": "121677.65",
      "entry_value": "2879988.1154631481396099405228",
      "id": 15,
      "initial_margin": "191999.219856667",
      "leverage": "15",
      "margin_asset": "DUSD",
      "margin_mode": "isolated",
      "qty": "23.669",
      "realized_pnl": "158.197103148",
      "status": "open",
      "symbol": "BTC-USD",
      "updated_at": "2025-08-10T09:05:50.265265Z",
      "user": "bsc_0x..."
    }
  }
  

User Balance Subscription

• Request:
• Response:

  {
    "seq": 37,
    "channel": "balance",
    "data": {
      "account_type": "perps",
      "created_at": "2025-08-09T09:36:54.504639Z",
      "free": "906946.976225666",
      "id": "bsc_0x...",
      "inbound": "0",
      "is_enabled": true,
      "kind": "user",
      "last_tx": "",
      "last_tx_updated_at": 0,
      "locked": "0.000000000",
      "occupied": "0",
      "outbound": "0",
      "ref_id": 0,
      "token": "DUSD",
      "total": "923207.752500717",
      "updated_at": "2025-08-09T09:36:54.504639Z",
      "version": 0,
      "wallet_id": "bsc_0x..."
    }
  }
  

Order Response Stream

This WebSocket channel provides real-time order status updates for the new order API. Since order creation is asynchronous, this channel notifies clients about order responses, including ALO order rejections.

Base Endpoint:wss://perps.standx.com/ws-api/v1

Request Structure

All WebSocket requests follow this structure:

Fields:

• session_id: UUID that remains consistent throughout the session
• request_id: Unique UUID for each request
• method: Operation to perform (auth:login, order:new, order:cancel)
• header: Required for order:new and order:cancel methods (authentication headers)
• params: JSON-stringified parameters specific to the method

Methods

auth:login

Authenticate using JWT token.

Parameters:

{ "token": "<jwt>" }

Example Request:

order:new

Create a new order. Parameters are the same as the HTTP API new_order payload.

order:cancel

Cancel an existing order. Parameters are the same as the HTTP API cancel_order payload.

Order Response Format

Success Response:

{
  "code": 0,
  "message": "success",
  "request_id": "bccc2b23-03dc-4c2b-912f-4315ebbbb7e0"
}

Rejection Response:

{
  "code": 400,
  "message": "alo order rejected",
  "request_id": "1187e114-1914-4111-8da1-2aaaa86bb1b9"
}

Last updated on

Perps HTTP API Perps Reference