# Data Dictionary — Turkish Crypto Exchange Tick Data

This document describes all file formats delivered with the dataset. All timestamps are Unix epoch in UTC. All files are UTF-8; CSVs use comma separators with a header row.

## 1. trades_YYYY-MM-DD.csv

One row per executed trade, both exchanges, sorted by exchange timestamp.

| Column | Type | Description |
|---|---|---|
| exchange | string | `btcturk` or `binance` |
| symbol | string | Exchange symbol, e.g. `BTCTRY`, `USDTTRY` |
| trade_id | string | Exchange-assigned unique trade ID (unique per exchange+symbol) |
| ts_exchange_ms | int64 | Trade timestamp reported by the exchange, ms |
| ts_recv_ms | int64 | Our server receive timestamp (NTP-synced), ms |
| price | decimal | Trade price in quote currency (TRY or USDT) |
| amount | decimal | Trade size in base currency |
| side | string | Aggressor side: `buy` = taker bought, `sell` = taker sold |

## 2. quotes_YYYY-MM-DD.csv

Best bid/ask updates derived from order book messages.

| Column | Type | Description |
|---|---|---|
| exchange | string | `btcturk` or `binance` |
| symbol | string | Exchange symbol |
| ts_recv_ms | int64 | Receive timestamp, ms (exchanges do not timestamp book snapshots) |
| bid | decimal | Best bid price |
| bid_qty | decimal | Size at best bid |
| ask | decimal | Best ask price |
| ask_qty | decimal | Size at best ask |

Update frequency: BTCTurk pushes full-book snapshots on change; Binance depth updates every 100 ms per symbol.

## 3. spread_YYYY-MM-DD.csv

Second-by-second cross-exchange mid-price comparison for symbols listed on both venues (BTCTRY, ETHTRY, USDTTRY, SOLTRY, XRPTRY).

| Column | Type | Description |
|---|---|---|
| symbol | string | Symbol |
| ts_s | int64 | Unix timestamp, seconds |
| btcturk_mid | decimal | BTCTurk mid price ((bid+ask)/2), last known within 10 s |
| binance_mid | decimal | Binance mid price, last known within 10 s |
| spread_bps | decimal | (btcturk_mid − binance_mid) / binance_mid × 10 000 |

Rows are only emitted when both venues have a quote within the last 10 seconds (no stale comparisons).

## 4. Raw archive (on request): <exchange>_HH.ndjson.gz

Hourly gzip NDJSON, one JSON object per line:

```json
{"ts": 1783098260162, "ex": "btcturk", "raw": "<original WebSocket message, unmodified>"}
```

- `ts` — our receive timestamp, ms
- `raw` — the exact message as sent by the exchange

BTCTurk message types: `422` single trade, `421` trade list (sent on subscribe), `431` full order book, `100`/`991` protocol messages. Binance messages follow the standard combined-stream format (`stream` + `data`).

## Data quality notes

- Collection runs 24/7 from EU servers; reconnects are automatic. Gaps, if any, are visible in the raw archive as missing receive-timestamp ranges.
- BTCTurk trade snapshots (`421`) received on reconnect are deduplicated by trade ID in the normalized CSVs; the raw archive keeps everything.
- `ts_recv_ms` is NTP-synced and comparable across exchanges — this is what makes the cross-exchange spread series valid.

## Coverage

- Symbols: BTCTRY, ETHTRY, USDTTRY, SOLTRY, XRPTRY, AVAXTRY, DOGETRY (BTCTurk); same TRY pairs + BTCUSDT, ETHUSDT (Binance)
- Start date: 2026-07-04
- Update cadence: daily (previous day delivered by 03:00 UTC)
