> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Heatmap API

> Retrieve crypto market heatmap data for asset, narrative, and ecosystem performance with price, volume, breadth, and rotation context.

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

**mode** `string`

The grouping mode. One of `coins`, `narratives`, `ecosystems`. Defaults to `coins`. `narratives` and `ecosystems` return one tile per category.

**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.

**ex** `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)

| 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`.

> [!NOTE]
>
> 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.

```bash cURL theme={null}
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
```

```ts TypeScript theme={null}
const params = new URLSearchParams({
  mode: 'coins',
  category: 'top20',
  ex: 'ethereum',
})
const res = await fetch(
  `https://www.sharpe.ai/api/v1/heatmap/data?${params}`,
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/heatmap/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={
        "mode": "coins",
        "category": "top20",
        "ex": "ethereum",
    },
)
data = resp.json()["data"]
```

***

## Response fields

### Top-level data

**dots** `array`

One object per coin (coins mode) or per narrative or ecosystem tile (aggregate modes). Each carries the fields below.

**updated\_at** `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.

**coverage** `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).

**as\_of** `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.

**eligible** `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.

**excluded** `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`).

**omitted** `integer | null`

Aggregate modes: categories left off because `ex` removed every member. `null` in coins mode.

### Dot object

**id** `string`

Coin: the CoinGecko coin id, the id `ex` takes (e.g. `bitcoin`). Tile: the narrative or ecosystem id.

**name** `string`

Human-readable coin or category name.

**symbol** `string`

Coin: the ticker. Tile: the category's short name.

**kind** `string`

`coin`, or `category` for an aggregate tile.

**logoUrl** `string`

URL of the coin's logo. May be absent.

**price** `number`

Coins only: CoinGecko price in USD. May be absent.

**marketCap** `number`

CoinGecko market cap in USD. Tile: the sum over its members.

**returns** `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).

**x** `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.

**avgFundingApr** `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.

**fundingMethod** `string | null`

Coins only: `oi_weighted` or `median_fallback`, how `avgFundingApr` was averaged across venues.

**fundingVenuesUsed** `integer`

Coins only: venues behind `avgFundingApr`, one primary contract each.

**rsi** `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.

**openInterest** `number`

Open interest in USD summed across venues by coin id, MEXC excluded. Tile: the sum over its members. Absent when there is none.

**oiChange24h** `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.

**volume24h** `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.

**median** `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.

**constituents** `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.

```json Response theme={null}
{
  "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,
        "returns": {
          "1h": 0.0012,
          "4h": -0.0041,
          "24h": -0.0092632,
          "7d": -0.015904,
          "30d": 0.067394,
          "1y": -0.222415,
          "3y": null
        },
        "avgFundingApr": 0.068,
        "fundingMethod": "oi_weighted",
        "fundingVenuesUsed": 37,
        "rsi": { "1h": 47.3, "4h": 41.8, "1d": 44.6 },
        "openInterest": 29951649559.993732,
        "oiChange24h": -0.0146713437409833,
        "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
  }
}
```

```json title="Tile (mode=narratives)" theme={null}
{
  "id": "layer-1",
  "name": "L1",
  "symbol": "L1",
  "kind": "category",
  "marketCap": 2329860676390,
  "x": 0.71,
  "returns": {
    "1h": 0.0008,
    "4h": null,
    "24h": -0.0295,
    "7d": -0.047,
    "30d": 0.1182,
    "1y": -0.3923,
    "3y": null
  },
  "avgFundingApr": 0.0591,
  "rsi": { "1h": 48.2, "4h": 43, "1d": null },
  "openInterest": 62451015687.07828,
  "oiChange24h": -0.0205934943115176,
  "volume24h": 41091245345.52,
  "median": {
    "returns": { "1h": 0.0005, "4h": null, "24h": -0.031, "7d": -0.0602, "30d": 0.044, "1y": -0.517 },
    "avgFundingApr": 0.031,
    "x": 0.82
  },
  "constituents": {
    "m": 159,
    "n": {
      "return1h": 41, "return4h": 3, "return24h": 159, "return7d": 159, "return30d": 158, "return1y": 131,
      "avgFundingApr": 64, "oiChange24h": 61, "rsi1h": 41, "rsi4h": 3, "rsi1d": 0, "rvol": 150
    },
    "weightCoverage": {
      "return1h": 0.962, "return4h": 0.31, "return24h": 1, "return7d": 1, "return30d": 1, "return1y": 0.998,
      "avgFundingApr": 0.997, "oiChange24h": 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](https://www.sharpe.ai/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 | `returns` | 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) (1h 1.02%, 4h 2.04%, 24h and longer 5%) |
| Funding APR | `avgFundingApr` | none | Centered at 0% APR; full color at ±30% APR |
| OI value change (USD) | `oiChange24h` | none (a 24h change) | Centered at 0; full color at the board's p10/p90 magnitude, at least 5% |
| 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](https://www.sharpe.ai/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`, `oiChange24h` |
| y | `tf` | `24h`, `7d` (default), `1m` (30 days) | `returns.24h`, `returns.7d`, `returns.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](https://docs.sharpe.ai/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.