跳到主要内容

鉴权

本接口许多端点是公开的。部分数据端点需要付费套餐及平台签发的 API 密钥。少数端点要么在请求体中接受用户的 Binance API key/secret，要么通过 email 查找用户事先登记到平台的密钥。

共五种模式。每个端点页面会注明其使用的模式。

1. 公开端点​

无需鉴权头。核心加密行情接口与策略 CRUD 都属于此类。公开端点仍受每 IP 限流约束（见 通用信息）。

1b. 套餐限制端点（平台 API 密钥）​

部分数据端点需要付费订阅，并按套餐等级鉴权。目前股票、指数、大宗商品的 K 线（klines）端点至少需要标准套餐。

购买套餐后，平台会为你的账户签发一枚数据 API 密钥（以 pk_ 开头）——它与任何 Binance 交易密钥无关。每次调用套餐限制端点时，通过 X-Primit-API-Key 请求头携带该密钥：

X-Primit-API-Key: pk_xxxxxxxxxxxxxxxx

后端会校验该密钥并确认订阅处于有效期内。返回：

HTTP原因
401缺少或无效的 X-Primit-API-Key。
403端点所需套餐未生效（订阅已过期或未购买）。

订阅后可在控制台查看与管理你的数据 API 密钥。

2. 请求体携带凭据（*/auth 及部分 POST 端点）​

部分端点 —— 主要是下单和按账户取数据的接口 —— 直接在 JSON 请求体里接收调用方的 Binance API 凭据。

通用请求体形态：

{
  "api_key": "<binance-api-key>",
  "api_secret": "<binance-api-secret>",
  "...endpoint-specific fields..."
}

这些凭据用于对上游 Binance 请求签名，平台不持久化。属于此类的端点包括所有以 /auth 结尾的变体（如 /orders/auth、/orders/cancel/auth、/positions/close/auth、/leverage/auth、/margin-type/auth），以及一部分接受 ApiCredentials 体的 POST 端点。这些交易侧端点不在本站点的文档化范围。

3. 基于 Email 的已登记密钥查询​

适用于事先把 Binance 密钥上传到平台、希望平台用其登记密钥的调用方。

验证已登记的密钥​

POST /api-key/verify

请求体：

{ "email": "user@example.com" }

响应：

{
  "success": true,
  "message": "API 密钥验证成功",
  "email": "user@example.com",
  "has_api_key": true
}

查询已登记密钥状态​

GET /api-key/status/{email}

未登记时响应：

{
  "success": false,
  "message": "用户不存在或没有API密钥",
  "email": "user@example.com",
  "has_api_key": false
}

已登记时响应：

{
  "success": true,
  "message": "获取状态成功",
  "email": "user@example.com",
  "has_api_key": true,
  "verification_status": "verified",
  "last_verified": "2026-04-29T12:00:00",
  "created_at": "2026-04-01T00:00:00",
  "is_active": true
}

4. Google 登录（Bearer 应用令牌）​

原生 App 使用 Google 完成用户登录，并换取平台的应用令牌（一个受限的 JWT），作为用户维度端点的 Bearer 凭据使用。

用 Google ID token 换取应用令牌​

POST /auth/mobile/google

App 通过 Google Sign-In SDK 获取 Google ID token 后提交。无需 X-Backend-Key。

请求体：

{ "id_token": "<google-id-token>" }

后端会通过 Google 校验该 token（RS256 签名、过期时间、签发方 accounts.google.com、audience 以及 email_verified），随后按 google_id / email 创建或关联用户。

响应 —— 200 OK：

{
  "access_token": "<app-jwt>",
  "user": {
    "id": 123,
    "email": "user@example.com",
    "name": "Jane Doe",
    "google_id": "1067290000000000000",
    "apple_id": null,
    "is_vip": false,
    "vip_expires_at": null,
    "created_at": "2026-06-01T00:00:00",
    "updated_at": "2026-06-24T00:00:00"
  }
}
HTTP触发原因
401id_token 无效或已过期，或邮箱未验证。
503Google 校验依赖不可用。

使用应用令牌​

将返回的 access_token 以 Bearer 头携带，访问用户维度端点：

Authorization: Bearer <app-jwt>

该令牌是用户维度的 HS256 JWT，按服务端配置过期。Apple 登录方式相同，使用并行的 POST /auth/mobile/apple 端点（请求体 { "identity_token": "<apple-identity-token>" }）。

不使用的方案​

平台不对请求做 HMAC 签名。除套餐限制端点使用的数据 API 密钥（X-Primit-API-Key，见模式 1b）与上文 Google / Apple 登录签发的 Bearer 应用令牌外，平台不需要其他 X-Primit-* 头。