# ZhenQuant Python SDK v1.0.0

> Status: transitional downloadable SDK reference aligned to the current public factor contract.
>
> Canonical current-entry docs:
> - `/www/wwwroot/www.zhenquant.hk/README.md`
> - `/www/wwwroot/www.zhenquant.hk/docs/README.md`
> - `/www/wwwroot/www.zhenquant.hk/docs/architecture/API_CONTRACT_BASELINE.md`

本文档描述官网可下载 Python SDK 的当前接入方式。它不是统一身份、统一账单、统一 entitlement 或平台控制面真相的定义来源。

## Install

```bash
pip install requests
```

下载单文件 SDK：

```bash
wget https://www.zhenquant.hk/downloads/skills/python-sdk/zhenquant_sdk.py
```

## Quick Start

```python
from zhenquant_sdk import ZhenQuantClient

client = ZhenQuantClient(api_key="zq_live_your_api_key_here")

result = client.factors.calculate(
    factor_code="MACD",
    symbols=["AAPL", "TSLA", "00700.HK"],
    timeframe="1d",
    fast_period=12,
    slow_period=26,
    signal_period=9,
)

print(result)
```

## Contract Baseline

- Current public factor entrypoint: `POST /v1/factors/calculate`
- Current request shape:
  - `factor`
  - `symbols`
  - `params`
  - `timeframe`
  - optional `start_date` / `end_date`
- This SDK uses `X-API-Key` by default for direct server-side calls
- Backend remains compatible with `Authorization: Bearer`, but this SDK does not need to switch headers for normal usage

## Client Initialization

```python
client = ZhenQuantClient(
    api_key="zq_live_xxx",
    base_url="https://www.zhenquant.hk",
    timeout=30,
)
```

如果你在其他环境或同源网关下接入，请将 `base_url` 替换为当前环境域名。

## Factor Calls

### Unified calculate

```python
result = client.factors.calculate(
    factor_code="RSI",
    symbols=["AAPL"],
    timeframe="1d",
    period=14,
)
```

### Convenience helpers

```python
ma = client.calculate_ma(symbols=["AAPL"], period=20)
rsi = client.calculate_rsi(symbols=["AAPL"], period=14)
macd = client.calculate_macd(
    symbols=["AAPL"],
    fast_period=12,
    slow_period=26,
    signal_period=9,
)
```

### Batch execution

```python
results = client.calculate_batch(
    symbols=["AAPL", "TSLA"],
    factor_requests=[
        {"factor_code": "MA", "period": 20},
        {"factor_code": "RSI", "period": 14},
        {
            "factor_code": "MACD",
            "fast_period": 12,
            "slow_period": 26,
            "signal_period": 9,
        },
    ],
)
```

## Health Check

```python
health = client.health_check()
print(health)
```

## Error Handling

```python
from zhenquant_sdk import (
    ZhenQuantClient,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    ZhenQuantError,
)

try:
    result = client.factors.calculate(
        factor_code="MA",
        symbols=["AAPL"],
        timeframe="1d",
        period=20,
    )
except AuthenticationError:
    print("API Key 无效或已过期")
except RateLimitError as error:
    print(f"超过限流，请稍后重试: {error.retry_after}")
except ValidationError as error:
    print(f"参数错误: {error}")
except ZhenQuantError as error:
    print(f"SDK 调用失败: {error}")
```

## Related Links

- 官网: `https://www.zhenquant.hk`
- 文档中心: `https://www.zhenquant.hk/docs`
- API Docs: `https://www.zhenquant.hk/docs/api`
- 下载中心: `https://www.zhenquant.hk/downloads`