FCS WebSocket API

Get Started in 3 Steps

Start receiving real-time market data in minutes. No complex setup required - just include our JavaScript library and connect.

Step 1: Include the Library

Download and include fcs-client-lib.js in your HTML file.

<script src="fcs-client-lib.js"></script>

Step 2: Connect to WebSocket

Create a client instance with your API key and connect.

const client = new FCSClient("YOUR_API_KEY", "wss://ws-v4.fcsapi.com/ws");
client.connect();

Step 3: Subscribe to Symbols

Join symbols to start receiving real-time updates.

client.onconnected = () => {
    client.join("BINANCE:BTCUSDT", "60"); // Bitcoin 1-hour candles
};

client.onmessage = (data) => {
    console.log("Price update:", data);
};

Library Installation

The FCS WebSocket client library works in both browser and Node.js environments. Choose your preferred installation method.

Browser Installation

Download fcs-client-lib.js and include it in your HTML:

<script src="path/to/fcs-client-lib.js"></script>

Node.js Installation

For Node.js, install the ws package first:

npm install ws

Then require the library:

const FCSClient = require("./fcs-client-lib.js");

API Key Configuration

To use the WebSocket API, you need a valid API key:

• With Active Socket Subscription: Use your own API key from the dashboard
• For Testing/Demo: Use the demo key: fcs_socket_demo

// Using your API key (requires active socket subscription)
const client = new FCSClient("YOUR_API_KEY");

// Using demo key for testing
const client = new FCSClient("fcs_socket_demo");

Important: Standard REST API keys will NOT work with WebSocket. You must have an active socket subscription or use the demo key.

Connecting to WebSocket

Establish a WebSocket connection to start receiving real-time data. The client handles authentication, heartbeat, and reconnection automatically.

Creating Client Instance

const client = new FCSClient(apiKey, wsUrl);

// Parameters:
// apiKey (required): Your FCS API key
// wsUrl (optional): WebSocket server URL, defaults to "wss://ws-v4.fcsapi.com/ws/"

Connect Method

client.connect()
    .then((client) => {
        console.log("Connection established");
    })
    .catch((err) => {
        console.error("Connection failed:", err);
    });

Event Callbacks

// Server ready to receive commands
client.onconnected = () => {
    console.log("Connected and authenticated");
    // Join symbols here
};

// Automatic reconnection event
client.onreconnect = () => {
    console.log("Reconnected successfully");
};

// Connection closed
client.onclose = (event) => {
    console.log("Disconnected:", event.reason);
};

// WebSocket errors
client.onerror = (err) => {
    console.error("WebSocket error:", err);
};

Response Format

Symbol Subscription

Subscribe to symbols to receive real-time price updates. You can join multiple symbols with different timeframes simultaneously.

Join Symbol (Subscribe)

client.join(symbol, timeframe);

// Examples:
client.join("BINANCE:BTCUSDT", "60");     // Bitcoin 1-hour candles
client.join("FX:EURUSD", "5");           // EUR/USD 5-minute candles
client.join("NASDAQ:AAPL", "1D");         // Apple daily candles

Leave Symbol (Unsubscribe)

client.leave(symbol, timeframe);

// Example:
client.leave("BINANCE:BTCUSDT", "60");

Remove All Subscriptions

client.removeAll(); // Unsubscribe from all symbols

Symbol Format

Symbols must include exchange prefix:

// Correct formats:
"BINANCE:BTCUSDT"  // Crypto
"FX:EURUSD"       // Forex
"NASDAQ:AAPL"      // Stock
"OKX:ETHUSDT"      // Crypto from OKX

// Wrong format:
"BTCUSDT"          // Missing exchange prefix ❌

client.onconnected = () => {
    client.join("BINANCE:BTCUSDT", "60");
};

client.onconnected = () => {
    const symbols = [
        { symbol: "BINANCE:BTCUSDT", timeframe: "60" },
        { symbol: "BINANCE:ETHUSDT", timeframe: "60" },
        { symbol: "FX:EURUSD", timeframe: "15" },
        { symbol: "NASDAQ:AAPL", timeframe: "1D" }
    ];

    symbols.forEach(s => client.join(s.symbol, s.timeframe));
};

WebSocket Message Types

The WebSocket server sends different message types. Handle them in your onmessage callback to process real-time updates.

Message Handler

