> ## Documentation Index > Fetch the complete documentation index at: https://docs.agg.market/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle). > Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors). > The API reference is generated from https://docs.agg.market/openapi/openapi.json. # List venue markets > Returns paginated venue markets with optional filters for venue, status, category, and date range. When `venueEventId` is set, the response covers that event's ENTIRE matched cluster by default — every venue's markets for the same real-world event, with matched siblings folded into their anchor row rather than repeated. Naming any member of a cluster returns the same page, and the ordering does not depend on which member you name. This is the only way to reach markets that exist on a single venue and therefore have no cross-venue counterpart. Send `cluster=false` for the legacy behaviour (that one venue event's own markets), or `venue=` to keep the cluster scope but narrow to one venue. ## OpenAPI ````yaml /openapi/openapi.json get /venue-markets openapi: 3.0.2 info: title: AGG API version: 1.0.0 description: >- Prediction market aggregator REST API — authentication, users, venue events, venue markets, orderbooks, charts, and execution workflows. servers: - url: https://api.agg.market description: Production security: [] tags: - name: Authentication description: Sign users in and manage their session tokens. - name: Markets description: Find events, markets and outcomes to trade. - name: Market Data description: Live orderbooks, prices, charts and scores for those markets. - name: Trading description: Quote, place, sign, track and cancel orders. - name: Portfolio description: A user's orders, positions, balances and activity. - name: Funding description: Deposit addresses, withdrawals, balance refills and fiat on-ramp. - name: Users description: The signed-in user's profile, linked accounts, KYC and venue keys. - name: Hosted Venue Accounts description: Provision, fund and withdraw from venue accounts hosted for the user. - name: Webhooks description: Configure and operate webhook delivery to your server. - name: Partner Admin description: Server-side reads across your app's users, orders and analytics. - name: Paper Trading description: Simulated accounts and orders for testing without real funds. - name: News description: News feeds linked to markets. - name: Correlated Markets description: Markets related to a given market and the effect of its resolution. paths: /venue-markets: get: tags: - Markets summary: List venue markets description: >- Returns paginated venue markets with optional filters for venue, status, category, and date range. When `venueEventId` is set, the response covers that event's ENTIRE matched cluster by default — every venue's markets for the same real-world event, with matched siblings folded into their anchor row rather than repeated. Naming any member of a cluster returns the same page, and the ordering does not depend on which member you name. This is the only way to reach markets that exist on a single venue and therefore have no cross-venue counterpart. Send `cluster=false` for the legacy behaviour (that one venue event's own markets), or `venue=` to keep the cluster scope but narrow to one venue. operationId: listVenueMarkets parameters: - name: venue in: query required: false schema: $ref: '#/components/schemas/Venue' - name: venueEventId in: query required: false schema: type: string - name: cluster in: query required: false schema: type: string enum: - 'true' - 'false' - name: matchStatus in: query required: false schema: anyOf: - type: array items: type: string enum: - pending - unmatched - review - matched - verified - rejected - type: string enum: - pending - unmatched - review - matched - verified - rejected - name: status in: query required: false schema: anyOf: - type: array items: type: string enum: - open - closed - resolved - unopened - paused - type: string enum: - open - closed - resolved - unopened - paused - name: search in: query required: false schema: type: string - name: createdAtFrom in: query required: false schema: type: string - name: createdAtTo in: query required: false schema: type: string - name: limit in: query required: false schema: minimum: 1 maximum: 100 type: number - name: cursor in: query required: false schema: type: string - name: sortDir in: query required: false schema: type: string enum: - asc - desc - name: sortBy in: query required: false schema: type: string enum: - volume - volume24hr - createdAt - updatedAt - name: context in: query required: false schema: type: string enum: - list - detail - name: aggKey in: query required: false schema: anyOf: - type: array items: type: string - type: string - name: sportsMarketType in: query required: false schema: anyOf: - type: array items: type: string - type: string - name: period in: query required: false schema: anyOf: - type: array items: type: string - type: string - name: marketCategory in: query required: false schema: anyOf: - type: array items: type: string - type: string - name: marketGroup in: query required: false schema: anyOf: - type: array items: type: string - type: string - name: externalIdentifier in: query required: false schema: anyOf: - maxItems: 20 type: array items: type: string - type: string responses: '200': description: '200' content: application/json: schema: type: object required: - data - nextCursor - hasMore properties: data: description: This page of results. type: array items: type: object required: - id - venue - externalIdentifier - question - venueMarketOutcomes properties: id: type: string venue: $ref: '#/components/schemas/Venue' deployerVenue: type: string nullable: true marketId: type: string nullable: true externalIdentifier: type: string venueEventId: type: string nullable: true question: type: string description: type: string nullable: true rulesPrimary: type: string nullable: true rulesSecondary: type: string nullable: true conditionId: type: string nullable: true volume: minimum: 0 type: number nullable: true volume24hr: minimum: 0 type: number nullable: true image: type: string nullable: true venueMarketOutcomes: type: array items: type: object required: - id - venueMarketId - label properties: id: type: string venueMarketId: type: string externalIdentifier: type: string nullable: true label: type: string title: type: string nullable: true price: minimum: 0 maximum: 1 deprecated: true description: >- No longer returned. Fetch live prices from GET /midpoints (pass this outcome's parent venueMarketId in `ids` and match on `outcomes[].venueMarketOutcomeId`), or subscribe to the WebSocket midpoint stream. type: number winner: type: boolean nullable: true payoutPerShare: minimum: 0 maximum: 1 description: >- Per-share USDC payout of this outcome in [0, 1] once the market settles. Source of truth over `winner` when set: a Polymarket UMA 50/50 stores 0.5 on both sides, a Novig void stores its refund prices (e.g. 0.155 / 0.845). `null` = unknown; clients fall back to `winner ? 1/winnerCount : 0`. type: number nullable: true refundAtCost: description: >- True when the venue voided the market and returns every holder their stake (ProphetX). `winner` is true on every outcome and `payoutPerShare` is null; the per-share refund is the holder's own average entry price. Check this BEFORE `payoutPerShare` / `winner ? 1/winnerCount : 0`. type: boolean matchedVenueMarketOutcomes: type: array items: type: object required: - venueMarketId - venueMarketOutcomeId properties: venueMarketId: type: string venueMarketOutcomeId: type: string status: type: string enum: - open - closed - resolved - unopened - paused startDate: type: string nullable: true endDate: type: string nullable: true creationDate: type: string nullable: true createdAt: type: string nullable: true resolutionDate: type: string nullable: true negRisk: type: boolean venues: type: array items: $ref: '#/components/schemas/Venue' venueCount: minimum: 0 type: integer arbReturn: type: number nullable: true aggKey: description: >- Deterministic canonical key computed from this venue's own data; null when not canonicalizable. This is a fetch filter, not a cross-venue join key — it is guaranteed identical across venues only for sports head-to-head and crypto up/down markets, and two members of the same matched cluster can carry different keys. Use the event id and matchedVenueMarkets for identity. type: string nullable: true sportsMarketType: type: string nullable: true sectionRank: type: integer nullable: true period: type: string nullable: true marketCategory: type: string nullable: true marketGroup: type: string nullable: true marketSubtype: type: string nullable: true lineValue: type: number nullable: true minOrderSize: description: >- Per-market minimum order size in shares/contracts. Populated for Polymarket (the market's own floor) and PRED (0.001); null elsewhere. POST /execution/limit-orders validates `sizeRaw` against this value on Polymarket. `null` means AGG ingested no value for this market — NOT that the market has no minimum; other venues enforce their own floors this field does not carry. type: number nullable: true tickSize: description: >- Price increment from the venue's market metadata. A seed value — prefer the runtime-inferred `tick` from GET /orderbooks or GET /orderbook/outcome/:outcomeId when aligning a limit price, since the live grid can be finer than this. type: number nullable: true feeRate: description: >- The venue's published taker fee rate for this market. `null` means we do not have it — fall back to your own table; `0` is a real rate meaning the venue charges nothing. Excludes our builder and clearinghouse fees, which appear in the quote's `feeBreakdown`. See /recipes/venue-fees. type: number nullable: true feeExponent: description: >- Exponent paired with `feeRate`: `0` = flat fraction of notional, `>= 1` = quadratic family. `null` when `feeBasis` is `winnings`, which has no price curve. See /recipes/venue-fees. type: number nullable: true feeBasis: description: >- When the fee is charged: `fill` at execution, `fill_in_game_only` only on fills matched while the event is live, `winnings` at settlement on net profit per market, `exit` only when a position is closed or settles as a winner (opening trades are free). See /recipes/venue-fees. type: string enum: - fill - fill_in_game_only - winnings - exit nullable: true matchedVenueMarkets: type: array items: type: object required: - id - venue - externalIdentifier - question properties: id: type: string venue: $ref: '#/components/schemas/Venue' deployerVenue: type: string nullable: true externalIdentifier: type: string question: type: string description: type: string nullable: true rulesPrimary: type: string nullable: true rulesSecondary: type: string nullable: true volume: minimum: 0 type: number nullable: true volume24hr: minimum: 0 type: number nullable: true status: type: string enum: - open - closed - resolved - unopened - paused conditionId: type: string nullable: true arbReturn: type: number nullable: true shortTitle: type: string nullable: true image: type: string nullable: true venueEvent: type: object required: - id - externalIdentifier properties: id: type: string externalIdentifier: type: string slug: type: string nullable: true title: type: string nullable: true series: type: object required: - id - venue - externalIdentifier properties: id: type: string name: type: string nullable: true venue: type: string externalIdentifier: type: string nullable: true nullable: true venueMarketOutcomes: type: array items: type: object required: - id - venueMarketId - label properties: id: type: string venueMarketId: type: string externalIdentifier: type: string nullable: true label: type: string title: type: string nullable: true price: deprecated: true description: >- No longer returned. Fetch live prices from GET /midpoints — sibling outcomes are covered by the `matched[]` entries of the parent market's midpoint item. type: number winner: type: boolean nullable: true payoutPerShare: minimum: 0 maximum: 1 description: >- Per-share USDC payout of this outcome in [0, 1] once the market settles. Source of truth over `winner` when set: a Polymarket UMA 50/50 stores 0.5 on both sides, a Novig void stores its refund prices (e.g. 0.155 / 0.845). `null` = unknown; clients fall back to `winner ? 1/winnerCount : 0`. type: number nullable: true refundAtCost: description: >- True when the venue voided the market and returns every holder their stake (ProphetX). `winner` is true on every outcome and `payoutPerShare` is null; the per-share refund is the holder's own average entry price. Check this BEFORE `payoutPerShare` / `winner ? 1/winnerCount : 0`. type: boolean venueEvent: type: object required: - id - externalIdentifier - title - image - venue - categories properties: id: description: >- Event id. List responses return one row per matched cluster, and for a matched event this id is the cluster anchor — the handle to use for cross-venue lookups. Re-resolve it from discovery rather than storing it as a permanent key: clusters can merge, after which the id remains a valid event but is no longer the cluster head. See the Matched Clusters guide. type: string externalIdentifier: type: string title: type: string description: type: string nullable: true image: type: string nullable: true venue: $ref: '#/components/schemas/Venue' deployerVenue: type: string nullable: true volume: minimum: 0 type: number nullable: true status: type: string enum: - open - closed - resolved - unopened - paused startDate: type: string nullable: true endDate: type: string nullable: true creationDate: type: string nullable: true gameStartTime: type: string nullable: true categories: type: array items: type: object required: - id - category properties: id: type: string category: type: object required: - id - name - displayName - parentId - eventCount - volume24hr - volume properties: id: type: string name: type: string displayName: type: string nullable: true parentId: type: string nullable: true eventCount: type: number volume24hr: type: number volume: type: number slug: type: string nullable: true subtitle: type: string nullable: true venues: description: >- Venues this row's matched cluster spans — use it for venue badges. On a cluster anchor this is the cluster-wide set; a non-anchor member usually reports the same set, but narrows to its own venue when none of its markets have cross-venue counterparts. type: array items: $ref: '#/components/schemas/Venue' marketCount: minimum: 0 description: >- Number of markets on this event. Use this rather than the length of an embedded venueMarkets array, which is a preview on list responses. On GET /venue-events/:id this counts the whole matched cluster (send cluster=false to scope it to the single venue event); on list responses it counts the row's own event. type: integer venueCount: minimum: 0 description: >- Length of `venues` — the size of the matched cluster. type: integer groupMarketCount: minimum: 0 type: integer groupParentId: description: >- Same-venue companion grouping: the id of this event's group base. NULL means the event IS the base, or is standalone. A venue splits one game into several events (`… - More Markets`, `… : Spread`), and same-venue events never share a matched cluster (the sole exception is Hyperliquid HIP-4 deployers, see /recipes/hyperliquid-deployers) — so on a companion, `matchedVenueEvents[]` lists the other venues' EQUIVALENT companions, not the game's cluster. Use this id (or the shared `aggKey`) to reach the base. See /recipes/sports-market-detail. type: string nullable: true updatedAt: type: string nullable: true venueMarkets: description: >- Embedded markets. On list responses this is a preview of up to three markets chosen to represent the event on a card — not the complete set, and not necessarily the largest; use marketCount for totals. On the by-id response it is uncapped. Deprecated on both — fetch markets from GET /venue-markets?venueEventId=. type: array items: type: object required: - id - venue - externalIdentifier - question - venueMarketOutcomes properties: id: type: string venue: $ref: '#/components/schemas/Venue' deployerVenue: type: string nullable: true marketId: type: string nullable: true externalIdentifier: type: string venueEventId: type: string nullable: true question: type: string description: type: string nullable: true rulesPrimary: type: string nullable: true rulesSecondary: type: string nullable: true conditionId: type: string nullable: true volume: minimum: 0 type: number nullable: true volume24hr: minimum: 0 type: number nullable: true image: type: string nullable: true venueMarketOutcomes: type: array items: type: object required: - id - venueMarketId - label properties: id: type: string venueMarketId: type: string externalIdentifier: type: string nullable: true label: type: string title: type: string nullable: true price: minimum: 0 maximum: 1 deprecated: true description: >- No longer returned. Fetch live prices from GET /midpoints (pass this outcome's parent venueMarketId in `ids` and match on `outcomes[].venueMarketOutcomeId`), or subscribe to the WebSocket midpoint stream. type: number winner: type: boolean nullable: true payoutPerShare: minimum: 0 maximum: 1 description: >- Per-share USDC payout of this outcome in [0, 1] once the market settles. Source of truth over `winner` when set: a Polymarket UMA 50/50 stores 0.5 on both sides, a Novig void stores its refund prices (e.g. 0.155 / 0.845). `null` = unknown; clients fall back to `winner ? 1/winnerCount : 0`. type: number nullable: true refundAtCost: description: >- True when the venue voided the market and returns every holder their stake (ProphetX). `winner` is true on every outcome and `payoutPerShare` is null; the per-share refund is the holder's own average entry price. Check this BEFORE `payoutPerShare` / `winner ? 1/winnerCount : 0`. type: boolean matchedVenueMarketOutcomes: type: array items: type: object required: - venueMarketId - venueMarketOutcomeId properties: venueMarketId: type: string venueMarketOutcomeId: type: string status: type: string enum: - open - closed - resolved - unopened - paused startDate: type: string nullable: true endDate: type: string nullable: true creationDate: type: string nullable: true createdAt: type: string nullable: true resolutionDate: type: string nullable: true negRisk: type: boolean venues: type: array items: $ref: '#/components/schemas/Venue' venueCount: minimum: 0 type: integer arbReturn: type: number nullable: true aggKey: description: >- Deterministic canonical key computed from this venue's own data; null when not canonicalizable. This is a fetch filter, not a cross-venue join key — it is guaranteed identical across venues only for sports head-to-head and crypto up/down markets, and two members of the same matched cluster can carry different keys. Use the event id and matchedVenueMarkets for identity. type: string nullable: true sportsMarketType: type: string nullable: true sectionRank: type: integer nullable: true period: type: string nullable: true marketCategory: type: string nullable: true marketGroup: type: string nullable: true marketSubtype: type: string nullable: true lineValue: type: number nullable: true minOrderSize: description: >- Per-market minimum order size in shares/contracts. Populated for Polymarket (the market's own floor) and PRED (0.001); null elsewhere. POST /execution/limit-orders validates `sizeRaw` against this value on Polymarket. `null` means AGG ingested no value for this market — NOT that the market has no minimum; other venues enforce their own floors this field does not carry. type: number nullable: true tickSize: description: >- Price increment from the venue's market metadata. A seed value — prefer the runtime-inferred `tick` from GET /orderbooks or GET /orderbook/outcome/:outcomeId when aligning a limit price, since the live grid can be finer than this. type: number nullable: true feeRate: description: >- The venue's published taker fee rate for this market. `null` means we do not have it — fall back to your own table; `0` is a real rate meaning the venue charges nothing. Excludes our builder and clearinghouse fees, which appear in the quote's `feeBreakdown`. See /recipes/venue-fees. type: number nullable: true feeExponent: description: >- Exponent paired with `feeRate`: `0` = flat fraction of notional, `>= 1` = quadratic family. `null` when `feeBasis` is `winnings`, which has no price curve. See /recipes/venue-fees. type: number nullable: true feeBasis: description: >- When the fee is charged: `fill` at execution, `fill_in_game_only` only on fills matched while the event is live, `winnings` at settlement on net profit per market, `exit` only when a position is closed or settles as a winner (opening trades are free). See /recipes/venue-fees. type: string enum: - fill - fill_in_game_only - winnings - exit nullable: true matchedVenueMarkets: description: >- The same market on other venues, as linked by AGG's matching pipeline. This is the cross-venue linkage — it hangs off each market, not off the event, and is complete regardless of which cluster member you queried. type: array items: type: object required: - id - venue - externalIdentifier - question properties: id: type: string venue: $ref: '#/components/schemas/Venue' deployerVenue: type: string nullable: true externalIdentifier: type: string question: type: string description: type: string nullable: true rulesPrimary: type: string nullable: true rulesSecondary: type: string nullable: true volume: minimum: 0 type: number nullable: true volume24hr: minimum: 0 type: number nullable: true status: type: string enum: - open - closed - resolved - unopened - paused conditionId: type: string nullable: true arbReturn: type: number nullable: true shortTitle: type: string nullable: true image: type: string nullable: true venueEvent: type: object required: - id - externalIdentifier properties: id: type: string externalIdentifier: type: string slug: type: string nullable: true title: type: string nullable: true series: type: object required: - id - venue - externalIdentifier properties: id: type: string name: type: string nullable: true venue: type: string externalIdentifier: type: string nullable: true nullable: true venueMarketOutcomes: type: array items: type: object required: - id - venueMarketId - label properties: id: type: string venueMarketId: type: string externalIdentifier: type: string nullable: true label: type: string title: type: string nullable: true price: deprecated: true description: >- No longer returned. Fetch live prices from GET /midpoints — sibling outcomes are covered by the `matched[]` entries of the parent market's midpoint item. type: number winner: type: boolean nullable: true payoutPerShare: minimum: 0 maximum: 1 description: >- Per-share USDC payout of this outcome in [0, 1] once the market settles. Source of truth over `winner` when set: a Polymarket UMA 50/50 stores 0.5 on both sides, a Novig void stores its refund prices (e.g. 0.155 / 0.845). `null` = unknown; clients fall back to `winner ? 1/winnerCount : 0`. type: number nullable: true refundAtCost: description: >- True when the venue voided the market and returns every holder their stake (ProphetX). `winner` is true on every outcome and `payoutPerShare` is null; the per-share refund is the holder's own average entry price. Check this BEFORE `payoutPerShare` / `winner ? 1/winnerCount : 0`. type: boolean arbReturn: type: number nullable: true series: type: object required: - externalIdentifier properties: externalIdentifier: type: string nullable: true recurrence: type: string nullable: true aggKey: description: >- Deterministic canonical key computed from this venue's own data; null when not canonicalizable. This is a fetch filter, not a cross-venue join key — it is guaranteed identical across venues only for sports head-to-head and crypto up/down markets, and two members of the same matched cluster can carry different keys. Use the event id and matchedVenueMarkets for identity. type: string nullable: true structureType: type: string enum: - candidate - sport - axis - dates nullable: true sport: type: string nullable: true settlementDiff: type: object required: - sharedSummary - differences properties: sharedSummary: type: string differences: type: array items: type: object required: - type - title - perVenue properties: type: type: string title: type: string perVenue: type: object additionalProperties: type: string summary: type: string nullable: true matchedVenueEvents: type: array items: type: object required: - id - venue - externalIdentifier - title properties: id: description: >- Sibling event id. Re-resolve from discovery rather than persisting: cluster merges re-point members onto the surviving root, after which this id remains a valid event but is no longer the cluster head. type: string venue: $ref: '#/components/schemas/Venue' externalIdentifier: type: string title: type: string slug: type: string nullable: true status: type: string enum: - open - closed - resolved - unopened - paused series: type: object required: - externalIdentifier properties: externalIdentifier: type: string nullable: true nullable: true nextCursor: description: >- Pass as `cursor` to fetch the next page; `null` on the last page. type: string nullable: true hasMore: description: '`true` when another page exists.' type: boolean '400': description: '400' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - appId: [] components: schemas: Venue: type: string enum: - kalshi - polymarket - limitless - opinion - predict - pred - tiprun - probable - myriad - hyperliquid - novig - prophetx - betdex ErrorMessage: type: object required: - message properties: message: type: string securitySchemes: appId: type: apiKey in: header name: x-app-id description: Your application ID. Required for all app-tier and user-tier routes. ````