Chainbase CLI

A command-line interface for the Chainbase Web3 API. Designed for both human use and AI agent automation — outputs human-readable key-value format by default, with --json for machine-parseable JSON output. Supports x402 pay-per-call micropayments.

Install

npm install -g chainbase-cli

Or run directly with npx:

npx chainbase-cli --help

Quick Start

# Set your API key (get one at https://platform.chainbase.com)
chainbase config set api-key YOUR_API_KEY

# Get latest Ethereum block number
chainbase block latest

# Get USDT price
chainbase token price 0xdac17f958d2ee523a2206206994597c13d831ec7

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

# Query on BSC (chain ID 56)
chainbase token price 0x55d398326f99059fF775485246999027B3197955 --chain 56

Global Options

Option	Description	Default
--chain <id>	Chain ID	1 (Ethereum)
--json	Output raw JSON (for AI agents)	false
--page <n>	Page number	1
--limit <n>	Results per page	20
--x402	Enable x402 payment mode	false

Commands

config — Configuration

chainbase config set api-key <key>       # Set API key
chainbase config set default-chain 137   # Set default chain to Polygon
chainbase config set private-key 0x...   # Set wallet private key (for x402)
chainbase config set payment-mode x402   # Enable x402 payment mode
chainbase config get api-key             # Get a config value
chainbase config list                    # List all config

block — Block Queries

chainbase block latest                  # Latest block number
chainbase block detail 20000000         # Block details by number

tx — Transaction Queries

chainbase tx detail <hash>                        # Transaction by hash
chainbase tx list <address>                        # Account transactions
chainbase tx list <address> --from-block 20000000  # With block range filter

token — Token Queries

chainbase token metadata <contract>                # Token metadata
chainbase token price <contract>                   # Current price
chainbase token price-history <contract> --from <ts> --to <ts>  # Price history
chainbase token holders <contract>                 # All holders
chainbase token top-holders <contract>             # Top holders
chainbase token transfers --contract <addr>        # Transfer history

nft — NFT Queries

chainbase nft metadata <contract> <token_id>       # NFT metadata
chainbase nft collection <contract>                # Collection info
chainbase nft collection-items <contract>          # Items in collection
chainbase nft search "Bored Ape"                   # Search by name
chainbase nft owner <contract> <token_id>          # Current owner
chainbase nft owners <contract>                    # All owners
chainbase nft owner-history <contract> <token_id>  # Owner history
chainbase nft transfers --contract <addr>          # Transfer history
chainbase nft floor-price <contract>               # Floor price
chainbase nft price-history <contract> --from <ts> --to <ts>  # Price history
chainbase nft trending                             # Trending collections
chainbase nft rarity <contract>                    # Rarity scores

balance — Balance & Portfolio

chainbase balance native <address>                 # Native token balance (ETH, BNB, etc.)
chainbase balance tokens <address>                 # ERC20 token balances
chainbase balance nfts <address>                   # NFTs owned
chainbase balance portfolios <address>             # DeFi positions
chainbase balance portfolios <address> --chains 1,137  # Filter by chains

domain — ENS & Space ID

chainbase domain ens <address>                     # ENS domains held by address
chainbase domain ens-resolve vitalik.eth           # Resolve ENS → address
chainbase domain ens-reverse <address>             # Reverse resolve address → ENS
chainbase domain spaceid-resolve <domain>          # Resolve Space ID (BSC)
chainbase domain spaceid-reverse <address>         # Reverse resolve Space ID

contract — Smart Contract

chainbase contract call \
  --address <contract> \
  --function "balanceOf" \
  --abi '[...]' \
  --params '["0x..."]'

sql — SQL Queries

chainbase sql execute "SELECT number FROM ethereum.blocks LIMIT 5"  # Execute async query
chainbase sql status <execution_id>                                 # Check status
chainbase sql results <execution_id>                                # Get results

Supported Chains

Chain	ID	Chain	ID
Ethereum	1	Arbitrum	42161
BSC	56	Optimism	10
Polygon	137	Base	8453
Avalanche	43114	zkSync	324

Authentication

API Key (Traditional)

Get your free API key at Chainbase Platform:

1. Sign up / log in at https://platform.chainbase.com
2. Navigate to the API Keys section in the dashboard
3. Create a new API key and copy it

The API key can be configured in two ways (in priority order):

1. Environment variable: CHAINBASE_API_KEY=xxx chainbase block latest
2. Config file: chainbase config set api-key xxx (stored at ~/.chainbase/config.json, mode 0600)

x402 Payment Mode

x402 is an open standard by Coinbase that enables pay-per-call API access via on-chain USDC micropayments ($0.002 per call). No API key subscription needed — just a wallet with USDC.

Setup:

# Configure your wallet private key
chainbase config set private-key 0x...

# Use x402 for a single command
chainbase --x402 token price 0xdac17f958d2ee523a2206206994597c13d831ec7

# Or enable x402 permanently
chainbase config set payment-mode x402
chainbase token price 0xdac17f958d2ee523a2206206994597c13d831ec7

Private key resolution (in priority order):

1. Environment variable: CHAINBASE_PRIVATE_KEY=0x...
2. Config file: chainbase config set private-key 0x...

Note: x402 supports all Web3 API endpoints. SQL API endpoints (sql execute, sql status, sql results) are not supported in x402 mode.

Output Format

By default, results are displayed in a human-readable key-value format:

$ chainbase token price 0xdac17f958d2ee523a2206206994597c13d831ec7
Price:  1.00007
Symbol:  ZUSDT
Decimals:  0
Updated At:  2025-03-05T19:30:00Z

When using x402 payment mode, transaction details are shown below the result:

$ chainbase --x402 token price 0xdac17f958d2ee523a2206206994597c13d831ec7
Price:  1.00007
Symbol:  ZUSDT

── x402 Payment ──
Tx Hash:   0x57951c54ed9138edc16274238777a3fdf67cc95ec62c74816daeab98f691673e
From:      0xb712b83E1722FE0177a40ce97e4C0637A739f0f9
Network:   base

Use --json for machine-parseable JSON output (recommended for AI agents):

$ chainbase --json token price 0xdac17f958d2ee523a2206206994597c13d831ec7
{"code":0,"message":"ok","data":{"price":1.00007,"symbol":"ZUSDT"}}

For AI Agents

This CLI is designed to be controlled by AI agents. Key features:

• JSON mode — use --json for machine-parseable output, no colors or formatting
• Consistent error format — errors output as {"error":"message"} to stderr
• Discoverable — chainbase --help and chainbase <command> --help list all available commands
• Predictable — every command follows the same pattern: chainbase <group> <action> [args] [options]

Example agent usage:

# Parse output directly
PRICE=$(chainbase --json token price 0xdac17f958d2ee523a2206206994597c13d831ec7 | jq '.data.price')

# Check if command succeeded
if chainbase --json balance native 0x... 2>/dev/null; then
  echo "Success"
fi

Development

git clone https://github.com/chainbase-labs/cli.git
cd cli
npm install
npm run build      # Build
npm test           # Run tests
npm run lint       # Type-check
npm link           # Install globally for local dev

License

ISC