> For the complete documentation index, see [llms.txt](https://docs.synthdata.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.synthdata.co/insights/volatility-old.md).

# Volatility (old)

```
GET /insights/volatility
```

### Parameters

| Parameter | Type    | Required | Default | Description                                                        |
| --------- | ------- | -------- | ------- | ------------------------------------------------------------------ |
| `asset`   | string  | Yes      | —       | Asset symbol: `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX`          |
| `days`    | integer | No       | 14      | Number of days to aggregate for the meta-leaderboard ranking       |
| `limit`   | integer | No       | 10      | Number of top miners from the meta-leaderboard to use for analysis |

### Headers

| Header          | Required | Description                              |
| --------------- | -------- | ---------------------------------------- |
| `Authorization` | Yes      | API key in format: `Apikey YOUR_API_KEY` |

### Response

The endpoint returns a comprehensive volatility analysis object containing current price, forecasted volatility (both forward and backward-looking), and realized historical volatility with price/return data.

#### Response Schema

```json
{
  "current_price": number,
  "forecast_future": {
    "average_volatility": number,
    "volatility": number[]
  },
  "forecast_past": {
    "average_volatility": number,
    "volatility": number[]
  },
  "realized": {
    "average_volatility": number,
    "prices": [
      {
        "price": number,
        "returns": number
      }
    ],
    "volatility": number[]
  }
}
```

#### Field Descriptions

| Field                                | Type      | Description                                                    |
| ------------------------------------ | --------- | -------------------------------------------------------------- |
| `current_price`                      | number    | Current asset price at time of request                         |
| `forecast_future.average_volatility` | number    | Mean of forward-looking volatility predictions                 |
| `forecast_future.volatility`         | number\[] | Array of predicted future volatility values                    |
| `forecast_past.average_volatility`   | number    | Mean of backward-looking volatility analysis                   |
| `forecast_past.volatility`           | number\[] | Array of historical volatility predictions                     |
| `realized.average_volatility`        | number    | Mean realized volatility over the observation period           |
| `realized.prices`                    | array     | Historical price observations with computed returns            |
| `realized.prices[].price`            | number    | Asset price at observation time                                |
| `realized.prices[].returns`          | number    | Return from previous observation                               |
| `realized.volatility`                | number\[] | Realized volatility values corresponding to price observations |

### Example Request

{% code title="curl" %}

```bash
curl "https://api.synthdata.co/insights/volatility?asset=BTC&days=14&limit=10" \
  -H "Authorization: Apikey YOUR_API_KEY"
```

{% endcode %}

### Example Response

```json
{
  "current_price": 89081.11,
  "forecast_future": {
    "average_volatility": 34.99,
    "volatility": [49.07, 48.54, 48.61, 48.46, 50.86, 52.03, ...]
  },
  "forecast_past": {
    "average_volatility": 36.63,
    "volatility": [54.84, 51.18, 50.89, 50.99, 45.77, 42.86, ...]
  },
  "realized": {
    "average_volatility": 40.66,
    "prices": [
      {"price": 89750.75, "returns": -0.000105},
      {"price": 89741.30, "returns": 0.000275},
      {"price": 89766.00, "returns": 0.001540},
      ...
    ],
    "volatility": [30.17, 55.97, 83.24, 84.78, 137.25, ...]
  }
}
```

### Response Codes

| Code  | Description                               |
| ----- | ----------------------------------------- |
| `200` | Success - returns volatility data         |
| `400` | Bad Request - invalid parameters          |
| `401` | Unauthorized - invalid or missing API key |
| `500` | Internal Server Error                     |

***

## Volatility Percentiles

Get price distribution percentiles over the forecast horizon.

```
GET /insights/volatility-percentiles
```

### Parameters

| Parameter | Type    | Required | Default | Description                                                        |
| --------- | ------- | -------- | ------- | ------------------------------------------------------------------ |
| `asset`   | string  | Yes      | —       | Asset symbol: `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX`          |
| `days`    | integer | No       | 14      | Number of days to aggregate for the meta-leaderboard ranking       |
| `limit`   | integer | No       | 10      | Number of top miners from the meta-leaderboard to use for analysis |

### Response

```json
{
  "current_price": 88996.66,
  "forecast_future": {
    "percentiles": [
      {
        "0.005": 88996.66,
        "0.05": 88996.66,
        "0.2": 88996.66,
        "0.35": 88996.66,
        "0.5": 88996.66,
        "0.65": 88996.66,
        "0.8": 88996.66,
        "0.95": 88996.66,
        "0.995": 88996.66
      },
      {
        "0.005": 88631.35,
        "0.05": 88765.15,
        "0.2": 88879.70,
        "0.35": 88943.39,
        "0.5": 88998.23,
        "0.65": 89055.24,
        "0.8": 89122.30,
        "0.95": 89236.58,
        "0.995": 89359.79
      }
    ]
  },
  "forecast_past": {
    "percentiles": [...]
  },
  "realized": {
    "prices": [...],
    "percentiles": [...]
  }
}
```

#### Field Descriptions

| Field                         | Description                                                     |
| ----------------------------- | --------------------------------------------------------------- |
| `current_price`               | Current asset price                                             |
| `forecast_future.percentiles` | Array of percentile objects, one per time step                  |
| `0.005`, `0.05`, etc.         | Price at that percentile (0.5 = median, 0.95 = 95th percentile) |

### Example

{% code title="python" %}

```python
response = requests.get(
    "https://api.synthdata.co/insights/volatility-percentiles",
    headers={"Authorization": "Apikey YOUR_API_KEY"},
    params={"asset": "BTC"}
)

data = response.json()
percentiles = data['forecast_future']['percentiles']

# Get 95% confidence interval at final time step
final = percentiles[-1]
lower_bound = final['0.05']   # 5th percentile
upper_bound = final['0.95']   # 95th percentile
print(f"24h 90% CI: ${lower_bound:,.0f} - ${upper_bound:,.0f}")
```

{% endcode %}

***

### Use Cases

* Options Pricing: Use `forecast_future.average_volatility` as volatility input for pricing models
* Position Sizing: Scale position sizes inversely with `realized.average_volatility` for risk management
* Regime Detection: Compare `forecast_future` vs `realized` volatility to detect market regime changes
* Volatility Trading: Identify mean-reversion opportunities when forecast significantly deviates from realized
* Backtesting: Use `realized.prices` array to reconstruct historical price paths for strategy validation