openapi: 3.1.0
info:
    title: PredictionService API
    version: 1.0.0
paths:
    /api/prediction/v1/list-prediction-markets:
        get:
            tags:
                - PredictionService
            summary: ListPredictionMarkets
            description: ListPredictionMarkets retrieves active prediction markets from Polymarket.
            operationId: ListPredictionMarkets
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: Cursor for next page.
                  required: false
                  schema:
                    type: string
                - name: category
                  in: query
                  description: Optional category filter (e.g., "Politics").
                  required: false
                  schema:
                    type: string
                - name: query
                  in: query
                  description: Optional search query for market titles.
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListPredictionMarketsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidationError'
                default:
                    description: Error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
components:
    schemas:
        Error:
            type: object
            properties:
                message:
                    type: string
                    description: Error message (e.g., 'user not found', 'database connection failed')
            description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
        FieldViolation:
            type: object
            properties:
                field:
                    type: string
                    description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
                description:
                    type: string
                    description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
            required:
                - field
                - description
            description: FieldViolation describes a single validation error for a specific field.
        ValidationError:
            type: object
            properties:
                violations:
                    type: array
                    items:
                        $ref: '#/components/schemas/FieldViolation'
                    description: List of validation violations
            required:
                - violations
            description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
        ListPredictionMarketsRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: Cursor for next page.
                category:
                    type: string
                    description: Optional category filter (e.g., "Politics").
                query:
                    type: string
                    description: Optional search query for market titles.
            description: ListPredictionMarketsRequest specifies filters for retrieving prediction markets.
        ListPredictionMarketsResponse:
            type: object
            properties:
                markets:
                    type: array
                    items:
                        $ref: '#/components/schemas/PredictionMarket'
                pagination:
                    $ref: '#/components/schemas/PaginationResponse'
            description: ListPredictionMarketsResponse contains prediction markets matching the request.
        PredictionMarket:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique market identifier or slug.
                title:
                    type: string
                    description: Market question or title.
                yesPrice:
                    type: number
                    maximum: 1
                    minimum: 0
                    format: double
                    description: Current "Yes" price (0.0 to 1.0, representing probability).
                volume:
                    type: number
                    minimum: 0
                    format: double
                    description: Trading volume in USD.
                url:
                    type: string
                    description: URL to the market page.
                closesAt:
                    type: integer
                    format: int64
                    description: 'Market close time, as Unix epoch milliseconds. Zero if no expiry.. Warning: Values > 2^53 may lose precision in JavaScript'
                category:
                    type: string
                    description: Market category (e.g., "Politics", "Crypto", "Sports").
                source:
                    type: string
                    enum:
                        - MARKET_SOURCE_UNSPECIFIED
                        - MARKET_SOURCE_POLYMARKET
                        - MARKET_SOURCE_KALSHI
                    description: Source platform for prediction market data.
            required:
                - id
            description: PredictionMarket represents a prediction market contract.
        PaginationResponse:
            type: object
            properties:
                nextCursor:
                    type: string
                    description: Cursor for fetching the next page. Empty string indicates no more pages.
                totalCount:
                    type: integer
                    format: int32
                    description: Total count of items matching the query, if known. Zero if the total is unknown.
            description: PaginationResponse contains pagination metadata returned alongside list results.