> ## Documentation Index > Fetch the complete documentation index at: https://docs.predictamarkets.com/llms.txt > Use this file to discover all available pages before exploring further. # List Markets > Returns a paginated list of markets. Filter by status, category, domain, or free-text search. Sort with `sort_by` — prefix with `-` for descending (e.g. `-created_at`). ## OpenAPI ````yaml GET /v1/markets openapi: 3.0.3 info: title: Predicta Markets API description: >- The Predicta Markets REST API lets you build on top of a continuous double-auction prediction market platform. Users buy and sell shares in YES/NO outcomes of real-world events. When a market resolves, holders of the winning side receive payouts; holders of the losing side lose their stake. Data model hierarchy: Market → MarketAsset → MarketAssetOption (prediction key) → Order. A Market is a question about a real-world event (e.g. 'Will Arsenal win the Premier League?'). Each Market contains one or more MarketAssets — the tradeable outcomes. Simple binary markets have a single asset; multi-player markets (e.g. Player of the Match) have one asset per candidate. Each MarketAsset exposes two options, YES and NO, each carrying a prediction_key — the unique hash you pass when placing an order to identify exactly which outcome you are trading. Trading flow: (1) call GET /v1/markets to find a market; (2) inspect market_assets and their options to get the prediction_key for the outcome you want; (3) call POST /v1/markets/{market_id}/orders with that prediction_key, your price, and quantity. Orders match immediately when a counterparty exists, otherwise they rest as open limit orders in the order book. Price system: all prices are integers in the range 1–99, representing cents. Price equals implied probability in percent — a YES price of 65 means the market implies a 65% chance the event will occur. YES and NO prices for the same asset always sum to approximately 100. Currency: the platform's internal unit is PT (Predicta Token). Balances, prices, and payout amounts are expressed in PT unless the market was created with a real-currency denomination. QID system: many resources expose a human-readable qualified ID (qid) alongside the numeric id. QIDs are computed, not stored as database columns. Prefix conventions — MA: market, MAA: market asset, AP: account payout. Most path parameters accept either the numeric id or the qid interchangeably. Authentication: include your API key in the X-Api-Key request header. All account-scoped endpoints require authentication. Market listing and detail endpoints are public. version: 1.0.0 contact: email: api-support@predictamarkets.com servers: - url: https://api.predictamarkets.com description: Production security: [] paths: /v1/markets: get: tags: - Market summary: List Markets description: >- Returns a paginated list of markets. Filter by status, category, domain, or free-text search. Sort with `sort_by` — prefix with `-` for descending (e.g. `-created_at`). operationId: get_all_markets_v1_markets_get parameters: - name: skip in: query required: false schema: type: integer description: Number of records to skip default: 0 title: Skip description: 'Records to skip for pagination (default: 0)' - name: limit in: query required: false schema: type: integer description: Maximum number of records to return default: 25 title: Limit description: 'Max records to return (default: 10)' - name: status in: query required: false schema: description: Filter by market status (e.g., 'active') title: Status type: string nullable: true description: >- Filter by market status: PENDING_APPROVAL, OPEN, CLOSED, LOCKED, CANCELLED, COMPLETED, SETTLED, REJECTED - name: currency in: query required: false schema: $ref: '#/components/schemas/CurrencyEnum' description: Filter by currency (e.g., 'USD') title: Currency nullable: true description: Filter by currency (e.g., 'USD') - name: is_active in: query required: false schema: description: Filter by active status title: Is Active type: boolean nullable: true description: Filter by active status - name: market_category_slug in: query required: false schema: description: Filter by market category slug title: Market Category Slug type: string nullable: true description: Filter by market category slug - name: display_group in: query required: false schema: $ref: '#/components/schemas/MarketDisplayGroup' description: Filter by display group title: Display Group nullable: true description: Filter by display group - name: account_id in: query required: false schema: description: Filter by creator account ID title: Account Id type: integer nullable: true description: Filter by creator account ID - name: market_domain in: query required: false schema: $ref: '#/components/schemas/MarketDomain' description: Filter by market domain (e.g., 'FINANCE', 'SPORTS', 'CRYPTO') title: Market Domain nullable: true description: Filter by market domain (e.g., 'FINANCE', 'SPORTS', 'CRYPTO') - name: tracking_identifier in: query required: false schema: description: Filter by tracking identifier (e.g. ticker symbol) title: Tracking Identifier type: string nullable: true description: Filter by tracking identifier (e.g. ticker symbol) - name: search in: query required: false schema: description: Full-text search on market title title: Search type: string nullable: true description: Full-text search against market title - name: sort_by in: query required: false schema: description: >- Fields to sort by, prefix with - for descending order (e.g., ['-created_at']) title: Sort By type: array items: type: string nullable: true description: Sort fields, prefix with `-` for descending (e.g. `-created_at`) responses: '200': description: List of markets content: application/json: schema: type: array items: $ref: '#/components/schemas/MarketListResponseSchema' title: Response Get All Markets V1 Markets Get example: - id: 12 qid: MKT-12 slug: will-bitcoin-hit-100k-before-july-2025 title: Will Bitcoin hit $100k before July 2025? description: >- Resolves YES if BTC closes above $100,000 on Binance before 1 July 2025. logo_path: https://cdn.predictamarkets.com/logos/btc.png currency: KES expires_at: '2025-07-01T00:00:00Z' status: OPEN is_active: true allows_trading: true locked_at: null display_group: ALL total_buy_in: '125000.00' market_total_share: '125000.00' created_at: '2024-12-01T10:00:00Z' updated_at: '2025-05-01T08:00:00Z' market_type: DEFAULT ticker_symbol: BTC tracking_identifier: null market_domain: crypto market_category: id: 3 name: Crypto slug: crypto description: Cryptocurrency markets icon: bitcoin market_assets: - id: 34 qid: MAS-34 prediction_key: mkt-12-yes label: 'YES' side: 'YES' probability: 0.65 - id: 35 qid: MAS-35 prediction_key: mkt-12-no label: 'NO' side: 'NO' probability: 0.35 regeneration_interval_type: null regeneration_interval_value: null regeneration_timezone: null regeneration_schedule: null regeneration_template_format: null last_regenerated_at: null next_regeneration_at: null regenerated_title: null regeneration_count: null '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CurrencyEnum: type: string enum: - NGN - USD - KES - GHS - ZAR - XOF - TZS - EUR - GBP - CAD - AUD - CHF - CNY - INR - MXN - NZD - RUB - SEK - SGD - THB - TRY - UAH - VND - JPY - UGX - RWF - USDC - USDT - PT title: CurrencyEnum description: >- ISO currency code or platform token. PT is Predicta's internal token used for most markets. USDC and USDT are supported stablecoins. All other values are standard ISO 4217 fiat codes. MarketDisplayGroup: type: string enum: - TRENDING - POPULAR - DISCOVER - NEW - FEATURED - RECENT - TOP - ALL title: MarketDisplayGroup description: >- Controls which UI feed this market appears in (e.g. TRENDING, FEATURED, ALL). MarketDomain: type: string enum: - SPORTS - FINANCE - CRYPTO - GENERAL title: MarketDomain description: >- Subject-area category for filtering: SPORTS, FINANCE, CRYPTO, or GENERAL. MarketListResponseSchema: properties: id: type: integer title: Id description: Unique identifier for the market qid: type: string title: Qid description: Query identifier for the market slug: title: Slug description: Slug of the market type: string nullable: true title: type: string title: Title description: Market title description: title: Description description: Market description type: string nullable: true logo_path: title: Logo Path description: URL of the market logo type: string nullable: true currency: type: string title: Currency description: Currency used for transactions in this market expires_at: title: Expires At description: Expiration date of the market type: string format: date-time nullable: true status: title: Status description: Current status of the market type: string nullable: true is_active: type: boolean title: Is Active description: Whether the market is currently active default: true allows_trading: type: boolean title: Allows Trading description: >- Whether the market allows trading (based on status, active state, and expiration) default: true locked_at: title: Locked At description: Time when the market gets locked type: string format: date-time nullable: true display_group: $ref: '#/components/schemas/MarketDisplayGroup' description: Display group of the market default: ALL total_buy_in: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Total Buy In description: Total amount of buy-in in the market default: '0' market_total_share: title: Market Total Share description: Total share of the market type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ nullable: true created_at: type: string format: date-time title: Created At description: Timestamp when the market was created updated_at: type: string format: date-time title: Updated At description: Timestamp when the market was last updated market_type: $ref: '#/components/schemas/MarketType' description: Market type ticker_symbol: title: Ticker Symbol description: Ticker symbol for the market type: string nullable: true tracking_identifier: title: Tracking Identifier description: Tracking identifier for querying and analytics type: string nullable: true market_domain: title: Market Domain description: Market domain type: string nullable: true regeneration_interval_type: $ref: '#/components/schemas/MarketRegenerationIntervalType' description: Regeneration interval type nullable: true regeneration_interval_value: title: Regeneration Interval Value description: Regeneration interval value type: integer nullable: true regeneration_timezone: title: Regeneration Timezone description: IANA timezone name for custom schedules type: string nullable: true regeneration_schedule: title: Regeneration Schedule description: Custom regeneration schedule anyOf: - $ref: '#/components/schemas/SimpleRegenerationSchedule-Output' - $ref: '#/components/schemas/RegenerationSchedule-Output' - $ref: '#/components/schemas/MixedRegenerationSchedule-Output' nullable: true regeneration_template_format: title: Regeneration Template Format description: Regeneration template format type: string enum: - DEFAULT - ABOVE_AT_OR_BELOW_PERCENTAGE nullable: true last_regenerated_at: title: Last Regenerated At description: Timestamp when the market was last regenerated type: string format: date-time nullable: true next_regeneration_at: title: Next Regeneration At description: Timestamp when the market will be regenerated next type: string format: date-time nullable: true regenerated_title: title: Regenerated Title description: Regenerated title for series markets type: string nullable: true regeneration_count: title: Regeneration Count description: Total number of regeneration cycles type: integer nullable: true market_category: $ref: '#/components/schemas/MarketCategoryListSchema' description: Category of the market nullable: true market_assets: title: Market Assets description: List of market assets under this market default: [] items: $ref: '#/components/schemas/MarketAssetListSchema' type: array nullable: true type: object required: - id - qid - title - currency - created_at - updated_at - market_type title: MarketListResponseSchema description: >- Lightweight Market payload for listing endpoints. Excludes heavy fields like `parameters`, `mini_markets`, winning keys, etc. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError description: >- Returned by FastAPI when request validation fails (HTTP 422). Contains one or more ValidationError entries describing each invalid field. MarketType: type: string enum: - DEFAULT - SERIES title: MarketType description: >- Whether the market is a one-off (DEFAULT) or a recurring auto-regenerating series (SERIES). MarketRegenerationIntervalType: type: string enum: - HOUR - DAY - WEEK - MONTH - YEAR - CUSTOM title: MarketRegenerationIntervalType description: >- Frequency unit for SERIES market regeneration: HOUR, DAY, WEEK, MONTH, YEAR, or CUSTOM. SimpleRegenerationSchedule-Output: properties: regenerates_at_minute: title: Regenerates At Minute description: >- Minute of the hour when the market should regenerate, Only works for hourly intervals type: integer nullable: true regenerates_at_hour: title: Regenerates At Hour description: >- Hour of the day when the market should regenerate, Only works for hourly intervals type: integer nullable: true regenerates_at_day: title: Regenerates At Day description: >- Day of the month when the market should regenerate, Only works for daily intervals type: integer nullable: true regenerates_at_month: title: Regenerates At Month description: >- Month of the year when the market should regenerate, Only works for monthly intervals type: integer nullable: true active_days: title: Active Days description: Days when the market should be active items: type: string type: array nullable: true type: object title: SimpleRegenerationSchedule RegenerationSchedule-Output: properties: regenerates_at_minute: title: Regenerates At Minute description: >- Minute of the hour when the market should regenerate, Only works for hourly intervals type: integer nullable: true regenerates_at_hour: title: Regenerates At Hour description: >- Hour of the day when the market should regenerate, Only works for hourly intervals type: integer nullable: true regenerates_at_day: title: Regenerates At Day description: >- Day of the month when the market should regenerate, Only works for daily intervals type: integer nullable: true regenerates_at_month: title: Regenerates At Month description: >- Month of the year when the market should regenerate, Only works for monthly intervals type: integer nullable: true active_days: title: Active Days description: Days when the market should be active items: type: string type: array nullable: true timezone: type: string title: Timezone description: IANA timezone name (e.g., 'America/New_York') start_time: title: Start Time description: Start time in HH:MM format (24-hour) - legacy support type: string nullable: true end_time: title: End Time description: End time in HH:MM format (24-hour) - legacy support type: string nullable: true time_windows: title: Time Windows description: >- List of time windows, each with start_time and end_time in HH:MM format items: additionalProperties: type: string type: object type: array nullable: true type: object required: - active_days - timezone title: RegenerationSchedule description: >- Model for flexible regeneration schedules with support for multiple time windows MixedRegenerationSchedule-Output: properties: regenerates_at_minute: title: Regenerates At Minute description: >- Minute of the hour when the market should regenerate, Only works for hourly intervals type: integer nullable: true regenerates_at_hour: title: Regenerates At Hour description: >- Hour of the day when the market should regenerate, Only works for hourly intervals type: integer nullable: true regenerates_at_day: title: Regenerates At Day description: >- Day of the month when the market should regenerate, Only works for daily intervals type: integer nullable: true regenerates_at_month: title: Regenerates At Month description: >- Month of the year when the market should regenerate, Only works for monthly intervals type: integer nullable: true regenerates_at_week: title: Regenerates At Week description: >- Week of the year when the market should regenerate, Only works for weekly intervals type: integer nullable: true regenerates_at_year: title: Regenerates At Year description: >- Year of the market when the market should regenerate, Only works for yearly intervals type: integer nullable: true interval_type: type: string description: The type of the regeneration interval interval_value: type: integer title: Interval Value description: The value of the regeneration interval timezone: type: string title: Timezone description: IANA timezone name (e.g., 'America/New_York') start_time: title: Start Time description: >- When the first regeneration should start, in the timezone of the market type: string format: date-time nullable: true active_days: title: Active Days description: Days when the market should be active items: type: string type: array nullable: true time_windows: title: Time Windows description: >- Dictionary mapping weekdays to their regeneration schedules with windows and breaks additionalProperties: $ref: '#/components/schemas/WeekdayScheduleConfig' type: object nullable: true type: object required: - interval_type - interval_value - timezone title: MixedRegenerationSchedule MarketCategoryListSchema: properties: name: type: string title: Name description: Name of the market category slug: title: Slug description: Slug of the market category type: string nullable: true type: object required: - name title: MarketCategoryListSchema description: Minimal category payload for market listing endpoints. MarketAssetListSchema: properties: id: type: integer title: Id description: The items ID qid: type: string title: Qid description: the qualified identifier asset_identifier: type: string title: Asset Identifier description: Unique asset identifier market_id: type: integer title: Market Id description: The market ID current_price: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ nullable: true title: Current Price description: Current price of the asset default: null yes_price: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ nullable: true title: Yes Price description: Current YES price of the asset default: null no_price: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ nullable: true title: No Price description: Current NO price of the asset default: null volume: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ nullable: true title: Volume description: Trading volume of the asset default: null status: type: string title: Status description: Status of the market asset default: active title: title: Title description: >- Display name for this market asset. For multi-outcome markets this is the candidate name. Null for simple binary markets. type: string nullable: true options: title: Options description: Tradeable options for this market asset. type: array items: $ref: '#/components/schemas/MarketAssetOption' nullable: true default: null avatar_path: title: Avatar Path description: The avatar url type: string nullable: true outcome: $ref: '#/components/schemas/MarketAssetOutcomeSchema' description: Outcome of the market asset nullable: true type: object required: - id - qid - asset_identifier - market_id title: MarketAssetListSchema description: |- Lightweight MarketAsset payload for markets listing. `options` is included because both list queries explicitly load it via load_only, so there is no deferred lazy-load risk in async context. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location description: >- Path to the invalid field as a list of keys and/or array indices. For example, ['body', 'price'] indicates the price field in the request body failed validation. msg: type: string title: Message description: Human-readable explanation of what validation rule was violated. type: type: string title: Error Type description: >- Machine-readable Pydantic error type (e.g. 'value_error.missing', 'type_error.integer'). type: object required: - loc - msg - type title: ValidationError description: >- A single field validation failure within an HTTP 422 response. The loc array traces the path to the invalid field (e.g. ['body', 'price']). ErrorResponse: type: object properties: detail: type: string description: Human-readable error message required: - detail title: ErrorResponse WeekdayScheduleConfig: properties: regenerations_within: $ref: '#/components/schemas/TimeWindow' description: Primary time window during which regeneration can occur on this day. default: start_time: '00:00' end_time: '23:59' nullable: true breaks: title: Breaks description: >- List of time windows representing breaks (pauses) within the main window. items: $ref: '#/components/schemas/TimeWindow' type: array nullable: true type: object title: WeekdayScheduleConfig MarketAssetOption: type: object title: MarketAssetOption description: >- A single tradeable option within a market asset (e.g. YES / NO for binary markets). required: - id - key properties: id: type: string description: >- Option identifier — 'YES' / 'NO' for binary markets, or the condition key for multi-outcome markets. key: type: string description: >- The prediction key for this option. This is the value you supply as `prediction_key` when placing an order via POST /v1/markets/{market_id}/orders. It is a unique uppercase hex hash that identifies a specific tradeable outcome (e.g. the YES side of a particular market asset). value: type: string nullable: true description: >- Human-readable label for the option. Typically 'Yes' / 'No', but can be a full sentence (e.g. 'Yes Kylian Mbappe wins the Ballon d\'Or'). determination_formula: type: string nullable: true description: >- Auto-determination formula used by the oracle to resolve this option. Present only on finance/series markets. Absent (not null) on simple binary markets. example: id: 'YES' key: B634817F0B02790D949F56F7BBDE7ECF value: 'Yes' determination_formula: '#{price} >= 4554.71' MarketAssetOutcomeSchema: properties: id: title: Id description: Primary key of the outcome record. Populated after resolution. type: integer nullable: true qid: title: Qid description: Human-readable qualified ID for this outcome record. type: string nullable: true winning_side: $ref: '#/components/schemas/MarketSides' description: The winning side nullable: true winning_prediction_key: title: Winning Prediction Key description: >- The prediction key (`market_asset.options[n].key`) of the option that was resolved as the winner. Holders of orders with this prediction key receive payouts. type: string nullable: true market_determined_at: title: Market Determined At description: >- Timestamp when the market outcome was officially determined by the platform. After this point the market moves toward COMPLETED/SETTLED status and payouts are calculated. type: string format: date-time nullable: true type: object title: MarketAssetOutcomeSchema description: >- Resolution outcome for a market asset. Populated after the market is resolved. Contains the winning side, the winning prediction_key, and the timestamp of determination. TimeWindow: properties: start_time: type: string title: Start Time description: Start time of the time window, in HH:MM format (24-hour) end_time: type: string title: End Time description: End time of the time window, in HH:MM format (24-hour) type: object required: - start_time - end_time title: TimeWindow MarketSides: type: string enum: - 'YES' - 'NO' title: MarketSides description: 'The two tradeable sides of a market asset: YES or NO.' responses: InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: An unexpected error occurred. Please try again later. ````