Narratives API

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.

GET/v1/narratives/data

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, layer-1, ai-agents). Accepts the config id (dex) or the URL slug (dex-tokens); an unknown value returns 400 invalid_parameter listing the valid values. 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
sort
Type
string
Description
List mode only. -change24h orders narratives by 24h change, highest first; change24h lowest first. A narrative without a 24h change is last either way.
Name
top
Type
integer
Description
List mode only. Adds top: the N narratives (1 to 50) with the highest 24h change, highest first. A narrative without a 24h change is never ranked.
Name
bottom
Type
integer
Description
List mode only. Adds bottom: the N narratives (1 to 50) with the lowest 24h change, lowest first.

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, tvl, dexVolume, protocolRevenue. sentimentPct, mindsharePct, and watchlistUsers are null when the mindshare sync has no measurement for the narrative, never 0. protocolRevenue is 24h protocol revenue in USD from DeFi Llama (dataType=dailyRevenue), not total fees; values stored before 2026-09-26 were fees. openInterest is the constituents' one-sided open interest across every venue, each asset once; fundingRate is their average funding (8-hour-equivalent, open-interest-weighted) annualized, as a fraction a year. dominance is the narrative's market cap over the sum of all narrative market caps; a coin in several narratives counts in each narrative and in that sum, so the shares add up to 100%. dexVolume (and its 24h, 7d and 30d windows) is DEX trading volume from DeFi Llama and is served only for the defi and dex narratives; every other narrative returns null.
Name
top
Type
array
Description
With top=N: the N narratives with the highest 24h change, highest first. The same objects as in narratives.
Name
bottom
Type
array
Description
With bottom=N: the N narratives with the lowest 24h change, lowest first.
Name
totalNarrativeMcap
Type
number
Description
Sum of market caps across all narratives.
Name
basePrices
Type
object
Description
Percent price changes for BTC, ETH, and SOL from CoinGecko, used to re-base narrative performance into BTC, ETH, or SOL terms. Each of btc, eth, and sol holds change1h, change24h, change7d, change30d, change200d, and change1y in percent (-2.49 = -2.49%). There are no USD prices here. basePrices is null when CoinGecko did not return every window for BTC, ETH and SOL; no window reads a fabricated 0.
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"

Response

{
  "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.0525,
        "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": 62.4,
        "mindsharePct": 8.1,
        "watchlistUsers": null,
        "tvl": 62000000000,
        "dexVolume": 3200000000,
        "protocolRevenue": 15000000
      }
    ],
    "totalNarrativeMcap": 1690000000000,
    "basePrices": {
      "btc": { "change1h": -0.07, "change24h": -2.49, "change7d": 1.12, "change30d": 4.81, "change200d": -9.63, "change1y": 21.4 },
      "eth": { "change1h": 0.12, "change24h": -1.85, "change7d": 3.4, "change30d": 7.92, "change200d": -14.2, "change1y": 8.75 },
      "sol": { "change1h": -0.21, "change24h": -3.1, "change7d": 0.58, "change30d": 2.3, "change200d": -20.5, "change1y": 15.6 }
    },
    "updatedAt": "2026-03-28T07:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T07:45:00Z",
    "elapsed_ms": 12
  }
}

GET/v1/narratives/data?narrative={id}

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.

A constituent is an eligible coin among the 250 largest CoinGecko lists for the narrative's category: its price was updated in the last 48 hours, its market cap is at least $1M, its 24h volume (at most 50x its market cap) is at least $100K, and it is not a stablecoin, wrapped, bridged, liquid-staking, tokenized fund, stock or metal token. The Stablecoins narrative keeps its stablecoins; the other conditions still apply. Every aggregate, coinCount and the coins list use the same constituents.

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
Percent price changes for BTC, ETH, and SOL, in the same shape as list mode.
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 (the coin's funding across venues on an 8-hour basis), fundingApr (percent a year), openInterest (one-sided USD across venues), 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

Response

{
  "data": {
    "narratives": ["...same as list mode..."],
    "totalNarrativeMcap": 1690000000000,
    "basePrices": {
      "btc": { "change1h": -0.07, "change24h": -2.49, "change7d": 1.12, "change30d": 4.81, "change200d": -9.63, "change1y": 21.4 },
      "eth": { "change1h": 0.12, "change24h": -1.85, "change7d": 3.4, "change30d": 7.92, "change200d": -14.2, "change1y": 8.75 },
      "sol": { "change1h": -0.21, "change24h": -3.1, "change7d": 0.58, "change30d": 2.3, "change200d": -20.5, "change1y": 15.6 }
    },
    "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.000045,
        "fundingApr": 4.93,
        "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",
    "elapsed_ms": 12
  }
}

GET/v1/narratives/data?correlation=true

Get narrative correlations

Returns a correlation matrix showing how the chain-linked narrative indexes 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].
Name
coverage
Type
object
Description
Actual requested/available boundaries, bucket cadence, point count, usable pair count, and a full, partial, insufficient, or unknown status. Partial matrices are not presented as complete windows in the terminal.
Name
availableTimeframes
Type
string[]
Description
Correlation windows with full boundary coverage. Short windows use 4-hour log returns; windows of 1M or longer use daily log returns.

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

Response

{
  "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",
    "elapsed_ms": 12
  }
}

Read the error reference