Heatmap

The heatmap endpoint returns a structured snapshot of market performance across asset categories. Use it to build visual heatmaps showing which sectors and assets are outperforming or underperforming.

GET/v1/heatmap/data

Get heatmap data

Returns heatmap dot data for the specified mode and category. Each dot represents an asset with its performance metrics across multiple timeframes. There are 34 valid category slugs: the legacy top-100 slug for the Top 50 universe, 15 narratives, and 18 ecosystems.

Query parameters

Name
mode
Type
string
Description
The grouping mode. One of coins, narratives, ecosystems. Defaults to coins.
Name
category
Type
string
Description
Filter by asset category (only used when mode=coins). Defaults to top-100. See the valid categories table below.

Valid categories (mode=coins)

Category	Description
`top-100`	Top 50 assets by market cap (default)
`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
`decentralized-perpetuals`	Perpetual DEX tokens
`prediction-markets`	Prediction market tokens
`centralized-exchange-token-cex`	CEX tokens

Ecosystem categories are also valid: 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.

When mode is narratives or ecosystems, the category parameter is ignored. The response returns all narratives or ecosystems respectively. The synthetic Top 50 coin universe is available only through mode=coins&category=top-100; it is not included as a narrative.

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=layer-1

Response fields

Top-level data

Name
dots
Type
array
Description
Array of asset objects. Each dot contains the fields below.
Name
updated_at
Type
string
Description
ISO 8601 timestamp when the heatmap cache was last refreshed.
Name
coverage
Type
object | null
Description
Aggregate category coverage for narratives and ecosystems, or null for coins. Includes status (complete or partial), availableCategories, totalCategories, and a ratio from 0 to 1.

Dot object

Name
id
Type
string
Description
Canonical asset ID (e.g., bitcoin, ethereum).
Name
name
Type
string
Description
Human-readable asset name.
Name
symbol
Type
string
Description
Asset ticker symbol.
Name
logoUrl
Type
string
Description
URL to the asset's logo image. May be absent for some assets.
Name
x
Type
number | null
Description
Historical RVOL: current 24-hour volume divided by the asset's own average prior daily volume. Requires at least three positive historical observations and is null when that history is unavailable; cross-sectional turnover is not substituted.
Name
y
Type
object
Description
Performance percentages keyed by timeframe: 24h, 7d, 30d, 1y, 3y. Values may be null if data is unavailable.
Name
marketCap
Type
number
Description
Current market capitalization in USD.
Name
price
Type
number
Description
Current price in USD. May be absent.
Name
volume24h
Type
number
Description
24-hour trading volume in USD. May be absent.

Response

{
  "data": {
    "dots": [
      {
        "id": "bitcoin",
        "name": "Bitcoin",
        "symbol": "BTC",
        "logoUrl": "https://assets.sharpe.ai/coins/bitcoin.png",
        "x": 1.25,
        "y": {
          "24h": 2.34,
          "7d": 5.12,
          "30d": -1.45,
          "1y": 82.30,
          "3y": 145.60
        },
        "marketCap": 1730000000000,
        "price": 87542.30,
        "volume24h": 42500000000
      },
      {
        "id": "ethereum",
        "name": "Ethereum",
        "symbol": "ETH",
        "logoUrl": "https://assets.sharpe.ai/coins/ethereum.png",
        "x": 0.98,
        "y": {
          "24h": 1.87,
          "7d": 3.45,
          "30d": -2.10,
          "1y": 45.20,
          "3y": 78.90
        },
        "marketCap": 390000000000,
        "price": 3245.80,
        "volume24h": 18900000000
      }
    ],
    "updated_at": "2026-03-27T07:40:00Z",
    "coverage": null
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-27T07:45:00Z",
    "elapsed_ms": 12
  }
}

Read the error reference