Mercados e orderbook
O namespace markets de @getenginex/sdk-predictions cobre o catálogo: categorias → eventos → mercados → orderbook e histórico de preços. Todas as rotas são públicas (o SDK nunca manda token nelas), então a vitrine funciona sem login. Em testes, withPredictionsRoutes já responde a todas (veja Testes).
Preços, quantidades e dinheiro
- Preço em centavos, inteiro, de 1 a 99.
lastPriceYes: 62é 62 centavos por contrato, que paga 100 se oyesacertar. Oyese onosão preços independentes do último negócio de cada lado (lastPriceNo: 38): tendem a somar cerca de 100, mas não é uma identidade. - Quantidade em contratos (inteiro). Volumes (
volume24h,totalVolume) e limites (minOrderSize,maxPosition) em centavos da moeda de liquidação (settlementCurrency). - Os enums chegam em minúsculas e sem o prefixo do protobuf:
status: 'open'(nãoMARKET_STATUS_OPEN),side: 'yes' | 'no'.
Categorias, eventos e mercados
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 })A listagem de eventos tem página fixa
O gateway devolve sempre a página 1 com 50 eventos em listEvents e ignora qualquer filtro além de categoryId (não há busca, status nem paginação). Por isso as listas de markets são arrays, não Page: filtre e ordene no app. A assinatura (params?, options?) permite ganhar paginação depois sem quebrar quem já usa.
event.topMarkets (quando presente) traz os mercados de maior volume, o bastante para um cartão de listagem sem chamar listMarkets por evento. Campos que o gateway omite (ticker, outcomes, datas) ficam undefined: use ?..
getEvent e getMarket aceitam { eventId }/{ marketId } ou { ticker }, nunca os dois (o tipo recusa). Um id vazio, com espaço no início ou no fim, com /, . ou .. rejeita com CONFIGURATION_ERROR antes de qualquer request (o SDK não apara ids: passe-os já limpos).
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 e asks são listas de níveis { price, quantity, orderCount }. É uma foto: para acompanhar ao vivo, use o tempo real: veja Orderbook ao vivo.
Histórico de preços
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 é obrigatório: omitir dá erro de tipo, e um valor fora de yes/no (ou um interval fora da lista) em runtime rejeita com CONFIGURATION_ERROR, sem request.
Erros
Decida sempre pelo code, nunca pelo status HTTP. Vários erros de predictions chegam com HTTP 500 (o gateway ainda não os mapeia): MARKET_NOT_FOUND é o exemplo.
import { isEnginexError } from '@getenginex/sdk'
try {
await predictions.markets.getMarket({ marketId })
} catch (error) {
if (isEnginexError(error, 'MARKET_NOT_FOUND')) showNotFound()
else throw error
}Enums desconhecidos
Cada enum (status, resolution, liquidityMode) é validado contra os valores que o SDK conhece. Com validation: 'strict', um valor novo rejeita com VALIDATION_ERROR. Em 'warn' (o padrão) o campo chega como o gateway o enviou (ex.: 'MARKET_STATUS_PAUSED', sem normalizar), o onValidationIssue é avisado e o resto da resposta continua convertido. Por isso os tipos dos enums são uniões abertas: trate o caso padrão.
Testes
withPredictionsRoutes() traz 3 categorias, 3 eventos e 5 mercados fixos (mock-market-1 a mock-market-5), com orderbook e histórico de preços determinísticos (o mesmo id sempre devolve a mesma resposta). Ids desconhecidos devolvem MARKET_NOT_FOUND/EVENT_NOT_FOUND com HTTP 500, como o gateway. Para simular um erro, sobrescreva a rota (use o mesmo nome de parâmetro da rota do mock):
createMockFetch(
withPredictionsRoutes({
routes: { 'GET /api/v1/predictions/markets/:marketId': () => fail(500, 'MARKET_NOT_FOUND') },
}),
)