Orderbook

The Orderbook API provides real-time access to market depth and order data for specific market outcomes.

Get Orderbook Data

Retrieve the orderbook for a specific market outcome.

Get orderbook list

get

Path parameters

outcomeIdstring · min: 1RequiredExample: 546eb1a1-b87d-49d4-a579-9c80c0601c72

Query parameters

pagestringOptionalDefault: 1Example: 1Pattern: ^\d+$

pageSizestringOptionalDefault: 20Example: 20Pattern: ^\d+$

sortstring · enumOptionalDefault: descExample: descPossible values:

Responses

200

Orderstable data

application/json

400

Bad request

application/json

404

Not found

application/json

get

/api/v1/orderbook/{outcomeId}

HTTPcURLJavaScriptPython

GET /api/v1/orderbook/{outcomeId} HTTP/1.1
Host: 
Accept: */*

{
  "orders": [
    {
      "id": "order-uuid",
      "userId": "user-uuid",
      "marketId": "1",
      "outcomeId": "2",
      "quantity": "10",
      "amount": "100",
      "filledQuantity": "5",
      "price": "0.5",
      "filledPrice": "0.5",
      "fee": "0.01",
      "side": "buy",
      "type": "limit",
      "status": "open",
      "cancelReason": null,
      "isSystem": false,
      "signature": "signature",
      "expiredAt": null,
      "signTime": 1680000000,
      "createdAt": "2024-06-01T00:00:00.000Z",
      "updatedAt": "2024-06-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}

Code Examples

// Get Orderbook Data
const API_KEY = 'YOUR_API_KEY'
const BASE_URL = 'https://engine.xmarket.app/api/v1';

async function getOrderbook(outcomeId) {
  const response = await fetch(
    `${BASE_URL}/orderbook/${outcomeId}`,
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  
  const orderbook = await response.json();
  return orderbook;
}

Get Spread

Retrieve the orderbook spread for a specific market outcome.

Get orderbook spread

get

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

outcomeIdstring · min: 1RequiredExample: 546eb1a1-b87d-49d4-a579-9c80c0601c72

Responses

200

Orderbook spread data

application/json

400

Bad request

application/json

404

Not found

application/json

get

/api/v1/orderbook/spread/{outcomeId}

HTTPcURLJavaScriptPython

GET /api/v1/orderbook/spread/{outcomeId} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "asks": [
    {
      "price": 0.5,
      "shares": 10
    }
  ],
  "bids": [
    {
      "price": 0.4,
      "shares": 8
    }
  ],
  "lastPrice": 0.5,
  "spread": 0.1
}

Best Practices

1. Polling Frequency: Don't poll too frequently; respect rate limits

2. Data Caching: Cache orderbook data with appropriate TTL

3. Error Handling: Handle network errors and invalid responses gracefully

4. Price Validation: Validate prices are within valid range (0-1)

5. Depth Analysis: Consider market depth when placing large orders

6. Real-time Updates: For high-frequency updates, consider WebSocket connections when available

Performance Tips

• Use pagination to limit response size

• Cache orderbook data for recently viewed markets

• Implement exponential backoff for retry logic

• Consider aggregating multiple outcome orderbooks in parallel

• Monitor rate limit headers to avoid throttling

Related Documentation

• Quick Start - Get started with the API

• Markets API - Get market information

• Orders API - Create and manage orders

• Positions API - Track your trading positions