WebSockets

The Bitcompare API provides a WebSocket endpoint for real-time price updates with approximately 3-second latency.

Connecting

Connect to the WebSocket endpoint at /api/v1/prices/ws.

/api/v1/prices/ws

const ws = new WebSocket('wss://api.bitcompare.net/api/v1/prices/ws')

ws.addEventListener('open', () => {
  console.log('Connected to price stream')
})

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data)

  switch (message.type) {
    case 'welcome':
      console.log('Connected:', message.data.clientId)
      break
    case 'initial_prices':
      console.log('Current prices:', message.data)
      break
    case 'price_update':
      console.log('Updated prices:', message.data)
      break
    case 'subscribed':
      console.log('Subscription confirmed:', message.symbols)
      break
    case 'pong':
      console.log('Connection healthy')
      break
    case 'error':
      console.error('Server error:', message.error)
      break
  }
})

Message types

The server sends six message types:

Name
welcome
Description
Sent immediately on connection with the assigned client ID and server time.
Name
initial_prices
Description
Sent right after welcome with the current snapshot of all prices.
Name
price_update
Description
Sent every ~1 second when prices have changed. Contains an array of updated price ticks.
Name
subscribed
Description
Confirmation that the client is subscribed, includes the list of available symbols.
Name
pong
Description
Response to a client ping message for connection health checks.
Name
error
Description
Sent when the server receives an invalid message (e.g., malformed JSON).

Client commands

You can send commands to the server as JSON messages:

Ping for connection health

ws.send(JSON.stringify({ type: 'ping' }))
// Server responds with { type: 'pong', timestamp: '...' }

Subscribe to updates (optional — auto-subscribed on connect)

ws.send(JSON.stringify({ type: 'subscribe' }))
// Server responds with { type: 'subscribed', symbols: ['BTC', 'ETH', ...], timestamp: '...' }

Message format

welcome message

{
  "type": "welcome",
  "data": {
    "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "connectedAt": "2025-10-29T14:00:00Z",
    "serverTime": "2025-10-29T14:00:00Z"
  },
  "timestamp": "2025-10-29T14:00:00Z"
}

initial_prices message

{
  "type": "initial_prices",
  "data": [
    {
      "symbol": "BTC",
      "price": 45000.50,
      "volume": 12345,
      "timestamp": 1730212800000,
      "source": "binance"
    },
    {
      "symbol": "ETH",
      "price": 2500.75,
      "volume": 8900,
      "timestamp": 1730212800000,
      "source": "coinbase"
    }
  ],
  "timestamp": "2025-10-29T14:00:00Z"
}

price_update message

{
  "type": "price_update",
  "data": [
    {
      "symbol": "BTC",
      "price": 45050.25,
      "volume": 12400,
      "timestamp": 1730212801000,
      "source": "binance",
      "changePercent": 0.11,
      "previousPrice": 45000.50
    }
  ],
  "timestamp": "2025-10-29T14:00:01Z"
}

Price tick fields

Name
symbol
Type
string
Description
The cryptocurrency ticker symbol.
Name
price
Type
number
Description
Current price.
Name
volume
Type
number
Description
Trading volume (optional).
Name
timestamp
Type
number
Description
Unix timestamp in milliseconds.
Name
source
Type
string
Description
The provider source (e.g., "binance", "coinbase").
Name
changePercent
Type
number
Description
Percentage change from previous price (optional, only on price_update).
Name
previousPrice
Type
number
Description
Previous broadcast price (optional, only on price_update).

Heartbeat

The server pings connected clients every 30 seconds. Clients must respond with a pong within 60 seconds or they will be disconnected. Most WebSocket libraries handle this automatically.

Reconnection

Implement client-side reconnection with exponential backoff:

Reconnection with backoff

function connect(attempt = 0) {
  const ws = new WebSocket('wss://api.bitcompare.net/api/v1/prices/ws')

  ws.addEventListener('open', () => {
    attempt = 0 // Reset on successful connection
  })

  ws.addEventListener('close', () => {
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000)
    setTimeout(() => connect(attempt + 1), delay)
  })

  ws.addEventListener('message', (event) => {
    const message = JSON.parse(event.data)
    // Handle message...
  })
}

connect()