WebSocket API

The Datafye WebSocket API provides real-time streaming access to live market data. This API is designed for scenarios where you run your own algorithmic trading containers and need continuous updates of market data.

Base URL

The WebSocket API base URL depends on your deployment model and where your containers are running:

Local (Standalone) Deployments

ws://localhost:8080/datafye-ws/v1/...

Cloud (Distributed) Deployments

Internal Access (containers running within the deployment):

ws://api.rumi.local/datafye-ws/v1/...

External Access (containers running remotely, if configured):

ws://<user>-<type>-<env>-api.datafye.io/datafye-ws/v1/...

Where:

• <user> - The unique name assigned to you by Datafye (e.g., acme)

• <type> - Deployment type: foundry or trading

• <env> - Environment identifier (omit for production, or use dev, staging, etc.)

Examples: acme-foundry-api.datafye.io, acme-foundry-dev-api.datafye.io

External Access: External URLs are disabled by default and must be explicitly configured. Security is enforced through IP allowlisting (not API keys or credentials). For self-managed deployments, configure IP allowlisting in your cloud provider's infrastructure. For Datafye Managed deployments, contact your administrator. External access may require secure WebSocket connections (wss://). See API URLs and Security Model for complete details.

Connection Lifecycle

1. Connect

Establish a WebSocket connection to the server:

// Replace with appropriate URL for your deployment:
// - Local: 'ws://localhost:8080/datafye-ws/v1/market-data'
// - Cloud (internal): 'ws://api.rumi.local/datafye-ws/v1/market-data'
// - Cloud (external): 'ws://acme-foundry-api.datafye.io/datafye-ws/v1/market-data'
const ws = new WebSocket('ws://api.rumi.local/datafye-ws/v1/market-data');

2. Subscribe

Send subscription messages to receive specific data streams:

{
  "action": "subscribe",
  "channel": "quotes",
  "symbols": ["AAPL", "MSFT", "GOOGL"]
}

3. Receive Data

Handle incoming market data messages:

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Process market data
};

4. Unsubscribe

Stop receiving data for specific subscriptions:

{
  "action": "unsubscribe",
  "channel": "quotes",
  "symbols": ["AAPL"]
}

5. Disconnect

Close the WebSocket connection:

ws.close();

Message Formats

Subscription Request

{
  "action": "subscribe",
  "channel": "quotes|trades|aggregates",
  "symbols": ["SYMBOL1", "SYMBOL2", ...],
  "requestId": "optional-client-request-id"
}

Subscription Response

{
  "type": "subscription",
  "status": "success",
  "channel": "quotes",
  "symbols": ["AAPL", "MSFT"],
  "requestId": "optional-client-request-id"
}

Market Data Message

{
  "type": "quote",
  "symbol": "AAPL",
  "bidPrice": 182.50,
  "bidSize": 200,
  "askPrice": 182.52,
  "askSize": 150,
  "timestamp": "2024-01-15T15:59:59.456Z"
}

Error Message

{
  "type": "error",
  "code": "INVALID_SYMBOL",
  "message": "The specified symbol was not found in the security master",
  "details": {
    "symbol": "INVALID"
  }
}

Available Channels

Channel	Description	Data Type
quotes	Real-time quote updates (bid/ask)	Level 1 market data
trades	Real-time trade executions	Trade ticks
aggregates	Real-time OHLC bars	Aggregated data

Heartbeat and Keep-Alive

The server sends periodic heartbeat messages to maintain the connection:

{
  "type": "heartbeat",
  "timestamp": "2024-01-15T16:00:00.000Z"
}

Clients should respond with a pong message:

{
  "action": "pong"
}

If no heartbeat response is received within 30 seconds, the server will close the connection.

Error Handling

Connection Errors

Handle connection failures and implement reconnection logic:

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = (event) => {
  console.log('Connection closed:', event.code, event.reason);
  // Implement exponential backoff reconnection
  setTimeout(() => reconnect(), 1000);
};

Subscription Errors

