API reference

Cosmos SDK modules define their queries and transaction messages in protobuf. A node exposes them through gRPC and REST, while the CLI provides commands for using them. CometBFT exposes a separate API for consensus and node data. This section documents these interfaces. For how applications register them, see CLI, gRPC, and REST API.

Interfaces

Interface	Default address	Default	Purpose
gRPC	`localhost:9090`	Enabled	Query application state and access supporting services
REST	`localhost:1317`	Disabled	Call gRPC methods through HTTP and JSON
CometBFT RPC	`127.0.0.1:26657`	Enabled	Query blocks, validators, and the mempool; broadcast transactions; subscribe to events
CLI	n/a	n/a	Query state and build, sign, and broadcast transactions

How they relate

Modules usually define two protobuf services:

A Query service for reading application state
A Msg service describing the state changes transactions can request

Queries

Query methods are callable through gRPC on port 9090. Methods with a google.api.http binding are also available through REST on port 1317. For example, these calls reach the same query handler:

cosmos.bank.v1beta1.Query/AllBalances
GET /cosmos/bank/v1beta1/balances/{address}

Without an HTTP binding, a method is available only through gRPC.

Transaction messages

Msg methods are not callable endpoints. They define messages that are encoded into transactions, signed, and broadcast through a transaction service:

cosmos.tx.v1beta1.Service/BroadcastTx     gRPC
POST /cosmos/tx/v1beta1/txs               REST
broadcast_tx_sync                         CometBFT RPC

CLI

The CLI is a client. Query commands call the application’s query services. Transaction commands construct and sign module messages, then broadcast the resulting transaction. See Using the CLI for worked examples, and CLI for how it fits with the other interfaces. Most commands are not written by hand: autocli generates one per gRPC service method, which is why a command and a grpcurl call usually take the same arguments. Examples in this reference use simd, but each chain normally provides its own application-specific binary.

CometBFT RPC

CometBFT RPC is separate from the application APIs. It belongs to the consensus engine beneath the Cosmos SDK and exposes blocks, validators, consensus data, the mempool, transaction broadcasting, and event subscriptions. See the CometBFT RPC reference.

What this section covers

Page	Contents
gRPC services	Service names, field encodings, reflection, and pagination
REST	Generated OpenAPI documentation with a playground for each route
Sending transactions	How to build, sign, and broadcast transactions

Each module page includes both kinds of declaration. For example, the bank page documents Query/AllBalances and MsgSend. To list the gRPC services registered by a running node:

grpcurl -plaintext localhost:9090 list

Enable the interfaces

gRPC is enabled by default. Enable REST in app.toml:

[api]
enable = true
address = "tcp://localhost:1317"

# Serve the generated OpenAPI document at /swagger.
swagger = true

[grpc]
enable = true
address = "localhost:9090"

Configure CometBFT RPC in config.toml:

[rpc]
laddr = "tcp://127.0.0.1:26657"

Overview

gRPC Services

REST (gRPC Gateway)

Interfaces

How they relate

Queries

Transaction messages

CLI

CometBFT RPC

What this section covers

Enable the interfaces

​Interfaces

​How they relate

​Queries

​Transaction messages

​CLI

​CometBFT RPC

​What this section covers

​Enable the interfaces

Interfaces

How they relate

Queries

Transaction messages

CLI

CometBFT RPC

What this section covers

Enable the interfaces