> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Narratives API

> Access crypto narrative intelligence data including market caps, performance metrics, constituent coins, and correlation matrices for 30 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

`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

**narrative** `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.

**correlation** `string`

Set to `true` to return the inter-narrative correlation matrix instead of narrative data.

**timeframe** `string`

Timeframe for correlation data (e.g., `1M`, `3M`). Only used when `correlation=true`. Defaults to `1M`.

**sort** `string`

List mode only. `-return24h` orders `narratives` by `return24h`, highest first; `return24h` lowest first. A narrative without a 24h return is last either way.

**top** `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.

**bottom** `integer`

List mode only. Adds `bottom`: the N narratives (`1` to `50`) with the lowest `return24h`, lowest first.

### Response fields

**narratives** `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`.

**top** `array`

With `top=N`: the N narratives with the highest `return24h`, highest first. The same objects as in `narratives`.

**bottom** `array`

With `bottom=N`: the N narratives with the lowest `return24h`, lowest first.

**totalNarrativeMcap** `number`

Sum of market caps across all narratives.

**basePrices** `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`.

**updatedAt** `string`

ISO 8601 timestamp of the last data refresh.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/narratives/data \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```ts TypeScript theme={null}
const res = await fetch('https://www.sharpe.ai/api/v1/narratives/data', {
  headers: {
    Authorization: 'Bearer sk_live_your_key_here',
  },
})
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/narratives/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "narratives": [
      {
        "id": "defi",
        "name": "DeFi",
        "slug": "defi",
        "marketCap": 98500000000,
        "volume24h": 4200000000,
        "return1h": 0.0032,
        "return24h": 0.0245,
        "return7d": -0.012,
        "return30d": 0.085,
        "return200d": 0.452,
        "return1y": 1.205,
        "medianReturn1h": 0.0028,
        "medianReturn24h": 0.021,
        "medianReturn7d": -0.0095,
        "medianReturn30d": 0.078,
        "medianReturn200d": 0.421,
        "medianReturn1y": 1.153,
        "openInterest": 2400000000,
        "fundingRate": 0.0525,
        "mcapFdvRatio": 0.72,
        "volMcapRatio": 0.043,
        "oiMcapRatio": 0.024,
        "topCoin": {
          "symbol": "UNI",
          "image": "https://...",
          "price": 12.45,
          "return24h": 0.032
        },
        "coinCount": 48,
        "marketShare": 0.058,
        "momentumReturn": 0.0152,
        "sentiment": 0.624,
        "mindshare": 0.081,
        "watchlistUsers": null,
        "tvl": 62000000000,
        "dexVolume": 3200000000,
        "protocolRevenue": 15000000
      }
    ],
    "totalNarrativeMcap": 1690000000000,
    "basePrices": {
      "btc": { "return1h": -0.0007, "return24h": -0.0249, "return7d": 0.0112, "return30d": 0.0481, "return200d": -0.0963, "return1y": 0.214 },
      "eth": { "return1h": 0.0012, "return24h": -0.0185, "return7d": 0.034, "return30d": 0.0792, "return200d": -0.142, "return1y": 0.0875 },
      "sol": { "return1h": -0.0021, "return24h": -0.031, "return7d": 0.0058, "return30d": 0.023, "return200d": -0.205, "return1y": 0.156 }
    },
    "updatedAt": "2026-03-28T07:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T07:45:00Z",
    "elapsed_ms": 12
  }
}
```

***

## 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

**narratives** `array`

The full list of all narratives with aggregate metrics (same as list mode).

**totalNarrativeMcap** `number`

Sum of market caps across all narratives.

**basePrices** `object`

Price returns for BTC, ETH, and SOL as fractions, in the same shape as list mode.

**coins** `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.

**sparkline** `array`

Array of `[timestamp, value]` tuples representing the narrative's market cap over time.

**updatedAt** `string`

ISO 8601 timestamp of the last data refresh.

`GET /v1/narratives/data?narrative=defi`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/narratives/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d narrative=defi
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/narratives/data?narrative=defi',
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/narratives/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"narrative": "defi"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "narratives": ["...same as list mode..."],
    "totalNarrativeMcap": 1690000000000,
    "basePrices": {
      "btc": { "return1h": -0.0007, "return24h": -0.0249, "return7d": 0.0112, "return30d": 0.0481, "return200d": -0.0963, "return1y": 0.214 },
      "eth": { "return1h": 0.0012, "return24h": -0.0185, "return7d": 0.034, "return30d": 0.0792, "return200d": -0.142, "return1y": 0.0875 },
      "sol": { "return1h": -0.0021, "return24h": -0.031, "return7d": 0.0058, "return30d": 0.023, "return200d": -0.205, "return1y": 0.156 }
    },
    "coins": [
      {
        "id": "uniswap",
        "symbol": "UNI",
        "name": "Uniswap",
        "image": "https://...",
        "price": 12.45,
        "marketCap": 7500000000,
        "fdv": 12500000000,
        "volume24h": 320000000,
        "return1h": 0.0045,
        "return24h": 0.032,
        "return7d": -0.0085,
        "return30d": 0.124,
        "return200d": 0.852,
        "return1y": 2.105,
        "ath": 44.97,
        "fromAth": -0.7232,
        "fundingRate": 0.000045,
        "avgFundingApr": 0.0493,
        "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 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

**correlation** `string`

Must be `true` to activate correlation mode.

**timeframe** `string`

Lookback period for the correlation calculation. Defaults to `1M`.

### Response fields

**timeframe** `string`

The timeframe used for the correlation calculation.

**labels** `string[]`

Ordered list of narrative names corresponding to matrix rows and columns.

**matrix** `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]`.

**coverage** `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.

**availableTimeframes** `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`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/narratives/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d correlation=true \
  -d timeframe=3M
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/narratives/data?correlation=true&timeframe=3M',
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/narratives/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"correlation": "true", "timeframe": "3M"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "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](https://docs.sharpe.ai/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.