> TickerLayer documentation for AI agents and LLMs, the Markdown version of https://tickerlayer.com/docs/websocket/connection
> REST base URL https://api.tickerlayer.com, API key in the `x-api-key` header. WebSocket wss://stream.tickerlayer.com?apiKey=YOUR_API_KEY.
> Any docs page reads as Markdown at its URL plus `.md`. Index: https://tickerlayer.com/llms.txt · Full API reference: https://tickerlayer.com/llms-full.txt

# Connection

Open one native WebSocket to the stream host. Authentication is part of the upgrade URL. After a successful handshake the first application message is always a ready frame.

## Connect URL

The stream host is `wss://stream.tickerlayer.com`. Pass your raw API key, URL-encoded, as the `apiKey` query parameter ([Authentication](https://tickerlayer.com/docs/websocket/authentication)). To try it before wiring a client, use the live panel on the [WebSocket overview](https://tickerlayer.com/docs/websocket#try-live).

**Default connect URL**

```javascript
const ws = new WebSocket(
  "wss://stream.tickerlayer.com/?apiKey=" + encodeURIComponent(rawKey)
);
```

Custom path

The path defaults to `/`. An account given a custom stream path adds it before the query string, for example `wss://stream.tickerlayer.com/stream?apiKey=…`.

## Upgrade outcomes

| Status | Meaning |
| --- | --- |
| `101 Switching Protocols` | Connected. The first frame is [ready](https://tickerlayer.com/docs/websocket/connection#ready-frame). |
| `401` | Missing or invalid `apiKey`, or a key not entitled for WebSocket. A plain HTTP response; no frames are sent. |
| `403` | The key exists but the `ws` surface is not enabled for this account. |
| `429` | A global or per-account connection limit; the account limit answers with `WS_CONNECTION_LIMIT_EXCEEDED`. With [reserved connections](https://tickerlayer.com/docs/websocket/connection#reserved-connections) it can also say the remaining slots are reserved while the account is below its total. |

## Reserved connections per key

Your connection allowance is shared by every API key on the account. In the dashboard's **Manage API keys** panel you can reserve part of it for one key, so a critical consumer such as an oracle feed or a production service survives reconnect storms or leaks in your other environments.

- **Reserved slots:** A key with `N` reserved slots can always open at least `N` connections, whatever your other keys hold. Keys without a reservation share the rest.
- **When the shared part is full:** Connects from keys without a reservation get `WS_CONNECTION_LIMIT_EXCEEDED` even below the account total, and the message says the remaining slots are reserved.
- **Changes:** Apply to new connections within a few seconds and never close open sockets. Reservations can never add up to more than the account allowance.

## Ready frame

Sent right after a successful upgrade. Wait for it before any subscribe.

**Server → client**

```json
{
  "type": "system",
  "event": "ready",
  "ts": 1743512400000
}
```

## Connections in the dashboard

The **Connections** page, opened from the WebSocket usage card on your [dashboard](https://tickerlayer.com/dashboard), lists the account's open WebSocket connections and the ones that ended in the last 7 days, with the source IP and country, the API key, how long each stayed open and how it ended. Times are in UTC.

- **Live:** Each open connection with its symbols and channels.
- **Last 7 days:** Each ended connection and how it ended: a close from your client with its code, a drop without a close frame, no reply to ping (`4008`), a reconnect request from the server (`1012`), or an access change on the account.
- **By IP:** Connections per source address, with the ones that closed within 10 seconds in the last 24 hours. An address you do not recognize is a reason to regenerate that key.
- **Reconnect loops:** Three or more connections in a row from one address and key that each closed within 10 seconds show as one row. Keep one long-lived connection per service and back off between retries ([Disconnects](https://tickerlayer.com/docs/websocket/troubleshooting#disconnects)).