GETGet Orderbook by Slug

Retrieve the current orderbook (bids and asks) for a specific outcome using the market slug. This endpoint is designed for use with WebSocket signals, which provide slug-based channel names (market:{slug}:orderbook).

Request

GET /v1/markets/slug/:slug/orderbook

Path Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Market URL slug (e.g., `will-btc-hit-100k`)

Query Parameters

Parameter	Type	Required	Description
`outcomeId`	string	Yes	Outcome ID to get orderbook for

Response

{
  "outcomeId": "outcome-uuid-1",
  "outcomeSide": "Yes - YES",
  "bids": [
    { "price": "0.650", "shares": "500.00" },
    { "price": "0.640", "shares": "300.00" },
    { "price": "0.620", "shares": "150.00" }
  ],
  "asks": [
    { "price": "0.680", "shares": "200.00" },
    { "price": "0.700", "shares": "400.00" },
    { "price": "0.750", "shares": "100.00" }
  ]
}

Response Fields

Field	Type	Description
`outcomeId`	string	The outcome ID this orderbook represents
`outcomeSide`	string	Outcome name and side combined (e.g., `Yes - YES`, `Trump - YES`)
`bids`	array	Buy orders sorted by price (highest first)
`asks`	array	Sell orders sorted by price (lowest first)
`bids[].price`	string	Bid price (3 decimal places)
`bids[].shares`	string	Total shares at this price level

WebSocket Integration

This endpoint is designed to be called after receiving a WebSocket signal on the market:{slug}:orderbook channel:

// 1. Subscribe to WebSocket channel
socket.emit('join', { channel: 'market:will-btc-hit-100k:orderbook' });

// 2. When signal received, fetch updated data using the same slug
socket.on('market:will-btc-hit-100k:orderbook', async (data) => {
  const response = await fetch('/v1/markets/slug/will-btc-hit-100k/orderbook?outcomeId=outcome-uuid-1');
  const orderbook = await response.json();
});

This eliminates the need to maintain a slug-to-UUID mapping, as both the WebSocket channel and the REST API use the same slug identifier.

Errors

Status	Description
`400`	Missing `outcomeId` or outcome does not belong to market
`404`	Market or outcome not found

Example

curl "https://api.conviction.bet/v1/markets/slug/will-btc-hit-100k/orderbook?outcomeId=outcome-uuid-1"