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

Orderbook ao vivo ​

Carregando a demo interativa…

A demo acima roda o SDK de verdade (createPredictions, createRealtime) com createMockFetch, withPredictionsRoutes e createMockRealtime de @getenginex/sdk/testing: nenhuma chamada sai para a rede. O livro é público: a base vem de markets.getOrderbook e cada orderbook_update substitui a base (a demo trata a mensagem como o livro inteiro, que é a convenção mais segura enquanto o formato do delta não é confirmado, veja o aviso abaixo). Drop the connection perde um negócio de propósito e o onResync recarrega o livro por HTTP. Depois do login, o formulário envia uma ordem limitada (preço de 1 a 99) ou a mercado (sem preço) com orders.place e uma Idempotency-Key por intenção; a ordem enviada também aparece no livro, pelo tempo real. No cenário Network failure a resposta se perde e a nova tentativa reusa a chave e recebe a mesma ordem. A chave aparece mascarada no painel Under the hood, como a URL do WebSocket (token).

predictionsTopics.orderbook({ marketId }) avisa cada mudança no orderbook de um mercado sem polling. Os conceitos (conexão, status, onResync) estão em Realtime. O tópico é público: funciona sem login.

1. Base por HTTP, depois o tempo real ​

O SDK não aplica deltas: a base vem de markets.getOrderbook e o app decide como combinar as atualizações com ela.

ts
import { createRealtime } from '@getenginex/sdk/realtime'
import { createPredictions } from '@getenginex/sdk-predictions'
import { predictionsTopics } from '@getenginex/sdk-predictions/realtime'

const predictions = createPredictions(enginex)
const realtime = createRealtime(enginex)

async function loadBook(marketId: string) {
  const book = await predictions.markets.getOrderbook({ marketId, depth: 20 })
  render(book)
}

async function watchBook(marketId: string) {
  await loadBook(marketId) // initial base
  const topic = predictionsTopics.orderbook({ marketId })
  const off = realtime.subscribe(topic, (update, meta) => {
    // update: { marketId, bids, asks, lastPriceYes, lastPriceNo, spread, updatedAt }
    if (meta.kind === 'snapshot') return render(update) // full snapshot (sequenced mode)
    applyUpdate(update) // app rule, see the warning below
  })
  // after a drop and reconnection, reload the base over HTTP
  const offResync = realtime.onResync(topic, () => void loadBook(marketId))
  return () => {
    off()
    offResync()
  }
}

Semântica de delta

O gateway publica cada orderbook_update no formato do orderbook, mas o SDK não garante a convenção de aplicação: não está verificado se uma mensagem traz o livro inteiro ou só os níveis que mudaram, nem se quantity: 0 remove o nível. Por isso o SDK não traz um helper de merge. Se o seu gateway publica níveis parciais, confirme a convenção com o time do gateway antes de mesclar; o caminho mais seguro é tratar cada mensagem como a foto atual e recarregar por HTTP no onResync.

Snapshot no modo sequenciado ​

Só no modo single-tenant (WS_SEQUENCED=true) o gateway numera as mensagens e envia um snapshot ao assinar. No tópico de orderbook esse snapshot tem o mesmo formato do orderbook_update e é entregue com meta.kind === 'snapshot' (e meta.seq). Em produção multi-tenant não há snapshot nem seq: uma mensagem perdida numa queda não é detectável, e o onResync é que mantém a tela certa.

Outros tópicos ​

ts
// executed trades
realtime.subscribe(predictionsTopics.trades({ marketId }), (trade) => {
  // { tradeId, marketId, side: 'yes' | 'no', price, quantity, makerFee, takerFee, executedAt }
})

// prices, volume and market status
realtime.subscribe(predictionsTopics.market({ marketId }), (m) => {
  // { marketId, eventId, status, lastPriceYes, lastPriceNo, volume24h, totalVolume, openInterest,
  //   bestBidYes?, bestAskYes?, bestBidNo?, bestAskNo?, updatedAt }
})

Em trades, o snapshot do modo sequenciado é o histórico de preços cru do gateway (outro formato que o trade_update): o SDK não o entrega (como o balance do core); os negócios novos seguem chegando, e a base vem de markets.getPriceHistory. Em market, o snapshot tem o mesmo formato do market_update e é entregue.

Ordens ao vivo ​

predictionsTopics.orders() é privado: usa o usuário da sessão e realtime.subscribe lança UNAUTHENTICATED sem login. Cada mudança de situação de uma ordem do usuário chega como OrderStatusUpdate:

ts
const off = realtime.subscribe(predictionsTopics.orders(), (order) => {
  // { orderId, marketId, side, direction, status, price, quantity, filledQuantity, remainingQuantity,
  //   lastFillPrice?, lastFillQuantity?, lastFillTradeId?, updatedAt }
  if (order.status === 'filled') toast('Order filled')
})
// reload the orders over HTTP (private topic: applies to the session's user)
realtime.onResync(predictionsTopics.orders(), () => void predictions.orders.list())

side, direction e status chegam em minúsculas ('yes', 'buy', 'partial'), mesmo se o gateway publicar ORDER_SIDE_YES: o SDK aceita os dois estilos. Não use o evento para lançar saldo: wallet.getBalance() e coreTopics.balance() são a fonte do dinheiro.

Testando ​

ts
import { createMockRealtime } from '@getenginex/sdk/testing'

const mock = createMockRealtime()
const enginex = createEnginexClient({ /* ... */ webSocket: mock.webSocket })
// ... subscribe, wait for the connection to open
mock.emit('predictions:orderbook:mkt-1', 'orderbook_update', {
  market_id: 'mkt-1',
  bids: [{ price: 61, quantity: 100, order_count: 2 }],
  asks: [{ price: 63, quantity: 50, order_count: 1 }],
  last_price_yes: 62,
  last_price_no: 38,
  spread: 2,
  updated_at: '2026-09-30T12:00:00Z',
})
mock.emitSequenced('predictions:orderbook:mkt-1', 'snapshot', 1, { /* same payload */ })