Chainbase CLI

A command-line interface for the Chainbase Web3 API. Designed for both human use and AI agent automation — outputs JSON by default, with an optional --pretty flag for human-readable format.

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) | | --pretty | Human-readable output | 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.

For AI Agents

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

• JSON output by default — machine-parseable, 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 token price 0xdac17f958d2ee523a2206206994597c13d831ec7 | jq '.data.price')

# Check if command succeeded
if chainbase 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