Get Orderbook by Slug

GET/v1/markets/slug/:slug/orderbookPublic

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).

#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"

Was this page helpful?