Orderbook - Kuest Prediction Market

Orderbook

curl --request POST \
  --url https://api.example.com/books \
  --header 'Content-Type: application/json' \
  --data '
{
  "[].token_id": "<string>"
}
'

{
  "[].asset_id": "<string>",
  "[].bids": [
    {
      "[].bids[].price": "<string>",
      "[].bids[].size": "<string>"
    }
  ],
  "[].asks": [
    {
      "[].asks[].price": "<string>",
      "[].asks[].size": "<string>"
    }
  ],
  "[].token_id": "<string>",
  "[].price": "<string>",
  "[].side": "<string>"
}

POST

books

Orderbook

curl --request POST \
  --url https://api.example.com/books \
  --header 'Content-Type: application/json' \
  --data '
{
  "[].token_id": "<string>"
}
'

{
  "[].asset_id": "<string>",
  "[].bids": [
    {
      "[].bids[].price": "<string>",
      "[].bids[].size": "<string>"
    }
  ],
  "[].asks": [
    {
      "[].asks[].price": "<string>",
      "[].asks[].size": "<string>"
    }
  ],
  "[].token_id": "<string>",
  "[].price": "<string>",
  "[].side": "<string>"
}

Overview

The Orderbook endpoint returns current bid and ask levels for one or more outcome tokens. This provides a real-time view of available liquidity at different price points.

Authentication

This endpoint does not require authentication. It provides public market data. Required Headers:

Content-Type: application/json
Accept: application/json

Request Body

Send an array of token ID objects:

[].token_id

string

required

The outcome token ID to retrieve orderbook data for. Multiple tokens can be requested in a single call.

Response

Returns an array of orderbook summaries:

[].asset_id

string

The outcome token ID

[].bids

array

Array of bid levels (buy orders), sorted from highest to lowest price

[].bids[].price

string

Price level as decimal between 0 and 1 (e.g., “0.65” = 65%)

[].bids[].size

string

Total shares available at this price level

[].asks

array

Array of ask levels (sell orders), sorted from lowest to highest price

[].asks[].price

string

Price level as decimal between 0 and 1

[].asks[].size

string

Total shares available at this price level

Last Trade Prices

The companion endpoint /last-trades-prices provides recent trade information:

[].token_id

string

Outcome token ID

[].price

string

Last trade price (decimal between 0 and 1)

[].side

string

Last trade side: BUY or SELL

Orderbook Structure

Bid Levels (Buy Orders)

Sorted from highest to lowest price
Represents demand - traders willing to buy
Higher prices indicate stronger buying interest

Ask Levels (Sell Orders)

Sorted from lowest to highest price
Represents supply - traders willing to sell
Lower prices indicate stronger selling pressure

Spread

The difference between the best bid (highest buy price) and best ask (lowest sell price). Example:

Best bid: 0.64 (64%)
Best ask: 0.67 (67%)
Spread: 0.03 (3%)

Orderbook Depth

The response includes up to 12 price levels per side:

12 bid levels maximum
12 ask levels maximum
Levels with zero size are filtered out

Price Rounding

Display Prices

Prices are rounded to the nearest 0.1 cent:

Bids rounded down (e.g., 0.647 → 0.64)
Asks rounded up (e.g., 0.643 → 0.65)

This ensures executable limit orders at displayed prices.

Raw Prices

Internal calculations use full precision to prevent rounding errors.

Example Request

cURL - Single Token

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

Get Orders

Get Current Positions

​Overview

​Authentication

​Request Body

​Response

​Last Trade Prices

​Orderbook Structure

​Bid Levels (Buy Orders)

​Ask Levels (Sell Orders)

​Spread

​Orderbook Depth

​Price Rounding

​Display Prices

​Raw Prices

​Example Request

Overview

Authentication

Request Body

Response

Last Trade Prices

Orderbook Structure

Bid Levels (Buy Orders)

Ask Levels (Sell Orders)

Spread

Orderbook Depth

Price Rounding

Display Prices

Raw Prices

Example Request