Skip to content
Docs

Norynta public docs

Norynta Streaming And Reconciliation

Consume streaming endpoints reliably and reconcile live market state after disconnects, retries, and partial delivery.

Streaming and Reconciliation

Purpose

This document explains how to consume Norynta streaming endpoints reliably.

Audience

  • market data consumers
  • bot and agent developers
  • professional trading systems maintaining live state

Why this matters

Low-latency integrations fail most often when they over-trust stream continuity. The correct design is to combine:

  • snapshot seeding
  • live stream processing
  • reconnect logic
  • periodic reconciliation

Streaming endpoints

v1 stream manifest

  • GET /api/v1/streams/manifest

Use this before wiring a production bot. It defines:

  • channel keys
  • sequence behavior
  • snapshot endpoints
  • SSE endpoints available today
  • WebSocket topics for the locked contract
  • replay policy

The current production-ready path is SSE plus snapshot reconciliation. WebSocket topics follow the same manifest when the sender is deployed.

Event stream

  • GET /api/events/:slug/stream

Emits:

  • trades
  • orderbook
  • heartbeat

Orderbook stream

  • GET /api/events/:slug/orderbook/stream

Emits:

  • snapshot
  • delta
  • heartbeat

Recommended architecture

1. Seed from REST first

Before you trust streaming events, fetch:

  • GET /api/events/:slug/snapshot or
  • POST /api/events/snapshots

This gives you a known-good starting state.

2. Apply live updates

After seeding state, subscribe to the relevant stream and apply incoming events to your in-memory model.

3. Treat heartbeats as liveness only

Heartbeats mean the connection is alive. They are not proof your local state is fully correct.

4. Reconcile periodically

Even healthy streams should be reconciled against a fresh snapshot on a regular cadence.

5. Reconcile immediately after reconnect

If the stream drops, assume you may have missed updates. Pull a fresh snapshot before trusting new live deltas.

6. Handle sequence gaps

Each v1 stream channel uses a strictly increasing sequence value per channel key. If a gap is detected:

  1. pause strategy writes for the affected market/account
  2. request replay from /api/v1/streams/replay
  3. if replay returns complete: false, refresh the snapshot
  4. resume only after local state is rebuilt from a canonical snapshot

Replay is contract-ready, but persistent replay storage is not enabled until the stream event store is deployed. Current responses include remediation guidance and an empty event list.

Common failure patterns

Connection drop during volatile trading

Risk:

  • missed trades
  • stale best bid/ask
  • incorrect local decision inputs

Recovery:

  1. reconnect
  2. fetch fresh snapshot
  3. replace local state
  4. resume normal processing

Long-lived stream without periodic reseed

Risk:

  • silent drift between local and canonical state

Recovery:

  • schedule snapshot-based reconciliation even when no obvious failure is present

Over-polling instead of streaming

Risk:

  • wasted rate budget
  • worse latency
  • unnecessary infra load

Better approach:

  • use bulk snapshots for seeding
  • use stream for incremental updates
  • reserve REST refreshes for reconciliation

Suggested operating policy

For each tracked market:

  1. fetch snapshot
  2. start stream
  3. process heartbeats and updates
  4. if disconnect occurs, reconnect and reseed
  5. on schedule, pull another snapshot and compare

SDK support

Relevant helpers include:

  • createEventStream
  • createEventStreamNode

See:

  • src/lib/bot/sdk.ts
  • packages/bot-sdk/src/sdk.ts
  • examples/market-watcher.ts

Related docs

  • docs/DEVELOPERS.md
  • docs/public/API_OVERVIEW.md
  • docs/public/API_REFERENCE.md
  • docs/public/ORDERBOOK_AND_PRICING.md
  • docs/public/ERROR_CODES.md
  • docs/public/SDK_AND_EXAMPLES.md
  • docs/public/TRADING_INTEGRATION_WORKFLOW.md