Narratives

Narratives are thematic groupings of crypto assets such as L1, L2, DeFi, AI Agents, and RWA. This endpoint provides aggregate market data for 30 narratives, detailed constituent coin breakdowns, sparkline time series, and inter-narrative correlation matrices.

List all narratives

Returns an overview of all 30 narratives with aggregate market metrics. No parameters required for the default list mode.

Query parameters

Name
narrative
Type
string
Description
Narrative identifier to fetch detail data for (e.g., defi, l1, ai-agents). When provided, the response includes constituent coins and sparkline data alongside the narrative list.
Name
correlation
Type
string
Description
Set to true to return the inter-narrative correlation matrix instead of narrative data.
Name
timeframe
Type
string
Description
Timeframe for correlation data (e.g., 1M, 3M). Only used when correlation=true. Defaults to 1M.
Name
historical
Type
string
Description
Reserved for historical snapshot mode.
Name
chart
Type
string
Description
Reserved for chart-specific data retrieval.

Response fields

Name
narratives
Type
array
Description
Array of narrative objects. Each includes: id, name, slug, marketCap, volume24h, change1h, change24h, change7d, change30d, change200d, change1y, median1h, median24h, median7d, median30d, median200d, median1y, openInterest, fundingRate, mcapFdvRatio, volMcapRatio, oiMcapRatio, topCoin (object with symbol, image, price, change24h), coinCount, dominance, momentum, sentimentPct, mindsharePct, watchlistUsers, telegramMembers, tvl, dexVolume, protocolRevenue.
Name
totalNarrativeMcap
Type
number
Description
Sum of market caps across all narratives.
Name
basePrices
Type
object
Description
Reference prices for base currencies (BTC, ETH, SOL) used for currency conversion.
Name
updatedAt
Type
string
Description
ISO 8601 timestamp of the last data refresh.

Request

GET

/v1/narratives/data

curl -G https://www.sharpe.ai/api/v1/narratives/data \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "data": {
    "narratives": [
      {
        "id": "defi",
        "name": "DeFi",
        "slug": "defi",
        "marketCap": 98500000000,
        "volume24h": 4200000000,
        "change1h": 0.32,
        "change24h": 2.45,
        "change7d": -1.20,
        "change30d": 8.50,
        "change200d": 45.20,
        "change1y": 120.50,
        "median1h": 0.28,
        "median24h": 2.10,
        "median7d": -0.95,
        "median30d": 7.80,
        "median200d": 42.10,
        "median1y": 115.30,
        "openInterest": 2400000000,
        "fundingRate": 0.0045,
        "mcapFdvRatio": 0.72,
        "volMcapRatio": 0.043,
        "oiMcapRatio": 0.024,
        "topCoin": {
          "symbol": "UNI",
          "image": "https://...",
          "price": 12.45,
          "change24h": 3.20
        },
        "coinCount": 48,
        "dominance": 5.8,
        "momentum": 1.52,
        "sentimentPct": 0,
        "mindsharePct": 0,
        "watchlistUsers": 0,
        "telegramMembers": 0,
        "tvl": 62000000000,
        "dexVolume": 3200000000,
        "protocolRevenue": 15000000
      }
    ],
    "totalNarrativeMcap": 1690000000000,
    "basePrices": {
      "btc": { "usd": 95200 },
      "eth": { "usd": 3420 },
      "sol": { "usd": 185 }
    },
    "updatedAt": "2026-03-28T07:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T07:45:00Z"
  }
}

Get narrative detail

When the narrative parameter is provided, the response is enriched with the constituent coins and a sparkline time series for that narrative.

Response fields

Name
narratives
Type
array
Description
The full list of all narratives with aggregate metrics (same as list mode).
Name
totalNarrativeMcap
Type
number
Description
Sum of market caps across all narratives.
Name
basePrices
Type
object
Description
Reference prices for base currencies (BTC, ETH, SOL).
Name
coins
Type
array
Description
Constituent coins for the selected narrative. Each coin includes id, symbol, name, image, price, marketCap, fdv, volume24h, change1h, change24h, change7d, change30d, change200d, change1y, ath, athDistance, fundingRate, openInterest, sparkline7d.
Name
sparkline
Type
array
Description
Array of [timestamp, value] tuples representing the narrative's market cap over time.
Name
updatedAt
Type
string
Description
ISO 8601 timestamp of the last data refresh.

Request

GET

/v1/narratives/data?narrative=defi

curl -G https://www.sharpe.ai/api/v1/narratives/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d narrative=defi

{
  "data": {
    "narratives": ["...same as list mode..."],
    "totalNarrativeMcap": 1690000000000,
    "basePrices": {
      "btc": { "usd": 95200 },
      "eth": { "usd": 3420 },
      "sol": { "usd": 185 }
    },
    "coins": [
      {
        "id": "uniswap",
        "symbol": "UNI",
        "name": "Uniswap",
        "image": "https://...",
        "price": 12.45,
        "marketCap": 7500000000,
        "fdv": 12500000000,
        "volume24h": 320000000,
        "change1h": 0.45,
        "change24h": 3.20,
        "change7d": -0.85,
        "change30d": 12.40,
        "change200d": 85.20,
        "change1y": 210.50,
        "ath": 44.97,
        "athDistance": -72.32,
        "fundingRate": 0.0032,
        "openInterest": 180000000,
        "sparkline7d": [11.2, 11.8, 12.1, 12.45]
      }
    ],
    "sparkline": [
      [1711584000000, 95200000000],
      [1711670400000, 96800000000],
      [1711756800000, 98500000000]
    ],
    "updatedAt": "2026-03-28T07:30:00Z"
  },
  "meta": {
    "request_id": "req_def456ghi789jklm",
    "timestamp": "2026-03-28T07:45:00Z"
  }
}

Get narrative correlations

Returns a correlation matrix showing how narrative market caps move relative to each other over the specified timeframe. Useful for portfolio diversification analysis.

Query parameters

Name
correlation
Type
string
Description
Must be true to activate correlation mode.
Name
timeframe
Type
string
Description
Lookback period for the correlation calculation. Defaults to 1M.

Response fields

Name
timeframe
Type
string
Description
The timeframe used for the correlation calculation.
Name
labels
Type
string[]
Description
Ordered list of narrative names corresponding to matrix rows and columns.
Name
matrix
Type
number[][]
Description
Square correlation matrix. Values range from -1 (perfect inverse) to 1 (perfect correlation). matrix[i][j] is the correlation between labels[i] and labels[j].

Request

GET

/v1/narratives/data?correlation=true&timeframe=3M

curl -G https://www.sharpe.ai/api/v1/narratives/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d correlation=true \
  -d timeframe=3M

{
  "data": {
    "timeframe": "3M",
    "labels": ["DeFi", "Layer 1", "AI Agents", "RWA"],
    "matrix": [
      [1.00, 0.85, 0.62, 0.41],
      [0.85, 1.00, 0.71, 0.38],
      [0.62, 0.71, 1.00, 0.29],
      [0.41, 0.38, 0.29, 1.00]
    ]
  },
  "meta": {
    "request_id": "req_ghi789jkl012mnop",
    "timestamp": "2026-03-28T07:45:00Z"
  }
}

Read the error reference