synth-data

从 Synthdata.co 查询加密货币、商品和股票的波动性预测。比较资产并运行蒙特卡罗模拟。

# Synthdata Volatility Skill

Query and analyze volatility forecasts from Synthdata.co for crypto, commodities, and stock indices.

## Setup

Set your API key:
```bash
export SYNTHDATA_API_KEY=your_key_here
```

## Quick Start

```bash
# Single asset
python3 scripts/synth.py BTC

# Multiple assets comparison
python3 scripts/synth.py BTC ETH SOL --compare

# All assets overview
python3 scripts/synth.py --all

# Monte Carlo simulation (24h max)
python3 scripts/synth.py BTC --simulate --hours 12
```

## Available Assets

| Ticker | Name | Category |
|--------|------|----------|
| BTC | Bitcoin | Crypto |
| ETH | Ethereum | Crypto |
| SOL | Solana | Crypto |
| XAU | Gold | Commodity |
| SPYX | S&P 500 | Index |
| NVDAX | NVIDIA | Stock |
| GOOGLX | Google | Stock |
| TSLAX | Tesla | Stock |
| AAPLX | Apple | Stock |

## Output Example

```
==================================================
  BTC — Bitcoin
==================================================
  Price:           $77,966
  24h Change:      🔴 -0.95%
  Current Vol:     58.4% 🟠 [Elevated]
  Avg Realized:    53.3%
  Forecast Vol:    52.2%
```

## Volatility Levels

| Level | Range | Emoji |
|-------|-------|-------|
| Low | < 20% | 🟢 |
| Moderate | 20-40% | 🟡 |
| Elevated | 40-60% | 🟠 |
| High | 60-80% | 🔴 |
| Extreme | > 80% | 🔴 |

## Use Cases

### 1. Market Overview
```bash
python3 scripts/synth.py --all
```
Get a ranked table of all assets by volatility.

### 2. Trading Signals
- **High forecast → Current low**: Expect volatility spike
- **Low forecast → Current high**: Volatility may decrease
- Use for position sizing and options trading

### 3. Monte Carlo Projections
```bash
python3 scripts/synth.py BTC --simulate --hours 24 --paths 1000
```
Generate probabilistic price ranges using forecast volatility (24h max - Synthdata forecast window).

### 4. Scheduled Reports
Create a cron job for daily Slack/Telegram forecasts (see examples/use-cases.md).

### 5. Risk Alerts
Monitor for assets crossing volatility thresholds and trigger notifications.

## API Reference

See `references/api.md` for full API documentation.

## Direct API Usage

```python
import requests

resp = requests.get(
    "https://api.synthdata.co/insights/volatility",
    params={"asset": "BTC"},
    headers={"Authorization": f"Apikey {API_KEY}"}
)
data = resp.json()

# Key fields:
price = data["current_price"]
realized_vol = data["realized"]["average_volatility"]
forecast_vol = data["forecast_future"]["average_volatility"]
```

## Integration Ideas

- **Polymarket**: Use volatility forecasts to inform up/down market bets
- **Options**: High forecast vol = consider buying options
- **Portfolio**: Rebalance when aggregate volatility spikes
- **Alerts**: Notify when forecast differs significantly from realized

---

## 中文说明

# Synthdata 波动性技能

查询并分析来自 Synthdata.co 的波动性预测，涵盖加密货币、商品和股票指数。

## 设置

设置你的 API 密钥：
```bash
export SYNTHDATA_API_KEY=your_key_here
```

## 快速开始

```bash
# Single asset
python3 scripts/synth.py BTC

# Multiple assets comparison
python3 scripts/synth.py BTC ETH SOL --compare

# All assets overview
python3 scripts/synth.py --all

# Monte Carlo simulation (24h max)
python3 scripts/synth.py BTC --simulate --hours 12
```

## 可用资产

| Ticker | 名称 | 类别 |
|--------|------|------|
| BTC | Bitcoin | 加密货币 |
| ETH | Ethereum | 加密货币 |
| SOL | Solana | 加密货币 |
| XAU | Gold | 商品 |
| SPYX | S&P 500 | 指数 |
| NVDAX | NVIDIA | 股票 |
| GOOGLX | Google | 股票 |
| TSLAX | Tesla | 股票 |
| AAPLX | Apple | 股票 |

## 输出示例

```
==================================================
  BTC — Bitcoin
==================================================
  Price:           $77,966
  24h Change:      🔴 -0.95%
  Current Vol:     58.4% 🟠 [Elevated]
  Avg Realized:    53.3%
  Forecast Vol:    52.2%
```

## 波动性等级

| 等级 | 范围 | 表情 |
|-------|-------|-------|
| 低 | < 20% | 🟢 |
| 中等 | 20-40% | 🟡 |
| 偏高 | 40-60% | 🟠 |
| 高 | 60-80% | 🔴 |
| 极端 | > 80% | 🔴 |

## 使用场景

### 1. 市场概览
```bash
python3 scripts/synth.py --all
```
获取一张按波动性排名的所有资产表格。

### 2. 交易信号
- **预测高 → 当前低**：预期波动性激增
- **预测低 → 当前高**：波动性可能下降
- 用于仓位规模管理和期权交易

### 3. 蒙特卡罗推演
```bash
python3 scripts/synth.py BTC --simulate --hours 24 --paths 1000
```
使用预测波动性生成概率性价格区间（最长 24 小时——Synthdata 的预测窗口）。

### 4. 定时报告
创建一个 cron 任务，用于每日 Slack/Telegram 预测（参见 examples/use-cases.md）。

### 5. 风险警报
监控跨越波动性阈值的资产并触发通知。

## API 参考

完整 API 文档请参见 `references/api.md`。

## 直接调用 API

```python
import requests

resp = requests.get(
    "https://api.synthdata.co/insights/volatility",
    params={"asset": "BTC"},
    headers={"Authorization": f"Apikey {API_KEY}"}
)
data = resp.json()

# Key fields:
price = data["current_price"]
realized_vol = data["realized"]["average_volatility"]
forecast_vol = data["forecast_future"]["average_volatility"]
```

## 集成思路

- **Polymarket**：使用波动性预测为涨/跌市场押注提供依据
- **期权**：预测波动性高 = 考虑买入期权
- **投资组合**：当聚合波动性激增时重新平衡
- **警报**：当预测与已实现值显著偏离时通知