Skip to main content

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.

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 TypeConnection URLBest For
Generalwss://ws.amberdata.comBlockchain data, general subscriptions
Spot Marketswss://ws.amberdata.com/spotSpot trading data (OHLCV, tickers, trades)
Futureswss://ws.amberdata.com/futuresFutures data (funding rates, liquidations, OI)
Optionswss://ws.amberdata.com/optionsOptions data (liquidations, OI, trades)
DEXwss://ws.amberdata.com/defi/dexDecentralized exchange trades

​
Subscription Format

All subscription requests follow JSON-RPC 2.0 format:

​
Request Structure

FieldTypeRequiredDescription
jsonrpcstringYesMust be “2.0”
methodstringYes”subscribe” or “unsubscribe”
paramsarrayYes[subscription_type, options_object]
idnumberYesClient-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"
BlockchainNetworkBlockchain ID
BitcoinMainnetbitcoin-mainnet
Bitcoin CashMainnetbitcoin-abc-mainnet
EthereumMainnetethereum-mainnet
LitecoinMainnetlitecoin-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