explorer-monorepo/docs/specs/api/websocket-api.md

WebSocket API Specification

Overview

This document specifies the WebSocket API for real-time blockchain data subscriptions, including new blocks, pending transactions, and address activity.

Endpoint: wss://api.explorer.d-bis.org/ws

Connection Lifecycle

Connection

URL: wss://api.explorer.d-bis.org/ws?chain_id=138

Query Parameters:

• chain_id (optional): Default chain ID for subscriptions
• api_key (optional): API key for authenticated connections

Headers:

• Authorization: Bearer <token> (optional)

Authentication

Methods:

1. Query parameter: ?api_key=<key>
2. Header: Authorization: Bearer <token>
3. Message: Send auth message after connection

Auth Message:

{
  "type": "auth",
  "api_key": "your-api-key"
}

Response:

{
  "type": "auth_success",
  "user_id": "uuid",
  "tier": "pro"
}

Heartbeat

Purpose: Keep connection alive and detect disconnections.

Client Ping: Send every 30 seconds

{
  "type": "ping"
}

Server Pong: Response within 1 second

{
  "type": "pong",
  "timestamp": 1640995200
}

Timeout: Connection closed if no pong received within 60 seconds

Subscription Model

Subscribe to New Blocks

Request:

{
  "type": "subscribe",
  "channel": "blocks",
  "chain_id": 138,
  "params": {
    "include_transactions": false
  }
}

Response:

{
  "type": "subscribed",
  "subscription_id": "sub_123",
  "channel": "blocks"
}

Updates:

{
  "type": "update",
  "subscription_id": "sub_123",
  "data": {
    "number": 12345,
    "hash": "0x...",
    "timestamp": "2024-01-01T00:00:00Z",
    "transaction_count": 100
  }
}

Subscribe to Pending Transactions

Request:

{
  "type": "subscribe",
  "channel": "pending_transactions",
  "chain_id": 138,
  "params": {
    "from_address": "0x...",  // Optional filter
    "min_value": "1000000000000000000"  // Optional filter
  }
}

Updates: Transaction objects as they enter mempool

Subscribe to Address Activity

Request:

{
  "type": "subscribe",
  "channel": "address",
  "chain_id": 138,
  "params": {
    "address": "0x..."
  }
}

Updates: Transactions involving the address

Subscribe to Logs/Events

Request:

{
  "type": "subscribe",
  "channel": "logs",
  "chain_id": 138,
  "params": {
    "address": "0x...",
    "topics": ["0xddf252..."]  // Event signatures
  }
}

Updates: Matching log entries

Unsubscribe

Request:

{
  "type": "unsubscribe",
  "subscription_id": "sub_123"
}

Response:

{
  "type": "unsubscribed",
  "subscription_id": "sub_123"
}

Message Formats

Client Messages

Subscribe:

{
  "type": "subscribe",
  "channel": "<channel_name>",
  "chain_id": 138,
  "params": { ... }
}

Unsubscribe:

{
  "type": "unsubscribe",
  "subscription_id": "<id>"
}

Ping:

{
  "type": "ping"
}

Server Messages

Update:

{
  "type": "update",
  "subscription_id": "<id>",
  "data": { ... }
}

Error:

{
  "type": "error",
  "code": "invalid_subscription",
  "message": "Invalid subscription parameters",
  "subscription_id": "<id>"
}

Notification:

{
  "type": "notification",
  "level": "info",  // info, warning, error
  "message": "Subscription limit reached"
}

Subscription Limits

Per Connection:

• Anonymous: 5 subscriptions
• Free API Key: 20 subscriptions
• Pro API Key: 100 subscriptions
• Enterprise: Unlimited

Per Chain:

• Limit subscriptions per chain to prevent abuse

Reconnection Strategy

Automatic Reconnection

Strategy: Exponential backoff

Backoff Schedule:

• Initial: 1 second
• Max: 60 seconds
• Multiplier: 2x

Behavior:

• Reconnect automatically
• Resubscribe to all active subscriptions
• Resume from last received update

Manual Reconnection

Steps:

1. Close connection gracefully
2. Reconnect with same parameters
3. Resubscribe to desired channels

Rate Limiting

Limits:

• Message rate: 10 messages/second per connection
• Subscription rate: 5 subscriptions/minute per connection
• Update rate: Throttled per subscription type

Throttling: Server may batch or skip updates if client cannot keep up

Error Codes

• invalid_message: Malformed message
• invalid_subscription: Invalid subscription parameters
• subscription_limit: Too many subscriptions
• rate_limit: Rate limit exceeded
• unauthorized: Authentication required
• chain_not_supported: Chain ID not supported
• internal_error: Server error

Security Considerations

Connection Security

• WSS (WebSocket Secure) required
• TLS 1.2+ only
• Certificate validation

Authentication

• API key validation
• User permission checks
• Subscription authorization

Message Validation

• Validate all incoming messages
• Sanitize parameters
• Reject invalid requests

Performance Considerations

Message Batching

Strategy: Batch multiple updates into single message when possible

Example:

{
  "type": "batch_update",
  "updates": [
    { "subscription_id": "sub_1", "data": {...} },
    { "subscription_id": "sub_2", "data": {...} }
  ]
}

Backpressure

Strategy: Drop updates if client cannot process them

Indicators:

• Client buffer full
• No ping/pong responses
• Slow message processing

References

• REST API: See rest-api.md
• GraphQL API: See graphql-api.md
• Mempool Service: See ../mempool/mempool-service.md