> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Futures chart data

> Returns time-series data for a specific futures chart. Supports open interest (one-sided USD notional per venue), volume, funding rate history, liquidations, long/short ratios, basis, term structure, OHLCV, and more. A database read that fails before returning any row answers 503 (Retry-After) rather than an empty dataset; one that fails part-way returns the rows it has, with coverage.status "partial", coverage.warnings and an X-Data-Partial header. chart=cvd serves OHLCV candle rows with the CVD precomputed: each candle with a taker volume carries `cvd_delta_usd` ((2 * taker_buy_volume - volume) * close) and `cvd_usd`, the running sum per venue from the first candle in the window (Binance only today; coverage.warnings names the venues without one). returns-session, returns-heatmap, returns-hour and returns-day serve the raw 1h candles of the highest-volume venue (the averages are computed by the client). Composite charts (perp-dislocation, funding-cost, crowding-risk, flow-confirmation, carry-curve) serve their raw input rows tagged with `_type`. Liquidation `quantity` is USD notional.



## OpenAPI

````yaml /openapi.json get /v1/futures/data
openapi: 3.0.0
info:
  title: Sharpe API
  version: 1.0.0
  description: >-
    Institutional-grade crypto market data API. Access funding rates, futures,
    arbitrage opportunities, narratives, ecosystems, and more.


    Authentication is supported via two production-safe methods:

    1. **Bearer token** in the Authorization header: `Authorization: Bearer
    sk_live_...`

    2. **X-API-Key header**: `X-API-Key: sk_live_...`


    API keys in query parameters are rejected by default because URLs are
    commonly stored in logs, browser history, analytics tools, and referrer
    headers.


    These `/v1` endpoints send no CORS headers and must be called from a server:
    calling them from a browser would expose your API key in page JavaScript.


    Every endpoint needs an API key, except `/v1/health` and
    `/v1/meta/coverage`. A key works on a paid plan
    (https://www.sharpe.ai/pricing) or during its account's one-time trial of 7
    days and 250 requests; otherwise it answers 401 `expired_api_key`. There is
    no free API tier and no keyless API.
  contact:
    name: Sharpe API Support
    url: https://sharpe.ai
    email: team@sharpe.ai
servers:
  - url: https://www.sharpe.ai/api
    description: Production
security:
  - BearerAuth: []
  - ApiKeyAuth: []
tags:
  - name: System
    description: Health checks and service status
  - name: Account
    description: API key usage and quota information
  - name: Derivatives
    description: Funding rates and futures data
  - name: Market Data
    description: >-
      Heatmaps, correlations, tracker, price predictions, news, gem finder, and
      market cap search
  - name: Arbitrage
    description: >-
      Spot-perp, cross-exchange, dated futures basis, calendar spread,
      perp-dated carry, and transfer arbitrage scanners
  - name: Categories
    description: Narratives, ecosystems, and memecoins data
  - name: New Listings
    description: >-
      Spot listings, Perp listings, delistings, suspensions, scheduled trading
      starts, exchange pages, and narrative flow across CEXs and Perp DEXs.
  - name: Screener
    description: Rug Check security, holders, resolve and trending endpoints.
  - name: Signals
    description: >-
      Composite signal scores derived from cross-exchange derivatives data:
      insider selling pressure and pump-and-dump detection.
  - name: Reports
    description: >-
      Markdown reports rendered on the server from the endpoints above: the
      market briefing, one coin's analysis, and the funding-arbitrage
      opportunities.
paths:
  /v1/futures/data:
    get:
      tags:
        - Derivatives
      summary: Futures chart data
      description: >-
        Returns time-series data for a specific futures chart. Supports open
        interest (one-sided USD notional per venue), volume, funding rate
        history, liquidations, long/short ratios, basis, term structure, OHLCV,
        and more. A database read that fails before returning any row answers
        503 (Retry-After) rather than an empty dataset; one that fails part-way
        returns the rows it has, with coverage.status "partial",
        coverage.warnings and an X-Data-Partial header. chart=cvd serves OHLCV
        candle rows with the CVD precomputed: each candle with a taker volume
        carries `cvd_delta_usd` ((2 * taker_buy_volume - volume) * close) and
        `cvd_usd`, the running sum per venue from the first candle in the window
        (Binance only today; coverage.warnings names the venues without one).
        returns-session, returns-heatmap, returns-hour and returns-day serve the
        raw 1h candles of the highest-volume venue (the averages are computed by
        the client). Composite charts (perp-dislocation, funding-cost,
        crowding-risk, flow-confirmation, carry-curve) serve their raw input
        rows tagged with `_type`. Liquidation `quantity` is USD notional.
      operationId: getFuturesData
      parameters:
        - name: chart
          in: query
          description: Futures chart identifier.
          required: true
          schema:
            type: string
            enum:
              - perp-dislocation
              - funding-cost
              - crowding-risk
              - flow-confirmation
              - carry-curve
              - perpetual-price
              - liquidations
              - oi-stacked
              - oi-change
              - oi-daily-change
              - oi-snapshot
              - oi-volume
              - volume-snapshot
              - volume-history
              - cvd
              - long-short-ratio
              - funding-rate
              - top-trader-ls
              - returns-session
              - returns-heatmap
              - returns-hour
              - returns-day
              - annualized-basis
              - term-structure
        - name: coin
          in: query
          description: Base coin ticker.
          schema:
            type: string
            minLength: 1
            default: BTC
        - name: timeframe
          in: query
          description: Lookback window for the data.
          schema:
            default: 3M
            type: string
            enum:
              - 1W
              - 2W
              - 1M
              - 3M
              - 6M
              - 1Y
              - 3Y
        - name: exchanges
          in: query
          description: Comma-separated list of exchanges to include (e.g. Binance,Bybit).
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of data points per page.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: cursor
          in: query
          description: Opaque pagination cursor from a previous response.
          schema:
            type: string
        - $ref: '#/components/parameters/FormatParam'
      responses:
        '200':
          description: Futures chart data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FuturesDataResponse'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-Data-Partial:
              $ref: '#/components/headers/X-Data-Partial'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Quota-Limit:
              $ref: '#/components/headers/X-Quota-Limit'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/components/headers/X-Quota-Reset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    FormatParam:
      name: format
      in: query
      description: >-
        Response format. When set to "csv", the response Content-Type is
        text/csv instead of JSON.
      schema:
        default: json
        type: string
        enum:
          - json
          - csv
  schemas:
    FuturesDataResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/FuturesDataPayload'
          required:
            - data
    SuccessEnvelope:
      type: object
      properties:
        data:
          description: >-
            Endpoint-specific response payload. See the operation response
            schema.
        meta:
          $ref: '#/components/schemas/ApiMeta'
      required:
        - data
        - meta
    FuturesDataPayload:
      type: object
      properties:
        chart:
          type: string
          enum:
            - perp-dislocation
            - funding-cost
            - crowding-risk
            - flow-confirmation
            - carry-curve
            - perpetual-price
            - liquidations
            - oi-stacked
            - oi-change
            - oi-daily-change
            - oi-snapshot
            - oi-volume
            - volume-snapshot
            - volume-history
            - cvd
            - long-short-ratio
            - funding-rate
            - top-trader-ls
            - returns-session
            - returns-heatmap
            - returns-hour
            - returns-day
            - annualized-basis
            - term-structure
        coin:
          type: string
        timeframe:
          type: string
          enum:
            - 1W
            - 2W
            - 1M
            - 3M
            - 6M
            - 1Y
            - 3Y
        data:
          type: array
          items:
            $ref: '#/components/schemas/FuturesDataPoint'
        openInterestExcludedVenues:
          type: array
          items:
            $ref: '#/components/schemas/OpenInterestExclusion'
          description: >-
            Open-interest charts only (oi-stacked, oi-change, oi-daily-change,
            oi-snapshot): venues whose rows are shown per venue but must not be
            summed into a total, with the reason.
        coverage:
          $ref: '#/components/schemas/FuturesCoverage'
        source:
          type: string
          enum:
            - supabase
        pagination:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PaginationInfo'
        summary:
          $ref: '#/components/schemas/FuturesOiSummary'
      required:
        - chart
        - coin
        - timeframe
        - data
        - coverage
        - source
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the error type.
          example: https://www.sharpe.ai/errors/invalid_parameter
        title:
          type: string
          description: Short human-readable summary.
          example: Invalid Parameter
        status:
          type: integer
          description: HTTP status code.
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: 'Invalid parameter "coin": must not be empty'
        request_id:
          type: string
          description: Unique request identifier for support reference.
          example: req_a1b2c3d4e5f6g7h8i9j0
        doc_url:
          type: string
          format: uri
          description: Link to the relevant documentation page for troubleshooting.
          example: https://www.sharpe.ai/docs/errors#error-codes
        suggested_action:
          type: string
          description: Actionable suggestion for resolving the error.
          example: >-
            Check the 'coin' parameter value and ensure it is a valid ticker
            symbol.
      required:
        - type
        - title
        - status
        - detail
        - request_id
        - doc_url
        - suggested_action
      description: Error response following RFC 9457 (Problem Details for HTTP APIs).
    ApiMeta:
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier.
          example: req_a1b2c3d4e5f6g7h8i9j0
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response.
        elapsed_ms:
          type: integer
          minimum: 0
          description: Server processing time in milliseconds.
        dataset_id:
          type: string
          enum:
            - funding_rates_current
            - funding_rates_history
            - funding_accumulated
            - funding_fee_settlement
            - global_overview_snapshot
            - futures_open_interest
            - futures_basis
            - futures_term_structure
            - futures_liquidations
            - futures_long_short_ratio
            - futures_ohlcv
            - futures_coins
            - rwa_perp_rates_current
            - arbitrage_tickers
            - arbitrage_boards
            - arbitrage_dated_quotes
            - narratives
            - ecosystems
            - memecoins
            - mindshare
            - sectors
            - chains
            - sector_coins
            - chain_coins
            - gem_finder
            - web_traffic
            - heatmap_cache
            - stablecoins
            - news
            - listings
            - memecoin_launches
            - rug_check_inputs
            - rug_check_trending
            - pump_dump
            - insider_pressure
            - price_prediction_inputs
            - correlation_prices
            - market_cap_search
            - coingecko_coin_list
            - boros_markets
            - margin_borrow_rates
          description: >-
            The dataset the answer is read from; /v1/meta/coverage lists each
            product's datasets with their cadence and SLA.
        as_of:
          nullable: true
          type: string
          format: date-time
          description: >-
            When the data was current: the dataset's own time (the newest live
            row, the snapshot or refresh time, the fetch time), not the response
            time. Null when unknown.
        stale_after:
          nullable: true
          type: string
          format: date-time
          description: >-
            `as_of` plus the freshness SLA: after this instant the data is
            stale, whenever the body is read (a cached copy can be re-judged
            against it).
        freshness_sla_seconds:
          type: number
          description: >-
            Seconds after `as_of` the data stays fresh: the writer's cadence
            plus one skipped run.
        freshness_status:
          type: string
          enum:
            - fresh
            - stale
            - unknown
          description: >-
            `fresh` within the SLA at `generated_at`, `stale` past it, `unknown`
            when `as_of` is null.
        runtime_status:
          type: string
          enum:
            - ok
            - degraded
          description: >-
            `degraded` when this read was incomplete: a leg timed out or failed,
            a row budget was hit, or a fallback answered. Degraded answers are
            never cached.
        served_from:
          type: string
          enum:
            - snapshot
            - table
            - matview
            - live
            - last-good
          description: >-
            Where the rows came from: a precomputed snapshot, a table or
            materialized view, the upstream on request, or the server's last
            good answer.
        generated_at:
          type: string
          format: date-time
          description: >-
            When this answer was built (the instant `freshness_status` is judged
            at).
        source:
          type: array
          items:
            type: string
          description: >-
            The upstream sources behind the rows (source ids such as `binance`,
            `coingecko`).
        coverage:
          type: object
          properties:
            expected:
              type: number
            used:
              type: number
            dropped:
              type: object
              additionalProperties:
                type: number
            missing:
              type: array
              items:
                type: string
          required:
            - expected
            - used
            - dropped
          description: >-
            How complete the stored data is (never whether it is cached): `used`
            of `expected` inputs counted; `dropped` counts the rest by reason (a
            halted market is `not_live`, outside `expected`); `missing` names
            the late ones when known.
        warnings:
          type: array
          items:
            type: string
          description: >-
            What the read could not do, in words (an unreadable table, a late
            writer).
        truncated:
          type: boolean
          description: True when a row budget cut the answer short.
      required:
        - request_id
        - timestamp
        - elapsed_ms
    FuturesDataPoint:
      anyOf:
        - $ref: '#/components/schemas/OpenInterestPoint'
        - $ref: '#/components/schemas/OhlcvPoint'
        - $ref: '#/components/schemas/FundingPoint'
        - $ref: '#/components/schemas/LongShortPoint'
        - $ref: '#/components/schemas/BasisPoint'
        - $ref: '#/components/schemas/LiquidationPoint'
        - $ref: '#/components/schemas/TermStructurePoint'
        - $ref: '#/components/schemas/AnnualizedBasisPoint'
        - $ref: '#/components/schemas/FuturesPriceOverlayPoint'
    OpenInterestExclusion:
      type: object
      properties:
        exchange:
          type: string
        reason:
          type: string
      required:
        - exchange
        - reason
      description: >-
        A venue whose stored open interest is published per venue but left out
        of every cross-venue total, and why. MEXC today: its holdVol moves 7.00x
        the position change of MEXC's own deal feed, so it fits neither side
        count.
    FuturesCoverage:
      type: object
      properties:
        status:
          type: string
          enum:
            - full
            - partial
            - insufficient
            - unknown
          description: >-
            "partial" when a database read failed or timed out after some rows
            arrived, or stopped at its row cap, so the oldest rows in the window
            can be missing; warnings says which. Omitted when every read
            completed.
        availableSince:
          nullable: true
          type: string
          format: date-time
        availableUntil:
          nullable: true
          type: string
          format: date-time
        pointCount:
          type: integer
        availableTimeframes:
          type: array
          items:
            type: string
            enum:
              - 1W
              - 2W
              - 1M
              - 3M
              - 6M
              - 1Y
              - 3Y
        warnings:
          type: array
          items:
            type: string
          description: >-
            One sentence per gap: an incomplete database read, a read stopped at
            its row cap, an open-interest history (oi-stacked, oi-change,
            oi-daily-change) above 30,000 rows resampled per venue to 2-, 4-,
            6-, 12- or 24-hour buckets (last value per venue) to fit the
            response, an open-interest bucket that is the current (still
            filling) hour, or chart=cvd venues whose candles carry no taker buy
            volume.
      required:
        - availableSince
        - availableTimeframes
    PaginationInfo:
      type: object
      properties:
        cursor:
          nullable: true
          type: string
        has_more:
          type: boolean
        total:
          type: integer
          minimum: 0
      required:
        - cursor
        - has_more
        - total
    FuturesOiSummary:
      type: object
      properties:
        oi_total_usd:
          nullable: true
          description: >-
            The coin's one-sided open interest across venues (engine L4
            `oi.asset_total`): each venue's latest reading within 6 hours,
            summed, rounded to whole USD. Venues in `oi_excluded_venues` are
            left out. Null when no venue has a reading within 6 hours
            (`oi_null_reason`).
          type: number
        oi_venue_count:
          nullable: true
          description: Venues inside `oi_total_usd`.
          type: integer
        oi_as_of:
          nullable: true
          description: >-
            The oldest reading inside `oi_total_usd` (each venue's latest
            reading is hour-bucketed).
          type: string
          format: date-time
        oi_null_reason:
          description: >-
            Why `oi_total_usd` is null (`no_eligible_inputs`: no venue reading
            within 6 hours). Present only then.
          type: string
        oi_excluded_venues:
          type: array
          items:
            $ref: '#/components/schemas/OpenInterestExclusion'
          description: >-
            Venues that have a reading for this coin but are left out of the
            total, with the reason (MEXC today).
      required:
        - oi_total_usd
        - oi_venue_count
        - oi_as_of
        - oi_excluded_venues
      description: >-
        chart=oi-snapshot only: the coin's open interest summed across venues,
        computed by the server from the rows it returns.
    OpenInterestPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        open_interest_value:
          type: number
          description: >-
            One-sided open interest in USD at the sampled price: a change
            between two rows includes the price move, not only positions opened
            or closed.
        timestamp:
          type: string
          format: date-time
          description: >-
            The UTC hour bucket (its start). The value is the last ~10-minute
            sample the capture saw inside that hour, so it is about the OI at
            the bucket's END (it lines up with Binance openInterestHist at the
            next hour). The newest bucket is still filling while its hour runs;
            coverage.warnings names it.
        _type:
          description: >-
            Composite charts only: which input leg the row is. perp-dislocation
            = basis + funding + oi; funding-cost = funding + oi; crowding-risk =
            funding + oi + long-short (account rows) + ohlcv (Binance candles);
            flow-confirmation = ohlcv + oi (Binance); carry-curve =
            term-structure + funding (each venue's latest settlement). The
            composite signal is not computed by the server: the rows are its raw
            inputs. Also on oi-volume's open-interest rows when they come from
            the live venue fallback. Absent elsewhere.
          type: string
          enum:
            - funding
            - oi
            - basis
            - long-short
            - ohlcv
            - term-structure
      required:
        - exchange
        - base_coin
        - open_interest_value
        - timestamp
    OhlcvPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        timeframe:
          type: string
        open:
          type: number
        high:
          type: number
        low:
          type: number
        close:
          type: number
        volume:
          type: number
          description: Base-asset volume of the candle (not USD).
        taker_buy_volume:
          nullable: true
          description: >-
            Base-asset taker buy volume; null where the venue publishes none
            (only Binance candles carry it today, so CVD exists only for
            Binance).
          type: number
        timestamp:
          type: string
          format: date-time
          description: >-
            The candle's open (bucket start). Only closed candles are stored, so
            the newest candle can be up to ~2 hours old.
        volume_usd:
          description: >-
            Aggregated candles only (the downsampled 4h/1d buckets the web
            terminal's charts read; `/v1` serves the stored candles and omits
            it): the sum of each source candle's volume × its close. Null when a
            source candle lacks either.
          nullable: true
          type: number
        cvd_delta_usd:
          description: >-
            chart=cvd, candles with taker volume only: (taker buy − taker sell)
            × close = (2 × taker_buy_volume − volume) × close, USD.
          type: number
        cvd_usd:
          description: >-
            chart=cvd, candles with taker volume only: the venue's cumulative
            volume delta, the running sum of `cvd_delta_usd` from the window's
            first candle, USD.
          type: number
        _type:
          description: >-
            Composite charts only: which input leg the row is. perp-dislocation
            = basis + funding + oi; funding-cost = funding + oi; crowding-risk =
            funding + oi + long-short (account rows) + ohlcv (Binance candles);
            flow-confirmation = ohlcv + oi (Binance); carry-curve =
            term-structure + funding (each venue's latest settlement). The
            composite signal is not computed by the server: the rows are its raw
            inputs. Also on oi-volume's open-interest rows when they come from
            the live venue fallback. Absent elsewhere.
          type: string
          enum:
            - funding
            - oi
            - basis
            - long-short
            - ohlcv
            - term-structure
      required:
        - exchange
        - base_coin
        - timeframe
        - open
        - high
        - low
        - close
        - volume
        - taker_buy_volume
        - timestamp
    FundingPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        rate:
          type: number
          x-field: funding.settled_rate
          description: >-
            The rate a contract was charged at one funding settlement, as its
            venue reports it, a fraction per the interval that settlement
            covered.
        interval_hours:
          type: number
        settled_at:
          type: string
          format: date-time
          x-field: funding.settled_at
          description: When a contract's funding settlement took place.
        _type:
          description: >-
            Composite charts only: which input leg the row is. perp-dislocation
            = basis + funding + oi; funding-cost = funding + oi; crowding-risk =
            funding + oi + long-short (account rows) + ohlcv (Binance candles);
            flow-confirmation = ohlcv + oi (Binance); carry-curve =
            term-structure + funding (each venue's latest settlement). The
            composite signal is not computed by the server: the rows are its raw
            inputs. Also on oi-volume's open-interest rows when they come from
            the live venue fallback. Absent elsewhere.
          type: string
          enum:
            - funding
            - oi
            - basis
            - long-short
            - ohlcv
            - term-structure
      required:
        - exchange
        - base_coin
        - rate
        - interval_hours
        - settled_at
    LongShortPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        long_ratio:
          type: number
        short_ratio:
          type: number
        timestamp:
          type: string
          format: date-time
        _type:
          description: >-
            Composite charts only: which input leg the row is. perp-dislocation
            = basis + funding + oi; funding-cost = funding + oi; crowding-risk =
            funding + oi + long-short (account rows) + ohlcv (Binance candles);
            flow-confirmation = ohlcv + oi (Binance); carry-curve =
            term-structure + funding (each venue's latest settlement). The
            composite signal is not computed by the server: the rows are its raw
            inputs. Also on oi-volume's open-interest rows when they come from
            the live venue fallback. Absent elsewhere.
          type: string
          enum:
            - funding
            - oi
            - basis
            - long-short
            - ohlcv
            - term-structure
      required:
        - exchange
        - base_coin
        - long_ratio
        - short_ratio
        - timestamp
      description: >-
        long-short-ratio: the venue's account ratio (all accounts).
        top-trader-ls: the venue's top traders, with `exchange` suffixed
        `_top_trader`. The two populations are never mixed in one chart.
    BasisPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        spot_price:
          type: number
        futures_price:
          type: number
        basis_rate:
          type: number
          description: >-
            Instantaneous perp premium: (perp mark − spot) / spot, as a
            fraction. For an annualized dated-futures basis use
            chart=annualized-basis (basis_apr).
        timestamp:
          type: string
          format: date-time
        _type:
          description: >-
            Composite charts only: which input leg the row is. perp-dislocation
            = basis + funding + oi; funding-cost = funding + oi; crowding-risk =
            funding + oi + long-short (account rows) + ohlcv (Binance candles);
            flow-confirmation = ohlcv + oi (Binance); carry-curve =
            term-structure + funding (each venue's latest settlement). The
            composite signal is not computed by the server: the rows are its raw
            inputs. Also on oi-volume's open-interest rows when they come from
            the live venue fallback. Absent elsewhere.
          type: string
          enum:
            - funding
            - oi
            - basis
            - long-short
            - ohlcv
            - term-structure
      required:
        - exchange
        - base_coin
        - spot_price
        - futures_price
        - basis_rate
        - timestamp
    LiquidationPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        side:
          type: string
          enum:
            - long
            - short
        quantity:
          type: number
          description: >-
            USD notional liquidated on this side in the hour bucket starting at
            `timestamp` (Binance and Bybit from our own capture of their
            liquidation streams, Deribit from Velo; OKX is not served because
            its series is a delayed, partial sample of OKX's liquidations, not
            their total). Already in USD: do not multiply by a price. The newest
            hour is still accumulating.
        price:
          nullable: true
          description: 'Always null: the hourly buckets carry no fill price.'
          type: number
        timestamp:
          type: string
          format: date-time
      required:
        - exchange
        - base_coin
        - side
        - quantity
        - price
        - timestamp
    TermStructurePoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        contract_symbol:
          type: string
        expiry_date:
          type: string
          format: date-time
        days_to_expiry:
          type: number
        futures_price:
          type: number
        spot_price:
          type: number
        basis_rate:
          nullable: true
          description: >-
            The contract's basis to expiry (futures over spot, minus 1), a
            fraction (0.0149 is 1.49%). Null on Velo's synthetic 3-month rows
            (`contract_symbol` ending in `-VELO-3M-BASIS`), which store an
            annualized figure in its place: `basis_apr` keeps it.
          type: number
        basis_apr:
          type: number
          description: >-
            `basis_rate` × 365 / `days_to_expiry`, a fraction per year (0.0604
            is 6.04%).
        volume_24h_usd:
          nullable: true
          type: number
        open_interest_usd:
          nullable: true
          type: number
        snapshot_at:
          type: string
          format: date-time
        _type:
          description: >-
            Composite charts only: which input leg the row is. perp-dislocation
            = basis + funding + oi; funding-cost = funding + oi; crowding-risk =
            funding + oi + long-short (account rows) + ohlcv (Binance candles);
            flow-confirmation = ohlcv + oi (Binance); carry-curve =
            term-structure + funding (each venue's latest settlement). The
            composite signal is not computed by the server: the rows are its raw
            inputs. Also on oi-volume's open-interest rows when they come from
            the live venue fallback. Absent elsewhere.
          type: string
          enum:
            - funding
            - oi
            - basis
            - long-short
            - ohlcv
            - term-structure
      required:
        - exchange
        - base_coin
        - contract_symbol
        - expiry_date
        - days_to_expiry
        - futures_price
        - spot_price
        - basis_rate
        - basis_apr
        - volume_24h_usd
        - open_interest_usd
        - snapshot_at
    AnnualizedBasisPoint:
      type: object
      properties:
        exchange:
          type: string
        base_coin:
          type: string
        contract_symbol:
          type: string
        days_to_expiry:
          type: number
        basis_apr:
          type: number
          description: >-
            The contract's basis annualized over `days_to_expiry`, a fraction
            per year (0.0604 is 6.04%).
        snapshot_at:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
      required:
        - exchange
        - base_coin
        - contract_symbol
        - days_to_expiry
        - basis_apr
        - snapshot_at
        - timestamp
    FuturesPriceOverlayPoint:
      type: object
      properties:
        base_coin:
          type: string
        timeframe:
          type: string
        close:
          type: number
        timestamp:
          type: string
          format: date-time
      required:
        - base_coin
        - timeframe
        - close
        - timestamp
      description: >-
        v1 only, on oi-stacked and liquidations: Binance candle closes joined
        into `data` beside the chart's rows as a price overlay. They carry
        `close` and no `exchange`; filter them out before summing liquidation or
        OI rows.
  headers:
    X-Request-Id:
      schema:
        type: string
      description: Unique request identifier. Include this value when contacting support.
    X-Data-Partial:
      schema:
        type: string
      description: >-
        Comma-separated database tables whose paged read failed or timed out
        after some rows arrived, so the series is missing rows. Absent when
        every read completed.
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Requests allowed per minute for the authenticated API key.
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Requests remaining in the current one-minute rate-limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
      description: Unix timestamp in seconds when the current rate-limit window resets.
    X-Quota-Limit:
      schema:
        type: integer
      description: Monthly request quota for the authenticated API key.
    X-Quota-Remaining:
      schema:
        type: integer
      description: Monthly requests remaining in the current billing period.
    X-Quota-Reset:
      schema:
        type: string
        format: date-time
      description: >-
        ISO 8601 timestamp when the monthly quota resets, when available from
        the quota store.
    Retry-After:
      schema:
        type: integer
      description: >-
        Seconds to wait before retrying after a per-minute rate-limit or
        monthly-quota rejection.
  responses:
    BadRequest:
      description: Invalid or missing parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: https://www.sharpe.ai/errors/invalid_parameter
            title: Invalid Parameter
            status: 400
            detail: 'Invalid parameter "coin": must not be empty'
            request_id: req_a1b2c3d4e5f6g7h8i9j0
            doc_url: https://www.sharpe.ai/docs/errors#error-codes
            suggested_action: >-
              Check the parameter value against the endpoint documentation. Use
              GET /v1/futures/coins or GET /v1/meta/coverage to discover valid
              values.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
    Unauthorized:
      description: >-
        Missing or invalid API key, or a key without an active plan
        (`expired_api_key`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_api_key:
              summary: Missing or invalid API key
              value:
                type: https://www.sharpe.ai/errors/invalid_api_key
                title: Invalid API Key
                status: 401
                detail: >-
                  Missing API key. Pass via Authorization: Bearer <key> or the
                  X-API-Key header.
                request_id: req_a1b2c3d4e5f6g7h8i9j0
                doc_url: https://www.sharpe.ai/docs/authentication
                suggested_action: >-
                  Check your API key is correct. Pass it via Authorization:
                  Bearer <key> or the X-API-Key header.
            expired_api_key:
              summary: The key has no active plan
              value:
                type: https://www.sharpe.ai/errors/expired_api_key
                title: Expired API Key
                status: 401
                detail: >-
                  This API key has no active plan. Subscribe or renew at
                  https://www.sharpe.ai/dashboard/billing.
                request_id: req_a1b2c3d4e5f6g7h8i9j0
                doc_url: https://www.sharpe.ai/docs/authentication
                suggested_action: >-
                  Subscribe or renew at https://www.sharpe.ai/dashboard/billing.
                  The same key works again once the plan is active.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
    Forbidden:
      description: The API key lacks a scope this endpoint requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: https://www.sharpe.ai/errors/insufficient_scope
            title: Insufficient Scope
            status: 403
            detail: 'This API key requires the following scope(s): read.'
            request_id: req_a1b2c3d4e5f6g7h8i9j0
            doc_url: https://www.sharpe.ai/docs/authentication
            suggested_action: >-
              Create a new API key with the required scopes, or contact support
              to update scopes on your existing key.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
    RateLimited:
      description: >-
        Per-minute rate limit or monthly quota exceeded. Both are temporary;
        retry after the Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate_limit_exceeded:
              summary: Per-minute rate limit exceeded
              value:
                type: https://www.sharpe.ai/errors/rate_limit_exceeded
                title: Rate Limit Exceeded
                status: 429
                detail: Rate limit of 30 requests per minute exceeded.
                request_id: req_a1b2c3d4e5f6g7h8i9j0
                doc_url: https://www.sharpe.ai/docs/rate-limits
                suggested_action: >-
                  Wait until the time in the X-RateLimit-Reset header before
                  retrying. Upgrade your plan for higher limits.
            monthly_quota_exceeded:
              summary: Monthly quota exceeded
              value:
                type: https://www.sharpe.ai/errors/monthly_quota_exceeded
                title: Monthly Quota Exceeded
                status: 429
                detail: >-
                  Monthly quota of 50,000 requests exceeded. Resets at
                  2026-12-01T00:00:00.000Z.
                request_id: req_a1b2c3d4e5f6g7h8i9j0
                doc_url: https://www.sharpe.ai/docs/rate-limits
                suggested_action: >-
                  Retry after the seconds given in the Retry-After header, when
                  the monthly quota resets. Upgrade your plan for a higher
                  monthly quota. Check usage at GET /v1/usage.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Quota-Limit:
          $ref: '#/components/headers/X-Quota-Limit'
        X-Quota-Remaining:
          $ref: '#/components/headers/X-Quota-Remaining'
        X-Quota-Reset:
          $ref: '#/components/headers/X-Quota-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: https://www.sharpe.ai/errors/internal_error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred. Please try again later.
            request_id: req_a1b2c3d4e5f6g7h8i9j0
            doc_url: https://www.sharpe.ai/docs/errors#retry-guidance
            suggested_action: >-
              Retry with exponential backoff (1s, 2s, 4s, up to 30s). If the
              error persists, contact support with the X-Request-Id.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
    ServiceUnavailable:
      description: The API or quota verification service is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: https://www.sharpe.ai/errors/service_unavailable
            title: Service Unavailable
            status: 503
            detail: >-
              API key verification is temporarily unavailable. Please retry
              shortly.
            request_id: req_a1b2c3d4e5f6g7h8i9j0
            doc_url: https://www.sharpe.ai/docs/errors#retry-guidance
            suggested_action: >-
              The API is temporarily unavailable. Retry with exponential
              backoff. If it persists, contact team@sharpe.ai with the
              X-Request-Id.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Pass your API key as a Bearer token in the Authorization header:
        `Authorization: Bearer sk_live_...`
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternatively, pass your API key via the X-API-Key header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.