This version (v0.7) has not been published to npm yet.
Skip to content

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: 62 is 62 cents per contract, which pays 100 if the yes is right. yes and no are 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' (not MARKET_STATUS_OPEN), side: 'yes' | 'no'.

Categories, events and markets ​

ts
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 ​

ts
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 ​

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

ts
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):

ts
createMockFetch(
  withPredictionsRoutes({
    routes: { 'GET /api/v1/predictions/markets/:marketId': () => fail(500, 'MARKET_NOT_FOUND') },
  }),
)