eth_subscribe

This API allows you to create subscriptions for specific events (newHeads, logs, newPendingTransactions).

📘 Usage Notes

You must use a wss endpoint when connecting; https is not supported.

Subscriptions may be automatically canceled when the WebSocket connection is dropped. If the connection is lost, you must request a new subscription to reconnect.

CU is consumed based on the amount of subscribed data, so using appropriate filtering options to subscribe only to necessary data is recommended.

1.Request Parameters

All subscription requests include the following common parameters.

Parameter	Type	Required	Description
id	integer or string	required	Unique identifier for each request. Used by the client to match requests with server responses. Typically expressed as a number or string.
jsonrpc	string	required	Indicates the JSON-RPC protocol version. The version used on the network is "2.0", so always use this value.
method	string	required	Specifies the JSON-RPC method name to execute. Use "eth_subscribe" here.
params	array	required	Arguments required for execution, passed as an array. For "eth_subscribe", provide one of the subscription types (newHeads, logs, or newPendingTransactions) along with the required information for each type.

The arguments passed in params vary depending on the subscription type. Below is a description of the arguments for each subscription type.

Subscription Type

`newHeads`

Subscribing to this event sends the header information of each new block in real time whenever a new block is created. The table below shows detailed information about the arguments that must be entered in the params array.

Argument	Type	Required	Description
subscription_type	string	required	Specifies the event type to subscribe to. Use "newHeads" here.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["newHeads"]
}

`logs`

Subscribing to this event sends information in real time whenever specific logs occur. Users can filter events related to specific smart contract addresses using the address and topics fields. For example, you can subscribe to logs for events such as ERC-20 or ERC-721 token transfers. If empty filtering options are provided, all logs are returned, so specifying necessary filtering options is recommended. The table below shows detailed information about the arguments that must be entered in the params array.

Argument	Type	Required	Description
subscription_type	string	required	Specifies the event type to subscribe to. Use "logs" here.
filtering_option	object	required	Specifies the options (address, topics) for filtering logs. If an empty object is provided, all logs that occur are returned. Specifying desired filtering options according to your use case is recommended.
filtering_option.address	string	optional	Filters for a specific address.
filtering_option.topics	array	optional	Topics to filter, entered as an array.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ]
}

`newPendingTransactions`

Subscribing to this event sends the transaction information in real time when a new transaction is submitted to the network. The table below shows detailed information about the arguments that must be entered in the params array.

Argument	Type	Required	Description
subscription_type	string	required	Specifies the event type to subscribe to. Use "newPendingTransactions" here.
flag	boolean	optional	Specifies whether to include transaction data. If true, returns full transaction data; if false, returns only the transaction hash. If not specified, defaults to false and returns only the transaction hash.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["newPendingTransactions", true]
}

2. Response

