量化团队与 Broker 如何接入 WEEX：API、用户管理与返佣数据的协同设计

对于量化团队、交易工具服务商和带单社区而言，接入交易 API 不只是“替用户发起一笔订单”。当系统同时涉及用户授权、订单归属、返佣资格和数据对账时，真正需要解决的是一套多角色协作问题：

本文以 WEEX Broker API 为例，从系统设计视角拆解量化团队或 Broker 如何完成接入，并重点讨论 OAuth 授权、用户身份、订单标识和返佣数据的协同处理。

一、先分清四类角色：不要让权限和责任混在一起

一套 Broker 接入系统通常涉及四类角色：

关键原则是：Broker 平台方为用户提供连接与执行能力，但不应将不同用户的资金、凭证和订单混在同一个共享账户或共享密钥中。

用户身份、Broker 身份和订单身份应分别保存：

· 用户身份：WEEX UID、授权状态、用户绑定凭证

· Broker 身份：clientId、clientSecret、Broker ID、回调地址、出口 IP

· 订单身份：clientOrderId、orderId、用户 ID、Broker 标识

这套分层能帮助系统回答三个基本问题：

· 这笔订单属于哪个用户？

· 这笔订单由哪个 Broker 服务发起？

· 这笔订单是否正确绑定了 Broker 身份？

二、两种接入路径：自有 API Key 与 OAuth 授权

Broker 接入时，用户凭证通常有两种管理方式：用户自行配置 API Key，或通过 OAuth 完成授权。

路径一：用户自行创建 API Key

用户创建 API Key 后，将其配置到 Broker 系统中。Broker 再使用该密钥访问相应能力。

这种方式接入较直接，但 Broker 平台方需要更严格地保护用户提交的凭证，并处理密钥失效、权限不足、IP 变更和用户主动删除密钥等情况。

路径二：OAuth 用户授权

OAuth 更适合需要规模化服务用户的量化团队、策略工具和交易社区。

OAuth 流程包括：

1. Broker 完成注册并获取 clientId 与 clientSecret；

2. 用户跳转至 WEEX 页面完成登录与授权，Broker 获得临时授权码 code；

3. Broker 后端使用 code 获取 accessToken；

4. Broker 使用 accessToken 获取用户绑定的 API Key、Secret Key 与 Passphrase；

5. Broker 在用户授权范围内调用后续 API。

三、OAuth 的关键不是跳转，而是安全完成授权闭环

OAuth 接入中，最容易被低估的是回调安全。一个看似简单的“授权后跳回 Broker 系统”流程，至少需要处理 state、PKCE、回调地址和 token 生命周期。

1. Broker 注册：先固定身份边界

Broker 需要向 WEEX 提交名称、关联 UID、隐私条款、服务条款、回调地址、联系人和服务器出口 IP 等信息。

其中有两个关键点：

· redirectUri 必须预先配置，授权请求中的地址必须与已配置地址完全匹配；

· Broker 服务器出口 IP 需要纳入白名单，未授权 IP 无法调用相关接口。

因此，OAuth 接入应先完成生产环境、测试环境和回调域名规划，再进入开发阶段，而不是在上线前临时变更。

2. state：用于防止授权回调被伪造

发起授权时，Broker 应生成高随机度的 state，并将它与当前用户会话、过期时间和回调地址绑定保存。

回调后，必须校验：

· 回调 state 是否存在

· 回调 state 是否与发起授权时一致

· state 是否未过期

· state 是否尚未被使用

如果校验失败，应终止授权流程，不应继续交换 token。

3. PKCE：避免授权码被截获后滥用

WEEX OAuth 当前要求使用 PKCE，且支持 S256 方法。Broker 需要生成：

· code_verifier：高熵随机字符串，仅保存在后端或受控会话中；

· code_challenge：对 code_verifier 做 SHA-256 后进行 Base64URL 编码的结果。

授权时传递 code_challenge，换取 token 时提交原始 code_verifier。即使授权码被截获，攻击者没有对应的 code_verifier，也无法完成 token 交换。

4. Token 只在后端处理

换取到 accessToken 后，Broker 可在授权范围内请求用户绑定的 API 凭证。文档提示，创建 API Key 成功后，apiKey、secret 和 passphrase 仅在首次成功响应中返回，因此必须在受控后端完成加密存储和权限管理。

以下内容严禁放入前端页面、移动端应用、日志或即时通讯工具：

· clientSecret

· codeVerifier

· accessToken

· refreshToken

· API Key

· Secret Key

· Passphrase

WEEX OAuth 文档明确要求将这些敏感凭证存储在后端，并使用 HTTPS 和 state 校验保护授权流程。

四、Broker ID：让订单归属可识别、可审计

完成用户授权后，订单执行仍需解决 Broker 身份绑定问题。

WEEX Broker 文档要求：现货和合约下单时，如需绑定 Broker ID，newClientOrderId 必须以 b-{brokerId} 开头，总长度不超过 64 个字符。

例如：

Plain Textb-WEEX123456-20260723-000001

Broker 可将订单号设计为：

Plain Textb-{brokerId}-{业务日期}-{用户短标识}-{序号}

示例：

Plain Textb-WEEX123456-20260723-u8f2-000001

这种设计有三层价值：

