> ## 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.

# Funding spread history and carry backtest

> Returns a pair's historical funding spread and a carry backtest from stored settlements: a spot-perp carry on one venue (spot pays no funding) or a cross-exchange carry (long one perp, short another). The legs are aligned by settlement time (a 1h leg against an 8h leg reads the 8h settlement for each hour it covers), intervals come from the settlements themselves, never an assumed 8h. Backtests over 1-90 days sum the settlements in the window, charge each venue's entry and exit taker fees once, and report net return, annualized net APR, days with negative carry, max drawdown of cumulative carry and coverage. A short-spot leg (spot-perp long) is charged the venue's current borrow APR pro rata where the venue publishes one (borrowApr, borrowCostIncluded).



## OpenAPI

````yaml /openapi.json get /v1/arbitrage/funding-spread-history
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/arbitrage/funding-spread-history:
    get:
      tags:
        - Arbitrage
      summary: Funding spread history and carry backtest
      description: >-
        Returns a pair's historical funding spread and a carry backtest from
        stored settlements: a spot-perp carry on one venue (spot pays no
        funding) or a cross-exchange carry (long one perp, short another). The
        legs are aligned by settlement time (a 1h leg against an 8h leg reads
        the 8h settlement for each hour it covers), intervals come from the
        settlements themselves, never an assumed 8h. Backtests over 1-90 days
        sum the settlements in the window, charge each venue's entry and exit
        taker fees once, and report net return, annualized net APR, days with
        negative carry, max drawdown of cumulative carry and coverage. A
        short-spot leg (spot-perp long) is charged the venue's current borrow
        APR pro rata where the venue publishes one (borrowApr,
        borrowCostIncluded).
      operationId: getArbitrageFundingSpreadHistory
      parameters:
        - name: mode
          in: query
          description: >-
            `spot-perp`: one venue's spot and perp (needs `venue`).
            `cross-exchange`: a long perp and a short perp (needs `longVenue`
            and `shortVenue`).
          schema:
            default: spot-perp
            type: string
            enum:
              - spot-perp
              - cross-exchange
        - name: coin
          in: query
          description: Base coin, for example BTC.
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 32
        - name: venue
          in: query
          description: >-
            Spot-perp venue: Binance, OKX, Bybit, Bitget, Gate.io, KuCoin, MEXC,
            BingX or HTX. Required in the default `spot-perp` mode: a call
            without it answers 400.
          schema:
            type: string
            maxLength: 32
        - name: contract
          in: query
          description: >-
            Spot-perp: the venue's perp contract symbol, for example BTCUSDT.
            Optional: without it the venue's contract for the coin with the
            largest current open interest is used.
          schema:
            type: string
            maxLength: 64
        - name: direction
          in: query
          description: >-
            Spot-perp: `short` buys spot and shorts the perp (collects positive
            funding); `long` sells spot and longs the perp (the venue's current
            borrow APR is charged where it publishes one: `borrowCostIncluded`).
          schema:
            default: short
            type: string
            enum:
              - short
              - long
        - name: longVenue
          in: query
          description: 'Cross-exchange: the venue of the long perp.'
          schema:
            type: string
            maxLength: 32
        - name: longContract
          in: query
          description: >-
            Cross-exchange: the long perp's contract symbol. Optional, resolved
            as `contract` is.
          schema:
            type: string
            maxLength: 64
        - name: shortVenue
          in: query
          description: 'Cross-exchange: the venue of the short perp.'
          schema:
            type: string
            maxLength: 32
        - name: shortContract
          in: query
          description: >-
            Cross-exchange: the short perp's contract symbol. Optional, resolved
            as `contract` is.
          schema:
            type: string
            maxLength: 64
        - name: days
          in: query
          description: >-
            Backtest window in days (1-90): the series covers it, and
            `backtests` lists it after the shorter standard windows.
          schema:
            default: 30
            type: integer
            minimum: 1
            maximum: 90
      responses:
        '200':
          description: Spread series and backtests returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingSpreadHistoryResponse'
          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'
            X-Data-Source:
              $ref: '#/components/headers/X-Data-Source'
            X-Data-Stale:
              $ref: '#/components/headers/X-Data-Stale'
            X-Data-As-Of:
              $ref: '#/components/headers/X-Data-As-Of'
            X-Freshness-Sla-Seconds:
              $ref: '#/components/headers/X-Freshness-Sla-Seconds'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    FundingSpreadHistoryResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/FundingSpreadHistory'
          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
    FundingSpreadHistory:
      type: object
      properties:
        mode:
          type: string
          enum:
            - spot-perp
            - cross-exchange
        coin:
          type: string
        direction:
          nullable: true
          description: >-
            Spot-perp only: `short` = buy spot, short the perp (collects
            positive funding); `long` = sell spot, long the perp. Null on
            cross-exchange.
          type: string
          enum:
            - short
            - long
        days:
          type: integer
        legs:
          type: array
          items:
            $ref: '#/components/schemas/FundingSpreadHistoryLeg'
        spot:
          nullable: true
          description: >-
            Spot-perp only: the spot leg (same venue; spot pays no funding) and
            its taker fee per fill.
          type: object
          properties:
            venue:
              type: string
            takerFee:
              type: number
          required:
            - venue
            - takerFee
        roundTripFees:
          type: number
        requiresBorrow:
          type: boolean
          description: >-
            True for a spot-perp `long` direction: the coin must be borrowed on
            margin to sell spot.
        borrowCostIncluded:
          type: boolean
          description: >-
            True when every backtest charges `borrowApr`: a `long` spot-perp
            carry on a venue that publishes its borrow rate for the coin
            (Binance, OKX, Bybit, Gate.io). False otherwise; on a `long` carry a
            warning names why the borrow is left out.
        borrowApr:
          nullable: true
          description: >-
            The venue's current spot-margin borrow APR for the coin (simple, a
            fraction: hourly × 8,760), the rate the spot-perp board nets.
            Charged pro rata over each backtest's covered days; the history
            stores no borrow rates, so a past window is charged today's rate.
            `null` when none is charged.
          type: number
        windowEnd:
          nullable: true
          description: Every backtest's `end`; null when a leg has no usable settlement.
          type: string
          format: date-time
        series:
          type: array
          items:
            $ref: '#/components/schemas/FundingSpreadHistoryPoint'
          description: >-
            The spread at every settlement instant of either leg over the
            requested window's backtest span, ascending.
        backtests:
          type: array
          items:
            $ref: '#/components/schemas/FundingSpreadBacktest'
          description: >-
            One per window: 1, 7, 14, 30 and 60 days where shorter than `days`,
            then `days` itself, ascending.
      required:
        - mode
        - coin
        - direction
        - days
        - legs
        - spot
        - roundTripFees
        - requiresBorrow
        - borrowCostIncluded
        - borrowApr
        - windowEnd
        - series
        - backtests
    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
    FundingSpreadHistoryLeg:
      type: object
      properties:
        role:
          type: string
          enum:
            - perp
            - long
            - short
          description: >-
            `perp` on a spot-perp pair (its side is `direction`); `long` and
            `short` on a cross-exchange pair.
        venue:
          type: string
        contract:
          type: string
          description: The venue's native contract symbol the settlements are read for.
        contractSource:
          type: string
          enum:
            - given
            - resolved
          description: >-
            `given`: the query named the contract. `resolved`: the venue's
            contract for the coin with the largest current open interest
            (unknown open interest last), then the most settlements in the
            window, the latest settlement, the symbol.
        side:
          type: string
          enum:
            - long
            - short
          description: >-
            The position on this perp: a short leg receives positive funding, a
            long leg pays it.
        intervalHours:
          nullable: true
          description: >-
            The interval of the leg's latest settlement, in hours, read from the
            gap to the settlement before it (else the stored interval); null
            when none was readable. Never assumed 8.
          type: number
        settlements:
          type: integer
          description: Settlements read for the leg (the window plus a 2-day margin).
        firstSettledAt:
          nullable: true
          type: string
          format: date-time
        lastSettledAt:
          nullable: true
          type: string
          format: date-time
        takerFee:
          type: number
          description: >-
            The venue's standard perp taker fee per fill
            (src/engine/derive/venue-fees.ts).
      required:
        - role
        - venue
        - contract
        - contractSource
        - side
        - intervalHours
        - settlements
        - firstSettledAt
        - lastSettledAt
        - takerFee
    FundingSpreadHistoryPoint:
      type: object
      properties:
        at:
          type: string
          format: date-time
          description: A settlement instant of either leg.
        spreadApr:
          nullable: true
          description: >-
            The position's funding spread at `at`, annualized simply: Σ over the
            legs of ±(rate × 8,760 / interval hours), + for a short leg, − for a
            long leg. Each leg is read at the settlement whose interval covers
            `at` (legs aligned by time, never by index); null when a leg has no
            covering settlement (a gap, or its interval has not settled yet).
          type: number
        legAprs:
          type: array
          items:
            nullable: true
            type: number
          description: >-
            Each leg's own funding at `at`, annualized (rate × 8,760 / interval
            hours, the venue's sign), in `legs` order; null where the leg is
            uncovered.
        cashflow:
          type: number
          description: >-
            Funding the position received at `at` (fraction of one leg's
            notional, negative when paid): the settlements of the legs that
            settle at this instant.
        cumulativeCarry:
          type: number
          description: >-
            Running sum of `cashflow` from the start of the requested window's
            backtest; fees are not included.
        estimated:
          type: boolean
          description: >-
            True when a leg is read at an estimated settlement at `at`: the
            funding cron's last pre-settlement rate, either not yet replaced by
            the venue's own record by the reconcile job (stored `source:
            inferred`; its `legAprs`, `spreadApr` and `cashflow` can still
            change) or on a venue that publishes no settlement record (stored
            `source: estimate`, LBank and Variational; final). False for
            venue-recorded settlements and for rows stored before provenance was
            tracked (2026-09-26).
      required:
        - at
        - spreadApr
        - legAprs
        - cashflow
        - cumulativeCarry
        - estimated
    FundingSpreadBacktest:
      type: object
      properties:
        days:
          type: integer
          description: 'The window held: the last `days` days to `end`.'
        start:
          type: string
          format: date-time
          description: >-
            Where the backtest starts: `end` − `days`, or later when a leg's
            history begins inside the window.
        end:
          type: string
          format: date-time
          description: >-
            The latest instant every leg's funding is realised: the earliest of
            the legs' last settlements (`windowEnd`).
        coveredDays:
          type: number
          description: >-
            Days from `start` to `end`: the span the figures cover and annualize
            over.
        complete:
          type: boolean
          description: >-
            Every leg has history from the window's start and its settlements
            price at least 90% of the covered span. Coverage only: it does not
            say the settlements are final; see `estimatedSettlements`.
        coverageRatio:
          nullable: true
          description: >-
            The least-covered leg's share of the covered span its settlements
            price (Σ settlement interval ÷ span, at most 1). Missing settlements
            lower it; they are never read as zero funding.
          type: number
          minimum: 0
          maximum: 1
        estimatedSettlements:
          type: integer
          minimum: 0
          description: >-
            Settlements in (start, end], over all legs, that are the funding
            cron's pre-settlement estimates rather than the venue's record
            (series points marked `estimated`). Above 0, `fundingCollected` and
            the figures built on it can still move once those settlements are
            reconciled.
        fundingCollected:
          nullable: true
          description: >-
            Sum of the position's funding settlements in (start, end], fraction
            of one leg's notional; funding is paid at the settlement instant, so
            a settlement counts in full.
          type: number
        fees:
          type: number
          description: >-
            Entry and exit taker fees, fraction of one leg's notional: 2 spot +
            2 perp fills on the venue (spot-perp), 2 fills on each perp
            (cross-exchange). Same as `roundTripFees`.
        netReturn:
          nullable: true
          description: >-
            `fundingCollected − fees`, less `borrowApr × coveredDays / 365` when
            `borrowCostIncluded`.
          type: number
        grossApr:
          nullable: true
          description: '`fundingCollected × 365 / coveredDays`.'
          type: number
        netApr:
          nullable: true
          description: >-
            `netReturn × 365 / coveredDays` (so `borrowApr` lower when
            `borrowCostIncluded`): fees are charged once, so short windows carry
            them heavily.
          type: number
        negativeCarryDays:
          nullable: true
          description: >-
            24-hour periods, counted back from `end` (not UTC days), whose
            settlements summed below zero.
          type: integer
        daysObserved:
          nullable: true
          description: >-
            Full 24-hour periods inside the covered span that held at least one
            settlement.
          type: integer
        maxDrawdown:
          nullable: true
          description: >-
            Largest fall of cumulative funding from its running peak (starting
            at 0 at `start`), fraction of one leg's notional; fees excluded.
          type: number
          minimum: 0
        breakEvenDays:
          nullable: true
          description: >-
            `fees` ÷ the realised average daily funding (net of `borrowApr /
            365` when `borrowCostIncluded`); null unless that is positive.
          type: number
      required:
        - days
        - start
        - end
        - coveredDays
        - complete
        - coverageRatio
        - estimatedSettlements
        - fundingCollected
        - fees
        - netReturn
        - grossApr
        - netApr
        - negativeCarryDays
        - daysObserved
        - maxDrawdown
        - breakEvenDays
  headers:
    X-Request-Id:
      schema:
        type: string
      description: Unique request identifier. Include this value when contacting support.
    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.
    X-Data-Source:
      schema:
        type: string
      description: >-
        The sources behind the rows, comma-separated source ids (e.g.
        `binance,bybit`): `meta.source`. /v1/funding/rates and
        /v1/rwa-perps/rates send the origin tier instead, `live` or `supabase`.
    X-Data-Stale:
      schema:
        type: boolean
      description: >-
        True when the data is past its freshness SLA (`meta.freshness_status` is
        not `fresh`), judged for the answer as a whole; rows keep their own
        staleness flags. /v1/funding/rates and /v1/rwa-perps/rates set it when
        the response is empty or at least one returned row exceeds the published
        freshness target.
    X-Data-As-Of:
      schema:
        type: string
        format: date-time
      description: >-
        When the data was current: `meta.as_of` (the newest live row, the
        snapshot or refresh time, or the fetch time). /v1/funding/rates and
        /v1/rwa-perps/rates: the newest source timestamp in the response.
    X-Freshness-Sla-Seconds:
      schema:
        type: integer
      description: >-
        The dataset's freshness SLA in seconds (`meta.freshness_sla_seconds`):
        the writer's cadence plus one skipped run.
    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'
    NotFound:
      description: >-
        Resource not found, or no v1 route matches the request path.
        Unauthenticated requests to an unknown path return 401 instead, so route
        existence is never disclosed without a key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: https://www.sharpe.ai/errors/resource_not_found
            title: Resource Not Found
            status: 404
            detail: >-
              No v1 endpoint matches this path. Check the path against the
              endpoint list at https://www.sharpe.ai/docs/api-reference.
            request_id: req_a1b2c3d4e5f6g7h8i9j0
            doc_url: https://www.sharpe.ai/docs/errors#error-codes
            suggested_action: >-
              Verify the URL path. See https://www.sharpe.ai/docs for a list of
              available endpoints.
      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.