# Quick Start

Get connected and receiving announcements in under 5 minutes.

### 1. Get your API key

You will receive an API key from the administrator. It looks like this:

```
dsk_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890ab
```

All keys start with the `dsk_` prefix followed by 64 hexadecimal characters.

{% hint style="warning" %}
Store your API key securely. It is shown **only once** when created and cannot be retrieved later.
{% endhint %}

### 2. Connect to the WebSocket

```
wss://cryptolisting.ws
```

Pass your API key via the `X-API-Key` HTTP header during the WebSocket handshake.

{% tabs %}
{% tab title="Python" %}

```bash
pip install websocket-client
```

```python
# pip install websocket-client
import json, websocket
from datetime import datetime

URL    = "wss://cryptolisting.ws"
HEADER = ["X-API-Key: dsk_your_key_here"]

def on_open(ws):
    print("Connected!")

def on_message(ws, message):
    data = json.loads(message)
    ts   = datetime.now().strftime("%H:%M:%S.%f")[:-3]

    if data["type"] == "announcement":
        print(f"[{ts}] {data['listingType']} | {data['ticker']} on {data['publisher']}")
        print(f"        {data['title']}")
    elif data["type"] == "welcome":
        print(f"[{ts}] Welcome — tier={data['tier']}, cex={data['allowedCex']}")

def on_close(ws, code, msg):
    print(f"Disconnected ({code}). Reconnecting...")
    connect()

def connect():
    websocket.WebSocketApp(
        URL, header=HEADER,
        on_open=on_open, on_message=on_message, on_close=on_close
    ).run_forever(ping_interval=30, ping_timeout=10)

connect()
```

{% endtab %}

{% tab title="Node.js" %}

```bash
npm install ws
```

```javascript
const WebSocket = require("ws");

const URL = "wss://your-host:9201";

function connect() {
  const ws = new WebSocket(URL, {
    headers: { "X-API-Key": "dsk_your_key_here" },
  });

  ws.on("open", () => console.log("Connected!"));

  ws.on("message", (raw) => {
    const data = JSON.parse(raw);
    if (data.type === "announcement") {
      console.log(`${data.listingType} | ${data.ticker} on ${data.publisher}`);
      console.log(`  ${data.title}`);
    } else if (data.type === "welcome") {
      console.log(`Welcome — tier=${data.tier}, cex=${data.allowedCex}`);
    }
  });

  ws.on("close", () => {
    console.log("Disconnected. Reconnecting...");
    setTimeout(connect, 1000);
  });
}

connect();
```

{% endtab %}
{% endtabs %}

### 3. Receive messages

Once connected, you will immediately receive a **welcome message** confirming your subscription:

```json
{
  "type": "welcome",
  "tier": "premium",
  "maxConnections": 5,
  "allowedCex": "*",
  "expiresInSecs": 86400
}
```

Then you will receive:

* **Heartbeats** every 30 seconds -- confirms the connection is alive.
* **Announcements** whenever a listing or other exchange announcement is detected.

```json
{
  "type": "announcement",
  "title": "Binance Will List TOKEN (TOKEN)",
  "ticker": "TOKEN",
  "publisher": "binance",
  "listingType": "spot_listing",
  "publishTimestampUs": 1710345000000000,
  "detectedTimestampUs": 1710345000005000,
  "dispatchTimestampUs": 1710345000006000
}
```

### 4. Filter by exchange (optional)

To receive announcements only from specific exchanges, add the `cex` query parameter:

```
wss://cryptolisting.ws?cex=binance
wss://cryptolisting.ws?cex=binance,upbit
```

Omit the parameter to receive announcements from all exchanges.

### Next steps

* Message Reference -- full field-by-field documentation
* Error Handling & Reconnection -- build a resilient client
* Code Examples -- production-ready implementations