Skip to main content

​
Heartbeats (ping/pong)

BlockDB sends periodic WebSocket ping frames. Clients must respond with pong to keep the connection alive.
Most WebSocket libraries handle ping/pong automatically. If yours does not, enable keepalives or implement pong responses.

​
Idle timeout

Connections with no active subscriptions (or missing heartbeat responses) may be terminated after an idle period.
  • Recommendation: subscribe soon after connecting and keep ping/pong enabled.
  • If you intentionally idle: close the socket gracefully and reconnect when needed.

​
Reconnection strategy

You should assume transient disconnects (network, deploys, backpressure). Use exponential backoff with jitter:
  • 1s → 2s → 4s → 8s … (cap at ~30s)
  • add random jitter (e.g., ±20%)
# Reconnect loop with exponential backoff (cap 30s).
# Note: wscat is interactive; when the socket closes, the command exits and the loop retries.
attempt=0
while true; do
  delay=$((2 ** attempt))
  if [ "$delay" -gt 30 ]; then delay=30; fi

  echo "Connecting (attempt=$attempt)..."
  wscat -c wss://stream.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}'

  echo "Disconnected. Sleeping ${delay}s..."
  sleep "$delay"
  attempt=$((attempt + 1))
done

​
Resubscribe after reconnect

The WebSocket connection state is not preserved across reconnects. Maintain a local list of active subscriptions and re-send subscribe messages after open. For data continuity and reconciliation (especially around reorgs), see: Reliability & Reorgs.

​
Backpressure & rate control

If the server cannot deliver messages fast enough (or your client cannot process them fast enough), the connection may be closed to protect the system.
  • Common signal: close code 1013 TRY_AGAIN_LATER
  • What to do:
    • reconnect with longer backoff (and jitter)
    • reduce subscription count
    • add or tighten filters (params) on high-volume streams
    • move heavy processing off the receive loop
See: WSS Error Codes

​
Logging & support

When debugging connection stability, always log:
  • close code + reason (if provided)
  • timestamp (UTC)
  • the last subscribe message(s) you sent (redact API key)

​
See also