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"`); max 20 characters; normalized to uppercase
`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"
}

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

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; max 20 characters; normalized to uppercase before lookup
limit must be one of the valid limit values: 5, 10, 20, 50, 100, 500, 1000
No authentication required
Real-time data from matching engine

Error Handling

Common error scenarios:

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

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