Skip to main content
Get your first Cosmos SDK blockchain running in minutes. This guide will walk you through initializing, configuring, and starting a local chain using simapp, the SDK’s reference implementation.

​
Prerequisites

Before you begin, ensure you have:
  • Go 1.21 or later installed
  • Git installed
  • Basic command-line knowledge
  • At least 2GB of available disk space
If you haven’t installed the Cosmos SDK yet, check out the installation guide first.

​
Initialize your chain

1

Clone the Cosmos SDK repository

Clone the repository and navigate to the simapp directory:
git clone https://github.com/cosmos/cosmos-sdk
cd cosmos-sdk
2

Build the simapp binary

Build the simd binary which is the blockchain daemon:
make build
Verify the installation:
./build/simd version
You should see the SDK version output.
3

Initialize the chain

Initialize your chain with a moniker (node name) and chain ID:
./build/simd init mynode --chain-id my-test-chain
This creates the default configuration files in ~/.simapp/:
  • config/app.toml - Application configuration
  • config/config.toml - CometBFT configuration
  • config/genesis.json - Genesis state
  • data/ - Blockchain data directory
{
  "moniker": "mynode",
  "chain_id": "my-test-chain",
  "node_id": "a4f3c8d2e1b0...",
  "gentxs_dir": "",
  "app_message": {
    "auth": {...},
    "bank": {...},
    ...
  }
}
4

Create a key pair

Create a key that will be used for your validator and test account:
./build/simd keys add alice
Save the mnemonic phrase shown in the output. You’ll need it to recover your key.
The output will show:
- address: cosmos1...
  name: alice
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey",...}'
  type: local

**Important** write this mnemonic phrase in a safe place.
...24 word mnemonic...
5

Add genesis account

Add your key as a genesis account with initial tokens:
./build/simd genesis add-genesis-account alice 100000000stake --keyring-backend test
This adds alice to the genesis file with 100,000,000 stake tokens.
6

Create genesis transaction

Create a genesis transaction that makes your account a validator:
./build/simd genesis gentx alice 1000000stake --chain-id my-test-chain --keyring-backend test
This creates a validator with 1,000,000 stake tokens delegated to it.
7

Collect genesis transactions

Collect all genesis transactions (in this case, just one):
./build/simd genesis collect-gentxs
This finalizes the genesis file.
8

Start the blockchain

Start your blockchain node:
./build/simd start
You should see blocks being produced:
8:37PM INF finalizing commit of block hash=... height=1 module=consensus
8:37PM INF executed block height=1 module=state num_invalid_txs=0 num_valid_txs=0
8:37PM INF commit synced commit=... module=server
8:37PM INF committed state app_hash=... height=1 module=state
Press Ctrl+C to stop the node when you’re done testing.

​
Interact with your chain

Once your chain is running, open a new terminal to interact with it:

​
Query account balance

./build/simd query bank balances $(./build/simd keys show alice -a --keyring-backend test)

​
Send tokens

Create another account and send tokens: 
# Create bob's account
./build/simd keys add bob --keyring-backend test

# Send tokens from alice to bob
./build/simd tx bank send alice $(./build/simd keys show bob -a --keyring-backend test) 1000stake \
  --chain-id my-test-chain \
  --keyring-backend test \
  --yes

​
Query transaction

./build/simd query tx <TX_HASH>

​
Query block

./build/simd query block 1

​
Configuration

The default configuration is suitable for testing, but you can customize:

​
Application configuration (~/.simapp/config/app.toml)

Key settings:
  • minimum-gas-prices - Minimum gas price for transactions
  • pruning - State pruning strategy
  • api.enable - Enable REST API server
  • grpc.enable - Enable gRPC server

​
CometBFT configuration (~/.simapp/config/config.toml)

Key settings:
  • moniker - Node name
  • proxy_app - ABCI application address
  • rpc.laddr - RPC server listen address
  • p2p.laddr - P2P listen address
  • p2p.seeds - Seed nodes for discovery

​
Troubleshooting

If you see bind: address already in use, another process is using the default ports (26656, 26657).Stop other Cosmos SDK chains or change the ports in config.toml:
[rpc]
laddr = "tcp://127.0.0.1:26657"

[p2p]
laddr = "tcp://0.0.0.0:26656"
If gentx fails, ensure:
  • The account exists in genesis: simd genesis add-genesis-account
  • The chain-id matches: Use the same --chain-id everywhere
  • The keyring backend matches: Use --keyring-backend test consistently
To start fresh:
./build/simd tendermint unsafe-reset-all
rm -rf ~/.simapp
Then repeat the initialization steps.

​
Next steps

Architecture

Learn how Cosmos SDK applications are structured

Building chains

Create your own custom blockchain application

Modules

Explore available modules for your chain

API reference

Dive into the SDK’s core APIs

​
Using the quick initialization script

For rapid testing, use the built-in initialization script: 
make init-simapp
This script automatically:
  1. Builds the binary
  2. Initializes the chain
  3. Creates test accounts (alice and bob)
  4. Adds genesis accounts
  5. Creates a genesis validator
  6. Starts the chain
The script is defined in scripts/init-simapp.sh and is perfect for quick testing iterations.

Build docs developers (and LLMs) love

Get started for freeTalk to us