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

# Usage

> How to connect and consume KicksDB SSE

## Endpoint

* **URL:** `GET https://sse.kicks.dev/v1/stream`
* **Protocol:** `text/event-stream`
* **Authentication:** `Authorization: Bearer YOUR_API_KEY`
* **Plan requirement:** Pro membership

The connection remains open and continuously streams events as they occur.

# Selecting Topics

SSE currently supports **price updates** for:

* StockX (all markets)
* GOAT (all markets)

You must specify which markets to listen to using the `Topics` header.

### Header format

```
Topics: price:stockx:us, price:stockx:uk, price:goat:us, price:goat:nl
```

### Rules

* Format: `[event_type]:[source]:[country_code]`
* Lowercase only
* Comma-separated

### Example request

```http theme={null}
GET https://sse.kicks.dev/v1/stream

Authorization: Bearer YOUR_API_KEY
Topics: price:goat:uk, price:goat:us, price:stockx:us
```

<Warning>
  KicksDB is primarily a product catalog, not a tick-level trading feed.
  Some markets may not emit events for extended periods depending on refresh cycles.
  Refer to [sources and markets](/guides/sources) for refresh expectations.
</Warning>

# Event Format

Each event follows the standard SSE format:

```
id: 152
event: price:goat:uk
data: { ...json payload... }
```

### Fields

* `id` — unique incremental event ID
* `event` — topic name (`source:market`)
* `data` — JSON payload

### Example Payload

```json theme={null}
{
  "source": "goat",
  "product_id": "583450",
  "variant_id": "8",
  "size": "8",
  "price": 150,
  "currency": "GBP",
  "market": "UK",
  "sku": "FW3725",
  "timestamp": "2026-02-24T23:46:11.910541096Z"
}
```

# Node.js Example

Node 18+ has native `fetch` support.
This example uses the `eventsource` package for automatic reconnection handling.

### Install

```bash theme={null}
npm install eventsource
```

### Example Listener

```js theme={null}
import { EventSource } from "eventsource";

const topics = ["price:stockx:us", "price:goat:uk"];

const es = new EventSource("https://sse.kicks.dev/v1/stream", {
  fetch: (input, init) =>
    fetch(input, {
      ...init,
      headers: {
        ...(init.headers || {}),
        Authorization: `Bearer [YOUR_API_KEY]`,
        Topics: topics.join(","),
      },
    })
});

es.onopen = () => {
  console.log("Connected to KicksDB SSE");
};

es.addEventListener("price:goat:uk", (event) => {
  const payload = JSON.parse(event.data);

  console.log("GOAT UK update:");
  console.log(payload);
});

es.onerror = (err) => {
  console.error("SSE connection error:", err);
};

```

# Reconnection & Resume (Recommended)

SSE supports automatic reconnection.

For production systems:

* Persist the last processed `id`
* Reconnect with `Last-Event-ID` header
* Use exponential backoff if connection fails repeatedly
* Run listener in a dedicated worker process

<Note>
  Only the 5,000 last events are retryable.
</Note>

# Testing with CLI

You can test streaming manually:

```bash theme={null}
http --stream https://sse.kicks.dev/v1/stream \
  "Authorization: Bearer YOUR_API_KEY" \
  "Topics: price:goat:uk"
```

If successful, you'll receive a continuous stream:

```
id: 152
event: goat:uk
data: { ... }

id: 153
event: goat:uk
data: { ... }
```