Theme:
← Back to all documentation

CoinGecko WebSocket API Documentation (Spot)

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

1. /spot/ws/market

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/market

Purpose:
Retrieve a table of market data for all coins from CoinGecko, with dynamic price change columns based on requested timeframes.

Upstream Params:
- vs_currency (default: "usd") - per_page (default: 250, max: 500) - sparkline (default: True) - price_change_percentage (default: "24h,7d", supports any combination: "1h,24h,7d,30d,1y")

Client-side Filters/Search/Sort/Pagination:
- filters (JSON string): e.g. {"Symbol": "BTC"} - search (string): search string - sort_by (string): field to sort by (e.g. "Market Cap", "24h Change (%)", "7d Change (%)") - sort_order (string): "asc" or "desc" - page (int): page number - page_size (int): items per page

How it works:
The router fetches market data using get_coin_market_data from CoinGecko, 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/spot/ws/market?filters={"Symbol":"BTC"}&sort_by=Market Cap&sort_order=desc&page=1&page_size=20

Response Structure:
A JSON object with headers and rows for the requested coins.
Dynamic columns for each requested timeframe.

Example Response:
json { "headers": [ "Row", "Logo", "Symbol", "Name", "Price", "24h Change (%)", "Market Cap", "24h Volume", "7d Chart", "7d Change (%)" ], "rows": [ [1, "https://...", "BTC", "Bitcoin", 67000.12, 2.34, 1234567890, 987654321, [/* sparkline */], 5.12] ] }

2. /spot/ws/coin-heatmap

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/coin-heatmap?vs_currency=usd

Purpose:
Stream heatmap data for all coins (for visualization).

Upstream Params:
- vs_currency (default: "usd") - per_page (default: 250, max: 500) - page (default: 1) - price_change_percentage (fixed: "24h")

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

How it works:
The router fetches heatmap data using get_coin_heatmap_data from CoinGecko, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/spot/ws/coin-heatmap?filters={"symbol":"BTC"}&sort_by=market_cap&sort_order=desc&page=1&page_size=20

Response Structure:
A JSON list of heatmap items.

Example Response:
json [ { "size": 1234567890, "content": "BTC 2.34%", "symbol": "BTC", "price_change_24h": 2.34, "market_cap": 1234567890, "color": "green" } ]

3. /spot/ws/ticker-tape

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/ticker-tape?coin_ids=bitcoin,ethereum,tether&vs_currency=usd

Purpose:
Stream ticker tape data for a list of coins (for horizontally scrolling bar).

Upstream Params:
- coin_ids (comma-separated, required, max: 50) - vs_currency (default: "usd") - price_change_percentage (fixed: "24h")

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

How it works:
The router fetches ticker tape data using get_ticker_tape_data from CoinGecko, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/spot/ws/ticker-tape?coin_ids=bitcoin,ethereum,tether&search=eth

Response Structure:
A JSON list of ticker tape items.

Example Response:
json [ { "logo": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png", "symbol_pair": "BTC/USD", "price": 67000.12, "change_pct_24h": 2.34, "name": "Bitcoin" } ]

4. /spot/ws/top-gainers

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/top-gainers?vs_currency=usd&per_page=10&price_change_percentage=24h,7d

Purpose:
Stream the top gaining coins by dynamic price change percentage (supports multiple timeframes).

Upstream Params:
- vs_currency (default: "usd") - per_page (default: 10, max: 250) - price_change_percentage (default: "24h", can be "1h,24h,7d,30d,1y")

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by (e.g. "price_change_24h", "price_change_7d"), sort_order, page, page_size

How it works:
The router fetches top gainers using list_top_gainers from CoinGecko, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/spot/ws/top-gainers?sort_by=price_change_24h&sort_order=desc&page=1&page_size=10&price_change_percentage=24h,7d

Response Structure:
A JSON list of top gainers, each with rank and key stats, and dynamic price change fields.

Example Response:
json [ { "rank": 1, "name": "Bitcoin", "logo": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png", "symbol": "BTC", "price": 67000.12, "market_cap": 1234567890, "volume_24h": 987654321, "price_change_24h": 2.34, "price_change_7d": 5.12 } ]

5. /spot/ws/top-losers

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/top-losers?vs_currency=usd&per_page=10&price_change_percentage=24h,7d

Purpose:
Stream the top losing coins by dynamic price change percentage (supports multiple timeframes).

Upstream Params:
- vs_currency (default: "usd") - per_page (default: 10, max: 250) - price_change_percentage (default: "24h", can be "1h,24h,7d,30d,1y")

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by (e.g. "price_change_24h", "price_change_7d"), sort_order, page, page_size

How it works:
The router fetches top losers using list_top_losers from CoinGecko, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/spot/ws/top-losers?sort_by=price_change_24h&sort_order=asc&page=1&page_size=10&price_change_percentage=24h,7d

Response Structure:
A JSON list of top losers, each with rank and key stats, and dynamic price change fields.

Example Response:
json [ { "rank": 1, "name": "SomeCoin", "logo": "https://assets.coingecko.com/coins/images/2/large/somecoin.png", "symbol": "SCN", "price": 0.12, "market_cap": 12345678, "volume_24h": 8765432, "price_change_24h": -15.67, "price_change_7d": -20.12 } ]

6. /spot/ws/most-active

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/most-active?vs_currency=usd&per_page=10&price_change_percentage=24h,7d

Purpose:
Stream the most active coins by 24h trading volume, with dynamic price change fields.

Upstream Params:
- vs_currency (default: "usd") - per_page (default: 10, max: 250) - price_change_percentage (default: "24h", can be "1h,24h,7d,30d,1y")

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by (e.g. "volume_24h", "price_change_24h"), sort_order, page, page_size

How it works:
The router fetches most active coins using list_most_active from CoinGecko, then applies all client-side filters using ws_apply_filters.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/spot/ws/most-active?sort_by=volume_24h&sort_order=desc&page=1&page_size=10&price_change_percentage=24h,7d

Response Structure:
A JSON list of most active coins, each with rank and key stats, and dynamic price change fields.

Example Response:
json [ { "rank": 1, "name": "Bitcoin", "logo": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png", "symbol": "BTC", "price": 67000.12, "market_cap": 1234567890, "volume_24h": 987654321, "price_change_24h": 2.34, "price_change_7d": 5.12 } ]

7. /spot/ws/historical-ohlcv

Full Endpoint:
ws://<host>/tzone_apis/services/spot/ws/historical-ohlcv?coin_id=bitcoin&vs_currency=usd&days=30

Purpose:
Stream historical OHLCV (Open, High, Low, Close, Volume) data for a given coin.

Upstream Params:
- coin_id (required) - vs_currency (default: "usd") - days (default: 30, max: 365)

Client-side Filters/Search/Sort/Pagination:
- filters, search, sort_by (e.g. "timestamp", "volume"), sort_order, 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 OHLCV data using get_historical_ohlcv from CoinGecko, then applies all client-side filters using ws_apply_filters.
Supports CSV export via WebSocket message.

Example Request:
ws://127.0.0.1:8000/tzone_apis/services/spot/ws/historical-ohlcv?coin_id=bitcoin&days=30&page=1&page_size=100&start_time=1719878400000&end_time=1719882000000&time_field=timestamp

Response Structure:
A JSON list of OHLCV data points.

Example Response:
json [ { "timestamp": 1719878400000, "open": 67000.0, "high": 67500.0, "low": 66500.0, "close": 67200.0, "volume": 123456789.0 } ]

Additional Notes