surf sync                       # Refresh API spec cache — always run first
surf list-operations            # All available commands with params
surf list-operations | grep <domain>  # Filter by domain
surf <command> --help           # Full params, enums, defaults, response schema

Always run surf sync before discovery. Always check --help before calling a command — it shows every flag with its type, enum values, and defaults.

Getting Data

surf market-price --symbol BTC -o json -f body.data
surf wallet-detail --address 0x... -o json -f body.data
surf social-user --handle vitalikbuterin -o json -f body.data

-o json → JSON output
-f body.data → extract just the data array/object (skip envelope)
-f body.data[0] → first item only
-f body.data -r → raw strings, not escaped
-f body.meta → metadata (credits used, pagination info)

Domain Guide

Need	Grep for
Prices, market cap, rankings, fear & greed	`market`
Futures, options, liquidations	`market`
Technical indicators (RSI, MACD, Bollinger)	`market`
On-chain indicators (NUPL, SOPR)	`market`
Wallet portfolio, balances, transfers	`wallet`
DeFi positions (Aave, Compound, etc.)	`wallet`
Twitter/X profiles, posts, followers	`social`
Mindshare, sentiment, smart followers	`social`
Token holders, DEX trades, unlocks	`token`
Project info, DeFi TVL, protocol metrics	`project`
Order books, candlesticks, funding rates	`exchange`
VC funds, portfolios, rankings	`fund`
Transaction lookup, gas prices, SQL	`onchain`
Kalshi binary markets	`kalshi`
Polymarket prediction markets	`polymarket`
Cross-platform prediction metrics	`prediction-market`
News feed and articles	`news`
Cross-domain entity search	`search`
Fetch/parse any URL	`web`

Gotchas

Things --help won't tell you:

Never use -q for search. -q is a global flag (not the --q search parameter). Always use --q (double dash).
Chains require canonical long-form names. eth → ethereum, sol → solana, matic → polygon, avax → avalanche, arb → arbitrum, op → optimism, ftm → fantom, bnb → bsc.
POST endpoints (onchain-sql, onchain-structured-query) take JSON on stdin. Pipe JSON: echo '{"sql":"SELECT ..."}' | surf onchain-sql. Always filter on block_date — it's the partition key.
Ignore --rsh-* internal flags in --help output. Only the command-specific flags matter.

Troubleshooting

Auth errors: Run surf refresh to renew an expired token, or surf login to re-authenticate
Unknown command: Run surf sync to update schema, then surf list-operations to verify
Empty results: Check --help for required params and valid enum values

API Reference

For building apps that call the Surf API directly (without the SDK).

API Conventions

Base URL:  https://api.asksurf.ai/gateway/v1
Auth:      Authorization: Bearer <token>

URL Mapping — command name → API path:

market-price          →  GET /market/price
social-user-posts     →  GET /social/user-posts
onchain-sql           →  POST /onchain/sql

Known domain prefixes: market, wallet, social, token, project, fund, onchain, news, exchange, search, web, kalshi, polymarket, prediction-market.

Response Envelope

{ "data": [...items], "meta": { "credits_used": 1, "cached": false } }

Variants:

Object response (detail endpoints): data is an object, not array
Offset-paginated: meta includes total, limit, offset
Cursor-paginated: meta includes has_more, next_cursor

Reading `--help` Schema Notation

Schema notation	Meaning
`(string)`	string
`(integer format:int64)`	integer
`(number format:double)`	float
`(boolean)`	boolean
`field*:`	required
`field:`	optional
`enum:"a","b","c"`	constrained values
`default:"30d"`	default value
`min:1 max:100`	range constraint

Detecting Pagination from `--help`

Cursor: has --cursor param AND response meta has has_more + next_cursor
Offset: has --limit + --offset params AND response meta has total
None: neither pattern

API Feedback

When a surf command fails, returns confusing results, or the API doesn't support something the user naturally expects, log a suggestion:

mkdir -p ~/.surf/api-feedback

Write one file per issue: ~/.surf/api-feedback/<YYYY-MM-DD>-<slug>.md

# <Short title>

**Command tried:** `surf <command> --flags`
**What the user wanted:** <what they were trying to accomplish>
**What happened:** <error message, empty results, or confusing behavior>

## Suggested API fix

<How the API could change to make this work naturally>

surf

Surf Data API

Setup

CLI Usage

Discovery

More from cyberconnecthq/surf-core

surf-app