Theme:
← Back to all documentation

Futures WebSocket API Documentation

This document describes all WebSocket API routers defined in Futures.
For each API, you will find:
- Full Endpoint address
- Purpose (Explanation)
- How to use it
- Upstream Params (parameters sent to upstream data fetchers)
- Client-side Filters/Search/Sort/Pagination
- Example Request to trigger the API
- Response Structure
- Example Response

Notes

Filters, Search, Sort, Pagination

All endpoints support the following client-side features via query params or WebSocket messages, applied using the ws_apply_filters function:

These filters are applied on the server side after data is fetched from upstream APIs, allowing flexible client-side customization of the returned data. The system uses pandas for large datasets (>100 items) and falls back to original implementation for smaller datasets.

1. /futures/ws/contract-comparison/table

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/contract-comparison/table?ticker=BTC

Purpose:
Stream a table comparing futures contracts for a given ticker across Binance, Bybit, and CoinDesk with Smart Hybrid System integration for dynamic coin icons and metadata.

Upstream Params:
- ticker (required): Coin ticker, e.g. "BTC" - markets (optional): Comma-separated CoinDesk markets, e.g. "binance,bybit,bitmex" - instrument_map (optional): JSON string for custom instrument mapping

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"exchange": "Binance"} - search (string): search string - sort_by (string): field to sort by (e.g. "funding_rate", "open_interest") - sort_order (string): "asc" or "desc" - page (int): page number - page_size (int): items per page

How it works:
The router fetches contract comparison data using fetch_coindesk from ContractsComparisonClient with concurrent processing for multiple markets. Uses Smart API Management with rate limit handling and exponential backoff. Applies deduplication and enhanced caching, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/contract-comparison/table?ticker=BTC&markets=binance,bybit,bitmex&filters={"exchange":"Binance"}&sort_by=funding_rate&sort_order=desc&page=1&page_size=10

Response Structure:
A JSON object with headers, filtered rows, adaptive interval, and enhanced metadata.

