> ## 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 Venue Listings
> List flattened venue-native executable listings mapped to canonical Predexon outcomes
Use canonical listings when you need the venue-native execution metadata behind canonical outcomes: token IDs, condition IDs, Kalshi tickers, market slugs, and venue market IDs.
**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/listings
```
Returns venue-native executable listings flattened across canonical markets and outcomes.
Use this endpoint when you need venue-native identifiers for execution or routing: `token_id`, `condition_id`, `market_ticker`, `market_slug`, or venue-native `market_id`.
## 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/listings?limit=20'
```
## Query Parameters
| Parameter | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | Number of canonical markets to page before flattening listings. 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 one venue. Example: `kalshi`, `polymarket`, `limitless`, `opinion`, `predict`. |
| `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 listings for a specific canonical market/question scope. |
`limit` paginates canonical markets before listings are flattened. Therefore `listings.length` can be greater than `limit`. To fetch the next page, pass the returned `pagination.pagination_key` as the next request's `pagination_key`.
## Response Shape
```json theme={null}
{
"listings": [
{
"event_id": "string",
"market_title": "string",
"league": "mlb",
"predexon_id": "px-...",
"outcome": "yes",
"outcome_label": "Yes",
"venue": "polymarket",
"venue_market_title": "string",
"description": "string",
"yes_subtitle": "string",
"no_subtitle": "string",
"selection_label": "string",
"resolution_source": "string",
"market_id": "string",
"market_ticker": "string",
"condition_id": "string",
"market_slug": "string",
"token_id": "string",
"side": "yes",
"status": "open"
}
],
"pagination": {
"limit": 20,
"has_more": true,
"pagination_key": ""
}
}
```
Venue-native metadata fields are omitted when unavailable.
## Field Reference
| Field | Type | Description |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_id` | string | Canonical market/question scope ID. |
| `market_title` | string | Canonical market display title. |
| `league` | string | Optional sports league code. |
| `predexon_id` | string | Canonical outcome-level trading/routing ID. |
| `outcome` | string | Canonical outcome key. |
| `outcome_label` | string | Human-readable canonical outcome label. |
| `venue` | string | Venue name. |
| `venue_market_title` | string | Venue-native market title. |
| `description` | string | Venue-native description or rules/resolution text when available. |
| `yes_subtitle` | string | Venue-native YES subtitle/label when available. |
| `no_subtitle` | string | Venue-native NO subtitle/label when available. |
| `selection_label` | string | Venue-native selected outcome/selection label when available. |
| `resolution_source` | string | Venue-native resolution source/oracle when available. |
| `market_id` | string | Venue-native market ID where available. Not canonical. |
| `market_ticker` | string | Kalshi venue-native ticker. Not canonical. |
| `condition_id` | string | Venue-native condition ID where available. Not canonical. |
| `market_slug` | string | Venue-native market slug where available. |
| `token_id` | string | Venue-native executable token ID where available. Present for on-chain venues such as Polymarket, Limitless, Predict, and Opinion. Not returned for Kalshi. |
| `side` | string | Venue-native side, usually `yes` or `no`. |
| `status` | string | Listing status, usually `open` or `closed`. |
## Example
```bash theme={null}
curl -sS \
-H 'x-api-key: YOUR_API_KEY' \
'https://api.predexon.com/v2/markets/listings?limit=1&category=sports&league=fl1&event_id=fl1-asm-met-2026-05-02' \
| python -m json.tool
```
```json theme={null}
{
"listings": [
{
"event_id": "fl1-asm-met-2026-05-02",
"market_title": "Monaco vs Metz Winner?",
"league": "fl1",
"predexon_id": "px-udfdzy5gtmm4kdoa",
"outcome": "asm",
"outcome_label": "Monaco",
"venue": "kalshi",
"venue_market_title": "Metz vs Monaco Winner?",
"market_ticker": "KXLIGUE1GAME-26MAY02FCMASM-ASM",
"side": "yes",
"status": "open",
"yes_subtitle": "Monaco",
"selection_label": "Monaco"
},
{
"event_id": "fl1-asm-met-2026-05-02",
"market_title": "Monaco vs Metz Winner?",
"league": "fl1",
"predexon_id": "px-udfdzy5gtmm4kdoa",
"outcome": "asm",
"outcome_label": "Monaco",
"venue": "polymarket",
"venue_market_title": "Will AS Monaco FC win on 2026-05-02?",
"market_id": "2018979",
"condition_id": "0x070254c57b7545b0df2dba4a38ef81655a5b41c1f8edf9d466218f58d9a1f600",
"market_slug": "fl1-met-asm-2026-05-02-asm",
"token_id": "10439835459613392921040201374401440506564152347998894843834931942965004437054",
"side": "yes",
"status": "open",
"selection_label": "Monaco"
}
],
"pagination": {
"limit": 1,
"has_more": true,
"pagination_key": ""
}
}
```
## OpenAPI
````yaml GET /v2/markets/listings
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/listings:
get:
tags:
- markets
summary: List Market Listings
description: Flatten canonical markets into venue-native executable listings.
operationId: list_market_listings_v2_markets_listings_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 venue-native listings from this venue
title: Venue
description: Filter to venue-native listings from 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: 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
````