# ethcli
Comprehensive Ethereum CLI for logs, transactions, accounts, and contracts.
## Build Commands
```bash
# Development build
cargo build
# Release build (optimized)
cargo build --release
# Run tests
cargo test
# Check without building
cargo check
# Format code
cargo fmt
# Lint
cargo clippy
```
## Binary Location
- Debug: `./target/debug/ethcli`
- Release: `./target/release/ethcli`
## Available Commands
### Core Ethereum Commands
```
ethcli logs # Fetch historical logs from contracts
ethcli tx # Analyze transaction(s)
ethcli account # Account operations (balance, transactions, transfers)
ethcli address # Address book (save and lookup addresses by label)
ethcli contract # Contract operations (ABI, source, creation, bytecode analysis)
ethcli token # Token operations (info, holders, balance)
ethcli gas # Gas price oracle and estimates
ethcli sig # Signature lookup (function selectors, event topics)
ethcli simulate # Transaction simulation and tracing
ethcli cast # Type conversions, hashing, encoding
ethcli rpc # Direct RPC calls
ethcli ens # ENS name resolution
ethcli endpoints # Manage RPC endpoints
ethcli config # Manage configuration
ethcli update # Check for updates and self-update
ethcli doctor # Diagnose configuration and connectivity
ethcli completions # Generate shell completions (bash, zsh, fish, powershell)
```
### Aggregation Commands (parallel queries to multiple APIs)
```
ethcli price # Token prices from CoinGecko, DefiLlama, Alchemy, Moralis, Chainlink, Pyth, CCXT
ethcli portfolio # Portfolio balances from Alchemy, Dune SIM, Moralis
ethcli nfts # NFT holdings from Alchemy, CoinGecko, Moralis, Dune SIM
ethcli yields # DeFi yields from DefiLlama and Curve
ethcli quote # Swap quotes from OpenOcean, KyberSwap, 0x, 1inch, CowSwap, LI.FI, Velora, Enso
```
### Direct API Access Commands
```
ethcli tenderly # Tenderly API (vnets, wallets, contracts, alerts, actions)
ethcli alchemy # Alchemy API (NFTs, prices, portfolio, transfers, debug)
ethcli gecko # CoinGecko API (coins, prices, NFTs, exchanges)
ethcli llama # DefiLlama API (TVL, prices, yields, stablecoins)
ethcli moralis # Moralis API (wallet, token, NFT, DeFi, transactions)
ethcli dsim # Dune SIM API (balances, activity, collectibles, DeFi)
ethcli dune # Dune Analytics API (queries, executions, tables)
ethcli curve # Curve Finance API (pools, volumes, lending, tokens, router)
ethcli chainlink # Chainlink price feeds (RPC-based, no API key needed)
ethcli ccxt # Exchange data (Binance, Bitget, OKX, Hyperliquid)
ethcli kong # Yearn Kong API (vaults, strategies, prices, TVL, reports)
ethcli uniswap # Uniswap V2/V3/V4 (on-chain lens + subgraph)
ethcli goplus # GoPlus Security API (token/address/NFT/approval security)
ethcli solodit # Solodit vulnerability database (smart contract security findings)
```
### Direct DEX Aggregator Commands
```
ethcli 1inch # 1inch API (quote, swap, tokens, sources, approvals) - requires API key
ethcli openocean # OpenOcean API (quote, swap, reverse-quote, tokens, dexes)
ethcli kyberswap # KyberSwap API (routes, route-data, build)
ethcli 0x # 0x Protocol API (quote, price, sources)
ethcli cowswap # CowSwap API (quote, orders, trades, auctions) - MEV protected
ethcli lifi # LI.FI API (quote, routes, status, chains, tokens, bridges)
ethcli velora # Velora/ParaSwap API (price, transaction, tokens)
ethcli enso # Enso Finance API (route, price, balances) - requires API key
ethcli pyth # Pyth Network API (price feeds, search, known-feeds)
```
### Security & Token Analysis
```
ethcli blacklist # Token blacklist management (spam/scam filtering)
```
## Bytecode Analysis Commands
Analyze contract bytecode without requiring source code or ABI. Uses evmole for function extraction and evm-disassembler for opcode analysis.
```bash
# Extract function selectors, arguments, and state mutability
ethcli contract selectors 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
ethcli contract sel 0x... --lookup # Lookup signatures from 4byte.directory
# Disassemble bytecode into opcodes
ethcli contract disassemble 0x... --limit 50
ethcli contract dis 0x...
# Get opcode frequency statistics
ethcli contract opcodes 0x...
ethcli contract ops 0x...
# Full security analysis (combines all above)
ethcli contract analyze 0x...
ethcli contract az 0x... --include-disassembly --lookup
# Analyze proxy's implementation contract instead of proxy bytecode
ethcli contract analyze 0x... --follow-proxy
# JSON output
ethcli contract analyze 0x... --format json
```
### Proxy Detection
The analyze command automatically detects proxy contracts:
- **EIP-1167**: Minimal proxy clones (implementation embedded in bytecode)
- **EIP-1967**: Transparent proxies (implementation in storage slot)
- **EIP-1822**: UUPS proxies
- **OpenZeppelin Legacy**: Pre-EIP-1967 patterns
Use `--follow-proxy` to analyze the implementation contract instead of the proxy bytecode.
### Security Patterns Detected
| SELFDESTRUCT | Critical | Contract can be destroyed, potentially locking user funds |
| DELEGATECALL | High | Arbitrary code execution - can modify contract state via external code |
| CALLCODE | High | Deprecated opcode with similar risks to DELEGATECALL |
| ORIGIN | Medium | Uses tx.origin for authorization - honeypot indicator |
| CREATE | Medium | Dynamically creates contracts |
| CREATE2 | Medium | Deterministic contract creation |
### Output Includes
- **Functions**: Selectors, arguments, state mutability (pure/view/nonpayable/payable)
- **Risk Level**: LOW, MEDIUM, HIGH, or CRITICAL based on detected patterns
- **Dangerous Opcodes**: Count of SELFDESTRUCT, DELEGATECALL, CALLCODE
- **Hardcoded Addresses**: Count of PUSH20 operations (embedded addresses)
- **Opcode Statistics**: Frequency of each opcode type
- **Proxy Info**: Detected proxy type and implementation address (if applicable)
### Notes
- No API key required - works directly with RPC bytecode
- Aliases: `sel`, `dis`, `ops`, `az`, `an`
- Works on unverified contracts (no source/ABI needed)
## GoPlus Security Commands
Query the GoPlus Security API for token, address, NFT, and approval security analysis.
```bash
# Check token security (honeypot detection, taxes, ownership)
ethcli goplus token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain-id 1
# Check if address is malicious
ethcli goplus address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain-id 1
# Check NFT collection security
ethcli goplus nft 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d --chain-id 1
# Check ERC20/721/1155 approval security
ethcli goplus approval 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain-id 1
# List supported chains
ethcli goplus chains
# JSON output (use --format or -o)
ethcli goplus token 0x... --chain-id 1 --format json
ethcli goplus token 0x... --chain-id 1 -o ndjson
```
### Notes
- **Free API**: No API key required for basic usage
- **Authenticated mode**: Set `GOPLUS_APP_KEY` and `GOPLUS_APP_SECRET` for batch queries and higher rate limits
- **Alias**: `ethcli gp` works as an alias for `ethcli goplus`
- **Chain IDs**: 1=Ethereum, 56=BSC, 137=Polygon, 42161=Arbitrum, 8453=Base, etc.
## Blacklist Commands
Manage a local token blacklist for filtering spam/scam tokens from portfolio views.
```bash
# Scan a token for security issues
ethcli blacklist scan 0x... --chain ethereum
# Scan entire portfolio for suspicious tokens
ethcli blacklist scan-portfolio 0xYourAddress --chain ethereum --auto-blacklist
# Only show suspicious tokens (skip safe ones)
ethcli blacklist scan-portfolio 0xYourAddress --suspicious-only --auto-blacklist
# List blacklisted tokens
ethcli blacklist list
ethcli blacklist list --links # With Etherscan links
# Add token to blacklist
ethcli blacklist add 0x... --chain ethereum --reason "Honeypot token"
# Remove token from blacklist
ethcli blacklist remove 0x...
# Check if token is blacklisted
ethcli blacklist check 0x...
# Clear all blacklisted tokens
ethcli blacklist clear
```
### Notes
- **Storage**: Blacklist stored in `~/.config/ethcli/blacklist.toml`
- **Security checks**: Uses GoPlus API + Etherscan verification status
- **Known protocols**: Yearn, Curve, Aave, Compound, etc. are auto-whitelisted
- **Alias**: `ethcli bl` works as an alias for `ethcli blacklist`
## Solodit Commands
Search and explore smart contract security vulnerability findings from the Solodit database (by Cyfrin).
```bash
# Search for vulnerability findings
ethcli solodit search "reentrancy"
ethcli sld search "oracle manipulation" --impact HIGH,MEDIUM
ethcli sld search "flash loan" --firm "Trail of Bits" --tag Reentrancy
# Filter by various criteria
ethcli sld search "access control" --protocol "Aave" --language Solidity
ethcli sld search "price" --min-quality 3 --sort quality
# Advanced filtering
ethcli sld search "oracle" --protocol-category DeFi,Bridge
ethcli sld search "reentrancy" --finder "username" --min-finders 1 --max-finders 3
ethcli sld search "flash loan" --reported 30 # Last 30 days
ethcli sld search "access control" --reported-after 2024-01-01 # After specific date
ethcli sld search "price" --min-quality 3 --min-rarity 2
ethcli sld search "oracle" --sort quality --sort-dir asc
# Get a specific finding by slug
ethcli sld get <finding-slug>
ethcli sld get <finding-slug> --format json
# Check API rate limit status
ethcli sld rate-limit
# List common vulnerability tags
ethcli sld tags
# List common audit firms
ethcli sld firms
# Pagination
ethcli sld search "reentrancy" --page 2 --limit 50
```
### Search Filters
| `--impact`, `-i` | Impact level(s) | `--impact HIGH,MEDIUM` |
| `--firm`, `-f` | Audit firm(s) | `--firm "Cyfrin,Sherlock"` |
| `--tag`, `-t` | Vulnerability tag(s) | `--tag Reentrancy,Oracle` |
| `--protocol` | Protocol name (partial) | `--protocol Aave` |
| `--protocol-category` | Protocol category | `--protocol-category DeFi` |
| `--language` | Programming language | `--language Solidity` |
| `--finder` | Auditor handle (partial) | `--finder username` |
| `--min-finders` | Min number of finders | `--min-finders 1` |
| `--max-finders` | Max number of finders | `--max-finders 5` |
| `--reported` | Report period (30/60/90 days) | `--reported 30` |
| `--reported-after` | Reports after date (ISO) | `--reported-after 2024-01-01` |
| `--min-quality` | Min quality score (0-5) | `--min-quality 3` |
| `--min-rarity` | Min rarity score (0-5) | `--min-rarity 2` |
| `--sort` | Sort field | `--sort quality` |
| `--sort-dir` | Sort direction (asc/desc) | `--sort-dir asc` |
| `--page` | Page number | `--page 2` |
| `--limit` | Results per page (max 100) | `--limit 50` |
| `--format`, `-o` | Output format (table, json, ndjson) | `--format json` |
### Notes
- **API key required**: Set `SOLODIT_API_KEY` or use `ethcli config set-solodit <key>`
- **Get API key**: https://solodit.cyfrin.io (Profile > API Keys)
- **Rate limit**: 20 requests per 60 seconds
- **Alias**: `ethcli sld` works as an alias for `ethcli solodit`
- **Impact levels**: HIGH, MEDIUM, LOW, GAS
- **Sort options**: recency (default), quality, rarity
## Simulation Commands
```bash
# Simulate a contract call (uses cast by default)
ethcli simulate call <contract> --sig "balanceOf(address)" <address> --rpc-url https://eth.llamarpc.com
# Simulate with trace (requires debug-capable node)
ethcli simulate call <contract> --sig "transfer(address,uint256)" <to> <amount> --trace
# Trace an existing transaction
ethcli simulate tx <tx_hash> --rpc-url https://eth.llamarpc.com
# Use different backends
ethcli simulate call ... --via cast # Default: uses cast call
ethcli simulate call ... --via anvil # Forks mainnet with Anvil
ethcli simulate call ... --via tenderly # Uses Tenderly API (rich output)
ethcli simulate call ... --via debug # Uses debug_traceCall RPC
ethcli simulate call ... --via trace # Uses trace_call RPC (Erigon/OpenEthereum)
```
## Tenderly Commands
Requires `TENDERLY_ACCESS_KEY` environment variable. Most commands also need `--project` and `--account` flags.
```bash
# Virtual TestNets (VNets)
ethcli tenderly vnets list --project <slug> --account <slug>
ethcli tenderly vnets create --slug <slug> --name "My VNet" --network-id 1 --project <slug> --account <slug>
ethcli tenderly vnets get <vnet-id> --project <slug> --account <slug>
ethcli tenderly vnets delete <vnet-id> --project <slug> --account <slug>
ethcli tenderly vnets delete <id1> <id2> <id3> --project <slug> --account <slug>
ethcli tenderly vnets delete --all --project <slug> --account <slug>
ethcli tenderly vnets rpc <vnet-id> --project <slug> --account <slug>
# VNet Admin RPC - Balance Management
ethcli tenderly vnets admin --vnet <id> set-balance <address> 10eth --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> add-balance <address> 1eth --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> set-erc20-balance --token <token> --wallet <wallet> <amount> --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> set-max-erc20-balance --token <token> --wallet <wallet> --project <slug> --account <slug>
# VNet Admin RPC - Time Manipulation
ethcli tenderly vnets admin --vnet <id> increase-time 3600 --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> set-timestamp <epoch> --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> increase-blocks 10 --project <slug> --account <slug>
# VNet Admin RPC - State Management
ethcli tenderly vnets admin --vnet <id> snapshot --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> revert <snapshot-id> --project <slug> --account <slug>
# VNet Admin RPC - Storage/Code (slot/value accept decimal or hex, auto-padded to 32 bytes)
ethcli tenderly vnets admin --vnet <id> set-storage --address <addr> --slot 0 --value 1 --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> set-code --address <addr> --code <bytecode> --project <slug> --account <slug>
# VNet Admin RPC - Transactions
ethcli tenderly vnets admin --vnet <id> send-tx --from <addr> --to <addr> --value 0x1 --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> get-latest --project <slug> --account <slug>
# VNet Admin RPC - Simulation (tenderly_simulateTransaction / tenderly_simulateBundle)
ethcli tenderly vnets admin --vnet <id> simulate-tx --from <addr> --to <addr> --data 0x... --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> simulate-tx --from <addr> --to <addr> --value 0x1 --block latest --state-overrides '{"0x...":{"balance":"0x..."}}' --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> simulate-bundle '[{"from":"0x...","to":"0x...","data":"0x..."}]' --project <slug> --account <slug>
ethcli tenderly vnets admin --vnet <id> simulate-bundle '[...]' --state-overrides '{"0x...":{"balance":"0x..."}}' --block-overrides '{"number":"0x..."}' --project <slug> --account <slug>
# Virtual Wallets
ethcli tenderly wallets list --project <slug> --account <slug>
ethcli tenderly wallets add <address> --project <slug> --account <slug>
ethcli tenderly wallets get <address> --network 1 --project <slug> --account <slug>
# Contracts
ethcli tenderly contracts list --project <slug> --account <slug>
ethcli tenderly contracts get <address> --network 1 --project <slug> --account <slug>
ethcli tenderly contracts add <address> --network 1 --project <slug> --account <slug>
ethcli tenderly contracts verify <address> --network 1 --name <name> --source <file> --compiler <ver> --project <slug> --account <slug>
# Alerts
ethcli tenderly alerts list --project <slug> --account <slug>
ethcli tenderly alerts create --name "Alert" --alert-type successful_transaction --network 1 --project <slug> --account <slug>
ethcli tenderly alerts delete <alert-id> --project <slug> --account <slug>
ethcli tenderly alerts webhooks list --project <slug> --account <slug>
ethcli tenderly alerts webhooks create --name "Hook" --url https://... --project <slug> --account <slug>
# Web3 Actions
ethcli tenderly actions list --project <slug> --account <slug>
ethcli tenderly actions get <action-id> --project <slug> --account <slug>
ethcli tenderly actions invoke <action-id> --project <slug> --account <slug>
ethcli tenderly actions logs <action-id> --project <slug> --account <slug>
# Networks
ethcli tenderly networks list
ethcli tenderly networks get <network-id>
# Delivery Channels (Slack, Discord, Email, etc.)
ethcli tenderly channels list --project <slug> --account <slug>
ethcli tenderly channels account --project <slug> --account <slug>
ethcli tenderly channels project --project <slug> --account <slug>
# Simulation (alias to ethcli simulate)
ethcli tenderly simulate call <contract> --sig "balanceOf(address)" <args>
```
## Curve Router Commands
The Curve router finds optimal swap routes across Curve pools (local implementation, not REST API).
```bash
# Find swap routes between two tokens
ethcli curve router route <from_token> <to_token> --chain ethereum --limit 5
# Example: DAI to USDC
ethcli curve router route 0x6B175474E89094C44Da98b954EedeAC495271d0F 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
# Get calldata for a swap (to send to router contract)
ethcli curve router encode <from> <to> <amount> <min_out> --chain ethereum
# Show router graph statistics
ethcli curve router stats --chain ethereum
# Get router contract address
ethcli curve router address ethereum
ethcli curve router address polygon
ethcli curve router address arbitrum
```
## Quote Commands
Get swap quotes from multiple DEX aggregators in parallel. Finds the best swap route across OpenOcean, KyberSwap, 0x, 1inch, CowSwap, LI.FI, Velora, and Enso.
```bash
# Get the best quote from all aggregators
ethcli quote best ETH USDC 1000000000000000000 --chain ethereum
# Get quote from a specific aggregator
ethcli quote from openocean ETH USDC 1000000000000000000
ethcli quote from 1inch WETH DAI 1000000000000000000 --chain polygon
# Compare quotes from all aggregators side-by-side
ethcli quote compare ETH USDC 1000000000000000000 --chain ethereum
# Use human-readable amounts with --decimals
ethcli quote best ETH USDC 1.5 --decimals 18 --chain ethereum
# Include transaction data in output
ethcli quote best ETH USDC 1000000000000000000 --show-tx
# Set slippage tolerance (basis points, default 50 = 0.5%)
ethcli quote best ETH USDC 1000000000000000000 --slippage 100
# Provide sender address for more accurate quotes
ethcli quote best ETH USDC 1000000000000000000 --sender 0xYourAddress
# JSON output
ethcli quote compare ETH USDC 1000000000000000000 --format json
```
### Available Sources
| `openocean`, `oo` | OpenOcean | Multi-chain DEX aggregator |
| `kyberswap`, `kyber` | KyberSwap | Dynamic routing |
| `0x`, `zerox` | 0x Protocol | Professional-grade liquidity |
| `1inch`, `oneinch` | 1inch | Pathfinder algorithm |
| `cowswap`, `cow` | CowSwap | MEV-protected trades |
| `li.fi`, `lifi` | LI.FI | Cross-chain aggregator |
| `velora`, `paraswap` | Velora/ParaSwap | Multi-protocol routing |
| `enso`, `ensofi` | Enso Finance | DeFi shortcuts |
### Notes
- **No API keys required** for basic usage (some sources may have higher rate limits with keys)
- **MEV protection**: CowSwap uses batch auctions to protect against MEV
- **Amount format**: Pass raw amounts (wei) or use `--decimals` for human-readable input
- **Chains**: Supports Ethereum, Polygon, Arbitrum, Optimism, Base, and more
## Chainlink Commands
Query Chainlink price feeds via RPC (no API key required). Supports Feed Registry (mainnet) and direct oracle queries (all chains).
```bash
# Get current price (uses Feed Registry on mainnet, direct oracles on L2s)
ethcli chainlink price ETH
ethcli chainlink price CVX
ethcli chainlink price BTC --chain arbitrum
# Historical price at a specific block (requires archive node)
ethcli chainlink price ETH --block 18000000
ethcli chainlink price CVX --block 19500000
# Query a specific oracle address directly
ethcli chainlink price ETH --oracle 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
# Get feed/oracle address for a token
ethcli chainlink feed CVX
ethcli chainlink feed ETH --quote usd
# List known oracle addresses
ethcli chainlink oracles
ethcli chainlink oracles --chain ethereum
ethcli chainlink oracles --chain arbitrum
# Data Streams (requires API credentials)
ethcli chainlink streams feeds
ethcli chainlink streams latest <feed_id>
ethcli chainlink streams report <feed_id> <timestamp>
ethcli chainlink streams bulk <feed_id1>,<feed_id2> <timestamp>
ethcli chainlink streams history <feed_id> <timestamp> --limit 10
```
### Notes
- **Ethereum mainnet**: Uses Feed Registry - supports any token Chainlink has a feed for. Pass token address or symbol.
- **L2 chains**: Uses hardcoded oracle mappings. Run `ethcli chainlink oracles --chain <chain>` to see available feeds.
- **Historical queries**: Require an archive node. Feed address is resolved at the target block for accuracy.
- **Stale detection**: Warns if `answeredInRound < roundId` (oracle hasn't updated recently).
## Kong (Yearn) Commands
Query Yearn Finance vault and strategy data via the Kong GraphQL API. No API key required.
```bash
# List vaults (optionally filtered)
ethcli kong vaults list # All vaults
ethcli kong vaults list --chain-id 1 # Ethereum mainnet vaults
ethcli kong vaults list --chain-id 1 --yearn # Official Yearn vaults only
ethcli kong vaults list --v3 # V3 vaults only
ethcli kong vaults list --erc4626 # ERC4626 compliant vaults
# Get specific vault details
ethcli kong vaults get --chain-id 1 0x7B5A0182E400b241b317e781a4e9dEdFc1429822
# Get user positions in vaults (DEPRECATED - Kong API removed this endpoint in 2024)
# This command returns empty results. Use `ethcli portfolio` for vault positions instead.
# ethcli kong vaults accounts --chain-id 1 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# List strategies
ethcli kong strategies list --chain-id 1
ethcli kong strategies list --vault 0x... # Strategies for specific vault
ethcli kong strategies get --chain-id 1 0x... # Get strategy details
# Token prices (contract addresses only)
ethcli kong prices current --chain-id 1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
ethcli kong prices historical --chain-id 1 0x... 1700000000 # At timestamp
# TVL data
ethcli kong tvl current --chain-id 1 0x...
ethcli kong tvl history --chain-id 1 0x... --period day --limit 30
# Vault/strategy reports (harvests)
ethcli kong reports vault --chain-id 1 0x...
ethcli kong reports strategy --chain-id 1 0x...
```
### Notes
- **Chain IDs**: 1=Ethereum, 137=Polygon, 42161=Arbitrum, 10=Optimism, 8453=Base
- **Alias**: `ethcli yearn` works as an alias for `ethcli kong`
- **No API key**: Kong API is free and public
## Alchemy Commands
Direct access to Alchemy API. Requires `ALCHEMY_API_KEY` environment variable.
```bash
# NFT queries
ethcli alchemy nfts 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
ethcli alchemy nft-metadata 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1
# Token data
ethcli alchemy balances 0x...
ethcli alchemy token-metadata 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
# Transfers
ethcli alchemy transfers 0x... --category erc20
# Debug traces
ethcli alchemy trace-tx 0x...
```
## Gecko (CoinGecko) Commands
Direct access to CoinGecko API. Optional `COINGECKO_API_KEY` for Pro API (higher rate limits).
```bash
# Coin data
ethcli gecko coin bitcoin
ethcli gecko coin ethereum --format json
# Price queries
ethcli gecko price bitcoin,ethereum --vs usd,eur
ethcli gecko price-history bitcoin --days 30
# Market data
ethcli gecko markets --vs usd --per-page 100
ethcli gecko trending
# NFT data
ethcli gecko nft-collection boredapeyachtclub
# Exchanges
ethcli gecko exchanges
ethcli gecko exchange binance
```
## Llama (DefiLlama) Commands
Direct access to DefiLlama API. Optional `DEFILLAMA_API_KEY` for Pro endpoints.
```bash
# TVL data
ethcli llama tvl aave
ethcli llama protocols
ethcli llama chains
# Prices
ethcli llama price ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
ethcli llama prices ethereum:0x...,ethereum:0x...
ethcli llama price-history ethereum:0x... --period 1d
# Yields
ethcli llama yields
ethcli llama yields --chain ethereum --project aave
# Stablecoins
ethcli llama stablecoins
ethcli llama stablecoin-history tether
```
## Moralis Commands
Direct access to Moralis API. Requires `MORALIS_API_KEY` environment variable.
```bash
# Wallet data
ethcli moralis balance 0x...
ethcli moralis tokens 0x...
ethcli moralis transactions 0x...
ethcli moralis transfers 0x...
# NFT data
ethcli moralis nfts 0x...
ethcli moralis nft-metadata 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1
# Token data
ethcli moralis token-price 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
ethcli moralis token-metadata 0x...
# DeFi positions
ethcli moralis defi-positions 0x...
```
## Dsim (Dune SIM) Commands
Direct access to Dune SIM API. Requires `DUNE_SIM_API_KEY` environment variable.
```bash
# Wallet simulation
ethcli dsim balances 0x...
ethcli dsim activity 0x...
ethcli dsim collectibles 0x...
ethcli dsim defi 0x...
```
## Dune Commands
Direct access to Dune Analytics API. Requires `DUNE_API_KEY` environment variable.
```bash
# Run queries
ethcli dune query 1234567
ethcli dune query 1234567 --params '{"address": "0x..."}'
# Get results
ethcli dune results 1234567
ethcli dune results 1234567 --format csv
# Executions
ethcli dune execute 1234567
ethcli dune status <execution-id>
# Tables
ethcli dune tables --namespace dune
```
## Curve Commands
Direct access to Curve Finance API. No API key required.
```bash
# Pool data
ethcli curve pools
ethcli curve pools --chain ethereum
ethcli curve pool 0x...
# Volume and TVL
ethcli curve volumes
ethcli curve tvl
# Lending
ethcli curve lending-pools
ethcli curve lending-pool 0x...
# Token data
ethcli curve tokens
ethcli curve token 0x...
```
## CCXT Commands
Query cryptocurrency exchanges via CCXT. No API key required for public data.
```bash
# Ticker data
ethcli ccxt ticker binance BTC/USDT
ethcli ccxt ticker okx ETH/USDT
# Order book
ethcli ccxt orderbook binance BTC/USDT --limit 10
# OHLCV candles
ethcli ccxt ohlcv binance BTC/USDT --timeframe 1h --limit 100
# Exchange info
ethcli ccxt exchanges
ethcli ccxt markets binance
# Multiple exchanges
ethcli ccxt ticker bitget,hyperliquid BTC/USDT
```
### Supported Exchanges
Binance, Bitget, OKX, Hyperliquid, and many more via CCXT library.
## Direct DEX Aggregator Commands
### 1inch Commands
Direct access to 1inch DEX Aggregator API. Requires `ONEINCH_API_KEY` or `1INCH_API_KEY`.
```bash
# Get swap quote
ethcli 1inch quote <src> <dst> <amount> --chain-id 1 --include-gas
# Get swap transaction data
ethcli 1inch swap <src> <dst> <amount> <from> --chain-id 1 --slippage 1
# Get supported tokens and sources
ethcli 1inch tokens --chain-id 1
ethcli 1inch sources --chain-id 1
# Approvals
ethcli 1inch spender --chain-id 1
ethcli 1inch allowance <token> <wallet> --chain-id 1
ethcli 1inch approve <token> --chain-id 1
```
**Alias**: `ethcli oneinch`
### OpenOcean Commands
Direct access to OpenOcean DEX Aggregator API. No API key required.
```bash
# Get swap quote
ethcli openocean quote <in_token> <out_token> <amount> --chain ethereum --slippage 1
# Get swap transaction
ethcli openocean swap <in_token> <out_token> <amount> <account> --chain ethereum
# Get reverse quote
ethcli openocean reverse-quote <in_token> <out_token> <out_amount> --chain ethereum
# List tokens and DEXes
ethcli openocean tokens --chain ethereum
ethcli openocean dexes --chain ethereum
```
**Alias**: `ethcli oo`
### KyberSwap Commands
Direct access to KyberSwap Aggregator API. No API key required.
```bash
# Get optimal routes
ethcli kyberswap routes <token_in> <token_out> <amount_in> --chain ethereum
# Get route with full data
ethcli kyberswap route-data <token_in> <token_out> <amount_in> --chain ethereum
# Build swap transaction
ethcli kyberswap build <token_in> <token_out> <amount_in> <sender> <recipient> \
--chain ethereum --slippage-bps 50 --route-summary '<json>'
```
**Alias**: `ethcli kyber`
### 0x Protocol Commands
Direct access to 0x API. Optional `ZEROX_API_KEY` or `0X_API_KEY` for higher limits.
```bash
# Get swap quote with tx data
ethcli 0x quote <sell_token> <buy_token> <sell_amount> <taker> --chain ethereum --slippage-bps 100
# Get price estimate (lighter)
ethcli 0x price <sell_token> <buy_token> <sell_amount> <taker> --chain ethereum
# Get liquidity sources
ethcli 0x sources --chain ethereum
```
**Alias**: `ethcli zerox`
### CowSwap Commands
Direct access to CoW Protocol API for MEV-protected trading. No API key required.
```bash
# Get MEV-protected quote
ethcli cowswap quote <sell_token> <buy_token> <amount> <from> --chain ethereum --kind sell
# Order and trade queries
ethcli cowswap order <uid> --chain ethereum
ethcli cowswap orders <owner> --chain ethereum
ethcli cowswap trades <owner> --chain ethereum
ethcli cowswap order-trades <uid> --chain ethereum
# Auction data
ethcli cowswap auction --chain ethereum
ethcli cowswap competition <auction_id> --chain ethereum
# Get native token price
ethcli cowswap native-price <token> --chain ethereum
```
**Alias**: `ethcli cow`
### LI.FI Commands
Direct access to LI.FI cross-chain aggregator API. Optional `LIFI_INTEGRATOR` for analytics.
```bash
# Cross-chain quote
ethcli lifi quote <from_chain> <from_token> <to_chain> <to_token> <amount> <from_address>
# Routes
ethcli lifi routes <from_chain> <from_token> <to_chain> <to_token> <amount> <from_address>
ethcli lifi best-route <from_chain> <from_token> <to_chain> <to_token> <amount> <from_address>
# Transaction status
ethcli lifi status <tx_hash> --from-chain 1 --to-chain 137
# Discovery
ethcli lifi chains
ethcli lifi chain <chain_id>
ethcli lifi tokens --chain-id 1
ethcli lifi tools
ethcli lifi bridges
ethcli lifi exchanges
ethcli lifi gas <chain_id>
ethcli lifi connections --from-chain 1 --to-chain 137
```
**Alias**: `ethcli li.fi`
### Velora (ParaSwap) Commands
Direct access to ParaSwap API. Optional `PARASWAP_API_KEY` or `VELORA_API_KEY` for higher limits.
```bash
# Get swap price/route
ethcli velora price <src_token> <dest_token> <amount> --chain ethereum --side SELL
# Build swap transaction
ethcli velora transaction <user_address> --chain ethereum --slippage 100 --price-route '<json>'
# List tokens
ethcli velora tokens --chain ethereum
```
**Alias**: `ethcli paraswap`
### Enso Finance Commands
Direct access to Enso Finance DeFi aggregator API. Requires `ENSO_API_KEY`.
```bash
# Get DeFi route
ethcli enso route <token_in> <token_out> <amount_in> <from_address> --chain-id 1 --slippage 50
# Get token price
ethcli enso price <token> --chain-id 1
# Get balances
ethcli enso balances <address> --chain-id 1
```
### Pyth Network Commands
Direct access to Pyth Network Hermes API. No API key required.
```bash
# Get latest prices
ethcli pyth price BTC/USD
ethcli pyth price ETH SOL AVAX
# Search for feeds
ethcli pyth search "BTC"
# List feeds
ethcli pyth feeds
ethcli pyth feeds --asset-type crypto
ethcli pyth known-feeds
```
**Notes**:
- Supports common symbols: BTC, ETH, SOL, USDC, USDT, DAI, AVAX, ARB, OP, LINK, UNI, AAVE, CRV, CVX, etc.
## Uniswap Commands
Query Uniswap V2, V3, and V4 pools via on-chain lens queries and The Graph subgraph.
```bash
# On-chain queries (no API key needed)
ethcli uniswap pool 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 # Get V3 pool state
ethcli uniswap liquidity 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 # Get pool liquidity
ethcli uniswap balance <token> <account> # Get token balance
# Subgraph queries (requires THEGRAPH_API_KEY)
ethcli uniswap eth-price # Current ETH price
ethcli uniswap eth-price --version v2 # From V2 subgraph
ethcli uniswap top-pools 10 # Top 10 pools by TVL
ethcli uniswap top-pools 20 --version v4 # Top V4 pools
ethcli uniswap swaps 0x... --limit 20 # Recent swaps for a pool
ethcli uniswap day-data 0x... --days 7 # Daily data for a pool
# LP positions (subgraph, queries all versions by default)
ethcli uniswap positions 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
ethcli uniswap positions <address> --version v3 --chain arbitrum
ethcli uniswap positions <address> --format json # JSON output
# List well-known addresses
ethcli uniswap addresses # All factories, pools, tokens
ethcli uniswap addresses --factories # Only factories
ethcli uniswap addresses --pools --version v3 # Only V3 pools
```
### Notes
- **Alias**: `ethcli uni` works as an alias for `ethcli uniswap`
- **On-chain queries**: Use `pool`, `liquidity`, `balance` - no API key needed
- **Subgraph queries**: Use `eth-price`, `top-pools`, `swaps`, `day-data`, `positions` - requires `THEGRAPH_API_KEY`
- **Multi-chain**: Supports Ethereum, Arbitrum, Optimism, Polygon, Base
- **Multi-version**: Supports V2, V3, and V4 protocols
## Project Structure
```
src/
├── main.rs # CLI entry point (clap)
├── lib.rs # Library exports
├── error.rs # Error types (thiserror)
├── fetcher.rs # Main LogFetcher coordinator
├── checkpoint.rs # Resume/checkpoint system
├── proxy.rs # Proxy rotation support
├── tx/
│ ├── mod.rs # Transaction analysis module
│ ├── addresses.rs # Address extraction from traces
│ ├── analyzer.rs # Transaction analyzer
│ ├── flow.rs # Token flow analysis
│ └── types.rs # Transaction types
├── config/
│ ├── mod.rs # Config structs, builder pattern
│ ├── addressbook.rs # Address book storage
│ ├── chain.rs # Chain enum (Ethereum, Polygon, etc.)
│ ├── endpoint.rs # EndpointConfig
│ └── file.rs # TOML config file handling
├── rpc/
│ ├── mod.rs
│ ├── endpoint.rs # Single RPC endpoint wrapper (alloy)
│ ├── pool.rs # RPC pool with parallel requests
│ ├── health.rs # Endpoint health tracking
│ ├── multicall.rs # Multicall batching
│ ├── optimizer.rs # Request optimization
│ ├── retry.rs # Retry logic
│ └── selector.rs # Endpoint selection
├── abi/
│ ├── mod.rs
│ ├── parser.rs # Event signature parser
│ ├── fetcher.rs # Etherscan ABI fetcher (v2 API)
│ └── decoder.rs # Log decoder (alloy dyn-abi)
├── output/
│ ├── mod.rs # OutputWriter trait
│ ├── json.rs # JSON/NDJSON output
│ ├── csv.rs # CSV output
│ └── sqlite.rs # SQLite output
├── bytecode/ # Bytecode analysis (evmole, evm-disassembler)
│ ├── mod.rs # Module exports
│ ├── types.rs # ExtractedFunction, OpcodeStats, SecurityAnalysis, etc.
│ ├── selectors.rs # Function selector extraction (evmole wrapper)
│ ├── disassemble.rs # Opcode disassembly (evm-disassembler wrapper)
│ ├── security.rs # Security pattern detection (SELFDESTRUCT, DELEGATECALL, etc.)
│ └── analyze.rs # Combined bytecode analysis
├── chainlink/ # Chainlink price feed queries
│ ├── mod.rs # Public exports, fetch_price(), fetch_price_at_block()
│ ├── types.rs # PriceData, ChainlinkError
│ ├── constants.rs # Feed Registry, denominations, oracle addresses
│ ├── registry.rs # Feed Registry queries (mainnet only)
│ └── aggregator.rs # Direct AggregatorV3 queries (all chains)
├── etherscan/
│ ├── mod.rs # Etherscan client wrapper
│ ├── client.rs # Extended Etherscan API client
│ └── cache.rs # Signature caching
├── utils/
│ ├── mod.rs # Shared utility functions
│ ├── format.rs # Number/token formatting
│ └── address.rs # Address resolution utilities
├── aggregator/ # Multi-source data aggregation
│ ├── mod.rs # Core types (SourceResult, AggregatedResult)
│ ├── normalize.rs # Data normalization across APIs
│ ├── chain_map.rs # Chain name normalization
│ ├── price.rs # Price fetching and aggregation
│ ├── portfolio.rs # Portfolio aggregation
│ ├── nft.rs # NFT aggregation
│ └── yields.rs # DeFi yield aggregation
└── cli/
├── mod.rs # CLI command structure
├── logs.rs # Log fetching arguments
├── tx.rs # Transaction analysis args
├── account.rs # Account commands
├── address.rs # Address book commands
├── cast.rs # Type conversions, hashing, encoding
├── config.rs # Config management
├── contract.rs # Contract commands
├── doctor.rs # Diagnostics and health checks
├── endpoints.rs # Endpoint management
├── ens.rs # ENS name resolution
├── gas.rs # Gas oracle commands
├── rpc.rs # Direct RPC calls
├── sig.rs # Signature lookup commands
├── simulate/ # Transaction simulation (multiple backends)
├── tenderly.rs # Tenderly API commands
├── token.rs # Token commands
├── update.rs # Self-update from GitHub
├── price.rs # Aggregated price command
├── portfolio.rs # Aggregated portfolio command
├── nfts.rs # Aggregated NFT command
├── yields.rs # Aggregated yields command
├── alchemy.rs # Direct Alchemy API
├── gecko.rs # Direct CoinGecko API
├── llama.rs # Direct DefiLlama API
├── moralis.rs # Direct Moralis API
├── dsim.rs # Direct Dune SIM API
├── dune_cli.rs # Direct Dune Analytics API
├── curve.rs # Direct Curve Finance API
├── chainlink.rs # Chainlink price feeds (RPC + Data Streams)
├── ccxt.rs # Exchange data via CCXT
├── kong.rs # Direct Yearn Kong API
├── uniswap.rs # Uniswap V2/V3/V4 queries
├── goplus.rs # GoPlus Security API (token/address/NFT/approval)
├── solodit.rs # Solodit vulnerability database
├── blacklist.rs # Token blacklist management
├── oneinch.rs # Direct 1inch DEX Aggregator API
├── openocean.rs # Direct OpenOcean DEX Aggregator API
├── kyber.rs # Direct KyberSwap Aggregator API
├── zerox.rs # Direct 0x Protocol API
├── cowswap.rs # Direct CowSwap/CoW Protocol API
├── lifi.rs # Direct LI.FI Cross-Chain API
├── velora.rs # Direct Velora/ParaSwap API
├── enso.rs # Direct Enso Finance API
└── pyth.rs # Direct Pyth Network Price Feeds API
```
## Key Dependencies
- **alloy 1.0**: Ethereum provider, types, ABI decoding
- **evmole**: Function selector extraction from bytecode
- **evm-disassembler**: EVM opcode disassembly
- **foundry-block-explorers**: Etherscan API client
- **chainlink-data-streams-sdk**: Chainlink Data Streams API (optional, requires API key)
- **pyth**: Pyth Network Hermes API client (no API key needed)
- **tndrly**: Tenderly API client
- **alcmy**: Alchemy API client
- **gecko**: CoinGecko API client
- **llama**: DefiLlama API client
- **mrls**: Moralis API client
- **dsim**: Dune SIM API client
- **dune**: Dune Analytics API client
- **crv**: Curve Finance API client
- **ykong**: Yearn Kong GraphQL API client
- **unswp**: Uniswap V2/V3/V4 client (on-chain lens + subgraph)
- **gplus**: GoPlus Security API client
- **sldt**: Solodit vulnerability database client
- **ccxt-rust**: Cryptocurrency exchange data via CCXT
- **tokio**: Async runtime
- **clap**: CLI parsing
- **serde/serde_json**: Serialization
- **rusqlite**: SQLite output
- **indicatif**: Progress bars
## Testing Locally
```bash
# Fetch USDC Transfer events (small range)
ethcli logs -c 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
-e "Transfer(address,address,uint256)" \
-f 21500000 -t 21500010
# Analyze a transaction
ethcli tx 0x123abc...
# Get account balance
ethcli account balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Get recent transactions for an address
ethcli account txs 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Get contract ABI
ethcli contract abi 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
# Get verified source code
ethcli contract source 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
# Lookup function selector
ethcli sig fn 0xa9059cbb
# Get gas prices
ethcli gas oracle
# Get token info
ethcli token info 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
# List available RPC endpoints
ethcli endpoints list
# Test a specific RPC endpoint
ethcli endpoints test https://eth.llamarpc.com
# Aggregated price from all sources
ethcli price ETH
ethcli price 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum
# Aggregated portfolio
ethcli portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Aggregated NFTs
ethcli nfts 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# DeFi yields
ethcli yields --protocol aave
# Chainlink price feeds (RPC-based, no API key)
ethcli chainlink price ETH
ethcli chainlink price CVX --chain ethereum
ethcli chainlink oracles --chain arbitrum
```
## Environment Variables
**Note:** Some services have similar-named keys that serve different purposes:
- `DUNE_API_KEY` (Dune Analytics queries) vs `DUNE_SIM_API_KEY` (Dune SIM wallet simulation)
- `CHAINLINK_API_KEY` + `CHAINLINK_USER_SECRET` are only for Data Streams (premium), not needed for RPC-based price feeds
| `ETHERSCAN_API_KEY` | Optional | Increases Etherscan rate limit |
| `TENDERLY_ACCESS_KEY` | `ethcli tenderly` | Tenderly API access |
| `ALCHEMY_API_KEY` | `ethcli alchemy`, `--via alcmy` | Alchemy API access |
| `COINGECKO_API_KEY` | Optional | CoinGecko Pro API (increases rate limit) |
| `DEFILLAMA_API_KEY` | Optional | DefiLlama Pro endpoints |
| `MORALIS_API_KEY` | `ethcli moralis` | Moralis API access |
| `DUNE_SIM_API_KEY` | `ethcli dsim` | Dune SIM wallet simulation |
| `DUNE_API_KEY` | `ethcli dune` | Dune Analytics queries |
| `CHAINLINK_API_KEY` | `chainlink streams` only | Data Streams API key |
| `CHAINLINK_USER_SECRET` | `chainlink streams` only | Data Streams secret |
| `THEGRAPH_API_KEY` | Uniswap subgraph | The Graph API access |
| `GOPLUS_APP_KEY` | Optional | GoPlus batch queries (>1 token) |
| `GOPLUS_APP_SECRET` | Optional | GoPlus batch queries (>1 token) |
| `SOLODIT_API_KEY` | `ethcli solodit` | Solodit vulnerability database |
| `ONEINCH_API_KEY` / `1INCH_API_KEY` | `ethcli 1inch` | 1inch DEX Aggregator (required) |
| `ZEROX_API_KEY` / `0X_API_KEY` | Optional | 0x Protocol (higher rate limits) |
| `LIFI_INTEGRATOR` | Optional | LI.FI analytics tracking |
| `PARASWAP_API_KEY` / `VELORA_API_KEY` | Optional | Velora/ParaSwap (higher rate limits) |
| `ENSO_API_KEY` | `ethcli enso` | Enso Finance (required) |
## Release Process
**Automated with release-please:**
- Use [Conventional Commits](https://www.conventionalcommits.org/) in commit messages
- `feat:` - triggers minor version bump
- `fix:` - triggers patch version bump
- `feat!:` or `BREAKING CHANGE:` - triggers major version bump
- Release-please creates a PR with version bump and CHANGELOG
- Merging the PR triggers binary builds for all platforms
**Manual release (alternative):**
```bash
git tag v0.x.x
git push origin v0.x.x
```
## Pre-commit Hooks
Installed hooks run automatically on commit:
- `cargo fmt --check` - formatting check
- `cargo clippy -- -D warnings` - lint check
## Architecture Notes
- Uses user-configured RPC endpoints (add with `ethcli endpoints add <url>`)
- **Archive node routing**: Historical queries prefer archive nodes when configured
- Parallel requests with automatic failover on errors
- Health tracking disables failing endpoints temporarily
- Checkpoint system allows resuming interrupted fetches
- Etherscan API v2 for ABI fetching (works without API key, rate limited)
- foundry-block-explorers for account, contract, token, and gas commands
- **Block numbers**: Accept both decimal (`17382257`) and hex (`0x1093b71`) format
### Endpoint Management
```bash
# Add endpoints with node type for proper archive routing
ethcli endpoints add https://my-archive.com --node-type archive
ethcli endpoints add https://my-node.com --node-type full --has-debug --priority 10
# Node types: archive (full history), full (recent only), unknown (default)
# Historical queries (old blocks) automatically prefer archive nodes if configured
```