Querying On-Chain Data

Read blockchain state using high-level client methods and composable QueryClient extensions

CosmJS provides two ways to query on-chain data: convenience methods on the high-level clients (StargateClient, CosmWasmClient) and a low-level QueryClient with composable module extensions. Choose the approach that fits your needs — high-level methods for common tasks, extensions for full module coverage.

Prerequisites

• @cosmjs/stargate installed (npm install @cosmjs/stargate)
• A connected client (see Connect to a Chain)

Quick Start

import { StargateClient } from "@cosmjs/stargate";

const client = await StargateClient.connect("https://rpc.my-chain.network");

const balance = await client.getBalance("cosmos1...", "uatom");
console.info(balance); // { denom: "uatom", amount: "1000000" }

const account = await client.getAccount("cosmos1...");
console.info(account); // { address, pubkey, accountNumber, sequence }

client.disconnect();

High-Level Client Methods

StargateClient bundles the most common queries behind simple methods. These cover bank, staking, auth, and transaction queries out of the box.

Method	Returns	Description
getChainId()	string	Chain identifier
getHeight()	number	Latest block height
getBlock(height?)	Block	Block data at the given or latest height
getAccount(address)	Account | null	Account info (address, pubkey, sequence)
getSequence(address)	SequenceResponse	Account number and sequence
getBalance(address, denom)	Coin	Single-denom balance
getAllBalances(address)	Coin[]	All balances for an address
getBalanceStaked(address)	Coin | null	Total staked balance across all validators
getDelegation(delegator, validator)	Coin | null	Delegation to a specific validator
getTx(id)	IndexedTx | null	Transaction by hash
searchTx(query)	IndexedTx[]	Search transactions by events

CosmWasmClient extends these with contract-specific queries:

Method	Returns	Description
getCodes()	Code[]	All uploaded WASM codes
getCodeDetails(codeId)	CodeDetails	Code metadata and bytecode
getContracts(codeId)	string[]	Contract addresses for a code ID
getContractsByCreator(creator)	string[]	Contracts created by an address
getContract(address)	Contract	Contract metadata
getContractCodeHistory(address)	ContractCodeHistoryEntry[]	Migration history
queryContractRaw(address, key)	Uint8Array | null	Raw contract state by key
queryContractSmart(address, query)	JsonObject	JSON smart query

Using QueryClient with Extensions

For queries beyond what the high-level clients expose, build a QueryClient with the exact extensions you need. This gives you typed access to every query endpoint in each Cosmos SDK module.

import {
  QueryClient,
  setupBankExtension,
  setupStakingExtension,
  setupGovExtension,
  setupDistributionExtension,
  setupMintExtension,
} from "@cosmjs/stargate";
import { connectComet } from "@cosmjs/tendermint-rpc";

const cometClient = await connectComet("https://rpc.my-chain.network");
const queryClient = QueryClient.withExtensions(
  cometClient,
  setupBankExtension,
  setupStakingExtension,
  setupGovExtension,
  setupDistributionExtension,
  setupMintExtension,
);

Extensions are merged into the QueryClient instance. Each one adds a namespace — queryClient.bank, queryClient.staking, queryClient.gov, etc. You can compose up to 18 extensions in a single call.

Combining Multiple Extensions

You can compose any combination of extensions to build a query client tailored to your needs:

import {
  QueryClient,
  setupBankExtension,
  setupStakingExtension,
  setupGovExtension,
  setupDistributionExtension,
  setupMintExtension,
  setupSlashingExtension,
  setupAuthzExtension,
  setupFeegrantExtension,
  setupIbcExtension,
} from "@cosmjs/stargate";

const queryClient = QueryClient.withExtensions(
  cometClient,
  setupBankExtension,
  setupStakingExtension,
  setupGovExtension,
  setupDistributionExtension,
  setupMintExtension,
  setupSlashingExtension,
  setupAuthzExtension,
  setupFeegrantExtension,
  setupIbcExtension,
);

const balance = await queryClient.bank.balance("cosmos1...", "uatom");
const validators = await queryClient.staking.validators("BOND_STATUS_BONDED");
const inflation = await queryClient.mint.inflation();

Each extension is independently typed — TypeScript knows exactly which namespaces and methods are available based on the setup functions you pass.

Next Steps

Bank Queries

Token balances, supply, and denomination metadata.

Staking Queries

Validators, delegations, unbonding, and staking pool.

Governance Queries

Proposals, votes, deposits, and tallies.

Account Queries

Account info, auth extension, and custom parsers.

Distribution & Mint

Staking rewards, commission, inflation, and community pool.

IBC Queries

Channels, connections, clients, and transfer denominations.

Transaction Queries

Search, decode, and inspect transactions and events.

CosmWasm Queries

Smart contract state and metadata queries.

Pagination

Navigate large result sets page by page.

Blocks & Chain Info

Block data, chain status, and CometBFT RPC.

Custom Extensions

Write query extensions for custom chain modules.

Error Handling

Handle missing data, NotFound errors, and broadcast failures.