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

Returns heatmap dot data for the specified mode and category. Each dot represents an asset with its performance metrics across multiple timeframes.

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.

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.

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
Description
Relative volume metric (turnover-normalized). Used for the X-axis in heatmap visualizations.
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.

{
  "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"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-27T07:45:00Z"
  }
}

Read the error reference