Example Response:
json { "headers": [ {"key": "coin_icon", "label": "Icon", "sortable": false}, {"key": "exchange", "label": "Exchange", "sortable": true}, {"key": "pair", "label": "Pair", "sortable": true}, {"key": "last_price", "label": "Last Price", "sortable": true}, {"key": "funding_rate", "label": "Funding Rate", "sortable": true}, {"key": "open_interest", "label": "Open Interest", "sortable": true}, {"key": "volume_2h", "label": "2h Volume", "sortable": true} ], "rows": { "results": [ { "coin_icon": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png", "coin_symbol": "BTC", "coin_name": "Bitcoin", "exchange": "CoinDesk-binance", "pair": "BTCUSDT", "last_price": 67000.12, "funding_rate": 0.0001, "open_interest": 123456789.0, "volume_2h": 987654321.0, "exchange_logo": "https://logo.clearbit.com/binance.com" } ], "count": 3, "processing_method": "pandas" }, "adaptive_interval": 80, "timestamp": 1640995200.0, "query_params": { "ticker": "BTC", "markets": "binance,bybit,bitmex", "instrument_map": null } }

2. /futures/ws/fund-rate-tracker/table

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/fund-rate-tracker/table?symbols=BTC,ETH,SOL

Purpose:
Stream a table of funding rates, mark prices, and next funding times for futures contracts across Binance, Bybit, and CoinDesk with enhanced error handling and rate limiting.

Upstream Params:
- symbol (optional): Single futures symbol, e.g. "BTCUSD" (deprecated, use symbols) - symbols (optional): Comma-separated symbols, e.g. "BTC,ETH,SOL" - markets (optional): Comma-separated CoinDesk markets - instruments (optional): Comma-separated CoinDesk instruments

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"exchange":"Bybit"} - search (string) - sort_by (string): e.g. "funding_rate", "mark_price" - sort_order (string) - page, page_size

How it works:
The router fetches funding rate data using fetch_all from FundingRateTrackerClient with concurrent execution for multiple exchanges. Handles both single symbol and multiple symbols with proper parameter conversion. Applies enhanced caching with deduplication and uses ws_apply_filters for client-side customization.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/fund-rate-tracker/table?symbols=BTC,ETH&markets=binance,bybit&filters={"exchange":"Bybit"}&sort_by=funding_rate&sort_order=desc&page=1&page_size=10

Response Structure:
A JSON object with headers and filtered rows with proper structure for multiple exchanges.

Example Response:
json { "headers": [ {"key": "exchange", "label": "Exchange", "sortable": true}, {"key": "pair", "label": "Pair", "sortable": true}, {"key": "mark_price", "label": "Mark Price", "sortable": true}, {"key": "funding_rate", "label": "Funding Rate", "sortable": true}, {"key": "next_funding_time", "label": "Next Funding Time", "sortable": true} ], "rows": { "results": [ { "exchange": "bybit", "exchange_logo": "https://img.logo.dev/bybit.com?token=logo_pub_key", "pair": "BTCUSDT", "mark_price": 67000.12, "funding_rate": 0.0001, "next_funding_time": "2025-10-25 16:00:00", "current_hour_change": 0.0002, "current_day_change": 0.0001, "moving_24H_change": 0.0003 } ], "count": 2, "processing_method": "original" }, "adaptive_interval": 80, "timestamp": 1640995200.0, "query_params": { "symbols": "BTC,ETH", "markets": "binance,bybit" } }

3. /futures/ws/funding-rate-chart

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/funding-rate-chart?symbol=BTCUSDT&exchanges=binance,bybit,bitmex

Purpose:
Stream funding rate time-series chart for a futures symbol with price overlay using CoinDesk historical APIs with enhanced time filtering and aggregation.

Upstream Params:
- symbol (required): Base symbol, e.g. "BTC", "ETH" - start_time (optional): Start timestamp in seconds (CoinDesk expects seconds) - end_time (optional): End timestamp in seconds - limit (default: 30): Number of data points (1-5000) - aggregate (default: 1): Aggregation interval in days (1-30) - exchanges (optional): Comma-separated exchange names, e.g. "binance,bybit,bitmex" - instruments (optional): List of specific CoinDesk instruments

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"source":"CoinDesk-binance"} - search (string) - sort_by (string): e.g. "funding_rate", "price" - sort_order (string) - page, page_size - start_time, end_time - timeframe (string): e.g. "7d", "24h", "1h" - time_field (string): field to filter time range on (default: "timestamp")

How it works:
The router fetches historical funding rate data using fetch_historical_funding_rate_chart from FundingRateTrackerClient with concurrent requests to CoinDesk funding rate and mark price APIs. Processes each market-instrument combination with rate limiting and generates chart structure with price overlay. Applies time filtering and other filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/funding-rate-chart?symbol=BTC&exchanges=binance,bybit&start_time=1640995200&end_time=1641081600&limit=100&filters={"source":"CoinDesk-binance"}&timeframe=7d&time_field=timestamp

Response Structure:
Enhanced chart structure with concurrent data fetching and price overlay integration.

Example Response:
json { "symbol": "BTC", "exchanges": ["binance", "bybit", "bitmex"], "x": [1640995200000, 1641081600000], "y": [0.0001, 0.0002], "price_overlay": [67000.12, 67500.34], "sources": ["CoinDesk-binance", "CoinDesk-bybit"], "y_axis": "Funding Rate", "x_axis": "DateTime", "title": "Funding Rate History for BTC", "series": [ { "name": "Funding Rate", "type": "line", "data": [[1640995200000, 0.0001], [1641081600000, 0.0002]] }, { "name": "Price Overlay", "type": "line", "data": [[1640995200000, 67000.12], [1641081600000, 67500.34]], "y_axis": "Price", "color": "#ff6b6b", "yAxisIndex": 1 } ], "count": 2, "adaptive_interval": 80, "timestamp": 1640995200.0, "query_params": { "symbol": "BTC", "exchanges": "binance,bybit", "start_time": 1640995200, "end_time": 1641081600, "limit": 100, "timeframe": "7d" } }

```markdown

4. /futures/ws/oi-price/chart

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/oi-price/chart

Purpose:
Stream chart-ready open interest and price time-series data using CoinDesk Historical OHLC+ API. This endpoint provides dual-axis chart data with price on the primary Y-axis and open interest on the secondary Y-axis, along with a timestamp-based X-axis.

Upstream Params:
- symbol (required): Trading symbol, e.g., "BTCUSDT", "ETHUSDT". - exchange (default: "bybit"): CoinDesk market/exchange, e.g., "binance", "bitmex", "bybit". - category (optional): Product type for compatibility, e.g., "linear", "inverse". - start_time, end_time (optional): Time range in milliseconds for filtering. - timeframe (default: "1m"): Time range shorthand, e.g., "1w", "1m", "3m", "5m", "1y", or "custom" for custom date ranges. - page, page_size (default: 1, 2000): Pagination parameters for client-side filtering. - filters (optional): JSON string for field-based filtering, e.g., {"source":"CoinDesk-bybit"}. - search (optional): String for fuzzy search across fields. - sort_by, sort_order (optional): Sorting parameters, e.g., "timestamp" and "asc" or "desc". - interval (default: 10.0): Push interval in seconds for WebSocket updates.

How it works:
The router fetches open interest and price data using the fetch_oi_price_chart method from the OIPriceChartClient. It integrates both current/latest data and historical OHLC+ data from the CoinDesk API. The data is processed with comprehensive error handling, deduplication, and filtering using ws_apply_filters. The response includes enhanced chart-ready data with dual Y-axis support for price and open interest.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/oi-price/chart?symbol=BTCUSDT&exchange=bybit&start_time=1759363200000&end_time=1760020800000&timeframe=custom&page_size=1000 ws://127.0.0.1:8000/tzone_apis/services/futures/ws/oi-price/chart?symbol=BTCUSDT&exchange=bybit&category=linear&timeframe=3m&page_size=1000

Response Structure:
The response includes chart-ready data with enhanced metadata and OHLC+ support.

json { "x": [1759363200000, 1759376800000], "y_price": [67000.12, 67200.34], "y_open_interest": [123456789.0, 123556789.0], "sources": ["CoinDesk-bybit", "CoinDesk-bybit"], "symbol": "BTCUSDT", "y_axis_primary": "Price", "y_axis_secondary": "Open Interest", "x_axis": "DateTime", "title": "Open Interest & Price Chart for BTCUSDT", "series": [ { "name": "Price", "type": "line", "data": [[1759363200000, 67000.12], [1759376800000, 67200.34]], "yAxisIndex": 0, "color": "#2563eb" }, { "name": "Open Interest", "type": "line", "data": [[1759363200000, 123456789.0], [1759376800000, 123556789.0]], "yAxisIndex": 1, "color": "#dc2626" } ], "count": 2, "markets": ["bybit"], "instruments": ["BTCUSDT"], "data_source": "CoinDesk Historical OHLC+ API", "historical_included": true, "timeframe_applied": "custom", "timeframe_config": { "start_time": 1759363200000, "end_time": 1760020800000, "historical_interval": "hours", "historical_limit": 2000, "timeframe": "custom" }, "adaptive_interval": 10.0, "timestamp": 1761582537.2447476, "query_params": { "symbol": "BTCUSDT", "exchange": "bybit", "category": "linear", "timeframe": "custom", "start_time": 1759363200000, "end_time": 1760020800000 } }

Key Features: 1. Dual-Axis Chart:
- Primary Y-Axis: Price data (y_price).
- Secondary Y-Axis: Open interest data (y_open_interest).
- X-Axis: Timestamps (x) in milliseconds.

  1. Custom Time Ranges:
    Supports both predefined timeframes (1w, 1m, etc.) and custom date ranges using start_time and end_time.

  2. Pagination and Filtering:

  3. Supports client-side filtering, sorting, and pagination using filters, search, sort_by, sort_order, page, and page_size.

  4. Historical OHLC+ Data:
    Fetches historical open interest and price data from CoinDesk with configurable intervals (minutes, hours, days).

  5. Error Handling:
    Includes fallback to cached data and comprehensive error messages for rate limits or service unavailability.

  6. Adaptive Push Interval:
    Dynamically adjusts the WebSocket push interval based on the size of the response.

Notes: - The start_time and end_time parameters must be in Unix timestamp format (milliseconds). - The timeframe parameter determines the granularity of the data (hours for short timeframes, days for longer ones). - The page_size parameter defaults to 2000 but can be increased up to 5000 for larger datasets.

5. /futures/ws/top-contracts-oi

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/top-contracts-oi?coindesk_markets=binance,bybit,bitmex&sort_by=open_interest&sort_order=desc

Purpose:
Stream a sortable table of top futures contracts by open interest using CoinDesk REST API with exchange information integration and enhanced data processing.

Upstream Params:
- category (optional): Category for compatibility (not used with CoinDesk) - coindesk_markets (default: extensive list): List of CoinDesk markets/exchanges - coindesk_instruments (optional): Dict mapping market to instruments - coindesk_limit (default: 50): Number of contracts to fetch - sort_by (default: "open_interest"): Sort field - sort_order (default: "desc"): Sort order - exchange_filter (optional): Filter by exchange names

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"exchange":"Binance"} - search (string) - sort_by (string): e.g. "open_interest", "price" - sort_order (string) - page, page_size

How it works:
The router fetches top contracts data using get_top_contracts_table from TopContractsOIClient with CoinDesk REST API integration. Uses exchange_list API for proper exchange information and logos, applies clean pair name processing, and transforms contracts to match desired format. Enhanced with circuit breaker protection and comprehensive error handling, then applies filtering using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/top-contracts-oi?coindesk_markets=binance,bybit,bitmex&sort_by=open_interest&sort_order=desc&filters={"exchange":"Binance"}&page=1&page_size=20

Response Structure:
Enhanced table format with exchange information integration and clean data transformation.

Example Response:
json { "headers": [ {"key": "rank", "label": "Rank"}, {"key": "pair", "label": "Pair"}, {"key": "base_logo", "label": "base_logo"}, {"key": "quote_logo", "label": "quote_logo"}, {"key": "exchange", "label": "Exchange"}, {"key": "exchange_logo", "label": "Logo"}, {"key": "open_interest", "label": "Open Interest"}, {"key": "price", "label": "Price"}, {"key": "volume_24h", "label": "24h Volume"} ], "rows": { "results": [ { "rank": 1, "pair": "BTCUSDT", "base_logo": "https://img.logo.dev/crypto/btc?token=logo_pub_key", "quote_logo": "https://img.logo.dev/crypto/usdt?token=logo_pub_key", "exchange": "Binance", "exchange_logo": "https://logo.clearbit.com/binance.com", "open_interest": 123456789.0, "price": 67000.12, "volume_24h": 987654321.0 } ], "count": 1, "processing_method": "original" }, "controls": { "exchange_filter": ["Binance", "Bybit", "BitMEX"], "sort_by": "open_interest", "sort_order": "desc" }, "data_sources": ["CoinDesk"], "coindesk_markets": ["binance", "bybit", "bitmex"], "adaptive_interval": 80, "timestamp": 1640995200.0 }

6. /futures/ws/fear-greed-index

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/fear-greed-index?mode=latest&days=30&chart_interval=daily

Purpose:
Stream Fear and Greed Index data with multiple modes (latest, history, chart, summary, dashboard) using alternative.me API with comprehensive filtering and chart generation.

Upstream Params:
- mode (default: "latest"): Data mode - latest, history, chart, summary, dashboard - days (default: 30): Number of days for history/chart (0 for all available, max 365) - limit (default: 1): Limit for raw API calls (1 for latest, 0 for all, max 100) - format_type (default: "json"): Response format - json or csv - date_format (default: ""): Date format - us, cn, kr, world, or '' for unix - chart_interval (default: "daily"): Chart interval - daily, weekly, monthly

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"value_classification":"Extreme Fear"} - search (string) - sort_by (string): e.g. "value", "timestamp" - sort_order (string) - page, page_size - timeframe (string): e.g. "7d", "24h", "1h" - time_field (string): field to filter time range on (default: "timestamp")

How it works:
The router fetches Fear & Greed data using multiple methods from FearGreedIndexClient based on mode. Supports latest values, historical data, chart generation with aggregation, comprehensive summaries, and dashboard layouts. Enhanced with rate limiting, comprehensive error handling, and time-based filtering. Applies filtering using ws_apply_filters for all modes.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/fear-greed-index?mode=chart&days=30&chart_interval=daily&filters={"value_classification":"Fear"}&timeframe=7d&time_field=timestamp

Response Structure:
Enhanced response structure varying by mode with comprehensive metadata and filtering support.

Example Response:
json { "mode": "chart", "data": { "x": [1640995200000, 1641081600000], "y": [25, 45], "labels": ["2022-01-01 00:00:00", "2022-01-02 00:00:00"], "classifications": ["Fear", "Neutral"], "title": "Fear and Greed Index Chart (30 days)", "y_axis": "Fear & Greed Index (0-100)", "x_axis": "Date", "count": 2, "series": [ { "name": "Fear & Greed Index", "type": "line", "data": [[1640995200000, 25], [1641081600000, 45]], "color": "#ff8844" } ], "zones": [ {"value": 0, "color": "#ff4444", "label": "Extreme Fear"}, {"value": 25, "color": "#ff8844", "label": "Fear"}, {"value": 45, "color": "#ffcc44", "label": "Neutral"}, {"value": 55, "color": "#88cc44", "label": "Neutral"}, {"value": 75, "color": "#44cc44", "label": "Greed"}, {"value": 100, "color": "#44ff44", "label": "Extreme Greed"} ], "source": "alternative.me" }, "parameters": { "days": 30, "chart_interval": "daily", "format_type": "json", "date_format": "", "timeframe": "7d" }, "adaptive_interval": 80, "timestamp": "2025-10-25 12:00:00", "source": "alternative.me" }

7. /futures/ws/live-liquidation-feed

Full Endpoint:
ws://<host>/tzone_apis/services/futures/ws/live-liquidation-feed?asset_filter=BTCUSDT,ETHUSDT&exchange_filter=binance,bybit&max_size=100

Purpose:
Stream real-time liquidation events with Smart Hybrid System integration for dynamic coin discovery and comprehensive WebSocket management.

Upstream Params:
- asset_filter (optional): Comma-separated symbols for filtering - exchange_filter (optional): Comma-separated exchanges, e.g. "binance,bybit" - max_size (default: 100, max: 200): Maximum number of liquidation events

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"exchange":"Binance"} - search (string) - sort_by (string): e.g. "timestamp", "quantity" - sort_order (string) - page, page_size

How it works:
The router fetches live liquidation data using get_live_liquidation_feed from LiveLiquidationFeedClient with Smart Hybrid System for 100% coin coverage. Uses concurrent WebSocket connections to multiple exchanges, enhanced with dynamic coin icons from CoinGecko API, comprehensive caching, and rate limiting. Applies filtering using ws_apply_filters with real-time data processing.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/futures/ws/live-liquidation-feed?asset_filter=BTCUSDT,ETHUSDT&exchange_filter=binance,bybit&max_size=50&filters={"exchange":"Binance"}&sort_by=timestamp&sort_order=desc&page=1&page_size=20

Response Structure:
Enhanced feed structure with Smart Hybrid System integration and dynamic coin information.

Example Response:
json { "feed": { "results": [ { "timestamp": 1640995200000, "datetime": "2022-01-01T00:00:00.000000+00:00", "exchange": "Binance", "exchange_logo": "https://logo.clearbit.com/binance.com", "pair": "BTCUSDT", "side": "Long", "price": 67000.12, "quantity": 1.5, "coin_icon": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png", "coin_symbol": "BTC", "coin_name": "Bitcoin" } ], "count": 1, "processing_method": "original" }, "controls": { "asset_filter": ["BTCUSDT", "ETHUSDT"], "exchange_filter": ["binance", "bybit"], "max_size": 50 }, "adaptive_interval": 80, "timestamp": 1640995200.0, "query_params": { "asset_filter": "BTCUSDT,ETHUSDT", "exchange_filter": "binance,bybit", "max_size": 50 } }

Additional Notes