---
title: eth_subscribe
slug: ethsubscribe
docTags: 
createdAt: 2023-03-30T16:33:01.000Z
---

Caduceus follows the EVM specification, so API should be the same as the API for Ethereum or other compliant evm blockchains. A good place to see the full documentation is on the [Alchemy eth-subscribe documentation. ](https://docs.alchemy.com/reference/eth-subscribe)But continue reading to understand the most important parts.

# eth\_subscribe Parameters:

`eth_subscribe` takes an array value `params` which accepts two items in the array. The first is the **subscription name** and the second is an optional **data** payload. 

- **subscription name** - string - The type of event you want to subscribe to (i.e., newHeads, logs, pendingTransactions, newPendingTransactions). This method supports the following subscription types:
  - `newHeads` - It fires a notification each time a new header is appended to the chain, including chain reorganizations
  - `logs` - It returns logs that are included in new imported blocks and match the given filter criteria
  - `pendingTransactions` - It returns full transactions that are sent to the network, marked as pending, and are sent from or to a certain address
  - `newPendingTransactions` - It returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node
- **data** - object - (optional) The arguments such as an address, multiple addresses, and topics. Note, only logs that are created from these addresses or match the specified topics will return logs

Returns:

- **result** - The hex encoded subscription ID. This ID will be attached to all received events and can also be used to cancel the subscription using `eth_unsubscribe`



## newHeads

The newHeads subscription type emits an event any time a new header (block) is added to the chain, including during a chain reorganization.

### Request

```shell
> wscat -c "wss://mainnet.ws.caduceus.foundation"
# This will open up a connection and it will show the following message if
# successfully connected
Connected (press CTRL+C to quit)
> { "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }
```

### Response

```json
{
   "jsonrpc": "2.0",
   "method": "eth_subscription",
   "params": {
     "result": {
       "difficulty": "0x15d9223a23aa",
       "extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
       "gasLimit": "0x47e7c4",
       "gasUsed": "0x38658",
       "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
       "miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
       "nonce": "0x084149998194cc5f",
       "number": "0x1348c9",
       "parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
       "receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
       "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
       "stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
       "timestamp": "0x56ffeff8",
       "transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
     },
   "subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
   }
 }
```

## logs

setting the subscription name to `logs` is a great way to listen to events on a particular smart contract.  It however needs the following data field to be set. It is an object with the following fields:

- address
- topics: an array of topic specifiers.
  - Each topic specifier is either
  - For every non null topic, a log will be emitted when activity associated with that topic occurs.

### Topic Specifications

- \[]
  - : Any topics allowed.
- \[A]
  - : A in first position (and anything after).
- \[null, B]
  - : Anything in first position and B in second position (and anything after).
- \[A, B]
  - : A in first position and B in second position (and anything after).
- \[\[A, B], \[A, B]]
  - : (A or B) in first position and (A or B) in second position (and anything after).

To understand more about topics we suggest you read the api documentation of [Alchemy](https://docs.alchemy.com/reference/logs) which explain it very well.

### Request

```shell
> wscat -c "wss://mainnet.ws.caduceus.foundation"
# This will open up a connection and it will show the following message if
# successfully connected
Connected (press CTRL+C to quit)
> {"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}
```

### Response

```json
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x4a8a4c0517381924f9838102c5a4dcb7",
    "result": {
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "blockHash": "0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
      "blockNumber": "0x29e87",
      "data": "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
      "logIndex": "0x0",
      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
      "transactionHash": "0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
      "transactionIndex": "0x0"
    }
  }
}
```

Below you can find the explanation for individual properties of the response:

- **jsonrpc**: The jsonrpc property specifies the version of the JSON-RPC protocol that is being used, which in this case is "2.0".
- **method**: The method property specifies the method that was called, which in this case is eth\_subscription.
- **params**: The params property contains the parameters of the method call. In this case, it contains a subscription property, which specifies the subscription identifier, and a result property, which contains the result of the subscription.
  - **result**: The result property contains information about a specific transaction on the Ethereum blockchain.
  - **address**: The address property specifies the address from which this log originated.
  - **blockhash**: The blockHash property specifies the hash of the block in which the transaction was included.
  - **blockNumber**: The blockNumber property specifies the number of the block in which the transaction was included. It is encoded as a hexadecimal string.
  - **data**: Contains one or more 32 Bytes non-indexed arguments of the log.
  - **logIndex**: The logIndex property specifies the index or position of the log entry within the block. It is encoded as a hexadecimal string.
  - **topics**: The topics property is an array of 0 to 4 32 bytes topic hashes of indexed log arguments.
  - **transactionHash**: The transactionHash property specifies the hash of the transaction.
  - **transactionIndex**: The transactionIndex property specifies the index or position of the transaction within the block. It is encoded as a hexadecimal string.