# OMNIAXS 对外接口文档（V1）

## 0. 文档信息
- 文档名称：OMNIAXS External API Specification
- 版本：v1（向后兼容优先）
- 文档日期：2026-04-03
- 对应 PRD：`PRD_v1.1_zh.md`
- 适用对象：机构开发者、系统集成商、量化团队

## 1. API 总览
### 1.1 基础地址
| 环境 | Base URL | 说明 |
|---|---|---|
| Sandbox | `https://sandbox-api.omniaxs.com` | 联调与测试，不可用于真实交易 |
| Production | `https://api.omniaxs.com` | 生产环境 |

### 1.2 协议与格式
1. 协议：HTTPS（TLS1.2+）。
2. 数据格式：`application/json; charset=utf-8`。
3. 时间格式：ISO8601 UTC（示例：`2026-04-03T10:15:22.345Z`）。
4. 数值：价格与数量使用字符串承载高精度 decimal（避免浮点误差）。

### 1.3 版本策略
1. 统一前缀：`/v1`。
2. 非破坏性字段新增不视为破坏性变更。
3. 破坏性变更通过 `/v2` 发布，不在 `/v1` 中直接替换。

### 1.4 接口域划分（前台/后台）
1. Public 接口：官网漏斗与留资，路径前缀 ` /public/v1/* `。
2. Partner 接口：机构用户正式 API（行情、交易、接入申请），路径前缀 ` /v1/* `。
3. Internal Admin 接口：后台审批、交易所凭证管理、自动接入编排，路径前缀 ` /internal/v1/admin/* `。

### 1.5 多语言支持（新增强制）
1. 支持语言：`zh-CN`、`en-US`、`ja-JP`。
2. 请求头：客户端可通过 `Accept-Language` 指定期望语言。
3. 默认语言：`en-US`。
4. 回退策略：不支持或缺失翻译时，回退到 `en-US`。
5. 响应头：服务端返回 `Content-Language` 标识实际使用语言。

## 2. 鉴权与签名
### 2.1 请求头
所有私有接口（`/v1/*`，不含 `/public/*`）必须带以下头：

| Header | 必填 | 说明 |
|---|---|---|
| `X-PM-API-KEY` | 是 | API Key |
| `X-PM-TIMESTAMP` | 是 | Unix 毫秒时间戳 |
| `X-PM-SIGNATURE` | 是 | HMAC-SHA256 签名 |
| `Content-Type` | 是 | `application/json` |
| `Idempotency-Key` | 写接口必填 | 幂等键（建议 UUIDv7） |
| `Accept-Language` | 否 | 期望语言：`zh-CN/en-US/ja-JP` |

Internal Admin 接口额外要求：
| Header | 必填 | 说明 |
|---|---|---|
| `Authorization` | 是 | `Bearer <admin_jwt>` |
| `X-PM-ROLE` | 是 | 管理角色标识（如 `ops_admin`） |
| `Accept-Language` | 否 | 后台界面语言：`zh-CN/en-US/ja-JP` |

### 2.2 签名规则
1. `canonical_string` 结构：
```text
{timestamp}\n{method_upper}\n{path}\n{query_string}\n{sha256(body)}
```
2. `query_string` 必须按 key 字典序编码，空则为 `""`。
3. body 为空时，`sha256(body)` 对空字符串计算。
4. `signature = hex(hmac_sha256(api_secret, canonical_string))`。

### 2.3 时间窗与重放保护
1. 默认时间窗：请求时间与服务器时间偏差不得超过 30 秒。
2. 超时返回：`401 AUTH_TIMESTAMP_EXPIRED`。
3. 可选增强：启用 `X-PM-NONCE` 做一次性随机串防重放。

## 3. 通用响应结构
### 3.1 成功响应
```json
{
  "success": true,
  "data": {},
  "trace_id": "trc_01JQ..."
}
```

### 3.2 失败响应
```json
{
  "success": false,
  "error": {
    "code": "RISK_NET_EXPOSURE_EXCEEDED",
    "message": "Net exposure limit exceeded",
    "message_i18n_key": "error.risk.net_exposure_exceeded",
    "retryable": false,
    "upstream_code": null,
    "details": null
  },
  "trace_id": "trc_01JQ..."
}
```

说明：
1. `message` 会根据 `Accept-Language` 返回对应语言文案。
2. `message_i18n_key` 提供稳定的国际化键值，便于客户端本地映射。

