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

# Correlation API

> Retrieve NxN correlation matrices for any set of crypto assets and TradFi instruments over configurable time periods.

Compute pairwise Pearson correlation coefficients for any combination of crypto assets and traditional finance instruments. The resulting NxN matrix is built from daily log returns and supports lookback periods from 30 days to 3 years. Use it for portfolio diversification analysis, regime detection, or cross-asset risk monitoring.

***

## Get correlation matrix

`GET /v1/correlation/matrix`

Returns a symmetric correlation matrix for the requested assets and period. The matrix is computed from daily log returns with a minimum data coverage threshold of 80%. Asset pairs with insufficient overlapping data return `null` coefficients.

### Query parameters

**period** `string`

Lookback period. One of `30d`, `90d`, `1y`, `3y`. Defaults to `30d`.

**ids** `string`

Comma-separated asset identifiers. Crypto assets use canonical IDs (e.g., `bitcoin`, `ethereum`, `solana`). TradFi assets use short IDs (e.g., `sp500`, `gold`, `dxy`, `aapl`, `nvda`). Maximum 10 assets. Defaults to `bitcoin,ethereum,solana,sp500,gold`. Ids no source recognises get a row and column with null correlations and are listed in an optional `unresolved` array (partial success); a selection none of whose ids is recognised returns 404 `resource_not_found` naming them.

### Response fields

**assets** `array`

Ordered array of asset metadata matching the matrix dimensions.

**assets\[].id** `string`

Asset identifier (canonical crypto ID or TradFi short ID).

**assets\[].name** `string`

Display name (e.g., `Bitcoin`, `S&P 500`).

**assets\[].symbol** `string`

Ticker symbol (e.g., `BTC`, `SPY`).

**assets\[].type** `string`

`"crypto"` or `"tradfi"`.

**assets\[].logoUrl** `string`

URL to the asset logo, if available.

**matrix** `(number | null)[][]`

NxN array of Pearson correlation coefficients. `matrix[i][j]` is the correlation between `assets[i]` and `assets[j]`. Values are in `[-1, 1]`, or `null` when fewer than 80% of the period's days are present in both series. Self-correlations on the diagonal are `1`, or `null` when the asset has no observations in the period.

**dataPoints** `number[][]`

NxN array of integers. `dataPoints[i][j]` is the number of overlapping daily observations used to compute `matrix[i][j]`. TradFi-only pairs use trading-day counts (≈252/year), so a 90-day period yields fewer points than a crypto-only pair over the same window.

**period** `string`

The period that was applied.

**computedAt** `string`

ISO 8601 timestamp of the last matrix computation, or `null`.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/correlation/matrix \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d period=90d \
  -d ids=bitcoin,ethereum,solana,sp500,gold
