# 安装与环境

## 支持的平台

- Python **3.12 及以上**，64 位解释器。
- Windows x86_64、Linux x86_64、macOS Apple Silicon arm64。
- SDK 通过平台 wheel 分发，不提供源码安装包；不支持的平台不能依靠下载源码自行编译安装。
- 使用 venv 隔离项目依赖；不要在同一个解释器内混装不同架构的二进制包。

## 安装与检查

```bash
python --version
python -m venv .venv
```

Linux / macOS：

```bash
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install exsdk
python -c "import exsdk; print(exsdk.__version__)"
```

Windows PowerShell：

```powershell
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install exsdk
python -c "import exsdk; print(exsdk.__version__)"
```

本文以 1.1.2 为基准。需要可复现环境时使用 `python -m pip install exsdk==1.1.2`。若无匹配分发包，请检查 Python 版本、系统架构和可用 wheel。

## 设置 Token

在官网使用手机号登录。首次登录自动开通账户，享 15 天专业版体验。进入个人中心 → SDK Token 创建令牌，明文只显示一次。不要将令牌提交到 Git 或写入共享 Notebook。

SDK 构造函数接收一个非空 Token 字符串，可以显式传入。将 `YOUR_TOKEN` 替换为刚刚创建的完整令牌：

```python
from exsdk import ExApi

with ExApi(token="YOUR_TOKEN") as api:
    print(api.query_symbols("FUTURE"))
```

### 可选：通过环境变量传入

`EXSDK_TOKEN` 只是本教程约定的环境变量名，不是 Python 或 SDK 内置变量。SDK 不会自动创建或读取它；下面由你手动设置，再通过自己的 Python 代码读取并传给 `ExApi`。运行脚本的进程必须能够继承该变量；在终端设置后，请在同一个终端运行脚本。

Linux / macOS：

```bash
export EXSDK_TOKEN='替换为自己的令牌'
```

Windows PowerShell：

```powershell
$env:EXSDK_TOKEN = '替换为自己的令牌'
```

Python 显式读取并传入：

```python
import os
from exsdk import ExApi

token = os.environ["EXSDK_TOKEN"]
with ExApi(token=token) as api:
    print(api.query_symbols("FUTURE"))
```

环境变量不存在时，`os.environ["EXSDK_TOKEN"]` 会抛出 `KeyError`，这是本地配置问题，不是 SDK 服务故障。也可以改用自己的变量名，并让设置和读取的名称保持一致。

## 网络与认证前提

SDK 源码的账户认证地址已统一为 `https://skyzhi.com`，认证接口为 `/api/token/verify`，行情服务为 `https://api.skyzhi.com`。本地运行 exweb 并不自动部署这些域名；需要先将主域名部署到本系统，并使用认证地址已更新的 SDK 安装包。本次源码修改尚未发布为新安装包，已安装的旧包需要在新包发布后更新。不要通过修改 SDK 私有变量绕过认证。

行情和 CTP 柜台连接均要求对应网络可达。CTP 的交易前置、AppID、AuthCode、账号和密码由期货公司提供，全部配置在本地，勿提交至官网。