Get Orderbook

Retrieve order book depth (market depth) for a specific trading pair.

Endpoint

POST https://papi.synthetix.io/v1/info

Request

Request Format

{
  "params": {
    "action": "getOrderbook",
    "symbol": "BTC-USDT",
    "limit": 100
  }
}

Request Parameters

Parameter	Type	Required	Description
`params.action`	string	Yes	Must be `"getOrderbook"`
`params.symbol`	string	Yes	Trading pair symbol (e.g., "BTC-USDT")
`params.limit`	integer	No	Number of orders to return per side (default: 500)

Valid Limits

Limit	Description
`5`	Top 5 orders per side
`10`	Top 10 orders per side
`20`	Top 20 orders per side
`50`	Top 50 orders per side
`100`	Top 100 orders per side
`500`	Top 500 orders per side
`1000`	Top 1000 orders per side

Response

Success Response

{
  "status": "ok",
  "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"]
    ]
  },
  "request_id": "5ccf215d37e3ae6d"
}

Depth Response Object

Field	Type	Description
`bids`	array	Array of bid orders [price, quantity]
`asks`	array	Array of ask orders [price, quantity]

Order Array Format

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

["price", "quantity"]

Where:

price (string): Order price
quantity (string): Order quantity

Error Response

{
  "status": "error",
  "error": {
    "message": "Invalid limit parameter",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Code Examples

Get Top 100 Orders

{
  "params": {
    "action": "getOrderbook",
    "symbol": "BTC-USDT",
    "limit": 100
  }
}

Get Top 20 Orders

{
  "params": {
    "action": "getOrderbook",
    "symbol": "ETH-USDT",
    "limit": 20
  }
}

Market Depth Information

Real-time Data: Live order book snapshot
Bid/Ask Orders: Separate arrays for buy and sell orders
Price Priority: Orders sorted by best price first
Configurable Depth: Choose from 5 to 1000 orders per side
Sequence Numbers: Track order book updates for consistency

Use Cases

Market Analysis: Understand liquidity and market depth
Trading Decisions: Analyze order book pressure
Price Discovery: See where orders are concentrated
Liquidity Assessment: Evaluate market depth for large orders
Real-time Monitoring: Track order book changes

Validation Rules

symbol must be a valid trading pair
limit must be one of the valid limit values
No authentication required
Real-time data from matching engine

Error Handling

Common error scenarios:

Error	Description
Invalid signature	EIP-712 signature validation failed
Invalid market symbol	Market symbol not recognized
Nonce already used	Nonce must be greater than previous value
Rate limit exceeded	Too many requests in time window
Request expired	`expiresAfter` timestamp has passed

Error	Description
Symbol required	Missing trading pair symbol
Invalid limit	Limit not in valid range
Timeout	Request to matching service timed out
Market data unavailable	Failed to retrieve order book data

Rate Limiting

Default: 1000 requests per minute per IP
Burst: Up to 100 requests per second
Real-time Data: High-frequency access supported

Data Format Notes

Price Precision: Prices use market-specific decimal precision
Quantity Precision: Quantities use market-specific decimal precision
Order Sorting: Bids sorted descending (highest first), asks sorted ascending (lowest first)
Snapshot Consistency: All data from the same timestamp

Related Endpoints

Get Markets - Market configuration
Get Market Prices - Current prices
Get Candles - Historical price data