> ## Documentation Index
> Fetch the complete documentation index at: https://docs.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Canonical Markets
> List cross-venue canonical market/question containers with outcome-level Predexon IDs
Canonical markets are the recommended discovery layer for cross-venue trading. Use this endpoint to find outcome-level `predexon_id`s that unify the same outcome across venues.
**Beta:** Canonical market endpoints are in beta. Response fields and match coverage may evolve as we refine the canonical matching system.
## Endpoint
```http theme={null}
GET https://api.predexon.com/v2/markets
```
Returns canonical market/question containers backed by the canonical matching system. Each market contains one or more canonical outcomes, and each outcome has its own public `predexon_id`.
Use this endpoint for aggregate discovery. Use [`/v2/markets/listings`](/api-reference/canonical/listings) when you need venue-native executable identifiers like token IDs, Kalshi tickers, condition IDs, or market slugs.
## Auth
Pass your API key in the `x-api-key` header.
```bash theme={null}
curl -sS \
-H 'x-api-key: YOUR_API_KEY' \
'https://api.predexon.com/v2/markets?limit=20'
```
## Core IDs
| ID | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `event_id` | Canonical market/question scope. It is one tradable question container, not a broad real-world event. |
| `predexon_id` | Canonical outcome-level trading/routing ID. Equivalent outcomes across venues share the same `predexon_id`. |
| Venue IDs | `market_id`, `market_ticker`, `condition_id`, `token_id`, and `market_slug` are venue-native identifiers, not canonical Predexon IDs. |
## Query Parameters
| Parameter | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | Number of canonical markets to return. Default `50`, max `200`. |
| `pagination_key` | string | Cursor from the previous response. Omit on the first request. |
| `search` | string | Text search over market titles and canonical claims. Must be 3–200 characters. |
| `venue` | string | Filter to markets available on one venue. Example: `polymarket`. |
| `status` | string | Market status filter: `open` (default), `closed`, `resolved`, or `all`. Omitting it returns only `open` markets. |
| `category` | string | Broad market category. Examples: `sports`, `crypto`, `politics`, `entertainment`, `economics`, `weather`, `general`. |
| `league` | string | Sports-only league filter. Only use with `category=sports` or by itself to imply sports. Example: `mlb`, `fl1`. |
| `event_id` | string | Fetch a specific canonical market/question scope. |
## Response Shape
```json theme={null}
{
"markets": [
{
"event_id": "string",
"market_title": "string",
"description": "string",
"starts_at": "2026-05-02T00:00:00+00:00",
"status": "open",
"venues": ["kalshi", "polymarket"],
"outcomes": [
{
"predexon_id": "px-...",
"outcome": "yes",
"market_type": "binary",
"outcome_label": "Yes",
"claim": "string",
"status": "open",
"venues": ["kalshi", "polymarket"]
}
],
"league": "mlb"
}
],
"pagination": {
"limit": 20,
"has_more": true,
"pagination_key": ""
}
}
```
`description`, `starts_at`, and `league` are omitted when unavailable. `total` is intentionally not returned for performance. To fetch the next page, pass the returned `pagination.pagination_key` as the next request's `pagination_key`.
## Field Reference
| Field | Type | Description |
| -------------------------- | --------- | ------------------------------------------------------------ |
| `markets[]` | array | Canonical market/question containers. |
| `markets[].event_id` | string | Canonical market/question scope ID. |
| `markets[].market_title` | string | Display title for the canonical market. |
| `markets[].description` | string | Optional display description or rules text when available. |
| `markets[].starts_at` | string | Optional ISO timestamp for scheduled markets. |
| `markets[].status` | string | Market status, usually `open` or `closed`. |
| `markets[].venues` | string\[] | Venues with at least one listing in this canonical market. |
| `markets[].outcomes[]` | array | Canonical tradable outcomes in this market. |
| `outcomes[].predexon_id` | string | Public canonical trading/routing ID for this outcome. |
| `outcomes[].outcome` | string | Canonical outcome key. Examples: `yes`, `no`, `draw`, `asm`. |
| `outcomes[].market_type` | string | Market type. Examples: `binary`, `game_winner`. |
| `outcomes[].outcome_label` | string | Human-readable outcome label. |
| `outcomes[].claim` | string | Canonical claim text for this outcome. |
| `outcomes[].status` | string | Outcome status, usually `open` or `closed`. |
| `outcomes[].venues` | string\[] | Venues with executable listings mapped to this outcome. |
| `markets[].league` | string | Optional sports league code. |
## Example
```bash theme={null}
curl -sS \
-H 'x-api-key: YOUR_API_KEY' \
'https://api.predexon.com/v2/markets?limit=1&category=sports&league=fl1&event_id=fl1-asm-met-2026-05-02' \
| python -m json.tool
```
```json theme={null}
{
"markets": [
{
"event_id": "fl1-asm-met-2026-05-02",
"market_title": "Monaco vs Metz Winner?",
"starts_at": "2026-05-02T00:00:00+00:00",
"status": "open",
"venues": ["kalshi", "polymarket"],
"outcomes": [
{
"predexon_id": "px-udfdzy5gtmm4kdoa",
"outcome": "asm",
"market_type": "game_winner",
"outcome_label": "Monaco",
"claim": "Monaco win fl1-asm-met-2026-05-02.",
"status": "open",
"venues": ["kalshi", "polymarket"]
},
{
"predexon_id": "px-45mbzcmzgir33767",
"outcome": "draw",
"market_type": "game_winner",
"outcome_label": "Draw",
"claim": "Draw in fl1-asm-met-2026-05-02.",
"status": "open",
"venues": ["kalshi", "polymarket"]
},
{
"predexon_id": "px-ifcdu3x2c56kzxcq",
"outcome": "met",
"market_type": "game_winner",
"outcome_label": "Metz",
"claim": "Metz win fl1-asm-met-2026-05-02.",
"status": "open",
"venues": ["kalshi", "polymarket"]
}
],
"league": "fl1"
}
],
"pagination": {
"limit": 1,
"has_more": true,
"pagination_key": ""
}
}
```
## OpenAPI
````yaml GET /v2/markets
openapi: 3.1.0
info:
title: Predexon API
description: Prediction market data aggregation and matching API
version: 2.0.0
servers:
- url: https://api.predexon.com
security:
- apiKey: []
paths:
/v2/markets:
get:
tags:
- markets
summary: List Markets
description: >-
List canonical markets grouped as question containers with outcome-level
predexon_ids.
operationId: list_markets_v2_markets_get
parameters:
- name: event_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Canonical market/question event_id
title: Event Id
description: Canonical market/question event_id
- name: category
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Broad market category, e.g. sports, crypto, politics
title: Category
description: Broad market category, e.g. sports, crypto, politics
- name: league
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Sports-only league filter, e.g. mlb, nba, epl
title: League
description: Sports-only league filter, e.g. mlb, nba, epl
- name: status
in: query
required: false
schema:
type: string
description: open, closed, resolved, or all
default: open
title: Status
description: open, closed, resolved, or all
- name: venue
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to canonical markets with this venue
title: Venue
description: Filter to canonical markets with this venue
- name: search
in: query
required: false
schema:
anyOf:
- type: string
minLength: 3
maxLength: 200
- type: 'null'
description: Search canonical title/description
title: Search
description: Search canonical title/description
- name: include_venue_listings
in: query
required: false
schema:
type: boolean
description: Include venue-native listing metadata under each outcome
default: false
title: Include Venue Listings
description: Include venue-native listing metadata under each outcome
- name: routable_only
in: query
required: false
schema:
type: boolean
description: Only include verified/tradable/healthy listings
default: true
title: Routable Only
description: Only include verified/tradable/healthy listings
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: pagination_key
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for the next page
title: Pagination Key
description: Cursor for the next page
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````