十二星座商户接口

接口地址

服务地址为 https://api.12zodi.com，所有 /v1/ 请求均校验商户签名和 IP 白名单。

查看 OpenAPI 接口定义 · 下载单一钱包协议定义 · 下载 Node.js 商户接入客户端 · 商户后台登录

GET  /v1/game                 直播地址、当前期次、赔率、限额
GET  /v1/issues/current       当前期次、封盘时间、可投注状态
GET  /v1/odds                 当前期次的十二星座赔率
POST /v1/balance              查询商户玩家钱包余额
POST /v1/bets                 商户服务端提交投注
GET  /v1/bets/{id}            查询注单和扣款、派奖、退款状态
GET  /v1/bets                 分页查询本商户注单
GET  /v1/results              最近开奖结果与取消局
GET  /v1/results?issueNo=...  指定期次结果
GET  /v1/transactions/{id}    查询交易状态
GET  /v1/reconciliation      查询本商户账务汇总

签名

签名使用后台提供的商户密钥。请求头包含 X-Operator-Id、X-Timestamp（UTC 秒）、X-Nonce（每次请求唯一）和 X-Signature。

HMAC-SHA256(secret, [
  HTTP方法大写,
  实际路径及查询字符串,
  X-Timestamp,
  X-Nonce,
  SHA256(实际UTF-8请求体)
].join('\n'))

X-Signature 为小写十六进制。GET 空请求体按空字符串计算。
请求时间允许相差 120 秒。每次重试使用新 nonce，投注 requestId 保持原值。
密钥仅保留在商户服务端。

投注请求

POST /v1/bets
{
  "playerId": "merchant-player-001",
  "requestId": "unique-bet-request-001",
  "issueNo": "从当前期次接口读取",
  "currency": "USD",
  "items": [{"signCode": "aries", "amount": 100}]
}

金额为币种最小单位整数，USD 精度 2 时 100 表示 1.00 USD。一批可选择多个不同星座，一次扣款。

HTTP 202 表示请求已受理。读取返回的注单编号，查询 GET /v1/bets/{id}，直到 status 变为 active（扣款已确认）、rejected（扣款拒绝）或后续结算状态。相同玩家和 requestId 同内容返回原注单，异参冲突返回 409。

钱包超时保留待确认状态，按原交易号查单恢复。退款和派奖均关联原扣款。商户钱包需实现余额、扣款、派奖、退款和交易查单协议。

Node.js 服务端示例

import { MerchantClient } from './merchant-client.mjs';
const client = new MerchantClient({
  merchantId: process.env.MERCHANT_ID,
  secret: process.env.MERCHANT_SECRET
});
const game = await client.game();
if (game.bettingEnabled) {
  const order = await client.placeBet({
    playerId: 'your-player-id',
    requestId: 'your-unique-request-id',
    issueNo: game.currentIssue.issueNo,
    currency: game.currency,
    items: [{signCode: 'aries', amount: 100}]
  });
  // 用 order.id 查询扣款及结算的最终状态。
  const detail = await client.getBet(order.id);
}

接入顺序

1. 后台新增商户，填写钱包回调、币种限额和出口 IP。
2. 下载商户接入参数，完成钱包协议对接。
3. 调用 /v1/game 读取直播、期次、赔率和投注状态。
4. 调用 /v1/bets 提交投注，按注单号查询结果。
5. 开奖后查询结果、派奖和账务汇总。

没有可验证的当前期次时 bettingEnabled 为 false。演示赔率为沙箱配置，正式赔率由业务冻结后设置。