Querying On-Chain Data

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.

CosmJS

Concepts

Guides

API Reference

Querying On-Chain Data

Prerequisites

Quick Start

High-Level Client Methods

Using QueryClient with Extensions

Combining Multiple Extensions

Next Steps

Bank Queries

Staking Queries

Governance Queries

Account Queries

Distribution & Mint

IBC Queries

Transaction Queries

CosmWasm Queries

Pagination

Blocks & Chain Info

Custom Extensions

Error Handling

​Prerequisites

​Quick Start

​High-Level Client Methods

​Using QueryClient with Extensions

​Combining Multiple Extensions

​Next Steps

Bank Queries

Staking Queries

Governance Queries

Account Queries

Distribution & Mint

IBC Queries

Transaction Queries

CosmWasm Queries

Pagination

Blocks & Chain Info

Custom Extensions

Error Handling

Prerequisites

Quick Start

High-Level Client Methods

Using QueryClient with Extensions

Combining Multiple Extensions

Next Steps