@cosmjs/stargate

The primary client library for interacting with Cosmos SDK chains. Provides read-only querying via StargateClient and transaction signing/broadcasting via SigningStargateClient.

npm install @cosmjs/stargate

StargateClient

Read-only client for querying blockchain state.

Static Methods

Method	Parameters	Returns
`connect`	`endpoint: string \| HttpEndpoint`, `options?: StargateClientOptions`	`Promise<StargateClient>`
`create`	`cometClient: CometClient`, `options?: StargateClientOptions`	`StargateClient`

Instance Methods

Method	Parameters	Returns
`getChainId`	—	`Promise<string>`
`getHeight`	—	`Promise<number>`
`getAccount`	`searchAddress: string`	`Promise<Account \| null>`
`getSequence`	`address: string`	`Promise<SequenceResponse>`
`getBlock`	`height?: number`	`Promise<Block>`
`getBalance`	`address: string`, `searchDenom: string`	`Promise<Coin>`
`getAllBalances`	`address: string`	`Promise<readonly Coin[]>`
`getBalanceStaked`	`address: string`	`Promise<Coin \| null>`
`getDelegation`	`delegatorAddress: string`, `validatorAddress: string`	`Promise<Coin \| null>`
`getTx`	`id: string`	`Promise<IndexedTx \| null>`
`searchTx`	`query: SearchTxQuery`	`Promise<IndexedTx[]>`
`broadcastTx`	`tx: Uint8Array`, `timeoutMs?: number`, `pollIntervalMs?: number`	`Promise<DeliverTxResponse>`
`broadcastTxSync`	`tx: Uint8Array`	`Promise<string>`
`disconnect`	—	`void`

Usage

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

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

const balance = await client.getBalance("cosmos1...", "uatom");
const account = await client.getAccount("cosmos1...");
const block = await client.getBlock();
const tx = await client.getTx("ABC123...");

client.disconnect();

SigningStargateClient

Extends StargateClient with transaction signing and broadcasting. Inherits all read-only methods above.

Static Methods

Method	Parameters	Returns
`connectWithSigner`	`endpoint: string \| HttpEndpoint`, `signer: OfflineSigner`, `options?: SigningStargateClientOptions`	`Promise<SigningStargateClient>`
`createWithSigner`	`cometClient: CometClient`, `signer: OfflineSigner`, `options?: SigningStargateClientOptions`	`SigningStargateClient`
`offline`	`signer: OfflineSigner`, `options?: SigningStargateClientOptions`	`Promise<SigningStargateClient>`

Instance Methods

Method	Parameters	Returns
`simulate`	`signerAddress: string`, `messages: readonly EncodeObject[]`, `memo: string \| undefined`	`Promise<number>`
`sendTokens`	`senderAddress: string`, `recipientAddress: string`, `amount: readonly Coin[]`, `fee: StdFee \| "auto" \| number`, `memo?: string`	`Promise<DeliverTxResponse>`
`delegateTokens`	`delegatorAddress: string`, `validatorAddress: string`, `amount: Coin`, `fee: StdFee \| "auto" \| number`, `memo?: string`	`Promise<DeliverTxResponse>`
`undelegateTokens`	`delegatorAddress: string`, `validatorAddress: string`, `amount: Coin`, `fee: StdFee \| "auto" \| number`, `memo?: string`	`Promise<DeliverTxResponse>`
`withdrawRewards`	`delegatorAddress: string`, `validatorAddress: string`, `fee: StdFee \| "auto" \| number`, `memo?: string`	`Promise<DeliverTxResponse>`
`signAndBroadcast`	`signerAddress: string`, `messages: readonly EncodeObject[]`, `fee: StdFee \| "auto" \| number`, `memo?: string`, `timeoutHeight?: bigint`	`Promise<DeliverTxResponse>`
`signAndBroadcastSync`	`signerAddress: string`, `messages: readonly EncodeObject[]`, `fee: StdFee \| "auto" \| number`, `memo?: string`, `timeoutHeight?: bigint`	`Promise<string>`
`sign`	`signerAddress: string`, `messages: readonly EncodeObject[]`, `fee: StdFee`, `memo: string`, `explicitSignerData?: SignerData`, `timeoutHeight?: bigint`	`Promise<TxRaw>`

