Introduction
# Onchain CLI
CLI for crypto portfolio tracking, market data, and CEX history.
## First-Time Setup (Required)
Before using most features, users must configure their API keys:
```bash onchain setup ```
This interactive wizard helps configure: - **Coinbase/Binance** - For CEX balances and trade history - **DeBank** - For EVM wallet data (Ethereum, Polygon, Arbitrum, etc.) - **Helius** - For Solana wallet data
**Without setup**: Only `onchain price` and `onchain markets` work (using free CoinGecko tier).
**Verify setup**: Run `onchain test` to check which providers are configured and working.
**Agent note**: If a command fails with "not configured" or "API key required", guide the user to run `onchain setup` first, then `onchain test` to verify.
## Invocation
``` onchain <command> ```
## Commands
### Market Data
```bash onchain price <token> # Token price (btc, eth, sol, etc.) onchain markets # Market overview with trending onchain search <query> # Search tokens by name or symbol onchain gas # Current gas prices (Ethereum default) onchain gas --chain polygon # Gas prices for other EVM chains ```
### Wallet Data
```bash onchain balance [address] # Token balances (auto-detects EVM/Solana) onchain balance --chain polygon # Filter by chain onchain history [address] # Transaction history onchain portfolio [address] # Full portfolio with DeFi positions ```
### Transaction Lookup
```bash onchain tx <hash> # Lookup transaction details (auto-detects chain) onchain tx <hash> --chain base # Specify chain explicitly onchain tx <explorer-url> # Paste block explorer URL directly ```
Supports EVM chains (Ethereum, Polygon, Base, Arbitrum, Optimism, BSC, Avalanche, Fantom) and Solana. Accepts raw hashes or explorer URLs (etherscan.io, basescan.org, solscan.io, etc.).
#### Example Output ``` Transaction Details
✓ Status: SUCCESS Hash: 0xd757...5f31 Chain: Base Block: 41,310,593 Time: Jan 26, 2026, 01:55 PM (4h ago)
Addresses From: 0xc4e7263dd870a29f1cfe438d1a7db48547b16888 To: 0xab98b760e5ad88521a97c0f87a3f6eef8c42641d
Value & Fee Value: 0 ETH Fee: 3.62e-7 ETH Gas: 96,893 / 249,604 (39%)
Method ID: 0x6a761202
🔗 https://basescan.org/tx/0xd757... ```
**This output contains all available transaction data.** The CLI queries Etherscan/Solscan APIs directly - there is no additional data available from other sources.
### CEX Data
```bash onchain coinbase balance # Coinbase balances onchain coinbase history # Coinbase trade history onchain binance balance # Binance balances onchain binance history # Binance trade history ```
### Prediction Markets
```bash onchain polymarket tags # List all available tags/categories onchain polymarket tags --popular # Show popular tags by market count onchain polymarket trending # Trending markets (respects config filters) onchain polymarket trending --all # Show all markets (ignore config filters) onchain polymarket trending --exclude sports,nfl # Exclude specific tags onchain polymarket trending --include crypto,ai # Only show specific tags onchain polymarket search <query> # Search markets (respects config filters) onchain polymarket view <slug> # View market details onchain polymarket sentiment <topic> # Analyze market sentiment for a topic ```
**Sentiment analysis**: Analyzes prediction markets to determine bullish/bearish expectations: ```bash onchain polymarket sentiment fed # Fed rate expectations onchain polymarket sentiment bitcoin # Bitcoin market sentiment onchain polymarket sentiment ai # AI-related predictions onchain polymarket sentiment trump # Political sentiment onchain polymarket sentiment fed --json # JSON output for agents ```
**Tag filtering**: Configure default excludes in `~/.config/onchain/config.json5`: ```json5 { "polymarket": { "excludeTags": ["sports", "nfl", "nba", "mlb"], "includeTags": [] // empty = all non-excluded } } ```
### Configuration
```bash onchain setup # Interactive setup wizard onchain config # View current config onchain config wallet add <name> <address> onchain config wallet set-default <name> ```
## Global Options
- `--json` - Output as JSON (agent-friendly) - `--plain` - Disable colors and emoji - `--timeout <ms>` - Request timeout
## Configuration
Config file: `~/.config/onchain/config.json5`
### Required API Keys
| Feature | API Key | Get Key | |---------|---------|---------| | EVM wallets | `DEBANK_API_KEY` | [DeBank](https://cloud.debank.com/) | | Solana wallets | `HELIUS_API_KEY` | [Helius](https://helius.xyz/) | | Coinbase CEX | `COINBASE_API_KEY` + `COINBASE_API_SECRET` | [Coinbase](https://www.coinbase.com/settings/api) | | Binance CEX | `BINANCE_API_KEY` + `BINANCE_API_SECRET` | [Binance](https://www.binance.com/en/my/settings/api-management) |
### Optional API Keys
| Feature | API Key | Notes | |---------|---------|-------| | Market data | `COINGECKO_API_KEY` | Free tier works, Pro for higher limits | | Market fallback | `COINMARKETCAP_API_KEY` | Alternative market data source | | EVM tx lookup | `ETHERSCAN_API_KEY` | For `onchain tx` on EVM chains | | Solana tx lookup | `SOLSCAN_API_KEY` | For `onchain tx` on Solana |
## Examples
### Get Bitcoin price ```bash onchain price btc ```
### Check wallet balance ```bash onchain balance 0x1234...5678 ```
### View portfolio with DeFi positions ```bash onchain portfolio main # Uses saved wallet named "main" ```
### Get trending prediction markets ```bash onchain polymarket trending -n 5 # Top 5 (respects config filters) onchain polymarket trending --all # All markets, ignore config onchain polymarket trending --exclude sports # Filter out sports on-the-fly ```
### Lookup a transaction ```bash onchain tx 0xd757e7e4cdb424e22319cbf63bbcfcd4b26c93ebef31d1458ab7d5e986375f31 onchain tx https://basescan.org/tx/0x... # Or paste explorer URL ```
### Search for tokens ```bash onchain search pepe # Find tokens matching "pepe" onchain search "shiba inu" -l 5 # Limit to 5 results ```
### Check gas prices ```bash onchain gas # Ethereum gas prices onchain gas --chain polygon # Polygon gas prices onchain gas --json # JSON output ```
### JSON output for scripts ```bash onchain --json price eth | jq '.priceUsd' ```
## Supported Chains
### EVM (via DeBank) Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Avalanche, Base, zkSync Era, Linea, Scroll, Blast, Mantle, Gnosis, Fantom, Celo, and more.
### Solana (via Helius) Full Solana mainnet support including SPL tokens and NFTs.
## Agent Integration
This CLI is designed for agent use. Key patterns:
1. **Always use `--json`** for programmatic access 2. **Check exit codes** - 0 for success, 1 for error 3. **Use saved wallets** - Configure once with `onchain setup`, reference by name 4. **Rate limiting** - APIs have rate limits, add delays between rapid calls
### Example Agent Usage
```bash # Get portfolio value VALUE=$(onchain --json portfolio main | jq -r '.totalValueUsd')
# Get price with change onchain --json price btc | jq '{price: .priceUsd, change24h: .priceChange24h}'
# Check if market is bullish CHANGE=$(onchain --json markets | jq '.marketCapChange24h')
# Get transaction details as JSON TX=$(onchain --json tx 0x... --chain base) echo $TX | jq '{status: .status, from: .from, to: .to, method: .methodId}' ```
### Transaction Lookup Guidance
**IMPORTANT: Trust the CLI output.** The `onchain tx` command queries Etherscan (EVM) or Solscan (Solana) APIs directly and returns all available data.
**DO NOT:** - Use curl to hit Etherscan/Basescan APIs directly - Use `cast` or other CLI tools as "fallbacks" - Use WebFetch to scrape block explorer websites - Assume the CLI is missing data - it returns everything available
**DO:** - Use `onchain tx <hash>` or `onchain tx <explorer-url>` - Use `--json` for structured data parsing - Interpret the output directly to answer user questions
**Example interpretation:** ```bash onchain tx 0x... --chain base ``` If output shows `Status: SUCCESS`, `From: 0x...`, `To: 0x...`, `Method ID: 0x6a761202` - that's a successful contract interaction. The method ID `0x6a761202` is `execTransaction` (Gnosis Safe). No additional lookups needed.