Jupiter Events API

openapi: 3.2.0
info:
  title: Jupiter Prediction Market Events API
  version: 1.0.0
  description: Jupiter Prediction Market API Schema
servers:
- url: https://api.jup.ag/prediction/v1
  description: Jupiter Prediction Market API Endpoint
security:
- ApiKeyAuth: []
tags:
- name: Events
paths:
  /events/search:
    get:
      tags:
      - Events
      summary: Search events
      description: Full-text search of prediction events by title. Returns the matching events with pagination. Use `provider=bisonfi` for Jupiter Forecast markets.
      parameters:
      - schema:
          type: string
          enum:
          - kalshi
          - polymarket
          - bisonfi
          default: polymarket
          description: Data provider for events (defaults to polymarket). Use `bisonfi` for Jupiter Forecast markets.
        required: false
        description: Data provider for events (defaults to polymarket). Use `bisonfi` for Jupiter Forecast markets.
        name: provider
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 200
          description: Search term matched against event titles
        required: true
        description: Search term matched against event titles
        name: query
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 20
        required: false
        description: Maximum number of events to return, 1 to 20.
        name: limit
        in: query
      responses:
        '200':
          description: Events matching the search query
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - data
      operationId: getEventsSearch
      x-operation-id-source: derived
  /events:
    get:
      tags:
      - Events
      summary: List events
      description: Paginated list of prediction events, each holding one or more binary YES/NO markets. Filter by provider, category, subcategory, tags and status (`filter`), sort by volume or start time, and set `includeMarkets=true` to nest each event's markets in the response. Paginate with the `start` and `end` indexes.
      parameters:
      - schema:
          type: string
          enum:
          - kalshi
          - polymarket
          - bisonfi
          default: polymarket
          description: Data provider for events (defaults to polymarket). Use `bisonfi` for Jupiter Forecast markets.
        required: false
        description: Data provider for events (defaults to polymarket). Use `bisonfi` for Jupiter Forecast markets.
        name: provider
        in: query
      - schema:
          type:
          - boolean
          - 'null'
        required: false
        description: Set to `true` to nest each event's markets in the response.
        name: includeMarkets
        in: query
      - schema:
          type: boolean
        required: false
        description: Include all allowed sports market types (moneyline, spread, totals) and extra (e.g. Saba) markets mapped onto Polymarket events. Defaults to false (moneyline only). F1 events always include every sportsMarketType.
        name: includeAllMarkets
        in: query
      - schema:
          type:
          - integer
          - 'null'
          minimum: 0
        required: false
        description: Pagination start index of the page to return.
        name: start
        in: query
      - schema:
          type:
          - integer
          - 'null'
          minimum: 0
        required: false
        description: Pagination end index of the page to return.
        name: end
        in: query
      - schema:
          type: string
          enum:
          - all
          - crypto
          - sports
          - politics
          - esports
          - culture
          - economics
          - tech
        required: false
        description: Event category. `all` returns every category.
        name: category
        in: query
      - schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
          - type: string
        required: false
        description: Subcategory within the chosen category.
        name: subcategory
        in: query
      - schema:
          type: string
          enum:
          - volume
          - beginAt
          description: Sort field for events (volume or begin time). Pair with sortDirection to control ascending/descending.
        required: false
        description: Sort field for events (volume or begin time). Pair with sortDirection to control ascending/descending.
        name: sortBy
        in: query
      - schema:
          type: string
          enum:
          - asc
          - desc
          description: Direction for the chosen sort field. Defaults to desc for volume and asc for beginAt.
        required: false
        description: Direction for the chosen sort field. Defaults to desc for volume and asc for beginAt.
        name: sortDirection
        in: query
      - schema:
          type: string
          enum:
          - new
          - live
          - trending
          - upcoming
          description: Apply named filters. Use `new` for events created in the last 24 hours, `live` for events that have begun, `trending` for events with recent trade activity, and `upcoming` for events that have not begun yet.
        required: false
        description: Apply named filters. Use `new` for events created in the last 24 hours, `live` for events that have begun, `trending` for events with recent trade activity, and `upcoming` for events that have not begun yet.
        name: filter
        in: query
      - schema:
          type: string
          description: Filter events by tag (e.g. `soccer`).
        required: false
        description: Filter events by tag (e.g. `soccer`).
        name: tags
        in: query
      responses:
        '200':
          description: List of all events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - data
                - pagination
      operationId: getEvents
      x-operation-id-source: derived
  /events/{eventId}:
    get:
      tags:
      - Events
      summary: Get event
      description: One event by id, with its category, tags, metadata, volume and live score. Set `includeMarkets=true` to nest its markets.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Event identifier
        required: true
        description: Event identifier
        name: eventId
        in: path
      - schema:
          type:
          - boolean
          - 'null'
        required: false
        description: Set to `true` to nest the event's markets in the response.
        name: includeMarkets
        in: query
      - schema:
          type: boolean
        required: false
        description: Include all allowed sports market types (moneyline, spread, totals) and extra (e.g. Saba) markets mapped onto Polymarket events. Defaults to false (moneyline only). F1 events always include every sportsMarketType.
        name: includeAllMarkets
        in: query
      responses:
        '200':
          description: Event data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getEventsByEventId
      x-operation-id-source: derived
  /events/suggested/{pubkey}:
    get:
      tags:
      - Events
      summary: Get suggested events
      description: Events suggested for a wallet, derived from that wallet's past order activity.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Order public key to base suggested events on
        required: true
        description: Order public key to base suggested events on
        name: pubkey
        in: path
      - schema:
          type: string
          enum:
          - kalshi
          - polymarket
          - bisonfi
          default: polymarket
          description: Data provider for events (defaults to polymarket). Use `bisonfi` for Jupiter Forecast markets.
        required: false
        description: Data provider for events (defaults to polymarket). Use `bisonfi` for Jupiter Forecast markets.
        name: provider
        in: query
      responses:
        '200':
          description: Suggested events derived from the user's order activity
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                required:
                - data
      operationId: getEventsSuggestedByPubkey
      x-operation-id-source: derived
  /events/scores:
    get:
      tags:
      - Events
      summary: Get live scores
      description: Latest live scores for several sports events in one call. Pass the event ids as a comma-separated `eventIds` list; events without a score are omitted from the response.
      parameters:
      - schema:
          type: string
          minLength: 1
          example: POLY-351731,POLY-30615
        required: true
        description: Comma-separated event IDs to fetch live scores for (max 100)
        name: eventIds
        in: query
      responses:
        '200':
          description: Latest live scores for the given event IDs. Events without a score row are omitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GameScore'
                required:
                - data
      operationId: getEventsScores
      x-operation-id-source: derived
  /events/{eventId}/score:
    get:
      tags:
      - Events
      summary: Get event score
      description: 'Latest live score for one sports event: teams, score, period, elapsed time and status. Returns `null` when the event has no score.'
      parameters:
      - schema:
          type: string
          minLength: 1
        required: true
        description: Event identifier
        name: eventId
        in: path
      responses:
        '200':
          description: Latest live score for the event, or null if no score row exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameScore'
      operationId: getEventsByEventIdScore
      x-operation-id-source: derived
