Stablecoins WebSocket API Documentation

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

Notes

• All endpoints require a WebSocket connection.
• All endpoints require Cookie Header. Example: Cookie: access_token=<token>; refresh_token=<token>
• For endpoints with query parameters, supply them in the connection URL. No message needs to be sent after connecting; data is pushed at intervals.
• All responses are JSON objects or lists; field names and structure may vary depending on backend implementation.
• All endpoints support client-side filtering, searching, sorting, and pagination via query params, applied using the ws_apply_filters function after data is fetched.

Filters, Search, Sort, Pagination

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

• filters: JSON string for field-based filtering (e.g. {"stablecoin": "USDT"})
• search: String for fuzzy search across fields
• sort_by: Field name to sort by (e.g. "market_cap", "price")
• sort_order: "asc" or "desc"
• page: Page number (integer)
• page_size: Items per page (integer)
• start_time, end_time: Unix timestamps for time range filtering
• timeframe: Shorthand time filters (e.g. "7d", "24h", "1h")
• time_field: Field to filter time range on (default: "timestamp")

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. /stablecoins/overall-market-snapshot

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/overall-market-snapshot

Purpose:
Stream overall market snapshot: total crypto market cap, BTC dominance, and ETH dominance as cards.

Upstream Params:
- None required. Data fetched concurrently from CoinGecko global data, Bitcoin metadata, and Ethereum metadata.

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"symbol": "BTC"} - search (string) - sort_by (string): e.g. "value" - sort_order (string) - page, page_size

How it works:
The router fetches market snapshot data using get_overall_market_snapshot from CoinGeckoClient with concurrent requests for global data, BTC and ETH metadata. Applies deduplication and enhanced caching (5min fresh, 15min stale). Then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/overall-market-snapshot?filters={"symbol":"BTC"}&sort_by=value&sort_order=desc&page=1&page_size=10

Response Structure:
A list of cards, each with title, value, and optionally logo and symbol, plus adaptive interval.

Example Response:
json { "results": [ {"title": "Total Crypto Market Cap", "value": "$2,345,678,901"}, {"title": "BTC Dominance", "value": "52.34 %", "logo": "...", "symbol": "BTC"}, {"title": "ETH Dominance", "value": "17.89 %", "logo": "...", "symbol": "ETH"} ], "count": 3, "adaptive_interval": 80, "timestamp": 1640995200.0 }

2. /stablecoins/btc_dom

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/btc_dom

Purpose:
Stream the current Bitcoin dominance percentage.

Upstream Params:
- None required. Uses CoinGecko global endpoint.

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by, sort_order, page, page_size

How it works:
The router fetches BTC dominance using fetch_bitcoin_dominance from CoinGeckoClient with deduplication support, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/btc_dom?filters={"Title":"Bitcoin Dominance"}

Response Structure:
A JSON object with BTC dominance wrapped in filter response structure.

