Inside a Series-Day Bundle: the Tick File Format

A series-day bundle is the unit our archive sells prediction-market data in: all contract files of one series — say, every Kalshi BTC 15m market — for one UTC day. This guide walks through exactly what is inside those files, byte by byte, so you can decide whether to write your own parser (it is easy) or use the free tooling (it is easier). Everything shown below comes verbatim from the free Kalshi sample day you can download right now. The Deribit option-chain day bundles in the shop use the identical file format — one file per call or put, plus mark-price lines (type 7) that carry delta, gamma, vega, theta and implied vols.

Everything below runs on the CryptoStruct archive: every message Kalshi, Polymarket and 35+ crypto venues publish — every Level-2 snapshot and update at full depth, every trade, every contract, every day since we added the venue — captured co-located with nanosecond venue and receive timestamps and a gap-audited event-id chain, in one normalized schema. It is the same capture our own trading engine and enterprise feeds run on, sold as €1 day bundles you buy as a guest in the Data Shop with instant download — no subscription, no minimum, no sales call. Free full-day samples let you run every command in this guide before paying.

File anatomy: one contract, one day, JSON lines

Each file is named {instrument_id}_{date}.txt.zst and is zstd-compressed text. The first line is a JSON object with the instrument's masterdata; every following line is one event encoded as a JSON array. The first line of the Kalshi sample looks like this (truncated):

{"instrument":{"id":466528,"code":"KXBTCMINY-27JAN01-55000.00",
  "native_code":{"default":"KXBTCMINY-27JAN01-55000.00"},
  "type":"perpetual","state":"open",
  "exchange_id":46,"exchange_code":"kalshi",
  "ticksize":0.01,"lot_size":0.01,"min_order":0.01, …}}

Every event line shares one envelope, regardless of venue: [msgType, instrumentId, prevEventId, eventId, adapterTs, exchangeTs, data, …]. adapterTs is when our co-located recorder received the message; exchangeTs is the venue's own timestamp — both integer nanoseconds since epoch, UTC. The prevEventId/eventId chain lets you verify you have every message. A real trade from the sample:

[2,466528,"8454531473485012705","5466866425187754076",
 1785283123014075654,          ← adapterTs (ns, capture)
 1785283123000000000,          ← exchangeTs (ns, venue)
 [[1,"0.6","2.88","e463494f-…",1785283123000000000]]]
   ↑side  ↑price ↑qty  ↑trade id      ↑per-fill ts

Message types

In the CryptoStruct prediction-market archive, Kalshi and Polymarket files do not carry a separate type-6 BBO stream — the top-of-book at any moment is reconstructed by replaying types 0/1, and the free reader does this for you with a Book class. Prices on event contracts live in 0..1: in the sample files shown here, the recorded tick size is 0.01 for the Kalshi contract (USD) and 0.001 for the Polymarket contract (USDC) — tick sizes are market-specific and may change over time. Turnover in our analytics is USD-normalized.

Parsing: three lines to first trades

The free AI toolkit ships cryptostruct_reader.py — a streaming parser with a CLI. The reader itself uses only the Python standard library; decompression requires either the zstd CLI or the optional zstandard package, whichever is available:

# summary of a day file (counts per message type, time span)
python3 cryptostruct_reader.py info 466528_2026-07-29.txt.zst

# all trades as CSV / Parquet
python3 cryptostruct_reader.py trades 466528_2026-07-29.txt.zst --out trades.csv

# order book sampled every second, top 5 levels
python3 cryptostruct_reader.py book 466528_2026-07-29.txt.zst --every 1s --depth 5

Writing your own parser instead is deliberately easy — iterate lines, json.loads, switch on msgType — but three properties of the format bite people who skim:

No parser at all: CSV and Parquet exports

Every sample and purchased day also serves flat exports via ?format= on its download link: trades.csv.gz, bbo.csv.gz, liquidations.csv.gz and Parquet variants — columns per our docs convention with microsecond UTC timestamps (the native files stay nanoseconds). Note the BBO export does not exist for files that carry no type-6 BBO stream (in this archive: Kalshi, Polymarket, BitMEX, Coinbase, Kraken spot) — there the L2 replay above is the way to top-of-book.

What you can buy today

Limitations

This walkthrough covers the fields relevant for prediction-market work; the complete field-by-field specification (options greeks, funding, schema-version tails) lives in the shipped format reference and the official protocol docs. Sample lines are from July 2026 files; the schema is versioned and additive, so older files can lack newer trailing fields — parse positionally and tolerate unknown tails. Not investment advice; this is a file-format guide.