> 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.md).

# Volatility

GET /insights/volatility

### Parameters

| Parameter | Type    | Required | Default | Description                                                                                                 |
| --------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `asset`   | string  | Yes      | —       | Asset symbol: `BTC`, `ETH`, `SOL`, `HYPE`, `XRP`, `XAU`, `WTIOIL`, `SPYX`, `NVDAX`, `GOOGL`, `TSLA`, `AAPL` |
| `horizon` | string  | No       | 24H     | `1h` for short term volatility forecast and `24h` for longer term                                           |
| `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

{% code title="Response (application/json)" %}

```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, ...]
  }
}
```

{% endcode %}

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

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