MarketSnapshot

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/0xinsider-com/json-schema/0xinsider-com-market-snapshot-schema.json",
  "title": "MarketSnapshot",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/0xinsider-com-openapi.json#/components/schemas/MarketSnapshot",
  "type": "object",
  "required": [
    "market",
    "outcomes",
    "liquidity",
    "sports",
    "freshness"
  ],
  "properties": {
    "market": {
      "type": "object",
      "required": [
        "id",
        "condition_id",
        "provider",
        "title",
        "slug",
        "page_slug",
        "event_slug",
        "category",
        "status",
        "description",
        "image",
        "series_slug",
        "market_type",
        "market_result",
        "created_at",
        "end_date",
        "resolved_at"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "condition_id": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "page_slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "event_slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "category": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "closed"
          ],
          "description": "closed once Polymarket has closed trading or the market has resolved; active otherwise. The same rule labels a market on markets/search, markets/explore and market/{condition_id}/snapshot."
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "image": {
          "type": [
            "string",
            "null"
          ]
        },
        "series_slug": {
          "type": [
            "string",
            "null"
          ],
          "description": "Polymarket series slug from the canonical identity row, null when unavailable. A sports series identifies a league and must not be used as a per-matchup grouping key."
        },
        "market_type": {
          "deprecated": true,
          "type": [
            "string",
            "null"
          ],
          "description": "Always null. Deprecated (#24169): 0xinsider has never stored a value for this field. The key stays on the wire until its sunset on 2027-02-01 (#29352), when it is removed; do not read it."
        },
        "market_result": {
          "deprecated": true,
          "type": [
            "string",
            "null"
          ],
          "description": "Always null. Deprecated (#24169): 0xinsider stores no value for this field on a Polymarket market. The key stays on the wire until its sunset on 2027-02-01 (#29352), when it is removed; do not read it. market.status and market.resolved_at say whether the market has closed or resolved."
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "end_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "resolved_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "outcomes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "side",
          "label",
          "top_of_book"
        ],
        "properties": {
          "side": {
            "type": "string",
            "enum": [
              "yes",
              "no"
            ]
          },
          "label": {
            "type": "string"
          },
          "token_id": {
            "type": "string"
          },
          "current_price": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "The outcome's display price, the probability Polymarket shows for it: the midpoint of the cached top of book when the spread is at most 0.10, otherwise the token's last trade price. Omitted when neither is known, including a book wider than 0.10 with no last trade on record; top_of_book still carries that book's best_bid and best_ask. expand=trust explains a missing value in trust.current_price."
          },
          "top_of_book": {
            "$ref": "#/$defs/MarketSnapshotTopOfBook"
          }
        }
      }
    },
    "liquidity": {
      "type": "object",
      "required": [
        "source",
        "volume_usd",
        "liquidity_usd",
        "volume_24h_usd",
        "volume_24h_as_of",
        "last_price"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "volume_usd": {
          "type": [
            "number",
            "null"
          ],
          "description": "Polymarket's traded-volume figure for the market, as last stored: cumulative taker volume in shares, each counted at its $1 settlement value, not the cash that changed hands (100 shares bought at $0.40 add 100, not 40). It can lag Polymarket's current figure. The name ends in _usd because Polymarket prints this figure with a dollar sign; it is a share count. Null when unavailable."
        },
        "liquidity_usd": {
          "type": [
            "number",
            "null"
          ]
        },
        "volume_24h_usd": {
          "type": [
            "number",
            "null"
          ],
          "description": "Polymarket's taker volume over the 24 hours before volume_24h_as_of, in shares, each counted at its $1 settlement value, not the cash that changed hands (100 shares bought at $0.40 add 100, not 40). The name ends in _usd because Polymarket prints volume with a dollar sign; it is a share count. Null when Polymarket does not report one: it omits the figure on closed markets and on open markets with no trades in the last 24 hours."
        },
        "volume_24h_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When 0xinsider read volume_24h_usd from Polymarket; the figure covers the 24 hours before this time. Null exactly when volume_24h_usd is null."
        },
        "last_price": {
          "type": [
            "number",
            "null"
          ],
          "description": "Always null. Polymarket snapshot prices come from outcome top-of-book midpoints."
        }
      }
    },
    "sports": {
      "type": "object",
      "required": [
        "status",
        "source"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "fresh",
            "stale",
            "not_live",
            "unavailable"
          ]
        },
        "source": {
          "type": "string"
        },
        "live_match_key": {
          "type": "string"
        },
        "live_league_key": {
          "type": "string"
        },
        "live_score": {
          "description": "Live-score period and elapsed may be omitted when unavailable (older responses use null). A score entry may omit full_name when it equals team; fall back to team. Distinct aliases and score admission markers are preserved. For live esports, scores[].map_score retains an available pair through an update omitting both sides only within the same live map, series format and series totals. Map changes and final state follow current provider updates; absent detail remains unavailable. Optional tennis_points supplies independently sourced current-game points and serving side; absence means unavailable. Compatible unexpired tennis_points survives temporary supplemental snapshot unavailability or contention; expiry and set/game mismatch still clear it.",
          "allOf": [
            {
              "type": "object"
            },
            {
              "type": "object",
              "properties": {
                "tennis_points": {
                  "$ref": "#/$defs/TennisPoints"
                }
              }
            }
          ]
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "freshness": {
      "type": "object",
      "required": [
        "market_data",
        "top_of_book",
        "live_sports"
      ],
      "properties": {
        "market_data": {
          "$ref": "#/$defs/MarketSnapshotFreshness"
        },
        "top_of_book": {
          "$ref": "#/$defs/MarketSnapshotFreshness"
        },
        "live_sports": {
          "$ref": "#/$defs/MarketSnapshotFreshness",
          "description": "Freshness requires the dedicated two-second post-publication marker to match the retained vintage and non-invalidated data timestamp; timestamp presence alone is insufficient. as_of records compute start, so stale_after_s is omitted rather than implying as_of plus two seconds. Missing membership is not_live only in a fresh source; stale membership remains stale and unreadable source data is unavailable. Repeated lookups reuse the shared payload and typed index for an unchanged generation."
        }
      }
    },
    "trust": {
      "$ref": "#/$defs/MarketSnapshotTrust",
      "description": "Price and spread trust metadata. Present only when expand=trust or expand[]=trust is requested."
    }
  },
  "$defs": {
    "MarketSnapshotFreshness": {
      "type": "object",
      "required": [
        "status",
        "source"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "fresh",
            "stale",
            "available",
            "not_live",
            "unavailable"
          ]
        },
        "source": {
          "type": "string"
        },
        "as_of": {
          "type": "string",
          "format": "date-time"
        },
        "stale_after_s": {
          "type": "integer",
          "description": "Age-relative freshness bound when known. Omitted for live_sports: its as_of records compute start, while its two-second freshness marker starts at publication."
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "MarketSnapshotTopOfBook": {
      "type": "object",
      "required": [
        "status",
        "source"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "available",
            "unavailable"
          ]
        },
        "source": {
          "type": "string"
        },
        "best_bid": {
          "type": "number"
        },
        "best_ask": {
          "type": "number"
        },
        "spread_bps": {
          "type": "integer"
        },
        "bid_depth_usdc": {
          "type": "number"
        },
        "ask_depth_usdc": {
          "type": "number"
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "MarketSnapshotTrust": {
      "type": "object",
      "description": "Price and spread trust metadata returned only when GET /api/v1/market/{condition_id}/snapshot includes expand=trust.",
      "required": [
        "current_price",
        "spread_bps"
      ],
      "properties": {
        "current_price": {
          "$ref": "#/$defs/TrustMetadata"
        },
        "spread_bps": {
          "$ref": "#/$defs/TrustMetadata"
        }
      }
    },
    "TennisPoints": {
      "type": "object",
      "description": "Optional current-game tennis facts from API-Tennis, aligned with live_score.scores display order. These facts have their own revision and expiry; Polymarket remains the source of sets, match status, period, and the outer live-score revision. New observations require corroborated identity, current set/games, and live state. Where Polymarket publishes no score (tennis doubles, whose live_score reads one 0-0 set throughout), the group binds on both pairs' names, the tour, the date and API-Tennis's live flag, and carries set_games, the provider's set score for the match. Cached responses and replayed frames may still carry expired facts, so clients must enforce expires_at.",
      "required": [
        "source",
        "match_key",
        "player_keys",
        "points",
        "source_revision",
        "observed_at",
        "expires_at",
        "set_number",
        "games"
      ],
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "api_tennis"
          ]
        },
        "match_key": {
          "type": "integer",
          "description": "API-Tennis match ID. This is not a Polymarket market or event ID."
        },
        "player_keys": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": "integer"
          },
          "description": "API-Tennis player IDs in the same first/second order as live_score.scores. These are not Polymarket team IDs."
        },
        "points": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": "string"
          },
          "description": "Current-game point values in first/second order. Read strings, including A for advantage and numeric tiebreak points. Missing points are not zero."
        },
        "serving_side": {
          "type": "string",
          "enum": [
            "first",
            "second"
          ],
          "description": "The serving player in live_score.scores display order. Omitted when API-Tennis does not identify the server."
        },
        "source_revision": {
          "type": "integer",
          "minimum": 1,
          "description": "Orders only the tennis_points group for the same match. Never compare this with live_score.source_revision."
        },
        "observed_at": {
          "type": "string",
          "format": "date-time",
          "description": "When 0xinsider observed these API-Tennis facts. This is not a timestamp from the court."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Stop displaying the point group at this instant, even if the enclosing score remains fresh. The group expires 30 seconds after observed_at."
        },
        "set_number": {
          "type": "integer",
          "minimum": 1,
          "description": "Current set number. Display points only while this matches the enclosing scoreboard, unless set_games is present."
        },
        "games": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": "integer",
            "minimum": 0
          },
          "description": "Current-set games in first/second order. Display points only while these match the enclosing scoreboard, unless set_games is present."
        },
        "set_games": {
          "type": "array",
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "items": {
              "type": "integer",
              "minimum": 0
            }
          },
          "description": "API-Tennis games in every listed set, first set first, each in first/second order. Present only when Polymarket publishes no score for the match (tennis doubles): display these as the set score, and discard the group once live_score carries a nonzero game. A deciding match tie-break is listed as games, for example 9-5. Omitted for every other match."
        }
      }
    },
    "TrustCompleteness": {
      "type": "object",
      "description": "Whether the described value or result set is complete for its stated contract.",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "complete",
            "partial",
            "not_computed",
            "not_applicable",
            "unavailable"
          ]
        },
        "detail": {
          "type": "string"
        }
      }
    },
    "TrustFreshness": {
      "type": "object",
      "description": "Freshness metadata for a trust-critical value. This is separate from transport cache fields in ResponseMeta.",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "fresh",
            "refreshing",
            "stale",
            "not_live",
            "unknown",
            "unavailable"
          ]
        },
        "as_of": {
          "type": "string",
          "format": "date-time"
        },
        "max_age_s": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "TrustMetadata": {
      "type": "object",
      "description": "Shared source/freshness/reconciliation/completeness metadata for public API values that may be cached, stale, partial, computed, or provider-unavailable. Unavailable provider values must be represented with explicit metadata instead of fabricated zeros or empty arrays.",
      "required": [
        "source",
        "freshness",
        "reconciliation",
        "completeness"
      ],
      "properties": {
        "source": {
          "$ref": "#/$defs/TrustSource"
        },
        "freshness": {
          "$ref": "#/$defs/TrustFreshness"
        },
        "reconciliation": {
          "$ref": "#/$defs/TrustReconciliation"
        },
        "completeness": {
          "$ref": "#/$defs/TrustCompleteness"
        }
      }
    },
    "TrustReconciliation": {
      "type": "object",
      "description": "How provider-owned facts were reconciled with stored/read-model values.",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "provider_backed",
            "db_mirror",
            "computed",
            "partial",
            "not_applicable",
            "unavailable"
          ]
        },
        "detail": {
          "type": "string"
        }
      }
    },
    "TrustSource": {
      "type": "object",
      "description": "Source metadata for a trust-critical value. Providers and DB/read models own business truth; clients should not infer missing provider facts from titles, slugs, zeros, or empty arrays.",
      "required": [
        "kind",
        "owner"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "provider",
            "database",
            "cache",
            "computed",
            "client_input",
            "unavailable"
          ]
        },
        "owner": {
          "type": "string",
          "description": "Provider, table/read-model, cache, or service that owns the value."
        },
        "field": {
          "type": "string",
          "description": "Provider field, DB column, or computed field name when applicable."
        }
      }
    }
  }
}