Skip to main content
The heatmap endpoint returns the market heatmap: the largest coins, the coins of one narrative or ecosystem, or one tile per narrative or ecosystem. Every coin and tile carries its price change, funding APR, RSI(14), relative volume, open interest and OI value change, and the response says when each was observed.

Get heatmap data

GET /v1/heatmap/data Returns heatmap dots for the mode and universe. category takes 39 ids: top10, top20, top30 and top50, 15 narratives and 20 ecosystems. The legacy top-100 is an alias of top50; aliases such as defi or sol, and every /heatmap/<slug> page slug, resolve to their category. Only eligible coins count, in every mode: a 24h price change, a market cap of at least $1M, plausible 24h spot volume (at most 50x market cap) of at least $100K, CoinGecko data under 48 hours old, and not a stablecoin, wrapped, bridged or staked copy, LP token, tokenized metal, fund, stock, ETF or pre-IPO token.

Query parameters

string
The grouping mode. One of coins, narratives, ecosystems. Defaults to coins. narratives and ecosystems return one tile per category.
string
The coins-mode universe. Defaults to top50. top10 to top50 are the N largest eligible coins by market cap. A narrative or ecosystem id returns its eligible members, of which the 50 largest are served; an ecosystem’s members are the coins whose home chain it is. Ignored when mode is narratives or ecosystems. See the tables below.
string
Comma-separated CoinGecko coin ids to leave out, lower case (bitcoin,ethereum), up to 2,000 characters. Coins mode removes them after the Top N cut and never refills, so category=top10&ex=bitcoin,ethereum returns 8 coins. The aggregate modes rebuild every tile from its members without them; a tile left with no member is dropped and counted in omitted. Ids that applied are listed in excluded; the others are ignored and named in meta.warnings.

Coin universes (mode=coins)

The 20 ecosystem ids return the coins whose home chain it is: ethereum-ecosystem, solana-ecosystem, bitcoin-ecosystem, binance-smart-chain, base-ecosystem, arbitrum-ecosystem, sui-ecosystem, avalanche-ecosystem, tron-ecosystem, hyperliquid-ecosystem, polygon-ecosystem, aptos-ecosystem, optimism-ecosystem, berachain-ecosystem, mantle-ecosystem, starknet-ecosystem, sei-v2-ecosystem, scroll-ecosystem, blast-ecosystem, linea-ecosystem.
When mode is narratives or ecosystems, category is ignored and the response has one tile per narrative or ecosystem. A tile covers every eligible member, not only the 50 a coins-mode request returns. The Top N universes are coins-mode only; they are not tiles.

Response fields

Top-level data

array
One object per coin (coins mode) or per narrative or ecosystem tile (aggregate modes). Each carries the fields below.
string
ISO 8601 timestamp of the heatmap cache behind the CoinGecko fields, open interest, OI value change and RVOL. The cache is rebuilt every three hours; the X-Data-Stale header turns true once this is more than six hours old or missing (X-Freshness-Sla-Seconds: 21600), and X-Data-As-Of repeats it.
object | null
Aggregate category coverage for narratives and ecosystems, or null for coins. Includes status (complete or partial), availableCategories, totalCategories, a ratio from 0 to 1, emptyCategories: categories fetched with no eligible member, left off the board and not counted as missing, and failedCategories: the ids of the categories whose fetch failed at the last refresh (absent on an older cache row).
object | null
When each non-CoinGecko metric was observed: funding (the funding snapshot behind avgFundingApr), candle_1h (the last closed hour, behind returns.1h, returns.4h and rsi.1h), candle_4h (the end of the last closed UTC 4-hour block, behind rsi.4h) and candle_1d (the last UTC midnight, behind rsi.1d). The candle metrics are served while the last closed hour is under two hours old; older, they are null and meta.warnings says so. null on a cache row written before these times existed.
integer | null
Coins mode: the universe’s size before ex. N for a Top N universe; every eligible member for a narrative or ecosystem, of which dots are the 50 largest. null in the aggregate modes.
array
The ex ids that applied: members of this coin universe, or of at least one category in the aggregate modes. Empty when ex is absent or could not be applied (see meta.warnings).
integer | null
Aggregate modes: categories left off because ex removed every member. null in coins mode.

Dot object

