Data API Overview

Surf Data API — crypto market data, on-chain analytics, social signals, and more

About

The Surf Data API provides typed REST endpoints for crypto market data, project analytics, social signals, on-chain queries, and more. All endpoints use credit-based billing with per-request rate limiting.

Base URL: https://api.asksurf.ai/gateway

Parameter Conventions

All endpoints follow a standardized naming scheme.

Asset Identification

Param	Type	Description	Example
symbol	string	Uppercase ticker symbol(s), comma-separated	BTC, ETH,SOL
q	string	Free-text search keyword	bitcoin
id	string	Surf entity UUID for direct lookup	550e8400-...
address	string	On-chain contract or wallet address. Also accepts ENS names (e.g. vitalik.eth)	0xdead...

Time & Aggregation

Param	Type	Description	Example
time_range	string or int	Lookback window	7d, 30d, 365d, max
interval	string	Candlestick / indicator interval	1h, 1d, 1w
granularity	string	Data aggregation granularity	day, block, hour

Filtering & Sorting

Param	Type	Description	Example
chain	string	Blockchain name (canonical long-form only)	ethereum, solana, base
currency	string	Quote currency	usd, eur, btc
metric	string	Metric name (endpoint-specific enum)	nupl, tvl
type	string	Category selector (endpoint-specific enum)	us-btc-spot
sort_by	string	Sort field	volume_24h, market_cap
order	string	Sort direction	asc, desc

Pagination

All list endpoints support:

• limit (int, default: 20, max: 100) — results per page
• offset (int, default: 0) — pagination offset

Supported Chains

Use canonical long-form names only. Short aliases (eth, sol, matic, etc.) are not accepted.

Chain	Value
Ethereum	ethereum
Polygon	polygon
BNB Chain	bsc
Solana	solana
Avalanche	avalanche
Arbitrum	arbitrum
Optimism	optimism
Fantom	fantom
Base	base
Linea	linea
Cyber	cyber

Not all chains are available on every endpoint. Check each endpoint’s chain enum for supported values.

Authentication

All data endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <API_KEY>

Error Responses

All endpoints return errors in a consistent format:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "insufficient credits"
  }
}

HTTP Status	Meaning
400	Bad request — invalid or missing parameters
401	Unauthorized — missing or invalid API key
404	Not found — the requested entity does not exist
422	Validation error — parameter value is out of range or invalid
429	Rate limited — too many requests, retry after the indicated interval
502	Upstream error — a data source is temporarily unavailable

Credits

Each API call costs a certain number of credits. The cost is returned in every response under meta.credits_used. Check your remaining balance via GET /v1/me/credit-balance.