List Markets

GET /v1/predexon/markets — Search and filter prediction markets using multiple filter options. Find markets by identifier (slug, event, condition), category (tags), status, liquidity (volume), with offset-based pagination.

Base URL: https://api.predexon.com/v1
Auth: x-api-key: YOUR_API_KEY
Time: All timestamps are UTC ISO-8601 (e.g., 2025-10-06T19:21:02Z)
Pagination: Offset-based via offset and limit
Rate Limits: 100 requests/minute per API key. Returns 429 with Retry-After header (seconds) when exceeded. Use exponential backoff on 429/503 responses.

Common use cases

Market discovery: Find trending or high-volume markets across all categories
Category browsing: Explore markets by tag (e.g., politics, crypto, sports)
Event tracking: Get all markets related to a specific event or condition
Liquidity analysis: Filter by minimum volume to find liquid markets for trading

Endpoint

GET /v1/predexon/markets

Query parameters

All are optional unless noted.

Parameter	Type	Notes
`market_slug`	string[]	Filter markets by market slug(s). Format: lowercase-hyphenated (e.g., `bitcoin-up-or-down-july-25-8pm-et`). Repeatable. Use when you already have specific market identifiers.
`event_slug`	string[]	Filter markets by event slug(s). Format: lowercase-hyphenated (e.g., `presidential-election-winner-2028`). Repeatable. Returns all markets related to the specified event(s).
`condition_id`	string[]	Filter markets by condition ID(s). Format: 0x-prefixed hex string (e.g., `0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57`). Repeatable. Useful for blockchain-based market lookups.
`tags`	string[]	Filter markets by tag(s). Common tags: `politics`, `crypto`, `sports`, `macro`, `election`. Repeatable. OR logic within array (returns markets with any matching tag).
`status`	enum	Filter markets by status: `active` \| `closed` \| `archived`. Returns markets in the specified lifecycle state.
`min_volume`	float	Filter markets with trading volume >= this amount (USD). Must be >= 0. Useful for finding liquid markets.
`limit`	integer	Number of markets to return per page. Default: 20, max: 100. Must be >= 1.
`offset`	integer	Number of markets to skip for pagination. Default: 0. Must be >= 0.

Query behavior:

No parameters: Returns all markets (paginated), ordered by creation/update time, then by market slug ascending.
Multiple parameters: Combined with AND logic. Example: status=active&min_volume=10000 returns active markets with volume >= $10k only.
Array parameters: OR logic within the array. Example: tags=politics&tags=crypto returns markets with either politics OR crypto tag. Maximum 50 values per array parameter.
Pagination: Use limit and offset to page through results. Check has_more to determine if additional pages exist.
Empty results: Returns HTTP 200 with empty markets array and pagination metadata.

Where do IDs come from?

market_slug: Market-specific identifier found in market URLs or previous API responses. Use for direct market lookups.
event_slug: Event identifier found in market responses or event discovery endpoints. Use to get all markets for an event.
condition_id: Blockchain condition identifier for Polymarket integration. Found in market responses or smart contract details.
tags: Common categories returned in market responses or displayed in market discovery. Query with known tags to filter results.

Common pattern: Call with broad filters (tags + status), store market identifiers for future lookups, and use min_volume to prioritize liquid markets.

Response schema

