认证机制

Token 格式

Agent Token 采用三段式结构，各部分以 . 分隔：

{agent_api_key}.{timestamp}.{signature}

部分	类型	说明	示例
agent_api_key	string	您的 API Key	a9f3c28d7b1e4f90c2a1b3d4
timestamp	string	当前 Unix 时间戳（秒）	1743055200
signature	string	HMAC-SHA256 签名（hex 小写）	a1b2c3d4e5...

签名算法

signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) → hex 小写

生成步骤

1. 获取当前时间戳
   Unix timestamp（秒），如 1743055200

2. 拼接待签名字符串

   raw_string = agent_api_key + "." + timestamp

3. 计算 HMAC-SHA256 签名

   signature = HMAC-SHA256(raw_string, agent_api_secret)

   转为 hex 小写字符串

4. 组合 Token

   token = agent_api_key + "." + timestamp + "." + signature

5. 放入 HTTP Header

   Authorization: Bearer {token}

时效性

Token 中的时间戳必须在服务器当前时间 ±2 分钟 以内，否则会被拒绝。请确保您的服务器时间准确（建议使用 NTP 同步）。

服务端验证流程

服务端收到请求后的验证步骤：

1. 提取 Token — 从 Authorization: Bearer {token} Header 中获取 Token
2. 拆分 Token — 按 . 分割为 agent_api_key、timestamp、signature 三部分
3. 验证时间戳 — 确认 timestamp 与服务器时间差不超过 2 分钟
4. 查库获取密钥 — 用 agent_api_key 查数据库取出 agent_api_secret
5. 验证签名 — 用取到的 agent_api_secret 重新计算 HMAC-SHA256 并比对 signature

双向签名验证 (Mutual Verification)

为确保接口的安全性，系统对双向调用的认证机制进行了如下定义：

1. Agent 调用 VCT 平台（API 接口）：Agent 需按照上述步骤生成 Token 并携带在 Authorization: Bearer {token} 请求头中，由 VCT 平台进行验证。
2. VCT 平台调用 Agent（回调接口/Webhook）：VCT 平台向 Agent 发送余额查询、离线回收及其他回调请求时，必须携带 Authorization 请求头。包网系统必须先校验 Header，再校验请求体中的 sign。Header 与 Body 的 timestamp 必须是同一个秒级 Unix 时间戳，不能分别生成或使用不同时间戳。
   • Header 格式：Authorization: Bearer {agent_api_key}.{timestamp}.{header_signature}
   • Header 签名：header_signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret)，结果使用小写 hex
   • agent_api_key 必须对应当前 Agent，不能使用其他 Agent 的 Secret 进行尝试
   • 对于单玩家回调（/balance、/offline，含 launch_failed）： signature = HMAC-SHA256(username + "." + timestamp, agent_api_secret)
   • 对于投注数据推送（/bet-push）： signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) 包网系统校验请求体中的 sign 字段与上述算法计算结果一致后才可处理业务。