---
url: https://game-engine-io.github.io/enginex-frontend-sdk/predictions/markets.md
---
# Markets and orderbook

The `markets` namespace of [`@getenginex/sdk-predictions`](/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](#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 })
```

::: warning 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](/predictions/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 {#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 {#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') },
  }),
)
```
