# 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


---

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