string
Coin: the CoinGecko coin id, the id ex takes (e.g. bitcoin). Tile: the narrative or ecosystem id.
string
Human-readable coin or category name.
string
Coin: the ticker. Tile: the category’s short name.
string
coin, or category for an aggregate tile.
string
URL of the coin’s logo. May be absent.
number
Coins only: CoinGecko price in USD. May be absent.
number
CoinGecko market cap in USD. Tile: the sum over its members.
object
Price return as a fraction (0.054 is 5.4%), keyed 1h, 4h, 24h, 7d, 30d, 1y and 3y; each may be null. 24h to 1y are CoinGecko’s changes read at the sync. 1h and 4h are the last closed hour and the last 4 closed hours, ending at as_of.candle_1h, from stored perp candles (Binance, then Bybit, OKX, Hyperliquid, joined by coin id); null for a coin with no such perp series. 3y is always null (CoinGecko has no 3-year window). Tile: the cap-weighted change of its members (see Aggregation rules).
number | null
Relative volume (RVOL). Coin: 24h spot volume divided by the mean of its prior daily volumes (up to 10 days), capped at 10; null under 3 days of positive history. For a coin with $100B or more market cap, a day over 5x its median prior day is left out of the mean, and x is null when today’s volume is. Tile: the members’ summed 24h volume over their summed mean prior daily volume.
number | null
Funding APR, a fraction per year (0.068 is 6.8%), as of as_of.funding. Coin: the funding snapshot’s per-asset 8-hour average (one primary contract per venue, OI-weighted; MEXC carries no weight; the median when too few venues report OI) x 1,095, joined by coin id; null when no venue lists the coin under its own id. Tile: OI-weighted over its members.
string | null
Coins only: oi_weighted or median_fallback, how avgFundingApr was averaged across venues.
integer
Coins only: venues behind avgFundingApr, one primary contract each.
object
Wilder RSI(14) keyed by candle size 1h, 4h and 1d, from the same perp series as returns.1h. Coin: null unless 64 contiguous closed bars end at the matching as_of time. Tile: the median member’s RSI.
number
Open interest in USD summed across venues by coin id, MEXC excluded. Tile: the sum over its members. Absent when there is none.
number
OI value change (USD), 24h, a fraction (-0.0147 is −1.47%): summed USD open interest now over the same contracts’ sum 24 hours earlier, minus 1, across the contracts present at both times (MEXC excluded). It is a change in USD value, so it moves with price as well as positioning. Absent when no contract matches.
number
Spot volume 24h (CoinGecko) in USD, left out when implausible: over 50x market cap, or, for a coin with $100B or more market cap, over 5x its median prior day. Tile: the sum over its members.
object
Tiles only: the median member’s returns (1h to 1y), avgFundingApr and x, beside the tile’s weighted values. Each is null under 5 members with a value.
object
Tiles only: m (the tile’s members), n (members with a value, per metric), weightCoverage (the share of the tile’s weight those members carry, per weighted metric) and largest (the largest member by market cap and its share of the tile’s market cap).
returns.1h, returns.4h, avgFundingApr, rsi, median and constituents are rounded: returns and funding to 4 dp, RVOL to 2 dp, RSI to 1 dp, weightCoverage to 3 dp and largest.marketCapShare to 4 dp. A tile’s other returns windows are 4 dp too. Every other field keeps full precision.
Response
Tile (mode=narratives)

Aggregation rules

A tile’s members are the category’s eligible members (an ecosystem’s are the coins whose home chain it is), minus ex, with a market cap above 0. Every metric and window uses that one set, so each metric reports its own coverage in constituents.n; 1h and 4h cover fewer members than 24h, because only coins with a perp have candles. Tiles are built on every request from the stored member rows and the latest hourly candles, which is how ex and the candle metrics reach them between the three-hourly cache writes. Narratives overlap: a coin in two narratives counts in both tiles, so tiles do not add up to a market total. constituents.largest shows how much of a tile one coin carries. Until the member rows exist (a cache written before them), the aggregate modes serve the stored tiles: as_of is null, excluded is empty and meta.warnings says that ex was not applied.

Pages that read this endpoint

Heatmap

/heatmap draws this endpoint’s answer as a treemap. Its universe select covers the four Top N universes, each narrative and ecosystem, and All narratives or All ecosystems; Exclude takes coin ids (with a “BTC & ETH” preset), applied after the universe and never refilled. Size is Market cap (CoinGecko), Open interest (USD, MEXC excluded), Spot volume 24h (CoinGecko) or Equal area. A coin or tile without the size value is not drawn, stays in the lists and is counted; Open interest and Spot volume are unavailable while fewer than half the board has them.

Scatter

The Market Scatter page (/scatter) plots the same answer: one dot per coin or tile, price change on the y axis against one x metric. It has no endpoint or MCP tool of its own; read its numbers here, through get_heatmap. Its universe (cat) and exclusions (ex) are those of /heatmap. RVOL and OI value change are 24-hour readings, so against them y is fixed at 24h; the URL keeps the chosen window for when x is market cap or open interest. A dot is drawn when it has a change in the y window and an x value (market cap and open interest above 0, for the log axis); the page’s info tip (hover) says how many were not drawn and why. Read the error reference