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

# Getting Started

> Learn how to connect to Amberdata's WebSocket services and make your first subscription for real-time, low-latency data streaming.

Amberdata's WebSocket services provide real-time, low-latency data streaming across multiple blockchain and market data feeds. This guide will get you connected and subscribed quickly.

## Quick Start

### Prerequisites

* Valid Amberdata API key
* WebSocket client (we'll use `wscat` for examples)

### Installation

```bash theme={null}
npm install -g wscat
```

### Your First Connection

Connect to Amberdata's WebSocket endpoint with your API key:

```bash theme={null}
wscat -c "wss://ws.amberdata.com/spot" -H "x-api-key: <your-api-key>"
```

### Your First Subscription

Once connected, subscribe to block events:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "binance", "pair": "btc_usdt"}]
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "a04c6fe3-f85a-402c-8f29-d17627b48576",
  "metadata": [
    "exchange",
    "pair",
    "timestamp",
    "timestampNanoseconds",
    "tradeId",
    "price",
    "volume",
    "isBuy"
  ]
}
```

You'll now receive real-time trade events like this:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscription": "a04c6fe3-f85a-402c-8f29-d17627b48576",
    "result": [
      [
        "binance",
        "btc_usdt",
        1755108576827,
        747408,
        "5154882831",
        121651.18,
        0.00041,
        true
      ]
    ]
  }
}
```

## Connection Endpoints

Use the appropriate endpoint for optimal performance based on your data type:

| Data Type        | Connection URL                    | Best For                                       |
| ---------------- | --------------------------------- | ---------------------------------------------- |
| **General**      | `wss://ws.amberdata.com`          | Blockchain data, general subscriptions         |
| **Spot Markets** | `wss://ws.amberdata.com/spot`     | Spot trading data (OHLCV, tickers, trades)     |
| **Futures**      | `wss://ws.amberdata.com/futures`  | Futures data (funding rates, liquidations, OI) |
| **Options**      | `wss://ws.amberdata.com/options`  | Options data (liquidations, OI, trades)        |
| **DEX**          | `wss://ws.amberdata.com/defi/dex` | Decentralized exchange trades                  |

## Subscription Format

All subscription requests follow JSON-RPC 2.0 format:

### Request Structure

| Field     | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `jsonrpc` | string | Yes      | Must be "2.0"                          |
| `method`  | string | Yes      | "subscribe" or "unsubscribe"           |
| `params`  | array  | Yes      | \[subscription\_type, options\_object] |
| `id`      | number | Yes      | Client-generated identifier            |

### Market Data Subscription Examples

**Spot Market Data:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "coinbase", "pair": "btc_usd"}]
}
```

**Multiple Instruments (make separate requests):**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "binance", "pair": "btc_usdt"}]
}
```

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "binance", "pair": "eth_usdt"}]
}
```

**Exchange-wide Subscription (Spot only):**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"pair": "btc_usdt"}]
}
```

## Supported Blockchains

For specifc blockchains, specify as a header in the initial HTTP upgrade request.

```bash theme={null}
wscat -c "wss://ws.amberdata.com" -H "x-api-key: <your-api-key>" -H "x-amberdata-blockchain-id: ethereum-mainnet"
```

| Blockchain   | Network | Blockchain ID         |
| ------------ | ------- | --------------------- |
| Bitcoin      | Mainnet | `bitcoin-mainnet`     |
| Bitcoin Cash | Mainnet | `bitcoin-abc-mainnet` |
| Ethereum     | Mainnet | `ethereum-mainnet`    |
| Litecoin     | Mainnet | `litecoin-mainnet`    |

## Unsubscribing

Stop receiving notifications by sending an unsubscribe request:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "params": ["242d29d5c0ec9268f51a39aba4ed6a36c757c03c183633568edb0531658a9799"],
  "id": 1
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}
```

## Authentication Errors

If your API key is invalid, you'll receive this error and the connection will close:

```json theme={null}
{
    "jsonrpc": "2.0",
    "id": 0,
    "error": {
        "description": "invalid api key 'UAKHelloCryptoHiAmberdata'",
        "code": 401
    }
}
```

## Next Steps

* Learn about [subscription guidelines and best practices →](/real-time/websocket-guidelines)
* Explore [advanced configuration and error handling →](/real-time/websocket-advanced)