Cosmos Wallet Documentation

System Requirements

Operating System: Windows 10+, macOS 10.15+, Ubuntu 18.04+
RAM: 4GB minimum, 8GB recommended
Storage: 500MB available space
Network: Internet connection required

Download and Install

Download the appropriate installer for your operating system:

First-Time Setup

After installation, follow the steps depending on your operating system

Launch Cosmos Wallet from the Start Menu or desktop shortcut.
Choose Create New Wallet or Restore Wallet.
If creating a new wallet, carefully write down the recovery phrase.
Set a strong password to protect local access.

Open the .dmg file and drag Cosmos Wallet into Applications.
Launch from Launchpad or Finder.
On first run, choose Create New Wallet or Restore Wallet.
Back up your recovery phrase securely.
Create a password for app access.

Download the .AppImage or .deb package.
For AppImage: chmod +x cosmos-wallet.AppImage
Launch from terminal or app menu.
Select Create New Wallet or Restore Wallet.
Save your recovery phrase offline and set a strong password.

Verification

To confirm that installation and setup were successful, check the following:

Step 1 – Application Launch

• Open Cosmos Wallet without errors or crashes.
• The home screen should display wallet creation/restore options.

Step 2 – Version Check

• Navigate to Settings → About
• Confirm the version number matches the official release page.

Step 3 – Network Status

• Ensure the status indicator shows Connected to Cosmos Hub or another chain.
• If offline, check firewall, proxy, or VPN settings.

Step 4 – Test Account (Optional)

• Create a new wallet and verify that an address is generated.
• Transactions can be tested later once funds are added.

Troubleshooting

If you encounter issues during installation or first launch, try the following:

Installer won’t run

• Windows: Right-click → Run as Administrator
• macOS: Allow the app in System Preferences → Security & Privacy
• Linux: Ensure executable permissions with chmod +x.

Application won’t launch

• Confirm your system meets minimum OS requirements.
• Update GPU drivers if running on Linux.

No network connection

• Verify your internet is active and firewall allows Cosmos Wallet.
• Check if your VPN/proxy is interfering.

Corrupted files

• Redownload the installer from the [official page].
• Avoid third-party downloads to prevent tampering.

Interface Overview

When you first open Cosmos Wallet, you’ll notice three main sections:

• Dashboard – your balances and recent activity.
• Navigation Panel – quick access to Send, Receive, Staking, IBC Transfers.
• Settings Menu – configuration, preferences, and network tools.

Account Management Basics

Cosmos Wallet supports multiple accounts.

• Switch between accounts from the top-left dropdown.
• Each account has its own address but can share the same recovery phrase (HD derivation).
• Use labels to keep accounts organized (e.g., “Main”, “Staking”, “Testing”).

Exploring Features

Here’s what you can do right after installation:

• Portfolio View – track all Cosmos assets in one place.
• Staking Panel – delegate tokens and view validator info.
• IBC Transfers – move assets between Cosmos chains.
• Transaction History – see confirmations and memos.

Best Practices for Beginners

Before moving larger amounts, follow these simple steps:

Troubleshooting at First Launch

• Wallet won’t connect? → Check internet connection and firewall.
• Balances not showing? → Verify that the correct network is selected.
• App feels slow? → Switch to a different public RPC endpoint in Settings → Network.

Network Settings

Cosmos Wallet can connect to different Cosmos-based blockchains through RPC and REST endpoints.

Default Setup

• Preloaded with stable public nodes for Cosmos Hub.
• Automatically selects the fastest available endpoint.

Custom Configuration

Users may add their own endpoints:

{
  "network": "cosmoshub",
  "chain_id": "cosmoshub-4",
  "rpc": "https://cosmos-rpc.publicnode.com",
  "rest": "https://cosmos-rest.publicnode.com"
}

• rpc → for broadcasting and querying transactions
• rest → for light client queries and API calls
• chain_id → must match the target network

💡 Advanced users can run a local full node and point Cosmos Wallet to it for maximum privacy and control.

Security Configuration

Protect your wallet against unauthorized access:

