Skip to navigation
JSON-RPC Reference

eth_subscribe

WebSocket required: eth_subscribe is only available over a persistent WebSocket connection (wss://). Starting August 4, 2026 at 12:00 PM PST, WebSocket connections require an authenticated Conduit account — append an API key to your WSS URL; anonymous connections are rejected. It cannot be used over HTTP and will fail against any HTTP endpoint. Use your Conduit WebSocket URL (wss://rpc-{chainSlug}.t.conduit.xyz/{apiKey}) with a WebSocket client such as websockets in Python, the native WebSocket in JavaScript, or gorilla/websocket in Go.

Creates a subscription for real-time events. Supported subscription types include newHeads, logs, newPendingTransactions, and syncing.

⚡ Compute Units: 10 CU

Request

This endpoint expects an object.
subscriptionTypeenumRequired
Type of subscription
Allowed values:
optionsobject or booleanOptional

Per-subscription-type options. Shape depends on subscriptionType:

  • newHeads: no options accepted.
  • logs: optional filter object {address?, topics?} mirroring the Filter shape minus blockHash/fromBlock/toBlock. address is a single address or array; topics is the positional array with single/array/null per position.
  • newPendingTransactions: optional boolean. When true, the notification payload includes the full transaction object instead of just the transaction hash.
  • syncing: no options accepted.

Response

Opaque subscription ID returned by the server. Pass this to eth_unsubscribe to cancel the subscription. Not a numeric quantity — treat as an opaque hex string.