### 3.3 分页规范
分页接口统一参数：
1. `page_size`：默认 50，最大 500。
2. `page_token`：游标。

响应分页对象：
```json
{
  "items": [],
  "next_page_token": "eyJvZmZzZXQiOjUwfQ=="
}
```

## 4. 限流、幂等与重试
### 4.1 限流头
| Header | 说明 |
|---|---|
| `X-RateLimit-Limit` | 当前窗口总额度 |
| `X-RateLimit-Remaining` | 当前窗口剩余额度 |
| `X-RateLimit-Reset` | 窗口重置时间戳（秒） |

超限返回 `429 RATE_LIMITED`。

### 4.2 幂等规则
1. 所有写操作必须带 `Idempotency-Key`。
2. 相同 key + 相同 payload：返回首次结果。
3. 相同 key + 不同 payload：`409 IDEMPOTENCY_CONFLICT`。
4. 幂等窗口：24 小时。

### 4.3 重试建议
1. `retryable=true` 可指数退避重试（`200ms, 500ms, 1s, 2s`）。
2. 遇到 `429` 必须遵守 `Retry-After`。
3. `RISK_*`、参数类错误禁止重试。

## 5. 错误码
| 错误码 | HTTP | retryable | 说明 |
|---|---|---|---|
| `AUTH_INVALID_KEY` | 401 | false | API Key 无效 |
| `AUTH_INVALID_SIGNATURE` | 401 | false | 签名错误 |
| `AUTH_TIMESTAMP_EXPIRED` | 401 | false | 时间戳过期 |
| `AUTH_SCOPE_DENIED` | 403 | false | 权限不足 |
| `GEOFENCE_BLOCKED` | 403 | false | 地理围栏限制 |
| `LOCALE_UNSUPPORTED` | 400 | false | 不支持的语言参数 |
| `VALIDATION_FAILED` | 422 | false | 参数校验失败 |
| `IDEMPOTENCY_CONFLICT` | 409 | false | 幂等键重复但请求体不一致 |
| `RATE_LIMITED` | 429 | true | 平台限流 |
| `RATE_LIMITED_UPSTREAM` | 503 | true | 上游限流 |
| `MARKET_SESSION_CLOSED` | 409 | false | 非交易时段 |
| `RISK_MARGIN_INSUFFICIENT` | 409 | false | 保证金不足 |
| `RISK_NET_EXPOSURE_EXCEEDED` | 409 | false | 净敞口超限 |
| `ACCESS_NOT_PROVISIONED` | 409 | false | 尚未完成审批或交易所绑定未生效 |
| `ORDER_NOT_FOUND` | 404 | false | 订单不存在 |
| `CONNECTOR_UNAVAILABLE` | 503 | true | 连接器不可用 |
| `UPSTREAM_TIMEOUT` | 504 | true | 上游超时 |
| `INTERNAL_ERROR` | 500 | true | 未分类系统错误 |

## 6. REST 接口定义

## 6.1 Public 接口（官网漏斗）
### 6.1.1 `POST /public/v1/waitlist`
提交 Waitlist 留资。

请求体：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `work_email` | string(email) | 是 | 工作邮箱 |
| `contact_handle` | string | 否 | WhatsApp/Telegram/X |
| `country_region` | string | 是 | 国家或地区 |
| `institution_type` | string | 否 | 机构类型 |
| `preferred_language` | string | 否 | `zh-CN/en-US/ja-JP`，默认 `en-US` |
| `consent` | boolean | 是 | 同意条款 |
| `utm_source` | string | 否 | UTM 来源 |
| `utm_campaign` | string | 否 | UTM 活动 |

请求示例：
```json
{
  "work_email": "ops@alphafund.io",
  "contact_handle": "@alpha_ops",
  "country_region": "SG",
  "institution_type": "quant_fund",
  "preferred_language": "ja-JP",
  "consent": true,
  "utm_source": "x",
  "utm_campaign": "global-hub-launch"
}
```

成功响应：
```json
{
  "success": true,
  "data": {
    "lead_id": "ld_01JQ9M2...",
    "message": "Submitted successfully",
    "estimated_contact_time_hours": 24
  },
  "trace_id": "trc_01JQ..."
}
```

错误：`422 VALIDATION_FAILED`、`403 GEOFENCE_BLOCKED`。

