Skip to main content

Subscribe to events

Use WebSockets to subscribe to events on the blockchain. For example, monitor an NFT smart contract to alert you when a new NFT is minted.

Stateless HTTP WebSockets are supported, however, we recommend using the WSS protocol to set up bidirectional stateful subscriptions.

info

For users on Infura's credit pricing plan, subscribing and unsubscribing to events using the eth_subscribe and eth_unsubscribe methods consume credits from your daily quota. Credits are consumed for these actions to prevent spamming, even if no valuable data is sent.

View the WebSocket pricing information for a breakdown of the costs.

You need to be aware of the following when sending HTTP RPC requests:

  • Silent failures - Users need to manage client-side silent failures.
  • Load balancing - Unlike HTTP requests, WSS requests are not load-balanced to the fastest possible server.
  • Retries - Retrying failed WebSocket requests typically requires custom JSON-RPC ID-based tracking, whereas support for retrying failed HTTP requests often is automatic, or easy to configure.
  • Status codes - WebSockets use its own set of status codes to provide users with a disconnection reason. The service will respond with the standard EVM response codes for each JSON-RPC request.

Example event subscription​

The following WebSocket subscription example fires a notification each time a new header is appended to the chain:

$ wscat -c wss://mainnet.infura.io/ws/v3/<YOUR-API-KEY>
> {"jsonrpc":  "2.0",  "id":  1,  "method":  "eth_subscribe",  "params":  ["newHeads"]}