<div align="center">
  <h1>AKShare One Derivative</h1>
  <p>Standardized Chinese financial market data interface + derivatives analytics engine</p>
  <div>
    <a href="README_zh.md">中文</a> | <strong>English</strong>
  </div>
</div>

Built on [AKShare](https://github.com/akfamily/akshare), **AKShare One Derivative** provides:

- Unified input/output formats across 6 data sources (EastMoney, Sina, XueQiu, SSE, Exchange, AKShare)
- Two-track architecture: **Track A** (data fetching) + **Track B** (derivatives analytics)
- Built-in MCP server with 43 tools for LLM Agent integration
- Covers A-shares, futures, ETF options, and commodity options

## Installation

```bash
pip install akshare-one-derivative

# With MCP server support
pip install akshare-one-derivative[mcp]

# With TA-Lib technical indicators
pip install akshare-one-derivative[talib]
```

Requires Python >= 3.10.

## Quick Start

```python
from akshare_one import get_hist_data, get_realtime_data

# Stock historical data (EastMoney, forward-adjusted)
df = get_hist_data("600000", interval="day", adjust="qfq")

# Futures main contract daily data (Sina)
from akshare_one import get_futures_hist_data
df = get_futures_hist_data(symbol="AG", contract="main", interval="day")

# ETF options chain (Sina)
from akshare_one import get_options_chain
df = get_options_chain(underlying_symbol="510300")

# Commodity options chain (Sina, auto-detect main contract by OI)
from akshare_one import get_commodity_options_chain
df = get_commodity_options_chain(commodity_symbol="黄金期权", contract="main")

# Calculate Greeks (Black-76)
from akshare_one.options_indicators import calculate_greeks
greeks = calculate_greeks(S=3.2, K=3.0, T=0.25, r=0.02, sigma=0.2)

# Historical volatility with Yang-Zhang estimator
from akshare_one.futures_indicators import get_historical_volatility
hv = get_historical_volatility(ohlcv_df, method="yang_zhang", window=20)
```

## API Overview

### Track A — Data Fetching

All functions return standardized `pd.DataFrame` with unified column names.

| Category | Functions | Sources |
|----------|-----------|---------|
| **Stock** | `get_basic_info` `get_hist_data` `get_realtime_data` `get_news_data` | EastMoney, Sina, XueQiu |
| **Financial** | `get_balance_sheet` `get_income_statement` `get_cash_flow` `get_financial_metrics` | Sina, EastMoney |
| **Futures** | `get_futures_hist_data` `get_futures_realtime_data` `get_futures_main_contracts` | Sina |
| **Futures Derived** | `get_futures_basis` `get_futures_roll_yield` `get_futures_position_ranking` `get_futures_warehouse_receipt` `get_futures_inventory` | AKShare |
| **ETF Options** | `get_options_chain` `get_options_realtime` `get_options_expirations` `get_options_hist` | Sina |
| **Options Indicators** | `get_options_greeks` `get_options_risk_indicators` `get_options_value_analysis` `get_commodity_options_iv` | SSE, Exchange |
| **Commodity Options** | `get_commodity_options_contracts` `get_commodity_options_chain` `get_commodity_options_hist` | Sina |
| **Insider** | `get_inner_trade_data` | XueQiu |

### Track B — Derivatives Analytics

Local computation engines operating on Track A data.

**Options Indicators** (`akshare_one.options_indicators`):

| Function | Description |
|----------|-------------|
| `calculate_greeks` | Greeks & theoretical value (Black-76 / BS) |
| `calculate_iv` | Implied volatility solver |
| `get_options_pcr` | Put-Call Ratio (by volume or OI) |
| `get_options_max_pain` | Max Pain strike |
| `get_iv_rank` / `get_iv_percentile` | IV Rank & Percentile (rolling window) |
| `get_iv_smile` | IV smile curve (OTM filtering, real moneyness) |
| `get_iv_term_structure` | ATM IV term structure across expirations |

**Futures Indicators** (`akshare_one.futures_indicators`):

| Function | Description |
|----------|-------------|
| `get_historical_volatility` | HV (close-to-close / Parkinson / Garman-Klass / Yang-Zhang) |
| `get_volatility_cone` | Volatility cone (multi-window percentiles) |
| `get_futures_oi_change` | Open interest change |
| `get_futures_price_oi_divergence` | Price-OI divergence signal |
| `get_futures_vwap` | VWAP |
| `get_futures_term_structure` | Futures term structure (curve slope & level) |
| `get_futures_spread` | Inter-contract spread |
| `get_futures_long_short_ratio` | Long/short ratio from position ranking |

**Technical Indicators** (`akshare_one.indicators`):

34 indicators including SMA, EMA, RSI, MACD, Bollinger Bands, Stochastic, ATR, CCI, ADX, OBV, MFI, SAR, and more. Supports TA-Lib and pure-pandas backends.

## MCP Server

The built-in [MCP](https://modelcontextprotocol.io/) server exposes 43 tools for LLM agents (Claude, GPT, etc.), organized in three categories:

| Category | Prefix | Count | Description |
|----------|--------|-------|-------------|
| Data Fetching | `get_*` | 28 | Track A pass-through, returns `list[dict]` |
| Self-contained Analysis | `compute_*` | 13 | Internally fetches data + computes indicator |
| Pure Math | `calculate_*` | 2 | Greeks calculation & IV solver |

`compute_*` tools are designed for LLM agents — they accept simple params (symbol, date) and handle data fetching internally, so agents never need to pass DataFrames.

### Run the server

```bash
# stdio mode (for Claude Desktop, Cursor, etc.)
uvx --from "akshare-one-derivative[mcp]" akshare-one-derivative

# HTTP mode
uvx --from "akshare-one-derivative[mcp]" akshare-one-derivative --transport http --port 8000
```

### Claude Desktop config

```json
{
  "mcpServers": {
    "akshare-one": {
      "command": "uvx",
      "args": ["--from", "akshare-one-derivative[mcp]", "akshare-one-derivative"]
    }
  }
}
```

## Architecture

```
akshare_one/
├── __init__.py              # Track A public API (28 functions)
├── options_indicators.py    # Track B options (8 functions)
├── futures_indicators.py    # Track B futures (9 functions)
├── indicators.py            # Technical indicators (34 functions)
├── mcp/
│   └── server.py            # FastMCP server (43 tools)
└── modules/
    ├── derivatives/          # Track B engines (Greeks, options, futures)
    ├── historical/           # Stock historical data providers
    ├── realtime/             # Stock realtime data providers
    ├── financial/            # Financial statement providers
    ├── futures/              # Futures data providers (Sina, AKShare)
    ├── options/              # Options data providers (ETF + commodity)
    ├── indicators/           # Technical indicator calculators
    ├── info/                 # Stock info providers
    ├── insider/              # Insider trade providers
    ├── news/                 # News providers
    └── cache.py              # TTL cache (cachetools)
```

All modules follow the **Factory + ABC** pattern: `base.py` (abstract interface) → `factory.py` (registry) → `{source}.py` (implementation).

## Documentation

Full API documentation: https://zwldarren.github.io/akshare-one/

## License

MIT
