List Markets

GET /api/v1/markets Returns markets from the gold layer with filtering and pagination. Use this endpoint to search across exchanges, fetch exact markets, or pull every market in one event. Start here when you do not yet know the IDs you need.

Find the IDs You Need

Use a discovery query first:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parsecapi.com/api/v1/markets?exchanges=kalshi&search=bitcoin&limit=1"

The response gives you:

parsec_id — Parsec’s standard market ID
exchange — source exchange
exchange_market_id — native market ID on that exchange
parsec_group_id / exchange_group_id — event identifiers

You can then reuse either parsec_id or exchange + exchange_market_id on /orderbook, /price, /trades, and /execution-price.

Scopes

/markets supports four scopes:

Scope	Use it for	Required selector
`list`	discovery, search, filters, pagination	`exchanges` optional
`market`	one exact market lookup	`parsec_id` or `exchange + exchange_market_id`
`market_batch`	many exact lookups in one request	`parsec_ids` or `external_market_keys`
`event`	all markets for one event	`event_id` or `exchange + exchange_group_id`

If you omit scope and pass parsec_ids, the server automatically treats the request as scope=market_batch.

Most Common Request Shapes

Task	Scope	What to send
Search and filter markets	`list`	`search`, `exchanges`, `status`, `limit`
Fetch one exact market	`market`	`parsec_id` or `exchange + exchange_market_id`
Fetch many exact markets	`market_batch`	`parsec_ids` or `external_market_keys`
Fetch all markets in one event	`event`	`event_id` or `exchange + exchange_group_id`

Query Reference

Discovery: `scope=list` (default)

Common

scope

string

default:"list"

Query scope: list, market, market_batch, or event.

include_matches

boolean

default:"false"

When true, each market includes a matched_markets array with cross-exchange same-market relations.

When true, each market includes a related_markets array with co-dependent market relations.

scope=list

exchanges

string

Comma-separated exchange IDs: polymarket, kalshi, limitless, opinion, predictfun. Omit to search across all exchanges.

status

string

default:"active"

Filter by market status: active, closed, resolved, or archived. scope=list defaults to active when omitted.

string

Case-insensitive keyword search across question and description fields.

min_volume

number

Minimum volume filter (USDC).

min_liquidity

number

Minimum liquidity filter (USDC).

limit

number

default:"100"

Results per page (max 100).

cursor

string

Cursor from the previous response.

scope=market

parsec_id

string

Single canonical parsec ID (format: {exchange}:{native_id}). Mutually exclusive with exchange + exchange_market_id.

exchange

string

Exchange identifier for external-ID lookup. Must be paired with exchange_market_id.

exchange_market_id

string

Exchange-native market ID. Must be paired with exchange.

scope=market_batch

parsec_ids

string

Comma-separated parsec IDs (format: {exchange}:{native_id}). Max 100. Mutually exclusive with external_market_keys. If scope is omitted, the server auto-infers market_batch.

external_market_keys

string

Comma-separated external keys (format: {exchange}:{exchange_market_id}). Max 100. Mutually exclusive with parsec_ids.

scope=event

event_id

string

Stored Parsec event-group ID (exact match). The ev:{event_id} alias form is also accepted. Mutually exclusive with exchange + exchange_group_id.

exchange

string

Exchange identifier. Must be paired with exchange_group_id.

exchange_group_id

string

Exchange-native event/group ID. Must be paired with exchange.

Cross-Exchange Relation Expansions

Use relation expansions when you want cross-exchange links returned alongside each market row:

include_matches=true returns matched_markets, which represent published same_market links
include_related=true returns related_markets, which represent published co_dependent links
you can request both in the same call

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parsecapi.com/api/v1/markets?scope=market&parsec_id=kalshi:KXBTC-26MAR10&include_matches=true"

Relation links are precomputed match links. They are decision support, not ground truth. Before trading, verify the market question, resolution terms, timing window, and settlement source directly on the source exchange. Links can still be wrong or incomplete.

Response

(root)

object

Show properties

scope

string

Query scope that produced this response: list, market, market_batch, or event.

markets

Market[]

Array of markets matching the query or selector.

Show Market fields worth knowing first

parsec_id

string

Parsec’s standard market ID: {exchange}:{exchange_market_id}.

parsec_group_id

string

Parsec’s standard event ID for cross-exchange grouping.

exchange

string

Exchange identifier.

exchange_market_id

string

Native market ID on that exchange.

question

string

Market question.

status

string

Market status. Common values are active, closed, resolved, or archived.

matched_markets

RelatedMarketLink[]

Published same_market counterparts when include_matches=true.

Published co_dependent counterparts when include_related=true.

image_url

string | null

Market image URL.

icon_url

string | null

Market icon URL.

price_updated_at

string | null

ISO 8601 timestamp of when bid/ask/last_price was last refreshed. Upgraded to now when live WebSocket data overlays the snapshot.

matched_markets

RelatedMarketLink[]

Cross-exchange same-market relations. Only included when include_matches=true.

Show RelatedMarketLink properties

parsec_id

string

Parsec ID of the related market.

