Evm Balance

EVM Balance Skill

Overview

The evm-balance project is a high-performance library and CLI for fetching EVM balances across multiple chains using Multicall3. It supports native and ERC20 token balances, address generation (XPUB, CREATE2), and batch processing.

Key Components:

• SDK (@evm-balance/sdk): Core library for fetching balances.
• CLI (@evm-balance/cli): Command-line interface for easy interaction.
• Contracts: Solidity contracts for Multicall3 interactions.

Project Structure

evm-balance/
├── packages/
│   ├── sdk/              # Core library
│   │   ├── src/
│   │   │   ├── index.ts     # Main exports
│   │   │   ├── types.ts     # TypeScript interfaces
│   │   │   ├── balance.ts   # Balance fetching logic
│   │   │   ├── multicall.ts # Multicall3 encoding/decoding
│   │   │   ├── chains.ts    # Chain utilities
│   │   │   └── utils.ts     # Range parsing, formatting
│   │   └── package.json
│   └── cli/              # CLI tool
│       ├── src/
│       │   └── index.ts     # CLI implementation
│       └── package.json
├── src/                  # Solidity contracts
│   └── Multicall3.sol
├── script/               # Deployment scripts
│   └── DeployTest.s.sol
└── package.json          # Workspace root

CLI Usage

The CLI provides a powerful interface for fetching balances.

Quick Start

# Query multiple chains
evm-balance 0-100 --chain mainnet,optimism,arbitrum --xpub $XPUB

# Query specific tokens
evm-balance 0-100 -c mainnet -t 0xA0b86991...USDC,0xdAC17F9...USDT -X $XPUB

# Filter by minimum balance
evm-balance 0-1000 -c mainnet -t 0xUSDT,0xUSDC --min 0.1

# Output as JSON
evm-balance 0-100 -c mainnet -f json -o balances.json

Common Options

• -c, --chains: Comma-separated chain names or IDs (e.g., mainnet,optimism).
• -t, --tokens: Comma-separated ERC20 token addresses.
• -m, --min: Minimum balance filter.
• -f, --format: Output format (table, json, csv).
• -X, --xpub: Extended public key for BIP-44 address generation.
• --mode: Address generation mode (xpub or factory).

SDK Usage

The SDK allows programmatically fetching balances.

Basic Example

import { createBalanceFetcher, parseRange, mainnet } from "@evm-balance/sdk";

const fetcher = createBalanceFetcher({ chain: mainnet });

const results = await fetcher.fetchBalances({
  config: { chain: mainnet },
  mode: { type: "xpub", xpub: process.env.XPUB! },
  indices: parseRange("0-100"),
  options: {
    tokens: ["0xA0b86991..."], // USDC
    includeNative: true,
  },
});

For detailed API documentation, see [sdk_api.md](references/sdk_api.md).

Development Workflow

Prerequisites

• bun
• foundry (forge, anvil)

Commands

# Install dependencies
bun install

# Build all packages
bun run build

# Run tests
bun run test

# Run Solidity tests (requires Anvil)
bun run test:sol

# Type check
bun run typecheck

# Format code
bun run fmt

Testing with Anvil

# 1. Start Anvil
anvil

# 2. Deploy test contracts
forge script script/DeployTest.s.sol:DeployTest --rpc-url http://127.0.0.1:8545 --broadcast

# 3. Run tests
bun run test

EVM Balance Skills

This skill provides guidance and implementation patterns for fetching EVM balances across multiple chains using the @evm-balance toolkit and Multicall3. It covers both SDK integration and CLI usage.

Features

• High Performance: Fetch native and ERC20 balances using Multicall3 (single RPC call).
• Multi-Chain: Native support for all chains available in viem/chains.
• Dual Address Mode: Support for XPUB (BIP-44) and Factory (CREATE2) derivation.
• Batch Processing: Efficiently query large address ranges with configurable batch sizes.
• Smart Filtering: Filter by minimum balance with correct decimal handling.

Installation

To add this skill to your project, run:

npx skills add melonask/evm-balance-skills

Contents

• `SKILL.md`: Main guide with strategies, quick start, and CLI/SDK overview.
• `references/sdk_api.md`: Detailed API reference for the TypeScript SDK.

Usage

Trigger this skill by asking:

• "How do I fetch balances for a range of addresses?"
• "Query USDC balances on mainnet and optimism using the CLI."
• "Show me how to use the @evm-balance/sdk in my project."
• "How do I filter addresses by minimum balance?"
• "Set up balance fetching for CREATE2 counterfactual addresses."

SDK API Reference

API Reference

createBalanceFetcher(config)

Create a balance fetcher instance.

interface BalanceConfig {
  chain: Chain;
  rpc?: string;
  multicall3Address?: Address;
  batchSize?: number;  // default: 500
  timeout?: number;    // default: 30000
}

BalanceFetcher.fetchBalances(query, onProgress?)

Fetch balances for the given query.

interface BalanceQuery {
  config: BalanceConfig;
  mode: AddressMode;
  indices: number[];
  options?: QueryOptions;
}

interface QueryOptions {
  tokens?: Address[];
  includeNative?: boolean;  // default: true
  minBalance?: string;
}

interface AddressBalance {
  index: number;
  address: Address;
  balances: TokenBalance[];
}

interface TokenBalance {
  token: Address | null;  // null for native
  symbol: string;
  decimals: number;
  raw: bigint;
  formatted: string;
}

parseRange(input)

Parse a range string into an array of indices.

parseRange("5");           // [5]
parseRange("0-10");        // [0, 1, 2, ..., 10]
parseRange("0-5,100,500-505"); // [0, 1, 2, 3, 4, 5, 100, 500, 501, ..., 505]

findChain(nameOrId)

Find a chain by name, ID, or alias.

parseChains(input)

Parse a comma-separated list of chain names/IDs.

Re-exports

For convenience, this package re-exports from @evm-address/sdk:

• createXpubGenerator
• createFactoryGenerator
• indexToSalt
• computeCreationCode