WebSocket

Availability

WebSocket requires a paid plan or active PAYG. Free, public and demo access remain HTTPS-only. Only networks with qualified native self-hosted and fallback sources are enabled.

Available networks: Ethereum (1), BNB Smart Chain (56), Base (8453), Arbitrum One (42161), Optimism (10), Robinhood Chain (4663), Arc Mainnet (5042), Polygon PoS (137), Cronos (25), Unichain (130), World Chain (480), Arc Testnet (5042002).

The network API reports websocket.availability, websocket.url and websocket.subscriptionTypes. An unavailable network has no WebSocket URL. Avalanche and external-only networks remain HTTPS-only.

Connect and subscribe

Copy the WSS endpoint from Endpoints. Its shape is wss://rpc.solidrpc.io/ws/YOUR_API_KEY/evm/CHAIN_ID. Use the staging host only with staging credentials. Treat the URL as a secret.

Send this JSON-RPC request over the open socket:

{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}

The acknowledgment returns your subscription ID:

{"jsonrpc":"2.0","id":1,"result":"0xYOUR_SUBSCRIPTION_ID"}

Heads arrive as eth_subscription notifications. params.subscription identifies your subscription and params.result contains the native header, including its number, hash and parent hash. A head is not a finality guarantee. Replacement heads can signal a reorganization.

To stop one subscription, send:

{"jsonrpc":"2.0","id":2,"method":"eth_unsubscribe","params":["0xYOUR_SUBSCRIPTION_ID"]}

The result is true when that subscription was removed, or false if it did not exist on this connection. Ordinary stateless JSON-RPC calls use the same request and response formats as HTTPS and retain SolidRPC routing.

Supported methods and security

Ordinary stateless JSON-RPC calls are supported. Subscriptions support newHeads only. Log, pending-transaction and other subscription types are rejected. Node-local filters, including eth_newFilter, eth_newBlockFilter, eth_newPendingTransactionFilter, eth_getFilterChanges, eth_getFilterLogs and eth_uninstallFilter, are unsupported. Subscription controls must be individual requests with an ID.

API-key chain, method, IP and JWT restrictions apply. Allow eth_subscribe and eth_unsubscribe in a restricted method policy when using subscriptions. Active credentials are revalidated at least every five seconds and connections close when a required JWT expires.

For a JWT-protected key, supply Authorization: Bearer YOUR_JWT during the upgrade handshake. This requires a client that supports custom authorization headers. The browser WebSocket API cannot supply that header and cannot use a JWT-protected key. Do not put the JWT in the URL or a subprotocol.

Billing and limits

Each notification successfully written to your connection consumes one existing response unit. This means the socket write completed, not that your application acknowledged it. Ordinary calls retain the existing billable-result rules. HTTPS calls, WebSocket calls and pushed heads share your account allowance, rate and burst limits, including existing PAYG invoice bounds. There is no separate WebSocket price.

Connection setup, subscribe/unsubscribe acknowledgments, ping/pong, internal retries and suppressed upstream duplicates are free. Two subscriptions to the same chain create two separately counted deliveries. Shared upstream feeds do not make those customer deliveries free.

Limits are 100 sockets and 100 subscriptions per account across replicas, with at most 10 subscriptions per socket. Connections, frame sizes and outbound queues are bounded. A slow reader or sustained rate exhaustion causes an explicit disconnect. Reconcile after reconnecting. See rate limits and pricing.

All WebSocket traffic, including ordinary JSON-RPC carried over WebSocket, is excluded from monetary SLA evidence and credits in v1. See the Service Level Terms.

Recovery and errors

SolidRPC keeps your subscription ID stable during upstream failover, suppresses duplicate hashes and avoids replaying stale heads from lagging sources. If every native source becomes unavailable, it retries internally for up to 30 seconds, then closes affected connections. Notifications are never synthesized from HTTP polling.

The stream is live-only and has no durable replay. Save the last processed block number and hash. After a disconnect, reconnect with backoff and jitter, resubscribe, and fetch missed blocks through SolidRPC. Compare parent hashes and reconcile replacement blocks before advancing your cursor. You do not need to manage another RPC provider.

Handshake denials use HTTP status codes: 400 for conflicting credentials, 401/403 for authorization, 404 for unsupported routes or networks, 429 for admission limits, and 503 while unavailable. After upgrade, method errors use JSON-RPC responses. Connection closes identify policy changes, unavailable sources, service restarts or backpressure. Do not interpret a close as successful delivery.