Surf Market API

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 Market API
  version: sha-80d3407
servers:
- url: /
tags:
- description: Get a high-level view of the crypto market. Browse token rankings by market cap or volume, track derivatives across all exchanges, monitor spot ETF fund flows, view liquidation events, compute technical indicators (RSI, MACD, Bollinger Bands, and more), explore on-chain valuation metrics (NUPL, MVRV, SOPR), and check the Fear & Greed Index.
  name: Market
paths:
  /gateway/v1/market/etf:
    get:
      description: 'Returns daily spot ETF flow history.


        **Included fields:** net flow (USD), token price, per-ticker breakdown.


        Sorted by date descending. `symbol`: `BTC`, `ETH`, `XRP`, `SOL`, or `HYPE`.'
      operationId: market-etf
      parameters:
      - description: Token symbol. Can be `BTC`, `ETH`, `XRP`, `SOL`, or `HYPE`.
        explode: false
        in: query
        name: symbol
        required: true
        schema:
          description: Token symbol. Can be `BTC`, `ETH`, `XRP`, `SOL`, or `HYPE`.
          enum:
          - BTC
          - ETH
          - XRP
          - SOL
          - HYPE
          examples:
          - BTC
          type: string
      - description: Field to sort results by
        explode: false
        in: query
        name: sort_by
        schema:
          default: timestamp
          description: Field to sort results by
          enum:
          - flow_usd
          - timestamp
          examples:
          - timestamp
          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: Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
        explode: false
        in: query
        name: from
        schema:
          description: Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
          examples:
          - '2026-01-01'
          type: string
      - description: End of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
        explode: false
        in: query
        name: to
        schema:
          description: End of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
          examples:
          - '2026-03-01'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleListResponseMarketETFFlowItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: ETF Flow History
      tags:
      - Market
  /gateway/v1/market/exchange-flow/exchanges:
    get:
      description: 'Returns Hermod''s curated exchange filters for exchange-flow metrics: upstream aggregate filters plus 20 high-coverage individual exchanges.


        Use the returned `symbol` values as the `exchange` query parameter on `/v1/market/onchain-indicator` when `metric` is one of `exchange-flows/inflow`, `exchange-flows/outflow`, `exchange-flows/netflow`, or `exchange-flows/reserve`.


        The curated list intentionally excludes long-tail upstream exchange entities that return empty data or bad-request errors for flow metrics.'
      operationId: market-exchange-flow-exchanges
      parameters:
      - description: Token ticker symbol. Can be `BTC` or `ETH`.
        explode: false
        in: query
        name: symbol
        required: true
        schema:
          description: Token ticker symbol. Can be `BTC` or `ETH`.
          enum:
          - BTC
          - ETH
          examples:
          - BTC
          type: string
      - description: Results per page
        explode: false
        in: query
        name: limit
        schema:
          default: 100
          description: Results per page
          examples:
          - 100
          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/DataResponseMarketExchangeFlowExchangeItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Exchange Flow Exchanges
      tags:
      - Market
  /gateway/v1/market/fear-greed:
    get:
      description: 'Returns Bitcoin Fear & Greed Index history.


        **Included fields:** index value (0-100), classification label, BTC price at each data point.


        Sorted newest-first. Use `from`/`to` to filter by date range.'
      operationId: market-fear-greed
      parameters:
      - description: Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
        explode: false
        in: query
        name: from
        schema:
          description: Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
          examples:
          - '2026-01-01'
          type: string
      - description: End of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
        explode: false
        in: query
        name: to
        schema:
          description: End of time range. Accepts Unix seconds or date string (YYYY-MM-DD)
          examples:
          - '2026-03-01'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleListResponseMarketFearGreedHistoryItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Fear & Greed Index History
      tags:
      - Market
  /gateway/v1/market/futures:
    get:
      description: 'Returns futures market data across all tracked tokens in a single ranked snapshot.


        **Included fields:** open interest, funding rate, long/short ratio, 24h volume.


        Sorted by `volume_24h` by default — use `sort_by` to change.


        **No pagination** — this endpoint returns the full list in one response. Does NOT accept `limit`, `offset`, or `symbol`; to filter to one token, look it up in the response locally.'
      operationId: market-futures
      parameters:
      - description: Field to sort results by
        explode: false
        in: query
        name: sort_by
        schema:
          default: volume_24h
          description: Field to sort results by
          enum:
          - open_interest
          - funding_rate
          - volume_24h
          - long_short_ratio
          examples:
          - volume_24h
          type: string
      - description: Sort order
        explode: false
        in: query
        name: order
        schema:
          default: desc
          description: Sort order
          enum:
          - asc
          - desc
          examples:
          - desc
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleListResponseMarketFuturesItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Futures Market Overview
      tags:
      - Market
  /gateway/v1/market/liquidation/chart:
    get:
      description: 'Returns OHLC-style aggregated liquidation data for a token on a specific exchange.


        **Filters:** `symbol`, `exchange`, `interval`.


        Useful for charting liquidation volume over time.'
      operationId: market-liquidation-chart
      parameters:
      - description: Token ticker symbol like `BTC` or `ETH`
        explode: false
        in: query
        name: symbol
        required: true
        schema:
          description: Token ticker symbol like `BTC` or `ETH`
          examples:
          - BTC
          type: string
      - description: 'Candlestick interval — bucket size for each point in the liquidation chart series: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `8h`, `12h`, `1d`, or `1w`. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from`/`to` to bound the series.'
        explode: false
        in: query
        name: interval
        schema:
          default: 1h
          description: 'Candlestick interval — bucket size for each point in the liquidation chart series: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `8h`, `12h`, `1d`, or `1w`. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from`/`to` to bound the series.'
          enum:
          - 1m
          - 3m
          - 5m
          - 15m
          - 30m
          - 1h
          - 4h
          - 6h
          - 8h
          - 12h
          - 1d
          - 1w
          examples:
          - 1h
          type: string
      - description: Exchange name. Can be `Binance`, `OKX`, `Bybit`, `Bitget`, `Hyperliquid`, `Gate`, `HTX`, `Bitmex`, `Bitfinex`, `CoinEx`, `Aster`, or `Lighter`.
        explode: false
        in: query
        name: exchange
        schema:
          default: Binance
          description: Exchange name. Can be `Binance`, `OKX`, `Bybit`, `Bitget`, `Hyperliquid`, `Gate`, `HTX`, `Bitmex`, `Bitfinex`, `CoinEx`, `Aster`, or `Lighter`.
          enum:
          - Binance
          - OKX
          - Bybit
          - Bitget
          - Hyperliquid
          - Gate
          - HTX
          - Bitmex
          - Bitfinex
          - CoinEx
          - Aster
          - Lighter
          examples:
          - Binance
          type: string
      - description: Results per page
        explode: false
        in: query
        name: limit
        schema:
          default: 500
          description: Results per page
          examples:
          - 500
          format: int64
          maximum: 4500
          minimum: 1
          type: integer
      - description: Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`)
        explode: false
        in: query
        name: from
        schema:
          description: Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`)
          examples:
          - '2024-01-01'
          type: string
      - description: End of time range. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`)
        explode: false
        in: query
        name: to
        schema:
          description: End of time range. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`)
          examples:
          - '2024-02-01'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleListResponseLiquidationChartItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Liquidation Chart
      tags:
      - Market
  /gateway/v1/market/liquidation/exchange-list:
    get:
      description: 'Returns liquidation breakdown by exchange in a single ranked snapshot.


        **Included fields:** total, long, and short volumes in USD.


        **Filters:** `symbol` and `time_range` (`1h`, `4h`, `12h`, `24h`).


        **No pagination and no `interval`** — this endpoint does NOT accept `limit`, `offset`, or `interval`. Returns the full exchange list in one response.'
      operationId: market-liquidation-exchange-list
      parameters:
      - description: Token ticker symbol like `BTC` or `ETH`
        explode: false
        in: query
        name: symbol
        schema:
          default: BTC
          description: Token ticker symbol like `BTC` or `ETH`
          examples:
          - BTC
          type: string
      - description: 'Window to aggregate over for the snapshot: `1h`, `4h`, `12h`, or `24h`. Returns a single snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`.'
        explode: false
        in: query
        name: time_range
        schema:
          default: 24h
          description: 'Window to aggregate over for the snapshot: `1h`, `4h`, `12h`, or `24h`. Returns a single snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`.'
          enum:
          - 1h
          - 4h
          - 12h
          - 24h
          examples:
          - 24h
          type: string
      - description: Field to sort results by
        explode: false
        in: query
        name: sort_by
        schema:
          default: liquidation_usd
          description: Field to sort results by
          enum:
          - liquidation_usd
          - long_liquidation_usd
          - short_liquidation_usd
          examples:
          - liquidation_usd
          type: string
      - description: Sort order
        explode: false
        in: query
        name: order
        schema:
          default: desc
          description: Sort order
          enum:
          - asc
          - desc
          examples:
          - desc
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleListResponseLiquidationExchangeItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Liquidation by Exchange
      tags:
      - Market
  /gateway/v1/market/liquidation/order:
    get:
      description: 'Returns individual large liquidation orders above a USD threshold (`min_amount`, default 10000).


        **Filters:** `exchange` and `symbol`.


        **Pagination:** `limit`/`offset` page within a bounded, most-recent window. To page beyond that window, shift the time range: set `to` to `oldest_returned_timestamp + 1` (Unix seconds) and repeat, de-duplicating on `order_id`. `to` is **exclusive** (returns rows strictly older than `to`), so the `+1` re-includes the boundary second; using the oldest timestamp itself would skip any rows sharing that second. When `offset` exceeds the window the response returns an empty array with `meta.empty_reason` rather than falsely claiming exhaustion.


        For aggregate totals and long/short breakdown by exchange, use `/market/liquidation/exchange-list`. For historical liquidation charts, use `/market/liquidation/chart`.'
      operationId: market-liquidation-order
      parameters:
      - description: Exchange name. Can be `Binance`, `OKX`, `Bybit`, `Bitget`, `Hyperliquid`, `Gate`, `HTX`, `Bitmex`, `Bitfinex`, `CoinEx`, `Aster`, or `Lighter`.
        explode: false
        in: query
        name: exchange
        schema:
          default: Binance
          description: Exchange name. Can be `Binance`, `OKX`, `Bybit`, `Bitget`, `Hyperliquid`, `Gate`, `HTX`, `Bitmex`, `Bitfinex`, `CoinEx`, `Aster`, or `Lighter`.
          enum:
          - Binance
          - OKX
          - Bybit
          - Bitget
          - Hyperliquid
          - Gate
          - HTX
          - Bitmex
          - Bitfinex
          - CoinEx
          - Aster
          - Lighter
          examples:
          - Binance
          type: string
      - description: Token ticker symbol like `BTC` or `ETH`
        explode: false
        in: query
        name: symbol
        schema:
          default: BTC
          description: Token ticker symbol like `BTC` or `ETH`
          examples:
          - BTC
          type: string
      - description: Minimum liquidation amount in USD
        explode: false
        in: query
        name: min_amount
        schema:
          default: '10000'
          description: Minimum liquidation amount in USD
          examples:
          - '10000'
          type: string
      - description: Filter by liquidation side. Omit to return both.
        explode: false
        in: query
        name: side
        schema:
          description: Filter by liquidation side. Omit to return both.
          enum:
          - long
          - short
          examples:
          - long
          type: string
      - description: Field to sort results by
        explode: false
        in: query
        name: sort_by
        schema:
          default: timestamp
          description: Field to sort results by
          enum:
          - usd_value
          - timestamp
          - price
          type: string
      - description: Sort order
        explode: false
        in: query
        name: order
        schema:
          default: desc
          description: Sort order
          enum:
          - asc
          - desc
          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
      - description: Start of time range (inclusive). Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`)
        explode: false
        in: query
        name: from
        schema:
          description: Start of time range (inclusive). Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`)
          examples:
          - '2024-01-01'
          type: string
      - description: End of time range, exclusive (returns rows strictly older than `to`). Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`). To page backward, set this to the oldest returned `timestamp` + 1 and de-duplicate on `order_id`.
        explode: false
        in: query
        name: to
        schema:
          description: End of time range, exclusive (returns rows strictly older than `to`). Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`). To page backward, set this to the oldest returned `timestamp` + 1 and de-duplicate on `order_id`.
          examples:
          - '2024-02-01'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponseLiquidationOrderItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Large Liquidation Orders
      tags:
      - Market
  /gateway/v1/market/listing:
    get:
      description: 'Returns historical exchange listing and delisting events.


        **Filters:** date range, exchange, token symbol, product type, event type.'
      operationId: listing
      parameters:
      - description: Start date (YYYY-MM-DD or ISO 8601)
        explode: false
        in: query
        name: from
        required: true
        schema:
          description: Start date (YYYY-MM-DD or ISO 8601)
          examples:
          - '2024-01-01'
          type: string
      - description: End date (defaults to now)
        explode: false
        in: query
        name: to
        schema:
          description: End date (defaults to now)
          examples:
          - '2024-03-01'
          type: string
      - description: Filter by token symbol
        explode: false
        in: query
        name: symbol
        schema:
          description: Filter by token symbol
          examples:
          - BTC
          type: string
      - description: Filter by exchange name
        explode: false
        in: query
        name: exchange
        schema:
          description: Filter by exchange name
          examples:
          - binance
          type: string
      - description: Filter by product type
        explode: false
        in: query
        name: product
        schema:
          default: all
          description: Filter by product type
          enum:
          - spot
          - margin
          - perp
          - pre_market_perp
          - all
          type: string
      - description: Event type filter
        explode: false
        in: query
        name: type
        schema:
          default: listing
          description: Event type filter
          enum:
          - listing
          - delisting
          - cancelled
          - advanced
          - postponed
          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/DataResponseListingEventItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Exchange Listing Events
      tags:
      - Market
  /gateway/v1/market/onchain-indicator:
    get:
      description: 'Returns on-chain indicator time-series for BTC or ETH.


        **Available metrics:** `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, `exchange-flows` (inflow/outflow/netflow/reserve).


        **Long ranges:** each response is capped at about 100 data points. When `meta.has_more=true`, split `from`/`to` into smaller windows (about 90 days for daily data) and merge by timestamp client-side. For exchange-flow metrics, `all_exchange`, `spot_exchange`, and `derivative_exchange` are aggregate filters, not sums over the curated individual exchange list.'
      operationId: market-onchain-indicator
      parameters:
      - description: Token ticker symbol. Can be `BTC` or `ETH`.
        explode: false
        in: query
        name: symbol
        required: true
        schema:
          description: Token ticker symbol. Can be `BTC` or `ETH`.
          enum:
          - BTC
          - ETH
          examples:
          - BTC
          type: string
      - description: On-chain metric name. Can be `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, or `exchange-flows/{inflow,outflow,netflow,reserve}`.
        explode: false
        in: query
        name: metric
        required: true
        schema:
          description: On-chain metric name. Can be `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, or `exchange-flows/{inflow,outflow,netflow,reserve}`.
          enum:
          - nupl
          - sopr
          - mvrv
          - puell-multiple
          - nvm
          - nvt
          - nvt-golden-cross
          - exchange-flows/inflow
          - exchange-flows/outflow
          - exchange-flows/netflow
          - exchange-flows/reserve
          examples:
          - nupl
          type: string
      - description: Aggregation granularity.
        explode: false
        in: query
        name: granularity
        schema:
          default: day
          description: Aggregation granularity.
          enum:
          - day
          examples:
          - day
          type: string
      - description: Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD). Defaults to 90 days ago when omitted. Maximum range is 365 days. Responses are capped at about 100 data points; when meta.has_more is true, split from/to into smaller windows (about 90 days for daily data).
        explode: false
        in: query
        name: from
        schema:
          description: Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD). Defaults to 90 days ago when omitted. Maximum range is 365 days. Responses are capped at about 100 data points; when meta.has_more is true, split from/to into smaller windows (about 90 days for daily data).
          examples:
          - '2026-01-01'
          type: string
      - description: End of time range. Accepts Unix seconds or date string (YYYY-MM-DD). Defaults to today when omitted. Maximum range is 365 days. Responses are capped at about 100 data points; when meta.has_more is true, split from/to into smaller windows (about 90 days for daily data).
        explode: false
        in: query
        name: to
        schema:
          description: End of time range. Accepts Unix seconds or date string (YYYY-MM-DD). Defaults to today when omitted. Maximum range is 365 days. Responses are capped at about 100 data points; when meta.has_more is true, split from/to into smaller windows (about 90 days for daily data).
          examples:
          - '2026-03-01'
          type: string
      - description: Curated exchange filter for exchange-flow metrics. Use /v1/market/exchange-flow/exchanges to list labels.
        explode: false
        in: query
        name: exchange
        schema:
          default: all_exchange
          description: Curated exchange filter for exchange-flow metrics. Use /v1/market/exchange-flow/exchanges to list labels.
          enum:
          - all_exchange
          - spot_exchange
          - derivative_exchange
          - coinbase_prime
          - binance
          - coinbase_advanced
          - okx
          - kraken
          - bybit
          - bitstamp
          - gemini
          - bitget
          - kucoin
          - bitfinex
          - gate_io
          - deribit
          - mexc
          - htx_global
          - bitflyer
          - coinone
          - bithumb
          - upbit
          - hashkey_exchange
          examples:
          - all_exchange
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponseMarketMetricPoint'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: On-Chain Indicator
      tags:
      - Market
  /gateway/v1/market/options:
    get:
      description: 'Returns options market data for a `symbol`.


        **Included fields:** open interest, volume, put/call ratio, max pain price.'
      operationId: market-options
      parameters:
      - description: Token symbol. Can be `BTC`, `ETH`, `SOL`, `XRP`, `BNB`, `DOGE`, `ADA`, or `AVAX`.
        explode: false
        in: query
        name: symbol
        required: true
        schema:
          description: Token symbol. Can be `BTC`, `ETH`, `SOL`, `XRP`, `BNB`, `DOGE`, `ADA`, or `AVAX`.
          enum:
          - BTC
          - ETH
          - SOL
          - XRP
          - BNB
          - DOGE
          - ADA
          - AVAX
          examples:
          - BTC
          type: string
      - description: Field to sort results by
        explode: false
        in: query
        name: sort_by
        schema:
          default: volume_24h
          description: Field to sort results by
          enum:
          - open_interest
          - volume_24h
          examples:
          - volume_24h
          type: string
      - description: Sort order
        explode: false
        in: query
        name: order
        schema:
          default: desc
          description: Sort order
          enum:
          - asc
          - desc
          examples:
          - desc
          type: string
      responses:
      

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/surf/refs/heads/main/openapi/surf-market-api-openapi.yml