CometBFT RPC - Cosmos Docs

CometBFT RPC is a remote procedure call protocol that provides access to blockchain data, transaction broadcasting, validator information, and node status. The RPC server supports multiple transport protocols to accommodate different use cases. CometBFT supports the following RPC protocols:

URI over HTTP - REST-like interface for simple queries
JSONRPC over HTTP - Standard JSON-RPC 2.0 protocol
JSONRPC over WebSockets - Persistent connection with subscription support

Configuration

RPC can be configured by tuning parameters under the [rpc] section in the $CMTHOME/config/config.toml file or by using the --rpc.X command-line flags.

Default Settings

The default RPC listen address is tcp://127.0.0.1:26657. To set another address, update the laddr config parameter:

[rpc]

# TCP or UNIX socket address for the RPC server to listen on
laddr = "tcp://127.0.0.1:26657"

# A list of origins a cross-domain request can be executed from
# Default value '[]' disables cors support
# Use '["*"]' to allow any origin
cors_allowed_origins = []

# A list of methods the client is allowed to use with cross-domain requests
cors_allowed_methods = ["HEAD", "GET", "POST"]

# A list of non simple headers the client is allowed to use with cross-domain requests
cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"]

CORS Configuration

CORS (Cross-Origin Resource Sharing) can be enabled by setting the following config parameters:

cors_allowed_origins - List of allowed origin domains
cors_allowed_methods - HTTP methods allowed for CORS requests
cors_allowed_headers - Headers allowed in CORS requests

Protocol Examples

URI over HTTP

A REST-like interface for simple queries:

# Get block at height 5
curl http://localhost:26657/block?height=5

# Get node status
curl http://localhost:26657/status

# Get validators at height 1
curl http://localhost:26657/validators?height=1

JSONRPC over HTTP

JSONRPC requests can be POST’d to the root RPC endpoint:

# Get block at height 5
curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"method": "block", "params": ["5"], "id": 1}' \
  http://localhost:26657

# Broadcast a transaction
curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"method": "broadcast_tx_sync", "params": ["<tx_bytes>"], "id": 1}' \
  http://localhost:26657

Response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "height": "5",
    "hash": "...",
    "time": "..."
  }
}

JSONRPC over WebSockets

JSONRPC requests can also be made via WebSocket for real-time updates. The WebSocket endpoint is at /websocket, e.g. localhost:26657/websocket.

Asynchronous RPC functions like event subscribe and unsubscribe are only available via WebSockets.

Subscribing to Events

Using the websocat tool, you can subscribe to ‘NewBlock’ events:

echo '{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": 0,
  "params": {
    "query": "tm.event='\''NewBlock'\''"
  }
}' | websocat -n -t ws://127.0.0.1:26657/websocket

You’ll receive notifications as new events occur:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "query": "tm.event='NewBlock'",
    "data": {
      "type": "tendermint/event/NewBlock",
      "value": {
        "block": { ... },
        "result_begin_block": { ... },
        "result_end_block": { ... }
      }
    }
  }
}

Available Event Types

You can subscribe to the following event types:

NewBlock - Emitted when a new block is committed
NewBlockHeader - Emitted for new block headers
Tx - Emitted for transactions
ValidatorSetUpdates - Emitted when the validator set changes

Endpoint Categories

The CometBFT RPC API is organized into several categories:

Category	Description	Example Methods
Info	Node information and blockchain data	`status`, `health`, `net_info`, `blockchain`, `block`
Tx	Transaction broadcasting and queries	`broadcast_tx_sync`, `broadcast_tx_async`, `tx`, `tx_search`
ABCI	Application Blockchain Interface queries	`abci_info`, `abci_query`
Evidence	Evidence of misbehavior	`broadcast_evidence`
Unsafe	Administrative operations (requires manual enablement)	`dial_seeds`, `dial_peers`, `unsafe_flush_mempool`

Unsafe Methods: Methods in the “Unsafe” category can affect node operation and must be manually enabled in the configuration. They should only be used by node operators who understand the implications.

Arguments

Arguments which expect strings or byte arrays may be passed as:

Quoted strings: "abc"
0x-prefixed hex strings: 0x616263

Common Use Cases

Querying Blockchain Data

# Get the latest block
curl http://localhost:26657/block

# Get block at specific height
curl http://localhost:26657/block?height=100

# Search for transactions
curl 'http://localhost:26657/tx_search?query="tx.height>100"&prove=false'

Broadcasting Transactions

# Synchronous broadcast (waits for CheckTx)
curl http://localhost:26657/broadcast_tx_sync?tx=0x01234567

# Asynchronous broadcast (returns immediately)
curl http://localhost:26657/broadcast_tx_async?tx=0x01234567

# Commit broadcast (waits for block inclusion)
curl http://localhost:26657/broadcast_tx_commit?tx=0x01234567

Node Status and Health

# Check node health
curl http://localhost:26657/health

# Get comprehensive node status
curl http://localhost:26657/status

# Get network information
curl http://localhost:26657/net_info

Next Steps

RPC Methods Reference

Browse the complete API reference in the sidebar - all ~30 RPC methods with interactive examples and detailed parameters

WebSocket Subscriptions

Learn more about subscribing to real-time events

​Configuration

​Default Settings

​CORS Configuration

​Protocol Examples

​URI over HTTP

​JSONRPC over HTTP

​JSONRPC over WebSockets

​Subscribing to Events

​Available Event Types

​Endpoint Categories

​Arguments

​Common Use Cases

​Querying Blockchain Data

​Broadcasting Transactions

​Node Status and Health

​Next Steps

RPC Methods Reference

WebSocket Subscriptions

Configuration

Default Settings

CORS Configuration

Protocol Examples

URI over HTTP

JSONRPC over HTTP

JSONRPC over WebSockets

Subscribing to Events

Available Event Types

Endpoint Categories

Arguments

Common Use Cases

Querying Blockchain Data

Broadcasting Transactions

Node Status and Health

Next Steps