synth-data

Original source / Raw SKILL.md

---
name: synth-data
description: Query volatility forecasts from Synthdata.co for crypto, commodities, and stocks. Compare assets and run Monte Carlo simulations.
metadata:
  {
    "openclaw":
      {
        "emoji": "📊",
        "requires": { "bins": ["python3"], "env": ["SYNTHDATA_API_KEY"] }
      }
  }
---

# 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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/synth.py

```python
#!/usr/bin/env python3
"""
Synthdata CLI — Query volatility forecasts and price data.

Usage:
    python3 synth.py BTC                        # Single asset
    python3 synth.py BTC ETH SOL --compare      # Compare assets
    python3 synth.py --forecast --chart         # Full forecast with chart
    python3 synth.py BTC --simulate             # 24h Monte Carlo simulation
    python3 synth.py BTC --simulate --hours 12  # 12h simulation
    python3 synth.py --all                      # All assets overview

Note: Synthdata provides 24h forecasts, so simulations are capped at 24 hours.
"""

import os
import sys
import json
import math
import random
import argparse
import urllib.request
from datetime import datetime

API_BASE = "https://api.synthdata.co"
API_KEY = os.environ.get("SYNTHDATA_API_KEY", "")

ASSETS = ["BTC", "ETH", "SOL", "XAU", "SPYX", "NVDAX", "GOOGLX", "TSLAX", "AAPLX"]

ASSET_NAMES = {
    "BTC": "Bitcoin",
    "ETH": "Ethereum",
    "SOL": "Solana",
    "XAU": "Gold",
    "SPYX": "S&P 500",
    "NVDAX": "NVIDIA",
    "GOOGLX": "Google",
    "TSLAX": "Tesla",
    "AAPLX": "Apple"
}


def api_get(endpoint):
    """Fetch from Synthdata API"""
    url = f"{API_BASE}{endpoint}"
    
    try:
        req = urllib.request.Request(url, headers={
            "Authorization": f"Apikey {API_KEY}",
            "User-Agent": "SynthdataSkill/1.0"
        })
        with urllib.request.urlopen(req, timeout=10) as resp:
            return json.loads(resp.read().decode())
    except urllib.error.HTTPError as e:
        return {"error": f"HTTP {e.code}: {e.reason}"}
    except Exception as e:
        return {"error": str(e)}


def get_asset(ticker):
    """Get single asset volatility data"""
    return api_get(f"/insights/volatility?asset={ticker.upper()}")


def get_all_assets():
    """Get all assets"""
    results = {}
    for ticker in ASSETS:
        data = get_asset(ticker)
        if "error" not in data:
            results[ticker] = data
    return results


def format_price(price):
    """Format price with appropriate decimals"""
    if price is None:
        return "N/A"
    if price >= 1000:
        return f"${price:,.0f}"
    elif price >= 1:
        return f"${price:,.2f}"
    else:
        return f"${price:.4f}"


def format_change(change):
    """Format percentage change with emoji"""
    if change is None:
        return "N/A"
    sign = "+" if change >= 0 else ""
    emoji = "🟢" if change >= 0 else "🔴"
    return f"{emoji} {sign}{change:.2f}%"


def vol_level(vol):
    """Categorize volatility level"""
    if vol is None:
        return "Unknown"
    if vol < 20:
        return "Low"
    elif vol < 40:
        return "Moderate"
    elif vol < 60:
        return "Elevated"
    elif vol < 80:
        return "High"
    else:
        return "Extreme"


def vol_emoji(vol):
    """Get emoji for vol level"""
    if vol is None:
        return "⚪"
    if vol < 20:
        return "🟢"
    elif vol < 40:
        return "🟡"
    elif vol < 60:
        return "🟠"
    else:
        return "🔴"


def extract_metrics(data):
    """Extract key metrics from API response"""
    if "error" in data:
        return data
    
    result = {}
    
    # Current price
    result["price"] = data.get("current_price")
    
    # Realized volatility (most recent and average)
    realized = data.get("realized", {})
    vol_array = realized.get("volatility", [])
    if vol_array:
        result["vol_current"] = vol_array[-1]  # Most recent
        result["vol_realized_avg"] = realized.get("average_volatility")
    
    # Calculate 24h change from price data
    prices = realized.get("prices", [])
    if len(prices) >= 24:
        old_price = prices[-24].get("price")
        new_price = prices[-1].get("price")
        if old_price and new_price and old_price > 0:
            result["change_24h"] = ((new_price - old_price) / old_price) * 100
    
    # Forecast volatility
    forecast_future = data.get("forecast_future", {})
    forecast_vol = forecast_future.get("volatility", [])
    if forecast_vol:
        # Filter out None values
        valid_forecast = [v for v in forecast_vol if v is not None]
        if valid_forecast:
            result["vol_forecast_avg"] = forecast_future.get("average_volatility")
            result["vol_forecast_next"] = valid_forecast[0] if valid_forecast else None
    
    return result


def print_asset(ticker, data):
    """Pretty print single asset"""
    print(f"\n{'='*50}")
    print(f"  {ticker} — {ASSET_NAMES.get(ticker, ticker)}")
    print(f"{'='*50}")
    
    if "error" in data:
        print(f"  Error: {data['error']}")
        return
    
    metrics = extract_metrics(data)
    
    price = metrics.get("price")
    change = metrics.get("change_24h")
    vol = metrics.get("vol_current")
    vol_avg = metrics.get("vol_realized_avg")
    forecast_avg = metrics.get("vol_forecast_avg")
    
    print(f"  Price:           {format_price(price)}")
    if change is not None:
        print(f"  24h Change:      {format_change(change)}")
    if vol is not None:
        print(f"  Current Vol:     {vol:.1f}% {vol_emoji(vol)} [{vol_level(vol)}]")
    if vol_avg is not None:
        print(f"  Avg Realized:    {vol_avg:.1f}%")
    if forecast_avg is not None:
        print(f"  Forecast Vol:    {forecast_avg:.1f}%")


def print_comparison(assets_data):
    """Print comparison table"""
    print(f"\n{'Asset':<8} {'Name':<12} {'Price':>12} {'Realized':>10} {'Forecast':>10} {'Level':>10}")
    print("-" * 70)
    
    # Extract metrics and sort by current vol descending
    rows = []
    for ticker, data in assets_data.items():
        if "error" in data:
            continue
        metrics = extract_metrics(data)
        vol = metrics.get("vol_current") or metrics.get("vol_realized_avg") or 0
        rows.append((ticker, data, metrics, vol))
    
    sorted_rows = sorted(rows, key=lambda x: x[3], reverse=True)
    
    for ticker, data, metrics, _ in sorted_rows:
        name = ASSET_NAMES.get(ticker, ticker)[:12]
        price = format_price(metrics.get("price"))
        vol = metrics.get("vol_current")
        forecast = metrics.get("vol_forecast_avg")
        vol_str = f"{vol:.1f}%" if vol else "N/A"
        forecast_str = f"{forecast:.1f}%" if forecast else "N/A"
        level = vol_level(vol)
        emoji = vol_emoji(vol)
        
        print(f"{ticker:<8} {name:<12} {price:>12} {vol_str:>10} {forecast_str:>10} {emoji} {level}")





def monte_carlo(price, vol_annual, hours=24, paths=500):
    """Generate Monte Carlo price paths (hourly steps, max 24h)"""
    if price is None or vol_annual is None:
        return []
    
    # Cap at 24 hours (forecast window)
    hours = min(hours, 24)
    
    vol_decimal = vol_annual / 100
    dt = 1/(365 * 24)  # Hourly time step
    results = []
    
    for _ in range(paths):
        path = [price]
        p = price
        for _ in range(hours):
            drift = 0
            shock = random.gauss(0, 1)
            p = p * math.exp((drift - 0.5 * vol_decimal**2) * dt + vol_decimal * math.sqrt(dt) * shock)
            path.append(p)
        results.append(path)
    
    return results


def monte_carlo_stats(paths):
    """Calculate percentile bands from paths"""
    if not paths:
        return None
    
    days = len(paths[0])
    stats = {"p5": [], "p25": [], "p50": [], "p75": [], "p95": []}
    
    for day in range(days):
        day_prices = sorted([p[day] for p in paths])
        n = len(day_prices)
        stats["p5"].append(day_prices[int(n * 0.05)])
        stats["p25"].append(day_prices[int(n * 0.25)])
        stats["p50"].append(day_prices[int(n * 0.50)])
        stats["p75"].append(day_prices[int(n * 0.75)])
        stats["p95"].append(day_prices[int(n * 0.95)])
    
    return stats





def main():
    parser = argparse.ArgumentParser(description="Synthdata Volatility CLI")
    parser.add_argument("assets", nargs="*", help="Asset tickers (e.g., BTC ETH SOL)")
    parser.add_argument("--all", action="store_true", help="Show all assets")
    parser.add_argument("--compare", action="store_true", help="Compare assets in table")
    parser.add_argument("--forecast", action="store_true", help="Full forecast")
    parser.add_argument("--simulate", action="store_true", help="Monte Carlo simulation")
    parser.add_argument("--hours", type=int, default=24, help="Simulation hours (max 24)")
    parser.add_argument("--paths", type=int, default=500, help="Simulation paths")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    
    args = parser.parse_args()
    
    if not API_KEY:
        print("Error: SYNTHDATA_API_KEY not set")
        print("Export your API key: export SYNTHDATA_API_KEY=your_key_here")
        sys.exit(1)
    
    # Determine which assets to fetch
    if args.all or args.forecast:
        tickers = ASSETS
    elif args.assets:
        tickers = [a.upper() for a in args.assets]
    else:
        parser.print_help()
        sys.exit(0)
    
    # Fetch data
    assets_data = {}
    for ticker in tickers:
        assets_data[ticker] = get_asset(ticker)
    
    # JSON output
    if args.json:
        print(json.dumps(assets_data, indent=2))
        return
    
    # Monte Carlo simulation
    if args.simulate and len(tickers) == 1:
        ticker = tickers[0]
        data = assets_data[ticker]
        if "error" not in data:
            metrics = extract_metrics(data)
            price = metrics.get("price")
            vol = metrics.get("vol_forecast_avg") or metrics.get("vol_current")  # Prefer forecast for simulation
            
            # Cap hours at 24 (forecast window)
            hours = min(args.hours, 24)
            if args.hours > 24:
                print(f"⚠️  Capped to 24h (Synthdata forecast window)")
            
            if price and vol:
                print(f"\n🎲 Monte Carlo Simulation: {ticker}")
                print(f"   Starting Price: {format_price(price)}")
                print(f"   Volatility: {vol:.1f}%")
                print(f"   Hours: {hours}, Paths: {args.paths}")
                
                paths = monte_carlo(price, vol, hours, args.paths)
                stats = monte_carlo_stats(paths)
                
                if stats:
                    print(f"\n   {hours}h Price Ranges:")
                    print(f"   5th percentile:  {format_price(stats['p5'][-1])}")
                    print(f"   25th percentile: {format_price(stats['p25'][-1])}")
                    print(f"   Median:          {format_price(stats['p50'][-1])}")
                    print(f"   75th percentile: {format_price(stats['p75'][-1])}")
                    print(f"   95th percentile: {format_price(stats['p95'][-1])}")
            else:
                print(f"Error: Missing price or volatility data for {ticker}")
        return
    
    # Comparison table
    if args.compare or args.forecast or args.all:
        print_comparison(assets_data)
        return
    
    # Single asset details
    for ticker in tickers:
        print_asset(ticker, assets_data[ticker])


if __name__ == "__main__":
    main()

```

