🔔 eth_subscribe - Base Chain

💡

The eth_subscribe method is only available through WebSockets. This cannot be used with standard HTTP connections.

Overview

The eth_subscribe method allows you to create a subscription to specific events on the Base blockchain. Once subscribed, you'll receive real-time notifications whenever these events occur, without needing to poll the API.

Need RPC API keys?

Get 12.5M archival requests for free today.

GET STARTED FOR FREE

Parameters

subscription name [required] - String - The type of event you want to subscribe to:
- newHeads - Notifies you each time a new block is added to the chain, including during chain reorganizations.
- logs - Returns logs from new blocks that match your specified filter criteria.
  - address [optional] - A single address or array of addresses. Only returns logs created from these addresses.
  - topics [optional] - Only returns logs that match the specified topics. Learn more about topics (opens in a new tab).
- newPendingTransactions - Returns the hash for all transactions added to the pending pool. When a transaction moves out of the canonical chain during a reorganization, it will be emitted again.
- newPendingTransactionsWithBody - Similar to newPendingTransactions, but includes the full transaction details, not just the hash.

💡

The syncing subscription parameter (available on some Ethereum nodes) is not supported at Chainnodes.org as our Base nodes are always fully synced for you.

Returns

After subscribing, you'll receive:

Initial response - Contains a Subscription ID that identifies your subscription
Ongoing notifications - Events matching your subscription criteria, each containing:
- The subscription ID
- The event data

Request

POST https://base-mainnet.chainnodes.org/YOUR-API-KEY

Example

WSS Request with a JSON RPC call in the body
Replace YOUR-API-KEY with the API key from your Chainnodes.org Dashboard
You can use a different supported network by replacing base-mainnet

wscat \
    -c wss://base-mainnet.chainnodes.org/YOUR-API-KEY
 
# newHeads - Subscribe to new blocks
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"], "id": 1 }
 
# newPendingTransactions - Subscribe to transaction hashes only
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newPendingTransactions"], "id": 1 }
 
# newPendingTransactionsWithBody - Subscribe to full transaction details
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newPendingTransactionsWithBody"], "id": 1 }
 
# logs - Subscribe to all logs (no filter)
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["logs", {}], "id": 1 }
 
# logs - Subscribe to USDC transfer events on Base
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["logs", {"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}], "id": 1 }

💡 Confusing?

Ask our experienced blockchain developers in Telegram

ASK FOR FREE

Responses

Subscription Confirmation

{
    "result": "0x44567e1f7aa50f78e15c1a93dd9cbfd3",
    "jsonrpc": "2.0",
    "id": 1
}

newHeads Notification

{
    "method": "eth_subscription",
    "jsonrpc": "2.0",
    "params": {
        "result": {
            "baseFeePerGas": "0x5f5e100",
            "gasLimit": "0x1c9c380",
            "gasUsed": "0x42a21",
            "difficulty": "0x0",
            "number": "0x57e450",
            "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            "nonce": "0x0000000000000000",
            "miner": "0x4200000000000000000000000000000000000011",
            "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
            "stateRoot": "0x3b25a38e97bba2cbc73f58909d81158ca84464a5505bc33d73fe57d91018774a",
            "transactionsRoot": "0x7b7978d47cde0af4714e173a1778b1a96a01d67cb34d19b6b76d09e798622014",
            "hash": "0x54751c3cb4f7c95b249ab5ed702a708a6782cc937b1d399f25be4b40d9e0f5d4",
            "parentHash": "0x6cdba7e0df16387c91e2c1cadad149943b26150eba35ad93696d29ae3bb6341b",
            "extraData": "0x",
            "timestamp": "0x662a877f"
        },
        "subscription": "0x44567e1f7aa50f78e15c1a93dd9cbfd3"
    }
}

newPendingTransactions Notification

{
    "params": {
        "result": "0xf02e0576a830ab37f2eb1c43ed3fbcaa53d84bf5ca985ae60c71f5cac27f4cc3",
        "subscription": "0x9ac5c0ccb2faa00f094046cd9283a637"
    },
    "method": "eth_subscription",
    "jsonrpc": "2.0"
}

newPendingTransactionsWithBody Notification

{
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "subscription": "0x0f659211bd6b7d0c962bee40a6b5d8c1",
        "result": {
            "gasPrice": "0xe12c5d1dc",
            "maxPriorityFeePerGas": "0x5f5e100",
            "value": "0x0",
            "s": "0x217ad72b41a611526a45aae9392affba8114c0bd4c25e8ef7f05cda45ef5cee0",
            "nonce": "0x1",
            "hash": "0xf02e0576a830ab37f2eb1c43ed3fbcaa53d84bf5ca985ae60c71f5cac27f4cc3",
            "type": "0x2",
            "input": "0x3593564c000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000642f1f1f0000000000000000000000000000000000000000000000000000000000000002",
            "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "v": "0x0",
            "gas": "0x3362",
            "maxFeePerGas": "0xe12c5d1dc",
            "r": "0x3b4afab91edec37c0cfe9e68f2d65c4c7e9ab23d3453eaa456bdb41e5d22548f",
            "chainId": "0x2105"
        }
    }
}

logs Notification

{
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "result": {
            "transactionIndex": "0x0",
            "data": "0x000000000000000000000000000000000000000000000000000000000098968000",
            "blockHash": "0x54751c3cb4f7c95b249ab5ed702a708a6782cc937b1d399f25be4b40d9e0f5d4",
            "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "topics": [
                "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                "0x000000000000000000000000ad89a377e302791fb523ffb427f3f480cad3a72c",
                "0x0000000000000000000000006b175474e89094c44da98b954eedeac495271d0f"
            ],
            "transactionHash": "0xf02e0576a830ab37f2eb1c43ed3fbcaa53d84bf5ca985ae60c71f5cac27f4cc3",
            "logIndex": "0x0",
            "blockNumber": "0x57e450",
            "removed": false
        },
        "subscription": "0xd4a23c4ae337b37920e97eca96ba581f"
    }
}

Common Use Cases

Monitoring Token Transfers

To monitor USDC token transfers on Base:

// Subscribe to USDC Transfer events (ERC-20 standard event)
{
    "jsonrpc": "2.0", 
    "method": "eth_subscribe", 
    "params": [
        "logs", 
        {
            "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
            "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] // Transfer event signature
        }
    ], 
    "id": 1
}

Real-time Block Monitoring

For applications that need to know about each new block immediately:

// Subscribe to all new blocks
{
    "jsonrpc": "2.0", 
    "method": "eth_subscribe", 
    "params": ["newHeads"], 
    "id": 1
}

Transaction Pool Monitoring

To track mempool activity:

// Subscribe to all new pending transactions (full transaction details)
{
    "jsonrpc": "2.0", 
    "method": "eth_subscribe", 
    "params": ["newPendingTransactionsWithBody"], 
    "id": 1
}

Unsubscribing

To stop receiving notifications, call the eth_unsubscribe method with your subscription ID:

{
    "jsonrpc": "2.0",
    "method": "eth_unsubscribe",
    "params": ["0x44567e1f7aa50f78e15c1a93dd9cbfd3"],
    "id": 1
}

Related Methods

eth_unsubscribe - Cancel an active subscription
eth_getLogs - For one-time historical log queries instead of subscriptions
eth_getFilterChanges - Alternative polling method for HTTP connections

JSON-RPC Base API Documentation by CHAINNODES is based on Reth node client. Contact us if you are interested in specific methods that are only available on geth, besu, Nethermind or Erigon

eth_maxPriorityFeePerGas eth_unsubscribe