Heatmap API

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/v1/heatmap/data

Get 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

Name
mode
Type
string
Description
The grouping mode. One of coins, narratives, ecosystems. Defaults to coins. narratives and ecosystems return one tile per category.
Name
category
Type
string
Description
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.
Name
ex
Type
string
Description
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)

Category	Universe
`top10`, `top20`, `top30`, `top50`	The N largest eligible coins by market cap. `top50` is the default; `top-100` is its legacy alias
`layer-1`	Layer 1 blockchains
`layer-2`	Layer 2 scaling solutions
`decentralized-finance-defi`	DeFi protocols
`meme-token`	Meme tokens
`artificial-intelligence`	AI-related tokens
`ai-agents`	AI agent tokens
`defai`	DeFAI tokens
`gaming`	Gaming and metaverse
`real-world-assets-rwa`	Real-world assets
`depin`	Decentralized physical infrastructure
`non-fungible-tokens-nft`	NFT-related tokens
`privacy-coins`	Privacy coins
`decentralized-perpetuals`	Perpetual DEX tokens
`prediction-markets`	Prediction market tokens
`centralized-exchange-token-cex`	CEX tokens

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.

Request

GET

/v1/heatmap/data

curl -G https://www.sharpe.ai/api/v1/heatmap/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d mode=coins \
  -d category=top20 \
  -d ex=ethereum

Response fields

Top-level data

Name
dots
Type
array
Description
One object per coin (coins mode) or per narrative or ecosystem tile (aggregate modes). Each carries the fields below.
Name
updated_at
Type
string
Description
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.
Name
coverage
Type
object | null
Description
Aggregate category coverage for narratives and ecosystems, or null for coins. Includes status (complete or partial), availableCategories, totalCategories, a ratio from 0 to 1, and emptyCategories: categories fetched with no eligible member, left off the board and not counted as missing.
Name
as_of
Type
object | null
Description
When each non-CoinGecko metric was observed: funding (the funding snapshot behind fundingApr), candle_1h (the last closed hour, behind y.1h, y.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.
Name
eligible
Type
integer | null
Description
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.
Name
excluded
Type
array
Description
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).
Name
omitted
Type
integer | null
Description
Aggregate modes: categories left off because ex removed every member. null in coins mode.

Dot object

Name
id
Type
string
Description
Coin: the CoinGecko coin id, the id ex takes (e.g. bitcoin). Tile: the narrative or ecosystem id.
Name
name
Type
string
Description
Human-readable coin or category name.
Name
symbol
Type
string
Description
Coin: the ticker. Tile: the category's short name.
Name
kind
Type
string
Description
coin, or category for an aggregate tile.
Name
logoUrl
Type
string
Description
URL of the coin's logo. May be absent.
Name
price
Type
number
Description
Coins only: CoinGecko price in USD. May be absent.
Name
marketCap
Type
number
Description
CoinGecko market cap in USD. Tile: the sum over its members.
Name
y
Type
object
Description
Price change in percent, 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).
Name
x
Type
number | null
Description
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.
Name
fundingApr
Type
number | null
Description
Funding, % APR, 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 x 100, joined by coin id; null when no venue lists the coin under its own id. Tile: OI-weighted over its members.
Name
fundingMethod
Type
string | null
Description
Coins only: oi_weighted or median_fallback, how fundingApr was averaged across venues.
Name
fundingVenuesUsed
Type
integer
Description
Coins only: venues behind fundingApr, one primary contract each.
Name
rsi
Type
object
Description
Wilder RSI(14) keyed by candle size 1h, 4h and 1d, from the same perp series as y.1h. Coin: null unless 64 contiguous closed bars end at the matching as_of time. Tile: the median member's RSI.
Name
openInterest
Type
number
Description
Open interest in USD summed across venues by coin id, MEXC excluded. Tile: the sum over its members. Absent when there is none.
Name
openInterestChange24h
Type
number
Description
OI value change (USD), 24h, in percent: 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.
Name
volume24h
Type
number
Description
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.
Name
median
Type
object
Description
Tiles only: the median member's y (1h to 1y), fundingApr and x, beside the tile's weighted values. Each is null under 5 members with a value.
Name
constituents
Type
object
Description
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).

y.1h, y.4h, fundingApr, rsi, median and constituents are rounded: percent and RVOL to 2 dp, RSI to 1 dp, weightCoverage to 3 dp and largest.marketCapShare to 4 dp. A tile's other y windows are 2 dp, as before. Every other field keeps full precision.

Response