• Local Encryption: Private keys are encrypted on-disk with AES-256.
• Password Settings: Require password for every send/transaction approval.
• Auto-Lock Timer: Auto-lock after 1–60 minutes of inactivity.
• Hardware Wallets: Use Ledger/Trezor for transaction signing.
• Session Timeout: Force re-login after a set period.

⚠️ Cosmos Wallet never stores or transmits your seed phrase. All security measures are local.

Display Preferences

Customize the interface to your liking:

Advanced Options

For users who want more control:

• Experimental Features: Enable beta modules (e.g., NFT viewer, advanced staking analytics).
• Developer Mode: Exposes raw transaction JSON before signing.
• Logs Export: Download anonymized logs to assist with troubleshooting.

Creating a New Wallet

When you start Cosmos Wallet for the first time, you’ll be asked to either create a new wallet or restore an existing one.

Restoring an Existing Wallet

If you already have an account, you can import it instead of creating a new one.

Supported restore methods:

• Seed Phrase (12/24 words) → safest and most complete restore option.
• Private Key → restores one account only; not recommended for long-term use.
• Keystore File (JSON) → import a file exported from another wallet app.

Multi-Account Management

Cosmos Wallet supports HD wallets, meaning multiple accounts can be derived from a single seed.

• Create Sub-Accounts → safest and most complete restore option.
• Label Accounts → rename for easier tracking (e.g., Main, Staking, Cold Storage).
• Quick Switch → toggle between accounts in one click.
• Combined Portfolio → see balances across all accounts in one overview.
• Use Cases:
  • Keep separate accounts for daily use and staking.
  • Manage multiple validator or testnet accounts from one app.

Advanced Tips

Cosmos Wallet supports HD wallets, meaning multiple accounts can be derived from a single seed.

• Testnet vs Mainnet → when restoring, double-check you’re using the correct network.
• Cold Storage → you can generate a wallet, back up the seed phrase, and delete the app. Use it later only for recovery.
• Multiple Devices → restore the same wallet on another device with the seed phrase.
• Security Add-ons → combine with a hardware wallet (Ledger/Trezor) for transaction signing.

Security Checklist

• Back up your seed phrase offline before adding funds.
• Store backups in multiple secure locations (not digital).
• Test restore on a spare device to ensure backups work.
• Never share your phrase with anyone — even support teams.

Receiving Tokens

To receive funds into your Cosmos Wallet:

Step 1 – Access Receive Screen

• Open the app and click “Receive”.
• Your wallet address will be displayed (starts with cosmos1...).
• A QR code is also generated for quick sharing.

Step 2 – Share Your Address

• Copy the address or show the QR code to the sender.
• Always double-check that the full address matches before sharing.

💡 Tip: If using exchanges, make sure the chain is Cosmos Hub (ATOM) and not another IBC chain.

Step 3 – Wait for Confirmation

• Transactions usually finalize in 5–10 seconds.
• Funds appear automatically in your portfolio once confirmed.

Sending Tokens

When you send ATOM or other Cosmos SDK tokens, you must enter transaction details correctly.

Step 1 – Enter Transaction Details

• Go to Send.
• Input recipient’s address (cosmos1…).
• Enter the amount and select the token (e.g., ATOM, OSMO).
• Optional: Add a memo (many exchanges require this).

Step 2 – Review Fees

• Cosmos uses gas fees (paid in the same token).
• Typical fee: 0.0025 ATOM for a standard transfer.
• You can set Low / Medium / High fee levels in the wallet.

Step 3 – Confirm and Send

• Review transaction summary.
• Enter your local password or confirm via Ledger/Trezor if enabled.
• Click Send → transaction is broadcast to the network.

Step 4 – Track Confirmation

• Transactions show up in your History tab.
• Status: Pending → Confirmed.
• Most transactions are final after 1–2 blocks.

Advanced Features

Cosmos Wallet provides tools for advanced users:

• Batch Transactions: Send to multiple addresses in a single broadcast.
• Scheduled Sends: Queue transactions to execute at a future time.
• Custom Memos: Attach structured metadata for validators, dApps, or exchanges.
• Fee Adjustment: Manually set gas fee for priority inclusion.

