> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graylayer.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoints

> Query historical tickers, snapshots, and deltas

**Base URL:** `http://data.graylayer.tech`

All data endpoints require an `x-api-key` header. Timestamps are UTC RFC 3339 (e.g. `2026-03-26T12:00:00Z`). Results are always sorted `ts` ascending; `limit` truncates after sort.

***

## `GET /health`

```bash theme={null}
curl http://data.graylayer.tech/health
```

```json theme={null}
{"status": "ok"}
```

***

## `GET /api/:exchange/tickers`

List all tickers collected for an exchange. Use `prefix` to narrow results — useful when you know the series you want (e.g. `KXBTC15M`) but not every individual contract.

| Param      | In    | Type   | Description                               |
| ---------- | ----- | ------ | ----------------------------------------- |
| `exchange` | path  | string | `kalshi`, `gemini`, or `polymarket_us`    |
| `prefix`   | query | string | Case-insensitive prefix filter (optional) |

<CodeGroup>
  ```bash All Kalshi tickers theme={null}
  curl -H "x-api-key: your_key" \
    http://data.graylayer.tech/api/kalshi/tickers
  ```

  ```bash BTC 15-minute contracts only theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/tickers?prefix=KXBTC15M"
  ```

  ```bash Gemini tickers theme={null}
  curl -H "x-api-key: your_key" \
    http://data.graylayer.tech/api/gemini/tickers
  ```

  ```bash Polymarket US tickers theme={null}
  curl -H "x-api-key: your_key" \
    http://data.graylayer.tech/api/polymarket_us/tickers
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "exchange": "kalshi",
  "count": 3,
  "tickers": [
    "KXBTC15M-26MAR281500-50",
    "KXBTC15M-26MAR281515-52",
    "KXBTC15M-26MAR281530-54"
  ]
}
```

Tickers are sorted alphabetically. If your key has `ticker_prefixes`, only matching tickers are returned regardless of what `prefix` you pass.

***

## `GET /api/:exchange/snapshots/:ticker`

Get snapshot rows — full orderbook state at discrete points in time. Each row represents the complete book at that moment (not a delta). Multiple rows at the same `ts` represent different price levels.

| Param      | In    | Type     | Description                                      |
| ---------- | ----- | -------- | ------------------------------------------------ |
| `exchange` | path  | string   | Exchange name                                    |
| `ticker`   | path  | string   | Ticker symbol                                    |
| `start_ts` | query | RFC 3339 | Rows at or after this time (optional)            |
| `end_ts`   | query | RFC 3339 | Rows at or before this time (optional)           |
| `limit`    | query | integer  | Max rows returned, applied after sort (optional) |

<CodeGroup>
  ```bash Last 100 snapshots theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/snapshots/KXBTC15M-26MAR281500-50?limit=100"
  ```

  ```bash Specific time window theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/snapshots/KXBTC15M-26MAR281500-50?start_ts=2026-03-26T14:00:00Z&end_ts=2026-03-26T15:00:00Z"
  ```

  ```bash From a start time, capped at 500 rows theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/snapshots/KXBTC15M-26MAR281500-50?start_ts=2026-03-26T00:00:00Z&limit=500"
  ```

  ```bash Gemini prediction market theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/gemini/snapshots/TRUMPWIN?start_ts=2026-03-01T00:00:00Z&end_ts=2026-03-28T00:00:00Z"
  ```

  ```bash Polymarket US market theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/polymarket_us/snapshots/will-bitcoin-reach-150k-in-2026?start_ts=2026-03-01T00:00:00Z&end_ts=2026-03-02T00:00:00Z"
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "exchange": "kalshi",
  "ticker": "KXBTC15M-26MAR281500-50",
  "count": 4,
  "rows": [
    {"ts": "2026-03-26T14:00:01.193Z", "side": "bid", "price": "0.4800", "quantity": "150.00"},
    {"ts": "2026-03-26T14:00:01.193Z", "side": "bid", "price": "0.4700", "quantity": "300.00"},
    {"ts": "2026-03-26T14:00:01.193Z", "side": "ask", "price": "0.5200", "quantity": "80.00"},
    {"ts": "2026-03-26T14:00:01.193Z", "side": "ask", "price": "0.5300", "quantity": "200.00"}
  ]
}
```

`start_ts` is clamped to your key's `max_data_age_days` window. Anonymous access is always clamped to the last 1 day.

***

## `GET /api/:exchange/deltas/:ticker`

Get delta rows — incremental changes to the orderbook. A positive `quantity_delta` means a level was added or increased; negative means it was reduced or removed. Reconstruct the full book by applying deltas to a snapshot.

