binance-api/specs/002-/contracts/signature-service.md

API 契约：签名服务（简化版）

概述

多平台账户凭据管理与签名服务，专注于单一职责：为不同平台提供签名功能。

基础信息

• API 版本: v1
• 基础路径: /api/v1
• 认证方式: 无（内部服务）
• 内容类型: application/json

---

1. 核心签名接口

1.1 执行签名操作

POST /api/v1/sign
Content-Type: application/json

{
  "platformId": "pacifica",
  "accountId": "pac-main-001",
  "data": {
    "type": "place_order",
    "market": "BTC-USD",
    "side": "bid",
    "amount": "0.001",
    "price": "65000"
  }
}

响应 (200 OK):

{
  "success": true,
  "data": {
    "signature": "base58_encoded_signature",
    "algorithm": "ed25519",
    "encoding": "base58",
    "publicKey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "signedAt": "2025-09-28T12:00:00Z"
  }
}

错误响应 (404 Not Found):

{
  "success": false,
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "指定账户不存在",
    "details": {
      "platformId": "pacifica",
      "accountId": "pac-main-001"
    }
  }
}

1.2 批量签名操作

POST /api/v1/sign/batch
Content-Type: application/json

{
  "requests": [
    {
      "requestId": "req_001",
      "platformId": "pacifica",
      "accountId": "pac-main-001",
      "data": {"type": "place_order", "symbol": "BTC-USD"}
    },
    {
      "requestId": "req_002",
      "platformId": "aster",
      "accountId": "ast-hedge-001",
      "data": {"action": "cancel_order", "orderId": "12345"}
    }
  ]
}

响应 (200 OK):

{
  "success": true,
  "data": {
    "results": [
      {
        "requestId": "req_001",
        "status": "success",
        "signature": "base58_signature_1",
        "algorithm": "ed25519"
      },
      {
        "requestId": "req_002",
        "status": "success",
        "signature": "0x8c7e40c7b23c0b86...",
        "algorithm": "eip191"
      }
    ],
    "summary": {
      "total": 2,
      "successful": 2,
      "failed": 0
    }
  }
}

---

2. 账户管理

2.1 获取账户列表

GET /api/v1/accounts?platform=pacifica

响应 (200 OK):

{
  "success": true,
  "data": {
    "accounts": [
      {
        "accountId": "pac-main-001",
        "platformId": "pacifica",
        "alias": "Pacifica主账户",
        "status": "active",
        "environment": "production",
        "usage": {
          "totalSigns": 1250,
          "lastSignAt": "2025-09-28T11:30:00Z",
          "errorCount": 2
        }
      }
    ],
    "total": 1
  }
}

2.2 获取单个账户信息

GET /api/v1/accounts/{platformId}/{accountId}

响应 (200 OK):

{
  "success": true,
  "data": {
    "accountId": "pac-main-001",
    "platformId": "pacifica",
    "alias": "Pacifica主账户",
    "status": "active",
    "environment": "production",
    "algorithm": "ed25519",
    "publicKey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "createdAt": "2025-09-01T10:00:00Z",
    "lastUsed": "2025-09-28T11:30:00Z"
  }
}

---

3. 配置管理

3.1 重载配置

POST /api/v1/config/reload

响应 (200 OK):

{
  "success": true,
  "data": {
    "reloadedAt": "2025-09-28T12:00:00Z",
    "changes": {
      "added": 1,
      "updated": 0,
      "removed": 0
    },
    "accountCount": 8,
    "platformCount": 4
  }
}

3.2 获取服务状态

GET /api/v1/status

响应 (200 OK):

{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": "72h 15m 30s",
    "config": {
      "path": "/path/to/credentials.json",
      "lastLoaded": "2025-09-28T12:00:00Z",
      "isWatching": true
    },
    "accounts": {
      "total": 8,
      "byPlatform": {
        "pacifica": 3,
        "aster": 2,
        "binance": 2,
        "okx": 1
      }
    },
    "performance": {
      "avgSigningTime": "15ms",
      "totalSigns": 12500,
      "errorRate": 0.002
    }
  }
}

---

4. 平台特定签名格式

4.1 Pacifica 签名数据格式

{
  "platformId": "pacifica",
  "accountId": "pac-main-001",
  "data": {
    "instruction": {
      "type": "place_order",
      "market": "BTC-USD",
      "side": "bid",
      "amount": "0.001",
      "price": "65000"
    },
    "nonce": 1735390800000
  }
}

4.2 Aster 签名数据格式

{
  "platformId": "aster",
  "accountId": "ast-hedge-001",
  "data": {
    "message": {
      "action": "place_order",
      "symbol": "BTCUSDT",
      "price": "65000",
      "quantity": "0.001",
      "timestamp": 1735390800000
    }
  }
}

4.3 Binance 签名数据格式

{
  "platformId": "binance",
  "accountId": "bn-spot-001",
  "data": {
    "method": "POST",
    "endpoint": "/api/v3/order",
    "params": {
      "symbol": "BTCUSDT",
      "side": "BUY",
      "type": "LIMIT",
      "quantity": "0.001",
      "price": "65000",
      "timestamp": 1735390800000
    }
  }
}

4.4 OKX 签名数据格式

{
  "platformId": "okx",
  "accountId": "okx-perp-001",
  "data": {
    "method": "POST",
    "path": "/api/v5/trade/order",
    "body": {
      "instId": "BTC-USDT",
      "side": "buy",
      "ordType": "limit",
      "sz": "0.001",
      "px": "65000"
    },
    "timestamp": "2025-09-28T12:00:00.000Z"
  }
}

---

错误代码规范

错误代码	HTTP状态码	描述
ACCOUNT_NOT_FOUND	404	指定账户不存在
PLATFORM_NOT_SUPPORTED	400	不支持的平台
INVALID_DATA_FORMAT	400	签名数据格式错误
SIGNATURE_FAILED	500	签名操作失败
CONFIG_LOAD_FAILED	500	配置文件加载失败
ACCOUNT_INACTIVE	423	账户已禁用

性能要求

延迟目标

• 单次签名: < 50ms
• 批量签名: < 200ms (10个请求)
• 配置重载: < 5秒

吞吐量目标

• 并发签名: 100 QPS
• 可扩展性: 支持水平扩展

可用性目标

• 服务可用性: 99.9%
• 配置热重载: 无服务中断

安全要求

数据保护

• 私钥永不在响应中返回
• 所有凭据在内存中加密存储
• 配置文件访问权限控制

日志记录

• 记录所有签名请求和结果
• 敏感数据自动脱敏
• 支持审计追踪

网络安全

• 仅限内网访问
• 支持 HTTPS 加密传输
• 请求大小限制 1MB