CosmoScope is a command-line portfolio tracker that aggregates balances across Cosmos, EVM, and Solana networks. Cosmos chain metadata and REST endpoints are loaded from the Cosmos Chain Registry; only curated, priced assets are included in the report.
- Multi-chain portfolio tracking
- Cosmos — bank, staking, and reward balances via chain-registry REST endpoints
- EVM — Ethereum, Polygon, Base, BSC, and other compatible chains
- Solana — native SOL and curated SPL tokens via JSON-RPC
- Balance types supported:
- Wallet balances
- Staked assets
- Unclaimed rewards
- Fixed balances (exchange / cold storage)
- Curated IBC token resolution (ATOM, USDC, AKT, TIA, DYM, and others on Osmosis-connected paths)
- Automatic REST endpoint discovery with health probing and failover
- Spam filtering — skips unknown IBC denoms, GAMM/LP/factory pool tokens, and unpriced assets
- Real-time USD values via CoinGecko (with ERC-20 metadata from Moralis)
- Detailed balance view, portfolio summary, and network distribution
# Clone the repository
git clone https://github.com/vitwit/cosmoscope.git
cd cosmoscope
# Install development dependencies
make dev-deps
# Copy and configure settings
cp configs/config_example.json configs/config.json
# Edit the configuration file with your details
vim configs/config.json
# Build the project
make build
# Run tests
make test
# Run the application
make run- Go 1.21 or later
- Make
- golangci-lint (installed via make dev-deps)
make build # Build the binary
make test # Run tests
make lint # Run linter
make coverage # Generate coverage report
make clean # Clean build artifacts
make dev-deps # Install development dependencies
make deps-update # Update dependencies
make check-tools # Check tool versions# Run all tests
make test
# Run tests with coverage
make coverage
# View coverage report in browser
go tool cover -html=coverage.out- Copy the example configuration:
cp configs/config_example.json configs/config.json- Update
configs/config.jsonwith your details:- cosmos_networks — chain folder names from chain-registry (e.g.
cosmoshub,osmosis,akash) - cosmos_addresses — one or more bech32 addresses (converted per-chain automatically)
- evm_networks / evm_addresses — RPC URLs and wallet addresses
- solana_networks / solana_addresses — RPC URL and wallet addresses
- fixed_balances — manual entries for off-chain holdings
- coingecko_uri — CoinGecko markets URL for USD pricing
- moralis_api_key — used for EVM ERC-20 token metadata
- cosmos_networks — chain folder names from chain-registry (e.g.
Example configuration:
{
"cosmos_networks": ["cosmoshub", "osmosis", "akash", "celestia", "dydx"],
"cosmos_addresses": ["cosmos1..."],
"evm_networks": [
{
"name": "ethereum",
"rpc": "https://mainnet.infura.io/v3/YOUR_KEY",
"chain_id": 1,
"native_token": {
"symbol": "ETH",
"name": "Ethereum",
"decimals": 18
}
}
],
"evm_addresses": ["0x..."],
"solana_networks": [
{
"name": "mainnet",
"rpc": "https://api.mainnet-beta.solana.com",
"chain_id": "mainnet-beta"
}
],
"solana_addresses": ["YOUR_SOLANA_ADDRESS"],
"moralis_api_key": "YOUR-MORALIS-API-KEY",
"coingecko_uri": "https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&ids=...",
"fixed_balances": [
{
"token": "BTC",
"amount": 1,
"label": "Cold Wallet"
}
]
}Network names must match chain-registry directory names. REST endpoints are discovered automatically from each chain's chain.json, probed for health, cached, and rotated on failure. Queries run sequentially per chain to reduce rate limiting.
Only well-known IBC denoms (Osmosis-connected paths for major assets) and native chain tokens with a CoinGecko price are shown. Unknown ibc/… denoms, GAMM pool shares, LP tokens, and factory spam are skipped silently.
Tracks native SOL plus curated SPL mints (USDC, USDT, JUP, RAY, BONK, etc.). The public Solana RPC supports per-mint balance queries; unlisted or unpriced mints are ignored.
Legacy config format is also supported via a top-level "solana" block with "rpc" and "addresses" fields.
-
CoinGecko (required for USD values)
- Configure
coingecko_uriinconfig.jsonwith the token IDs you need - Free tier: https://www.coingecko.com/en/api
- Configure
-
Moralis API Key (EVM ERC-20 metadata)
- Sign up at https://moralis.io/
- Add to
config.jsonasmoralis_api_key
-
EVM RPC Endpoints
- Infura: https://infura.io/
- Alchemy: https://www.alchemy.com/
- Or any JSON-RPC provider
-
Solana RPC (optional)
- Public: https://api.mainnet-beta.solana.com
- Helius: https://helius.dev/
- QuickNode: https://www.quicknode.com/
Running cosmoscope produces a detailed breakdown of your portfolio across different networks and asset types:
╔════════════════════════════════════════════════════════════╗
║ ║
║ BALANCES REPORT - 2024-03-12 15:04:05 ║
║ ║
╚════════════════════════════════════════════════════════════╝
Detailed Balance View:
+----------------------+-----------------+----------+---------------+--------------+
| ACCOUNT | NETWORK | TOKEN | AMOUNT | USD VALUE |
+----------------------+-----------------+----------+---------------+--------------+
| cosmos1abc...def | cosmos-bank | ATOM | 520.4530 | $5,204.53 |
| cosmos1abc...def | cosmos-staking | ATOM | 2500.0000 | $25,000.00 |
| cosmos1abc...def | cosmos-rewards | ATOM | 3.4520 | $34.52 |
| osmo1xyz...789 | osmosis-bank | OSMO | 1200.0000 | $2,400.00 |
| osmo1xyz...789 | osmosis-bank | ATOM | 150.0000 | $1,500.00 |
| osmo1xyz...789 | osmosis-staking | OSMO | 5000.0000 | $10,000.00 |
| 7xKX...abc | mainnet | SOL | 25.0000 | $3,750.00 |
| 7xKX...abc | mainnet | USDC | 5000.0000 | $5,000.00 |
| 0x123...789 | ethereum | ETH | 1.5000 | $4,500.00 |
| 0x123...789 | polygon | MATIC | 10000.0000 | $10,000.00 |
| Cold Storage | Fixed Balance | BTC | 0.7500 | $30,000.00 |
| Exchange | Fixed Balance | ETH | 2.0000 | $6,000.00 |
+----------------------+-----------------+----------+---------------+--------------+
Portfolio Summary:
+----------+---------------+--------------+----------+
| TOKEN | AMOUNT | USD VALUE | SHARE % |
+----------+---------------+--------------+----------+
| ATOM | 3173.9050 | $31,739.05 | 29.50% |
| OSMO | 6200.0000 | $12,400.00 | 11.52% |
| SOL | 25.0000 | $3,750.00 | 3.49% |
| USDC | 5000.0000 | $5,000.00 | 4.65% |
| ETH | 3.5000 | $10,500.00 | 9.76% |
| MATIC | 10000.0000 | $10,000.00 | 9.30% |
| BTC | 0.7500 | $30,000.00 | 27.90% |
+----------+---------------+--------------+----------+
Total Portfolio Value: $107,639.05
Network Distribution:
+-------------------+--------------+----------+
| NETWORK | USD VALUE | SHARE % |
+-------------------+--------------+----------+
| Cosmos Hub | $31,739.05 | 29.49% |
| Osmosis | $12,400.00 | 11.52% |
| Solana | $8,750.00 | 8.13% |
| Ethereum | $10,500.00 | 9.76% |
| Polygon | $10,000.00 | 9.29% |
| Fixed Balance | $36,000.00 | 33.45% |
+-------------------+--------------+----------+
Asset Types:
+------------+--------------+----------+
| TYPE | USD VALUE | SHARE % |
+------------+--------------+----------+
| Bank | $15,104.53 | 15.31% |
| Staking | $47,500.00 | 48.15% |
| Rewards | $34.52 | 0.04% |
| Fixed | $36,000.00 | 36.50% |
+------------+--------------+----------+
- Cosmos Ecosystem
- Auto-configuration from Chain Registry
- REST endpoint discovery, caching, and failover
- Bank, staking, and reward balances
- Curated IBC token resolution
- EVM Networks
- Ethereum and compatible chains
- Native token and ERC-20 balances (via Moralis)
- Custom RPC support and response caching
- Solana
- Native SOL via
getBalance - Curated SPL tokens via per-mint queries
- Skips unknown or unpriced mints
- Native SOL via
- Portfolio Analytics
- Real-time USD values (CoinGecko)
- Network and asset-type breakdown
- Green gradient highlighting on summary rows
- 429 / rate limits on Cosmos REST — reduce
cosmos_networksorcosmos_addresses; queries are sequential per chain but public LCD endpoints can still throttle heavy use. - No active REST endpoints found — chain-registry endpoints may be down; retry later or wait for discovery to rotate to another node.
- Missing tokens — only assets with a known symbol mapping and CoinGecko price appear; spam and unknown IBC denoms are intentionally excluded.
- Exchange Support
- Integrate exchanges apis
- Enhancements
- NFT tracking
- DeFi positions
- Solana stake accounts
- Additional L1 blockchains
- CSV export
- Custom grouping
- Database support for snapshots
- Historical snapshots
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests and linting (
make test lint) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request