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

# Dated futures basis scanner

> Returns cash-and-carry rows priced at spot ask and futures bid across Binance, OKX and Bybit (Deribit has no spot leg, so it appears only in calendar spreads). Rows at least 3 days from expiry rank first; within them executable rows at the requested notional, then rows executable on a live read (`snapshot_quote`), then the rest, each by fee-adjusted net APR. Reference-only rows are omitted. Days to expiry are recomputed from the expiry on every request. The per-coin aggregate covers only contracts at least three days from expiry.



## OpenAPI

````yaml /openapi.json get /v1/arbitrage/dated-futures-basis
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/dated-futures-basis:
    get:
      tags:
        - Arbitrage
      summary: Dated futures basis scanner
      description: >-
        Returns cash-and-carry rows priced at spot ask and futures bid across
        Binance, OKX and Bybit (Deribit has no spot leg, so it appears only in
        calendar spreads). Rows at least 3 days from expiry rank first; within
        them executable rows at the requested notional, then rows executable on
        a live read (`snapshot_quote`), then the rest, each by fee-adjusted net
        APR. Reference-only rows are omitted. Days to expiry are recomputed from
        the expiry on every request. The per-coin aggregate covers only
        contracts at least three days from expiry.
      operationId: getArbitrageDatedFuturesBasis
      parameters:
        - $ref: '#/components/parameters/ArbitrageCoinParam'
        - $ref: '#/components/parameters/ArbitrageExchangesParam'
        - $ref: '#/components/parameters/ArbitrageMinNetParam'
        - $ref: '#/components/parameters/ArbitrageMinOiUsdParam'
        - $ref: '#/components/parameters/ArbitrageMinVolumeUsdParam'
        - $ref: '#/components/parameters/ArbitrageMinDepthUsdParam'
        - $ref: '#/components/parameters/ArbitrageMarginTypeParam'
        - $ref: '#/components/parameters/ArbitrageNotionalParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CursorParam'
        - $ref: '#/components/parameters/FormatParam'
      responses:
        '200':
          description: Scanner rows returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatedFuturesBasisResponse'
          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'
        '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:
    ArbitrageCoinParam:
      name: coin
      in: query
      description: Optional base coin ticker, for example BTC, ETH, or SOL.
      schema:
        type: string
        minLength: 1
    ArbitrageExchangesParam:
      name: exchanges
      in: query
      description: Comma-separated exchange filter, for example Binance,Bybit,OKX.
      schema:
        type: string
    ArbitrageMinNetParam:
      name: minNet
      in: query
      description: >-
        Minimum of the board's net figure, as a fraction (0.05 is 5%): `netApr`
        on the dated basis board, `netRollApy` on the calendar board,
        `netCarryApr` (the fee-adjusted annualized net carry, not the edge to
        expiry) on the perp-dated carry board, `netReturn` (per trip, not
        annualized) on the CEX transfer board.
      schema:
        type: number
    ArbitrageMinOiUsdParam:
      name: minOiUsd
      in: query
      description: Minimum open interest in USD.
      schema:
        type: number
        minimum: 0
    ArbitrageMinVolumeUsdParam:
      name: minVolumeUsd
      in: query
      description: Minimum 24h futures or spot volume in USD.
      schema:
        type: number
        minimum: 0
    ArbitrageMinDepthUsdParam:
      name: minDepthUsd
      in: query
      description: Minimum executable depth in USD when available.
      schema:
        type: number
        minimum: 0
    ArbitrageMarginTypeParam:
      name: marginType
      in: query
      description: Futures margin filter.
      schema:
        type: string
        enum:
          - linear
          - inverse
          - both
    ArbitrageNotionalParam:
      name: notional
      in: query
      description: >-
        Position notional in USD. On the dated-futures basis, calendar-spread
        and perp-dated carry scanners a row is executable only when its book
        depth (level 1 on the stored snapshot; on a live read a top-20 walk
        where level 1 is thin, the side then priced at that walk's VWAP), any
        reported open interest and its 24h volume are at least this notional
        (and its quotes are at most 10 minutes old). The CEX spot transfer
        scanner sizes its order-book fills with it.
      schema:
        default: 10000
        type: number
        minimum: 0
        exclusiveMinimum: true
        maximum: 1000000000
    LimitParam:
      name: limit
      in: query
      description: Maximum number of rows returned.
      schema:
        default: 100
        type: integer
        minimum: 1
        maximum: 1000
    CursorParam:
      name: cursor
      in: query
      description: Opaque cursor from the previous page.
      schema:
        type: string
    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:
    DatedFuturesBasisResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                rows:
                  type: array
                  items:
                    $ref: '#/components/schemas/FuturesBasisRow'
                scannerMeta:
                  $ref: '#/components/schemas/ScannerMeta'
                pagination:
                  nullable: true
                  allOf:
                    - $ref: '#/components/schemas/PaginationInfo'
                aggregate:
                  nullable: true
                  type: array
                  items:
                    $ref: '#/components/schemas/FuturesBasisAggregate'
              required:
                - rows
                - scannerMeta
                - pagination
          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
    FuturesBasisRow:
      type: object
      properties:
        rank:
          type: integer
        coin:
          type: string
        spotVenue:
          type: string
        futuresVenue:
          type: string
        contract:
          type: string
        expiry:
          type: string
          format: date-time
        days:
          type: number
        spotAsk:
          type: number
        futureBid:
          type: number
        basisUsd:
          type: number
        basis:
          type: number
        annualizedBasis:
          type: number
        netApr:
          type: number
        volume24hUsd:
          nullable: true
          type: number
        openInterestUsd:
          nullable: true
          type: number
        oiToVolume:
          nullable: true
          type: number
        depthUsd:
          nullable: true
          type: number
        executionStatus:
          type: string
          enum:
            - executable
            - indicative
          description: >-
            Whether the row can be traded at the requested notional on the
            figures shown. "executable" needs all of: a snapshot inside the
            freshness SLA; book depth behind the spot ask and futures bid of at
            least notional (level 1 on a stored snapshot row,
            `depth_beyond_top_of_book` when thinner; on a live read a side
            thinner at level 1 than the default notional is walked 20 levels
            deep and priced at that walk's VWAP); no reported open interest on
            the contract below notional (unknown open interest does not demote);
            24h volume of at least notional; a non-negative basis; and quotes at
            most 10 minutes old (a live read, not the hourly snapshot).
            Otherwise "indicative" with `indicativeReason`: every figure is
            kept. Indicative rows sort below executable ones.
        indicativeReason:
          description: >-
            Why the row is indicative, the first failing check in this order:
            `stale_snapshot` (past the term-structure SLA), `no_perp_book`
            (carry: the perp has no bid/ask for its own contract), `no_depth`,
            `depth_below_notional` (the top-20 book walked is thinner than the
            notional), `depth_beyond_top_of_book` (the depth known is level 1
            only and thinner than the notional: the rest would fill beyond the
            quote the row is priced at), `oi_below_notional`, `no_volume` (no
            24h volume, or less than the notional), `backwardation_needs_borrow`
            (basis: a negative basis, and calendar: a backwardated Sell Near /
            Buy Far lock-in; the reverse trade needs a spot borrow the board
            does not price), `snapshot_quote` (every other check passes but the
            quotes are older than 10 minutes: executable on a live read). Null
            when executable. Absent on answers before 2026-09-30.
          nullable: true
          type: string
          enum:
            - stale_snapshot
            - no_perp_book
            - no_depth
            - depth_below_notional
            - depth_beyond_top_of_book
            - oi_below_notional
            - no_volume
            - backwardation_needs_borrow
            - snapshot_quote
        nearExpiry:
          description: >-
            Under 3 days to expiry: the round-trip fee annualized over the days
            left dominates the APR. Served, ranked after every row at least 3
            days out. Absent on answers before 2026-09-30.
          type: boolean
        fees:
          type: number
          description: >-
            Round-trip fees: 2 spot and 2 dated-futures taker fills at the
            venue's standard fee (engine/derive/venue-fees.ts), a fraction of
            the notional, not annualized (0.003 is 0.3%).
        marginType:
          type: string
          enum:
            - linear
            - inverse
        updatedAt:
          type: string
          format: date-time
        isStale:
          type: boolean
      required:
        - rank
        - coin
        - spotVenue
        - futuresVenue
        - contract
        - expiry
        - days
        - spotAsk
        - futureBid
        - basisUsd
        - basis
        - annualizedBasis
        - netApr
        - volume24hUsd
        - openInterestUsd
        - oiToVolume
        - depthUsd
        - executionStatus
        - fees
        - marginType
        - updatedAt
        - isStale
    ScannerMeta:
      type: object
      properties:
        kind:
          type: string
          enum:
            - dated-futures-basis
            - futures-calendar-spread
            - perp-dated-carry
            - cex-spot-transfer
        status:
          type: string
          enum:
            - ok
            - unavailable
        generatedAt:
          type: string
          format: date-time
        updatedAt:
          nullable: true
          type: string
          format: date-time
        stale:
          type: boolean
          description: >-
            True when `updatedAt` is older than `freshnessSlaSeconds`. Each row
            carries its own `isStale` by the same threshold.
        freshnessSlaSeconds:
          type: integer
          description: >-
            Seconds a row's snapshot stays fresh: 7,200 on the dated basis,
            calendar and carry boards (the term-structure SLA; the envelope's
            `freshness_sla_seconds` is 7,200 when the hourly term structure
            answered and 600 when the 5-minute dated-quotes snapshot did, its
            `dataset_id` says which), 60 on the CEX transfer board (its order
            books, the envelope's `freshness_sla_seconds`; transfer networks are
            judged on 10 minutes per row).
        source:
          type: string
          enum:
            - supabase
            - supabase-stale
            - live
            - unavailable
          description: >-
            Where the board's rows came from: the stored hourly term-structure
            snapshot, a stored snapshot past its SLA, the venues read live (on
            request, or by the 5-minute dated-quotes snapshot the
            arbitrage-boards cron writes: then the envelope's `dataset_id` is
            `arbitrage_dated_quotes` and `served_from` is `snapshot`; always
            `live` on the CEX transfer board), or nothing. The upstream source
            ids are in the X-Data-Source header.
        notionalUsd:
          type: number
        rowCount:
          type: integer
        supportedCoins:
          type: array
          items:
            type: string
          description: >-
            The coins the board covers: the supported basis coins on the dated
            boards; the coins the scan fetched on the CEX transfer board.
        warnings:
          type: array
          items:
            type: string
        transferScan:
          $ref: '#/components/schemas/CexTransferScan'
      required:
        - kind
        - status
        - generatedAt
        - updatedAt
        - stale
        - freshnessSlaSeconds
        - source
        - notionalUsd
        - rowCount
        - supportedCoins
        - warnings
    PaginationInfo:
      type: object
      properties:
        cursor:
          nullable: true
          type: string
        has_more:
          type: boolean
        total:
          type: integer
          minimum: 0
      required:
        - cursor
        - has_more
        - total
    FuturesBasisAggregate:
      type: object
      properties:
        coin:
          type: string
        totalOpenInterestUsd:
          type: number
        oiWeightedApr:
          type: number
        bestVenue:
          type: string
        bestApr:
          type: number
        contractCount:
          type: integer
      required:
        - coin
        - totalOpenInterestUsd
        - oiWeightedApr
        - bestVenue
        - bestApr
        - contractCount
      description: >-
        Per-coin summary over the ranked contracts at least three days from
        expiry (one day until 2026-09-30). Contracts closer to expiry stay in
        rows but are left out, because a round-trip fee annualized over a few
        days dominates the APR; a coin with no qualifying contract has no entry.
    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
    CexTransferScan:
      type: object
      properties:
        coinsScanned:
          type: integer
        scannedCoins:
          type: array
          items:
            type: string
        venuesAnswering:
          type: integer
          description: >-
            Selected venues that returned at least one order book and one
            transfer network.
        venues:
          type: array
          items:
            type: object
            properties:
              exchange:
                type: string
              status:
                type: string
                enum:
                  - ok
                  - not_live
                  - no_books
                  - no_networks
                  - failed
                description: >-
                  not_live: the venue's public spot ticker shows no live book
                  (left out of coverage); failed/no_books/no_networks make the
                  answer degraded.
            required:
              - exchange
              - status
        routesEvaluated:
          type: integer
          description: >-
            Directed (coin, buy venue, sell venue) routes with a computed net:
            both books fill the notional on one common open network.
        routesProfitable:
          type: integer
          description: Evaluated routes netting above zero after fees.
        bestNetReturn:
          nullable: true
          description: >-
            Best `netReturn` over evaluated routes, a fraction of the notional
            per trip (0.001 is 0.1%); null when none was evaluated.
          type: number
      required:
        - coinsScanned
        - scannedCoins
        - venuesAnswering
        - venues
        - routesEvaluated
        - routesProfitable
        - bestNetReturn
  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.
    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.