Instance Properties

Property	Type
`registry`	`Registry`
`broadcastTimeoutMs`	`number \| undefined`
`broadcastPollIntervalMs`	`number \| undefined`

Usage

import { SigningStargateClient, GasPrice } from "@cosmjs/stargate";
import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
import { MsgSend } from "cosmjs-types/cosmos/bank/v1beta1/tx";

const wallet = await DirectSecp256k1HdWallet.fromMnemonic("your mnemonic ...");
const [{ address }] = await wallet.getAccounts();

const client = await SigningStargateClient.connectWithSigner(
  "https://rpc.my-chain.network",
  wallet,
  { gasPrice: GasPrice.fromString("0.025uatom") },
);

const result = await client.sendTokens(
  address,
  "cosmos1recipient...",
  [{ denom: "uatom", amount: "1000000" }],
  "auto",
);

const sendMsg = {
  typeUrl: "/cosmos.bank.v1beta1.MsgSend",
  value: MsgSend.fromPartial({
    fromAddress: address,
    toAddress: "cosmos1recipient...",
    amount: [{ denom: "uatom", amount: "1000000" }],
  }),
};

await client.signAndBroadcast(address, [sendMsg], "auto", "memo");

GasPrice

Represents a gas price as an amount and denomination.

Method	Parameters	Returns
`constructor`	`amount: Decimal`, `denom: string`	`GasPrice`
`fromString` (static)	`gasPrice: string`	`GasPrice`
`toString`	—	`string`

Property	Type
`amount`	`Decimal`
`denom`	`string`

calculateFee

Calculates transaction fees from a gas limit and gas price.

function calculateFee(gasLimit: number, gasPrice: GasPrice | string): StdFee

import { calculateFee, GasPrice } from "@cosmjs/stargate";

const fee = calculateFee(200_000, GasPrice.fromString("0.025uatom"));
// { amount: [{ denom: "uatom", amount: "5000" }], gas: "200000" }

QueryClient

Base query client that supports modular extensions.

Method	Parameters	Returns
`withExtensions` (static)	`cometClient: CometClient`, `...extensionSetups: QueryExtensionSetup[]`	`QueryClient & Extensions`
`queryAbci`	`path: string`, `request: Uint8Array`, `desiredHeight?: number`	`Promise<QueryAbciResponse>`

Query Extensions

Setup functions to add module-specific query methods:

Function	Namespace	Key Methods
`setupBankExtension`	`bank`	`balance`, `allBalances`, `totalSupply`, `supplyOf`
`setupStakingExtension`	`staking`	`validators`, `delegation`, `delegatorDelegations`, `unbondingDelegation`
`setupGovExtension`	`gov`	`proposals`, `proposal`, `deposits`, `votes`, `tally`
`setupDistributionExtension`	`distribution`	`delegationRewards`, `delegationTotalRewards`, `communityPool`
`setupMintExtension`	`mint`	`inflation`, `annualProvisions`, `params`
`setupAuthExtension`	`auth`	`account`
`setupIbcExtension`	`ibc`	`channel.channel`, `channel.channels`, `transfer.denomTrace`
`setupTxExtension`	`tx`	`getTx`, `simulate`
`setupSlashingExtension`	`slashing`	`signingInfo`, `signingInfos`, `params`
`setupFeegrantExtension`	`feegrant`	`allowance`, `allowances`
`setupAuthzExtension`	`authz`	`grants`

import { QueryClient, setupBankExtension, setupStakingExtension } 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,
);

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

AminoTypes

Manages conversion between Protobuf messages and Amino JSON format.

Method	Parameters	Returns
`constructor`	`types: AminoConverters`	`AminoTypes`
`toAmino`	`encodeObject: EncodeObject`	`AminoMsg`
`fromAmino`	`aminoMsg: AminoMsg`	`EncodeObject`

Key Types

DeliverTxResponse

interface DeliverTxResponse {
  readonly height: number;
  readonly txIndex: number;
  readonly code: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  /** @deprecated Not filled in Cosmos SDK 0.50+. Use `events` instead. */
  readonly rawLog?: string;
  /** @deprecated Use `msgResponses` instead. */
  readonly data?: readonly MsgData[];
  readonly msgResponses: Array<{ readonly typeUrl: string; readonly value: Uint8Array }>;
  readonly gasUsed: bigint;
  readonly gasWanted: bigint;
}