When a subscription is created using the above parameters, you receive the following response whenever events occur.

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x71bf7fd5f1d909400aefbd04c96474e8",
    "result": {
      "parentHash": "0xef887cc02d9dcc195319201e78a5bf136ed68df16e30c6fe08e21a7d123b3612",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "miner": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
      "stateRoot": "0x401c9af726edb8cc0c96ccfe6fc8cd016fc2e1e4e1ebf90f52a9560d416e78b9",
      "transactionsRoot": "0x11747f43d21022eec362e8ca7b055b4e4417abb6ed12fbd2baae7817b407e614",
      "receiptsRoot": "0xa467e9c0ac6530a0f33c60bd0e799295811da732708cc338a00dcee9ab8794f0",
      "logsBloom": "0x11ad946a2ac00d44ed08ac72e8327009994f3884e471e1410269a2225ca342808053042d80484a9037426401842e07a44220a54a8a0263627091a48073363858040da08c00d80ca909a14189c24c90a481118db114e6188c983407c086e49204140b561783700160690dd010b148aff3a2290ca9a2026443b055609d30081238441a50080c10d1e8c0c56a5e92200300520909355558076c8f22246d6836516023c51862216430102e8075c0aac1133a005bc486f42230443d71406695aa4478a99281e2901e0a003160c2a5147bc8a04830ab0a421808740781538e50d6607a217aa015a10204b98a4c279842201124c1add048182c80c64002ac56d8a2540f",
      "difficulty": "0x0",
      "number": "0x13c5e89",
      "gasLimit": "0x1c9c380",
      "gasUsed": "0x8b58db",
      "timestamp": "0x66e2b143",
      "extraData": "0x6265617665726275696c642e6f7267",
      "mixHash": "0xd03523217638366b0bd1111d29108f0fc3789ab21e6a9e7afe4ab568f3b98a64",
      "nonce": "0x0000000000000000",
      "baseFeePerGas": "0x828e8440",
      "withdrawalsRoot": "0x5584306249ecc33fa9c0b1804b461ec16abcb305d646fcba128bca75e1700f4a",
      "blobGasUsed": "0x0",
      "excessBlobGas": "0xe0000",
      "parentBeaconBlockRoot": "0x9814d97d13152344553575788f0c6853c7d23f8c521201793257bb7c0c14fe59",
      "hash": "0x9f30ee57944013169c179c9c954aaf60a8bf785b166cc49f58dcc5ce28ecae96"
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x3b7f71db357fe4e9edd8f2e6ec6b24a6",
    "result": {
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x0000000000000000000000003ef97e73d4b8e06535e24aab125077d16462318b",
        "0x0000000000000000000000004af688bb824d12cff5c339abf3010ce7806afcd0"
      ],
      "data": "0x00000000000000000000000000000000000000000000000000000002540be400",
      "blockNumber": "0x13c5e92",
      "transactionHash": "0x283b803e4ed34b03674d04ed71b48d6879034ebfa564acccb8b7b48715d25e0d",
      "transactionIndex": "0x1",
      "blockHash": "0x492384316ea319b4f929306492746155d011f08a3b173e6e4eee9e82faeef207",
      "logIndex": "0x0",
      "removed": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x7f708f4295996c21dbf16e6fcdd8c9e3",
    "result": {
      "blockHash": null,
      "blockNumber": null,
      "from": "0x194981ee45d9ead1f67e7b2299153f0cf06ed542",
      "gas": "0x1061f",
      "gasPrice": "0xb2d05e00",
      "hash": "0x410d09342c540808a1a10eabebc6189b6786fad04c3ac88b7098243b0112d6e1",
      "input": "0xa9059cbb00000000000000000000000046e0e692e8cf2aecb75cdece4be2e110a82069b000000000000000000000000000000000000000000000000009f593793582b31c",
      "nonce": "0x8",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "transactionIndex": null,
      "value": "0x0",
      "type": "0x0",
      "chainId": "0x1",
      "v": "0x25",
      "r": "0xa0fbb1a0613b7e07b49b1e6585f75a0d92df71ee8482551a5d9dfbd82011a1eb",
      "s": "0x1271bfa29a4306b02d8d4c09dc467c540d5837110d8f43b3fd52bfed09351b59"
    }
  }
}

3. How to use

This API is WebSocket-based; you can subscribe using a WebSocket communication tool. This example uses wscat as the WebSocket client tool, which makes it easy to connect to the WebSocket server and send/receive data.

3.1. Connect to Websocket channel

Open a terminal window and enter the command below. Specify the protocol and network you want to subscribe to, and enter the API from the project you created in the console.

# Set protocol, network and your api key in the URL to connect (e.g., wss://ethereum-mainnet.nodit.io/FwG...)
wscat -c wss://{protocol}-{network}.nodit.io/{your_api_key}

Once the WebSocket connection is established, subscribe to the desired event from the examples below.

{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["newPendingTransactions", true]
}

3.3. Listen subscription

The first response returns the subscription ID.

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

Thereafter, results matching the subscription type are returned whenever events occur.

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0xb273410795d4411d707f272834cdd60e",
    "result": {
        # ...
    }
  }
}

3.4. Unsubscribe

Press CTRL+C in the terminal to close the connection and cancel the subscription. Alternatively, use eth_unsubscribe to cancel the subscription while keeping the connection open. Send the subscription ID linked to the channel in params as shown in the example below to cancel that subscription.

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

If the subscription was canceled successfully, you will receive the following response.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

1.Request Parameters​

Subscription Type​

newHeads​

logs​

newPendingTransactions​

2. Response​

3. How to use​

3.1. Connect to Websocket channel​

3.2. Subscribe a specific event​

3.3. Listen subscription​

3.4. Unsubscribe​