# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.synthdata.co/insights/volatility-old.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.