client.onmessage = (data) => {
    switch(data.type) {
        case "welcome":
            console.log("Welcome:", data.message);
            console.log("Client ID:", data.clientId);
            console.log("Debug Info:", data.debug);
            break;
        case "price":
            if (data.prices.mode === "candle") {
                console.log("Candle Update:", data.symbol, data.prices);
            } else if (data.prices.mode === "askbid") {
                console.log("Ask/Bid Update:", data.prices.a, data.prices.b);
            }
            break;
        case "message":
            console.log("Server message:", data.message);
            if (data.short === "joined_room") {
                console.log("Joined room:", data.room);
            }
            break;
        case "error":
            console.error("Error:", data.message);
            break;
    }
};

Price Update Modes

Price messages include two modes:

• candle: Full OHLCV data for the current candle period
• askbid: Real-time ask/bid prices between candle periods

Response Format

{
    "type": "price",
    "symbol": "BINANCE:BTCUSDT",
    "timeframe": "15",
    "prices": {
        "mode": "candle",
        "t": 1766076300,
        "o": 88284.57,
        "h": 88305.49,
        "l": 88022.62,
        "c": 88165.3,
        "v": 83.39898
    }
}

Advanced Configuration

The FCS WebSocket client includes intelligent features like automatic reconnection, tab visibility handling, and connection optimization.

Tab Visibility Management (Browser Only)

In browser environments, automatically disconnect when tab is inactive to save resources:

// Browser environment
client.focusTimeout = 3; // Disconnect after 3 minutes of inactivity
client.focusTimeout = 0; // Never disconnect (always connected)

Note: In Node.js environment, focusTimeout is automatically set to 0 (never disconnect) since there is no tab visibility concept.

Automatic Reconnection

If the WebSocket connection closes unexpectedly, the library will automatically attempt to reconnect:

client.reconnectDelay = 3000;      // Wait 3 seconds before reconnect
client.reconnectlimit = 5;         // Max 5 reconnection attempts

// Reconnection event
client.onreconnect = () => {
    console.log("Successfully reconnected!");
    // All subscriptions are automatically restored
};

Manual Disconnect

client.disconnect(); // Closes connection and stops auto-reconnect

Connection Status

if (client.isConnected) {
    console.log("WebSocket is connected");
}

console.log("Reconnect count:", client.countreconnects);

Response Format

Full Working Example

A complete, production-ready example showing all features: connection, subscription, message handling, error recovery, and real-time price display.

Server-Side WebSocket (Node.js)

Use the FCS WebSocket client in Node.js for server-side applications, trading bots, data logging, and backend integrations.

Installation

npm install ws

Node.js Implementation

const FCSClient = require("./fcs-client-lib.js");

const client = new FCSClient("YOUR_API_KEY");

client.connect()
    .then(() => console.log("Connected to FCS WebSocket"))
    .catch(err => console.error("Connection failed:", err));

client.onconnected = () => {
    console.log("Authenticated and ready");

    // Subscribe to multiple symbols
    client.join("BINANCE:BTCUSDT", "60");
    client.join("BINANCE:ETHUSDT", "60");
    client.join("FX:EURUSD", "60");
};

client.onmessage = (data) => {
    if (data.type === "price") {
        console.log(`${data.symbol}: $${data.prices.c}`);

        // Save to database, trigger alerts, etc.
        saveToDatabase(data);
    }
};

function saveToDatabase(priceData) {
    // Your database logic here
    console.log("Saving to DB:", priceData);
}

WebSocket Pricing Plans

FCS WebSocket API requires a paid subscription. Choose the plan based on your update frequency needs and concurrent connection requirements.

Available Plans

View complete pricing details at fcsapi.com/websocket-pricing

Common Issues & Solutions

Quick solutions to common WebSocket connection and usage issues.

Connection Issues

Terms & Disclaimer

Important legal information about data usage, accuracy, and limitations of the FCS WebSocket service.

Data Accuracy

Real-time prices are indicative and sourced from multiple exchanges and liquidity providers. While we strive for accuracy, data may not be 100% accurate or suitable for high-frequency trading.

Trading Disclaimer

Prices, market data, and signals provided via WebSocket are for informational and educational purposes only. They are NOT intended for trading purposes. We bear NO responsibility for any trading losses incurred from using this data.

Service Availability

We maintain 99.9% uptime but cannot guarantee uninterrupted service. Network issues, server maintenance, or technical problems may cause temporary disconnections.