surf-skills — Agent Skills for the Surf Data Platform

Give your AI coding agent direct access to crypto market data, wallet intelligence, prediction markets, and on-chain data — across 40+ blockchains and 200+ data sources.

Full Documentation →

Install

npx skills add asksurf-ai/surf-skills --skill surf

Works with any agent that supports the skills protocol — Claude Code, Codex, and more.

Prerequisites

Install the Surf CLI following the guide at agents.asksurf.ai/docs/cli/introduction

No API key required to start — you get 30 free credits daily. For full access, sign up at agents.asksurf.ai and run:

surf auth --api-key $API_KEY

What It Does

Once installed, your agent can fetch live crypto data just by you asking for it — no endpoints to memorize.

Example prompts your agent will handle:

• "What's the price of ETH?"
• "Show me the top 10 wallets holding AAVE"
• "Get Polymarket odds for the next US election"
• "What's the TVL of Uniswap on Arbitrum?"
• "Show me BTC funding rates across exchanges"

The skill teaches the agent to discover endpoints, use correct parameters, and return structured data — automatically.

Data Coverage

| Domain | What You Can Query | |--------|-------------------| | Market | Prices, rankings, technical indicators (RSI, MACD, Bollinger), fear & greed, liquidations, futures, options, ETFs | | Exchange | Order books, candlesticks, funding rates, long/short ratios, perpetual contracts | | Matching | CEX-DEX matching, market matching | | Wallet | Balances, transfers, DeFi positions, net worth, wallet labels | | Token | Holders, DEX trades, transfers, unlock schedules, tokenomics | | Project | Profiles, DeFi TVL, protocol metrics, DeFi rankings | | Prediction Markets | Polymarket & Kalshi — markets, trades, prices, volume, open interest, rankings | | On-chain | Transaction lookup, SQL queries, gas prices, bridge rankings, yield rankings | | News & Search | Cross-domain entity search, news feed, web fetch | | Fund | VC fund profiles, portfolios, rankings |

CLI Quick Reference

The skill uses the surf CLI under the hood. You can also use it directly:

# Discovery
surf sync                                    # Refresh API spec cache
surf list-operations                         # All available commands
surf list-operations | grep market           # Filter by domain
surf market-price --help                     # Full params and enums

# Fetch data
surf market-price --symbol BTC -o json -f body.data
surf wallet-detail --address 0x... -o json -f body.data
surf project-detail --q uniswap -o json -f body.data

# On-chain SQL
echo '{"sql":"SELECT project, sum(amount_usd) FROM agent.ethereum_dex_trades WHERE block_date = today() - 1 GROUP BY project ORDER BY 2 DESC LIMIT 10"}' | surf onchain-sql

# Robinhood Chain catalog and historical coverage
surf catalog search robinhood
echo '{"sql":"SELECT dataset, coverage_state, complete_through_block, semantic_coverage FROM agent.robinhood_dataset_coverage ORDER BY dataset"}' | surf onchain-sql

Documentation

| Resource | Link | |----------|------| | Full Docs | agents.asksurf.ai/docs | | CLI & Skills Guide | agents.asksurf.ai/docs/cli/introduction | | Data API (100+ endpoints) | agents.asksurf.ai/docs/data-api/overview | | Onchain SQL (cataloged tables) | agents.asksurf.ai/docs/data-catalog/overview |

How It Works

The skill (skills/surf/SKILL.md) is an instruction file that teaches your AI agent to:

1. Run surf sync to refresh the API spec cache
2. Use surf list-operations and surf <command> --help to discover the right endpoint
3. Use -o json -f body.data for structured output
4. Map natural language requests to the correct domain and parameters
5. Handle pagination, chain name conventions, and common gotchas

No code generation needed — the agent calls the CLI directly and returns the data.

Adding New Endpoints

No changes needed in this repo. When a new API endpoint is added upstream:

1. The OpenAPI spec updates automatically
2. surf list-operations shows the new command
3. surf <new-command> --help shows its parameters