Skip to main content

Tendermint RPC

You can query transactions, blocks, consensus status, broadcast transactions, and other things using the Tendermint RPC.

You may find the most recent Tendermint RPC documentations here. The following RPC protocols are compatible with Tendermint:

  • HTTP over URI
  • HTTP over JSON-RPC
  • Websockets and JSON-RPC
  • An interactive Swagger interface will be included throughout the documents.

URI/HTTP

A GET request with query parameters that are arguments encoded:

curl localhost:26657/block?height=5

RPC/HTTP

You can use HTTP POST to send JSONRPC requests to the root RPC endpoint. Here is a list of the Swagger-supported Tendermint RPC endpoints.

RPC/Websocket

Cosmos and Tendermint 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.

More on Events:

Subscribing to Events via Websocket

To subscribe to or unsubscribe from Tendermint Events, Tendermint Core offers a Websocket connection. When launching the node, you must specify the address with the --rpc.laddr flag (the default is tcp://127.0.0.1:26657) in order to establish a connection with the Tendermint websocket:

danger

aici mai sus ar merge niste links de Cometbft dar nush exact care sa le pun

humansd start --rpc.laddr="tcp://127.0.0.1:26657"

Then, start a websocket subscription with ws

# connect to tendermint websocket at port 8080
ws ws://localhost:8080/websocket

# subscribe to new Tendermint block headers
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlockHeader'"], "id": 1 }

You can filter the precise event you're looking for using the type and attribute values of the query. For instance, the MsgEthereumTx Ethereum transaction on Humans.ai causes a event of type ethermint and has the sender and recipient as attributes. To subscribe to this event, follow these steps:

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

where hexAddress is an Ethereum hex address (eg: 0x1122334455667788990011223344556677889900).

The general syntax is as follows:

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

List of Tendermint Events

The main events you can subscribe to are:

  • NewBlock: Contains events triggered during BeginBlock and EndBlock.
  • Tx: Contains events triggered during DeliverTx (i.e. transaction processing).
  • ValidatorSetUpdates: Contains validator set updates for the block.
tip

The Modules Specification contains a list of the event kinds and values for each Cosmos SDK module. For a list of events for each supported module on Humans.ai, see the Events page.

All Tendermint event keys are listed here:

Event TypeCategories
Subscribe to a specific event"tm.event"block
Subscribe to a specific transaction"tx.hash"block
Subscribe to transactions at a specific block height"tx.height"block
Index BeginBlock and Endblock events"block.height"block
Subscribe to ABCI BeginBlock events"begin_block"block
Subscribe to ABCI EndBlock events"end_block"consensus

The settings shown below can be used to subscribe for the tm.event type:

Event ValueCategories
New block"NewBlock"block
New block header"NewBlockHeader"block
New Byzantine Evidence"NewEvidence"block
New transaction"Tx"block
Validator set updated"ValidatorSetUpdates"block
Block sync status"BlockSyncStatus"consensus
lock"Lock"consensus
New consensus round"NewRound"consensus
Polka"Polka"consensus
Relock"Relock"consensus
State sync status"StateSyncStatus"consensus
Timeout propose"TimeoutPropose"consensus
Timeout wait"TimeoutWait"consensus
Unlock"Unlock"consensus
Block is valid"ValidBlock"consensus
Consensus vote"Vote"consensus

Example

ws ws://localhost:26657/websocket
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='ValidatorSetUpdates'"], "id": 1 }

Example response:

{
"jsonrpc": "2.0",
"id": 0,
"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"
}
]
}
}
}
}
note

The transaction hashes differ when comparing queries for transactions on Ethereum and Cosmos. The event query method must be used by users to query Ethereum transactions. Here's an illustration using the CLI:

curl -X GET "http://localhost:26657/tx_search?query=ethereum_tx.ethereumTxHash%3D0x8d43464891fac6c113e809e14dff1a3e608eae124d629799e42ca0e36562d9d7&prove=false&page=1&per_page=30&order_by=asc" -H "accept: application/json"