Python Real-time WebSocket client library for Forex, Cryptocurrency, and Stock market data from FCS API.
This library provides Python integration with WebSocket for live market data streaming. Uses the JavaScript client library for browser-based real-time updates.
- Real-time WebSocket - Live price updates via WebSocket connection
- Multi-Market Support - Forex, Crypto, and Stock data in one library
- Python Backend Ready - Easy integration with Python applications
- No Dependencies - Uses Python built-in
http.servermodule - Auto-Reconnect - Handles WebSocket connection drops automatically
- Tab Visibility - Smart disconnect when browser tab is hidden (saves bandwidth)
- Heartbeat - Built-in WebSocket keep-alive mechanism
Use demo API key for testing: fcs_socket_demo
pip install fcsapi-websocket-python- Download or clone this repository
- No dependencies required - uses Python built-in modules
- Include the JavaScript library in your templates
<!-- Include JS library from CDN -->
<script src="https://cdn.jsdelivr.net/gh/fcsapi/websocket-python/fcs-client-lib.js"></script>from http.server import HTTPServer, SimpleHTTPRequestHandler
API_KEY = 'YOUR_API_KEY' # Or use 'fcs_socket_demo' for testing
SYMBOL = 'BINANCE:BTCUSDT'
TIMEFRAME = '1D'
HTML_TEMPLATE = '''
<!DOCTYPE html>
<html>
<head>
<title>FCS Real-time Data</title>
<script src="https://cdn.jsdelivr.net/gh/fcsapi/websocket-python/fcs-client-lib.js"></script>
</head>
<body>
<div id="price">Loading...</div>
<script>
const client = new FCSClient('<!--API_KEY-->');
client.onmessage = (data) => {
if (data.type === 'price' && data.prices) {
const p = data.prices;
if (p.mode === 'candle' || p.mode === 'initial') {
document.getElementById('price').innerText =
`${data.symbol}: $${p.c} (O:${p.o} H:${p.h} L:${p.l})`;
}
}
};
client.connect().then(() => {
client.join('<!--SYMBOL-->', '<!--TIMEFRAME-->');
});
</script>
</body>
</html>
'''
class RequestHandler(SimpleHTTPRequestHandler):
def do_GET(self):
if self.path == '/':
self.send_response(200)
self.send_header('Content-type', 'text/html')
self.end_headers()
html = HTML_TEMPLATE
html = html.replace('<!--API_KEY-->', API_KEY)
html = html.replace('<!--SYMBOL-->', SYMBOL)
html = html.replace('<!--TIMEFRAME-->', TIMEFRAME)
self.wfile.write(html.encode())
else:
super().do_GET()
if __name__ == '__main__':
server = HTTPServer(('localhost', 5000), RequestHandler)
print("Open http://localhost:5000")
server.serve_forever()const client = new FCSClient(apiKey, url);| Parameter | Type | Default | Description |
|---|---|---|---|
apiKey |
string | required | Your FCS API key |
url |
string | wss://ws-v4.fcsapi.com/ws |
WebSocket server URL (optional) |
Connects to the WebSocket server. Returns a Promise.
client.connect().then(() => {
console.log('Connected!');
}).catch(err => {
console.error('Connection failed:', err);
});Manually closes the connection.
client.disconnect();Subscribe to a symbol for real-time updates.
// Forex
client.join('FX:EURUSD', '1m');
// Crypto
client.join('BINANCE:BTCUSDT', '1m');
// Stock
client.join('NASDAQ:AAPL', '1m');Unsubscribe from a symbol.
client.leave('FX:EURUSD', '1m');Unsubscribe from all symbols.
client.removeAll();| Callback | Description |
|---|---|
onconnected |
Fired when connection is established |
onmessage |
Fired when data is received |
onclose |
Fired when connection is closed |
onerror |
Fired when an error occurs |
onreconnect |
Fired when reconnection is successful |
client.onconnected = () => console.log('Connected!');
client.onmessage = (data) => console.log('Data:', data);
client.onclose = (event) => console.log('Closed:', event.code);
client.onerror = (err) => console.error('Error:', err);
client.onreconnect = () => console.log('Reconnected!');| Property | Type | Default | Description |
|---|---|---|---|
reconnectDelay |
number | 3000 | Delay (ms) before reconnection attempt |
reconnectlimit |
number | 5 | Maximum reconnection attempts |
focusTimeout |
number | 3 | Minutes before disconnect when tab is hidden (0 = never) |
const client = new FCSClient('YOUR_API_KEY');
client.reconnectDelay = 5000; // 5 seconds
client.reconnectlimit = 10; // 10 attempts
client.focusTimeout = 5; // 5 minutesThe WebSocket sends different message types:
{
"type": "message",
"success": true,
"message": "Successfully joined room: BINANCE:BTCUSDT_1D_0s",
"room": "BINANCE:BTCUSDT_1D_0s",
"symbol": "BTCUSDT",
"timeframe": "1D",
"short": "joined_room"
}{
"type": "price",
"symbol": "BINANCE:BTCUSDT",
"timeframe": "1D",
"prices": {
"mode": "profile",
"profile": {
"current_session": "market",
"timezone": "Etc/UTC",
"pro_name": "BINANCE:BTCUSDT",
"update_mode": "streaming"
}
}
}{
"type": "price",
"symbol": "BINANCE:BTCUSDT",
"timeframe": "1D",
"prices": {
"mode": "initial",
"t": 1766361600, // Timestamp (Unix seconds)
"o": 88658.87, // Open price
"h": 90588.23, // High price
"l": 87900, // Low price
"c": 89962.61, // Close price
"v": 0.247 // Volume
}
}Primary update mode - contains all price data including OHLCV and Ask/Bid.
{
"type": "price",
"symbol": "BINANCE:BTCUSDT",
"timeframe": "1D",
"prices": {
"mode": "candle",
"t": 1766361600, // Timestamp
"o": 88658.87, // Open
"h": 90588.23, // High
"l": 87900, // Low
"c": 89962.61, // Close
"v": 8192.70, // Volume
"a": 89962.62, // Ask price
"b": 89962.61 // Bid price
}
}Sent when only Ask/Bid data changes. All values in this message are updated.
{
"type": "price",
"symbol": "BINANCE:BTCUSDT",
"timeframe": "1D",
"prices": {
"mode": "askbid",
"update": 1766411426, // Update timestamp
"c": 89962.61, // Close price
"a": 89962.62, // Ask price
"b": 89962.61, // Bid price
"t": 1766361600 // Candle timestamp
}
}client.onmessage = (data) => {
if (data.type === 'price' && data.prices) {
const p = data.prices;
const symbol = data.symbol;
switch (p.mode) {
case 'profile':
console.log(`${symbol} Profile loaded`);
break;
case 'initial':
case 'candle':
console.log(`${symbol}: O=${p.o} H=${p.h} L=${p.l} C=${p.c} V=${p.v} Ask=${p.a} Bid=${p.b}`);
break;
case 'askbid':
console.log(`${symbol}: Ask=${p.a} Bid=${p.b}`);
break;
}
}
};Symbols must include an exchange prefix:
| Market | Format | Examples |
|---|---|---|
| Forex | FX:PAIR |
FX:EURUSD, FX:GBPUSD, FX:USDJPY |
| Crypto | EXCHANGE:PAIR |
BINANCE:BTCUSDT, BINANCE:ETHUSDT |
| Stock | EXCHANGE:SYMBOL |
NASDAQ:AAPL, NYSE:TSLA |
| Timeframe | Description |
|---|---|
1 |
1 minute |
5 |
5 minutes |
15 |
15 minutes |
30 |
30 minutes |
1H |
1 hour |
4H |
4 hours |
1D |
1 day |
1W |
1 week |
1M |
1 month |
Check the /examples folder for complete working demos:
- crypto_example.py - Real-time Cryptocurrency prices
- forex_example.py - Real-time Forex prices
- stock_example.py - Real-time Stock prices
- flask_crypto_example.py - Crypto with Flask
- flask_forex_example.py - Forex with Flask
- flask_stock_example.py - Stock with Flask
# Basic examples (No dependencies required!)
cd examples
python crypto_example.py # Open http://localhost:5000
python forex_example.py # Open http://localhost:5001
python stock_example.py # Open http://localhost:5002
# Flask examples (requires: pip install flask)
python flask_crypto_example.py # Open http://localhost:5000
python flask_forex_example.py # Open http://localhost:5001
python flask_stock_example.py # Open http://localhost:5002The library automatically handles browser tab visibility to save bandwidth:
- When tab is hidden for more than 3 minutes (configurable), connection is closed
- When tab becomes visible again, connection is automatically restored
- All subscriptions are automatically rejoined after reconnection
Set focusTimeout = 0 to disable this feature:
client.focusTimeout = 0; // Never disconnect when tab hiddenclient.onerror = (err) => {
console.error('WebSocket error:', err);
};
client.onclose = (event) => {
if (event.code !== 1000) {
console.error('Unexpected close:', event.code, event.reason);
}
};- Visit FCS API
- Sign up for a free account
- Get your API key from the dashboard
For complete API documentation, visit:
- Email: support@fcsapi.com
- Website: fcsapi.com
MIT License - see LICENSE file for details.