SharpAPI Futures API

openapi: 3.2.0
info:
  title: Sharp Futures API
  version: 3.28.0
  description: Real-time sports betting odds API with +EV detection, arbitrage, middles, and low-hold opportunities.
  contact:
    name: SharpAPI Support
    url: https://sharpapi.io
    email: support@sharpapi.io
  license:
    name: Proprietary
    url: https://sharpapi.io/terms
  x-generated-at: '2026-10-13T20:02:34Z'
  x-commit-sha: 850f5cb
servers:
- url: https://api.sharpapi.io/api/v1
  description: Production
security:
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Futures
  description: Futures markets and odds
paths:
  /futures:
    get:
      operationId: listFuturesMarkets
      summary: List futures markets
      description: Returns available futures markets with metadata, merged across all sportsbooks. Public endpoint.
      tags:
      - Futures
      security:
      - {}
      - ApiKeyHeader: []
      parameters:
      - name: sport
        in: query
        description: Filter by sport
        schema:
          type: string
      - name: league
        in: query
        description: Filter by league
        schema:
          type: string
      - name: future_type
        in: query
        description: Filter by futures type
        schema:
          type: string
          enum:
          - TEAM
          - PLAYER
          - OVER_UNDER
          - YES_NO
      responses:
        '200':
          description: List of futures markets
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/DataEnvelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/FutureMarket'
              example:
                success: true
                data:
                - market_id: championship_winner
                  display_name: NBA Championship Winner
                  sport: basketball
                  league: nba
                  future_type: TEAM
                  selection_count: 30
                  books_available:
                  - draftkings
                  - fanduel
                  - betmgm
  /futures/odds:
    get:
      operationId: listFuturesOdds
      summary: Get futures odds
      description: Returns cross-book odds for a specific futures market. Requires authentication.
      tags:
      - Futures
      parameters:
      - name: future_id
        in: query
        required: true
        description: Futures market ID
        schema:
          type: string
        example: championship_winner
      - name: sportsbook
        in: query
        description: Filter by sportsbook (comma-separated)
        schema:
          type: string
      - name: sport
        in: query
        schema:
          type: string
      - name: league
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Paginated futures odds
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedEnvelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/FutureOdds'
              example:
                success: true
                data:
                - selection: Boston Celtics
                  sportsbook: draftkings
                  odds_american: 350
                  odds_decimal: 4.5
                  probability: 0.2222
                  future_type: TEAM
                  future_market_id: championship_winner
                  future_market_name: NBA Championship Winner
                  sport: basketball
                  league: nba
                  event_start_time: '2026-06-15T00:00:00Z'
                  timestamp: '2026-03-09T14:00:00Z'
                pagination:
                  limit: 100
                  offset: 0
                  has_more: false
                  next_offset: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DataEnvelope:
      type: object
      description: Standard shape for non-paginated responses. Emitted by endpoints that return a single resource or a small fixed list. No `success` flag — HTTP status codes indicate success/failure.
      required:
      - data
      - updated_at
      properties:
        data: {}
        updated_at:
          type: string
          format: date-time
          description: Server emit time (RFC 3339).
    Pagination:
      type: object
      required:
      - limit
      - offset
      - has_more
      - next_offset
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
          description: Length of the current `data` page.
          example: 50
        total:
          type: integer
          description: Size of the full matching set. Emitted where the endpoint computes it (`/events` does); `/odds` omits it.
          example: 1247
        has_more:
          type: boolean
        next_offset:
          type:
          - integer
          - 'null'
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - missing_api_key
              - invalid_api_key
              - unauthorized
              - forbidden
              - tier_restricted
              - rate_limited
              - invalid_request
              - validation_error
              - not_found
              - streaming_not_available
              - stream_limit_exceeded
              - service_unavailable
              - internal_error
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            docs:
              type: string
              format: uri
              description: Link to relevant documentation
            tier:
              type: string
              description: Current subscription tier
            required_tier:
              type: string
              description: Minimum tier required for this feature
            retry_after:
              type: integer
              description: Unix timestamp (ms) when request can be retried
            retryAfter:
              type: integer
              description: Seconds until the request can be retried — same instant as retry_after, different unit and casing
            max_books:
              type: integer
            requested_books:
              type: integer
    PaginatedEnvelope:
      type: object
      description: Standard shape for paginated list responses. No `success` flag — HTTP status codes indicate success/failure.
      required:
      - data
      - pagination
      - updated_at
      properties:
        data:
          type: array
          items: {}
        pagination:
          $ref: '#/components/schemas/Pagination'
        updated_at:
          type: string
          format: date-time
          description: Server emit time (RFC 3339).
    FutureOdds:
      type: object
      required:
      - selection
      - sportsbook
      - odds_american
      - odds_decimal
      - probability
      - future_type
      - future_market_id
      - future_market_name
      - sport
      - league
      - event_start_time
      - timestamp
      properties:
        selection:
          type: string
          example: Boston Celtics
        sportsbook:
          type: string
          example: draftkings
        odds_american:
          type: number
          example: 350
        odds_decimal:
          type: number
          example: 4.5
        probability:
          type: number
          example: 0.2222
        line:
          type:
          - number
          - 'null'
        future_type:
          type: string
        future_market_id:
          type: string
        future_market_name:
          type: string
        sport:
          type: string
        league:
          type: string
        event_start_time:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
    FutureMarket:
      type: object
      required:
      - market_id
      - display_name
      - sport
      - league
      - future_type
      - selection_count
      properties:
        market_id:
          type: string
          example: championship_winner
        display_name:
          type: string
          example: NBA Championship Winner
        sport:
          type: string
          example: basketball
        league:
          type: string
          example: nba
        future_type:
          type: string
          enum:
          - TEAM
          - PLAYER
          - OVER_UNDER
          - YES_NO
        selection_count:
          type: integer
          description: Number of available selections
        books_available:
          type: array
          items:
            type: string
          description: Sportsbooks offering this futures market
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: invalid_request
              message: Missing required parameter
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing:
              summary: Missing API key
              value:
                error:
                  code: missing_api_key
                  message: API key required
                  docs: https://docs.sharpapi.io/en/authentication#authentication-methods
            invalid:
              summary: Invalid API key
              value:
                error:
                  code: invalid_api_key
                  message: Invalid API key
                  docs: https://docs.sharpapi.io/en/authentication#authentication-methods
  parameters:
    offset:
      name: offset
      in: query
      description: Number of results to skip
      schema:
        type: integer
        default: 0
        minimum: 0
    limit:
      name: limit
      in: query
      description: Maximum results per page
      schema:
        type: integer
        default: 50
        minimum: 0
        maximum: 500
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key passed in the `X-API-Key` header
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the `Authorization` header
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key as query parameter (for SSE/EventSource only)