cryptodataapi-com Liquidity / Market Depth API

openapi: 3.2.0
info:
  title: Crypto Data Liquidity / Market Depth API
  description: 'Real-time crypto market intelligence API. Built for AI agents: gasless USDC payments via x402 protocol, one-call onboarding, and 180+ endpoints for prices, derivatives, funding, and sentiment.'
  version: '2026-10-28'
servers:
- url: https://cryptodataapi.com
tags:
- name: Liquidity / Market Depth
  description: L2 depth snapshots, OI/price divergence, and the liquidity regime classifier.
paths:
  /api/v1/liquidity/depth:
    get:
      tags:
      - Liquidity / Market Depth
      summary: Get Depth
      description: 'Current per-coin depth/spread snapshot across the tracked universe.


        Returns one record per coin (top-25 HL perps by 24h volume):

        bid/ask depth in USD at {10, 25, 50, 100}bps from mid, spread in bps,

        book imbalance within 10bps, and joined open interest.


        The free tier is scoped to BTC; full-universe coverage is Pro and Pro Plus.'
      operationId: get_depth_api_v1_liquidity_depth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepthResponse'
      security:
      - APIKeyHeader: []
  /api/v1/liquidity/oi-divergence:
    get:
      tags:
      - Liquidity / Market Depth
      summary: Get Oi Divergence
      description: 'OI vs price change across 1h/4h/24h windows, ranked by 4h divergence.


        Positive divergence (OI rising faster than price) = fragile positioning.

        Coins without enough history for a given window report null for that window.


        The free tier is scoped to BTC; full-universe coverage is Pro and Pro Plus.'
      operationId: get_oi_divergence_api_v1_liquidity_oi_divergence_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDivergenceResponse'
      security:
      - APIKeyHeader: []
  /api/v1/liquidity/regime:
    get:
      tags:
      - Liquidity / Market Depth
      summary: Get Regime
      description: 'Per-coin liquidity regime + market-wide aggregate + composite score.


        Each coin is classified into one of: ``deep_book``, ``oi_price_divergence``,

        ``depth_withdrawal``, ``post_cascade_impaired``, or ``neutral``. The

        composite score (0-100) maps the regime mix into a single fragility read

        (higher = healthier market structure).


        **Forward-only — not historically backfillable.** Unlike ``technical_regime``

        (replayable from daily klines), the rules here depend on *intraday* L2 depth

        deltas (10-min withdrawal, 12h depth baselines, depth/spread percentiles)

        that only exist in the live per-minute sample buffer. There is no historical

        source to reconstruct them from, so this signal accumulates forward from

        collector start. The per-coin snapshot is archived daily so a backtestable

        history builds going forward; periods before collector deploy are unavailable.'
      operationId: get_regime_api_v1_liquidity_regime_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiquidityRegimeResponse'
      security:
      - APIKeyHeader: []
  /api/v1/liquidity/regime/score:
    get:
      tags:
      - Liquidity / Market Depth
      summary: Get Regime Score
      description: 'Composite liquidity fragility score (0-100) + sentiment band + aggregate breakdown.


        Trimmed companion to ``/liquidity/regime`` — same composite, no per-coin list.'
      operationId: get_regime_score_api_v1_liquidity_regime_score_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiquidityRegimeScoreResponse'
      security:
      - APIKeyHeader: []
  /api/v1/liquidity/depth/{coin}:
    get:
      tags:
      - Liquidity / Market Depth
      summary: Get Depth For Coin
      description: 'Per-coin depth history (rolling, up to 24h). Free: BTC only; Pro + Pro Plus: any tracked coin.


        **Tracked universe is the top 25 Hyperliquid perps by 24h notional** (re-

        selected each sweep), not every coin — an untracked coin 404s. The current

        set is the ``coins`` list on ``/liquidity/depth``.


        ``minutes`` is a **time** window measured back from now, not a row count.

        Sampling runs on a ~2-minute timer and can skip, so ``count`` is the number of

        snapshots that actually landed in the window — expect roughly ``minutes / 2``,

        fewer after a stall. Each record carries ``ts`` so staleness is visible.


        Each record carries ``depth_usd.bid`` / ``depth_usd.ask`` per band

        (10/25/50/100 bps) plus ``imbalance_10bps``. ``levels_truncated`` flags,

        per band per side, when the deepest level in HL''s ~20-level snapshot still

        sat inside the band — that band''s ``depth_usd`` is then a lower bound on

        the true resting depth, not the depth.'
      operationId: get_depth_for_coin_api_v1_liquidity_depth__coin__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: coin
        in: path
        required: true
        schema:
          type: string
          title: Coin
        example: BTC
      - name: minutes
        in: query
        required: false
        schema:
          type: integer
          maximum: 1440
          minimum: 1
          description: Trailing wall-clock minutes of history (max 24h)
          default: 60
          title: Minutes
        description: Trailing wall-clock minutes of history (max 24h)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoinDepthHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CoinDepthHistoryResponse:
      properties:
        coin:
          type: string
          title: Coin
        minutes:
          type: integer
          title: Minutes
        count:
          type: integer
          title: Count
        history:
          items:
            $ref: '#/components/schemas/CoinDepthSnapshot'
          type: array
          title: History
      type: object
      required:
      - coin
      - minutes
      - count
      - history
      title: CoinDepthHistoryResponse
    CoinRegimeEntry:
      properties:
        coin:
          type: string
          title: Coin
        regime:
          type: string
          title: Regime
          description: deep_book | oi_price_divergence | depth_withdrawal | post_cascade_impaired | neutral
        confidence:
          type: number
          title: Confidence
          default: 0.0
        low_confidence:
          type: boolean
          title: Low Confidence
          default: false
        baseline_minutes:
          type: integer
          title: Baseline Minutes
          default: 0
        signals:
          additionalProperties: true
          type: object
          title: Signals
      type: object
      required:
      - coin
      - regime
      title: CoinRegimeEntry
    CoinDepthSnapshot:
      properties:
        coin:
          type: string
          title: Coin
        ts:
          type: integer
          title: Ts
        mid_price:
          type: number
          title: Mid Price
        spread_bps:
          title: Spread Bps
          type:
          - number
          - 'null'
        bid_levels:
          type: integer
          title: Bid Levels
        ask_levels:
          type: integer
          title: Ask Levels
        depth_usd:
          $ref: '#/components/schemas/DepthBuckets'
        levels_truncated:
          title: Levels Truncated
          description: '{bid: {10bps: bool, ...}, ask: {...}} — band saturated the returned book levels; its depth_usd is a lower bound'
          additionalProperties:
            additionalProperties:
              type: boolean
            type: object
          type:
          - object
          - 'null'
        total_depth_25bps_usd:
          title: Total Depth 25Bps Usd
          type:
          - number
          - 'null'
        imbalance_10bps:
          title: Imbalance 10Bps
          type:
          - number
          - 'null'
        open_interest_usd:
          title: Open Interest Usd
          type:
          - number
          - 'null'
      type: object
      required:
      - coin
      - ts
      - mid_price
      - bid_levels
      - ask_levels
      title: CoinDepthSnapshot
    OIDivergenceResponse:
      properties:
        as_of:
          type: integer
          title: As Of
        universe_size:
          type: integer
          title: Universe Size
        rows:
          items:
            $ref: '#/components/schemas/OIDivergenceRow'
          type: array
          title: Rows
      type: object
      required:
      - as_of
      - universe_size
      - rows
      title: OIDivergenceResponse
    OIDivergenceRow:
      properties:
        coin:
          type: string
          title: Coin
        price:
          title: Price
          type:
          - number
          - 'null'
        open_interest_usd:
          title: Open Interest Usd
          type:
          - number
          - 'null'
        price_change_1h_pct:
          title: Price Change 1H Pct
          type:
          - number
          - 'null'
        price_change_4h_pct:
          title: Price Change 4H Pct
          type:
          - number
          - 'null'
        price_change_24h_pct:
          title: Price Change 24H Pct
          type:
          - number
          - 'null'
        oi_change_1h_pct:
          title: Oi Change 1H Pct
          type:
          - number
          - 'null'
        oi_change_4h_pct:
          title: Oi Change 4H Pct
          type:
          - number
          - 'null'
        oi_change_24h_pct:
          title: Oi Change 24H Pct
          type:
          - number
          - 'null'
        divergence_4h:
          title: Divergence 4H
          description: oi_change_4h_pct - price_change_4h_pct (positive = OI rising faster than price)
          type:
          - number
          - 'null'
      type: object
      required:
      - coin
      title: OIDivergenceRow
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LiquidityRegimeScoreResponse:
      properties:
        as_of:
          type: integer
          title: As Of
        composite_score:
          type: number
          title: Composite Score
        sentiment:
          type: string
          title: Sentiment
        aggregate:
          $ref: '#/components/schemas/RegimeAggregate'
      type: object
      required:
      - as_of
      - composite_score
      - sentiment
      - aggregate
      title: LiquidityRegimeScoreResponse
    LiquidityRegimeResponse:
      properties:
        as_of:
          type: integer
          title: As Of
        universe_size:
          type: integer
          title: Universe Size
        coins:
          items:
            $ref: '#/components/schemas/CoinRegimeEntry'
          type: array
          title: Coins
        aggregate:
          $ref: '#/components/schemas/RegimeAggregate'
        composite_score:
          type: number
          title: Composite Score
          description: 0-100; higher = healthier market structure
        sentiment:
          type: string
          title: Sentiment
          description: healthy | leaning_healthy | neutral | leaning_fragile | fragile
      type: object
      required:
      - as_of
      - universe_size
      - coins
      - aggregate
      - composite_score
      - sentiment
      title: LiquidityRegimeResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RegimeAggregate:
      properties:
        deep_book:
          type: integer
          title: Deep Book
          default: 0
        oi_price_divergence:
          type: integer
          title: Oi Price Divergence
          default: 0
        depth_withdrawal:
          type: integer
          title: Depth Withdrawal
          default: 0
        post_cascade_impaired:
          type: integer
          title: Post Cascade Impaired
          default: 0
        neutral:
          type: integer
          title: Neutral
          default: 0
        pct_deep_book:
          type: number
          title: Pct Deep Book
          default: 0.0
        pct_divergent:
          type: number
          title: Pct Divergent
          default: 0.0
        pct_withdrawing:
          type: number
          title: Pct Withdrawing
          default: 0.0
        pct_impaired:
          type: number
          title: Pct Impaired
          default: 0.0
        pct_neutral:
          type: number
          title: Pct Neutral
          default: 0.0
      type: object
      title: RegimeAggregate
    DepthBuckets:
      properties:
        bid:
          additionalProperties:
            type: number
          type: object
          title: Bid
        ask:
          additionalProperties:
            type: number
          type: object
          title: Ask
      type: object
      title: DepthBuckets
      description: Cumulative bid/ask notional within bps buckets from mid.
    DepthResponse:
      properties:
        as_of:
          type: integer
          title: As Of
        universe_size:
          type: integer
          title: Universe Size
        coins:
          items:
            $ref: '#/components/schemas/CoinDepthSnapshot'
          type: array
          title: Coins
      type: object
      required:
      - as_of
      - universe_size
      - coins
      title: DepthResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key