Full cross-venue matched-market clusters. Router only.

GET

/api/{exchange}/fetchMatchedMarketClusters

const url = 'https://data.predictefy.com/api/polymarket/fetchMatchedMarketClusters?relation=identity&includeRawMatches=false&sort=spread&limit=20&offset=0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://data.predictefy.com/api/polymarket/fetchMatchedMarketClusters?relation=identity&includeRawMatches=false&sort=spread&limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

Projection of the persisted clusters + cluster_members store. Returns delist-stable clusterId values and full UnifiedMarket members. similarity is the stored matcher score, never confidence. volume24h is deliberately OMITTED because the cluster store has no aggregate column; a missing field is not a fabricated zero. No per-cluster relations field is emitted. The relations filter can ask only what verified stores prove: identity membership or subset/superset market_relation_edges; overlap/disjoint return 400 VALIDATION_ERROR. includeRawMatches adds at most 100 pairwise rows per cluster plus rawMatchesTruncated. This stored projection does not implement withOrderbook or a live/order-book overlay. Unknown parameters are ignored.

Authorizations

bearerAuth

Parameters

Path Parameters

exchange

required

string

Allowed values: polymarket kalshi smarkets opinion myriad gemini hyperliquid limitless polymarket_us rain predictfun sxbet pascal xo pred predictstreet novig router

One of the 17 product venues, or router for the all-venues union. SX Bet serves catalog reads, real CLOB order books, the public trades tape, tape-derived candles, Trader Intelligence, and public account resources. It has no server execution lane. Its separate client-side SDK trading lane is live as of 2026-07-27. The SX Bet trading wallet must have a registered sx.bet account and betting enabled once per token per network. There is no venue-official history claim. pascal, xo and pred all serve catalog reads and real CLOB order books, plus a public trades tape on pascal only — xo and pred answer 501 NOT_SUPPORTED for fetchTrades. XO’s is a venue property rather than a gap: its trade endpoints are caller-scoped, so no public XO tape exists to serve. Their execution state differs per venue and is no longer uniform. Pascal is ARMED in production for build, submit, and signed cancel permits (armed 2026-08-12; fleet-verified 2026-08-15). XO advertises exactly its registry row — cancel plus the client-credentialed status refresh, with hosted build and submit disarmed. PRED is production-DARKED (2026-08-13) pending the venue’s key model: PRED_EXCHANGE_ADDRESSES is empty, which unregisters the entire lane, so every PRED execution route including build answers 404 VENUE_NOT_SUPPORTED. None of the three has an account or venue-official history lane. GET /v1/exec/venues remains the authoritative live list; this description is not a claim about one deployment’s runtime gates. PredictStreet serves keyless catalog/detail reads and real two-sided CLOB books. Its ADI Chain execution lane is armed for build and submit; it has no server cancel or hosted settlement lane. Predict Street Limited states it operates under Gibraltar licence 167, and FIFA names it the official prediction-market partner of the FIFA World Cup 2026. Venue eligibility and jurisdiction restrictions remain an operator/compliance responsibility. Pascal’s restricted-jurisdiction and API/data clauses are under owner review. PRED restricts the US, UK, France, Ontario, Singapore, Poland, Thailand, and Taiwan and prohibits location masking; pascal is US-restricted at the venue, and XO read access is partner-provided.

Query Parameters

marketId

string

Canonical “{venue}:{marketId}” anchor. Presence enables lookup mode.

slug

string

Venue market slug. Cross-venue collisions return 400; use marketId.

query

string

Title/question substring.

category

string

minSimilarity

number

<= 1

venues

string

CSV allow-list; the cluster must touch at least one.

excludeVenues

string

CSV deny-list; the cluster must touch none.

minVenues

integer

>= 1

hasDiscrepancy

boolean

relation

string

Allowed values: identity subset superset

Singular alias for relations.

relations

string

CSV of identity, subset, and/or superset. overlap/disjoint return 400.

includeRawMatches

boolean

updatedSince

string format: date-time

Cluster row content-write-time lower bound for identity; edge write-time for typed-only relation filters. Freshness-only matcher refreshes advance asOf (computed_at), not updated_at.

