# Schema — Polymarket College Football Order-Book Slice All files are Parquet (zstd). Rows are sorted by token_id, then timestamp (depth also by side, level). Every day-file in this archive has exactly these columns and types; a column that did not exist yet in an early capture era is NULL there (see COVERAGE.md). ## /quotes/poly_quotes_YYYY-MM-DD.parquet — top of book, one row per token per recorder cycle | column | type | meaning | |---|---|---| | timestamp | timestamp[us, UTC] | The recorder's SAMPLE time for the cycle (~30 s cadence); every row of a cycle shares it. NOT the exchange time of the quote. Each row was recorded within 300 s of the last WebSocket message the recorder received for that token (a message can re-send an unchanged book); an unchanged quote can persist for hours, so treat long runs of identical rows as an unchanged book, not a fresh price. There is no quote-age column. The 300 s rule has been the recorder's since at least 2026-06-15, when its code entered version control. Quotes from 2026-10-05 on come from the capture host's v2 recorder, which keeps the same 300 s rule and the same 14 columns (names, order, types, rounding). The host recorder also logs 5 extra columns (ask_size_valid, bid_size_valid, exchange_event_ts, last_update_age_s, ws_last_message_age_s); they are NOT included in this archive, so the schema is identical on every day. | | token_id | string | Polymarket CLOB outcome-token id (decimal string). | | sport | string | ZenHodl's sport label from its market cache (e.g. CFB, EPL), not a Polymarket field. Equals the folder name. | | event | string | Event title from the market cache at record time. | | outcome | string | Outcome this token pays on (team, player, Yes/No, Over/Under ...), from the market cache. | | market_type | string | ZenHodl's keyword label, assigned from the market question when the token entered the cache: basketball player-stat over/unders -> PROP; 'spread' -> SPREAD; 'o/u', 'over' or 'total' -> TOTAL; 'both teams' -> PROP; anything else -> GAME. It is NOT a full-game label: SPREAD includes 1H/2H/quarter and first-five-innings spreads; TOTAL includes half, quarter and first-five totals, team totals and player-stat over/unders outside basketball (e.g. MLB home runs, NFL receiving yards); GAME includes period moneylines and yes/no props. To select full-game markets use market_type_gamma in /tokens.csv (Polymarket's own sportsMarketType): full-game values are 'moneyline', 'spreads' and 'totals', plus the match-level tennis, table-tennis and esports lines COVERAGE.md lists under Market labels. NULL on days before the column existed. | | segment | string | Period/segment parsed by the recorder from the market question when it is written out ('Map 2', 'Set 1', '2nd Half' -> 'Half 2'); '' when none was parsed. Heuristic. It does NOT parse the shorthand most football, basketball and baseball period markets use ('1H', '2H', '1Q'-'4Q', '1st 5 Innings'), so '' does not mean full game. NULL before the column existed. | | line | float64 | Spread/total line parsed from the market question; NULL when none was parsed or before the column existed. Heuristic. | | bid, ask | float64 | Best bid and best ask (USDC per share, 0-1) held by the recorder's WebSocket client at the sample time. | | mid | float64 | (bid + ask) / 2, as computed by the client from those two values. | | spread | float64 | ask - bid. | | bid_size, ask_size | float64 | The size the client last held for the best bid / ask. Polymarket's price-change messages carry no size, so after such a move this can belong to an earlier price. The client's validity flag is not included. Not validity-checked. The host recorder sets the client's size-refresh period to the 30 s sample interval (the client default is 10 s); COVERAGE.md measures the share of zero sizes per recorder era. | ## /depth/poly_depth_YYYY-MM-DD.parquet — order-book levels Depth files exist only for days up to 2026-10-03 (depth_coverage_end); the quote files continue to 2026-10-19. There is no depth after 2026-10-03 in this vintage. | column | type | meaning | |---|---|---| | timestamp | timestamp[us, UTC] | The depth recorder's sample time (~30 s cycle). A row repeats the LAST FULL BOOK message received for the token (books are not patched by incremental price changes); a book is re-emitted every cycle for up to 300 s after it arrived, so identical consecutive snapshots are re-emissions, not new observations. There is no book-receipt-time column. | | token_id, sport, event, outcome, market_type, segment, line | | As in quotes. segment/line are NULL on days before those columns existed. | | side | string | 'bid' or 'ask'. | | level | int64 | 0 = best price on that side, counting away from the touch; at most 20 levels per side are kept. | | price | float64 | Price of the level (USDC per share, 0-1). The depth recorder drops levels with price or size <= 0 (its rule since at least 2026-07-09, when the code entered version control); COVERAGE.md counts any such rows that remain. | | size | float64 | Shares resting at that level in the book message. | ## /tokens.csv — per-token coverage (derived at build time) token_id, event, outcome, market_type, segment, line (first non-null value seen); first_seen_utc, last_seen_utc; observations (quote rows); cycles_between_first_last (recorder cycles, all sports, between those two moments, inclusive); presence_share (observations / cycles_between_first_last — well below 1.0 means the token went quiet or out of the recorder's set); max_gap_s (largest gap between consecutive observations of the token, including across days). Three trailing columns carry Polymarket's own labels, fetched from the gamma API (/markets) by token_id after capture: market_type_gamma (sportsMarketType, e.g. moneyline, spreads, totals, first_half_spreads, q1_totals, team_totals, points, home_runs; '' when gamma returned no market for the token or the market has no type), market_question_gamma (gamma's question text) and line_gamma (gamma's line, NULL when none). Join tokens.csv to the quote and depth files on token_id. The free sample CSV carries market_type_gamma as an extra last column. ## FILES.csv — every Parquet member path, bytes, rows, sha256 for each Parquet file; manifest.json carries the sha256 of FILES.csv and of every other member. ## days.csv — per day and sport date, sport, quote_file (ok / missing / unreadable), recorder_cycles, quote_rows, quote_tokens, depth_file, depth_cycles, depth_rows, depth_tokens. Every day of the window appears for every sport, including days with zero rows, so absence is explicit.