# Free data samples

A sample is a full day from Layer's own recorders: every order-book change and trade as each venue sent it, with the moment our server got it. Use it to test a bot on real books before it trades. It's free with any Layer key.

| Sample | What's in it |
|---|---|
| `sports-2026-11-15` | The sports day of Sunday Nov 15, 2026, 12:00 UTC to 08:00 UTC the next day, on Kalshi, Polymarket US, Polymarket and Novig. NFL, NBA, NHL, college basketball, soccer, tennis and more, with live scores and Layer's market pairs. |

## What's in the sports day

All four venues were recorded side by side by the same servers, so their receive times share one clock.

| Sport | Kalshi | Polymarket US | Polymarket | Novig |
|---|---|---|---|---|
| NFL (12 games) | Every line, most player props | Every market, player props too | Main lines, plus props that traded | Every market |
| NBA (9 games) | Moneylines, about half the spreads and totals | Every market, player props too | Most main lines | Every market |
| NHL (5 games) | Moneylines, most spreads and totals | Every market, player props too | Most main lines | Every market |
| College basketball (34 games) | Some games | Every market | Most main lines | Every market |
| Soccer (32 matches) | Main lines | Every market | Main lines, plus props that traded | Not listed |
| Tennis (64 matches) | Some matches | Every market | Matches that traded | Not listed |
| Esports, table tennis, darts | Some | Every market | Markets that traded | Not listed |

One known gap: Kalshi from 01:20 to about 04:00 UTC on Nov 16 (8:20 to 11 pm ET, during Sunday Night Football), when our Kalshi recorder fell behind and dropped messages. The other three venues have that stretch. Every gap, including short reconnects, is listed in the API answer.

Kalshi's files hold every market Layer was recording that day, a few non-sports ones too, so each subscription's message numbers (`seq`) stay continuous and a reader can tell a real gap from a filtered one.

## GET /v0/samples

The samples there are.

```bash
curl -H "Authorization: Bearer $LAYER_API_KEY" https://uselayer.sh/v0/samples
```

## GET /v0/samples/{id}

One sample's files, each with a download link that works for an hour, and every gap. Call it again for fresh links.

```bash
curl -H "Authorization: Bearer $LAYER_API_KEY" "https://uselayer.sh/v0/samples/sports-2026-11-15?venue=kalshi"
```

| Parameter | What it does |
|---|---|
| `venue` | One venue's files: `kalshi`, `polymarket_us`, `polymarket`, `novig` or `scores`. Leave it out for all |

```json
{
  "sample": "sports-2026-11-15",
  "from": "2026-11-15T12:00:00.000Z",
  "to": "2026-11-16T08:00:00.000Z",
  "links_expire_at": "…",
  "files": [
    { "venue": "kalshi", "hour": "2026-11-15T18:00:00Z", "url": "https://…", "bytes": 0, "lines": 0 }
  ],
  "markets": { "kalshi": 0, "polymarket_us": 0, "polymarket": 0, "novig": 0 },
  "pairs": { "url": "https://…", "bytes": 0, "lines": 0 },
  "gaps": [
    { "venue": "kalshi", "kind": "overflow", "at": "2026-11-16T01:20:…Z", "lines": 0 }
  ]
}
```

| Field | What it is |
|---|---|
| `files` | One file per venue per UTC hour: `venue`, `hour` (its start), `url`, `bytes`, `lines`. `scores` is Polymarket's live sports feed |
| `markets` | How many markets each venue's files touch |
| `pairs` | Layer's matches between Kalshi and the other venues for these games: one JSON line each with `kalshi`, `venue`, `market` and `status` |
| `gaps` | Every stretch we know is missing or suspect. `kind` is `reconnect` (a connection dropped; `ms` long), `overflow` (the recorder fell behind and dropped `lines` messages), `seqgap` (Kalshi's message numbers jumped), `restart` (the recorder restarted), `no_recorder` (no recorder was running) or `cut_short_file` |

## The files

Gzipped JSON Lines. Each line is our receive time and the venue's WebSocket message exactly as sent:

```json
{"received_at":"2026-11-15T20:00:01.255Z","message":{ … the venue's message … }}
```

The messages are each venue's own: Kalshi's `orderbook_snapshot`, `orderbook_delta`, `trade` and `market_lifecycle_v2`; Polymarket US's `marketData` and `trade`; Polymarket's `book`, `price_change`, `last_trade_price` and `tick_size_change`; Novig's book deltas.

### In Python

```python
import gzip, json

with gzip.open("kalshi-2026-11-15T18.jsonl.gz", "rt") as f:
    for line in f:
        event = json.loads(line)
        received_at, message = event["received_at"], event["message"]
```

The [Python SDK](https://uselayer.sh/docs/sdk.md) reads the Kalshi, Polymarket US and Polymarket files as they are, once unzipped (see [Backtest data](https://uselayer.sh/docs/backtest-data.md)):

```python
from uselayer import Client, import_events

data = import_events(["kalshi-2026-11-15T18.jsonl", "kalshi-2026-11-15T19.jsonl"], format="kalshi")
print(data.report.summary())
Client(mode="backtest", books=data).replay(on_book)
```

Load consecutive hours together, so each market's book carries from one hour to the next. Novig's files have no SDK reader yet.
