ClearMarket Events API

openapi: 3.2.0
info:
  title: ClearMarket Events 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: Events
paths:
  /v1/events:
    get:
      operationId: listEvents
      summary: List graded events
      parameters:
      - name: category
        in: query
        schema:
          type: string
          enum:
          - economics
          - financials
          - crypto
          - companies
          - technology
          - politics
          - geopolitics
          - health
          - climate
      - name: platform
        in: query
        schema:
          type: string
          enum:
          - kalshi
          - polymarket
      - name: grade
        in: query
        description: Resolution Clarity Grade of the primary market
        schema:
          type: string
          enum:
          - A
          - B
          - C
      - name: q
        in: query
        description: Token-AND search across question and tags
        schema:
          type: string
      - name: status
        in: query
        description: active = has at least one open market; resolved = none
        schema:
          type: string
          enum:
          - all
          - active
          - resolved
          default: all
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Paged event list. Unknown filter values return an empty page plus a notice naming the valid set.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: rows in this page
                  total:
                    type: integer
                    description: full count under the active filters
                  limit:
                    type: integer
                  offset:
                    type: integer
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                additionalProperties: true
      tags:
      - Events
  /v1/events/{slug}:
    get:
      operationId: getEvent
      summary: One event with all linked markets, cross-venue prices, catalysts, and…
      parameters:
      - name: slug
        in: path
        required: true
        description: Event slug OR ClearMarket event_id — both resolve
        schema:
          type: string
      - name: detail
        in: query
        schema:
          type: string
          enum:
          - full
          - concise
          default: full
      responses:
        '200':
          description: Event fields FLATTENED at the top level (not wrapped in an `event` key), plus linked markets and resolution log
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Event'
                - type: object
                  properties:
                    markets:
                      type: array
                      items:
                        $ref: '#/components/schemas/Market'
                    resolution_log:
                      type: array
                      items:
                        $ref: '#/components/schemas/ResolutionLogEntry'
        '404':
          description: Unknown slug/event_id
      tags:
      - Events
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
    ResolutionLogEntry:
      $id: https://clearmarket.fyi/schema/resolution_log.json
      title: ClearMarket Resolution Log Entry
      description: Append-only audit trail of lifecycle events for a market. Never updated, never deleted. Row sequence reconstructs the market's full history. v0.1 populates status_change / rule_change / resolved events via platform API diffing. resolution_proposed and disputed events require UMA subgraph reader (v0.3+). amended and reversed events require editorial observation. API responses add serve-time fields beyond this canonical schema (_provenance, _notice, and per-endpoint extras).
      type: object
      required:
      - log_id
      - market_id
      - event_type
      - occurred_at
      - recorded_at
      - source
      properties:
        log_id:
          type: integer
          description: BIGSERIAL auto-generated primary key.
        market_id:
          type: string
          pattern: ^CM-MKT-[0-9]{6}$
          description: FK to markets.market_id.
        event_type:
          type: string
          enum:
          - status_change
          - rule_change
          - resolution_proposed
          - disputed
          - resolved
          - amended
          - reversed
          description: 'Lifecycle event type. status_change: market state transition (active -> closed, etc). rule_change: resolution criteria amended mid-life. resolution_proposed: outcome submitted (UMA or staff). disputed: proposed resolution challenged. resolved: final outcome committed. amended: post-resolution correction. reversed: post-resolution full reversal.'
        occurred_basis:
          type:
          - string
          - 'null'
          enum:
          - venue_settlement
          - deadline
          - first_observed
          - null
          description: 'Which clock occurred_at holds. venue_settlement: the venue''s actual settlement timestamp (Kalshi settlement_ts, Polymarket closedTime). deadline: the contract deadline, used as fallback when the venue exposes no settlement time (e.g. delisted before settlement) — deadline-basis timestamps are NOT settlement times. first_observed: neither was available; the first pipeline observation date.'
        occurred_at:
          type: string
          format: date-time
          description: When the event happened, by the venue's clock. Authoritative event timestamp.
        recorded_at:
          type: string
          format: date-time
          description: When ClearMarket captured this event. Gap between occurred_at and recorded_at = detection lag.
        from_value:
          type:
          - string
          - 'null'
          description: 'Prior state. For status_change: old status string. For rule_change: snippet of old rule. NULL for initial creation events.'
        to_value:
          type:
          - string
          - 'null'
          description: New state. Same format as from_value.
        diff:
          type:
          - object
          - 'null'
          description: 'Structured diff for multi-field changes (rule_change, complex amended). Simple status changes leave this null. Free-form JSONB — typical shape: {field_name: {before, after}, reason_prose}.'
        source:
          type: string
          enum:
          - platform_api
          - uma_subgraph
          - editorial_observation
          - platform_announcement
          - cftc_filing
          description: How ClearMarket detected this event. v0.1 supports platform_api, editorial_observation, platform_announcement. uma_subgraph and cftc_filing are v0.3+.
        source_ref:
          type:
          - string
          - 'null'
          description: 'Pointer into the source: UMA dispute ID (for uma_subgraph), announcement URL (platform_announcement), editorial commit hash (editorial_observation). Null for platform_api events.'
        actor:
          type:
          - string
          - 'null'
          description: 'Who caused the event: platform name, UMA proposer address, editorial author. NULL for autonomous platform state transitions where actor is implicit.'
    Event:
      $id: https://clearmarket.fyi/schema/events.json
      title: ClearMarket Event
      description: Canonical record of a prediction market question. One row per canonical tradable question; every event has one or more markets attached. The editorial layer that platforms don't ship. Thematic grouping across events is handled via tags, not a hierarchy. API response shape includes derived fields (venues_covered, current_primary_mark) computed at serve time from the normalized 4-table storage. API responses add serve-time fields beyond this canonical schema (_provenance, _notice, and per-endpoint extras).
      type: object
      required:
      - event_id
      - slug
      - question
      - category
      - published
      - created_at
      - updated_at
      properties:
        event_id:
          type: string
          pattern: ^CM-EVT-[0-9A-Z]{10}$
          description: 'ClearMarket canonical event ID. Format: ''CM-EVT-'' + 9-char vowel-free base36 + 1-char mod-10 check digit. Stable forever — never changes.'
        slug:
          type: string
          description: Human-readable URL form. Can change; not a stable identifier.
        question:
          type: string
          description: ClearMarket-canonical normalized English question text.
        category:
          type: string
          enum:
          - economics
          - financials
          - crypto
          - companies
          - technology
          - health
          - politics
          - geopolitics
          - climate
          description: Top-level institutional classification. 9-enum (matches classify.py CATEGORIES_IN).
        tags:
          type: array
          items:
            type: string
          description: Cross-cutting filter tags (editorial + platform).
        primary_market_id:
          type:
          - string
          - 'null'
          pattern: ^CM-MKT-[0-9]{6}$
          description: FK to markets.market_id. The market quoted as the event's headline price. Auto-computed nightly unless locked.
        primary_market_locked:
          type: boolean
          default: false
          description: Editorial override flag. If true, primary_market_id is not auto-recomputed.
        catalyst_dates:
          type: array
          items:
            type: object
            required:
            - date
            - label
            properties:
              date:
                type: string
                format: date
              type:
                type: string
                description: 'Catalyst type: fomc / cpi / jobs / gdp / ppi / corporate_earnings / etc.'
              label:
                type: string
                description: Human-readable catalyst label.
              source_url:
                type: string
                description: Deep link to the authoritative source for this date (provenance).
            additionalProperties: false
          description: Scheduled real-world events that drive resolution or repricing, with provenance. Macro from FRED, FOMC from the Fed calendar, earnings from API Ninjas, ad-hoc from Exa.
        published:
          type: boolean
          default: false
          description: API gate. If false, event is internal-only and excluded from public API responses.
        editorial_notes:
          type:
          - string
          - 'null'
          description: Public-facing editorial context (why this event is grouped, source quality caveats, cross-platform observations). Surfaced in API responses — this is the editorial layer platforms don't ship.
        venue:
          type:
          - string
          - 'null'
          enum:
          - kalshi
          - polymarket
          - null
          description: Primary venue this event was ingested from. (Cross-venue coverage is surfaced via venues_covered at serve time.)
        bundle_type:
          type:
          - string
          - 'null'
          enum:
          - categorical
          - date_ladder
          - strike_ladder
          - augmented_negrisk
          - singleton
          - null
          description: Resolution-inheritance shape of the event's child markets (OCC class->series analog). Determines which resolution fields are event-level shared vs per-child native.
        resolution_reference:
          type:
          - string
          - 'null'
          description: 'Generic, subject-free event-level resolution ontology (the OCC class-level settlement rule): the data source, mechanism, and deadline that resolve ANY outcome in this event, inherited by all children. Never names a specific child''s subject; per-child references are composed from this plus each child''s group_item_title.'
        created_at:
          type: string
          format: date-time
          description: Row creation timestamp (TIMESTAMPTZ).
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp (TIMESTAMPTZ).
        venues_covered:
          type: array
          items:
            type: string
            enum:
            - kalshi
            - polymarket
          description: DERIVED AT API SERVE TIME. Distinct platform values across all markets linked to this event.
        current_primary_mark:
          type:
          - object
          - 'null'
          description: DERIVED AT API SERVE TIME. Latest marks row for the event's primary_market_id. Shape matches the marks schema response.
        field_provenance:
          type: object
          description: Per-field provenance. Keys are field names; values are objects with 'source' ('platform_api' / 'clearmarket_editorial' / 'derived') and optional metadata.
          additionalProperties:
            type: object
            properties:
              source:
                type: string
                enum:
                - platform_api
                - clearmarket_editorial
                - clearmarket_editorial_fallback
                - derived
                - imputed
                - null_by_venue_limitation
externalDocs:
  description: Human docs, schema tour, and grading methodology
  url: https://clearmarket.fyi/for-data/