# Polymarket & Kalshi Orderbook Archive — Physical Schema

**Artifact version 2026.01-v2 · contract corrected July 2026**

This fixed archive contains two independently captured prediction-market
tables. They have different schemas and coverage windows and are **not
pre-keyed or pre-joined**. Exact bytes, row counts, time bounds, and SHA-256
hashes are in `MANIFEST.json`.

## `poly_snapshots.parquet`

25,651,600 Polymarket CLOB book observations, from
2026-01-18T01:31:44Z through 2026-01-29T13:41:11Z.

| column | physical type | meaning |
|---|---|---|
| `timestamp` | float64 | capture time as Unix seconds UTC |
| `token_id`, `condition_id` | string | Polymarket outcome-token and parent-condition identifiers |
| `event_slug`, `event_title`, `question` | string | venue market labels |
| `sport`, `market_type` | string | collector-normalized classifications |
| `line` | float64 | spread/total line where applicable; null otherwise |
| `yes_bid`, `yes_ask`, `mid`, `spread` | float64 | YES-token prices in dollars in the 0–1 convention |
| `bid_size_top`, `ask_size_top` | int64 | aggregate size at the captured best level |
| `bid_depth_5c`, `ask_depth_5c` | int64 | captured depth within five cents of the top |
| `total_bid_depth`, `total_ask_depth` | int64 | captured aggregate book depth |
| `bid_levels`, `ask_levels` | int64 | captured distinct price-level counts |
| `is_burst` | bool | collector burst-mode flag |
| `datetime_utc` | timestamp[ns, UTC] | timestamp materialized as UTC datetime |

This table has no score, clock, period, ESPN game ID, execution, or settlement
outcome fields. Historical size fields are physically `int64`; fractional
sizes, if any existed upstream, cannot be recovered from this artifact.

## `kalshi_snapshots.parquet`

110,457,883 Kalshi top-of-book observations, from
2025-12-28T18:07:53Z through 2026-01-30T14:12:52Z.

| column | physical type | meaning |
|---|---|---|
| `timestamp` | float64 | capture time as Unix seconds UTC |
| `ticker`, `title` | string | Kalshi market identity and label |
| `game_id`, `home_team`, `away_team` | string | collector-linked game identity and teams; may be blank |
| `home_score`, `away_score`, `score_diff`, `period` | int64 | capture-time game state |
| `time_remaining`, `game_state` | string | capture-time display state |
| `yes_bid`, `yes_ask`, `mid`, `spread`, `spread_cents` | float64 | top-of-book prices in cents |
| `yes_bid_size`, `yes_ask_size`, `min_size` | int64 | captured size fields |
| `open_interest`, `volume_24h` | int64 | venue-reported activity fields |
| `liquidity_score` | float64 | collector heuristic, not a venue field |
| `tradable_now`, `is_burst_mode` | bool | capture-state and collector-mode flags |
| `datetime_utc` | timestamp[ns, UTC] | timestamp materialized as UTC datetime |

Game state belongs only to the Kalshi table and reflects capture time. It may
lag the sporting event and should not be described as event-time truth.

## Cross-venue analysis

There is no shared exchange identifier between the files. Cross-venue work
requires a buyer-supplied or independently verified mapping using market title,
teams, date, line, and outcome semantics. Match candidates as a set and fail
closed when an event, doubleheader, line, or outcome remains ambiguous. Normalize
Kalshi cents to dollars before comparing prices.

Midpoints and displayed sizes are observations, not fills. A useful execution
study must separately model quote age, tradability, fees, latency, queue
position, slippage, and adverse selection. No claim of executable arbitrage or
historical profitability is made.

## Coverage and quality limitations

- This is a fixed historical capture, not a continuous or gap-free venue feed.
- The two tables span different windows; neither implies coverage in the other.
- No executions, transaction hashes, or settlement outcomes are included.
- Polymarket rows do not contain sports game state.
- Empty/zero displayed size is common in the physical files, and many Kalshi
  rows are marked non-tradable. Filter these fields explicitly for liquidity or
  execution work; do not infer fillability from row count.
- Collector selection and burst modes create sampling bias and non-uniform
  cadence. Measure observed timestamp gaps for the subset under study.
- Venue and sports facts remain subject to their source providers' terms.

## Minimal validation

```python
import hashlib, json
from pathlib import Path
import pyarrow.parquet as pq

root = Path("poly_orderbook_archive")
manifest = json.loads((root / "MANIFEST.json").read_text())
for record in manifest["files"]:
    path = root.parent / record["path"]
    assert path.stat().st_size == record["bytes"]
    assert pq.ParquetFile(path).metadata.num_rows == record["rows"]
    assert hashlib.sha256(path.read_bytes()).hexdigest() == record["sha256"]
```

License terms: <https://zenhodl.net/data-license>