| Param      | In    | Type     | Description                                      |
| ---------- | ----- | -------- | ------------------------------------------------ |
| `exchange` | path  | string   | Exchange name                                    |
| `ticker`   | path  | string   | Ticker symbol                                    |
| `start_ts` | query | RFC 3339 | Rows at or after this time (optional)            |
| `end_ts`   | query | RFC 3339 | Rows at or before this time (optional)           |
| `limit`    | query | integer  | Max rows returned, applied after sort (optional) |

<CodeGroup>
  ```bash All deltas from a given time theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/deltas/KXBTC15M-26MAR281500-50?start_ts=2026-03-26T14:00:00Z"
  ```

  ```bash Narrow window for book reconstruction theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/deltas/KXBTC15M-26MAR281500-50?start_ts=2026-03-26T14:00:00Z&end_ts=2026-03-26T14:05:00Z"
  ```

  ```bash High volume — fetch first 1000 changes theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/kalshi/deltas/KXBTC15M-26MAR281500-50?start_ts=2026-03-26T00:00:00Z&limit=1000"
  ```

  ```bash Gemini delta stream theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/gemini/deltas/ETHUSD?start_ts=2026-03-26T14:00:00Z&end_ts=2026-03-26T15:00:00Z&limit=1000"
  ```

  ```bash Polymarket US deltas theme={null}
  curl -H "x-api-key: your_key" \
    "http://data.graylayer.tech/api/polymarket_us/deltas/will-bitcoin-reach-150k-in-2026?start_ts=2026-03-26T12:00:00Z&limit=500"
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "exchange": "kalshi",
  "ticker": "KXBTC15M-26MAR281500-50",
  "count": 3,
  "rows": [
    {"ts": "2026-03-26T14:00:03.000Z", "sequence": 10021, "side": "bid", "price": "0.4800", "quantity_delta": "50.00"},
    {"ts": "2026-03-26T14:00:03.000Z", "sequence": 10022, "side": "ask", "price": "0.5200", "quantity_delta": "-80.00"},
    {"ts": "2026-03-26T14:00:04.100Z", "sequence": 10023, "side": "bid", "price": "0.4900", "quantity_delta": "120.00"}
  ]
}
```

`sequence` is the exchange-assigned sequence number for ordering events within the same timestamp. `quantity_delta` is a signed decimal string — negative values mean that quantity was removed from that level.

***

## Examples by exchange

### Kalshi

Kalshi tickers follow patterns like `KXBTC-25` (event series) or `KXBTC15M-26MAR281530-50` (15-minute micro contracts).

```bash theme={null}
# List all Kalshi tickers
curl -H "x-api-key: your_key" \
  http://data.graylayer.tech/api/kalshi/tickers

# Filter to a specific series
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/kalshi/tickers?prefix=KXBTC15M"

# Snapshot for a short-dated BTC contract
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/kalshi/snapshots/KXBTC15M-26MAR281530-50?limit=50"

# Deltas over a 1-hour window
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/kalshi/deltas/KXBTC-25?start_ts=2026-03-26T14:00:00Z&end_ts=2026-03-26T15:00:00Z"

# Full day of deltas
curl -H "x-api-key: ak_prod_abc123def456" \
  "http://data.graylayer.tech/api/kalshi/deltas/KXBTC-25?start_ts=2026-03-26T00:00:00Z&limit=10000"
```

***

### Polymarket US

Polymarket tickers are **market slugs** — lowercase hyphenated strings matching the market URL on polymarket.com.

```bash theme={null}
# List all recorded Polymarket slugs
curl -H "x-api-key: your_key" \
  http://data.graylayer.tech/api/polymarket_us/tickers

# Filter to election markets
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/tickers?prefix=will-donald"

# Latest snapshot for a market
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/snapshots/will-donald-trump-win-the-2024-us-presidential-election?limit=1"

# Historical snapshots over a time range
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/snapshots/bitcoin-above-100000-on-december-31?start_ts=2026-03-01T00:00:00Z&end_ts=2026-03-02T00:00:00Z"

# Orderbook deltas for a crypto market
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/deltas/will-bitcoin-reach-150k-in-2026?start_ts=2026-03-26T12:00:00Z&limit=500"

# Deltas for a political market
curl -H "x-api-key: ak_prod_abc123def456" \
  "http://data.graylayer.tech/api/polymarket_us/deltas/will-the-us-enter-a-recession-in-2026?start_ts=2026-03-01T00:00:00Z"
```

**Snapshot response (Polymarket)**

```json theme={null}
{
  "exchange": "polymarket_us",
  "ticker": "will-bitcoin-reach-150k-in-2026",
  "count": 4,
  "rows": [
    {"ts": "2026-03-26T14:02:11.000Z", "side": "bid", "price": "0.3200", "quantity": "850.00"},
    {"ts": "2026-03-26T14:02:11.000Z", "side": "bid", "price": "0.3100", "quantity": "1200.00"},
    {"ts": "2026-03-26T14:02:11.000Z", "side": "ask", "price": "0.3400", "quantity": "500.00"},
    {"ts": "2026-03-26T14:02:11.000Z", "side": "ask", "price": "0.3500", "quantity": "2000.00"}
  ]
}
```

