cosmpy

0.11.2 verified Fri May 01 auth: no python

A Python library for interacting with Cosmos SDK-based blockchains. Supports transaction creation, signing, and querying. Current version 0.11.2 (latest stable), with release candidates for 0.12.0 targeting Cosmos SDK v0.53.4. Release cadence is irregular, with several minor versions per year.

pip install cosmpy

Common errors

error ModuleNotFoundError: No module named 'cosmpy.client' ↓

cause Wrong import path (singular 'client' does not exist).

fix

Use 'from cosmpy.clients import LedgerClient' (plural).

error AttributeError: module 'cosmpy' has no attribute 'Wallet' ↓

cause Wallet was moved to cosmpy.wallet in v0.8.0.

fix

Use 'from cosmpy.wallet import Wallet'.

error ValueError: Invalid denomination: "atom" (expected micro-denom like "uatom") ↓

cause Denomination must be the smallest base unit (e.g., uatom, not atom).

fix

Use the proper micro-denomination string (e.g., 'uatom').

Warnings

gotcha Import path for clients is cosmpy.clients (plural). Many examples show 'cosmpy.client' which does not exist. ↓

fix Use 'from cosmpy.clients import LedgerClient'.

gotcha Wallet class moved from cosmpy.crypto to cosmpy.wallet in v0.8.0. ↓

fix Use 'from cosmpy.wallet import Wallet'.

gotcha The 'LedgerClient' is not available in v0.12.0rc* (replaced by 'StargateClient'). If you upgrade to v0.12.0rc, update imports. ↓

fix Use 'from cosmpy.clients import StargateClient' instead.

gotcha When querying balances, the denomination string must match the chain's coin type (e.g., 'uatom' for Cosmos Hub). Using a wrong denomination returns zero or error. ↓

fix Check the chain's coin denom (e.g., 'uatom', 'uosmo', etc.).

gotcha Transaction broadcasting requires a client with a valid connection. Timeout errors often occur if RPC endpoint is unreachable. ↓

fix Ensure the RPC URL is correct and the node is accessible. Use client.ping() to test connectivity.

Imports

LedgerClient
```
from cosmpy.clients import LedgerClient
```
Common mistake is importing from cosmpy.client (missing 's').

Wallet

wrong

from cosmpy.crypto import Wallet

correct

from cosmpy.wallet import Wallet

Wallet was moved from cosmpy.crypto in v0.8.

StargateClient

wrong

from cosmpy.client import StargateClient

correct

from cosmpy.clients import StargateClient

Similar to LedgerClient, path is cosmpy.clients (plural).

Address

wrong

from cosmpy.address import Address

correct

from cosmpy.crypto.address import Address

Address lives in cosmpy.crypto.address.

Quickstart

Connect to a Cosmos node, create a wallet from a mnemonic, and query a balance.

from cosmpy.clients import LedgerClient
from cosmpy.wallet import Wallet

# Connect to a Cosmos node
client = LedgerClient("https://rpc.cosmos.network:26657")

# Create a wallet from a mnemonic (use env var for security)
import os
mnemonic = os.environ.get("MNEMONIC", "")
wallet = Wallet.from_mnemonic(mnemonic)

# Query balance
balance = client.query_bank_balance(wallet.address(), "uatom")
print(balance)