# Cross-Asset Volatility & Risk-Adjusted Return API
> The risk dashboard for the whole multi-asset book — how volatile each asset class is, how much it returned, and how much return it paid per unit of risk, computed live from Yahoo Finance (no key, nothing stored). Return without risk is meaningless; this puts them side by side. For every instrument — equities, bonds, gold, oil, commodities, FX and crypto — it measures the annualised realised volatility (the standard deviation of daily returns, the market's fear gauge), the trailing return, a Sharpe-style risk-adjusted return (return per unit of volatility) and the worst peak-to-trough drawdown over the window. The ranking endpoint returns the universe ranked by whichever you choose — volatility, Sharpe, return or drawdown — so you can see the calmest and wildest assets and who paid the best risk-adjusted return. The asset endpoint returns one instrument's full risk profile. The universe endpoint lists what is covered. The cross-asset volatility / risk-adjusted-return ranking cut — distinct from the crypto-only volatility and risk APIs, the FX-only volatility API and the bring-your-own-series risk-metrics, CAPM and portfolio-optimiser calculators. It ranks live risk across asset classes.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/assetvolatility-api/..."
```

## Pricing
- **Free** (Free) — 760 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 16,900 calls/Mo, 6 req/s
- **Pro** ($35/Mo) — 89,500 calls/Mo, 16 req/s
- **Business** ($81/Mo) — 488,000 calls/Mo, 40 req/s

## Endpoints

### Ranking

#### `GET /v1/ranking` — Multi-asset universe ranked by volatility, Sharpe, return or drawdown

**Parameters:**
- `sort` (query, optional, string) — volatility, sharpe, return or drawdown Example: `sharpe`
- `window` (query, optional, string) — Lookback in days (20-250) Example: `90`
- `class` (query, optional, string) — Filter by class Example: `commodities`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/assetvolatility-api/v1/ranking?sort=sharpe&window=90&class=commodities"
```

**Response:**
```json
{
    "data": {
        "note": "Annualised realised volatility (std of daily log returns x sqrt(252)), trailing return, a Sharpe-style risk-adjusted return (annualised return / annualised volatility, zero risk-free) and the worst drawdown over window_days. sort by volatility (calmest first), sharpe, return or drawdown. Not financial advice.",
        "class": "commodities",
        "assets": [
            {
                "key": "oil",
                "class": "commodities",
                "label": "Crude Oil",
                "vol_regime": "high volatility",
                "observations": 90,
                "sharpe_ratio": 5.65,
                "ann_return_pct": 349.3,
                "max_drawdown_pct": -16.48,
                "total_return_pct": 71.02,
                "ann_volatility_pct": 61.8
            },
            {
                "key": "broad_commodities",
                "class": "commodities",
                "label": "Broad Commodities",
                "vol_regime": "elevated volatility",
                "observations": 90,
                "sharpe_ratio": 3.23,
                "ann_return_pct": 76.7,
                "max_drawdown_pct": -8.96,
                "total_return_pct": 22.56,
                "ann_volatility_pct": 23.8
            },
            {
                "key": "silver",
                "class": "commodities",
                "label": "Silver",
                "vol_regime": "high volatility",
                "observations": 90,
         
…(truncated, see openapi.json for full schema)
```

### Asset

#### `GET /v1/asset` — One instrument full risk profile

**Parameters:**
- `asset` (query, required, string) — Asset key (see /v1/universe) Example: `gold`
- `window` (query, optional, string) — Lookback in days (20-250) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/assetvolatility-api/v1/asset?asset=gold&window=90"
```

**Response:**
```json
{
    "data": {
        "key": "gold",
        "note": "ann_volatility_pct is annualised realised volatility; sharpe_ratio is annualised return divided by annualised volatility (zero risk-free); max_drawdown_pct is the worst peak-to-trough fall over the window. Computed from daily closes.",
        "class": "commodities",
        "label": "Gold",
        "source": "Yahoo Finance",
        "symbol": "GLD",
        "vol_regime": "elevated volatility",
        "window_days": 90,
        "observations": 90,
        "sharpe_ratio": -0.78,
        "ann_return_pct": -24.5,
        "max_drawdown_pct": -23.56,
        "total_return_pct": -9.55,
        "ann_volatility_pct": 31.5
    },
    "meta": {
        "timestamp": "2026-06-12T10:35:16.937Z",
        "request_id": "fcb7a655-4fad-4590-a70d-afd80f527acb"
    },
    "status": "ok",
    "message": "Asset risk profile retrieved successfully",
    "success": true
}
```

### Universe

#### `GET /v1/universe` — Supported instruments

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/assetvolatility-api/v1/universe"
```

**Response:**
```json
{
    "data": {
        "note": "Supported cross-asset instruments. Pass key as asset= to /v1/asset, class=/sort= to /v1/ranking.",
        "count": 18,
        "sorts": [
            "volatility",
            "sharpe",
            "return",
            "drawdown"
        ],
        "assets": [
            {
                "key": "sp500",
                "class": "equities",
                "label": "S&P 500",
                "symbol": "SPY"
            },
            {
                "key": "nasdaq100",
                "class": "equities",
                "label": "Nasdaq 100",
                "symbol": "QQQ"
            },
            {
                "key": "russell2000",
                "class": "equities",
                "label": "Russell 2000",
                "symbol": "IWM"
            },
            {
                "key": "emerging",
                "class": "equities",
                "label": "Emerging Markets",
                "symbol": "EEM"
            },
            {
                "key": "long_treasuries",
                "class": "bonds",
                "label": "Long US Treasuries",
                "symbol": "TLT"
            },
            {
                "key": "ig_credit",
                "class": "bonds",
                "label": "Investment-Grade Credit",
                "symbol": "LQD"
            },
            {
                "key": "high_yield",
                "class": "bonds",
                "label": "High-Yield Credit",
            
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/assetvolatility-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "window is 20-250 days (default 90). sort is volatility (default), sharpe, return or drawdown. Volatility is annualised by sqrt(252); Sharpe uses a zero risk-free rate. Read fresh per call, nothing cached.",
        "sorts": [
            "volatility",
            "sharpe",
            "return",
            "drawdown"
        ],
        "source": "Yahoo Finance daily closes (1y range) across a multi-asset universe, live",
        "classes": [
            "equities",
            "bonds",
            "commodities",
            "fx",
            "crypto",
            "real_estate"
        ],
        "service": "assetvolatility-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/asset": "One instrument's full risk profile (asset=gold, window=90).",
            "GET /v1/ranking": "Multi-asset universe ranked by volatility/sharpe/return/drawdown with headline calmest/most-volatile/best-risk-adjusted (sort=sharpe, class=commodities).",
            "GET /v1/universe": "The supported instruments."
        },
        "description": "Cross-asset volatility & risk-adjusted return — the risk dashboard for the whole multi-asset book, live from Yahoo Finance (no key, nothing stored). ranking returns the universe ranked by volatility, Sharpe, return or drawdown, with the calmest, most-volatile and best risk-adjusted assets. asset returns one instrument's full risk profile (annualised volatility, return, Sharpe, max
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/assetvolatility-api
OpenAPI spec: https://www.oanor.com/api/assetvolatility-api/openapi.json