**Delta response (Polymarket)**

```json theme={null}
{
  "exchange": "polymarket_us",
  "ticker": "will-bitcoin-reach-150k-in-2026",
  "count": 2,
  "rows": [
    {"ts": "2026-03-26T14:02:15.000Z", "sequence": 88421, "side": "bid", "price": "0.3200", "quantity_delta": "-150.00"},
    {"ts": "2026-03-26T14:02:16.000Z", "sequence": 88422, "side": "ask", "price": "0.3400", "quantity_delta": "300.00"}
  ]
}
```

***

### Gemini

Gemini has two classes of tickers:

* **Crypto spot pairs** — e.g. `BTCUSD`, `ETHUSD`, `SOLUSD`
* **Prediction market contracts** — `instrumentSymbol` values like `GMKETSBTCUSD-20261231-T100000`

```bash theme={null}
# List all Gemini tickers
curl -H "x-api-key: your_key" \
  http://data.graylayer.tech/api/gemini/tickers

# Filter to BTC-related tickers
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/tickers?prefix=BTC"

# Filter to prediction market contracts
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/tickers?prefix=GMKETS"

# Snapshot for BTC/USD spot
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/snapshots/BTCUSD?limit=50"

# Snapshot for a prediction market contract
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/snapshots/GMKETSBTCUSD-20261231-T100000?limit=20"

# Deltas for ETH/USD over a window
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/deltas/ETHUSD?start_ts=2026-03-26T14:00:00Z&end_ts=2026-03-26T15:00:00Z&limit=1000"

# Deltas for a prediction market
curl -H "x-api-key: ak_prod_abc123def456" \
  "http://data.graylayer.tech/api/gemini/deltas/GMKETSBTCUSD-20261231-T100000?start_ts=2026-03-26T00:00:00Z"
```

**Snapshot response (Gemini crypto spot)**

```json theme={null}
{
  "exchange": "gemini",
  "ticker": "BTCUSD",
  "count": 4,
  "rows": [
    {"ts": "2026-03-26T14:01:05.000Z", "side": "bid", "price": "87450.00", "quantity": "0.5000"},
    {"ts": "2026-03-26T14:01:05.000Z", "side": "bid", "price": "87400.00", "quantity": "1.2000"},
    {"ts": "2026-03-26T14:01:05.000Z", "side": "ask", "price": "87500.00", "quantity": "0.3000"},
    {"ts": "2026-03-26T14:01:05.000Z", "side": "ask", "price": "87550.00", "quantity": "2.1000"}
  ]
}
```

***

## Typical usage pattern

To reconstruct the book at a point in time and track it forward:

1. Fetch a snapshot just before your target time to get the full book state
2. Fetch deltas starting at that snapshot's `ts` to replay changes forward
3. Apply each delta: add `quantity_delta` to the existing quantity at `(side, price)`; remove the level if quantity reaches zero

```bash theme={null}
# 1. Get book state just before 14:00
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/kalshi/snapshots/KXBTC15M-26MAR281500-50?end_ts=2026-03-26T14:00:00Z&limit=500"

# 2. Replay changes from 14:00 onward
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/kalshi/deltas/KXBTC15M-26MAR281500-50?start_ts=2026-03-26T14:00:00Z"
```

Same pattern works across all exchanges:

```bash theme={null}
# Polymarket book reconstruction
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/snapshots/will-bitcoin-reach-150k-in-2026?end_ts=2026-03-26T14:00:00Z&limit=500"

curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/deltas/will-bitcoin-reach-150k-in-2026?start_ts=2026-03-26T14:00:00Z"

# Gemini book reconstruction
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/snapshots/BTCUSD?end_ts=2026-03-26T14:00:00Z&limit=500"

curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/deltas/BTCUSD?start_ts=2026-03-26T14:00:00Z"
```

***

## Cross-market queries

Compare the same question across exchanges:

```bash theme={null}
# BTC prediction — Kalshi
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/kalshi/snapshots/KXBTC-25?limit=1"

# BTC prediction — Polymarket
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/polymarket_us/snapshots/will-bitcoin-reach-150k-in-2026?limit=1"

# BTC spot — Gemini
curl -H "x-api-key: your_key" \
  "http://data.graylayer.tech/api/gemini/snapshots/BTCUSD?limit=1"
```

***

## Notes

* Timestamps are **UTC RFC 3339** (e.g. `2026-03-26T12:00:00Z`)
* `side` is `"bid"` or `"ask"`
* `quantity_delta` can be negative (level removed or reduced)
* Prices and quantities are decimal strings
* Rows are always sorted `ts` ascending; `limit` truncates after sort
* Send `Accept-Encoding: gzip` for smaller payloads — responses are gzip compressed
* History begins from **March 7, 2026**