```

```ts TypeScript theme={null}
const params = new URLSearchParams({
  period: '90d',
  ids: 'bitcoin,ethereum,solana,sp500,gold',
})
const res = await fetch(
  `https://www.sharpe.ai/api/v1/correlation/matrix?${params}`,
  {
    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/correlation/matrix",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={
        "period": "90d",
        "ids": "bitcoin,ethereum,solana,sp500,gold",
    },
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "assets": [
      {
        "id": "bitcoin",
        "name": "Bitcoin",
        "symbol": "BTC",
        "type": "crypto",
        "logoUrl": "https://assets.sharpe.ai/coins/bitcoin.png"
      },
      {
        "id": "ethereum",
        "name": "Ethereum",
        "symbol": "ETH",
        "type": "crypto",
        "logoUrl": "https://assets.sharpe.ai/coins/ethereum.png"
      },
      {
        "id": "solana",
        "name": "Solana",
        "symbol": "SOL",
        "type": "crypto",
        "logoUrl": "https://assets.sharpe.ai/coins/solana.png"
      },
      {
        "id": "sp500",
        "name": "S&P 500",
        "symbol": "SPY",
        "type": "tradfi",
        "logoUrl": "/tradfi-logos/spy.svg"
      },
      {
        "id": "gold",
        "name": "Gold",
        "symbol": "GLD",
        "type": "tradfi",
        "logoUrl": "/tradfi-logos/gld.svg"
      }
    ],
    "matrix": [
      [1.0,   0.87,  0.82,  0.45,  0.12],
      [0.87,  1.0,   0.91,  0.41, -0.03],
      [0.82,  0.91,  1.0,   0.38, -0.08],
      [0.45,  0.41,  0.38,  1.0,   0.15],
      [0.12, -0.03, -0.08,  0.15,  1.0]
    ],
    "dataPoints": [
      [90, 90, 90, 64, 64],
      [90, 90, 90, 64, 64],
      [90, 90, 90, 64, 64],
      [64, 64, 64, 64, 64],
      [64, 64, 64, 64, 64]
    ],
    "period": "90d",
    "computedAt": "2026-03-28T04:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T12:00:00Z",
    "elapsed_ms": 12
  }
}
```

***

## Available TradFi assets

The following TradFi asset IDs are supported in the `ids` parameter. Crypto assets use their canonical ID (e.g., `bitcoin`, `ethereum`, `solana`, `dogecoin`).

### Indices and commodities

| ID | Name | Symbol |
| - | - | - |
| `sp500` | S\&P 500 | SPY |
| `nasdaq` | Nasdaq 100 | QQQ |
| `gold` | Gold | GLD |
| `dxy` | US Dollar Index | DXY |

### US stocks

| ID | Name | Symbol |
| - | - | - |
| `aapl` | Apple | AAPL |
| `msft` | Microsoft | MSFT |
| `nvda` | NVIDIA | NVDA |
| `tsla` | Tesla | TSLA |
| `amzn` | Amazon | AMZN |
| `googl` | Alphabet | GOOGL |
| `meta` | Meta | META |
| `brk` | Berkshire | BRK.B |
| `jpm` | JPMorgan | JPM |
| `v` | Visa | V |

Additional stocks are available on demand: `amd`, `nflx`, `crm`, `dis`, `ba`, `ko`, `pep`, `wmt`, `cost`, `intc`, `pypl`, `coin`, `mstr`, `pltr`, `uber`, `sq`, `snow`, `sofi`, `hood`, `spot`.

`GET /v1/correlation/matrix?ids=bitcoin,nvda,sp500`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/correlation/matrix \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d period=1y \
  -d ids=bitcoin,nvda,sp500
```

```ts TypeScript theme={null}
const params = new URLSearchParams({
  period: '1y',
  ids: 'bitcoin,nvda,sp500',
})
const res = await fetch(
  `https://www.sharpe.ai/api/v1/correlation/matrix?${params}`,
  {
    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/correlation/matrix",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={
        "period": "1y",
        "ids": "bitcoin,nvda,sp500",
    },
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "assets": [
      {
        "id": "bitcoin",
        "name": "Bitcoin",
        "symbol": "BTC",
        "type": "crypto"
      },
      {
        "id": "nvda",
        "name": "NVIDIA",
        "symbol": "NVDA",
        "type": "tradfi",
        "logoUrl": "/tradfi-logos/nvda.svg"
      },
      {
        "id": "sp500",
        "name": "S&P 500",
        "symbol": "SPY",
        "type": "tradfi",
        "logoUrl": "/tradfi-logos/spy.svg"
      }
    ],
    "matrix": [
      [1.0,  0.52, 0.48],
      [0.52, 1.0,  0.89],
      [0.48, 0.89, 1.0]
    ],
    "dataPoints": [
      [365, 252, 252],
      [252, 252, 252],
      [252, 252, 252]
    ],
    "period": "1y",
    "computedAt": "2026-03-28T04:00:00Z"
  },
  "meta": {
    "request_id": "req_def456ghi789jklm",
    "timestamp": "2026-03-28T12:00:00Z",
    "elapsed_ms": 12
  }
}
```

***

## Interpreting correlation values

| Range | Interpretation |
| - | - |
| 0.8 to 1.0 | Strong positive correlation; assets move together |
| 0.5 to 0.8 | Moderate positive correlation |
| 0.0 to 0.5 | Weak positive correlation |
| -0.5 to 0.0 | Weak negative correlation |
| -0.8 to -0.5 | Moderate negative correlation |
| -1.0 to -0.8 | Strong negative correlation; assets move opposite |

> [!NOTE]
>
> TradFi assets (stocks, indices) only have data on trading days, so `dataPoints` will be lower than crypto pairs for the same period. A 90-day period yields \~64 TradFi data points versus 90 for crypto-only pairs.

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