AI Guide Map
Candle-Close Pipeline with Binance APIs & WebSockets
Binance Spot market-data systems can combine REST candle backfill, live kline WebSockets, buffered handoff, final-candle workflow execution, reconnect resync, and clean shutdown.
Perfect for indicator driven systems that need a cache of candles, with a trigger on candle close.
Default Scope
- Runtime: Node.js LTS
- Recommended language: TypeScript
- Package: binance
- Product: Binance Spot
- Starter sample: BTCUSDT 1m with explicit symbol and interval config
- Example use case: Converting a PineScript strategy or indicator that relies on candle closes into a realtime system with live data and historical backfill.
- Credentials: public endpoints only
Resources
Start with the task-specific resources below, then use SDK and exchange docs to verify exact method names, request fields, topics, and product rules.
Historical Backfill with Live WebSocket Streams
Historical Backfill with Live WebSocket Streams recipe
Historical Backfill with Live WebSocket Streams Conformance Pack
Binance JavaScript SDK guide
AI prompt generator
Machine-readable recipe
Markdown snapshot
Task-focused LLM index
SDK catalog
Agent skill
Binance SDK repository
Siebly examples repository
Implementation Steps
Follow these in order; use the linked artifacts only where they clarify the current step.
1. Verify SDK surfaces first
Before writing code, inspect the current SDK docs, examples, types, and source for the real kline subscription helper, REST candle method, formatted event type guard, final-candle field, subscription acknowledgement event, reconnect hook, and shutdown method for the selected Binance product group. Spot is the starter scope here; USD-M, COIN-M, or other product groups can use different clients, methods, request fields, and public stream topics.
- For Spot, expected surfaces to verify include subscribeSpotKline(...), MainClient.getKlines(), isWsFormattedKline(...), data.kline.final, response, reconnected, and closeAll(). If the product group changes, verify and use that product group’s current kline client, REST candle method, topic, subscription acknowledgement path, finality field, reconnect hook, and shutdown method.
- Do not invent stream names, event names, or payload fields if the package has typed helpers.
2. Subscribe before backfill
Open the public WebSocket and send the selected product group kline subscription before starting REST backfill. This prevents missing live candles that arrive during historical hydration.
- Treat socket open, subscribe request sent, and subscription acknowledgement as separate lifecycle states.
- Do not assume subscribe() means subscription acknowledgement.
3. Buffer live events during backfill
Once subscription acknowledgement is observed, buffer incoming kline events without applying workflow side effects. Backfill recent candles over REST into an in-memory store keyed by symbol, interval, and candle open time.
- Normalize open time, close time, OHLCV fields, interval, symbol, and finalization state.
- Deduplicate historical records before replaying buffered live events.
4. Replay, then enable live processing
After REST backfill completes, replay buffered WebSocket events in deterministic event-time order. Skip stale or duplicate candles, update the store, then mark the pipeline strategy-ready.
- The system is not strategy-ready until subscription acknowledgement, backfill, buffered replay, and live-processing enablement are complete.
- Open candles may update local state, but cannot trigger strategy, indicator, signal generation, optional external alert, order-intent, or account-decision workflows.
5. Run workflows only on closed candles
If the data type has a finality signal, run strategy, indicator, signal generation, optional external alert, order-intent, or account-decision workflows only after that final/closed/terminal signal.
- Use the current formatted kline type guard before reading normalized kline fields.
- Use the current finalization field from the SDK payload, not an inferred timer.
6. Resync after reconnect
A WebSocket reconnect restores transport, not application correctness. On reconnect, keep streams connected and buffering where possible, pause only downstream candle-close actions, resubscribe if needed, run REST resync/reconciliation, replay buffered events, then re-enable candle-close processing.
- Log reconnecting, reconnected, resync started, resync completed, and strategy-ready transitions.
- Reconnects must not create duplicate candles or duplicate workflow executions.
7. Shut down cleanly
Handle process signals and close SDK WebSocket connections before exit. Persisting state is optional for the initial implementation, but the in-memory store should have a clear boundary so storage can be swapped later.
- Use the SDK shutdown method verified from current docs/source.
- Document the public-only boundary and the no-live-orders guarantee in README/setup notes.
8. Prove lifecycle behavior
Keep the page implementation public-data-only, but still validate the complete data lifecycle before treating it as ready.
- Candle lifecycle validation must cover subscription acknowledgement, REST backfill, buffered replay, duplicate/stale/out-of-order candles, open-candle no-op, final-candle once-only execution, malformed or wrong-symbol events, reconnect resync, public-only boundaries, and sample-symbol/config handling.
- Do not copy the starter BTCUSDT/1m sample into runtime defaults; symbol and interval stay explicit config.
- Do not mark the pipeline complete until three consecutive full data-lifecycle review passes produce no code, tests, fixtures, or documentation changes.
Pipeline invariants
- Correctness-sensitive workflows cannot run until the selected subscription acknowledgement, backfill, buffered replay, and live-processing gates are complete.
- Open candles may update local state, but cannot trigger strategy, indicator, signal generation, optional external alert, order-intent, or account-decision workflows.
- Reconnect handling must pause strategy readiness until REST resync/reconciliation completes.
- The code must run without API keys and must not include private clients, account reads, or order endpoints.
- Every data-lifecycle claim in README or code comments needs a fixture or replay case. Behaviors without fixtures should be documented as unsupported or unverified.