Markets and orderbook
The markets namespace of @getenginex/sdk-predictions covers the catalog: categories → events → markets → orderbook and price history. All routes are public (the SDK never sends a token on them), so the storefront works without login. In tests, withPredictionsRoutes already answers all of them (see Testing).
Prices, quantities and money
- Price in cents, integer, from 1 to 99.
lastPriceYes: 62is 62 cents per contract, which pays 100 if theyesis right.yesandnoare independent prices of each side's last trade (lastPriceNo: 38): they tend to add up to about 100, but it is not an identity. - Quantity in contracts (integer). Volumes (
volume24h,totalVolume) and limits (minOrderSize,maxPosition) are in cents of the settlement currency (settlementCurrency). - Enums arrive in lowercase and without the protobuf prefix:
status: 'open'(notMARKET_STATUS_OPEN),side: 'yes' | 'no'.
Categories, events and markets
const categories = await predictions.markets.listCategories()
// Fixed page: the first 50 events. `categoryId` is the only filter the gateway accepts.
const events = await predictions.markets.listEvents({ categoryId: categories[0].id })
// An event by id or by ticker (e.g. coming from the page URL).
const event = await predictions.markets.getEvent({ ticker: 'ELECTION-26OCT' })
// The event's markets and one market by id or ticker.
const markets = await predictions.markets.listMarkets({ eventId: event.id })
const market = await predictions.markets.getMarket({ marketId: markets[0].id })The event listing has a fixed page
The gateway always returns page 1 with 50 events from listEvents and ignores any filter other than categoryId (there is no search, status or pagination). That is why the markets lists are arrays, not Page: filter and sort in the app. The (params?, options?) signature allows adding pagination later without breaking existing users.
event.topMarkets (when present) carries the highest-volume markets, enough for a listing card without calling listMarkets per event. Fields the gateway omits (ticker, outcomes, dates) are undefined: use ?..
getEvent and getMarket accept { eventId }/{ marketId } or { ticker }, never both (the type refuses it). An id that is empty, has leading or trailing whitespace, or contains /, . or .. rejects with CONFIGURATION_ERROR before any request (the SDK doesn't trim ids: pass them already clean).
Orderbook
const { bids, asks, spread, lastPriceYes } = await predictions.markets.getOrderbook({
marketId: market.id,
depth: 5, // levels per side; default 10, maximum 50
})
// bids[0] === { price: 61, quantity: 100, orderCount: 2 }bids and asks are lists of { price, quantity, orderCount } levels. It is a snapshot: to follow it live, use realtime: see Live orderbook.
Price history
const points = await predictions.markets.getPriceHistory({
marketId: market.id,
side: 'yes', // required: 'yes' | 'no'
interval: '1d', // '1h' (default) | '6h' | '1d' | '1w' | '1m'
limit: 30, // gateway default: 100
})
// points[0] === { timestamp, open, high, low, close, volume } // timestamp in seconds (Unix)side is required: omitting it is a type error, and a value other than yes/no (or an interval outside the list) at runtime rejects with CONFIGURATION_ERROR, with no request.
Errors
Always decide by code, never by HTTP status. Several predictions errors arrive with HTTP 500 (the gateway doesn't map them yet): MARKET_NOT_FOUND is an example.
import { isEnginexError } from '@getenginex/sdk'
try {
await predictions.markets.getMarket({ marketId })
} catch (error) {
if (isEnginexError(error, 'MARKET_NOT_FOUND')) showNotFound()
else throw error
}Unknown enums
Each enum (status, resolution, liquidityMode) is validated against the values the SDK knows. With validation: 'strict', a new value rejects with VALIDATION_ERROR. In 'warn' (the default) the field arrives as the gateway sent it (e.g. 'MARKET_STATUS_PAUSED', not normalized), onValidationIssue is notified and the rest of the response is still converted. That is why the enum types are open unions: handle the default case.
Testing
withPredictionsRoutes() ships 3 categories, 3 events and 5 fixed markets (mock-market-1 to mock-market-5), with deterministic orderbook and price history (the same id always returns the same response). Unknown ids return MARKET_NOT_FOUND/EVENT_NOT_FOUND with HTTP 500, like the gateway. To simulate an error, override the route (use the same parameter name as the mock's route):
createMockFetch(
withPredictionsRoutes({
routes: { 'GET /api/v1/predictions/markets/:marketId': () => fail(500, 'MARKET_NOT_FOUND') },
}),
)