Security Checklist

Before sending tokens:

• Double-Check Addresses – Copy-paste errors are common; never type manually.
• Verify Network – Sending to the wrong Cosmos chain (Hub vs Osmosis vs Juno) may cause loss of funds.
• Start Small – For large transfers, always test with a small amount first.
• Memo Required – If depositing to an exchange, ensure you include the correct

Troubleshooting

• Transaction Failed → Check if gas fee was too low.
• Funds Not Received → Verify you used the correct chain and memo.
• Stuck Pending → Network may be congested; resubmit with higher fee.
• Wrong Address → Transactions on Cosmos are irreversible. Always test first.

Understanding Staking

Staking allows you to earn rewards while also contributing to the security and decentralization of the Cosmos ecosystem:

• Delegation: You delegate tokens to validators without losing ownership of your funds.
• Rewards: Average APY ranges between 5–20%, depending on validator performance and overall network parameters.
• Security: By staking, you help secure the Cosmos Hub and other networks using Proof of Stake.
• Governance: Stakers can participate in governance by voting on proposals through their validators.
• Risks : Choosing unreliable validators can lead to missed rewards or even slashing penalties (loss of a portion of your stake).

How to Stake

Follow these steps to start staking in Cosmos Wallet:

Validator Selection

Important factors when picking a validator:

Validator Metrics:
- Commission Rate: % fee taken from your rewards
- Uptime: % of blocks signed successfully (higher is better)
- Voting Power: Stake delegated to the validator
- Self-Delegation: Tokens staked by the validator themselves
- Community Involvement: Reputation and governance activity

💡 Tip: Avoid staking all your tokens with one validator. Delegating to multiple validators reduces risk.

Unstaking Process

When you undelegate tokens, they are subject to an unbonding period before they become available:

• Unbonding Period: 21 days on most Cosmos chains. During this time, tokens cannot be moved or traded.
• No Rewards: Tokens do not earn rewards during unbonding.
• Slashing Risk: If your validator misbehaves (e.g., downtime or double-signing), your stake can be partially slashed.
• Liquid Staking: Some protocols offer liquid staking derivatives (e.g., stATOM, stkATOM) that let you keep liquidity while still earning rewards.

Common Issues & Troubleshooting

• Rewards not showing up → Check if you claimed them manually or if your validator distributes on schedule.
• Unbonding taking too long → Confirm the chain’s unbonding period; 21 days is typical but can differ on other Cosmos SDK chains.
• High commission → If a validator increases fees after you delegate, you can redelegate to another validator without waiting for unbonding.
• Validator jailed → If your validator is inactive or jailed, you will stop receiving rewards until you redelegate.

What is IBC?

IBC (Inter-Blockchain Communication) is the protocol that allows tokens and data to move between independent blockchains built on the Cosmos SDK. It ensures trustless, secure, and verifiable transfers across chains.

Key points:

• Cross-chain: Move tokens between Cosmos Hub, Osmosis, Juno, and many others.
• Trustless: No centralized bridges or intermediaries; transfers are validated by the chains themselves.
• Native Integration: IBC is built directly into the Cosmos SDK.
• Asset Preservation: Transferred tokens are locked on the source chain and minted as vouchers on the destination chain.

Supported Networks

Major IBC-enabled networks supported in Cosmos Wallet:

Source Chain → Destination Chain
─────────────────────────────────
Cosmos Hub    → Osmosis, Juno, Akash
Osmosis       → Cosmos Hub, Secret Network
Juno          → Cosmos Hub, Osmosis
Akash         → Cosmos Hub, Osmosis
Secret        → Osmosis, Cosmos Hub
Stargaze      → Osmosis, Juno

💡 Tip: The list of supported chains updates frequently. Always check the wallet’s live network list before sending.

Making IBC Transfers

Steps for a successful transfer:

Transfer Timing and Fees

Typical IBC transfer parameters:

Processing Time:   10–30 seconds
Timeout:           10 minutes (default)
Relay Fees:        Paid in tokens from source chain
Gas Costs:         Standard fees per chain
Finality:          After ~2–3 block confirmations

