Listen to events

Stream contract events as they happen over a WebSocket subscription, and fetch past events with eth_getLogs, in viem, ethers, or web3.py.

Contracts emit events to record what happened, such as a token transfer. This recipe watches Transfer events from USDC on Sei Mainnet as they happen. Then it fetches past Transfer events. USDC has many transfers, so new events usually arrive within a minute.

Pick the right endpoint

Use a different public endpoint for each task:

Task	Endpoint	Sei Mainnet	Sei Testnet
Live events (eth_subscribe)	WebSocket	wss://evm-ws.sei-apis.com	wss://evm-ws-testnet.sei-apis.com
Past events (eth_getLogs)	HTTP	https://evm-rpc.sei-apis.com	https://evm-rpc-testnet.sei-apis.com

Watch live events over WebSocket. Watchers that poll the public HTTP endpoints for new events can miss events or report them twice. Fetch past events over HTTP, because the public WebSocket endpoints do not serve eth_getLogs.

Install

viem

npm install viem

The TypeScript examples use top-level await. Save each one as a .mts file, such as script.mts. Run it with npx tsx script.mts on Node.js 18 or later. In a new npm project, tsx compiles a plain .ts file as CommonJS, where top-level await does not work.

Watch new events

Each script prints a line for every USDC transfer. The script runs until you stop it with Ctrl+C.

viem

import { createPublicClient, webSocket, parseAbiItem, formatUnits } from 'viem';
import { sei } from 'viem/chains';

const client = createPublicClient({
  chain: sei,
  transport: webSocket('wss://evm-ws.sei-apis.com'),
});

const USDC = '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392';

const unwatch = client.watchEvent({
  address: USDC,
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  strict: true,
  onLogs: (logs) => {
    for (const { args, blockNumber } of logs) {
      console.log(`${args.from} -> ${args.to}: ${formatUnits(args.value, 6)} USDC (block ${blockNumber})`);
    }
  },
  onError: (error) => console.error(error.message),
});
// Call unwatch() to stop the subscription

You are done when you see:

0x3D20…CB04 -> 0x8397…62C4: 27.847524 USDC (block 235331015)

The scripts print the full sender and recipient addresses. The example output above shortens them. Sei has instant finality, so each event is final when it arrives. You do not need to wait for confirmations or handle reorganizations.

The web3.py example uses the subscription manager, which needs web3.py 7.7 or later.

Fetch past events

eth_getLogs returns the events in a block range. On the public endpoints, one request can cover at most 2,000 blocks. A larger range fails with block range too large. This example fetches the transfers from the latest 1,000 blocks.

viem

import { createPublicClient, http, parseAbiItem } from 'viem';
import { sei } from 'viem/chains';

const client = createPublicClient({ chain: sei, transport: http() });

const USDC = '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392';
const latest = await client.getBlockNumber();

const logs = await client.getLogs({
  address: USDC,
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  fromBlock: latest - 999n,
  toBlock: latest,
});
console.log(`${logs.length} transfers in blocks ${latest - 999n} to ${latest}`);

You are done when you see:

319 transfers in blocks 235329562 to 235330561

To cover a longer range, split it into windows of 2,000 blocks or fewer. Request the windows one after another. For a full history of a contract, use an indexer instead of eth_getLogs.

Related recipes

• WebSocket connections: new blocks and the newHeads subscription
• Transaction lifecycle: decode the events from one transaction’s receipt
• Deploy an ERC-20: deploy a token that emits its own Transfer events