sort

string

default: spread

Allowed values: spread similarity venues newest

limit

integer

default: 20 >= 1 <= 100

offset

integer

page

integer

>= 1

One-based alias for offset; explicit offset wins.

Responses

200

A cluster-grained page of full matched-market clusters.

application/json

object

success

required

boolean

data

required

Array<object>

A delist-stable market cluster. There is deliberately no relations response field: absence is no relation claim. volume24h is deliberately omitted because no stored cluster aggregate exists; member markets retain their own venue-reported volume24h.

object

clusterId

required

Delist-stable internal id; never a venue key.

string

canonicalTitle

required

string | null

category

required

string | null

similarity

required

Stored matcher similarity, never confidence.

number | null

<= 1

venues

required

Array<string>

venueCount

required

integer | null

hasDiscrepancy

required

boolean

aggSpread

required

Indicative stored spread; not executable.

number | null

<= 1

maxSpread

required

Indicative stored spread; not executable.

number | null

<= 1

aggAvgYes

required

number | null

<= 1

markets

required

Array<object>

object

marketId

required

string

title

required

string

description

required

string

outcomes

required

Array<object>

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

volume24h

required

Null means the venue publishes no such figure; 0 is a real venue-published zero

number | null

volume24hSource

Metric-specific provenance for volume24h. venue is published by the venue; derived_cumulative is Predictefy-derived from cumulative snapshots; derived_tape is Predictefy-derived from captured fills. A derived value must carry this field.

string

Allowed values: venue derived_cumulative derived_tape

liquidity

required

Null means the venue publishes no such figure; 0 is a real venue-published zero

number | null

url

required

string

eventId

string

slug

string

resolutionDate

string | null format: date-time

volume

number

openInterest

number

image

required

Known-absent is null; this key is always emitted for market records.

string | null

eventImage

required

Known-absent is null; event/parent artwork is distinct from market artwork.

string | null

category

string

tags

Array<string>

canonicalCategory

required

string | null

canonicalTags

required

Array<string>

tickSize

number

status

string

contractAddress

string

sourceMetadata

object

key

additional properties

any

sourceExchange

string

yes

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

down

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

asOf

required

string | null format: date-time

provenance

required

object

source

required

Venue-rest — per-request REST via the venue adapter (all 16 venues; the default stamp). predictefy-live — served from the live WebSocket hub or live order book; SX Bet overlay-bridge rows use this explicit source. fixture — offline sample data, never production venues. overlay — a serve-time catalog price overlay replaced the stored snapshot price for a fresh price-refresher entry.

string

Allowed values: venue-rest predictefy-live fixture overlay

capabilities

required

Market capability flags. history is true only when Predictefy’s history coverage for the venue is proven under docs/history-coverage.md; it is independent of venue-native history endpoints and the hosted fetchOHLCV route’s availability.

object

read

required

boolean

trade

required

boolean

depth

required

True when the venue exposes real order-book depth rather than an emulated or synthetic top-of-book (such as a single level synthesized from spot price, AMM pool, parimutuel odds, or P2P offer odds). Does not imply tradeable.

boolean

history

required

boolean

asOf

required

Clusters.computed_at; data-as-of, never live.

string | null format: date-time

provenance

required

object

source

required

string

Allowed values: venue-rest predictefy-live fixture

rawMatches

Array<object>

<= 100 items

object

marketAId

required

Canonical markets.id endpoint.

string

marketBId

required

Canonical markets.id endpoint.

string

relation

required

string

Allowed values: identity subset superset

similarity

required

number | null

<= 1

asOf

required

string | null format: date-time

rawMatchesTruncated

Present with rawMatches; true when more than 100 verified pairs exist.

boolean

meta

required

object

asOf

required

string | null format: date-time

coverage

Present on archive-backed trade pages; earliest/latest archived trade for this outcome.

object

from

required

string format: date-time

required

string format: date-time

snapshot

object

version

required

string

loadedAt

required

string format: date-time

asOf

required

string | null format: date-time

totalsAsOf

Present when page.total came from the exact background totals matrix.

