Skip to main content

OpenAPI Specification

GoDocs

We also have a Godoc available here.

The OpenAPI spec for the Shannon protocol is autogenerated by the Ignite CLI.

The raw file can be found at pocket/blob/main/docs/static/openapi.yml.

Swagger UI​

The Swagger UI for the Shannon Beta TestNet OpenAPI Spec may be viewed at shannon-testnet-grove-api.beta.poktroll.com.

Re-generating the OpenAPI Spec​

You can re-generate the OpenAPI spec by running the following command:

make ignite_openapi_gen_docker

Cosmos REST API vs CometBFT RPC​

External Resources​

warning

We are not going to dive into a discussion of REST vs RPC HTTP APIs here, but will provide minimal context.

You can read about the general differences between REST and RPC APIs here.

The CometBFT RPC Specification can be found here.

The Cosmos SDK REST API Specification can be found here.

Cosmos - Example command to check accounts​

curl -X 'GET' 'https://shannon-testnet-grove-api.beta.poktroll.com/cosmos/auth/v1beta1/accounts' -H 'accept: application/json' | jq

Cosmos - Example command to check node status​

curl -X 'GET' 'https://shannon-testnet-grove-api.beta.poktroll.com/cosmos/base/node/v1beta1/status' -H 'accept: application/json' | jq

CometBFT - Example command to check node status​

curl -X 'GET' 'https://shannon-testnet-grove-rpc.beta.poktroll.com/status' -H 'accept: application/json' | jq

Cosmos SDK & CometBFT API Comparison​

  • CometBFT RPC (26657) → Independent of Cosmos SDK APIs. Used for blockchain consensus, P2P networking, and transaction broadcasting.
  • Cosmos SDK gRPC (9090) → The core application API. Provides structured, high-performance blockchain state queries.
  • Cosmos SDK REST API (1317) → A wrapper around Cosmos SDK gRPC for frontend-friendly JSON-based queries.
note

💡 If gRPC (9090) is disabled, the REST API (1317) will not work. 💡 If CometBFT RPC (26657) is down, the blockchain itself may be offline, but Cosmos SDK APIs can still work if the app is running.

What is it?​

LayerWhat is it?
CometBFT RPC (Independent of the Cosmos SDK gRPC and REST API)A low-level RPC interface that interacts with the Tendermint consensus engine. It is completely independent of the Cosmos SDK gRPC and REST API. Used for network, consensus, and blockchain-related queries (not application state). Also used for sending transactions and querying blockchain state at a protocol level.
Cosmos SDK gRPC (The core application-level API)A high-performance binary API for querying Cosmos SDK modules. Provides structured access to chain state using protobuf messages. Used by full nodes, wallets, and services for efficient state access. 🚀 All Cosmos SDK REST API requests ultimately rely on this gRPC API.
Cosmos SDK REST API (gRPC-Gateway) (A wrapper around Cosmos SDK gRPC)A RESTful wrapper around Cosmos SDK gRPC that translates gRPC queries into HTTP REST endpoints. Enables browser-friendly and frontend-compatible access to Cosmos SDK modules. Uses JSON over HTTP instead of binary gRPC messages. 🚀 This API depends entirely on the Cosmos SDK gRPC API and does not work if gRPC is disabled.

Example Ports & Commands​

LayerExample PortExample CommandExample Endpoint
CometBFT RPC26657sh curl -X GET 'http://localhost:26657/status'/status, /net_info, /block, /broadcast_tx_commit
Cosmos SDK gRPC9090sh grpcurl -plaintext localhost:9090 listcosmos.auth.v1beta1.Query/Account, cosmos.bank.v1beta1.Query/Balance
Cosmos SDK REST API (gRPC-Gateway)1317sh curl -X GET 'http://localhost:1317/cosmos/auth/v1beta1/accounts/{address}'/cosmos/auth/v1beta1/accounts/{address}, /cosmos/bank/v1beta1/balances/{address}