> ## Documentation Index > Fetch the complete documentation index at: https://docs.xo.market/llms.txt > Use this file to discover all available pages before exploring further. # List markets > Returns a paginated list of markets with optional filters. Use `marketScope` to constrain by deployment type (CLOB only, Pulse only, etc.) or pass `marketType` directly. ## OpenAPI ````yaml /data-api-reference/openapi.yaml get /markets openapi: 3.0.3 info: title: XO Data API description: > Public HTTP routes for **market discovery, portfolio reads, and related metadata**, served by the NestJS [`xo-backend`](https://github.com/xo-market/xo) service on the app host (`https://api-mainnet.xo.market`). These endpoints are intentionally separate from the CLOB orderbook REST surface (`openapi.yaml`). Use them to: * list markets and apply filters (status, category, scope, search), * resolve a market by numeric id, by `conditionId`/wrapper address, or by slug, * list short-horizon **Pulse** markets (e.g. BTC 5-minute windows) and fetch a single pulse market by on-chain address, * read a user's public portfolio via `GET /users/portfolio`, and * read **liquidity rewards** (public discovery plus Privy-authenticated `/me` routes). Real-time portfolio snapshots are delivered over the unauthenticated Socket.IO namespace `/portfolio-public`. See the [Portfolio WebSocket](/data-api-reference/portfolio-websocket) guide. All paths use the service `/api` global prefix. In non-production deployments, the full generated Swagger document is available at `/swagger` on the same host. ### Rate limits Data API REST routes share a budget of **100 requests per 10 seconds** per client IP. `/public/liquidity-rewards/*` is throttled separately at **30 requests per 10 seconds**. ### Wire conventions * Pagination is page-based: `page` (1-indexed) and `take` (or `limit` for the Pulse routes). Liquidity-rewards proxied pages use 0-indexed `page` and `page_size`. * Numeric ids are integers; `conditionId` values are `0x`-prefixed 32-byte hex strings. Use `conditionId` as `marketId` on liquidity-rewards routes. * Volume strings are decimal (USD) or WEI-encoded (token), depending on the field name (`totalVolumeInUSD` vs `totalVolume`). * Liquidity-rewards amounts and scores are decimal **strings**. Catalogue/summary BFFs are camelCase; proxied maker/market-day payloads are snake_case. * Authenticated `/liquidity-rewards/*` routes require `Authorization: Bearer `. The `/public/liquidity-rewards/*` prefix does not. ### Market scope for market makers The `/markets` endpoint accepts a `marketScope` query parameter that maps to the on-chain `IXOMarketV1.MarketType` enum (`STANDARD=0`, `PULSE=1`, `CLOB=2`, `CLOB_PULSE=3`). Market makers integrating against the XO CLOB **should only use**: * `onlyClob` — `CLOB` + `CLOB_PULSE` (orderbook markets, both long-form and pulse). * `onlyClobPulse` — `CLOB_PULSE` only (BTC 5-minute pulse). The remaining scopes (`default`, `withClob`, `withPulse`, `onlyPulse`) include `STANDARD` and/or `PULSE` markets, which are **LMSR AMM** deployments and are not tradable through the CLOB orderbook. Ignore those scopes (and rows where `market.type` is `0` or `1`) for MM use. version: 1.0.0 contact: name: XO Market url: https://beta.xo.market servers: - url: https://api-mainnet.xo.market/api description: Production xo-backend (XO mainnet, chainId 3223) security: [] tags: - name: Markets description: Market list, filtering, and per-market metadata. - name: Pulse Markets description: Short-horizon (e.g. BTC 5-minute) Pulse markets. - name: Portfolio description: Unauthenticated public portfolio reads. - name: Liquidity Rewards (public) description: | Unauthenticated liquidity-rewards reads under `/public/liquidity-rewards`. No Privy token. - name: Liquidity Rewards (authenticated) description: | Privy-gated liquidity-rewards reads under `/liquidity-rewards`. Send `Authorization: Bearer `. externalDocs: description: Data API overview url: /data-api-reference/introduction paths: /markets: get: tags: - Markets summary: List markets description: | Returns a paginated list of markets with optional filters. Use `marketScope` to constrain by deployment type (CLOB only, Pulse only, etc.) or pass `marketType` directly. parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Take' - in: query name: search schema: type: string description: Full-text search over the market title. - in: query name: marketScope schema: type: string enum: - default - withClob - withPulse - onlyPulse - onlyClobPulse - onlyClob default: default description: | Convenience filter over deployment types (`IXOMarketV1.MarketType`): * `default` = STANDARD (0) + CLOB (2) * `withClob` = STANDARD + CLOB + CLOB_PULSE * `withPulse` = all * `onlyPulse` = PULSE (1) * `onlyClobPulse` = CLOB_PULSE (3) * `onlyClob` = CLOB + CLOB_PULSE - in: query name: marketType schema: type: string example: 1,3 description: | Comma-separated direct type override: 0=STANDARD, 1=PULSE, 2=CLOB, 3=CLOB_PULSE. Overrides `marketScope` when set. - in: query name: statuses schema: type: string example: ACTIVE,CLOSING_24H description: | Comma-separated statuses. Includes `MarketStatus` values plus the special tokens `CLOSING_24H` and `EXPIRED`. - in: query name: categories schema: type: string example: SPORTS,TECHNOLOGY - in: query name: isFeatureMarket schema: type: boolean - in: query name: sortBy schema: type: string enum: - createdAt - expiresAt - totalVolume - liquidity - priorityScore - conviction - endingSoon - totalVolumeInUSD - in: query name: sortOrder schema: type: string enum: - ASC - DESC responses: '200': description: Paginated market list. content: application/json: schema: $ref: '#/components/schemas/MarketsPage' '429': description: Too Many Requests components: parameters: Page: in: query name: page required: false schema: type: integer minimum: 1 default: 1 description: Page number (1-indexed). Take: in: query name: take required: false schema: type: integer minimum: 1 maximum: 1000 default: 10 description: Page size for `/markets` style endpoints. schemas: MarketsPage: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/Market' meta: $ref: '#/components/schemas/PageMeta' Market: type: object description: | Canonical market metadata. Identifiers MMs care about: * `id` — backend numeric id (used in `/markets/{id}`). * `conditionId` — `0x`-prefixed 32-byte ConditionalTokens condition id. CLOB orderbook routes treat this as `market_id`. * `marketContractAddress` — on-chain contract to target for transactions (settlement, pause/resolve, etc.). For V3 CLOB this is the unified `XOClobMarketManager`. properties: id: type: integer example: 482 contractMarketId: type: string description: | Canonical indexer key. For LMSR / V2 CLOB this is the wrapper contract address; for V3 CLOB this equals `conditionId`. conditionId: type: string nullable: true description: 0x-prefixed bytes32 ConditionalTokens condition id. marketContractAddress: type: string nullable: true versionId: type: integer nullable: true description: 2 = V2 (LMSR / CLOB wrapper), 3 = V3 (XOClobMarketManager). title: type: string slug: type: string description: type: string rules: type: object additionalProperties: true category: type: array items: $ref: '#/components/schemas/MarketCategory' tags: type: array items: type: string type: type: integer enum: - 0 - 1 - 2 - 3 description: 0=STANDARD, 1=PULSE, 2=CLOB, 3=CLOB_PULSE. status: type: string enum: - PENDING - ACTIVE - PAUSED - CLOSED - RESOLVED - VOIDED - CANCELLED startsAt: type: string format: date-time nullable: true expiresAt: type: string format: date-time resolvedAt: type: string format: date-time nullable: true totalVolume: type: string description: Total volume in WEI (collateral token base units). totalVolumeInUSD: type: string description: Total volume in USD with 2-decimal precision. collateralTokenId: type: integer example: 3 imageUrl: type: string metadataUri: type: string winningOutcomeId: type: integer nullable: true outcomes: type: array items: $ref: '#/components/schemas/MarketOutcome' visible: type: boolean isFeatured: type: boolean PageMeta: type: object required: - page - take - itemCount - pageCount - hasPreviousPage - hasNextPage properties: page: type: integer example: 1 take: type: integer example: 10 itemCount: type: integer example: 137 pageCount: type: integer example: 14 hasPreviousPage: type: boolean example: false hasNextPage: type: boolean example: true MarketCategory: type: object properties: id: type: integer example: 7 name: type: string example: SPORTS MarketOutcome: type: object description: | Outcome metadata. The on-chain CTF token id is exposed as `tokenId` and is the value MMs feed into the orderbook (`/book`, `/midpoint`, etc.). properties: id: type: integer title: type: string example: 'YES' tokenId: type: string description: Decimal U256 CTF outcome token id. example: '1234567890123456789012345678901234567890' position: type: integer example: 0 ````