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

npm install -g wscat

Your First Connection

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

wscat -c "wss://ws.amberdata.com/spot" -H "x-api-key: <your-api-key>"

Your First Subscription

Once connected, subscribe to block events:

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

Response:

{
  "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:

{
  "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:

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

Multiple Instruments (make separate requests):

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

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

Exchange-wide Subscription (Spot only):

{
  "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.

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:

{
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "params": ["242d29d5c0ec9268f51a39aba4ed6a36c757c03c183633568edb0531658a9799"],
  "id": 1
}

Response:

{
  "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:

{
    "jsonrpc": "2.0",
    "id": 0,
    "error": {
        "description": "invalid api key 'UAKHelloCryptoHiAmberdata'",
        "code": 401
    }
}

Next Steps

• Learn about subscription guidelines and best practices →
• Explore advanced configuration and error handling →