Theme:
← Back to all documentation

DeFi WebSocket API Documentation

This document describes all WebSocket API routers defined in DeFi.
For each API, you will find:
- Full Endpoint address
- Purpose (Explanation)
- How to use it
- Upstream Params (parameters sent to DefiLlama and CoinGecko 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 DefiLlama and CoinGecko, allowing flexible client-side customization of the returned data.

1. /defi/ws/health/tvl

Full Endpoint:
ws://<host>/tzone_apis/services/defi/ws/health/tvl

Purpose:
Stream TVL (Total Value Locked) time-series data for all DeFi, a specific chain, protocol, or protocol+chain.

Upstream Params:
- chain (string, optional): Chain name (e.g., "ethereum") - protocol (string, optional): Protocol slug (e.g., "uniswap") - period (string, default "all"): "1d", "7d", "30d", "90d", "1y", "all"

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"date": 1710000000} - search (string): search string - sort_by (string): field to sort by (e.g. "tvl") - sort_order (string): "asc" or "desc" - page (int): page number - page_size (int): items per page - start_time, end_time - time_field (string): field to filter time range on, e.g. "x" but default is timestamp

How it works:
The router fetches TVL time-series data using fetch_total_value_locked_timeseries from DefiLlammaDataClient, then applies all client-side filters using ws_apply_filters.
You can update filters, search, sort, and pagination live via WebSocket messages.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/defi/ws/health/tvl?chain=ethereum&period=30d&filters={"date":1710000000}&sort_by=tvl&sort_order=desc&page=1&page_size=50&start_time=1719878400000&end_time=1719882000000&time_field=timestamp

Response Structure:
json { "chart": { "x": [timestamp1, timestamp2, ...], "y": [tvl1, tvl2, ...], "y_label": "Total Value Locked (USD)", "x_label": "Time (unix timestamp)", "series_label": "TVL - Ethereum" }, "key_stats": { "latest_tvl": 123456789, "controller": "30d", "chain": "ethereum", "protocol": null } }

2. /defi/ws/health/tvl-by-chain

Full Endpoint:
ws://<host>/tzone_apis/services/defi/ws/health/tvl-by-chain

Purpose:
Stream TVL by chain for a pie chart.

Upstream Params:
- No required upstream params; fetches TVL by chain from DefiLlama.

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

How it works:
The router fetches TVL by chain using fetch_tvl_by_chain_pie from DefiLlammaDataClient, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/defi/ws/health/tvl-by-chain?filters={"chain":"Ethereum"}&sort_by=tvl&sort_order=desc&page=1&page_size=10&start_time=1719878400000&end_time=1719882000000&time_field=timestamp

Response Structure:
json { "labels": ["Ethereum", "BSC", "Polygon", ...], "values": [50000000000, 20000000000, 10000000000, ...], "percent": [62.5, 25.0, 12.5, ...], "total_tvl": 80000000000, "chart_type": "pie", "title": "TVL by Chain" }

3. /defi/ws/rank-protocol/top-protocols

Full Endpoint:
ws://<host>/tzone_apis/services/defi/ws/rank-protocol/top-protocols

Purpose:
Stream top DeFi protocols by TVL or revenue for a sortable table.

Upstream Params:
- by (string, default "tvl"): "tvl" or "revenue" - period (string, default "7d"): "7d" or "30d" (for revenue) - top_n (int, default 10): Number of top protocols to return - chain (string, optional): Filter by chain - data_type (string, default "dailyFees"): "dailyFees", "dailyRevenue", "dailyHoldersRevenue"

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string) - search (string) - sort_by (string) - sort_order (string) - page (int) - page_size (int)

How it works:
The router fetches top protocols using fetch_top_protocols_table from DefiLlammaDataClient, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/defi/ws/rank-protocol/top-protocols?by=revenue&period=30d&top_n=20&chain=ethereum&data_type=dailyRevenue&filters={"category":"Liquid Staking"}&sort_by=revenue24h&sort_order=desc&page=1&page_size=20

Response Structure:
json { "headers": [ {"key": "rank", "label": "Rank"}, {"key": "protocol", "label": "Protocol"}, {"key": "category", "label": "Category"}, {"key": "chains", "label": "Chains"}, {"key": "tvl", "label": "TVL"}, {"key": "fees24h", "label": "24h Fees"}, {"key": "revenue24h", "label": "24h Revenue"}, {"key": "change_1d", "label": "24h Change (%)"} ], "rows": [ { "rank": 1, "protocol": "Lido", "category": "Liquid Staking", "chains": "Ethereum, Polygon", "tvl": 30000000000, "fees24h": 1234567, "revenue24h": 234567, "logo": "https://defillama.com/protocols/lido.png", "slug": "lido", "change_1d": 2.34 } ], "sort_by": "revenue", "period": "30d", "top_n": 20, "chain": "ethereum", "data_type": "dailyRevenue", "title": "Top 20 Protocols by Revenue (24h)" }

4. /defi/ws/yield-opp/yield-aggregator

Full Endpoint:
ws://<host>/tzone_apis/services/defi/ws/yield-opp/yield-aggregator

Purpose:
Stream yield aggregator pools for a searchable/filterable table.

Upstream Params:
- chain (string, optional): Filter by chain (e.g., "Ethereum") - protocol (string, optional): Filter by protocol/project (e.g., "Aave") - asset_search (string, optional): Search by asset/symbol (e.g., "USDC") - apy_min (float, optional): Minimum APY - apy_max (float, optional): Maximum APY - tvl_min (float, optional): Minimum TVL (USD) - tvl_max (float, optional): Maximum TVL (USD) - top_n (int, default 100): Number of top pools to return

Client-side Filters/Search/Sort/Pagination:
- Custom filter logic (filter_yield_pools) for chain, protocol, asset, APY, TVL. - Results are re-ranked and limited after filtering.

How it works:
The router fetches yield aggregator pools using fetch_yield_aggregator_table from DefiLlammaDataClient, then applies all client-side filters using filter_yield_pools.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/defi/ws/yield-opp/yield-aggregator?chain=Ethereum&apy_min=5&top_n=50

Response Structure:
json { "headers": [ {"key": "rank", "label": "Rank"}, {"key": "pool", "label": "Pool"}, {"key": "chain", "label": "Chain"}, {"key": "protocol", "label": "Protocol"}, {"key": "symbol", "label": "Asset"}, {"key": "tvlUsd", "label": "TVL (USD)"}, {"key": "apy", "label": "APY (%)"}, {"key": "apyBase", "label": "Base APY"}, {"key": "apyReward", "label": "Reward APY"}, {"key": "rewardTokens", "label": "Reward Tokens"}, {"key": "underlyingTokens", "label": "Underlying Tokens"}, {"key": "poolMeta", "label": "Meta"}, {"key": "url", "label": "URL"}, {"key": "predictedClass", "label": "Prediction"}, {"key": "predictedProbability", "label": "Prediction Prob."} ], "rows": [ { "rank": 1, "pool": "Aave USDC Pool", "chain": "Ethereum", "protocol": "Aave", "symbol": "USDC", "tvlUsd": 10000000, "apy": 7.2, "apyBase": 5.0, "apyReward": 2.2, "rewardTokens": "AAVE", "underlyingTokens": "USDC", "poolMeta": "Stablecoin Lending", "url": "https://aave.com/pools/usdc", "predictedClass": "Low Risk", "predictedProbability": 0.95 } ], "top_n": 50, "title": "Yield Aggregator Pools" }

Additional Notes