exchange

string

Exchange of the related market.

confidence

number

Match confidence score (0.0–1.0).

confidence_tier

string

Confidence tier: HIGH, MEDIUM, or LOW.

source

string

Source of the match (e.g., embedding, llm).

Co-dependent market relations. Only included when include_related=true.

Show RelatedMarketLink properties

parsec_id

string

Parsec ID of the related market.

exchange

string

Exchange of the related market.

confidence

number

Match confidence score (0.0–1.0).

confidence_tier

string

Confidence tier: HIGH, MEDIUM, or LOW.

source

string

Source of the match.

dependency_type

string | null

Type of dependency.

dependency_direction

string | null

Direction of dependency.

duplicate_ids

string[]

Input IDs that were repeated in a market_batch request.

not_found_ids

string[]

Input IDs that did not resolve to a market in a market_batch request.

pagination

object

Cursor metadata for discovery and event queries that return multiple results.

event

object

Event context. Only present when scope=event.

Show properties

event_id

string

Stored Parsec event-group ID.

title

string

Event title.

market_count

number

Total markets in this event.

exchange_count

number

Number of exchanges covering this event.

duplicate_ids

string[]

IDs that appeared more than once in the request. Only present for scope=market_batch.

not_found_ids

string[]

IDs not found in any data layer. Only present for scope=market_batch.

Relation Link Shape

When relation expansions are enabled, each link includes:

Show properties

parsec_id

string

Counterpart market identifier.

exchange

string

Counterpart exchange.

confidence

number

Matching confidence score.

confidence_tier

string

Pipeline confidence bucket metadata.

source

string

Matching pipeline source label.

status

string | null

Counterpart market status when available: active, closed, or archived.

dependency_type

string | null

Optional dependency classification for co_dependent relations.

dependency_direction

string | null

Optional directionality metadata for co_dependent relations.

Examples

1. Discovery search (`scope=list`)

# scope=list (default) — Browse active Polymarket markets
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parsecapi.com/api/v1/markets?exchanges=polymarket,kalshi&search=bitcoin&min_volume=1000&limit=10"

2. Single market lookup (`scope=market`)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parsecapi.com/api/v1/markets?scope=market&parsec_id=kalshi:KXBTC-26MAR10&include_matches=true"

3. Batch lookup (`scope=market_batch`)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parsecapi.com/api/v1/markets?parsec_ids=kalshi:KXBTC-26MAR10,polymarket:572473&include_matches=true"

4. Event-scoped lookup (`scope=event`)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.parsecapi.com/api/v1/markets?scope=event&event_id=ev:btc-above-85000-mar-10&include_related=true"

{
  "scope": "market_batch",
  "markets": [
    {
      "parsec_id": "kalshi:KXBTC-26MAR10",
      "exchange": "kalshi",
      "exchange_market_id": "KXBTC-26MAR10",
      "question": "Will Bitcoin close above $85,000 on March 10?",
      "status": "active",
      "matched_markets": [
        {
          "parsec_id": "polymarket:572473",
          "exchange": "polymarket",
          "confidence": 0.97,
          "confidence_tier": "HIGH",
          "source": "hierarchical",
          "status": "active"
        }
      ],
      "related_markets": [
        {
          "parsec_id": "kalshi:KXBTCRANGE-26MAR10-80K-90K",
          "exchange": "kalshi",
          "confidence": 0.94,
          "confidence_tier": "HIGH",
          "source": "deterministic_graph",
          "status": "active"
        }
      ]
    }
  ],
  "duplicate_ids": [],
  "not_found_ids": [],
  "pagination": {
    "count": 1,
    "total": 1,
    "has_more": false
  }
}

Onboarding

Market Data

Find the IDs You Need

Scopes

Most Common Request Shapes

Query Reference

Discovery: `scope=list` (default)

Common

scope=list

scope=market

scope=market_batch

scope=event

Cross-Exchange Relation Expansions

Response

Relation Link Shape

Examples

1. Discovery search (`scope=list`)

2. Single market lookup (`scope=market`)

3. Batch lookup (`scope=market_batch`)

4. Event-scoped lookup (`scope=event`)

Onboarding

Market Data

​Find the IDs You Need

​Scopes

​Most Common Request Shapes

​Query Reference

​Discovery: scope=list (default)

​Common

​scope=list

​scope=market

​scope=market_batch

​scope=event

​Cross-Exchange Relation Expansions

​Response

​Relation Link Shape

​Examples

​1. Discovery search (scope=list)

​2. Single market lookup (scope=market)

​3. Batch lookup (scope=market_batch)

​4. Event-scoped lookup (scope=event)

Find the IDs You Need

Scopes

Most Common Request Shapes

Query Reference

Discovery: `scope=list` (default)

Common

scope=list

scope=market

scope=market_batch

scope=event

Cross-Exchange Relation Expansions

Response

Relation Link Shape

Examples

1. Discovery search (`scope=list`)

2. Single market lookup (`scope=market`)

3. Batch lookup (`scope=market_batch`)

4. Event-scoped lookup (`scope=event`)