Get Orderbook (WebSocket)

Retrieve order book depth (market depth) for a specific trading pair through the WebSocket connection. This endpoint provides a real-time snapshot of buy and sell orders without requiring authentication.

Endpoint

ws.send() wss://api.synthetix.io/v1/ws/info

Request

Request Format

{
  "id": "orderbook-1",
  "method": "post",
  "params": {
    "action": "getOrderbook",
    "symbol": "BTC-USDT",
    "limit": 100
  }
}

Request Parameters

Valid Limits

Response

Success Response

{
  "id": "orderbook-1",
  "status": 200,
  "result": {
    "response": {
      "bids": [
        ["45000.00", "1.5"],
        ["44999.50", "2.0"],
        ["44999.00", "0.8"]
      ],
      "asks": [
        ["45001.00", "1.2"],
        ["45001.50", "3.1"],
        ["45002.00", "0.9"]
      ]
    },
    "status": "success"
  }
}

Response Fields

Order Array Format

Each order in the bids and asks arrays is represented as:

["price", "quantity"]

Where:

• price (string): Order price level
• quantity (string): Total quantity available at this price level

Error Response

{
  "id": "orderbook-1",
  "status": 400,
  "result": null,
  "error": {
    "code": 400,
    "message": "Invalid limit parameter"
  }
}

WebSocket Connection Example

const ws = new WebSocket('wss://papi.synthetix.io/v1/ws/info');
 
ws.onopen = () => {
  // Request orderbook for BTC-USDT
  ws.send(JSON.stringify({
    id: 'orderbook-1',
    method: 'post',
    params: {
      action: 'getOrderbook',
      symbol: 'BTC-USDT',
      limit: 100
    }
  }));
};
 
ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
 
  if (response.id === 'orderbook-1' && response.status === 200) {
    const { bids, asks } = response.result.response;
 
    // Best bid and ask
    const bestBid = bids[0];
    const bestAsk = asks[0];
    console.log(`Best Bid: ${bestBid[0]} @ ${bestBid[1]}`);
    console.log(`Best Ask: ${bestAsk[0]} @ ${bestAsk[1]}`);
 
    // Calculate spread
    const spread = parseFloat(bestAsk[0]) - parseFloat(bestBid[0]);
    console.log(`Spread: ${spread.toFixed(2)}`);
 
    // Calculate total liquidity
    const totalBidLiquidity = bids.reduce((sum, [_, qty]) => sum + parseFloat(qty), 0);
    const totalAskLiquidity = asks.reduce((sum, [_, qty]) => sum + parseFloat(qty), 0);
    console.log(`Bid Liquidity: ${totalBidLiquidity.toFixed(4)}`);
    console.log(`Ask Liquidity: ${totalAskLiquidity.toFixed(4)}`);
  }
};

Examples

Get Top 100 Orders

{
  "id": "orderbook-100",
  "method": "post",
  "params": {
    "action": "getOrderbook",
    "symbol": "BTC-USDT",
    "limit": 100
  }
}

Get Top 20 Orders (Lightweight)

{
  "id": "orderbook-20",
  "method": "post",
  "params": {
    "action": "getOrderbook",
    "symbol": "ETH-USDT",
    "limit": 20
  }
}

Get Full Depth (1000 Levels)

{
  "id": "orderbook-full",
  "method": "post",
  "params": {
    "action": "getOrderbook",
    "symbol": "BTC-USDT",
    "limit": 1000
  }
}

Get Minimal Depth (Top 5)

{
  "id": "orderbook-minimal",
  "method": "post",
  "params": {
    "action": "getOrderbook",
    "symbol": "BTC-USDT",
    "limit": 5
  }
}

Implementation Notes

• Public Data: No authentication required for this endpoint
• Symbol Required: A valid market symbol must be provided
• Aggregated Levels: Orders at the same price are aggregated into a single level
• Snapshot Data: Returns a point-in-time snapshot of the order book
• Sorted Orders: Bids sorted descending (highest first), asks sorted ascending (lowest first)

Data Format Notes

• Price Precision: Prices use market-specific decimal precision
• Quantity Precision: Quantities use market-specific decimal precision
• String Format: Both price and quantity are returned as strings for precision
• Snapshot Consistency: All data from the same timestamp

Use Cases

Market Analysis

• Understand liquidity distribution across price levels
• Identify support and resistance levels
• Analyze order book imbalance

Trading Decisions

• Evaluate slippage for planned order sizes
• Assess market depth before placing large orders
• Monitor bid/ask spread changes

Price Discovery

• See where orders are concentrated
• Identify potential price movement barriers
• Track large order placements

Liquidity Assessment

• Evaluate market depth for institutional orders
• Calculate available liquidity at price ranges
• Compare liquidity across trading pairs

Validation Rules

• No authentication required (public Info WebSocket)
• Symbol parameter is required and must be a valid market symbol
• Limit must be one of the valid values: 5, 10, 20, 50, 100, 500, 1000
• Default limit is 500 if not specified

Common Errors

Performance Considerations

• Low Latency: WebSocket connection provides faster response times than REST
• Persistent Connection: Reuse the same connection for multiple requests
• Choose Appropriate Depth: Use smaller limits (5, 10, 20) for faster responses when full depth isn't needed
• Real-time Updates: For continuous updates, use Orderbook Updates subscription

Related Endpoints

• Orderbook Updates - Real-time orderbook changes via subscription
• Get Market Prices - Current market prices including best bid/ask
• Get Last Trades - Recent trade executions
• Get Markets - Market configuration and precision
• REST Alternative - HTTP request for orderbook