⚠️ Fees must be available on both chains for the transfer to succeed.

Troubleshooting

Common issues and solutions:

• Failed Transfer → Verify that the IBC channel between chains is active and funded.
• Timeout Error → Transaction not relayed in time; check relayer activity and try again.
• Incorrect Address → Ensure the recipient address is for the correct chain (cosmos1..., osmo1..., juno1...).
• Insufficient Fees → Make sure you have enough tokens to cover gas on both chains.
• Voucher Tokens Confusion → Remember: transferred tokens may appear as “ibc/…” assets on the destination chain. They are valid and can be swapped back.

Best Practices

• Always test with a small transfer before sending large amounts.
• Keep a balance on both chains for fees.
• Track IBC channel status using explorers like Mintscan.
• Redeem “ibc/…” vouchers back to native tokens when needed.

Introduction

Cosmos Wallet provides a comprehensive API for developers:

• RESTful API: Standard HTTP endpoints for wallet operations
• WebSocket: Real-time updates for transactions and balances
• JSON-RPC: Direct blockchain interaction methods
• SDK Support: Official libraries for popular programming languages

Base URL and Versioning

API endpoint structure and versioning:

Base URL: https://api.cosmoswallet.app
Current Version: v1
Full Endpoint: https://api.cosmoswallet.app/v1

Example Requests:
GET /v1/wallets/{address}/balance
POST /v1/transactions/send
GET /v1/networks/supported

Response Format

Standard API response structure:

{
  "success": true,
  "data": {
    "address": "cosmos1abc...xyz",
    "balance": "1000.5",
    "denom": "uatom"
  },
  "message": "Balance retrieved successfully",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

Available Endpoints

Core API functionality categories:

API Key Authentication

Generate and use API keys for secure access:

// Request Header
Authorization: Bearer your_api_key_here
Content-Type: application/json

// Example cURL
curl -X GET \
  https://api.cosmoswallet.app/v1/wallets/balance \
  -H 'Authorization: Bearer cwapi_1234567890abcdef' \
  -H 'Content-Type: application/json'

OAuth 2.0 Flow

For applications requiring user consent:

Rate Limiting

API usage limits and best practices:

Rate Limits:
- Free Tier: 100 requests/minute
- Pro Tier: 1,000 requests/minute
- Enterprise: Custom limits

Response Headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

Common authentication errors and solutions:

• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions for endpoint
• 429 Too Many Requests: Rate limit exceeded
• 400 Bad Request: Malformed authentication header

Wallet Endpoints

Manage wallet accounts and retrieve balances:

GET /v1/wallets/{address}/balance
GET /v1/wallets/{address}/transactions
POST /v1/wallets/create
POST /v1/wallets/import
DELETE /v1/wallets/{address}

Transaction Endpoints

Send transactions and track their status:

POST /v1/transactions/send
{
  "from": "cosmos1abc...xyz",
  "to": "cosmos1def...uvw",
  "amount": "100.5",
  "denom": "uatom",
  "memo": "Payment",
  "gas": "auto"
}

GET /v1/transactions/{txHash}
GET /v1/transactions/pending

Staking Endpoints

Staking operations and validator management:

GET /v1/staking/validators
GET /v1/staking/delegations/{address}
POST /v1/staking/delegate
POST /v1/staking/undelegate
POST /v1/staking/claim-rewards

IBC Endpoints

Cross-chain transfer functionality:

GET /v1/ibc/channels
GET /v1/ibc/networks
POST /v1/ibc/transfer
{
  "source_chain": "cosmoshub-4",
  "dest_chain": "osmosis-1",
  "from": "cosmos1abc...xyz",
  "to": "osmo1def...uvw",
  "amount": "10.0",
  "denom": "uatom",
  "timeout": 600
}

Network Information

Get network status and configuration:

GET /v1/networks/supported
GET /v1/networks/{chain-id}/status
GET /v1/networks/{chain-id}/validators
GET /v1/networks/{chain-id}/governance