Skip to main content

​
Overview

The Chainbase CLI is a command-line tool for accessing Chainbase Web3 API data directly from your terminal. It outputs JSON by default, making it ideal for scripting, automation, and AI agent integration.
  • Query tokens, balances, transactions, and more across 8+ EVM chains
  • JSON output by default for machine-parseable results
  • Async SQL queries against Chainbase’s on-chain data warehouse
  • Smart contract read calls without writing code

​
Installation

# Global install
npm install -g chainbase-cli

# Or run directly with npx (no install needed)
npx chainbase-cli --help
Requires Node.js >= 18.

​
Configuration

​
Set API Key

Get your API key from the Chainbase Console, then configure: 
# Option 1: Save to config file (~/.chainbase/config.json)
chainbase config set api-key YOUR_API_KEY

# Option 2: Use environment variable
export CHAINBASE_API_KEY=YOUR_API_KEY

​
Set Default Chain

# Set default chain to Ethereum (default)
chainbase config set default-chain 1

# View current config
chainbase config list

​
Supported Chains

Supports all EVM-compatible chains available on Chainbase. See the full list at Supported Networks.

​
Global Options

Every command supports these options:
OptionDescriptionDefault
--chain <id>Chain ID to query1 (or your default-chain)
--prettyHuman-readable formatted outputfalse
--page <n>Page number for paginated results1
--limit <n>Results per page20

​
Commands

​
block — Block Queries

# Get latest block number
chainbase block latest

# Get block details
chainbase block detail 17000000

​
tx — Transaction Queries

# Get transaction by hash
chainbase tx detail 0x...

# List transactions for an address
chainbase tx list 0x... --from-block 17000000 --to-block 17001000

​
token — Token Queries

# Get token metadata
chainbase token metadata 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Get current price
chainbase token price 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Get price history
chainbase token price-history 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --from 1700000000 --to 1700086400

# Get top holders
chainbase token top-holders 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Get token transfers
chainbase token transfers --contract 0x... --from-block 17000000

​
balance — Balance & Portfolio

# Native token balance (ETH, BNB, etc.)
chainbase balance native 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# ERC-20 token balances
chainbase balance tokens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

​
domain — ENS & Space ID

# Get ENS domains held by address
chainbase domain ens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Resolve ENS domain to address
chainbase domain ens-resolve vitalik.eth

# Reverse resolve address to ENS
chainbase domain ens-reverse 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Space ID (BSC) resolution
chainbase domain spaceid-resolve example.bnb
chainbase domain spaceid-reverse 0x...

​
address — Address Labels

# Get labels for an address (exchange, whale, contract, etc.)
chainbase address labels 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

​
contract — Smart Contract Calls

# Call a contract read function
chainbase contract call \
  --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --function "balanceOf" \
  --abi '[{"inputs":[{"name":"account","type":"address"}],"name":"balanceOf","outputs":[{"name":"","type":"uint256"}],"type":"function"}]' \
  --params '["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]'

​
sql — SQL Queries

Execute SQL queries against Chainbase’s on-chain data warehouse. Queries run asynchronously — submit, check status, then retrieve results. 
# Execute a query
chainbase sql execute "SELECT * FROM ethereum.blocks LIMIT 5"

# Check execution status
chainbase sql status <execution_id>

# Get results
chainbase sql results <execution_id>

​
tops — Crypto Social Intelligence

Query crypto social signals from Tops. No API key required. Free to use. Rate limits: 10 req/s · 60 req/min · 600 req/hour (per client IP) 
# List trending crypto topics (default: English)
chainbase tops trending
chainbase tops trending --language zh   # Chinese
chainbase tops trending --language ko   # Korean

# Get structured details for a topic
chainbase tops topic <topic_id>

# Get Twitter/X posts under a topic
chainbase tops posts <topic_id>

# Search narrative candidate topics by keyword
chainbase tops search "RWA"
chainbase tops search "AI Agent"

# Search recent Twitter/X mentions
chainbase tops mentions "Ethereum ETF"
SubcommandDescription
trending [--language <lang>]List trending crypto narratives ranked by heat score (zh/en/ko)
topic <topic_id>Structured details (summary, score, representative posts) for a topic
posts <topic_id>Raw Twitter/X posts under a topic
search <keyword>Find narrative candidate topics by keyword
mentions <keyword>Search recent Twitter/X mentions for a keyword
The topic_id values come from trending or search results. Use --json to get machine-parseable output when piping into other tools.

​
AI Agent Integration

The CLI is designed for AI agent automation with predictable, machine-parseable output:
  • JSON by default — no colors or formatting unless --pretty is used
  • Consistent error format — errors output as {"error":"message"} to stderr
  • Discoverable — run --help on any command for usage info
  • Predictable pattern — chainbase <group> <action> [args] [options]
# Parse output with jq
PRICE=$(chainbase token price 0xdAC17F958D2ee523a2206206994597C13D831ec7 | jq '.data.price')

# Use in scripts
if chainbase balance native 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 2>/dev/null; then
  echo "Query succeeded"
fi

​
Learn More