Skip to main content
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

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

Query parameters

string
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.
string
Set to true to return the inter-narrative correlation matrix instead of narrative data.
string
Timeframe for correlation data (e.g., 1M, 3M). Only used when correlation=true. Defaults to 1M.
string
List mode only. -return24h orders narratives by return24h, highest first; return24h lowest first. A narrative without a 24h return is last either way.
integer
List mode only. Adds top: the N narratives (1 to 50) with the highest return24h, highest first. A narrative without a 24h return is never ranked.
integer
List mode only. Adds bottom: the N narratives (1 to 50) with the lowest return24h, lowest first.

Response fields

array
Array of narrative objects. Each includes: id, name, slug, marketCap, volume24h, return1h, return24h, return7d, return30d, return200d, return1y, medianReturn1h, medianReturn24h, medianReturn7d, medianReturn30d, medianReturn200d, medianReturn1y, openInterest, fundingRate, mcapFdvRatio, volMcapRatio, oiMcapRatio, topCoin (object with symbol, image, price, return24h), coinCount, marketShare, momentumReturn, sentiment, mindshare, watchlistUsers, tvl, dexVolume, protocolRevenue. Returns (return*, medianReturn*, momentumReturn) and shares (marketShare, sentiment, mindshare, each 0 to 1) are fractions: 0.0245 is 2.45%. sentiment, mindshare, 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. marketShare 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 1. momentumReturn is 0.4 × return1h + 0.35 × return24h + 0.25 × return7d, the weights renormalised over the windows present, clamped to ±1. 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.
array
With top=N: the N narratives with the highest return24h, highest first. The same objects as in narratives.
array
With bottom=N: the N narratives with the lowest return24h, lowest first.
number
Sum of market caps across all narratives.
object
Price returns 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 return1h, return24h, return7d, return30d, return200d, and return1y as fractions (-0.0249 = -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.
string
ISO 8601 timestamp of the last data refresh.
Response

Get narrative detail

GET /v1/narratives/data?narrative={id} 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

array
The full list of all narratives with aggregate metrics (same as list mode).
number
Sum of market caps across all narratives.
object
Price returns for BTC, ETH, and SOL as fractions, in the same shape as list mode.
array
Constituent coins for the selected narrative. Each coin includes id, symbol, name, image, price, marketCap, fdv, volume24h, return1h, return24h, return7d, return30d, return200d, return1y, ath, fromAth (the price against the ATH, a fraction: -0.7232 is 72.32% below it), fundingRate (the coin’s funding across venues on an 8-hour basis), avgFundingApr (that funding annualized, a fraction a year: 0.0493 is 4.93%), openInterest (one-sided USD across venues), sparkline7d. The returns are fractions, as in list mode.
array
Array of [timestamp, value] tuples representing the narrative’s market cap over time.
string
ISO 8601 timestamp of the last data refresh.
GET /v1/narratives/data?narrative=defi
Response

Get narrative correlations

GET /v1/narratives/data?correlation=true 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

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

Response fields

string
The timeframe used for the correlation calculation.
string[]
Ordered list of narrative names corresponding to matrix rows and columns.
number[][]
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].
object
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.
string[]
Correlation windows with full boundary coverage. Short windows use 4-hour log returns; windows of 1M or longer use daily log returns.
GET /v1/narratives/data?correlation=true&timeframe=3M
Response
Read the error reference