Foxbit WebSocket API (3.0)

Welcome to Foxbit's official trader and developer documentation! Here, you'll find everything you need to know to integrate and utilize our services effectively. Whether you're a seasoned trader or just starting out, our comprehensive documentation provides clear guidance on how to make the most out of our API.

We also have a full API usage examples repository demonstrating how to integrate and utilize our API, and in JavaScript for the WebSocket example: Example Repository

Features

• Robust Functionality: Explore the wide range of functionalities our websocket offers, including fetching real-time market data, receiving updates about orders, trades and much more.
• Detailed Guides: Step-by-step guides and tutorials help you get started quickly and navigate complex features effortlessly.
• Comprehensive Reference: Dive deep into our API endpoints, parameters, and response structures with our detailed reference documentation.

This API provides both public and private channels, each accessible through specific URLs:

• Public WebSocket: wss://api.foxbit.com.br/ws/v3/public
• Private WebSocket: wss://api.foxbit.com.br/ws/v3/private

You can view the full list of available channels for both public and private subscriptions in the navigation menu.

Start Exploring

Ready to get started? Dive into our documentation and unleash the full potential of our Exchange API. Whether you're building trading automation, conducting research, or developing innovative solutions, our API provides the tools you need to succeed.

Happy coding! 🚀

Need More?

If you don't find something here, you can check our other APIs' documentation:

See all available APIs

A changelog is a record of all notable changes made to this API, including new features, bug fixes and updates. It helps users and developers stay informed about the evolution of the project. For more details, visit our changelog page.

The Rate Limit is divided into five topics, these being connection, concurrent connection, subscriptions by message, subscriptions by connection and messages by period.
Note: Rate limits for public connections are controlled by IP Address.

If a channel does not have rate limit information in its documentation, it will use our global rate limit values:

#	Public	Private
Connections per period	10 connections per 2 seconds	10 connections per 2 seconds
Messages per period	10 messages per 2 seconds	10 messages per 2 seconds
Concurrent connections	30 concurrent connections	30 concurrent connections
Subscriptions per message	25 subscriptions per message	25 subscriptions per message
Subscriptions per connection	50 subscriptions per connection	-

Secure access to private WebSocket functionality requires authentication. This section explains the end-to-end flow, signature generation, recommended client practices, and common troubleshooting hints to help you get connected quickly and reliably.

How It Works

Authentication is performed on the private WebSocket by sending a login message that includes a timestamp and an HMAC-SHA256 signature. The signature is generated with your private API key by concatenating the timestamp with the literal string login and hashing the result. If the signature is valid and within the allowed time window, the server responds with a success event and the connection becomes authorized to subscribe to private channels.

Time Window and Clock Skew

The server validates that the provided timestamp is recent. For stable connectivity, keep your client clock synchronized (e.g., via NTP) and generate the timestamp as close as possible to the moment you send the message. Large clock skews can cause the request to be rejected.

Message Payload

To create the signature, you can use the following code:

import CryptoJS from 'crypto-js';

const timestamp = Date.now();
const signature = CryptoJS.HmacSHA256(`${timestamp}login`, privateKey).toString();

Example in Python:

import hmac, hashlib, time

timestamp = str(int(time.time() * 1000))
payload = f"{timestamp}login".encode()
signature = hmac.new(private_key.encode(), payload, hashlib.sha256).hexdigest()

Recommended Client Flow

1. Open a connection to the private WebSocket.
2. Immediately send the authentication message using a fresh timestamp and corresponding signature.
3. Wait for the authentication success event before subscribing to any private channels.
4. If authentication fails, handle the error gracefully (see the troubleshooting section) and retry only after verifying keys and time synchronization.

Security Best Practices

• Store API keys securely and never expose them in client-side logs or UIs.
• Rotate keys periodically and revoke unused credentials.
• Use environment variables or a secure secrets manager for deployments.
• Prefer short-lived processes to reduce the attack surface of long-running sessions.

Troubleshooting Tips

• Verify the exact string being signed is ${timestamp}login (no spaces, encoding issues, or extra characters).
• Log the computed timestamp and signature in a secure, redacted way during development.
• Ensure you send the auth message before any private subscriptions.
• Keep your system clock synchronized (NTP) to avoid time-based rejections.

The Ping channel enables users to verify their connection to the server. When a ping is sent, the server will respond with a "success" event message if the connection is active.

Additionally, the Ping channel can be used to keep the connection alive. If the connection remains idle for too long, the server will close it. Regularly sending pings prevents this from happening. This functionality is available for both public and private connections. Recommendation: It is recommended to send a ping message every 20 seconds for each open connection to maintain optimal connection health and prevent automatic disconnection due to inactivity.

To send a ping, use the following message format:

This message will be sent when the user was successfully pinged

Provides summary data for a market, including the latest traded price, volume, and price changes over 24hr. Users will receive updates every 1000ms until they send an unsubscribe call.

To subscribe or unsubscribe from WebSocket channels, use the following message format: The type field determines the action ("subscribe" or "unsubscribe"), while params specifies the target channels and markets.

This message will be sent when the user was successfully subscribed to the channel with specified market data

This message will be sent when the user was successfully unsubscribed from the channel with specified market data

This message will be sent when the user sends an invalid payload; the connection will be closed automatically when an error occurs

This message will be sent at every market change if the user has successfully subscribed

Streams the current bid and ask orders in the market, showing price levels and available quantities. Users will receive updates every 1000ms by default, unless a different interval is specified, until they send an unsubscribe call.

Available intervals:

• 100ms
• 250ms
• 500ms
• 1000ms (default)

To subscribe or unsubscribe from WebSocket channels, use the following message format: The type field determines the action ("subscribe" or "unsubscribe"), while params specifies the target channels and markets.

This message will be sent when the user was successfully subscribed to the channel with specified market data

This message will be sent when the user was successfully unsubscribed from the channel with specified market data

This message provides a snapshot of the current orderbook state when you first subscribe to the orderbook channel. The snapshot is essential for initializing your local orderbook copy and serves as the foundation for maintaining an accurate, real-time orderbook in memory.

Depth: The orderbook snapshot returns the top 300 levels for both buy and sell sides.

Purpose and Usage:

• Initial State: The snapshot gives you the current state of buy and sell orders at the moment of subscription
• Memory Management: Use this data to build your initial in-memory orderbook structure before processing incremental updates
• Synchronization: The snapshot includes a sequence_id which is crucial for maintaining data consistency

Sequential Processing: After receiving the snapshot, all subsequent orderbook update events will be sequential and incremental. Each update event includes first_sequence_id and last_sequence_id to ensure you don't miss any orderbook changes and can maintain a perfectly synchronized local copy.

Implementation Strategy:

1. Subscribe to the orderbook channel with snapshot param as true
2. Receive and process the complete snapshot to build your initial orderbook state
3. Store the sequence_id from the snapshot
4. Process all subsequent update events sequentially using their first_sequence_id and last_sequence_id to maintain your local orderbook

Example Implementation: For a complete example of how to manage the orderbook in memory using JavaScript, check out our sample implementation: JavaScript Orderbook Management Example

This message will be sent when the user sends an invalid payload; the connection will be closed automatically when an error occurs

This message will be sent at every market change if the user has successfully subscribed

Streams aggregated market data over fixed time intervals (e.g., 1m, 5m, 1h), including open, high, low, close prices, and traded volume. Users will receive updates at the end of each interval until they send an unsubscribe call.

Available intervals:

time	1m	5m	15m	30m	1h	2h	4h	6h	12h	1d	1w	2w
seconds	60	300	900	1800	3600	7200	14400	21600	43200	86400	604800	1209600

To subscribe or unsubscribe from WebSocket channels, use the following message format: The type field determines the action ("subscribe" or "unsubscribe"), while params specifies the target channels and markets.

This message will be sent when the user was successfully subscribed to the channel with specified market data

This message will be sent when the user was successfully unsubscribed from the channel with specified market data

This message will be sent when the user sends an invalid payload; the connection will be closed automatically when an error occurs

This message will be sent at every market change if the user has successfully subscribed

Provides a real-time feed of executed trades, showing each transaction’s price, quantity, timestamp and taker side. Users will receive updates as trades occur until they send an unsubscribe call.

To subscribe or unsubscribe from WebSocket channels, use the following message format: The type field determines the action ("subscribe" or "unsubscribe"), while params specifies the target channels and markets.

This message will be sent when the user was successfully subscribed to the channel with specified market data

This message will be sent when the user was successfully unsubscribed from the channel with specified market data

This message will be sent when the user sends an invalid payload; the connection will be closed automatically when an error occurs

This message will be sent at every market change if the user has successfully subscribed

The Login channel is used to authenticate and authorize a user on the Private WebSocket connection. By sending a login message with a valid timestamp and signature, users can gain access to private channels that provide real-time updates about their account activities, such as orders, trades, and balances.
For more information about the signature generation, please refer to the Authentication section.

To authenticate, send a login message with the following format:

This message will be sent when the user was successfully authenticated. After receiving it, you can safely subscribe to private channels.

If the signature is invalid, the timestamp is too old, or the key has been revoked, the server will respond with an error. Typical causes include:

• Incorrect private key or misconfigured environment variables.
• Client clock skew beyond the allowed window.
• Truncated payload or incorrect concatenation when building the string to sign.
• Using a stale timestamp when retrying.

The following failure schema describes the error response:

The Account Events channel provides real-time notifications about all activities in your trading account. This channel is essential for monitoring your portfolio, tracking order execution, and building automated trading strategies. Users will receive updates continuously until they send an unsubscribe call.

Note: This channel requires authentication on the Private WebSocket connection. Ensure you have successfully authenticated before attempting to subscribe.

Available event types:

• Balance: Notifies when available or locked balance changes for any currency
• Order: Provides updates on order lifecycle (created, filled, partially filled, cancelled, rejected)
• Trade: Sent when your orders are matched and executed in the market

Common use cases:

• Real-time portfolio tracking and balance monitoring
• Automated trading bots that react to order fills
• Order management systems with live status updates
• Risk management and position monitoring

To subscribe to account events, send a subscription message through your authenticated WebSocket connection. Unlike public channels, account events don't require market symbols as they cover all activity across your account.

This message will be sent when you have successfully subscribed to the Account Events channel. From this point, you will receive real-time updates for all balance, order, and trade events as they occur in your account.

This message will be sent whenever your account balance changes, including when funds are locked for orders, unlocked from cancellations, or updated due to deposits, withdrawals, or trade executions. Each event includes both available and locked amounts for the affected currency.

This message will be sent at every stage of your order lifecycle, including when orders are created, partially filled, fully filled, cancelled, or rejected. The event provides complete order details including status, filled quantity, remaining quantity, and timestamps.

This message will be sent each time one of your orders is matched and executed in the market. A single order may generate multiple trade events if it's filled incrementally by matching with different orders in the book. Each event includes execution price, quantity, fees, and whether you were the maker or taker.