components:
  schemas:
    Event:
      type: object
      properties:
        eventId:
          type: string
          description: Application-level identifier
        isActive:
          type: boolean
          description: Whether the event is active (listed on events)
        isLive:
          type: boolean
          description: Whether the event is currently live
        category:
          type: string
          description: 'The category for the event, allowed values: all, crypto, sports, politics, esports, culture, economics, tech'
        subcategory:
          type: string
          description: The subcategory for the event
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the event
        metadata:
          $ref: '#/components/schemas/EventMetadata'
        markets:
          type: array
          items:
            $ref: '#/components/schemas/Market'
        volumeUsd:
          type: string
          description: Total volume for the event in micro USD
        volume24hr:
          type: string
          description: Rolling 24-hour volume in micro USD
        liveScore:
          description: Live score data for sports events; null when no score is available
        closeCondition:
          type: string
          description: Close condition for the event
        beginAt:
          type:
          - string
          - 'null'
          description: Unix timestamp (seconds) when the event begins
        rulesPdf:
          type: string
          description: Document to full rules for the event
      required:
      - eventId
      - isActive
      - isLive
      - category
      - subcategory
      - volumeUsd
      - closeCondition
      - beginAt
      - rulesPdf
    Market:
      type: object
      description: Market fields are returned flat (there is no nested `metadata` object).
      properties:
        marketId:
          type: string
          description: Market identifier
        eventId:
          type: string
          description: Parent event identifier
        provider:
          type: string
          enum:
          - polymarket
          - gx
          - bisonfi
          description: Market data provider
        title:
          type: string
          description: Market title
        status:
          type: string
          enum:
          - open
          - closed
          - cancelled
          description: Current market status
        result:
          type:
          - string
          - 'null'
          enum:
          - 'yes'
          - 'no'
          description: Market result. null until resolved, then "yes" or "no"
        openTime:
          type: number
          description: Unix timestamp (seconds) when the market opens
        closeTime:
          type: number
          description: Unix timestamp (seconds) when the market closes
        resolveAt:
          oneOf:
          - type: string
          - type: number
          description: When the market resolved. null while open; returned as an ISO 8601 string once resolved
        marketResultPubkey:
          type:
          - string
          - 'null'
          description: Public key of the market result account
        imageUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Market image URL
        rulesPrimary:
          type: string
          description: Primary resolution rules
        rulesSecondary:
          type: string
          description: Secondary resolution rules
        outcomes:
          type: array
          items:
            type: string
          description: Outcome labels for the market
        marketOptions:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              buyYes:
                type: boolean
          description: Selectable options for team or multi-outcome markets
        clobTokenIds:
          type: array
          items:
            type: string
          description: Underlying CLOB token IDs (provider-specific)
        isTeamMarket:
          type: boolean
          description: True for team or sports markets
        team:
          type:
          - object
          - 'null'
          description: Team metadata, present for team markets
        sportsLine:
          type:
          - number
          - 'null'
          description: Sports line or handicap, when applicable
        sportsMarketType:
          type:
          - string
          - 'null'
          description: Sports market type, when applicable
        outcomeMint:
          type:
          - string
          - 'null'
          description: Outcome token mint for this market side (Jupiter Forecast / bisonfi). Buying the market gives you this token; it can also be traded directly through the Swap API.
        outcomeTokenProgram:
          type:
          - string
          - 'null'
          description: Token program that owns `outcomeMint`. Jupiter Forecast uses Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`).
        marketPda:
          type:
          - string
          - 'null'
          description: On-chain market account (Jupiter Forecast / bisonfi).
        outcomeSide:
          type:
          - string
          - 'null'
          description: Outcome side for Jupiter Forecast markets (`up` or `down`).
        tradable:
          type: boolean
          description: Whether this Jupiter Forecast side can be traded right now. The Discover example filters on this field.
        lifecycleStatus:
          type: string
          enum:
          - open
          - resolving
          - settled
          description: 'Jupiter Forecast trading lifecycle: `open`, `resolving` after the close time, or `settled` after issuer resolution. Only `open` is tradable.'
        pricing:
          $ref: '#/components/schemas/MarketPricing'
      required:
      - marketId
      - status
      - result
      - openTime
      - closeTime
      - resolveAt
    Pagination:
      type: object
      properties:
        start:
          type: integer
          minimum: 0
        end:
          type: integer
          minimum: 0
        total:
          type: integer
          minimum: 0
        hasNext:
          type: boolean
      required:
      - start
      - end
      - total
      - hasNext
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - invalid_request_error
          - authentication_error
          - permission_error
          - idempotency_error
          - rate_limit_error
          - api_error
        message:
          type: string
        code:
          type: string
        param:
          type: string
        request_id:
          type: string
        doc_url:
          type: string
      required:
      - type
      - message
      - request_id
    EventMetadata:
      type: object
      properties:
        eventId:
          type: string
        title:
          type: string
        subtitle:
          type: string
        slug:
          type: string
        series:
          type: string
        closeTime:
          type: string
          description: ISO 8601 formatted close time
        imageUrl:
          type: string
          format: uri
        isLive:
          type: boolean
      required:
      - eventId
    MarketPricing:
      type: object
      properties:
        buyYesPriceUsd:
          type:
          - number
          - 'null'
        buyNoPriceUsd:
          type:
          - number
          - 'null'
        sellYesPriceUsd:
          type:
          - number
          - 'null'
        sellNoPriceUsd:
          type:
          - number
          - 'null'
        volume:
          type: number
          description: Trading volume for this market
    GameScore:
      type: object
      properties:
        eventId:
          type: string
          description: Application-level event identifier
        gameId:
          type: string
        leagueAbbreviation:
          type:
          - string
          - 'null'
        homeTeam:
          type:
          - string
          - 'null'
        awayTeam:
          type:
          - string
          - 'null'
        score:
          type:
          - string
          - 'null'
          description: Raw score string from the provider (e.g. "2-0")
        period:
          type:
          - string
          - 'null'
          description: Current period (e.g. "2H")
        elapsed:
          type:
          - string
          - 'null'
          description: Elapsed time within the game (e.g. "90")
        status:
          type:
          - string
          - 'null'
          description: Provider status string (e.g. "InProgress")
        live:
          type: boolean
          description: True while the game is in progress
        ended:
          type: boolean
          description: True once the game has finished
        finishedTimestamp:
          type:
          - string
          - 'null'
          description: ISO 8601 timestamp when the game finished, if ended
        updatedAt:
          type: string
          description: ISO 8601 timestamp of the last score update
      required:
      - eventId
      - gameId
      - live
      - ended
      - updatedAt
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Get API key via https://developers.jup.ag/portal
x-provenance:
  method: harvested
  publisher: Jupiter
  source: https://developers.jup.ag/docs/openapi-spec/prediction/prediction.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)