### references/api.md

```markdown
# Synthdata API Reference

## Endpoint

```
GET https://api.synthdata.co/insights/volatility?asset={TICKER}
```

## Authentication

Include API key in header:
```
Authorization: Apikey {YOUR_API_KEY}
```

## Available Assets

| Ticker | Name | Description |
|--------|------|-------------|
| BTC | Bitcoin | Leading cryptocurrency |
| ETH | Ethereum | Smart contract platform |
| SOL | Solana | High-performance blockchain |
| XAU | Gold | Precious metal spot price |
| SPYX | S&P 500 | US large-cap index |
| NVDAX | NVIDIA | AI/GPU semiconductor |
| GOOGLX | Google | Alphabet Inc. |
| TSLAX | Tesla | Electric vehicles |
| AAPLX | Apple | Consumer tech |

## Response Structure

```json
{
  "realized": {
    "prices": [
      { "price": 77132.29, "returns": null },
      { "price": 77172.32, "returns": 0.00052 },
      ...
    ],
    "volatility": [41.62, 82.4, 60.11, ...],
    "average_volatility": 53.36
  },
  "current_price": 77941.58,
  "forecast_past": {
    "volatility": [null, 50.84, 48.33, ...],
    "average_volatility": 52.75
  },
  "forecast_future": {
    "volatility": [null, 40.67, 43.48, ...],
    "average_volatility": 52.21
  }
}
```

## Response Fields

### `realized`
Historical data containing:
- **prices**: Array of `{price, returns}` objects - recent price history with log returns
- **volatility**: Array of realized volatility values (annualized %)
- **average_volatility**: Mean of realized volatility array

### `current_price`
Latest price for the asset.

### `forecast_past`
Model's historical volatility predictions (for backtesting):
- **volatility**: Array of predicted values
- **average_volatility**: Mean prediction

### `forecast_future`
Forward-looking volatility predictions:
- **volatility**: Array of forecast values (next periods)
- **average_volatility**: Mean forecast

## Volatility Interpretation

| Level | Range | Meaning |
|-------|-------|---------|
| Low | < 20% | Stable, low risk |
| Moderate | 20-40% | Normal market conditions |
| Elevated | 40-60% | Above-average movement expected |
| High | 60-80% | Significant price swings likely |
| Extreme | > 80% | Very volatile, high risk |

## Rate Limits

- Free tier: ~1 request/second recommended
- Add delays when fetching multiple assets

## Error Handling

HTTP errors return standard status codes. Check for `error` key in response for API-specific errors.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Synthdata Volatility Skill

Query and analyze volatility forecasts from [Synthdata.co](https://synthdata.co) for crypto, commodities, and stock indices.

## Features

- 📊 Real-time volatility data for 9 assets (BTC, ETH, SOL, XAU, stocks)
- 🎯 Forward-looking volatility forecasts
- 📈 Monte Carlo price simulations
- 📉 Comparison tables with visual charts
- 🔔 Alert-ready thresholds

## Requirements

- Python 3.8+
- Synthdata API key (sign up at synthdata.co)

## Quick Start

```bash
export SYNTHDATA_API_KEY=your_key_here
python3 scripts/synth.py BTC
```

## Commands

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

# Compare multiple assets
python3 scripts/synth.py BTC ETH SOL --compare

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

# Monte Carlo simulation
python3 scripts/synth.py BTC --simulate --hours 24 --chart

# JSON output for integration
python3 scripts/synth.py BTC --json
```

## Example Output

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

## Use Cases

- **Trading**: Use forecast volatility to size positions and set stops
- **Options**: High forecast vol = consider buying options
- **Alerts**: Get notified when volatility spikes
- **Research**: Compare volatility across asset classes
- **Automation**: Daily reports to Slack/Telegram

See `examples/use-cases.md` for detailed integration patterns.

## License

MIT

```

### _meta.json

```json
{
  "owner": "emsin44",
  "slug": "synth-data",
  "displayName": "Synth Data",
  "latest": {
    "version": "1.1.5",
    "publishedAt": 1770914369073,
    "commit": "https://github.com/openclaw/skills/commit/bdd07a76388a2f2415c131f0afda5d8d37cae87d"
  },
  "history": [
    {
      "version": "1.0.3",
      "publishedAt": 1770203134353,
      "commit": "https://github.com/clawdbot/skills/commit/836ebfc891bc232c2ea02b07990a3df379eda032"
    },
    {
      "version": "1.0.2",
      "publishedAt": 1770115056696,
      "commit": "https://github.com/clawdbot/skills/commit/3abdfbe8782394f9e47e69f4b1d94aa321ca1ff6"
    }
  ]
}

```