---
title: "Find Related Markets"
method: GET
path: "/api/router/fetchRelatedMarkets"
tags: ["Hosted"]
---

# Find Related Markets

`GET /api/router/fetchRelatedMarkets`

Find related markets across venues. Discovers subset/superset market relationships where one market's outcome implies another, with live prices.

## Query parameters

- `query` string
- `category` string
- `market` UnifiedMarket
  - `marketId` string, required — The unique identifier for this market
  - `eventId` string — Link to parent event
  - `title` string, required — The market title (e.g., "Will BTC close above $100k on Dec 31?").
  - `description` string, required — Long-form market description or resolution criteria.
  - `slug` string — URL-friendly slug for the market.
  - `outcomes` MarketOutcome[], required — The possible outcomes for this market.
    - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
    - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
    - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
    - `price` number, required — Probability between 0.0 and 1.0.
    - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
    - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
  - `resolutionDate` string, date-time — When the market is scheduled to resolve. Optional because some venues do not publish a cutoff for every market (e.g. Opinion categorical children) — emit `undefined` rather than coercing to epoch.
  - `volume24h` number, required — Trading volume over the past 24 hours (USD).
  - `volume` number — Total / Lifetime volume
  - `liquidity` number, required — Current market liquidity (USD).
  - `openInterest` number — Total value of outstanding contracts (USD).
  - `url` string, required — Canonical URL to view the market on the venue.
  - `image` string — Optional image URL for the market.
  - `category` string — Optional category label. Venue-defined — common values include "Sports", "Politics", "Crypto", "Economics", "Science", "Culture". Polymarket uses finer-grained categories like "Bitcoin", "Soccer", "Economic Policy"; Kalshi uses broader ones like "Sports" or "Mentions".
  - `tags` string[] — Optional list of tags. More granular than category — e.g. ["Crypto", "Crypto Prices", "Bitcoin"] or ["Politics", "Elections", "Trump"]. Tags vary by venue: Polymarket markets carry several, Kalshi typically one.
  - `tickSize` number — Minimum price increment (e.g., 0.01, 0.001)
  - `status` string — Venue-native lifecycle status (e.g. 'active', 'closed', 'archived').
  - `contractAddress` string — On-chain contract / condition identifier where applicable (Polymarket conditionId, etc.).
  - `sourceMetadata` object — Raw venue-specific metadata not captured by first-class fields (e.g. Kalshi series_ticker / series_title from the parent event, Polymarket series). Passed through verbatim so downstream consumers can recover anything the unified shape omits. Each venue populates what it has.
  - `sourceExchange` string — The exchange/venue this market originates from (e.g. 'polymarket', 'kalshi'). Populated by the Router.
  - `yes` MarketOutcome
    - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
    - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
    - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
    - `price` number, required — Probability between 0.0 and 1.0.
    - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
    - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
  - `no` MarketOutcome
    - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
    - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
    - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
    - `price` number, required — Probability between 0.0 and 1.0.
    - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
    - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
  - `up` MarketOutcome
    - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
    - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
    - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
    - `price` number, required — Probability between 0.0 and 1.0.
    - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
    - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
  - `down` MarketOutcome
    - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
    - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
    - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
    - `price` number, required — Probability between 0.0 and 1.0.
    - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
    - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
- `marketId` string
- `slug` string
- `url` string
- `relation` 'identity' | 'complement' | 'subset' | 'superset' | 'overlap' | 'disjoint'
- `minConfidence` number
- `limit` number
- `includePrices` boolean
- `minDifference` number
- `sort` 'confidence' | 'volume' | 'priceDifference'

## Response `200`

Find Related Markets response

