Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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 o yes acertar. O yes e o no sã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ão MARKET_STATUS_OPEN), side: 'yes' | 'no'.

Categorias, eventos e mercados ​

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

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 ​

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

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

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

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