Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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: 62 son 62 centavos por contrato, que paga 100 si el yes acierta. yes y no son 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' (no MARKET_STATUS_OPEN), side: 'yes' | 'no'.

Categorías, eventos y 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 })

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 ​

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

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

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

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