eth_subscribe - AVAX

Example code for the eth_subscribe JSON-RPC method. Complete guide on how to use eth_subscribe JSON-RPC in GetBlock Web3 documentation.

Creates a real-time subscription over a WebSocket connection on the C-Chain. Available subscription types: newHeads (new block headers), logs (matching contract events), newPendingTransactions (mempool), and newAcceptedTransactions (Avalanche-specific — fires when transactions are accepted by consensus).

Only available over WebSocket — use wss://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/ext/bc/C/ws. WebSocket is not available on P-Chain or X-Chain.

Parameters

Parameter	Type	Required	Description
subscriptionType	string	Yes	One of "newHeads", "logs", "newPendingTransactions", "newAcceptedTransactions"
filterObject	object	No	For "logs": filter with address and/or topics

Request Example

Axios

import axios from 'axios';

// Note: eth_subscribe requires WebSocket, but here's the message format
const data = JSON.stringify({
    "jsonrpc": "2.0",
    "method": "eth_subscribe",
    "params": ["newHeads"],
    "id": "getblock.io"
});

console.log('WebSocket message:', data);

JavaScript (WebSocket & message format)

// WebSocket connection required
const ws = new WebSocket('wss://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/');

ws.onopen = () => {
    ws.send(JSON.stringify({
        "jsonrpc": "2.0",
        "method": "eth_subscribe",
        "params": ["newHeads"],
        "id": "getblock.io"
    }));
};

ws.onmessage = (event) => {
    console.log('Received:', JSON.parse(event.data));
};

Python

import websocket
import json

def on_message(ws, message):
    print(f"Received: {message}")

def on_open(ws):
    ws.send(json.dumps({
        "jsonrpc": "2.0",
        "method": "eth_subscribe",
        "params": ["newHeads"],
        "id": "getblock.io"
    }))

ws = websocket.WebSocketApp(
    "wss://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/",
    on_message=on_message,
    on_open=on_open
)
ws.run_forever()

Rust

// Note: eth_subscribe requires WebSocket connection
// Example message format for WebSocket client
let message = r#"{
    "jsonrpc": "2.0",
    "method": "eth_subscribe",
    "params": ["newHeads"],
    "id": "getblock.io"
}"#;

Response Example

{
    "jsonrpc": "2.0",
    "id": "getblock.io",
    "result": "0x9cef478923ff08bf67fde6c64013158d"
}

Response Parameters

Field	Type	Description
result	string	Subscription ID, used to match incoming eth_subscription notifications and to call eth_unsubscribe

Use Cases

• Real-time wallet activity notifications

• Live DEX trade feeds for trading UIs

• Streaming indexers reacting to new blocks instantly

• Mempool surveillance (newPendingTransactions) or consensus-accepted feeds (newAcceptedTransactions)

Error Handling

Status Code	Error Message	Cause
404	Not Found	Missing or invalid <ACCESS-TOKEN>
-32602	Invalid params	Request parameters are missing or malformed
429	Too Many Requests	Rate limit exceeded for your plan
-32600	Invalid Request	eth_subscribe was called over HTTP; use a WebSocket connection instead

SDK Integration

Ethers.js (WebSocket)

import { ethers } from 'ethers';

const provider = new ethers.WebSocketProvider('wss://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/ext/bc/C/ws');

provider.on('block', (blockNumber) => {
    console.log('New block:', blockNumber);
});

Viem (WebSocket)

import { createPublicClient, webSocket } from 'viem';
import { avalanche } from 'viem/chains';

const client = createPublicClient({
    chain: avalanche,
    transport: webSocket('wss://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/ext/bc/C/ws')
});

const unwatch = client.watchBlockNumber({
    onBlockNumber: (blockNumber) => console.log('New block:', blockNumber)
});