Example Response:
json { "results": [ { "Title": "Bitcoin Dominance", "Value": "52.34 %" } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0 }

3. /stablecoins/eth_dom

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/eth_dom

Purpose:
Stream the current Ethereum dominance percentage.

Upstream Params:
- None required. Uses CoinGecko global endpoint.

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by, sort_order, page, page_size

How it works:
The router fetches ETH dominance using fetch_ethereum_dominance from CoinGeckoClient with deduplication support, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/eth_dom?filters={"Title":"Ethereum Dominance"}

Response Structure:
A JSON object with Ethereum dominance wrapped in filter response structure.

Example Response:
json { "results": [ { "Title": "Ethereum Dominance", "Value": "17.89 %" } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0 }

4. /stablecoins/ws/main_table

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/ws/main_table

Purpose:
Stream the latest stablecoins table data (rank, name, logo, price, 24h change percent, market cap).

Upstream Params:
- vs_currency (string, default "usd")

Client-side Filters/Search/Sort/Pagination:
- filters (e.g. {"name":"Tether"}) - search - sort_by (e.g. "market_cap") - sort_order - page, page_size

How it works:
The router fetches stablecoins table data using fetch_stablecoins_table from DefiLlammaDataClient with concurrent requests to DefiLlama and CoinGecko, enhanced caching with deduplication. Merges data efficiently and applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/ws/main_table?filters={"name":"Tether"}&sort_by=market_cap&sort_order=desc&page=1&page_size=10

Response Structure:
A JSON object with headers and rows, plus metadata.

Example Response:
json { "headers": [ {"key": "rank", "label": "Rank"}, {"key": "name", "label": "Name"}, {"key": "logo", "label": "Logo"}, {"key": "price", "label": "Price"}, {"key": "24h_change_percent", "label": "24h Change (%)"}, {"key": "market_cap", "label": "Market Cap"} ], "rows": [ { "rank": 1, "name": "Tether", "logo": "https://assets.coingecko.com/coins/images/325/large/Tether.png", "price": 1.0, "24h_change_percent": 0.01, "market_cap": 83000000000 } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0, "vs_currency": "usd" }

5. /stablecoins/ws/marketcap_total_index

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/ws/marketcap_total_index

Purpose:
Stream stablecoin market capitalization time series data.

Upstream Params:
- period (string, default "1d", supports "1d", "7d", "30d", "90d", "1y")

Client-side Filters/Search/Sort/Pagination:
- filters (e.g. {"marketcap":">1000000000"}) - search - sort_by (e.g. "marketcap") - sort_order - page, page_size - start_time, end_time - time_field (string): field to filter time range on (default: "timestamp")

How it works:
The router fetches marketcap time series using fetch_stablecoin_marketcap_timeseries from DefiLlammaDataClient with optimized data processing and efficient period filtering. Converts chart data to filterable format before applying ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/ws/marketcap_total_index?filters={"marketcap":">1000000000"}&sort_by=marketcap&sort_order=desc&page=1&page_size=10&start_time=1719878400000&end_time=1719882000000&time_field=timestamp

Response Structure:
Enhanced chart structure with data array and metadata.

Example Response:
json { "chart": { "x_label": "Time (unix timestamp)", "y_label": "Total Market Cap (USD)", "data": [ { "timestamp": 1719878400, "marketcap": 123456789 }, { "timestamp": 1719882000, "marketcap": 123556789 } ] }, "key_stats": { "latest_market_cap": 123556789, "price": 123556789, "controller": "1d" }, "count": 2, "adaptive_interval": 80, "timestamp": 1640995200.0, "period": "1d" }

6. /stablecoins/ws/distribution_analysis

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/ws/distribution_analysis

Purpose:
Stream stablecoin distribution analysis across blockchains.

Upstream Params:
- chains (list of strings, default ["ethereum", "bsc", "tron", "solana", "polygon"]) - period (string, default "1d")

Client-side Filters/Search/Sort/Pagination:
- filters (e.g. {"chain":"ethereum"}) - search - sort_by (e.g. "usd") - sort_order - page, page_size - start_time, end_time - time_field (string): field to filter time range on (default: "timestamp")

How it works:
The router fetches distribution analysis using fetch_stablecoin_distribution_analysis from DefiLlammaDataClient with optimized data processing, pre-computed lookups, and efficient percentage calculation. Sorts by total USD for better visualization, then applies filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/ws/distribution_analysis?filters={"chain":"ethereum"}&sort_by=usd&sort_order=desc&page=1&page_size=10&start_time=1719878400000&end_time=1719882000000&time_field=timestamp

Response Structure:
Enhanced table format with headers and distribution data.

Example Response:
json { "headers": [ {"key": "chain", "label": "Blockchain"}, {"key": "stablecoin", "label": "Stablecoin"}, {"key": "market_cap", "label": "Market Cap"}, {"key": "percentage", "label": "Percentage"}, {"key": "change_24h", "label": "24h Change"} ], "rows": [ { "stablecoin": "USDT", "name": "Tether", "chains": [ {"chain": "ethereum", "usd": 50000000000, "percent": 62.5}, {"chain": "tron", "usd": 30000000000, "percent": 37.5} ], "total_usd": 80000000000 } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0, "query_params": { "chains": ["ethereum", "bsc", "tron", "solana", "polygon"], "period": "1d" } }

7. /stablecoins/derivative/ws/24h_volume

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/derivative/ws/24h_volume

Purpose:
Stream 24-hour derivative trading volume.

Upstream Params:
- None required. Aggregates data from multiple markets: Binance, Bybit, OKEx, Deribit, BitMEX.

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by, sort_order, page, page_size

How it works:
The router fetches derivative volume using fetch_derivative_volume from DerivativesSnapshotClient with concurrent processing for multiple markets and enhanced caching. Uses individual market requests and aggregates results, then applies filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/derivative/ws/24h_volume?filters={"market":"binance"}&sort_by=volume&sort_order=desc&page=1&page_size=10

Response Structure:
Enhanced structure with aggregated volume data and details.

Example Response:
json { "results": [ { "title": "24h Derivative Volumes", "value": "1,234,567,890 USD", "subtext": "total volumes across selected derivatives contracts (CoinDesk)", "details": [ { "market": "binance", "instrument": "BTC-USDT-VANILLA-PERPETUAL", "volume": 500000000, "raw": { /* raw API data */ } } ] } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0 }

8. /stablecoins/derivative/ws/btc_open_interest

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/derivative/ws/btc_open_interest

Purpose:
Stream BTC open interest data.

Upstream Params:
- None required. Uses Deribit market data and BTC metadata from CoinGecko.

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by, sort_order, page, page_size

How it works:
The router fetches BTC open interest using fetch_btc_open_interest from DerivativesSnapshotClient with concurrent metadata fetch for BTC information and enhanced caching. Uses CoinDesk API for open interest data and CoinGecko for metadata, then applies filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/derivative/ws/btc_open_interest?filters={"market":"deribit"}&sort_by=open_interest&sort_order=desc&page=1&page_size=10

Response Structure:
Enhanced structure with BTC metadata and open interest details.

Example Response:
json { "results": [ { "title": "Bitcoin Options Open Interest", "value": "123,456,789 USD", "subtext": "total BTC options open interest (Deribit)", "logo": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png", "symbol": "BTC", "details": [ { "source": "CoinDesk", "instrument": "BTC-PERPETUAL", "market": "deribit", "open_interest": 123456789, "last_update": 1719878400, "raw": { /* raw API data */ } } ] } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0 }

9. /stablecoins/ws/comparative_price_timeseries

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/ws/comparative_price_timeseries

Purpose:
Stream comparative price time-series for multiple stablecoins.

Upstream Params:
- stablecoin_ids (comma-separated CoinGecko IDs, default "tether,usd-coin,dai") - vs_currency (string, default "usd") - days (int, default 7) - interval (string, deprecated, not used in current implementation)

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

How it works:
The router fetches comparative price time-series using fetch_stablecoins_comparative_price_timeseries from CoinGeckoClient with batch processing for multiple stablecoins and enhanced caching. Converts data to filterable format for timeframe filtering, applies ws_apply_filters, then reconstructs series data with time sorting.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/ws/comparative_price_timeseries?filters={"stablecoin":"tether"}&sort_by=price&sort_order=desc&page=1&page_size=10&start_time=1719878400000&end_time=1719882000000&timeframe=7d&time_field=time

Response Structure:
Enhanced time series structure with timeframe filtering applied.

Example Response:
json { "y_axis": "Price based on 1 USD (0.98$-1.02$)", "x_axis": "Time (unix timestamp)", "data_series": [ { "stablecoin": "tether", "data": [ {"time": 1712345678, "price": 1.001}, {"time": 1712345688, "price": 0.999} ] }, { "stablecoin": "usd-coin", "data": [ {"time": 1712345678, "price": 1.002}, {"time": 1712345688, "price": 1.000} ] } ], "count": 4, "adaptive_interval": 80, "timestamp": 1640995200.0, "timeframe_applied": "7d", "query_params": { "stablecoin_ids": ["tether", "usd-coin", "dai"], "vs_currency": "usd", "days": 7, "timeframe": "7d", "start_time": 1719878400000, "end_time": 1719882000000 } }

10. /stablecoins/ws/event_logs

Full Endpoint:
ws://<host>/tzone_apis/services/stablecoins/ws/event_logs

Purpose:
Stream de-peg event logs for stablecoins using DefiLlama data.

Upstream Params:
- threshold (float, default 0.01 = 1%) - peg_type (string, default "peggedUSD") - days_back (int, default 7)

Client-side Filters/Search/Sort/Pagination:
- filters (e.g. {"stablecoin":"USDT"}) - search - sort_by (e.g. "severity_score") - sort_order (default "desc") - page, page_size - start_time, end_time - timeframe (e.g. "7d", "24h") - time_field (string): field to filter time range on (default: "timestamp")

How it works:
The router fetches depeg events using fetch_stablecoin_depeg_events and fetch_historical_depeg_events from DefiLlammaDataClient with concurrent execution. Combines current and historical events, deduplicates based on timestamp and stablecoin, sorts by timestamp and severity, then applies filters using ws_apply_filters. Uses query parameters as initial values (no message handling required).

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/stablecoins/ws/event_logs?threshold=0.02&peg_type=peggedUSD&days_back=7&filters={"stablecoin":"USDT"}&sort_by=severity_score&sort_order=desc&page=1&page_size=10&start_time=1719878400000&end_time=1719882000000&time_field=timestamp

Response Structure:
Enhanced table format with event logs and metadata.

Example Response:
json { "headers": [ {"key": "timestamp", "label": "Timestamp"}, {"key": "stablecoin", "label": "Stablecoin"}, {"key": "severity_score", "label": "Severity Score"}, {"key": "depeg_depth", "label": "Depeg Depth"}, {"key": "duration", "label": "Duration"}, {"key": "volume", "label": "Volume"} ], "rows": [ { "timestamp": 1640995200, "stablecoin": "USDT", "name": "Tether", "price": 0.9820, "target_peg": 1.0, "depeg_depth": 0.0180, "depeg_percentage": 1.80, "volume": 83000000000, "severity_score": 123.45, "duration": 60, "logo": "https://logo.clearbit.com/usdt.com", "peg_type": "peggedUSD", "event_type": "current" } ], "count": 1, "adaptive_interval": 80, "timestamp": 1640995200.0, "query_params": { "threshold": 0.02, "peg_type": "peggedUSD", "days_back": 7, "page": 1, "page_size": 10 }, "data_source": "api" }

Additional Notes

• All endpoints use adaptive intervals based on data size (default 80 seconds, adjustable based on result count).
• The filtering system supports both pandas (for large datasets >100 items) and original implementation (for smaller datasets) for optimal performance.
• Enhanced caching with stale-while-revalidate (SWR) pattern: 5 minutes fresh, 15 minutes stale for most endpoints.
• Deduplication support prevents duplicate requests with dedupe_key parameter.
• Concurrent processing used for multiple API calls to improve response times.
• Rate limit handling with fallback to stale cache data when limits are exceeded.
• Automatic garbage collection every 10 requests to manage memory usage.
• Time filtering supports both unix timestamps and shorthand timeframes (e.g., "7d", "24h").
• Mixed type sorting handles numeric strings, percentages, and currency values appropriately.