### 6.1.2 用户认证（注册验证码 + 登录 OTP）
用户认证采用两段式流程：
1. 注册后邮箱验证码激活：`register -> verify-email`。
2. 登录时密码校验通过后，再验证邮箱一次性验证码（OTP）：`login -> login/verify-otp`。

用户认证相关端点：
1. `POST /public/v1/auth/register`
2. `POST /public/v1/auth/resend-verification`
3. `POST /public/v1/auth/verify-email`
4. `POST /public/v1/auth/login`（仅发起登录挑战，返回 `challenge_id`）
5. `POST /public/v1/auth/login/resend-otp`
6. `POST /public/v1/auth/login/verify-otp`（验证 OTP 并签发 Access/Refresh Token）
7. `POST /public/v1/auth/refresh`

登录挑战响应示例（`POST /public/v1/auth/login`）：
```json
{
  "success": true,
  "data": {
    "email": "ops@alphafund.io",
    "challenge_id": "ulog_01JQ...",
    "otp_required": true,
    "otp_expires_at": "2026-04-07T10:12:33.200Z"
  },
  "trace_id": "trc_01JQ..."
}
```

OTP 验证成功响应示例（`POST /public/v1/auth/login/verify-otp`）：
```json
{
  "success": true,
  "data": {
    "access_token": "<jwt>",
    "refresh_token": "<jwt>",
    "token_type": "Bearer",
    "session_id": "sess_01JQ...",
    "user": {
      "user_id": "usr_01JQ...",
      "tenant_id": "tenant_01JQ...",
      "email": "ops@alphafund.io",
      "status": "active",
      "email_verified": true
    }
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.1.3 管理员认证（注册验证码 + 登录 OTP）
管理员同样采用“两段登录”：
1. 注册管理员并完成邮箱验证码激活。
2. 管理员登录时先校验密码，再校验邮箱 OTP，成功后签发管理员 Bearer Token。

管理员认证相关端点：
1. `POST /public/v1/admin/auth/register`
2. `POST /public/v1/admin/auth/resend-verification`
3. `POST /public/v1/admin/auth/verify-email`
4. `POST /public/v1/admin/auth/login`（返回 `challenge_id`）
5. `POST /public/v1/admin/auth/login/resend-otp`
6. `POST /public/v1/admin/auth/login/verify-otp`（签发管理员 token）

管理员 OTP 登录验证成功后，内部管理接口需携带：
1. `Authorization: Bearer <access_token>`
2. `X-PM-ROLE: <admin_role>`

## 6.2 核心状态接口
### 6.2.1 `GET /v1/status`
返回平台系统状态。

查询参数：无。

响应示例：
```json
{
  "success": true,
  "data": {
    "overall": "operational",
    "label": "All Systems Operational",
    "mode": "non-production",
    "components": [
      {"name": "gateway", "status": "operational"},
      {"name": "router", "status": "operational"},
      {"name": "connectors", "status": "degraded"}
    ],
    "updated_at": "2026-04-03T10:20:00Z"
  },
  "trace_id": "trc_01JQ..."
}
```

## 6.3 市场数据接口
### 6.3.1 `GET /v1/markets`
查询可交易市场与标的元信息。

查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `asset_class` | string | 否 | `equity/fx/crypto/futures/metals/prediction/index` |
| `venue` | string | 否 | 交易场所过滤 |
| `status` | string | 否 | `active/halted` |
| `page_size` | int | 否 | 默认 50 |
| `page_token` | string | 否 | 游标 |

响应示例：
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "symbol": "AAPL.US",
        "venue": "NASDAQ",
        "asset_class": "equity",
        "session": "regular",
        "price_precision": 2,
        "qty_precision": 4,
        "status": "active"
      }
    ],
    "next_page_token": null
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.3.2 `GET /v1/quotes`
查询实时快照（最新价、盘口、涨跌、时段状态）。

查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `symbols` | string | 是 | 逗号分隔，如 `AAPL.US,TSLA.US` |
| `depth` | int | 否 | 盘口档位，默认 1 |

响应示例：
```json
{
  "success": true,
  "data": {
    "quotes": [
      {
        "symbol": "AAPL.US",
        "venue": "NASDAQ",
        "last": "189.45",
        "bid": "189.44",
        "ask": "189.46",
        "bid_size": "1200",
        "ask_size": "1000",
        "change_24h": "0.82",
        "session_state": "open",
        "ts": "2026-04-03T10:21:12.120Z"
      }
    ]
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.3.3 `GET /v1/bars`
查询历史 K 线。

查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `symbol` | string | 是 | 平台 symbol |
| `timeframe` | string | 是 | `1m/5m/15m/1h/1d` |
| `start` | string(datetime) | 否 | 起始时间 |
| `end` | string(datetime) | 否 | 截止时间 |
| `limit` | int | 否 | 默认 200，最大 5000 |

响应示例：
```json
{
  "success": true,
  "data": {
    "symbol": "AAPL.US",
    "timeframe": "15m",
    "bars": [
      {
        "t": "2026-04-03T09:30:00Z",
        "o": "188.10",
        "h": "189.50",
        "l": "187.90",
        "c": "189.20",
        "v": "142300"
      }
    ]
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.3.4 `GET /v1/calendar`
交易时段日历（交易日、节假日、盘前盘后、24/5）。

查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `venue` | string | 否 | 交易场所 |
| `asset_class` | string | 否 | 资产类别 |
| `date` | string(date) | 否 | 指定日期，默认当天 |

## 6.4 交易接口
### 6.4.1 `POST /v1/orders`
创建单笔订单。

请求体：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `symbol` | string | 是 | 平台 symbol |
| `venue` | string | 否 | 指定 venue，不传则由路由决定 |
| `side` | string | 是 | `buy/sell` |
| `type` | string | 是 | `market/limit/stop` |
| `quantity` | string | 条件必填 | 与 `notional` 二选一 |
| `notional` | string | 条件必填 | 与 `quantity` 二选一 |
| `price` | string | 条件必填 | `limit/stop` 时必填 |
| `stop_price` | string | 否 | 止损触发价 |
| `time_in_force` | string | 否 | `DAY/GTC/IOC/FOK` |
| `reduce_only` | bool | 否 | 默认 false |
| `post_only` | bool | 否 | 默认 false |
| `strategy_id` | string | 否 | 策略标识 |
| `client_order_id` | string | 否 | 客户侧订单 ID |

请求示例：
```json
{
  "symbol": "AAPL.US",
  "side": "buy",
  "type": "limit",
  "quantity": "20",
  "price": "189.30",
  "time_in_force": "DAY",
  "strategy_id": "mom_15m_v2"
}
```

成功响应：
```json
{
  "success": true,
  "data": {
    "order_id": "ord_01JQ...",
    "client_order_id": "cli_78901",
    "status": "accepted",
    "symbol": "AAPL.US",
    "side": "buy",
    "type": "limit",
    "quantity": "20",
    "filled_quantity": "0",
    "avg_price": null,
    "connector": "alpaca",
    "created_at": "2026-04-03T10:25:01.003Z"
  },
  "trace_id": "trc_01JQ..."
}
```

常见错误：`RISK_MARGIN_INSUFFICIENT`、`MARKET_SESSION_CLOSED`、`CONNECTOR_UNAVAILABLE`。

### 6.4.2 `POST /v1/orders/batch`
批量下单。

请求体：
```json
{
  "orders": [
    {
      "symbol": "AAPL.US",
      "side": "buy",
      "type": "market",
      "quantity": "10"
    },
    {
      "symbol": "TSLA.US",
      "side": "sell",
      "type": "limit",
      "quantity": "5",
      "price": "220.00"
    }
  ]
}
```

响应包含逐单结果：
```json
{
  "success": true,
  "data": {
    "results": [
      {"index": 0, "ok": true, "order_id": "ord_1"},
      {"index": 1, "ok": false, "error_code": "RISK_NET_EXPOSURE_EXCEEDED"}
    ]
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.4.3 `PATCH /v1/orders/{order_id}`
改单（仅允许部分字段修改）。

可改字段：`price`、`quantity`、`time_in_force`。

请求示例：
```json
{
  "price": "189.10",
  "quantity": "15"
}
```

### 6.4.4 `POST /v1/orders/cancel`
撤单（单笔/批量/按策略）。

请求体：
```json
{
  "order_ids": ["ord_01JQ...", "ord_01JQ...2"],
  "strategy_id": null,
  "symbol": null
}
```

说明：
1. `order_ids`、`strategy_id`、`symbol` 至少传一个。
2. 按 `strategy_id` 撤销时将撤该策略下所有可撤订单。

响应示例：
```json
{
  "success": true,
  "data": {
    "canceled": ["ord_01JQ..."],
    "failed": [
      {
        "order_id": "ord_01JQ...2",
        "error_code": "ORDER_NOT_FOUND"
      }
    ]
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.4.5 `GET /v1/orders`
订单查询。

查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `status` | string | 否 | `new/partially_filled/filled/canceled/rejected` |
| `symbol` | string | 否 | 标的 |
| `strategy_id` | string | 否 | 策略 ID |
| `start` | datetime | 否 | 开始时间 |
| `end` | datetime | 否 | 截止时间 |
| `page_size` | int | 否 | 默认 50 |
| `page_token` | string | 否 | 游标 |

## 6.5 账户与持仓接口
### 6.5.1 `GET /v1/positions`
持仓查询（跨市场统一模型）。

查询参数：`symbol`（可选）、`asset_class`（可选）。

响应示例：
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "symbol": "AAPL.US",
        "net_qty": "120",
        "avg_price": "182.40",
        "mark_price": "189.50",
        "unrealized_pnl": "852.00",
        "realized_pnl": "-122.30",
        "updated_at": "2026-04-03T10:27:00Z"
      }
    ]
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.5.2 `GET /v1/accounts`
账户资产总览。

响应示例：
```json
{
  "success": true,
  "data": {
    "equity": "1023400.12",
    "available_margin": "618000.00",
    "maintenance_margin": "210300.11",
    "risk_ratio": "0.2055",
    "currency": "USD",
    "updated_at": "2026-04-03T10:27:00Z"
  },
  "trace_id": "trc_01JQ..."
}
```

## 6.6 接入申请接口（Partner）
### 6.6.1 `POST /v1/access-applications`
机构用户提交“交易所接入申请”。审批通过后由后端自动执行接入编排。

请求体：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `contact_email` | string(email) | 是 | 申请联系人邮箱 |
| `target_markets` | string[] | 是 | 目标市场（如 `US_EQ`, `HK_EQ`, `CRYPTO`） |
| `target_exchanges` | string[] | 是 | 希望接入交易所代码 |
| `expected_monthly_volume` | string | 否 | 预估月交易量 |
| `preferred_language` | string | 否 | 通知语言：`zh-CN/en-US/ja-JP` |
| `notes` | string | 否 | 补充说明 |

请求示例：
```json
{
  "contact_email": "tech@alphafund.io",
  "target_markets": ["US_EQ", "CRYPTO"],
  "target_exchanges": ["ALPACA", "BINANCE"],
  "expected_monthly_volume": "5000000",
  "preferred_language": "zh-CN",
  "notes": "Need US equities + crypto perp"
}
```

响应示例：
```json
{
  "success": true,
  "data": {
    "application_id": "app_01JQAX...",
    "status": "submitted",
    "submitted_at": "2026-04-03T11:05:00Z"
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.6.2 `GET /v1/access-applications`
查询当前租户的申请单列表。

查询参数：`status`（可选）、`page_size`、`page_token`。

### 6.6.3 `GET /v1/access-applications/{application_id}`
查询申请单详情与自动接入进度。

响应示例：
```json
{
  "success": true,
  "data": {
    "application_id": "app_01JQAX...",
    "status": "provisioning",
    "review_result": "approved",
    "provisioning_job_id": "job_01JQAZ...",
    "bindings": [
      {
        "exchange_code": "ALPACA",
        "binding_status": "active",
        "activated_at": "2026-04-03T11:20:00Z"
      },
      {
        "exchange_code": "BINANCE",
        "binding_status": "pending",
        "activated_at": null
      }
    ]
  },
  "trace_id": "trc_01JQ..."
}
```

### 6.6.4 `GET /v1/access-bindings`
查询租户当前已生效交易所绑定关系（中转 API 可用范围）。

## 6.7 管理后台接口（Internal Admin）
说明：以下接口仅供内部运营后台使用，不对外公开。

### 6.7.1 `GET /internal/v1/admin/access-applications`
后台查询全量申请单（支持多维过滤：状态、市场、交易所、提交时间）。

### 6.7.2 `POST /internal/v1/admin/access-applications/{application_id}/approve`
审批通过并触发自动接入编排。

请求示例：
```json
{
  "review_note": "Approved by ops",
  "provision_policy": {
    "auto_bind": true,
    "priority_exchanges": ["ALPACA", "BINANCE"],
    "fallback_enabled": true
  }
}
```

### 6.7.3 `POST /internal/v1/admin/access-applications/{application_id}/reject`
审批拒绝。

请求示例：
```json
{
  "reject_reason_code": "COMPLIANCE_RESTRICTED_REGION",
  "reject_message": "Service unavailable in requested jurisdiction"
}
```

### 6.7.4 `POST /internal/v1/admin/exchange-credentials`
录入或更新交易所平台凭证（供自动接入任务使用，密文托管）。

### 6.7.5 `GET /internal/v1/admin/provisioning/jobs/{job_id}`
查看自动接入任务状态与步骤日志。

## 6.8 中转 API 基线约束（强制）
1. `/v1/orders`、`/v1/orders/batch`、`/v1/orders/cancel` 统一经中转层执行，不允许客户端直连交易所。
2. 中转层仅可路由到“审批通过且绑定生效”的交易所。
3. 若无任何可用绑定，返回 `409 ACCESS_NOT_PROVISIONED`。
4. 若绑定交易所临时不可用，返回 `503 CONNECTOR_UNAVAILABLE`（`retryable=true`）。

## 7. WebSocket 接口
### 7.1 连接地址
- `wss://stream.omniaxs.com/v1/ws`

### 7.2 鉴权方式
连接后先发送 `auth` 消息：
```json
{
  "op": "auth",
  "api_key": "pmk_xxx",
  "timestamp": "1743666600123",
  "signature": "3e6d..."
}
```

成功回包：
```json
{"op":"auth","ok":true}
```

### 7.3 订阅/退订
订阅：
```json
{"op":"subscribe","topics":["quotes.AAPL.US","orders.*","risk.*"]}
```

退订：
```json
{"op":"unsubscribe","topics":["quotes.AAPL.US"]}
```

### 7.4 Topic 与消息体
1. `quotes.*`：实时行情快照。
2. `trades.*`：逐笔成交。
3. `orders.*`：订单状态变更与 execution report。
4. `risk.*`：风险告警与熔断事件。

`orders.*` 示例：
```json
{
  "topic": "orders.ord_01JQ...",
  "event": "execution_report",
  "data": {
    "order_id": "ord_01JQ...",
    "status": "partially_filled",
    "filled_quantity": "10",
    "last_fill_price": "189.32",
    "ts": "2026-04-03T10:28:21.100Z"
  }
}
```

### 7.5 心跳与重连
1. 服务端每 20 秒发送 `ping`，客户端 10 秒内回复 `pong`。
2. 断线重连建议指数退避（最多 30 秒）。
3. 重连后需重新鉴权并重新订阅。

## 8. Webhook（可选）
### 8.1 用途
将订单状态、风控事件推送到客户系统。

### 8.2 投递协议
1. 方法：`POST`
2. Header：
   - `X-PM-WEBHOOK-ID`
   - `X-PM-WEBHOOK-TIMESTAMP`
   - `X-PM-WEBHOOK-SIGNATURE`

签名：
```text
signature = hex(hmac_sha256(webhook_secret, timestamp + "\n" + raw_body))
```

### 8.3 重试策略
1. 首次失败后最多重试 8 次。
2. 间隔：`10s, 30s, 1m, 2m, 5m, 10m, 20m, 30m`。
3. 客户端返回 `2xx` 视为成功。

### 8.4 事件类型
1. `order.accepted`
2. `order.rejected`
3. `order.partially_filled`
4. `order.filled`
5. `order.canceled`
6. `risk.alert`
7. `risk.circuit_break`

## 9. SDK 最小闭环示例（Python）
```python
import omniaxs as ox

client = pm.Client(api_key="YOUR_KEY", api_secret="YOUR_SECRET", env="sandbox")

bars = client.market.pull(symbol="AAPL.US", timeframe="15m", limit=200)
signal = pm.alpha.momentum(bars)
order = pm.strategy.to_order(signal, symbol="AAPL.US", notional=5000)

if client.risk.check(order):
    result = client.router.execute(order, connector="alpaca")
    print(result.status, result.order_id)
```

## 10. 合规与使用边界（对外声明）
1. OMNIAXS 是 Non-Custodial Technology Layer，不托管客户资金。
2. KYC/AML 与账户开立由最终受监管连接器执行。
3. 服务不面向受限制司法辖区（以实时 Geo-Fencing 配置为准）。

## 11. 变更记录模板
| 日期 | 版本 | 变更内容 | 负责人 |
|---|---|---|---|
| 2026-04-03 | v1.0 | 初版发布 | API Team |