Mercados y orderbook
El namespace markets de @getenginex/sdk-predictions cubre el catálogo: categorías → eventos → mercados → orderbook e historial de precios. Todas las rutas son públicas (el SDK nunca envía token en ellas), así que la vitrina funciona sin login. En pruebas, withPredictionsRoutes ya responde a todas (consulta Pruebas).
Precios, cantidades y dinero
- Precio en centavos, entero, de 1 a 99.
lastPriceYes: 62son 62 centavos por contrato, que paga 100 si elyesacierta.yesynoson precios independientes de la última operación de cada lado (lastPriceNo: 38): tienden a sumar cerca de 100, pero no es una identidad. - Cantidad en contratos (entero). Los volúmenes (
volume24h,totalVolume) y los límites (minOrderSize,maxPosition) van en centavos de la moneda de liquidación (settlementCurrency). - Los enums llegan en minúsculas y sin el prefijo de protobuf:
status: 'open'(noMARKET_STATUS_OPEN),side: 'yes' | 'no'.
Categorías, eventos y 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 })El listado de eventos tiene página fija
El gateway devuelve siempre la página 1 con 50 eventos en listEvents e ignora cualquier filtro que no sea categoryId (no hay búsqueda, estado ni paginación). Por eso las listas de markets son arrays, no Page: filtra y ordena en la app. La firma (params?, options?) permite ganar paginación después sin romper a quien ya lo usa.
event.topMarkets (cuando está presente) trae los mercados de mayor volumen, suficiente para una tarjeta de listado sin llamar a listMarkets por evento. Los campos que el gateway omite (ticker, outcomes, fechas) quedan undefined: usa ?..
getEvent y getMarket aceptan { eventId }/{ marketId } o { ticker }, nunca los dos (el tipo lo rechaza). Un id vacío, con espacio al inicio o al final, o con /, . o .. rechaza con CONFIGURATION_ERROR antes de cualquier request (el SDK no recorta ids: pásalos ya limpios).
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 y asks son listas de niveles { price, quantity, orderCount }. Es una instantánea: para seguirlo en vivo, usa el tiempo real: consulta Orderbook en vivo.
Historial de precios
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 es obligatorio: omitirlo da error de tipo, y un valor distinto de yes/no (o un interval fuera de la lista) en runtime rechaza con CONFIGURATION_ERROR, sin request.
Errores
Decide siempre por el code, nunca por el estado HTTP. Varios errores de predictions llegan con HTTP 500 (el gateway aún no los mapea): MARKET_NOT_FOUND es un ejemplo.
import { isEnginexError } from '@getenginex/sdk'
try {
await predictions.markets.getMarket({ marketId })
} catch (error) {
if (isEnginexError(error, 'MARKET_NOT_FOUND')) showNotFound()
else throw error
}Enums desconocidos
Cada enum (status, resolution, liquidityMode) se valida contra los valores que el SDK conoce. Con validation: 'strict', un valor nuevo rechaza con VALIDATION_ERROR. En 'warn' (el valor por defecto) el campo llega como lo envió el gateway (p. ej., 'MARKET_STATUS_PAUSED', sin normalizar), onValidationIssue recibe el aviso y el resto de la respuesta sigue convertido. Por eso los tipos de los enums son uniones abiertas: maneja el caso por defecto.
Pruebas
withPredictionsRoutes() trae 3 categorías, 3 eventos y 5 mercados fijos (mock-market-1 a mock-market-5), con orderbook e historial de precios determinísticos (el mismo id siempre devuelve la misma respuesta). Los ids desconocidos devuelven MARKET_NOT_FOUND/EVENT_NOT_FOUND con HTTP 500, como el gateway. Para simular un error, sobrescribe la ruta (usa el mismo nombre de parámetro de la ruta del mock):
createMockFetch(
withPredictionsRoutes({
routes: { 'GET /api/v1/predictions/markets/:marketId': () => fail(500, 'MARKET_NOT_FOUND') },
}),
)