> ## Documentation Index
> Fetch the complete documentation index at: https://docs.totalis.trade/llms.txt
> Use this file to discover all available pages before exploring further.
# List Markets (Flat)
> A flat, paginated feed of every individual market — ungrouped and never truncated. Built for market makers and partners syncing the full tradeable universe.
**Building parlays?** Every market carries an `exclusion_keys` array. Two
markets can share a parlay only if their arrays don't intersect — a plain
set-intersection check, with no correlation rules to maintain client-side.
Need every market for a single game? `GET /markets/events/{event_ticker}`
returns one event's complete market set in a single request.
## OpenAPI
````yaml GET /v1/markets/list
openapi: 3.0.3
info:
title: Totalis RFQ API
version: 2.1.0
description: >-
Public REST surface for the Totalis parlay RFQ platform — a decentralized
request-for-quote marketplace for parlay bets across Kalshi and Polymarket,
with on-chain Solana vault settlement.
**Wire format**: snake_case JSON. All successful responses are wrapped in `{
"data": ... }`; list endpoints add `meta` with cursor-based pagination.
Errors use a `{ "error": { code, message, details? } }` envelope.
**Authentication**: programmatic clients send `X-API-Key`; the web dashboard
uses Privy JWTs (`Authorization: Bearer ...`). Any authenticated user can
both place parlays and quote as a market maker — there is no separate MM
role. Admin endpoints are out of scope for this public reference.
**Rate limiting**: 100 req/min anonymous, 300 req/min authenticated.
Responses include `X-RateLimit-*` headers. Request body limit: 256KB.
**Pagination**: list endpoints use opaque cursor pagination. Pass
`meta.cursor` from the previous response as `?cursor=...` to fetch the next
page; do not parse or construct cursors client-side.
servers:
- url: https://api.totalis.trade
description: Production
security:
- ApiKey: []
tags:
- name: Markets
description: Cached Kalshi and Polymarket market data.
- name: User
description: User profile, wallet, and devnet helpers.
- name: API Keys
description: Manage programmatic access keys for the authenticated user.
paths:
/v1/markets/list:
get:
tags:
- Markets
summary: List markets (flat)
description: >-
Returns a paginated list of individual markets, most-traded first.
Unlike the event-grouped `GET /markets`, results aren't grouped by event
and are never capped per event, so every market is reachable. Filter by
venue, category, subcategory, or one or more series.
Paginate with `cursor` until it returns `null`; `meta.total` is the
total number of matches. For a complete sync, de-duplicate by `ticker` —
markets with equal volume aren't guaranteed a stable order between
requests. Scoping to a `subcategory` or `series_ticker` set avoids this
entirely.
operationId: listMarketsFlat
parameters:
- name: category
in: query
description: Filter by category, e.g. `sports` or `crypto`.
schema:
type: string
enum:
- crypto
- economics
- finance
- sports
- politics
- tech
- entertainment
- weather
- all
- name: venue
in: query
description: 'Filter by venue: `kalshi` or `polymarket`.'
schema:
$ref: '#/components/schemas/Venue'
- name: subcategory
in: query
description: Filter by subcategory, e.g. `world_cup`. Requires `category`.
schema:
$ref: '#/components/schemas/SubcategorySlug'
- name: frequency
in: query
description: 'Filter by series cadence: `daily`, `weekly`, `monthly`, or `hourly`.'
schema:
type: string
enum:
- daily
- weekly
- monthly
- hourly
- name: series_ticker
in: query
description: >-
Filter by one or more series, comma-separated and case-sensitive,
e.g. `KXWCAST,KXWCTCORNERS`. Up to 100.
schema:
type: string
- name: status
in: query
description: >-
Filter by status. Defaults to tradeable markets (`active,open`);
pass a comma-separated list of `active`, `open`, `closed`,
`settled`, `finalized`, or `all`. An empty or unrecognised value
returns 400.
schema:
type: string
default: active,open
- $ref: '#/components/parameters/CursorParam'
- name: limit
in: query
description: >-
Number of markets per page, from 1 to 500. Defaults to 100. Only the
first 10,000 matches are reachable — narrow the filters to page
further.
schema:
type: integer
default: 100
minimum: 1
maximum: 500
responses:
'200':
description: OK
headers:
Cache-Control:
schema:
type: string
example: public, max-age=15, stale-while-revalidate=60
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- markets
properties:
markets:
type: array
items:
$ref: '#/components/schemas/Market'
meta:
allOf:
- $ref: '#/components/schemas/PaginationMeta'
- type: object
properties:
total:
type: integer
description: >-
Total markets matching the filters across all
pages.
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
'503':
description: Market index unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security: []
components:
schemas:
Venue:
type: string
enum:
- kalshi
- polymarket
description: Source venue for a market.
SubcategorySlug:
type: string
description: >-
Subcategory wire format (lowercase snake_case). Valid values depend on
the selected `category` and are enforced server-side.
enum:
- nba
- ncaa
- nfl
- nhl
- mlb
- ufc
- lol
- epl
- efl
- la_liga
- world_cup
- bundesliga
- liga_portugal
- ligue_1
- f1
- ipl
- btc
- eth
- sol
- stocks
- indices
- etfs
- earnings
- rates
- inflation
- commodities
- fx
- jobs
- ai
- companies
- other
Market:
type: object
properties:
ticker:
type: string
description: >-
Unique market identifier on its venue. **Kalshi**: market ticker
(e.g. `KXBTC-25FEB07-T100000`). **Polymarket**: `condition_id`, the
0x-prefixed hex string from Polymarket's CTF (e.g. `0x4d2…`); not
the gamma id, question id, or market slug. Yes/no CLOB token ids are
not returned by this API.
event_ticker:
type: string
description: >-
Event identifier the market belongs to. **Kalshi**: event ticker
(e.g. `KXBTC-25FEB07`). **Polymarket**: Gamma `event_slug` (falls
back to `market_slug` when no parent event exists).
series_ticker:
type: string
description: >-
Series identifier the event belongs to. **Kalshi**: series ticker
(e.g. `KXBTC`). **Polymarket**: Gamma `market_slug` — Polymarket has
no native series concept, so we key whitelisting on the market slug.
title:
type: string
subtitle:
type: string
nullable: true
yes_sub_title:
type: string
nullable: true
no_sub_title:
type: string
nullable: true
bet_group:
type: string
nullable: true
description: >-
Polymarket-only: section label for the row (e.g. "Match O/U 21.5").
Always null on Kalshi rows.
category:
type: string
subcategory:
type: string
nullable: true
frequency:
type: string
nullable: true
description: >-
Cadence of the underlying series: daily/weekly/monthly/hourly/other.
Null for categories without timeframe pills.
venue:
$ref: '#/components/schemas/Venue'
status:
type: string
yes_bid:
type: number
yes_ask:
type: number
no_bid:
type: number
no_ask:
type: number
last_price:
type: number
price_to_beat:
type: number
nullable: true
description: >-
Reference price for Polymarket up/down markets. Null on Kalshi and
on non-up/down Polymarket markets.
volume:
type: integer
volume_24h:
type: integer
open_interest:
type: integer
venue_url:
type: string
nullable: true
description: Canonical market URL on its source venue.
open_time:
type: string
format: date-time
close_time:
type: string
format: date-time
expiration_time:
type: string
format: date-time
exclusion_keys:
type: array
items:
type: string
description: >-
Parlay-correlation keys. Two markets **cannot co-exist in the same
parlay if (and only if) their `exclusion_keys` arrays intersect** —
i.e. share at least one string. Apply a pure set-intersection; there
is no rule table to maintain client-side. The keys encode every
correlation rule (cross-series exclusion groups, threshold ladders,
same-game sports family/kind/participant correlation, Polymarket
sub-events). Keys are opaque and namespaced by reason and scope
(e.g. `kp::moneyline|spread`, `grp::`,
`fam::`), and are derived solely from the market
itself, so a selected leg can snapshot its keys and compare them
later. The plain one-leg-per-event rule (same `event_ticker`) is
intentionally not encoded here. Always present; an empty array means
the market participates in no correlation rule.
PaginationMeta:
type: object
properties:
cursor:
type: string
nullable: true
has_more:
type: boolean
limit:
type: integer
description: Maximum number of items requested for this page.
offset:
type: integer
description: Number of items skipped before this page.
total:
type: integer
description: >-
Total number of items available across all pages, when returned by
the endpoint.
ErrorEnvelope:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorBody'
ErrorBody:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- VALIDATION_ERROR
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- CONFLICT
- RATE_LIMITED
- PAYLOAD_TOO_LARGE
- INTERNAL_ERROR
- SERVICE_UNAVAILABLE
description: Machine-readable error code.
message:
type: string
description: Human-readable error message.
details:
type: object
description: Additional error context.
retry_after:
type: integer
nullable: true
description: Seconds until retry; set on 429 responses.
parameters:
CursorParam:
name: cursor
in: query
description: >-
Opaque pagination cursor from a previous response's `meta.cursor`. Do
not construct manually.
schema:
type: string
responses:
BadRequest:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >-
Programmatic API key. Sent as `X-API-Key: `. Generate one from the
Totalis dashboard. The same header is accepted on the WebSocket auth
message.
````