Skip to main content
Stream new blocks and contract events from StableNet using WebSocket subscriptions and log queries.

What you’ll learn

By the end of this tutorial, you’ll be able to:
  • Subscribe to new block headers via WebSocket
  • Subscribe to contract events matching a topic filter
  • Query historical logs for a contract using eth_getLogs

Prerequisites

  • Node.js ≥ 18
  • npm install ethers (v6)
  • A deployed contract that emits events (e.g., the WKRCPayment contract from Deploy with Foundry)

Connect via WebSocket

eth_subscribe requires a persistent WebSocket connection. HTTP endpoints do not support subscriptions.

Subscribe to new block headers

Each new block emits a header event. Use this to track chain progress or trigger polling logic.

Subscribe to contract events

To receive events from a specific contract, pass the contract’s ABI and address to an ethers.Contract instance. The example below listens for Payment events from the WKRCPayment contract.

Filter events by topic

To receive events only from a specific sender, add a topic filter. EVM topic filters use null as a wildcard.

Query historical logs with eth_getLogs

Use eth_getLogs to query past events without a persistent connection. Specify a block range and optional topic filters.

Clean up subscriptions

Remove event listeners when you no longer need them to avoid memory leaks.

Topic matching rules

Topics map to indexed event parameters. Multiple values in one position are OR conditions; positions without a value are wildcards. A maximum of 4 topic positions is supported.

Next steps

Deploy with Foundry

Deploy a contract that emits events.

RPC API Reference

Full reference for eth_subscribe, eth_getLogs, and filter methods.

Read On-Chain Data

Query balances, storage slots, and contract state.

Fee Delegation

Let a separate account pay gas for your users.