docs/api/PredictionService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
openapi: 3.1.0
info:
title: PredictionService API
version: 1.0.0
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
servers:
- url: https://api.worldmonitor.app
paths:
/api/prediction/v1/list-prediction-markets:
get:
tags:
- PredictionService
summary: ListPredictionMarkets
description: |-
ListPredictionMarkets retrieves active prediction markets from seeded market snapshots.
Empty markets with fetched_at=0 or data_available=false means the seed
snapshot is unavailable/degraded, not that there are confirmed zero markets.
operationId: ListPredictionMarkets
parameters:
- name: page_size
in: query
description: Maximum items per page (1-100).
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "next-page-token"
schema:
type: string
- name: category
in: query
description: Optional category filter (e.g., "Politics").
required: false
example: "ai"
schema:
type: string
enum:
- 'ai'
- 'tech'
- 'crypto'
- 'science'
- 'economy'
- 'fed'
- 'inflation'
- 'interest-rates'
- 'recession'
- 'trade'
- 'tariffs'
- 'debt-ceiling'
- name: query
in: query
description: Optional search query for market titles.
required: false
example: "supply chain risk"
schema:
type: string
- name: min_liquidity
in: query
description: |-
Optional minimum liquidity (resting order-book depth in USD). When above 0,
only markets with liquidity at or above this value are returned; markets
without a liquidity value are dropped. Applied before page_size.
required: false
example: 1.5
schema:
type: number
format: double
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"dataAvailable": true
"fetchedAt": 1717200000000
"markets":
- "category": "cs.AI"
"closesAt": 1717200000000
"id": "example-id"
"liquidity": 1.5
"source": "MARKET_SOURCE_POLYMARKET"
"title": "example"
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/ListPredictionMarketsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
components:
securitySchemes:
WorldMonitorKey:
type: apiKey
in: header
name: X-WorldMonitor-Key
description: User-issued WorldMonitor API key.
ApiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key).
schemas:
JmespathProjectionError:
description: Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits.
properties:
_jmespath_error:
description: Projection error discriminator and details.
type: string
original_keys:
description: Top-level keys or shape of the unprojected response.
items:
type: string
type: array
required:
- _jmespath_error
- original_keys
type: object
UnauthorizedError:
type: object
properties:
error:
type: string
description: Human-readable error message.
required:
- error
description: Returned when the API key is missing, malformed, or lacks current API access.
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.
BillingVerificationError:
type: object
description: "Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After."
properties:
error:
type: string
description: Human-readable billing-verification failure reason.
code:
type: string
enum:
- renewal_verification_pending
- renewal_verification_failed
- entitlement_verification_unavailable
description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.
required:
- error
- code
InvalidRequestBodyError:
type: object
description: Returned when a JSON POST request body is empty or malformed.
properties:
message:
type: string
description: Invalid request body
required:
- message
GatewayError:
type: object
description: Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks.
properties:
error:
oneOf:
- type: string
- type: object
additionalProperties: true
description: Gateway error reason or structured gateway failure details.
required:
- error
RateLimitError:
type: object
description: Returned when a gateway or handler rate limit rejects the request.
properties:
error:
type: string
description: Human-readable rate-limit failure reason.
required:
- error
ForbiddenError:
type: object
properties:
error:
type: string
description: Human-readable entitlement failure reason.
code:
type: string
enum:
- subscription_lapsed
description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint.
currentTier:
type: integer
format: int32
description: Caller entitlement tier when known.
planKey:
type: string
description: Caller plan key when known.
required:
- error
description: Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier.
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.
Accepted but currently ignored; no-op until this handler supports the parameter.
category:
type: string
description: Optional category filter (e.g., "Politics").
query:
type: string
description: Optional search query for market titles.
minLiquidity:
type: number
minimum: 0
format: double
description: |-
Optional minimum liquidity (resting order-book depth in USD). When above 0,
only markets with liquidity at or above this value are returned; markets
without a liquidity value are dropped. Applied before page_size.
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'
fetchedAt:
type: integer
format: int64
description: |-
Time the seed snapshot was fetched, as Unix epoch milliseconds. A value of
0 means the snapshot is unavailable/degraded, not that there are confirmed
zero matching markets.. Warning: Values > 2^53 may lose precision in JavaScript
dataAvailable:
type: boolean
description: |-
True when markets were evaluated against a seed snapshot. False means an
empty payload is graceful degradation because the snapshot is unavailable.
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.
yesPriceChange24h:
type: number
maximum: 1
minimum: -1
format: double
description: Upstream 24-hour Yes price change on the probability scale. Absent if unavailable.
yesPriceChange7d:
type: number
maximum: 1
minimum: -1
format: double
description: Upstream 7-day Yes price change on the probability scale. Polymarket only.
liquidity:
type: number
minimum: 0
format: double
description: |-
Resting order-book depth in USD, measured per venue: Polymarket CLOB
liquidity, or the sum of price times size over every Kalshi yes and no bid.
Absent when the venue reports none or the order book could not be fetched.
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.