v1

latestOpenAPI 3.1.02026-07-2610451.5 KB

One market by ClearMarket market_id

get/v1/markets/{id}

Path parameters

idstring required

Response

Market

market_idstring required

ClearMarket canonical market ID. Format: 'CM-MKT-' + 6-digit zero-padded sequence. Stable forever — never changes.

platform'kalshi' | 'polymarket' required

Source venue.

platform_market_idstring required

Venue's native ID. Kalshi ticker (e.g., 'KXFED-26APR-T3.25') or Polymarket conditionId.

event_idstring nullable

FK to events.event_id. Nullable — editorial assignment. Market can exist without an event.

platform_event_idstring nullable

Platform's own grouping identifier (informational). Kalshi event_ticker; Polymarket event slug.

question_rawstring nullable

Platform's short headline question.

description_rawstring nullable

Platform's long prose description.

category_rawstring nullable

Platform's own category classification.

contract_type'binary' | 'scalar' required

Binary YES/NO or true-scalar payout. v0.1 only populates binary; scalar support v0.2+.

settlement_currency'USD' | 'USDC' required

USD (Kalshi) or USDC (Polymarket).

tick_sizenumber nullable

Minimum price increment.

contract_multipliernumber nullable

Notional per contract. Usually 1.0 for binaries.

underlying_referencestring nullable

Editorial: specific real-world data reference (e.g., 'BLS Series CUUR0000SA0', 'S&P 500 index close per S&P Dow Jones Indices', 'Credible news reporting — no specific feed'). For multi-outcome events this is COMPOSED per child from the event's generic resolution_reference + this market's group_item_title, so each child names its own subject and no sibling's identity leaks.

group_item_titlestring nullable

Per-child subject within a multi-outcome event (the OSI-symbol analog): the candidate, company, strike, or date this market resolves on ('María Corina Machado', 'Discord', '$2 trillion', 'June 2026'). Native from the venue; composes underlying_reference against the event-level resolution_reference.

close_atstring date-time nullable

When trading stops (TIMESTAMPTZ).

last_trading_datestring date-time nullable

Last tradeable date. May differ from close_at.

resolve_atstring date-time nullable

Expected payout date.

status'open' | 'closed' | 'resolved' | 'amended' required

Market lifecycle state.

resolution_rules_rawstring nullable

Full rules text from platform. Source for the parsed resolution_triggers.

arbitration_model'uma_oracle' | 'kalshi_staff' | 'polymarket_staff' | 'platform_auto' | 'determinations_committee' | 'other' | 'null' nullable

Who arbitrates disputes. Stored column (not derived).

resolution_proposer'permissionless' | 'managed_whitelist' | 'platform_staff' | 'gov_agency' | 'null' nullable

Who can propose resolution outcomes. 'managed_whitelist' captures UMA MOOV2 (Aug 2025 — whitelist of 37 proposers).

resolution_sourcestring nullable

What data is cited. Editorial fill for Polymarket where API is blank or prose is vague ('consensus of credible reporting').

source_citationstring uri nullable

Link to the data source itself (not the arbiter's admin page).

source_commitment'named' | 'uncommitted' | 'none' | 'null' nullable

Top-level commitment class, stamped at enrichment from the LLM commitment judgment (rubric version recorded in field_provenance). committed_secondhand markets carry 'named' here — the venue DID commit; the quality deficiency is expressed by the subtype and the grade cap.

source_commitment_subtype'named' | 'committed_secondhand' | 'uncommitted_illustrative' | 'uncommitted_placeholder' | 'none' | 'null' nullable

Full commitment taxonomy (vocabulary: /schema/source-commitment/v1). Feeds the grade ceiling: uncommitted_illustrative caps B; committed_secondhand, uncommitted_placeholder and none cap C.

source_of_recordstring nullable

The committed source's name, copied VERBATIM from the venue's text or source list (never minted by the model — the anti-hallucination gate discards untraceable names). The authority for named; the secondhand source for committed_secondhand; null when uncommitted.

source_status'platform_named' | 'no_committed_source' | 'no_source_stated' | 'unknown' | 'null' nullable

THE stamped source judgment — pure function of the LLM commitment classification, stamped at enrichment. Every surface (API/MCP/web/.json/JSON-LD) reads this; none re-derives from raw field presence. Serve layers emit 'unknown' for pre-refactor rows with no stamp and no commitment; the stored value is never 'unknown'.

source_mechanism'single_authority' | 'precedence' | 'quorum' | 'null' nullable

How multiple sources bind when commitment=named: one controlling authority, a stated precedence/fallback rule, or a quorum (N sources must agree). The CFTC-comment tie-break disclosure, structured.

source_type'gov_stat_agency' | 'central_bank' | 'regulated_data_vendor' | 'media_consensus' | 'court_filing' | 'issuer_announcement' | 'scheduled_event' | 'subjective' | 'other' | 'null' nullable

Objectivity classification of the data source.

thresholdnumber nullable

Numeric resolution threshold (e.g. 150000 for 'Bitcoin reaches $150,000'). Typed top-level field for cross-venue matching; the verbose parse stays in resolution_triggers. Null for non-numeric (occurrence) markets.

direction'above' | 'below' | 'reach' | 'between' | 'occurrence' | 'null' nullable

Polarity of the claim relative to the threshold. An ATTRIBUTE, not an event discriminator — 'above'/'below' at the same threshold/window/settlement_style are the SAME claim (complementary; comparison normalizes polarity before computing a spread).

settlement_style'touch' | 'terminal' | 'relative' | 'occurrence' | 'null' nullable

How the contract settles on the underlying: 'touch' (level ever reached in a window), 'terminal' (level at a single point in time), 'relative' (new high/low), 'occurrence' (a discrete event happens). Distinct from arbitration_model (who arbitrates). Part of the cross-venue event key.

question_idstring nullable

Canonical question id. The normalized real-world question this market settles (subject + threshold + settlement_style, plus window for terminal). Markets sharing a question_id are the SAME question — across venues and across events within a venue. The stable join key CM Signal references. Null where the market has not been canonicalized. (Value prefix is CMX- for historical continuity; it is the ClearMarket question id.)

tagsstring[]

Entity tags for search + cross-cutting retrieval (e.g. 'bitcoin', 'deutsche-bank'). Market-level (events also carry tags). v1 plain strings; later resolved to sameAs Wikidata QIDs.

regulatory_class'DCM' | 'DeFi' | 'Other' | 'null' nullable

Regulatory class of the venue. DCM: CFTC-regulated Designated Contract Market. DeFi: token-vote-arbitrated decentralized protocol. Other: anything not in those two buckets (e.g., Manifold, Augur, Zeitgeist, prediction-market projects without CFTC registration or token-vote arbitration).

analyst_notesstring nullable

ClearMarket editorial note surfacing operational edge cases, dispute risks, or time-cutoff details for the market. v0.2: populated via per-venue fallback in render layer. v0.3+: populate via resolution_triggers.resolution_risks in enhance.py.

contract_terms_urlstring uri nullable

Kalshi PDF link to full contract terms. Kalshi-only.

resolution_outcomestring nullable

Once resolved: 'YES', 'NO', or scalar value. Null until resolved.

resolution_valuenumber nullable

For scalar markets: final numeric value. Null for binary.

resolved_atstring date-time nullable

Actual settlement timestamp.

first_seen_atstring date-time required

When ClearMarket first ingested this market.

last_updated_atstring date-time required

Most recent ingestion update.

field_provenanceobject

Per-field provenance. Keys are field names; values indicate 'platform_api' / 'clearmarket_editorial' / 'derived' / 'null_by_venue_limitation'.