WebSocket API

Connecting

Connect to the WebSocket endpoint with your API key. The key can be provided via query parameter, Authorization header, or socket auth token.

Authentication Methods

JavaScript Example

import { io } from 'socket.io-client';

const socket = io('wss://api.predikt.fun/api/v1/ws', {
  auth: { token: 'pk_live_your_api_key' }
});

socket.on('connect', () => {
  console.log('Connected!');
});

socket.on('message', (data) => {
  console.log('Received:', data);
});

socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});

Connection Response

Upon successful connection, you'll receive a connected message.

{
  "type": "connected",
  "accountId": "acc_abc123",
  "connectionId": "conn_xyz789",
  "timestamp": "2026-01-17T12:00:00.000Z"
}

Subscribe to Price Updates

Subscribe to real-time price updates for one or more symbols.

Request

// Using socket.emit
socket.emit('subscribe', {
  channel: 'price',
  symbols: ['SOL', 'BTC', 'ETH']
});

// Or using the 'message' event
socket.emit('message', {
  action: 'subscribe',
  channel: 'price',
  symbols: ['SOL', 'BTC', 'ETH']
});

Response

{
  "type": "subscribed",
  "channel": "price",
  "symbols": ["SOL", "BTC", "ETH"],
  "timestamp": "2026-01-17T12:00:01.000Z"
}

Receiving Price Updates

Once subscribed, you'll receive price updates every 5 seconds for each subscribed symbol.

{
  "type": "price_update",
  "symbol": "SOL",
  "price": 185.42,
  "source": "vwap",
  "timestamp": "2026-01-17T12:00:05.000Z"
}

Handling Price Updates

socket.on('message', (data) => {
  if (data.type === 'price_update') {
    console.log(`${data.symbol}: $${data.price}`);
    // Update your UI or trigger logic
  }
});

Unsubscribe from Price Updates

Unsubscribe from specific symbols to stop receiving their price updates.

Request

socket.emit('unsubscribe', {
  channel: 'price',
  symbols: ['BTC']
});

Response

{
  "type": "unsubscribed",
  "channel": "price",
  "symbols": ["BTC"],
  "timestamp": "2026-01-17T12:01:00.000Z"
}

Keep-Alive (Ping/Pong)

Send periodic ping messages to keep the connection alive. Connections without activity for 60 seconds may be closed.

socket.emit('ping');

{
  "type": "pong",
  "timestamp": "..."
}

Billing Notifications

WebSocket connections are billed hourly. You'll receive a notification each time you're charged.

{
  "type": "billing",
  "message": "Hourly subscription fee charged",
  "amountUsd": "0.10",
  "remainingBalanceUsd": "45.90",
  "timestamp": "2026-01-17T13:00:00.000Z"
}

Connection Limits

Connection and subscription limits vary by tier.

Error Messages

Errors are sent as messages with type: "error".

{
  "type": "error",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Maximum symbols (10) would be exceeded for STANDARD tier",
  "timestamp": "2026-01-17T12:00:00.000Z"
}

Error Codes

Message Types Summary

Client → Server

Server → Client