# Combo & Parlay Archive: Polymarket + Kalshi: schema

### polymarket/fills/fills_YYYY-MM-DD.parquet
One row per decoded `OrderFilled` log of a COMBO token on Polymarket's combo exchange contract (V3 proxy).
Day = UTC date of `block_time`.

| column | type | meaning |
|---|---|---|
| block | int64 | Polygon block number |
| block_time | timestamp[us, UTC] | the block's header time where `block_time_source` = `exact`; otherwise a linear-interpolation estimate (accuracy in COVERAGE.md) |
| block_time_source | string | `exact` (block header), `interpolated` between true block times sampled every 1,000 blocks, or `extrapolated` past the last sample |
| tx_hash, log_index | string, int32 | the on-chain transaction and log position (unique pair) |
| order_hash | string | the filled order |
| maker_id, taker_id | string | keyed-hash wallet id (`w_` + 16 hex; the same wallet has the same id everywhere in this release) or a protocol role (`contract:exchange_proxy`). Not anonymity: see Privacy in COVERAGE.md |
| is_taker_order_row | bool | the row of the order that CROSSED (its order_hash equals OrdersMatched.taker_order_hash). A protocol fact, not a claim about who the trader is |
| taker_order_label_source | string | `orders_matched` (v2 schema) or `is_intermediated_v1` (first ~24 h: the recorder's equivalent rule; COVERAGE.md reports its agreement with the decoded OrdersMatched logs) |
| maker_side | string | BUY or SELL, for this row's maker |
| condition_id | string | the combo's condition id in the combinatorial exchange (62 hex; join to combos/legs) |
| outcome | string | YES or NO token of the combo |
| price | float64 | USDC per share of THIS row's token (0-1) |
| shares | float64 | shares (decimal; 6-dp on chain) |
| usdc | float64 | USDC notional of this row (decimal) |
| fee_usdc | float64 | protocol fee in USDC; non-zero only on the taker-order row |
| builder | string | builder code (bytes32 hex) when set |
| schema_era | string | `v1` (to 2026-08-07 02:55Z) or `v2` |
| captured_at | timestamp[us, UTC] | when our recorder read the log: provenance only, never event time |
| captured_clock_fault | bool | captured_at earlier than block_time (the 2026-09-29/30 recorder clock rollback) |

### polymarket/matches/matches_YYYY-MM-DD.parquet
One row per `OrdersMatched` log (the v1 era's logs were archived undecoded and are decoded here with the recorder's own
layout).

| column | type | meaning |
|---|---|---|
| block, block_time, block_time_source | | as in fills |
| tx_hash, log_index | string, int32 | the on-chain transaction and log position |
| taker_order_hash | string | the order that crossed; equals `order_hash` of its taker-order fill row |
| taker_id | string | keyed-hash id of the wallet that signed that order |
| condition_id, outcome | string | the combo and its YES/NO token |
| taker_side | string | BUY or SELL |
| maker_amount, taker_amount | float64 | what the taker order gave / received, decimal units. BUY: maker_amount = USDC paid, taker_amount = shares received. SELL: maker_amount = shares given, taker_amount = USDC received |

### polymarket/combos.parquet
One row per combo with at least one fill in THIS archive; the aggregates count only this archive's fills.

| column | meaning |
|---|---|
| condition_id | the combo's condition id in Polymarket's combinatorial exchange (`Ids.sol` bytes31 as 62 hex), self-checked against its decoded legs. It is not a Gamma/CTF conditionId |
| n_fills, n_taker_order_rows | fill rows / taker-order rows (the order that crossed) |
| usdc_volume | sum of `usdc` over taker-order rows (counted once per match) |
| first_fill_time, last_fill_time | block times of this archive's first and last fill |
| decode_status | `decoded` (legs read on-chain and re-derived to the same id) or `undecoded` |
| n_legs, legs_all_named | leg count; every leg has a market title |
| outcome | result of the combo's YES token: `won` = every leg hit (YES paid 1), `lost` = YES paid 0 (NO holders were paid), `partial` = a void-class leg paid a fraction, `unresolved` = not resolved when read |
| yes_payout | payout per YES share in USDC (0-1) |
| outcome_read_at | when the payout was read on-chain (terminal results cannot change, so early reads stand) |

### polymarket/legs.parquet
One row per (combo, leg).

| column | meaning |
|---|---|
| condition_id, leg_index, n_legs | the combo and the leg's position in it |
| leg_position_id | the leg's position id in the combinatorial exchange |
| leg_condition_id | the leg position id without its outcome byte (exchange-internal; NOT Polymarket's Gamma/CTF conditionId) |
| leg_market_condition_id | the leg market's Polymarket conditionId (0x..., joins to Gamma/CTF), from our daily market catalogs; null when the leg was not matched |
| leg_side | YES / NO |
| title, slug, needs, tags | market title and slug, the outcome this leg needs, catalog tags |
| name_source | `stored` (named when decoded), `catalog_YYYY-MM-DD` (re-matched offline against that day's market catalog) or `unnamed` |
| decoded_at | when the legs were decoded |

### kalshi/trades/trades_YYYY-MM-DD.parquet
One row per CAPTURED combo trade print (a small SAMPLE: see COVERAGE.md). Day = UTC date of Kalshi's `created_time`.

| column | type | meaning |
|---|---|---|
| trade_id | string | Kalshi trade id (unique) |
| ticker | string | combo market ticker (join to combos/legs) |
| series | string | e.g. KXMVECROSSCATEGORY |
| created_time | timestamp[us, UTC] | exchange time of the trade |
| count | float64 | contracts (fractional) |
| yes_price, no_price | float64 | dollars 0-1 (yes + no = 1) |
| taker_side | string | yes / no |
| captured_at | timestamp[us, UTC] | provenance only |
| captured_clock_fault | bool | captured_at earlier than created_time (2026-09-29/30 rollback) |

Kalshi's `taker_book_side` / `taker_outcome_side` duplicated `taker_side` on every row and `is_block_trade` was
always false; they are not shipped.

### kalshi/combos.parquet
One row per combo with at least one captured print in THIS archive; captured_* count only this archive's prints.

| column | meaning |
|---|---|
| ticker, event_ticker, collection_ticker, series, title | identity |
| n_legs, n_no_legs, same_event_legs | leg structure |
| created_time, open_time, close_time, expiration_time | Kalshi times |
| first_seen_at | when our recorder registered the combo: normally at its first captured print, later if that fetch failed (provenance) |
| first_seen_clock_fault | first_seen_at earlier than the combo's created_time or its first captured print (the 2026-09-29/30 recorder clock rollback) |
| snap_* | ONE top-of-book snapshot fetched at registration (status, yes bid/ask and sizes, last price, volume, open interest; timing in COVERAGE.md); `snap_yes_ask` 1.0 with size 0 = no offer |
| price_level_structure | Kalshi tick regime |
| captured_prints, captured_contracts | what this archive's sample holds for the combo |
| final_status, result, settlement_value, settlement_ts, final_volume, outcome_fetched_at | the market's state when we read it (`final_volume` = Kalshi's total volume). `result` `scalar` = settled at a fractional value (see settlement_value). An open market shows final_status `active` and no result; a market we could not read has no final status |

### kalshi/legs.parquet
One row per (combo, leg): ticker, leg_index, n_legs, leg_event_ticker, leg_market_ticker, leg_side (yes/no),
leg_label (from Kalshi's selection text; empty rather than guessed if it did not align), leg_final_status, leg_result,
leg_settlement_value (the leg market's state when we read it).

### kalshi/collections/collections_YYYY-MM-DD.parquet
Daily snapshot of Kalshi's multivariate collections (first 500 only: see COVERAGE.md). Columns: snapshot_day,
snapshot_captured_at, collection_ticker, series_ticker, title, open_date, close_date, size_min / size_max (the allowed
number of legs), is_ordered / is_all_yes / is_single_market_per_event (Kalshi's combination rules, as returned),
n_associated_events (events in the collection).