Quick Start

Install CosmJS, connect to a Cosmos SDK chain, query state, and send your first transaction

This guide walks you through installing CosmJS, connecting to a Cosmos SDK chain, querying on-chain state, and sending your first transaction.

Prerequisites

• Node.js v22 or later
• npm, yarn, or pnpm
• A Cosmos SDK chain RPC endpoint (e.g. https://rpc.my-chain.network for the Cosmos Hub)

1. Install

   npm

   npm install @cosmjs/stargate @cosmjs/proto-signing
   
2. Connect to a chain

   Create a read-only client and verify the connection:

   import { StargateClient } from "@cosmjs/stargate";
   
   const rpcEndpoint = "https://cosmos-rpc.polkachu.com";
   const client = await StargateClient.connect(rpcEndpoint);
   
   const chainId = await client.getChainId();
   const height = await client.getHeight();
   console.log(`Connected to ${chainId} at height ${height}`);
   

   Find RPC endpoints for any Cosmos chain in the chain registry.

3. Query balances

   Use the connected client to look up any account’s balance:

   const address = "cosmos1...";
   const balance = await client.getBalance(address, "uatom");
   console.log(`Balance: ${balance.amount} ${balance.denom}`);
   
   const account = await client.getAccount(address);
   console.log("Account:", account);
   
   const allBalances = await client.getAllBalances(address);
   console.log("All balances:", allBalances);
   
4. Create a signer

   To send transactions you need a signer. You can create one from a mnemonic for development, or connect a browser wallet like Keplr in production.

   From mnemonic

   import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
   
   const wallet = await DirectSecp256k1HdWallet.fromMnemonic(
     "your mnemonic words here ...",
     { prefix: "cosmos" },
   );
   const [{ address }] = await wallet.getAccounts();
   console.log("Signer address:", address);
   

   Never hard-code or commit mnemonics. Use environment variables or a secrets manager.

   Keplr wallet (browser)

   const chainId = "cosmoshub-4";
   await window.keplr.enable(chainId);
   const offlineSigner = window.keplr.getOfflineSigner(chainId);
   const [{ address }] = await offlineSigner.getAccounts();
   console.log("Keplr address:", address);
   
5. Send tokens

   Connect a signing client and broadcast a token transfer:

   import { SigningStargateClient, GasPrice } from "@cosmjs/stargate";
   
   const signingClient = await SigningStargateClient.connectWithSigner(
     rpcEndpoint,
     wallet, // or offlineSigner from Keplr
     { gasPrice: GasPrice.fromString("0.025uatom") },
   );
   
   const result = await signingClient.sendTokens(
     address,
     "cosmos1recipientaddress...",
     [{ denom: "uatom", amount: "1000000" }], // 1 ATOM = 1,000,000 uatom
     "auto",
   );
   
   console.log("Tx hash:", result.transactionHash);
   console.log("Gas used:", result.gasUsed);
   

   Setting fee to "auto" lets CosmJS simulate the transaction and estimate gas automatically. You can also pass an explicit StdFee object for fine-grained control.

6. Send arbitrary messages

   For transactions beyond simple token transfers, construct message objects directly:

   import { MsgDelegate } from "cosmjs-types/cosmos/staking/v1beta1/tx";
   
   const msg = {
     typeUrl: "/cosmos.staking.v1beta1.MsgDelegate",
     value: MsgDelegate.fromPartial({
       delegatorAddress: address,
       validatorAddress: "cosmosvaloper1...",
       amount: { denom: "uatom", amount: "1000000" },
     }),
   };
   
   const result = await signingClient.signAndBroadcast(address, [msg], "auto");
   console.log("Tx hash:", result.transactionHash);
   

Next Steps

Clients

Understand read-only and signing client architecture.

Querying

Query balances, staking, governance, and custom modules.

Fees & Gas

Configure gas pricing, simulation, and fee calculation.

CosmWasm

Deploy, instantiate, and execute smart contracts.