Find anything across Surf's data universe. Search for crypto projects, X (Twitter) accounts and posts, news articles, wallet addresses, web pages, investment funds, airdrop opportunities, and prediction market events — all from a single unified search interface.
openapi: 3.1.0
info:
contact:
email: backend@cybertinolab.com
name: Cyber team
description: "Surf data API gateway providing typed 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.\n\n## Parameter Naming Conventions\n\nAll endpoints follow a standardized naming scheme. Use these canonical names when calling the API.\n\n### Asset Identification\n\n| Param | Type | Description | Example |\n|-------|------|-------------|---------|\n| `symbol` | string | Uppercase ticker symbol(s), comma-separated | `BTC`, `ETH,SOL` |\n| `q` | string | Free-text search keyword | `bitcoin` |\n| `id` | string | Surf entity UUID for direct lookup | `550e8400-...` |\n| `address` | string | On-chain contract or wallet address. Also accepts ENS names (e.g. `vitalik.eth`) which resolve automatically. | `0xdead...`, `vitalik.eth` |\n\n### Time & Aggregation\n\n| Param | Type | Description | Example |\n|-------|------|-------------|---------|\n| `time_range` | string or int | Lookback window | `7d`, `30d`, `365d`, `max` |\n| `interval` | string | Candlestick / indicator interval | `1h`, `1d`, `1w` |\n| `granularity` | string | Data aggregation granularity | `day`, `block`, `hour` |\n\n### Filtering & Sorting\n\n| Param | Type | Description | Example |\n|-------|------|-------------|---------|\n| `chain` | string | Blockchain name (canonical long-form only) | `ethereum`, `solana`, `base` |\n| `currency` | string | Quote currency | `usd`, `eur`, `btc` |\n| `metric` | string | Metric name (endpoint-specific enum) | `nupl`, `tvl` |\n| `type` | string | Category selector (endpoint-specific enum) | `us-btc-spot` |\n| `sort` | string | Sort direction | `asc`, `desc` |\n\n### Pagination\n\nAll list endpoints support:\n- `limit` (int, default: 20, max: 100) — results per page\n- `offset` (int, default: 0) — pagination offset\n\n### Supported Chains\n\nUse canonical long-form names only. Short aliases (eth, sol, matic, etc.) are **not accepted**.\n\n| Chain | Value |\n|-------|-------|\n| Ethereum | `ethereum` |\n| Polygon | `polygon` |\n| BNB Chain | `bsc` |\n| Solana | `solana` |\n| Avalanche | `avalanche` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Fantom | `fantom` |\n| Base | `base` |\n| Linea | `linea` |\n| Cyber | `cyber` |\n\nNot all chains are available on every endpoint. Check each endpoint's `chain` enum for supported values.\n\n## Authentication\n\nAll data endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer <API_KEY>\n```\n\n## Error Responses\n\nAll endpoints return errors in a consistent format:\n\n```json\n{\n \"error\": {\n \"code\": \"FORBIDDEN\",\n \"message\": \"insufficient credits\"\n }\n}\n```\n\n| HTTP Status | Meaning |\n|-------------|---------|\n| `400` | Bad request — invalid or missing parameters |\n| `401` | Unauthorized — missing or invalid API key |\n| `404` | Not found — the requested entity does not exist |\n| `422` | Validation error — parameter value is out of range or invalid |\n| `429` | Rate limited — too many requests, retry after the indicated interval |\n| `502` | Upstream error — a data source is temporarily unavailable |\n\n## Credits\n\nEach 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`.\n"
title: Hermod DEX Search API
version: sha-80d3407
servers:
- url: /
tags:
- description: Find anything across Surf's data universe. Search for crypto projects, X (Twitter) accounts and posts, news articles, wallet addresses, web pages, investment funds, airdrop opportunities, and prediction market events — all from a single unified search interface.
name: Search
paths:
/gateway/v1/search/airdrop:
get:
description: 'Searches and filters airdrop opportunities.
**Filters:** keyword, status, reward type, task type.
Returns paginated results with optional task details.'
operationId: search-airdrop
parameters:
- description: Search keyword for coin name
explode: false
in: query
name: q
schema:
description: Search keyword for coin name
examples:
- airdrop
maxLength: 100
type: string
- description: Comma-separated lifecycle phases. `active` = tasks open, can participate (POTENTIAL + CONFIRMED). `claimable` = eligible, can claim (SNAPSHOT + VERIFICATION + REWARD_AVAILABLE). `completed` = done (DISTRIBUTED). Defaults to `active,claimable` to show actionable airdrops.
explode: false
in: query
name: phase
schema:
default: active,claimable
description: Comma-separated lifecycle phases. `active` = tasks open, can participate (POTENTIAL + CONFIRMED). `claimable` = eligible, can claim (SNAPSHOT + VERIFICATION + REWARD_AVAILABLE). `completed` = done (DISTRIBUTED). Defaults to `active,claimable` to show actionable airdrops.
examples:
- active
type: string
- description: Filter by reward type
explode: false
in: query
name: reward_type
schema:
description: Filter by reward type
enum:
- airdrop
- points
- whitelist
- nft
- role
- ambassador
examples:
- airdrop
type: string
- description: Filter activities containing tasks of this type
explode: false
in: query
name: task_type
schema:
description: Filter activities containing tasks of this type
enum:
- social
- bounty-platforms
- testnet
- mainnet
- role
- form
- liquidity
- mint-nft
- game
- trading
- staking
- depin
- node
- ambassador
- hold
- check-wallet
- mint-domain
- predictions
- deploy
examples:
- social
type: string
- description: Only return activities with currently OPEN tasks
explode: false
in: query
name: has_open
schema:
default: false
description: Only return activities with currently OPEN tasks
examples:
- true
type: boolean
- description: Field to sort results by
explode: false
in: query
name: sort_by
schema:
default: last_status_update
description: Field to sort results by
enum:
- total_raise
- xscore
- last_status_update
examples:
- last_status_update
type: string
- description: Sort order
explode: false
in: query
name: order
schema:
default: desc
description: Sort order
enum:
- asc
- desc
examples:
- desc
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
examples:
- 20
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
examples:
- 0
format: int64
minimum: 0
type: integer
- description: Include full task list per activity
explode: false
in: query
name: include_tasks
schema:
default: false
description: Include full task list per activity
examples:
- true
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseAirdropSearchItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Airdrop Search
tags:
- Search
/gateway/v1/search/airdrop/activities:
get:
description: 'Lists airdrop activities with pagination.
Returns activity metadata including reward type, status, and social metrics.'
operationId: search-airdrop-activities
parameters:
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseAirdropActivityItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Airdrop Activities
tags:
- Search
/gateway/v1/search/events:
get:
description: 'Searches project events by keyword, optionally filtered by `type`.
**Valid types:** `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, `twitter`.
**Lookup:** by UUID (`id`) or name (`q`). Returns 404 if the project is not found.'
operationId: search-events
parameters:
- description: Surf project UUID. PREFERRED — always use this when available from a previous response (e.g. project_id from /fund/portfolio or id from /search/project). Takes priority over q.
explode: false
in: query
name: id
schema:
description: Surf project UUID. PREFERRED — always use this when available from a previous response (e.g. project_id from /fund/portfolio or id from /search/project). Takes priority over q.
examples:
- 25c6612a-395c-4974-94eb-3b5f9f4b2ed7
type: string
- description: Fuzzy entity name search. Only use when 'id' is not available. May return unexpected results for ambiguous names.
explode: false
in: query
name: q
schema:
description: Fuzzy entity name search. Only use when 'id' is not available. May return unexpected results for ambiguous names.
examples:
- ethereum
type: string
- description: Filter by event type. Can be `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, or `twitter`.
explode: false
in: query
name: type
schema:
description: Filter by event type. Can be `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, or `twitter`.
enum:
- launch
- upgrade
- partnership
- news
- airdrop
- listing
- twitter
examples:
- launch
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
examples:
- 20
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
examples:
- 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseProjectEventItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Project Event Search
tags:
- Search
/gateway/v1/search/fund:
get:
description: 'Searches funds by keyword.
**Included fields:** name, tier, type, logo, top invested projects.'
operationId: search-fund
parameters:
- description: Search keyword — fund name like `a16z`, `paradigm`, or `coinbase ventures`
explode: false
in: query
name: q
required: true
schema:
description: Search keyword — fund name like `a16z`, `paradigm`, or `coinbase ventures`
examples:
- a16z
maxLength: 100
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
examples:
- 20
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
examples:
- 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseFundSearchItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Fund Search
tags:
- Search
/gateway/v1/search/fundraising:
get:
description: 'Searches source-backed fundraising and token-sale events, or returns the latest fundraising timeline when `q` is omitted.
Supports inclusive UTC time bounds, source and importance filters, localization, deterministic sorting, and offset pagination. Results intentionally omit project or fundraiser identity because source context is not guaranteed to identify the organization raising funds.'
operationId: search-fundraising
parameters:
- description: Optional project name, alias, symbol, title, or summary search query. When provided, the trimmed query must contain 2-100 Unicode characters.
explode: false
in: query
name: q
schema:
description: Optional project name, alias, symbol, title, or summary search query. When provided, the trimmed query must contain 2-100 Unicode characters.
examples:
- elliptic
maxLength: 100
minLength: 2
type: string
- description: Inclusive event-time lower bound. Accepts Unix seconds, YYYY-MM-DD, or RFC3339; date-only values start at 00:00:00 UTC.
explode: false
in: query
name: from
schema:
description: Inclusive event-time lower bound. Accepts Unix seconds, YYYY-MM-DD, or RFC3339; date-only values start at 00:00:00 UTC.
examples:
- '2026-07-01'
type: string
- description: Inclusive event-time upper bound. Accepts Unix seconds, YYYY-MM-DD, or RFC3339; date-only values end at 23:59:59 UTC. Defaults to the current time.
explode: false
in: query
name: to
schema:
description: Inclusive event-time upper bound. Accepts Unix seconds, YYYY-MM-DD, or RFC3339; date-only values end at 23:59:59 UTC. Defaults to the current time.
examples:
- '2026-07-10'
type: string
- description: 'Filter by public source type: social or news.'
explode: false
in: query
name: source
schema:
description: 'Filter by public source type: social or news.'
enum:
- social
- news
examples:
- social
type: string
- description: Display and search language. Missing translated fields fall back to English.
explode: false
in: query
name: lang
schema:
default: en
description: Display and search language. Missing translated fields fall back to English.
enum:
- en
- zh
- ja
- kr
examples:
- en
type: string
- description: Minimum importance score from 1 to 5. Omit to include unscored events.
explode: false
in: query
name: min_importance
schema:
description: Minimum importance score from 1 to 5. Omit to include unscored events.
examples:
- 3
format: int64
maximum: 5
minimum: 1
type: integer
- description: Sort by recency, query relevance, or importance. Relevance requires q.
explode: false
in: query
name: sort_by
schema:
default: recency
description: Sort by recency, query relevance, or importance. Relevance requires q.
enum:
- recency
- relevance
- importance
examples:
- recency
type: string
- description: Sort order. Relevance only supports desc.
explode: false
in: query
name: order
schema:
default: desc
description: Sort order. Relevance only supports desc.
enum:
- asc
- desc
examples:
- desc
type: string
- description: Results per page.
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page.
examples:
- 20
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset. The offset plus limit cannot exceed 10000.
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset. The offset plus limit cannot exceed 10000.
examples:
- 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseFundraisingSearchItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Fundraising Event Search
tags:
- Search
/gateway/v1/search/kalshi:
get:
deprecated: true
description: '**[DEPRECATED]** Use `GET /v1/search/prediction-market?platform=kalshi` instead. This endpoint will continue to work but will not receive new features.
---
Searches Kalshi events by keyword and/or category.
**Filters:**
- Keyword matching event title, subtitle, or market title
- Category
At least one of `q` or `category` is required. Returns events with nested markets.
**Data refresh:** ~30 minutes'
operationId: search-kalshi
parameters:
- description: Search keyword matching event title, subtitle, or market title
explode: false
in: query
name: q
schema:
description: Search keyword matching event title, subtitle, or market title
examples:
- bitcoin
maxLength: 200
type: string
- description: Filter by category
explode: false
in: query
name: category
schema:
description: Filter by category
enum:
- crypto
- culture
- economics
- financials
- politics
- stem
- sports
- unknown
examples:
- crypto
type: string
- description: 'Market status filter: `active`, `closed`, `determined`, `disputed`, `finalized`, `inactive`, or `initialized`'
explode: false
in: query
name: status
schema:
description: 'Market status filter: `active`, `closed`, `determined`, `disputed`, `finalized`, `inactive`, or `initialized`'
enum:
- active
- closed
- determined
- disputed
- finalized
- inactive
- initialized
examples:
- active
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
examples:
- 20
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
examples:
- 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseKalshiEvent'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Kalshi Event Search [Deprecated]
tags:
- Search
/gateway/v1/search/news:
get:
description: 'Searches crypto news articles by keyword.
Returns results ranked by relevance with highlighted matching fragments. Supports pagination via limit and offset.'
operationId: search-news
parameters:
- description: Search keyword or phrase
explode: false
in: query
name: q
required: true
schema:
description: Search keyword or phrase
examples:
- bitcoin ETF
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 10
description: Results per page
examples:
- 10
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
examples:
- 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseNewsArticleItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: News Article Search
tags:
- Search
/gateway/v1/search/polymarket:
get:
deprecated: true
description: '**[DEPRECATED]** Use `GET /v1/search/prediction-market?platform=polymarket` instead. This endpoint will continue to work but will not receive new features.
---
Searches Polymarket events by keyword, tags, and/or category.
**Filters:**
- Keyword matching market question, event title, or description
- Comma-separated tag labels
- Surf-curated category
At least one of `q`, `tags`, or `category` is required. Returns events with nested markets ranked by volume.
**Data refresh:** ~30 minutes'
operationId: search-polymarket
parameters:
- description: Search keyword matching market question, event title, or description
explode: false
in: query
name: q
schema:
description: Search keyword matching market question, event title, or description
examples:
- bitcoin
maxLength: 200
type: string
- description: 'Comma-separated tag labels to filter by (matches any). Commonly used tags: `Crypto`, `Politics`, `Sports`, `Science`, `Pop Culture`'
explode: false
in: query
name: tags
schema:
description: 'Comma-separated tag labels to filter by (matches any). Commonly used tags: `Crypto`, `Politics`, `Sports`, `Science`, `Pop Culture`'
examples:
- politics
maxLength: 500
type: string
- description: Filter by Surf-curated category
explode: false
in: query
name: category
schema:
description: Filter by Surf-curated category
enum:
- crypto
- culture
- early_polymarket_trades
- economics
- financials
- politics
- stem
- sports
- unknown
examples:
- politics
type: string
- description: 'Market status filter: `active`, `finalized`, `ended`, `initialized`, or `closed`'
explode: false
in: query
name: status
schema:
default: active
description: 'Market status filter: `active`, `finalized`, `ended`, `initialized`, or `closed`'
enum:
- active
- finalized
- ended
- initialized
- closed
examples:
- active
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
examples:
- 20
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
examples:
- 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponsePolymarketEvent'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Polymarket Event Search [Deprecated]
tags:
- Search
/gateway/v1/search/prediction-market:
get:
description: 'Browse and search prediction markets across all supported platforms.
Filter by platform, category, status, keyword search, and smart money direction. Each result includes volume, open interest, trade counts, and smart money signals.
Supports single-market lookup via `condition_id` or `market_ticker`.
**Data refresh:** ~5 minutes.'
operationId: search-prediction-market
parameters:
- description: Polymarket condition ID for single-market lookup
explode: false
in: query
name: condition_id
schema:
description: Polymarket condition ID for single-market lookup
type: string
- description: Kalshi market ticker for single-market lookup
explode: false
in: query
name: market_ticker
schema:
description: Kalshi market ticker for single-market lookup
type: string
- description: Filter by platform (omit for both)
explode: false
in: query
name: platform
schema:
description: Filter by platform (omit for both)
enum:
- polymarket
- kalshi
type: string
- description: Filter by Surf-curated category
explode: false
in: query
name: category
schema:
description: Filter by Surf-curated category
enum:
- crypto
- culture
- economics
- financials
- politics
- stem
- sports
type: string
- description: Market status filter
explode: false
in: query
name: status
schema:
default: active
description: Market status filter
enum:
- active
- closed
- finalized
type: string
- description: Sort field
explode: false
in: query
name: sort_by
schema:
default: volume_7d
description: Sort field
enum:
- volume_1d
- volume_7d
- volume_30d
- open_interest
- trade_count_7d
- days_to_resolution
type: string
- description: Sort direction
explode: false
in: query
name: order
schema:
default: desc
description: Sort direction
enum:
- asc
- desc
type: string
- description: Filter by smart money direction (Polymarket only)
explode: false
in: query
name: smart_money
schema:
description: Filter by smart money direction (Polymarket only)
enum:
- bullish
- bearish
type: string
- description: Search markets by keyword in question text or ticker. Results include slug and event fields when available, but machine slugs are not searched.
explode: false
in: query
name: q
schema:
description: Search markets by keyword in question text or ticker. Results include slug and event fields when available, but machine slugs are not searched.
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
format: int64
maximum: 100
minimum: 1
type: integer
- description: Pagination offset
explode: false
in: query
name: offset
schema:
default: 0
description: Pagination offset
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseDiscoverMarketItem'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/DataAPIError'
description: Error
security:
- AccessToken: []
summary: Search Prediction Markets
tags:
- Search
/gateway/v1/search/project:
get:
description: 'Searches crypto projects by keyword.
**Included fields:** name, description, chains, logo.'
operationId: search-project
parameters:
- description: Search keyword — project name or ticker like `uniswap`, `bitcoin`, or `ETH`
explode: false
in: query
name: q
required: true
schema:
description: Search keyword — project name or ticker like `uniswap`, `bitcoin`, or `ETH`
examples:
- bitcoin
maxLength: 100
type: string
- description: Results per page
explode: false
in: query
name: limit
schema:
default: 20
description: Results per page
examples:
- 20
format: int64
maximum: 100
minimum: 1
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/surf/refs/heads/main/openapi/surf-search-api-openapi.yml