· 对 WEEX：能够识别订单的 Broker 归属；

· 对 Broker：可将订单与内部用户、策略任务和执行记录关联；

· 对审计与排错：可从订单号快速定位请求来源。

但应注意：订单号中不应直接放入手机号、邮箱、完整 UID 或其他个人信息。建议使用内部短标识或不可逆映射值。

WEEX Broker 文档对 Broker ID 的订单绑定格式有明确说明，实际接入时应以审核后下发的 Broker ID 与最新文档为准。

五、用户返佣资格：在绑定前校验，而不是事后猜测

用户是否符合返佣资格，不应由 Broker 自行推断，也不宜只根据前端页面展示来判断。

WEEX Broker API 提供用户返佣资格查询能力：

Plain TextGET /api/v3/apiReferral/checkUserEligibility

该接口要求传入 WEEX UID，并返回：

因此，一个更稳妥的用户接入流程可以是：

用户连接 WEEX 账户 → Broker 获得必要的用户标识与授权状态 → Broker 服务查询返佣资格 → 记录结果与查询时间 → 符合条件时进入后续 Broker 绑定与服务流程 → 不符合条件时展示原因或引导联系支持渠道

返佣资格属于动态业务状态。Broker 应记录查询时间，并在关键操作前按规则复核，而不是将一次查询结果永久缓存。

六、返佣数据不等于订单数据：应建立独立对账链路

订单数据回答的是“发生了什么交易”；返佣数据回答的是“在当前合作规则下，哪些业务数据进入结算范围”。两者相关，但不应互相替代。

建议 Broker 内部建立三类账本：

推荐的数据流如下：

对账时，至少应关注：

· 用户是否处于有效授权状态；

· 订单是否带有符合规则的 Broker 标识；

· 成交与返佣数据所属的时间范围是否一致；

· 同一订单是否被重复采集；

· 返佣数据是否已成功拉取、入库和对账；

· 差异是否有可追踪的原因和处理记录。

不要根据预估费率或单笔订单字段自行生成“最终返佣金额”。返佣比例与结算结果应以 WEEX 审核配置、官方接口数据及双方合作协议为准。

七、Broker API 的限频：按 UID 与 IP 双维度设计

WEEX Broker 文档说明，需要携带 API Key 的接口按账号 UID 限速；无需 API Key 的接口按 IP 限速。两种统计模式相互独立，且接口权重会因资源消耗不同而不同。

当前文档还列出：按 IP 和按 UID 的接口分别共享 500 权重/10 秒；收到 HTTP 429 时，应停止发送请求，不得滥用 API

Broker 的限频设计应至少做到：

· 将用户操作请求与后台批量对账任务隔离；

· 对相同用户的资格查询进行短时缓存；

· 将返佣数据同步放入任务队列，避免前端刷新直接触发；

· 遇到 429 时启用退避，而不是并发重试；

· 监控 UID 与 IP 两类限频压力；

· 为订单核验、撤单和安全处理保留较高优先级。

八、从“接入成功”到“长期可运营”的工程清单

Broker 注册与授权

· 已完成 Broker 信息、回调地址和出口 IP 配置

· redirectUri 使用 HTTPS，并严格匹配已配置地址

· 每次授权生成独立、一次性的 state

· 使用 PKCE S256，妥善保存 code_verifier

· 授权码、token 与密钥均只在后端处理

· 已设置 token 过期、刷新和授权失效后的用户提示

用户与订单管理

· 已建立 WEEX UID、Broker 用户、授权凭证之间的映射

· 每笔订单使用唯一 newClientOrderId

· Broker 订单号符合 b-{brokerId} 前缀与长度要求

· 订单号未包含个人敏感信息

· 已记录订单、成交、撤单和异常事件

· 重试前会先按原订单号或客户端订单号核验状态

返佣与对账

· 用户接入时已按规则校验返佣资格

· 资格结果记录了查询时间与原因

· 订单账本、用户归属账本和返佣账本相互独立

· 返佣数据按周期同步并保留原始响应

· 已建立差异处理、人工复核和审计记录

· 不以预估费率替代 WEEX 结算数据

稳定性与安全

· API OAuth 凭证和敏感请求头均完成日志脱敏

· 已按 UID、IP 和接口权重设计限频器

· 已处理 429、鉴权失败、回调校验失败和网络超时

· 已设置异常熔断：暂停新增操作、保留查询与必要的风险处理

· 已建立授权失败、限频异常、订单不一致和对账差异告警

总结一下：量化团队与 Broker 的 API 接入，本质上是一套“授权、执行、归属与结算”协同系统。OAuth 负责让用户在可控边界内完成 WEEX 授权；Broker ID 负责标识订单归属；资格查询帮助 Broker 减少业务状态判断误差；返佣数据与订单数据的独立对账，则让长期运营具备可审计性。把这些环节拆开设计，再通过统一的用户与订单标识连接起来，才能让 Broker 在规模化服务时仍保持清晰、稳定和可维护。

本文仅介绍 API、授权与数据管理的技术实践，不构成投资、交易、佣金或收益承诺。WEEX Broker API 文档当前标注为 V3（BETA）。实际接入前，请以 WEEX 最新文档、审核结果和双方合作协议中的权限、限频、接口可用性及结算规则为准。