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.
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
// 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:
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
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 */ })