binance-api/specs/001-specManager-perp/contracts/account-sync.md

账户同步接口契约

1. 请求：拉取账户状态

• 方法：POST /control-plane/account-sync（内部服务调用）

• 请求体：

  {
  "requestId": "uuid",
  "accounts": [
  {
    "accountId": "pacifica-1",
    "exchange": "pacifica",
    "nonce": 1695800000
  }
  ]
  }
  

• 说明：

  • requestId：全局唯一，用于追踪日志。
  • accounts：本次需要同步的账户列表；nonce 为去重或防重放字段。

2. 响应：账户余额与仓位

{
  "requestId": "uuid",
  "timestamp": "2025-09-27T12:00:00Z",
  "results": [
    {
      "accountId": "pacifica-1",
      "status": "success",
      "balances": [
        { "asset": "USDT", "total": "120.53", "available": "72.28" },
        { "asset": "BTC", "total": "0.0012", "available": "0.0003" }
      ],
      "positions": [
        {
          "symbol": "BTC",
          "side": "long",
          "size": "0.0009",
          "entryPrice": "109293.50",
          "markPrice": "109310.12",
          "unrealizedPnl": "0.15"
        }
      ],
      "utilization": {
        "value": 0.65,
        "formula": "(totalBalance - availableBalance) / totalBalance"
      }
    }
  ],
  "errors": []
}

• balances.total/available：字符串表示，保留精度。
• positions：同一交易所资产只列出一条，side 为 long/short。
• utilization.value：数值型，便于对齐 50%-80% 目标。
• errors：若单个账户失败，附带 { "accountId": ..., "code": ..., "message": ... }。

3. 失败示例

{
  "requestId": "uuid",
  "timestamp": "2025-09-27T12:00:01Z",
  "results": [],
  "errors": [
    {
      "accountId": "aster-1",
      "code": "AUTH_INVALID",
      "message": "API key expired",
      "retryable": false
    }
  ]
}

4. 业务规则

• 成功响应必须包含时间戳并与监控日志相关联。
• 控制平面收到结果后需更新 ExchangeAccount、RiskEnvelope 相应字段。
• 若 errors 非空，需生成 MonitoringEvent（类型：account-sync-fail）。