Skip to main content

​
CLI

​
Install

curl -fsSL https://agent.asksurf.ai/cli/releases/install.sh | sh
This installs the surf binary and sets up the default configuration under ~/.config/surf/.

​
Authenticate

No API key required to get started. Every IP gets 30 free credits per day — just install and start querying. For unlimited access, save your API key: 
# Option 1: persistent (recommended)
surf auth

# Option 2: environment variable
export SURF_API_KEY=your-api-key

​
Discover Commands

surf sync
surf list-operations -g
Inspect any command before using it: 
surf market-price --help
surf wallet-detail --help
surf search-project --help

​
Common Examples

# Market data
surf market-price --symbol BTC

# Wallet intelligence
surf wallet-detail --address 0x1234...

# Social lookup
surf social-user --handle vitalikbuterin

# Project search
surf search-project --q aave
For scripts and agents, use structured output: 
surf market-price --symbol BTC -o json -f body.data
surf wallet-detail --address 0x1234... -o json -f body.data
surf social-user --handle vitalikbuterin -o json -f body.data

​
Command Conventions

PatternRecommendation
FlagsUse kebab-case CLI flags such as --time-range and --token-address
SearchUse --q, not -q, for search parameters
ChainsUse canonical names such as ethereum, solana, base, and arbitrum
DiscoveryPrefer surf <command> --help to inspect enums, defaults, and response fields
Structured outputUse -o json for scripts, tooling, and agent workflows

​
What You Can Query

The CLI covers the same core domains exposed in the Surf Data API:
  • Market data and technical indicators
  • Exchange data such as ticker, order book depth, funding history, and candlesticks
  • Wallet balances, transfers, protocol positions, and net worth
  • Social profiles, posts, followers, and mindshare
  • Project profiles and DeFi metrics
  • Token holders, transfers, DEX trades, and unlock schedules
  • Prediction markets across Polymarket and Kalshi
  • On-chain transaction lookups, structured query, SQL, and gas prices
  • News, web fetch, and unified search