IndexedTx

interface IndexedTx {
  readonly height: number;
  readonly txIndex: number;
  readonly hash: string;
  readonly code: number;
  readonly events: readonly Event[];
  readonly rawLog: string;
  readonly tx: Uint8Array;
  readonly msgResponses: Array<{ readonly typeUrl: string; readonly value: Uint8Array }>;
  readonly gasUsed: bigint;
  readonly gasWanted: bigint;
}

Block

interface Block {
  readonly id: string;
  readonly header: BlockHeader;
  readonly txs: readonly Uint8Array[];
}

BlockHeader

interface BlockHeader {
  readonly version: { readonly block: string; readonly app: string };
  readonly height: number;
  readonly chainId: string;
  readonly time: string;
}

SigningStargateClientOptions

interface SigningStargateClientOptions extends StargateClientOptions {
  readonly registry?: Registry;
  readonly aminoTypes?: AminoTypes;
  readonly broadcastTimeoutMs?: number;
  readonly broadcastPollIntervalMs?: number;
  readonly gasPrice?: GasPrice | DynamicGasPriceConfig;
}

SignerData

interface SignerData {
  readonly accountNumber: number;
  readonly sequence: number;
  readonly chainId: string;
}

Account

interface Account {
  readonly address: string;
  readonly pubkey: Pubkey | null;
  readonly accountNumber: number;
  readonly sequence: number;
}

SequenceResponse

interface SequenceResponse {
  readonly accountNumber: number;
  readonly sequence: number;
}

Helper Functions

Function	Parameters	Returns
`assertIsDeliverTxSuccess`	`result: DeliverTxResponse`	`void` (throws on failure)
`assertIsDeliverTxFailure`	`result: DeliverTxResponse`	`void` (throws on success)
`isDeliverTxSuccess`	`result: DeliverTxResponse`	`boolean`
`isDeliverTxFailure`	`result: DeliverTxResponse`	`boolean`
`coin`	`amount: number \| string`, `denom: string`	`Coin`
`coins`	`amount: number \| string`, `denom: string`	`Coin[]`
`parseCoins`	`input: string`	`Coin[]`
`makeCosmoshubPath`	`account: number`	`HdPath`
`createPagination`	`paginationKey?: Uint8Array`	`PageRequest`
`createProtobufRpcClient`	`base: QueryClient`	`ProtobufRpcClient`
`decodeCosmosSdkDecFromProto`	`input: string \| Uint8Array`	`Decimal`

Error Classes

Class	Description
`BroadcastTxError`	Thrown when a transaction fails during broadcast
`TimeoutError`	Thrown when broadcast times out waiting for inclusion

CosmJS

Concepts

Guides

API Reference

StargateClient

Static Methods

Instance Methods

Usage

SigningStargateClient

Static Methods

Instance Methods

Instance Properties

Usage

GasPrice

calculateFee

QueryClient

Query Extensions

AminoTypes

Key Types

DeliverTxResponse

IndexedTx

Block

BlockHeader

SigningStargateClientOptions

SignerData

Account

SequenceResponse

Helper Functions

Error Classes

​StargateClient

​Static Methods

​Instance Methods

​Usage

​SigningStargateClient

​Static Methods

​Instance Methods

​Instance Properties

​Usage

​GasPrice

​calculateFee

​QueryClient

​Query Extensions

​AminoTypes

​Key Types

​DeliverTxResponse

​IndexedTx

​Block

​BlockHeader

​SigningStargateClientOptions

​SignerData

​Account

​SequenceResponse

​Helper Functions

​Error Classes

StargateClient

Static Methods

Instance Methods

Usage

SigningStargateClient

Static Methods

Instance Methods

Instance Properties

Usage

GasPrice

calculateFee

QueryClient

Query Extensions

AminoTypes

Key Types

DeliverTxResponse

IndexedTx

Block

BlockHeader

SigningStargateClientOptions

SignerData

Account

SequenceResponse

Helper Functions

Error Classes