ClearMarket Markets API

openapi: 3.2.0
info:
  title: ClearMarket Markets API
  version: 0.2.1
  description: 'Reference data layer for prediction markets: cross-venue event linking, Resolution Clarity Grades (A/B/C), committed resolution sources with provenance, jurisdiction eligibility screens, live marks, and CM Signal wires across Kalshi and Polymarket. Open access, no key required (optional free key raises rate limits). Attribution required: clearmarket.fyi. Same data via MCP (https://api.clearmarket.fyi/mcp) and A2A (https://api.clearmarket.fyi/a2a).'
  contact:
    name: ClearMarket
    url: https://clearmarket.fyi/for-data/
servers:
- url: https://api.clearmarket.fyi
tags:
- name: Markets
paths:
  /v1/markets/{id}:
    get:
      operationId: getMarket
      summary: One market by ClearMarket market_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Market'
        '404':
          description: Unknown market_id
      tags:
      - Markets
  /v1/markets/movers:
    get:
      operationId: listMovers
      summary: Day-over-day volume movers across all tracked markets
      parameters:
      - name: min_mult
        in: query
        description: Minimum volume multiple vs prior day
        schema:
          type: number
          minimum: 1
          default: 2
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 200
          default: 50
      responses:
        '200':
          description: Movers (empty with a notice when adjacent daily snapshots are unavailable)
          content:
            application/json:
              schema:
                type: object
      tags:
      - Markets
