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

# Ecosystems API

> Access blockchain ecosystem intelligence data including market caps, TVL, constituent coins, and correlation matrices for 25 ecosystems.

An ecosystem is a blockchain network and the token economy around it, such as Ethereum, Solana, or Arbitrum. This endpoint provides aggregate market data for 25 ecosystems, detailed constituent coin breakdowns, sparkline time series, TVL data via DeFi Llama, and inter-ecosystem correlation matrices.

***

## List all ecosystems

`GET /v1/ecosystems/data`

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

### Query parameters

**ecosystem** `string`

Ecosystem identifier to fetch detail data for (e.g., `ethereum`, `solana`, `arbitrum`). Accepts the config id (`bnb`) or the URL slug (`bnb-chain`); an unknown value returns 400 `invalid_parameter` listing the valid values. When provided, the response includes constituent coins and sparkline data alongside the ecosystem list.

**excludeNative** `string`

Set to `true` to exclude each ecosystem's native token from aggregate calculations. Only applies when `ecosystem` is provided.

**correlation** `string`

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

**timeframe** `string`

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

### Response fields

**ecosystems** `array`

Array of ecosystem objects. Each includes: `id`, `name`, `slug`, nullable market observations (`marketCap`, `volume24h`, the return windows `return1h` … `return1y` and their medians `medianReturn1h` … `medianReturn1y`, `openInterest`, ratios, `tvl`, `marketShare`, and `momentumReturn`), `fundingRate`, `topCoin` (object with `symbol`, `image`, nullable `price`, and nullable `return24h`), `coinCount`, `sentiment`, `mindshare`, and `watchlistUsers`. Returns and shares (`marketShare`, `sentiment`, `mindshare`, each 0 to 1) are fractions: `0.0185` is 1.85%. `marketShare` is the ecosystem's market cap over `totalEcosystemExposureMcap`. Missing upstream observations are `null`, never fabricated zeroes. `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. An ecosystem's constituents are the coins whose home chain it is and that are eligible (a 24h price change, market cap at least $1M, plausible 24h volume at least $100K, CoinGecko data under 48 hours old, and not a stablecoin, wrapped, bridged or staked copy, or tokenized asset); `coinCount`, the detail `coins` list and every aggregate count that one set.

**totalEcosystemMcap** `number | null`

Deduplicated sum of observed constituent market caps, or `null` when no market-cap observations are available.

**basePrices** `object`

Price returns for BTC, ETH, and SOL from CoinGecko, used to re-base ecosystem 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/ecosystems/data \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```ts TypeScript theme={null}
const res = await fetch('https://www.sharpe.ai/api/v1/ecosystems/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/ecosystems/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "ecosystems": [
      {
        "id": "ethereum",
        "name": "Ethereum",
        "slug": "ethereum",
        "marketCap": 420000000000,
        "volume24h": 18500000000,
        "return1h": 0.0042,
        "return24h": 0.0185,
        "return7d": 0.042,
        "return30d": 0.125,
        "return200d": 0.653,
        "return1y": 1.804,
        "medianReturn1h": 0.0038,
        "medianReturn24h": 0.016,
        "medianReturn7d": 0.038,
        "medianReturn30d": 0.112,
        "medianReturn200d": 0.601,
        "medianReturn1y": 1.702,
        "openInterest": 8500000000,
        "fundingRate": 0.0525,
        "mcapFdvRatio": 0.85,
        "volMcapRatio": 0.044,
        "oiMcapRatio": 0.020,
        "tvl": 62000000000,
        "topCoin": {
          "symbol": "ETH",
          "image": "https://...",
          "price": 3420,
          "return24h": 0.0138
        },
        "coinCount": 50,
        "marketShare": 0.248,
        "momentumReturn": 0.0215,
        "sentiment": null,
        "mindshare": null,
        "watchlistUsers": null
      }
    ],
    "totalEcosystemMcap": 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 ecosystem detail

`GET /v1/ecosystems/data?ecosystem={id}`

When the `ecosystem` parameter is provided, the response is enriched with the constituent coins and a sparkline time series for that ecosystem. Use `excludeNative=true` to filter out the native gas token from the coin list and aggregates.

### Response fields

**ecosystems** `array`

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

**totalEcosystemMcap** `number | null`

Deduplicated sum of observed constituent market caps, or `null` when unavailable.

**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 ecosystem. Each coin includes `id`, `symbol`, `name`, `image`, nullable `price`, `marketCap`, `fdv`, `volume24h`, the return windows `return1h` … `return1y`, `ath`, and `fromAth` (the price against the ATH, a fraction: `-0.7232` is 72.32% below it), plus nullable `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%) and `openInterest` (one-sided USD across venues), and `sparkline7d`.

**sparkline** `array`

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

**updatedAt** `string`

ISO 8601 timestamp of the last data refresh.

`GET /v1/ecosystems/data?ecosystem=ethereum`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/ecosystems/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d ecosystem=ethereum \
  -d excludeNative=true
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/ecosystems/data?ecosystem=ethereum&excludeNative=true',
  {
    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/ecosystems/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"ecosystem": "ethereum", "excludeNative": "true"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "ecosystems": ["...same as list mode..."],
    "totalEcosystemMcap": 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, 410000000000],
      [1711670400000, 415000000000],
      [1711756800000, 420000000000]
    ],
    "updatedAt": "2026-03-28T07:30:00Z"
  },
  "meta": {
    "request_id": "req_def456ghi789jklm",
    "timestamp": "2026-03-28T07:45:00Z",
    "elapsed_ms": 12
  }
}
```

***

## Get ecosystem correlations

`GET /v1/ecosystems/data?correlation=true`

Returns a correlation matrix showing how ecosystem market caps move relative to each other over the specified timeframe. Useful for identifying which chains trend together and which offer diversification.

### 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 ecosystem 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/ecosystems/data?correlation=true&timeframe=3M`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/ecosystems/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/ecosystems/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/ecosystems/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": ["Ethereum", "Solana", "Arbitrum", "Base"],
    "matrix": [
      [1.00, 0.78, 0.92, 0.88],
      [0.78, 1.00, 0.70, 0.74],
      [0.92, 0.70, 1.00, 0.85],
      [0.88, 0.74, 0.85, 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.