- object
  - `success` boolean
  - `error` ErrorDetail — Structured error envelope returned inside `BaseResponse.error` and `ErrorResponse.error`. Hosted-mode endpoints populate `code`, `retryable`, and optionally `exchange` / `detail`; legacy local-mode endpoints may still return only `message`.
    - `message` string — Human-readable error message.
    - `code` 'HOSTED_TRADING_ERROR' | 'INSUFFICIENT_ESCROW_BALANCE' | 'ORDER_SIZE_TOO_SMALL' | 'INVALID_API_KEY' | 'OUTCOME_NOT_FOUND' | 'CATALOG_UNAVAILABLE' | 'BUILT_ORDER_EXPIRED' | 'INVALID_SIGNATURE' | 'NO_LIQUIDITY' | 'MISSING_WALLET_ADDRESS' | 'BAD_REQUEST' | 'AUTHENTICATION_ERROR' | 'PERMISSION_DENIED' | 'NOT_FOUND' | 'ORDER_NOT_FOUND' | 'MARKET_NOT_FOUND' | 'EVENT_NOT_FOUND' | 'RATE_LIMIT_EXCEEDED' | 'INVALID_ORDER' | 'INSUFFICIENT_FUNDS' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'EXCHANGE_NOT_AVAILABLE' | 'NOT_SUPPORTED' — Stable machine-readable error code. Hosted-mode errors use the `HostedTradingError` family (e.g. `INSUFFICIENT_ESCROW_BALANCE`, `BUILT_ORDER_EXPIRED`); pre-hosted local errors use the legacy family (e.g. `BAD_REQUEST`, `NOT_FOUND`).
    - `retryable` boolean — Hint for clients: when `true`, the same request may succeed on retry (e.g. transient network or rate-limit conditions); when `false`, the caller should not retry without modifying the request.
    - `exchange` string, nullable — Venue the error originated from, when known (e.g. 'polymarket', 'kalshi').
    - `detail` object, nullable — Free-form hosted-mode detail blob. Shape depends on `code` — e.g. for `INSUFFICIENT_ESCROW_BALANCE` it may include `{ requested, available }`; for `ORDER_SIZE_TOO_SMALL` it may include `{ min }`; for `BUILT_ORDER_EXPIRED` it may include `{ expiry }`.
  - `data` PriceComparison[]
    - `market` UnifiedMarket, required
      - `marketId` string, required — The unique identifier for this market
      - `eventId` string — Link to parent event
      - `title` string, required — The market title (e.g., "Will BTC close above $100k on Dec 31?").
      - `description` string, required — Long-form market description or resolution criteria.
      - `slug` string — URL-friendly slug for the market.
      - `outcomes` MarketOutcome[], required — The possible outcomes for this market.
        - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
        - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
        - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
        - `price` number, required — Probability between 0.0 and 1.0.
        - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
        - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
      - `resolutionDate` string, date-time — When the market is scheduled to resolve. Optional because some venues do not publish a cutoff for every market (e.g. Opinion categorical children) — emit `undefined` rather than coercing to epoch.
      - `volume24h` number, required — Trading volume over the past 24 hours (USD).
      - `volume` number — Total / Lifetime volume
      - `liquidity` number, required — Current market liquidity (USD).
      - `openInterest` number — Total value of outstanding contracts (USD).
      - `url` string, required — Canonical URL to view the market on the venue.
      - `image` string — Optional image URL for the market.
      - `category` string — Optional category label. Venue-defined — common values include "Sports", "Politics", "Crypto", "Economics", "Science", "Culture". Polymarket uses finer-grained categories like "Bitcoin", "Soccer", "Economic Policy"; Kalshi uses broader ones like "Sports" or "Mentions".
      - `tags` string[] — Optional list of tags. More granular than category — e.g. ["Crypto", "Crypto Prices", "Bitcoin"] or ["Politics", "Elections", "Trump"]. Tags vary by venue: Polymarket markets carry several, Kalshi typically one.
      - `tickSize` number — Minimum price increment (e.g., 0.01, 0.001)
      - `status` string — Venue-native lifecycle status (e.g. 'active', 'closed', 'archived').
      - `contractAddress` string — On-chain contract / condition identifier where applicable (Polymarket conditionId, etc.).
      - `sourceMetadata` object — Raw venue-specific metadata not captured by first-class fields (e.g. Kalshi series_ticker / series_title from the parent event, Polymarket series). Passed through verbatim so downstream consumers can recover anything the unified shape omits. Each venue populates what it has.
      - `sourceExchange` string — The exchange/venue this market originates from (e.g. 'polymarket', 'kalshi'). Populated by the Router.
      - `yes` MarketOutcome
        - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
        - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
        - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
        - `price` number, required — Probability between 0.0 and 1.0.
        - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
        - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
      - `no` MarketOutcome
        - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
        - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
        - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
        - `price` number, required — Probability between 0.0 and 1.0.
        - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
        - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
      - `up` MarketOutcome
        - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
        - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
        - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
        - `price` number, required — Probability between 0.0 and 1.0.
        - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
        - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
      - `down` MarketOutcome
        - `outcomeId` string, required — Outcome ID for trading operations (CLOB Token ID for Polymarket, Market Ticker for Kalshi)
        - `marketId` string — The market this outcome belongs to (set automatically when outcomes are built)
        - `label` string, required — Human-readable outcome label (e.g., "Yes", "No", candidate name).
        - `price` number, required — Probability between 0.0 and 1.0.
        - `priceChange24h` number — Change in price over the past 24 hours, as an absolute probability delta.
        - `metadata` object — Exchange-specific metadata (e.g., clobTokenId for Polymarket)
    - `relation` 'identity' | 'complement' | 'subset' | 'superset' | 'overlap' | 'disjoint', required
    - `confidence` number, required
    - `reasoning` string, nullable, required
    - `bestBid` number, nullable, required
    - `bestAsk` number, nullable, required
    - `venue` string, required

---

[API](https://skmtc.net/pmxt-dev/apis/pmxt-hosted-api.md) · [All operations](https://skmtc.net/pmxt-dev/apis/pmxt-hosted-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pmxt-dev/pmxt-hosted-api/versions/da5293255d19/schema)