string format: date-time

totalUnavailable

Present if and only if page.total is null, explaining why the total is missing. Distinguishes “nothing matched” (total 0) from “your page was served but its matches were not counted” (total null).

string

provenance

required

object

source

required

string

Allowed values: venue-rest predictefy-live fixture

page

required

object

limit

required

integer

offset

required

integer

total

required

Total matching rows, or null when the total was NOT computed — never a fabricated 0. The data page is the product and the count is metadata, so routes may warm an exact total off-request or abandon a count that exceeds its short budget while the page is still served. null is always accompanied by meta.totalUnavailable, which says why; use hasMore / nextCursor to walk the result set.

integer | null

hasMore

required

Whether another page exists. Determined by fetching one row beyond the requested limit, so it stays correct even when total is null.

boolean

nextCursor

Opaque cursor for the next page. Omitted on the final page.

string

Example

{
  "data": [
    {
      "markets": [
        {
          "outcomes": [
            {
              "side": "yes",
              "priceBasis": "venue-composite"
            }
          ],
          "volume24hSource": "venue",
          "yes": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "no": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "up": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "down": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "provenance": {
            "source": "venue-rest"
          }
        }
      ],
      "provenance": {
        "source": "venue-rest"
      },
      "rawMatches": [
        {
          "relation": "identity"
        }
      ]
    }
  ],
  "meta": {
    "provenance": {
      "source": "venue-rest"
    }
  }
}

400

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

Allowed values: VALIDATION_ERROR NOT_SUPPORTED ACCOUNTS_UNSUPPORTED VENUE_NOT_AVAILABLE EXCHANGE_NOT_AVAILABLE MARKET_NOT_FOUND EVENT_NOT_FOUND CLUSTER_NOT_FOUND OUTCOME_NOT_FOUND SNAPSHOT_NOT_FOUND CATALOG_UNAVAILABLE CATALOG_QUERY_TOO_BROAD HISTORY_UNAVAILABLE ROUTE_NOT_FOUND INTERNAL AUTHENTICATION_ERROR PERMISSION_DENIED RATE_LIMIT_EXCEEDED NETWORK_ERROR NOT_FOUND BAD_REQUEST BRIDGE_UNSUPPORTED BRIDGE_UPSTREAM BRIDGE_PROVIDER_UNAVAILABLE BRIDGE_TRANSACTION_NOT_FOUND BRIDGE_SESSION_NOT_FOUND TRANSFER_PLAN_UNSUPPORTED UNAUTHORIZED SCOPE_MISSING PLAN_REQUIRED INSUFFICIENT_CREDITS RATE_LIMITED GEO_BLOCKED VENUE_REGION_BLOCKED IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_CONFLICT ARTIFACT_VERSION_CONFLICT SPEND_CAP_EXCEEDED ARTIFACT_BOUNDS_VIOLATION ARTIFACT_INTEGRITY_MISMATCH VENUE_NOT_SUPPORTED EXECUTION_NOT_FOUND NOT_IMPLEMENTED VENUE_CREDENTIAL_REJECTED VENUE_CREDENTIAL_BREAKER_OPEN GEMINI_TIME_NONCE_REQUIRED GEMINI_HEARTBEAT_KEY_UNSUPPORTED VENUE_RELAY_FAILED EXEC_UNAVAILABLE RAIN_INVALID_OPTION RAIN_INVALID_SIDE RAIN_INVALID_PRICE RAIN_INVALID_AMOUNT RAIN_SLIPPAGE_REQUIRED RAIN_INVALID_DEADLINE RAIN_PHASE_NOT_OPEN RAIN_ORDER_LIMIT_REACHED RAIN_POOL_SAFETY_CHECK_FAILED PLATFORM_UNAVAILABLE PACK_NOT_FOUND BILLING_UNAVAILABLE BILLING_CUSTOMER_REQUIRED INVALID_SIGNATURE FEED_NOT_FOUND FEEDS_UNAVAILABLE FEED_UPSTREAM MATCHES_UNAVAILABLE

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

401

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

402

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

403

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

404

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

429

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

500

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

503

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}