Orderbook

curl -X POST 'https://api.kuest.io/books' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '[
    {"token_id": "123456789"}
  ]'
```bash

```bash cURL - Multiple Tokens
curl -X POST 'https://api.kuest.io/books' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '[
    {"token_id": "123456789"},
    {"token_id": "987654321"}
  ]'
```bash

## Example Response

```json
[
  {
    "asset_id": "123456789",
    "bids": [
      {"price": "0.67", "size": "125.50"},
      {"price": "0.66", "size": "89.25"},
      {"price": "0.65", "size": "245.00"},
      {"price": "0.64", "size": "156.75"}
    ],
    "asks": [
      {"price": "0.68", "size": "95.00"},
      {"price": "0.69", "size": "178.50"},
      {"price": "0.70", "size": "210.25"},
      {"price": "0.71", "size": "142.00"}
    ]
  }
]
```bash

## Combined Orderbook Summary

The client typically combines orderbook and last trade data:

```json
{
  "123456789": {
    "bids": [
      {"price": "0.67", "size": "125.50"}
    ],
    "asks": [
      {"price": "0.68", "size": "95.00"}
    ],
    "last_trade_price": "0.675",
    "last_trade_side": "BUY",
    "spread": "0.01"
  }
}
```bash

## Cumulative Orderbook

For depth visualization, calculate cumulative totals:

```typescript
let cumulativeShares = 0
let cumulativeTotal = 0

const levels = bids.map(level => {
  const price = parseFloat(level.price)
  const size = parseFloat(level.size)
  
  cumulativeShares += size
  cumulativeTotal += price * size
  
  return {
    price,
    size,
    cumulativeShares,
    cumulativeTotal
  }
})
```bash

## Use Cases

### Price Discovery
Identify current market prices and available liquidity.

### Limit Order Placement
Find optimal price levels for limit orders based on orderbook depth.

### Market Depth Visualization
Display orderbook ladder or depth charts in trading interfaces.

### Slippage Estimation
Calculate expected execution price for large market orders.

### Spread Monitoring
Track bid-ask spread to assess market liquidity and trading costs.

## Data Freshness

Orderbook data updates:
- In real-time as orders are placed/cancelled
- Stale time: 10 seconds (recommended client cache)
- Use WebSocket feeds for tick-by-tick updates

## Batch Requests

### Optimal Batch Size
- Request multiple tokens in single call
- Maximum recommended: 50 tokens per request
- For 50+ tokens, split into multiple requests

### Performance
Batch requests significantly reduce:
- Network round trips
- Authentication overhead
- Server load

## Error Handling

### Empty Orderbook
If no orders exist:
```json
{
  "asset_id": "123456789",
  "bids": [],
  "asks": []
}
```bash

### Invalid Token
Tokens that don't exist return empty orderbook or may be omitted from response.

### Market Not Ready
Newly created markets may return empty orderbooks until first orders are placed.

## Orderbook Interpretation

### Strong Buy Signal
- Many bid levels
- High bid sizes
- Bids close to asks (narrow spread)

### Strong Sell Signal
- Many ask levels
- High ask sizes
- Asks close to bids

### Low Liquidity
- Few price levels
- Small sizes
- Wide spread

### Balanced Market
- Similar bid and ask depth
- Moderate spread
- Multiple price levels on both sides

## Rate Limiting

No authentication required, but rate limits apply:
- 100 requests per minute per IP
- Batch requests count as 1 request
- Exceeded limits return 429 status

## See Also

- [Place Order](/api/trading/place-order) - Submit orders to the orderbook
- [Get Orders](/api/trading/get-orders) - View your active orders
- [Cancel Order](/api/trading/cancel-order) - Remove orders from orderbook