components:
  schemas:
    Market:
      $id: https://clearmarket.fyi/schema/markets.json
      title: ClearMarket Market
      description: One row per market per platform. Raw venue data + ClearMarket editorial fill on top. Auto-ingested daily from Kalshi and Polymarket public APIs. API response shape includes the derived field also_on (the same question on other venues), computed at serve time. Thematic grouping across events is handled via tags on the linked event, not via fields on markets. API responses add serve-time fields beyond this canonical schema (_provenance, _notice, and per-endpoint extras).
      type: object
      required:
      - market_id
      - platform
      - platform_market_id
      - contract_type
      - settlement_currency
      - status
      - first_seen_at
      - last_updated_at
      properties:
        market_id:
          type: string
          pattern: ^CM-MKT-[0-9]{6}$
          description: 'ClearMarket canonical market ID. Format: ''CM-MKT-'' + 6-digit zero-padded sequence. Stable forever — never changes.'
        platform:
          type: string
          enum:
          - kalshi
          - polymarket
          description: Source venue.
        platform_market_id:
          type: string
          description: Venue's native ID. Kalshi ticker (e.g., 'KXFED-26APR-T3.25') or Polymarket conditionId.
        event_id:
          type:
          - string
          - 'null'
          pattern: ^CM-EVT-[0-9A-Z]{10}$
          description: FK to events.event_id. Nullable — editorial assignment. Market can exist without an event.
        platform_event_id:
          type:
          - string
          - 'null'
          description: Platform's own grouping identifier (informational). Kalshi event_ticker; Polymarket event slug.
        question_raw:
          type:
          - string
          - 'null'
          description: Platform's short headline question.
        description_raw:
          type:
          - string
          - 'null'
          description: Platform's long prose description.
        category_raw:
          type:
          - string
          - 'null'
          description: Platform's own category classification.
        contract_type:
          type: string
          enum:
          - binary
          - scalar
          description: Binary YES/NO or true-scalar payout. v0.1 only populates binary; scalar support v0.2+.
        settlement_currency:
          type: string
          enum:
          - USD
          - USDC
          description: USD (Kalshi) or USDC (Polymarket).
        tick_size:
          type:
          - number
          - 'null'
          description: Minimum price increment.
        contract_multiplier:
          type:
          - number
          - 'null'
          description: Notional per contract. Usually 1.0 for binaries.
        underlying_reference:
          type:
          - string
          - 'null'
          description: '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_title:
          type:
          - string
          - 'null'
          description: '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_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When trading stops (TIMESTAMPTZ).
        last_trading_date:
          type:
          - string
          - 'null'
          format: date-time
          description: Last tradeable date. May differ from close_at.
        resolve_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Expected payout date.
        status:
          type: string
          enum:
          - open
          - closed
          - resolved
          - amended
          description: Market lifecycle state.
        resolution_rules_raw:
          type:
          - string
          - 'null'
          description: Full rules text from platform. Source for the parsed resolution_triggers.
        resolution_triggers:
          type:
          - object
          - 'null'
          description: Parsed machine-readable resolution structure. Editorial.
          properties:
            triggers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  description:
                    type: string
                  metric:
                    type: string
                  threshold: {}
                  source:
                    type: string
                  deadline:
                    type:
                    - string
                    - 'null'
                    format: date-time
              description: Array of resolution trigger conditions.
            trigger_logic:
              type: string
              enum:
              - AND
              - OR
              - SINGLE
            exclusions:
              type: array
              items:
                type: string
              description: What explicitly does not count as resolution.
            resolution_risks:
              type: string
              description: Known edge cases or dispute scenarios.
        arbitration_model:
          type:
          - string
          - 'null'
          enum:
          - uma_oracle
          - kalshi_staff
          - polymarket_staff
          - platform_auto
          - determinations_committee
          - other
          - null
          description: Who arbitrates disputes. Stored column (not derived).
        resolution_proposer:
          type:
          - string
          - 'null'
          enum:
          - permissionless
          - managed_whitelist
          - platform_staff
          - gov_agency
          - null
          description: Who can propose resolution outcomes. 'managed_whitelist' captures UMA MOOV2 (Aug 2025 — whitelist of 37 proposers).
        resolution_source:
          type:
          - string
          - 'null'
          description: What data is cited. Editorial fill for Polymarket where API is blank or prose is vague ('consensus of credible reporting').
        source_citation:
          type:
          - string
          - 'null'
          format: uri
          description: Link to the data source itself (not the arbiter's admin page).
        resolution_source_list:
          type:
          - array
          - 'null'
          description: 'Full source set: every venue-listed source (provenance: platform_api) plus prose-named authorities surfaced by the commitment judgment (provenance: clearmarket_editorial). Added by the source-layer refactor 2026-07-03.'
          items:
            type: object
            properties:
              name:
                type:
                - string
                - 'null'
              url:
                type:
                - string
                - 'null'
              provenance:
                type:
                - string
                - 'null'
                enum:
                - platform_api
                - clearmarket_editorial
                - null
        source_commitment:
          type:
          - string
          - 'null'
          enum:
          - named
          - uncommitted
          - none
          - null
          description: 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:
          type:
          - string
          - 'null'
          enum:
          - named
          - committed_secondhand
          - uncommitted_illustrative
          - uncommitted_placeholder
          - none
          - null
          description: '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_record:
          type:
          - string
          - 'null'
          description: 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:
          type:
          - string
          - 'null'
          enum:
          - platform_named
          - no_committed_source
          - no_source_stated
          - unknown
          - null
          description: 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:
          type:
          - string
          - 'null'
          enum:
          - single_authority
          - precedence
          - quorum
          - null
          description: '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:
          type:
          - string
          - 'null'
          enum:
          - gov_stat_agency
          - central_bank
          - regulated_data_vendor
          - media_consensus
          - court_filing
          - issuer_announcement
          - scheduled_event
          - subjective
          - other
          - null
          description: Objectivity classification of the data source.
        threshold:
          type:
          - number
          - 'null'
          description: 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:
          type:
          - string
          - 'null'
          enum:
          - above
          - below
          - reach
          - between
          - occurrence
          - null
          description: 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:
          type:
          - string
          - 'null'
          enum:
          - touch
          - terminal
          - relative
          - occurrence
          - null
          description: '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_id:
          type:
          - string
          - 'null'
          pattern: ^CMX-[0-9A-F]{10}$
          description: 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.)
        tags:
          type: array
          items:
            type: string
          description: 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:
          type:
          - string
          - 'null'
          enum:
          - DCM
          - DeFi
          - Other
          - null
          description: '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_notes:
          type:
          - string
          - 'null'
          description: '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_url:
          type:
          - string
          - 'null'
          format: uri
          description: Kalshi PDF link to full contract terms. Kalshi-only.
        resolution_outcome:
          type:
          - string
          - 'null'
          description: 'Once resolved: ''YES'', ''NO'', or scalar value. Null until resolved.'
        resolution_value:
          type:
          - number
          - 'null'
          description: 'For scalar markets: final numeric value. Null for binary.'
        resolved_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Actual settlement timestamp.
        first_seen_at:
          type: string
          format: date-time
          description: When ClearMarket first ingested this market.
        last_updated_at:
          type: string
          format: date-time
          description: Most recent ingestion update.
        also_on:
          type:
          - array
          - 'null'
          description: DERIVED. The SAME question (same question_id) priced on other venues. Non-null only when this market's question_id has markets on a different venue; null when the question is unique to this venue. Lets a consumer see the cross-venue twin(s) without a second lookup.
          items:
            type: object
            properties:
              venue:
                type: string
                enum:
                - kalshi
                - polymarket
                description: The other venue this question trades on.
              market_id:
                type: string
                description: FK to the counterpart market (market_id) on that venue.
              price:
                type:
                - number
                - 'null'
                description: Last price (implied probability) of the counterpart market.
            required:
            - venue
            - market_id
            additionalProperties: false
        field_provenance:
          type: object
          description: Per-field provenance. Keys are field names; values indicate 'platform_api' / 'clearmarket_editorial' / 'derived' / 'null_by_venue_limitation'.
          additionalProperties:
            type: object
            properties:
              source:
                type: string
                enum:
                - platform_api
                - clearmarket_editorial
                - clearmarket_editorial_fallback
                - composed:event+child
                - inherited:event
                - native:expiration_time
                - derived:group_item_title
                - derived
                - imputed
                - null_by_venue_limitation
externalDocs:
  description: Human docs, schema tour, and grading methodology
  url: https://clearmarket.fyi/for-data/