Metadata-Version: 2.4
Name: nexusquant-sdk
Version: 0.1.0
Summary: NexusQuant strategy provider Python SDK
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Description-Content-Type: text/markdown

# nexusquant-sdk

NexusQuant 量化策略提供者 Python SDK，用于在 NexusQuant 平台上注册、管理量化策略并发送交易信号。

## 安装

```bash
pip install nexusquant-sdk
```

依赖 Python 3.10 及以上版本。

## 快速开始

```python
import nexusquant_sdk as nq

# 登录（首次使用，会打开浏览器完成授权）
nq.auth_login()

# 查看已注册的策略列表
strategies = nq.strategy_list()

# 发送单笔交易信号
nq.strategy_send_signal_single(
    "my_alpha",
    ticker="AAPL",
    direction="buy",    # "buy" 或 "sell"
    price=150.0,
    quantity=100,       # 股数
    order_type="LIMIT", # "MARKET" 或 "LIMIT"
)
```

## 认证

SDK 使用 OAuth 2.0 PKCE 流程完成登录，令牌存储在本地，无需每次重新登录。

```python
nq.auth_login()            # 打开浏览器完成登录，保存令牌到本地
nq.auth_logged_in()        # 检查是否已登录，返回 True/False
nq.auth_refresh()          # 使用 refresh token 刷新 ID token
nq.auth_logout()           # 删除本地令牌，退出登录
nq.auth_credentials_path() # 查看令牌文件的本地路径
```

## 策略管理

```python
# 注册或更新策略
nq.strategy_register("my_alpha", "我的 Alpha 策略", output_unit="SHARE_COUNT")

# 查询策略列表
nq.strategy_list()

# 查询信号历史
nq.strategy_signal_history("my_alpha", limit=20)

# 发送单笔信号
nq.strategy_send_signal_single(
    "my_alpha",
    ticker="AAPL",
    direction="buy",
    price=150.0,
    quantity=100,
    order_type="LIMIT",
)

# 批量发送信号（多路由映射）
nq.strategy_send_signals("my_alpha", {"default": { ... }})

# 从本地 JSON 文件发送信号
nq.strategy_send_signals_from_path("my_alpha", "signals.json")

# 查询订阅者配置快照
nq.strategy_subscriber_config("my_alpha")
```

## 环境变量配置

可通过以下环境变量覆盖默认配置：

| 变量名 | 说明 |
|---|---|
| `NEXUSQUANT_API_ENDPOINT` | API 服务地址（默认：`https://api.nexusquant.co`） |
| `NEXUSQUANT_COGNITO_DOMAIN` | 认证服务域名 |
| `NEXUSQUANT_COGNITO_CLIENT_ID` | OAuth 客户端 ID |
| `NEXUSQUANT_REDIRECT_URI` | OAuth 回调地址（默认：`http://127.0.0.1:8251/callback`） |

## 依赖

- Python 3.10+
- `httpx >= 0.27`
- `platformdirs >= 4.2`
