CometBFT RPC - Cosmos Docs

CometBFT RPC 是一种远程过程调用协议，提供对区块链数据、交易广播、验证者信息和节点状态的访问。RPC 服务器支持多种传输协议，以适应不同的使用场景。 CometBFT 支持以下 RPC 协议：

URI over HTTP - 用于简单查询的类 REST 接口
JSONRPC over HTTP - 标准的 JSON-RPC 2.0 协议
JSONRPC over WebSockets - 支持订阅的持久连接

配置

可以通过调整 $CMTHOME/config/config.toml 文件中 [rpc] 部分下的参数，或者使用 --rpc.X 命令行标志来配置 RPC。

默认设置

默认的 RPC 监听地址是 tcp://127.0.0.1:26657。如果要设置其他地址，请更新 laddr 配置参数：

[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 配置

可以通过设置以下配置参数来启用 CORS（跨源资源共享）：

cors_allowed_origins - 允许的源域名列表
cors_allowed_methods - CORS 请求允许使用的 HTTP 方法
cors_allowed_headers - CORS 请求允许携带的请求头

协议示例

通过 HTTP 的 URI

用于简单查询的类 REST 接口：

# 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

通过 HTTP 的 JSONRPC

JSONRPC 请求可以通过 POST 方式发送到根 RPC 端点：

# 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

响应格式：

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

通过 WebSockets 的 JSONRPC

也可以通过 WebSocket 发起 JSONRPC 请求，以获取实时更新。WebSocket 端点位于 /websocket，例如 localhost:26657/websocket。

像事件 subscribe 和 unsubscribe 这样的异步 RPC 函数仅可通过 WebSockets 使用。

订阅事件

使用 websocat 工具，你可以订阅 NewBlock 事件：

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

当有新事件发生时，你将收到通知：

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

可用事件类型

你可以订阅以下事件类型：

NewBlock - 当新区块提交时触发
NewBlockHeader - 当产生新区块头时触发
Tx - 当有交易时触发
ValidatorSetUpdates - 当验证者集合发生变化时触发

端点分类

CometBFT RPC API 被组织为以下几个类别：

分类	说明	示例方法
Info	节点信息和区块链数据	`status`, `health`, `net_info`, `blockchain`, `block`
Tx	交易广播和查询	`broadcast_tx_sync`, `broadcast_tx_async`, `tx`, `tx_search`
ABCI	应用区块链接口查询	`abci_info`, `abci_query`
Evidence	作恶证据	`broadcast_evidence`
Unsafe	管理操作（需要手动启用）	`dial_seeds`, `dial_peers`, `unsafe_flush_mempool`

Unsafe Methods：Unsafe 类别中的方法会影响节点运行，必须在配置中手动启用。只有理解其影响的节点运维人员才应使用它们。

参数

期望字符串或字节数组的参数可以按以下方式传递：

带引号的字符串："abc"
以 0x 为前缀的十六进制字符串：0x616263

常见用例

查询区块链数据

# 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'

广播交易

# 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

节点状态与健康检查

# 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

后续步骤

RPC Methods Reference

在侧边栏中浏览完整的 API 参考文档，包含约 30 个 RPC 方法，以及可交互示例和详细参数说明

WebSocket Subscriptions

进一步了解如何订阅实时事件

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

​配置

​默认设置

​CORS 配置

​协议示例

​通过 HTTP 的 URI

​通过 HTTP 的 JSONRPC

​通过 WebSockets 的 JSONRPC

​订阅事件

​可用事件类型

​端点分类

​参数

​常见用例

​查询区块链数据

​广播交易

​节点状态与健康检查

​后续步骤

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

RPC Methods Reference

WebSocket Subscriptions

配置

默认设置

CORS 配置

协议示例

通过 HTTP 的 URI

通过 HTTP 的 JSONRPC

通过 WebSockets 的 JSONRPC

订阅事件

可用事件类型

端点分类

参数

常见用例

查询区块链数据

广播交易

节点状态与健康检查

后续步骤

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