Handle invalid subscription requests:

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === 'error') {
    console.error(`Subscription error: ${message.code} - ${message.message}`);
    // Handle error appropriately
  }
};

Best Practices

Reconnection Strategy

Implement exponential backoff for reconnections:

class DatafyeWebSocket {
  constructor(baseUrl) {
    // baseUrl examples:
    // - 'ws://localhost:8080' (local)
    // - 'ws://api.rumi.local' (cloud internal)
    // - 'ws://acme-foundry-api.datafye.io' (cloud external)
    this.url = `${baseUrl}/datafye-ws/v1/market-data`;
    this.reconnectDelay = 1000;
    this.maxReconnectDelay = 30000;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url);

    this.ws.onopen = () => {
      console.log('Connected');
      this.reconnectDelay = 1000; // Reset delay on successful connection
      this.resubscribe(); // Resubscribe to previous subscriptions
    };

    this.ws.onclose = () => {
      console.log(`Reconnecting in ${this.reconnectDelay}ms...`);
      setTimeout(() => this.connect(), this.reconnectDelay);
      this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
    };

    this.ws.onerror = (error) => {
      console.error('WebSocket error:', error);
    };
  }

  resubscribe() {
    // Resubscribe to channels that were active before disconnect
  }
}

// Usage:
// const ws = new DatafyeWebSocket('ws://api.rumi.local');

Message Buffering

Handle message backpressure during high-volume periods:

const messageQueue = [];
let processing = false;

ws.onmessage = (event) => {
  messageQueue.push(JSON.parse(event.data));

  if (!processing) {
    processMessages();
  }
};

async function processMessages() {
  processing = true;

  while (messageQueue.length > 0) {
    const message = messageQueue.shift();
    await handleMessage(message);
  }

  processing = false;
}

Subscription Management

Track active subscriptions for reconnection:

class SubscriptionManager {
  constructor(ws) {
    this.ws = ws;
    this.subscriptions = new Map();
  }

  subscribe(channel, symbols) {
    const key = `${channel}:${symbols.join(',')}`;

    if (!this.subscriptions.has(key)) {
      this.subscriptions.set(key, { channel, symbols });

      this.ws.send(JSON.stringify({
        action: 'subscribe',
        channel: channel,
        symbols: symbols
      }));
    }
  }

  resubscribeAll() {
    for (const [key, sub] of this.subscriptions.entries()) {
      this.ws.send(JSON.stringify({
        action: 'subscribe',
        channel: sub.channel,
        symbols: sub.symbols
      }));
    }
  }
}

Examples

Basic Quote Subscription

Local deployment:

const ws = new WebSocket('ws://localhost:8080/datafye-ws/v1/market-data');

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'quotes',
    symbols: ['AAPL', 'MSFT', 'GOOGL']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'quote') {
    console.log(`${data.symbol}: Bid ${data.bidPrice} Ask ${data.askPrice}`);
  }
};

Cloud deployment (internal access):

const ws = new WebSocket('ws://api.rumi.local/datafye-ws/v1/market-data');

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'quotes',
    symbols: ['AAPL', 'MSFT', 'GOOGL']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'quote') {
    console.log(`${data.symbol}: Bid ${data.bidPrice} Ask ${data.askPrice}`);
  }
};

Cloud deployment (external access):

const ws = new WebSocket('ws://acme-foundry-api.datafye.io/datafye-ws/v1/market-data');

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'quotes',
    symbols: ['AAPL', 'MSFT', 'GOOGL']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'quote') {
    console.log(`${data.symbol}: Bid ${data.bidPrice} Ask ${data.askPrice}`);
  }
};

Multi-Channel Subscription

ws.onopen = () => {
  // Subscribe to both quotes and trades
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'quotes',
    symbols: ['AAPL']
  }));

  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'trades',
    symbols: ['AAPL']
  }));
};

Related Documentation

• Connection - Detailed connection management

• Real-time Market Data - Data streaming specifics

• Data Access Modes - Understanding Datafye data access and delivery

---

Last updated: 2025-10-14