CometBFT RPC

The CometBFT RPC allows you to query transactions, blocks, consensus state, broadcast transactions, etc. Complete documentation including a swagger interface can be found here.

URI/HTTP

A GET request with arguments encoded as query parameters:

curl http://localhost:26657/block\?height\=5

RPC/HTTP

JSONRPC requests can be POST'd to the root RPC endpoint via HTTP. See the list of supported CometBFT RPC endpoints in API/clients section.

RPC/Websocket

Cosmos and CometBFT Events

Events are objects that contain information about the execution of the application and are triggered after a block is committed. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. You can get the full list of event categories and values here.

Subscribing to Events via Websocket

CometBFT provides a WebSocket connection that allows you to subscribe to and unsubscribe from various blockchain events in real-time. This is a powerful tool for monitoring chain activity and building event-driven applications.

Prerequisites

CometBFT Node: You need a running CometBFT node with its RPC WebSocket enabled.
ws tool: A command-line WebSocket client. If you don't have it, you can install it via npm:
```
npm i -g ws
```

Subscribing to Events

Connect to the CometBFT WebSocket: Use the ws command to establish a connection to your node's WebSocket endpoint.
```
ws ws://localhost:26657/websocket
```
Once connected, you'll see your prompt ready to accept input (e.g., >).
Send a Subscription Request: To subscribe to a specific event, send a JSON-RPC request with the "method": "subscribe" and a "query" parameter. The query uses a specific syntax to filter events.
For example, to subscribe to NewBlockHeader events (which fire when a new block header is committed):
```
{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": ["tm.event='NewBlockHeader'"],
  "id": 1
}
```
Paste this JSON into your ws terminal and press Enter. You should receive a confirmation like:
```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```
Your terminal will now display incoming NewBlockHeader events as they occur.

Filtering Events with query The query parameter in your subscription request allows for granular filtering of events. You can combine an Event Type with specific Event Attributes to narrow down the events you receive.

The generic syntax for the query is:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": "0",
  "params": {
    "query": "tm.event='<event_value>' AND eventType.eventAttribute='<attribute_value>'"
  }
}

Example: Subscribing to specific Ethereum transactions on Guru

If you're on Guru, MsgEthereumTx transactions trigger an ethermint event. You can filter these events by sender or recipient attributes. To subscribe to transactions where the ethereum.recipient is a specific hex address (e.g., 0x1122334455667788990011223344556677889900):

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "id": "0",
    "params": {
        "query": "tm.event='Tx' AND ethereum.recipient='0x1122334455667788990011223344556677889900'"
    }
}

Common CometBFT Events and Attributes

Main Event Types

Usage: '<Event Key>'='<Event Value>':

List of event keys:

Event Key	Description	Categories
`"tm.event"`	Subscribe to a specific event.	`block`
`"tx.hash"`	Subscribe to a specific transaction by its hash.	`block`
`"tx.height"`	Subscribe to transactions at a specific block height.	`block`
`"block.height"`	Index `BeginBlock` and `EndBlock` events.	`block`
`"begin_block"`	Subscribe to ABCI `BeginBlock` events.	`block`
`"end_block"`	Subscribe to ABCI `EndBlock` events.	`consensus`

List of event values:

Event Value	Description	Categories
`"NewBlock"`	Contains events triggered during `BeginBlock` and `EndBlock`.	`block`
`"NewBlockHeader"`	Provides only the header of a new block.	`block`
`"Tx"`	Contains events triggered during `DeliverTx` (i.e., transaction processing).	`block`
`"ValidatorSetUpdates"`	Contains validator set updates for the block.	`block`
`"NewEvidence"`	Indicates new Byzantine evidence.	`block`
`"BlockSyncStatus"`	Provides information about block synchronization status.	`consensus`
`"Lock"`	Consensus: lock event.	`consensus`
`"NewRound"`	Consensus: new round started.	`consensus`
`"Polka"`	Consensus: Polka event.	`consensus`
`"Relock"`	Consensus: relock event.	`consensus`
`"StateSyncStatus"`	Provides information about state synchronization status.	`consensus`
`"TimeoutPropose"`	Consensus: timeout for propose.	`consensus`
`"TimeoutWait"`	Consensus: timeout for waiting.	`consensus`
`"Unlock"`	Consensus: unlock event.	`consensus`
`"ValidBlock"`	Consensus: block is valid.	`consensus`
`"Vote"`	Consensus: vote event.	`consensus`

Example: Subscribing to Validator Set Updates

Let's illustrate with an example to subscribe to ValidatorSetUpdates. This event is triggered when there are changes to the validator set for a block.

Connect to the WebSocket:
```
ws ws://localhost:26657/websocket
```

Send the Subscription Request:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": ["tm.event='ValidatorSetUpdates'"],
  "id": 1
}

Example Response (truncated for brevity): When a validator set update occurs, you'll receive a JSON response similar to this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "query": "tm.event='ValidatorSetUpdates'",
    "data": {
      "type": "tendermint/event/ValidatorSetUpdates",
      "value": {
        "validator_updates": [
          {
            "address": "09EAD022FD25DE3A02E64B0FE9610B1417183EE4",
            "pub_key": {
              "type": "tendermint/PubKeyEd25519",
              "value": "ww0z4WaZ0Xg+YI10w43wTWbBmM3dpVza4mmSQYsd0ck="
            },
            "voting_power": "10",
            "proposer_priority": "0"
          }
        ]
      }
    }
  }
}

This response indicates that the validator set has been updated, providing details about the changes (e.g., an updated validator address, pub_key, and voting_power).

tip

Important Note on Transaction Hashes: When querying Ethereum transactions on Guru, remember that their transaction hashes will differ from standard Cosmos transactions. For Ethereum transactions, you'll typically need to use event queries with specific attributes (like ethereum.recipient as shown above) rather than tx.hash.

CometBFT RPC

URI/HTTP​

RPC/HTTP​

RPC/Websocket​

Cosmos and CometBFT Events​

Subscribing to Events via Websocket​

Common CometBFT Events and Attributes​