Getting Started

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 →

WebSockets

Market Data

Price

Quick Start

Prerequisites

Installation

Your First Connection

Your First Subscription

Connection Endpoints

Subscription Format

Request Structure

Market Data Subscription Examples

Supported Blockchains

Unsubscribing

Authentication Errors

Next Steps

​Quick Start

​Prerequisites

​Installation

​Your First Connection

​Your First Subscription

​Connection Endpoints

​Subscription Format

​Request Structure

​Market Data Subscription Examples

​Supported Blockchains

​Unsubscribing

​Authentication Errors

​Next Steps

Quick Start

Prerequisites

Installation

Your First Connection

Your First Subscription

Connection Endpoints

Subscription Format

Request Structure

Market Data Subscription Examples

Supported Blockchains

Unsubscribing

Authentication Errors

Next Steps