{
  "data": {
    "dots": [
      {
        "id": "bitcoin",
        "name": "Bitcoin",
        "symbol": "BTC",
        "kind": "coin",
        "logoUrl": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
        "price": 81484,
        "marketCap": 1637728114831,
        "x": 0.75,
        "y": {
          "1h": 0.12,
          "4h": -0.41,
          "24h": -0.92632,
          "7d": -1.5904,
          "30d": 6.7394,
          "1y": -22.2415,
          "3y": null
        },
        "fundingApr": 6.8,
        "fundingMethod": "oi_weighted",
        "fundingVenuesUsed": 37,
        "rsi": { "1h": 47.3, "4h": 41.8, "1d": 44.6 },
        "openInterest": 29951649559.993732,
        "openInterestChange24h": -1.4671343740983283,
        "volume24h": 22592162057
      }
    ],
    "updated_at": "2026-10-17T12:14:09.840Z",
    "coverage": null,
    "as_of": {
      "funding": "2026-10-17T13:40:00.000Z",
      "candle_1h": "2026-10-17T13:00:00.000Z",
      "candle_4h": "2026-10-17T12:00:00.000Z",
      "candle_1d": "2026-10-17T00:00:00.000Z"
    },
    "eligible": 20,
    "excluded": ["ethereum"],
    "omitted": null
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-10-17T13:45:00Z",
    "elapsed_ms": 12
  }
}

Tile (mode=narratives)

{
  "id": "layer-1",
  "name": "L1",
  "symbol": "L1",
  "kind": "category",
  "marketCap": 2329860676390,
  "x": 0.71,
  "y": {
    "1h": 0.08,
    "4h": null,
    "24h": -2.95,
    "7d": -4.7,
    "30d": 11.82,
    "1y": -39.23,
    "3y": null
  },
  "fundingApr": 5.91,
  "rsi": { "1h": 48.2, "4h": 43, "1d": null },
  "openInterest": 62451015687.07828,
  "openInterestChange24h": -2.059349431151762,
  "volume24h": 41091245345.52,
  "median": {
    "y": { "1h": 0.05, "4h": null, "24h": -3.1, "7d": -6.02, "30d": 4.4, "1y": -51.7 },
    "fundingApr": 3.1,
    "x": 0.82
  },
  "constituents": {
    "m": 159,
    "n": {
      "change1h": 41, "change4h": 3, "change24h": 159, "change7d": 159, "change30d": 158, "change1y": 131,
      "fundingApr": 64, "openInterestChange24h": 61, "rsi1h": 41, "rsi4h": 3, "rsi1d": 0, "rvol": 150
    },
    "weightCoverage": {
      "change1h": 0.962, "change4h": 0.31, "change24h": 1, "change7d": 1, "change30d": 1, "change1y": 0.998,
      "fundingApr": 0.997, "openInterestChange24h": 0.995, "rvol": 0.999
    },
    "largest": { "id": "bitcoin", "symbol": "BTC", "marketCapShare": 0.703 }
  }
}

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.

Metric	Tile value	`null` (or absent) when
Price change, every window	Market-cap-weighted mean of the members' changes, winsorized	The members with a change carry under 50% of the tile's market cap
Funding APR	Open-interest-weighted over the members with funding	They carry under 50% of the tile's open interest
OI value change (USD)	Summed matched OI now over the same sum 24 hours earlier, minus 1	The matched members carry under 50% of the tile's open interest
RSI(14)	The median member's RSI	Fewer than 5 members have a value and those that do hold under half the market cap
RVOL	Summed 24h volume over summed mean prior daily volume, members with 3 or more days of history	They carry under 50% of the tile's 24h volume
Market cap, open interest, volume	The sum over the members	No member has a value
`median` values	The median member	Fewer than 5 members have a value

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.

Colour by	Field	Windows	Scale
Price change	`y`	1h, 4h, 24h, 7d (default), 30d	Centered at 0; full color at the board's p10/p90 magnitude, at least 5 x sqrt(min(hours, 24) / 24) points (1h 1.02, 4h 2.04, 24h and longer 5)
Funding APR	`fundingApr`	none	Centered at 0% APR; full color at ±30% APR
OI value change (USD)	`openInterestChange24h`	none (a 24h change)	Centered at 0; full color at the board's p10/p90 magnitude, at least 5 points
RSI (14)	`rsi`	1H, 4H (default), 1D candles	Centered at 50; full color at 30 and 70
Relative volume	`x`	none (24h)	Colored on log2, so 2x and 0.5x are equally strong

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.

Axis	URL	Options	Field
x	`metric`	`rvol` (default), `mcap`, `oi`, `oichange`	`x`, `marketCap`, `openInterest`, `openInterestChange24h`
y	`tf`	`24h`, `7d` (default), `1m` (30 days)	`y.24h`, `y.7d`, `y.30d`

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