Pre-shaped tiles for the market heatmap widget — one tile per coin.

Returns the exact tile-list the `/heatmap` page consumes. Each tile has `weight` (positive number for sizing — either 24h volume or aggregate OI) and `changePct` (24h % change, used for colouring). Coins with a null price change are excluded so the colour scale isn't skewed by blanks. Pass `weightBy=oi` for the OI-sized variant.

Query parameters

All query parameters are optional unless marked required.

Response shape

Always wrapped in the standard envelope. Nullable fields are explicitly marked — treat missing numeric data as a real data-source gap, not as an error.

// Wrapped in the standard envelope:
// {
//   data: /* shape below */,
//   meta?: { total?: number; limit?: number; offset?: number; ... }
// }

{
  weightBy: "volume" | "oi";
  tiles: Array<{
    base: string;
    weight: number;
    changePct: number;
    price: number;
    volume24hUsd: number;
    oiTotalUsd: number;
  }>;
}

Example

Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.

curl -sS "http://localhost:3000/api/v1/coins/heatmap?weightBy=volume&limit=50"

{
  "data": {
    "weightBy": "volume",
    "tiles": [
      { "base": "BTC", "weight": 28450000000, "changePct": 1.82, "price": 63180.5, "volume24hUsd": 28450000000, "oiTotalUsd": 24100000000 }
    ]
  },
  "meta": { "total": 1, "weightBy": "volume", "limit": 50 }
}