{
  "markets": [
    {
      "id": "market_001",
      "market_slug": "bitcoin-above-100k-2025",
      "title": "Will Bitcoin reach $100k by end of 2025?",
      "description": "Resolves YES if Bitcoin touches $100,000 USD at any point before 2026-01-01 UTC",
      "event_slug": "bitcoin-price-targets-2025",
      "condition_id": "0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57",
      "tags": ["crypto", "bitcoin", "price"],
      "status": "active",
      "created_at": "2025-10-01T10:30:00Z",
      "updated_at": "2025-11-03T14:22:33Z",
      "closes_at": "2026-01-01T00:00:00Z",
      "volume_usd": 150000.50,
      "liquidity_usd": 45000.25,
      "outcomes": [
        {
          "id": "outcome_yes",
          "label": "Yes",
          "description": "Bitcoin reaches $100k"
        },
        {
          "id": "outcome_no",
          "label": "No",
          "description": "Bitcoin stays below $100k"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "has_more": true
  }
}

Field reference

Field	Type	Description
`markets`	array	Array of market objects matching the filter criteria
`markets[].id`	string	Unique internal market identifier
`markets[].market_slug`	string	Human-readable, URL-safe market identifier
`markets[].title`	string	Market question or description
`markets[].description`	string	Detailed market description, rules, or resolution criteria
`markets[].event_slug`	string	Associated event identifier
`markets[].condition_id`	string	Blockchain condition ID for cross-platform integration
`markets[].tags`	string[]	Categorical tags for market discovery and filtering
`markets[].status`	enum	Market lifecycle state: `active`, `closed`, or `archived`
`markets[].created_at`	string (ISO-8601)	Market creation timestamp
`markets[].updated_at`	string (ISO-8601)	Last market update timestamp. Use for cache invalidation.
`markets[].closes_at`	string (ISO-8601)	Market close/expiration timestamp
`markets[].volume_usd`	float	Total trading volume in USD
`markets[].liquidity_usd`	float	Available liquidity in USD for trading
`markets[].outcomes`	array	Possible market outcomes/resolutions
`markets[].outcomes[].id`	string	Outcome identifier
`markets[].outcomes[].label`	string	Short outcome label (e.g., “Yes”, “No”)
`markets[].outcomes[].description`	string	Detailed outcome description
`pagination.limit`	integer	Number of results per page (echoes request parameter)
`pagination.offset`	integer	Number of results skipped (echoes request parameter)
`pagination.total`	integer	Total count of matching markets across all pages
`pagination.has_more`	boolean	`true` if additional pages exist; `false` on last page

Examples

curl -s "https://api.predexon.com/v1/predexon/markets?status=active&min_volume=10000&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

{
  "markets": [
    {
      "id": "market_001",
      "market_slug": "bitcoin-above-100k-2025",
      "title": "Will Bitcoin reach $100k by end of 2025?",
      "description": "Resolves YES if Bitcoin touches $100,000 USD at any point before 2026-01-01 UTC",
      "event_slug": "bitcoin-price-targets-2025",
      "condition_id": "0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57",
      "tags": ["crypto", "bitcoin", "price"],
      "status": "active",
      "created_at": "2025-10-01T10:30:00Z",
      "updated_at": "2025-11-03T14:22:33Z",
      "closes_at": "2026-01-01T00:00:00Z",
      "volume_usd": 150000.50,
      "liquidity_usd": 45000.25,
      "outcomes": [
        {
          "id": "outcome_yes",
          "label": "Yes",
          "description": "Bitcoin reaches $100k"
        },
        {
          "id": "outcome_no",
          "label": "No",
          "description": "Bitcoin stays below $100k"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "has_more": true
  }
}

Errors

All errors return standard HTTP status codes with JSON error responses:

{
  "error": {
    "type": "invalid_parameter",
    "message": "status must be one of: active, closed, archived",
    "param": "status"
  }
}

Error Types

HTTP Status	Error Type	Description	Common Causes
`400`	`invalid_parameter`	Parameter validation failed	Invalid enum value (status), negative min_volume, limit > 100, invalid hex format for condition_id
`400`	`invalid_request`	Malformed request	Missing required header, invalid JSON body, malformed query string
`401`	`unauthorized`	Authentication failed	Missing `x-api-key` header or invalid key
`403`	`forbidden`	API key lacks required permissions	Token doesn’t have access to Markets API
`404`	`not_found`	Resource doesn’t exist	Invalid endpoint path
`422`	`too_many_values`	Array parameter exceeds limit	More than 50 values in market_slug, event_slug, condition_id, or tags parameter
`429`	`rate_limit_exceeded`	Too many requests	Exceeded 100 requests/minute. Check `Retry-After` header.
`500`	`internal_error`	Server error	Contact team@predexon.com with request ID
`503`	`service_unavailable`	Temporary service issue	Retry with exponential backoff

Empty results return HTTP 200 with empty array:

{
  "markets": [],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}

See Errors & Status Codes for full list and remediation tips.

Best practices

Market discovery: Use broad filters (tags + status) to discover markets, then store market_slug or condition_id for future direct lookups.
Liquidity filtering: Always check volume_usd and liquidity_usd in responses. Filter with min_volume to prioritize high-liquidity markets for trading.
Pagination: Use offset and limit to page through results. Monitor has_more to determine when you’ve reached the last page. Store total count for analytics.
Cache invalidation: Store updated_at timestamp from responses. Re-fetch when updated_at changes to get latest market data.
Batch lookups: Use array parameters (e.g., multiple market_slug values) to retrieve multiple specific markets in a single request rather than separate calls.
Event tracking: Combine event_slug + status filters to track all market activity related to specific events.
Tag-based browsing: Use tags parameter to implement category-based market browsing features in your application.

Markets API Overview - General overview and key features
Discovery API - Normalized market discovery across venues
Trading Data API - Access orders and activity for markets
Price Analytics API - Get market prices and candlestick data

Getting Started

Market Matching

Polymarket Endpoints

Kalshi Endpoints

List Markets

List Markets

Common use cases

Endpoint

Query parameters

Response schema

Field reference

Examples

Errors

Error Types

Best practices

Getting Started

Market Matching

Polymarket Endpoints

Kalshi Endpoints

​List Markets

​Common use cases

​Endpoint

​Query parameters

​Response schema

​Field reference

​Examples

​Errors

​Error Types

​Best practices

​Related

List Markets

Common use cases

Endpoint

Query parameters

Response schema

Field reference

Examples

Errors

Error Types

Best practices

Related