xRocket WebSocket API

xRocket WebSocket API enables streaming real-time data for trading and account management.

How to connect?

Use the following URL to connect your project to xRocket WebSocket API:

For testnet:

tip

To keep the connection alive and prevent the server from closing idle connections after 60 seconds, send a ping message every 30 seconds.

Example ping message:

{
  "id": "12345",
  "method": "ping"
}

Message Format

All messages use JSON format with the following structure:

{
  "id": "12345",
  "method": "method_name",
  "params": {
// method-specific parameters, for example, channel name to subscribe, ticker or auth token
  }
}

Request ID guidelines:

• Each request must include a unique id field, that is a string or number value.
• id is used to match requests with their corresponding responses.

Example subscription request:

{
  "id": "request_id",
  "method": "subscribe",
  "params": {
    "channel": "ticker",
    "symbol": "BTC-USDT",
    "interval": "1day"
  }
}

Channel push notifications use the subscription format:

{
  "method": "subscription",
  "params": {
    "channel": "ticker",
    "symbol": "BTC-USDT",
    "interval": "1day",
    "data": {
// channel-specific data
    }
  }
}

Channels

Channel	Description
Public channels	Provide public market data like tickers, order books, and more. No authentication required.
Ticker	Ticker updates for specific symbols.
All tickers	Ticker updates for all symbols.
Order book	Order book updates.
Trades	Trade updates for specific symbols.
Candles	Candlestick data.
Private channels	Provide account-specific data and require authentication.
Balances	Account balance updates.
Active orders	Updates for active orders.

Authentication

• Get JWT Token linked to your xRocket user ID. In Telegram bot go to Menu-Settings-Exchange settings-API token or contact xRocket support for assistance. The token must be issued for your account and bound to your xRocket userId (stored in our database). The server extracts and validates userId from JWT claims.
• Use your JWT as API token. Send the token via the auth method right after connecting.

warning

Please use testnet bot to get JWT for testnet integration.

Authentication request example:

{
  "id": "1",
  "method": "auth",
  "params": {
    "token": "<your_jwt_token_here>"
  }
}

Successful response:

{
  "id": "1",
  "result": {
    "success": true
  }
}

Error response:

{  
    "id": "1", 
    "error": {  
        "code": -32034,  
        "message": "User Blocked",
        "data": {  
            "detail": "Invalid authentication" 
        }  
    }  
}

Methods

• ping — Health check and connection testing
• auth — Authenticate connection for private channels
• subscribe — Subscribe to a channel
• unsubscribe — Unsubscribe from a channel
• unsubscribeAll — Unsubscribe from all active channels

Unsubscribe

Unsubscribe from a specific channel request example:

{
  "id": "12345",
  "method": "unsubscribe",
  "params": {
    "channel": "channel_name"
  }
}

Unsubscribe All

Unsubscribe from all active channel subscriptions request example:

{
  "id": "12345",
  "method": "unsubscribeAll"
}

Error Handling

xRocket WebSocket API error codes comply with JSON-RPC specification.

Our Error Codes

Error code	Description
-32700	Parse error — Invalid JSON was received by the server.
-32600	Invalid request — The JSON sent is not a valid Request object.
-32601	Method not found — The method does not exist or is not available.
-32602	Invalid params — Invalid method parameter(s).
-32603	Internal error — Internal JSON-RPC error.
-32000	Incorrect decimal places — The requested number of decimal places is not supported.
-32001	Order not found — The specified order not found.
-32002	Already subscribed — The connection is already subscribed to this channel.
-32003	Not subscribed — Attempted to unsubscribe from a channel without an active subscription.
-32005	Symbol not found — The requested trading symbol not found.
-32006	Symbol incorrect — The provided symbol is invalid.
-32007	Symbol not available — The symbol is not currently available for trading.
-32008	Interval too big — The requested time interval is too big.
-32009	Symbol not opened — Trading for this symbol has not started or is suspended.
-32010	Asset not available — The requested asset is not available.
-32011	Incorrect precision — The requested price or quantity precision is not supported.
-32030	Invalid token — The provided authentication token is invalid, expired, or revoked.
-32032	Validation error — An error occurred while validating the incoming data.
-32033	Unauthorized — Insufficient permissions to perform the operation.
-32034	User Blocked — The user account has been blocked.
-32050	Rate limit exceeded — Too many requests. Please try again later.

Error Response Format

{  
    "id": "1205411", 
    "error": {  
        "code": -32034,
        "message": "User Blocked",  
        "data": {  
         // error-specific fields and data 
            "detail": "Invalid authentication"
        }  
    }  
}