# Build reliable MadeOnSol WebSocket recovery

Handle reconnects, replay completion, duplicate events and current-state refreshes without claiming missing trade history was recovered.

Access: Pro and above; channel access varies

[Compare plans and subscribe](https://madeonsol.com/pricing#pricing)

Author: MadeOnSol

Updated: 2026-11-17

## Integration choice

Treat connection health, current state and historical completeness as separate concerns. A reconnected socket can be healthy while an earlier interval still needs reconciliation. Keep one owner for reconnects and persist processing checkpoints where restart recovery matters.

## Before you start

- A working standard WebSocket subscription and a backend event handler.
- A durable event store if processing must survive your own process restarting.

## Implementation steps

1. Start with the standard stream client in the WebSocket guide. Add durable processing and observability before adding more named subscriptions.
2. Use the stream token returned by POST /api/v1/stream/token. Normal calls reuse the token; do not schedule periodic rotation. Protect the token as a credential.
3. For replayable event frames, persist an event identity and processing result before advancing the resume checkpoint. Restore subscriptions and their exact filters on reconnect.
4. Inspect replay_end for each subscription, including complete, reason and per-channel details. Record affected intervals and choose a channel-specific repair.
5. For state streams, take the documented fresh snapshot. For historical events, reconcile with the matching historical API only where its scope and retention cover the missing interval.

## Track three independent states

Connected means the transport is open; subscribed means the server acknowledged the requested subscription. Neither alone means your application has processed its backlog. Record the last successful handler time and queue depth as well as socket status.

Replay is bounded. Its result reports what the service recovered, and per-channel details can carry limitations. A gap between global sequence numbers is not sufficient proof that your filtered subscription missed events. Do not describe replay as unlimited archival recovery.

## Commit effects before checkpoints

For named subscriptions, the same event may appear once under each matching sub_id. Use sub_id plus event id for delivery-level deduplication. If several subscriptions trigger the same business action, use a second key for that action so it happens once.

Persist the action, deduplication record and checkpoint transactionally where possible. An in-memory Set disappears on restart. For an external notification, use an outbox and the destination’s idempotency mechanism when available; a local database alone cannot guarantee exactly-once delivery to another service.

## Repair the right kind of data

Robinhood Chain price ticks are state updates without seq/id replay; a new subscription supplies a current snapshot. Holder-state recovery has its own cursor contract. Do not reuse one generic event cursor for every channel.

The terminal helper refreshes current state after reconnect. Its incomplete flag is not cleared by pretending that a new snapshot recovered old trades. Call acknowledgeHistoricalRecovery() only after your application has reconciled the missing history. Use backoff and jitter when reconnecting multiple processes.

## Reconnect jitter policy (standalone JavaScript)

~~~javascript
// Backoff policy to integrate into your reconnect controller.
// Demo only: no socket is opened here. Keep a single reconnect owner.
function reconnectDelay(attempt, random = Math.random) {
  if (!Number.isInteger(attempt) || attempt < 0) throw new Error("Invalid attempt");
  const cap = Math.min(30000, 1000 * 2 ** Math.min(attempt, 5));
  return Math.floor(cap / 2 + random() * cap / 2);
}
console.log(reconnectDelay(0, () => 0)); // 500 ms
console.log(reconnectDelay(20, () => 0)); // 15000 ms
// These delays are client policy. Respect a longer server-directed wait.
// Reset attempts after a stable, acknowledged session, not on every open.
// Inspect replay_end separately; transport recovery is not historical repair.
~~~

## Common mistakes and fixes

- Mark the cursor before the event handler finishes. Fix: Commit processing first; a failed handler must leave the prior checkpoint intact.

- Treat replay_end as proof of unlimited complete history. Fix: Read complete, reason and each channel’s recovery limitations.

- Rotate the stream token every hour. Fix: Reuse the normal token; explicit rotation is a credential-management action.

## Verify your integration

Disconnect a test client during traffic, restart it after a processed event and inject a handler failure. Verify applied events are not duplicated, a failed event cannot advance the checkpoint, and an incomplete replay remains unresolved until its interval is actually reconciled.

## Production checklist

- One reconnect controller per upstream connection.
- Durable checkpoints tested across process restarts.
- Replay outcome tracked per subscription.
- Separate repair policies for state and event history.

## Frequently asked questions

### Does reconnecting recover every missed trade?

No. Recovery is bounded and channel-specific. Inspect replay_end and use supported historical reads for intervals you can reconcile.

### Can I refresh a snapshot and mark historical recovery complete?

No. A snapshot restores current state. It does not reconstruct the sequence of trades or alerts that occurred while disconnected.

## Continue building

- [Recover a WebSocket feed after a disconnect](https://madeonsol.com/docs/websocket)
- [Merge live candles with historical OHLCV](https://madeonsol.com/docs/candles)
- [Scale a MadeOnSol terminal to multiple viewers](https://madeonsol.com/docs/terminal-at-scale)

## Match your plan to your workload

Compare capacity, channel access and display rights before launching.

[Compare plans and subscribe](https://madeonsol.com/pricing#pricing)

## Related reference

- [Stream subscription builder](https://madeonsol.com/api-docs#stream-config)
- [Streaming reference](https://madeonsol.com/streaming)
- [Errors and rate limits](https://madeonsol.com/api-docs#errors)

[Canonical guide](https://madeonsol.com/docs/realtime-reliability)
