API Gateway v3.4.2 正常运行
REST Base: https://api.odds-api.com.cn/v3
协议编码: UTF-8 / JSON / Protobuf v3 下载多语言 SDK
DEVELOPER REFERENCE MANUAL // V3.4

体育盘口API文档:接口端点、签名鉴权与实时报文标准

欢迎查阅锐矩盘口API技术开放平台文档中心。本规范面向体育数据架构师与后端研发团队,完整定义全球足球、篮球及综合体育赛事的赛前盘口快照(Pre-match Snapshots)、滚球即时赔率流(In-Play Odds Stream)、亚盘/欧赔/大小球历史变动轨迹的标准接口协议。支持高吞吐 RESTful 轮询与全双工 WebSocket 增量推送。

通信安全标准
TLS 1.3 / HMAC
赔率格式支持
EU / HK / MY / ID
序列化协议
JSON & Protobuf
时间戳精度
Unix Millis (ms)
体育盘口API网关架构与实时赔率监控控制台界面
多活数据接入点 (CN-SZ / HK / SG) SLA 99.99%

所有 REST 请求默认启用 Gzip / Brotli 压缩,单次请求可拉取多达 200 场赛事的多庄家盘口矩阵。

全局 HTTP 请求头规范 (Standard Request Headers)

Header 字段名 必选 类型 / 示例值 字段描述与技术要求
X-Access-Key 是 ak_live_98f2a10c4b7e 开发者控制台分配的应用公钥标识(Access Key ID)。
X-Timestamp 是 1714568400125 当前 UTC 毫秒级时间戳。网关校验客户端与服务器时间偏移量不得超过 ±30,000ms。
X-Nonce 是 f47ac10b-58cc-4372 16-36位随机唯一字符串,用于防御時間窗口内的报文重放攻击(Replay Attack)。
X-Signature 是 e3b0c44298fc1c149afbf4... 基于 HMAC-SHA256 算法生成的十六进制小写签名摘要。
Accept-Encoding 推荐 gzip, br 开启压缩可降低约 78% 的全量盘口快照传输体积,显著提升高并发响应速度。
Security & Authentication

API签名鉴权机制与沙盒验签计算器

算法标准: HMAC-SHA256 (Hex)

为保障商业赛事数据流与客户配额安全,所有向 /v3/* 发起的请求均须通过签名验证。请勿在前端浏览器或移动端 App 代码中硬编码 SecretKey。签名原串(Payload String)由请求方法、URI路径、排序后的查询参数、时间戳与随机串按固定换行符 \n 拼接构成。

1 规范化签名原串拼接格式 (StringToSign)

StringToSign = 
  HTTP_METHOD + "\n" +
  REQUEST_PATH + "\n" +
  CANONICAL_QUERY_STRING + "\n" +
  X_TIMESTAMP + "\n" +
  X_NONCE
  • HTTP_METHOD:全大写英文,如 GET 或 POST。
  • REQUEST_PATH:不包含域名的绝对路径,如 /v3/football/odds/snapshot。
  • CANONICAL_QUERY_STRING:将所有 URL Query 参数按参数名 ASCII 字典序升序排列,使用 key=value 格式并以 & 连接。若为 POST JSON 请求,则将压缩去空格后的 JSON Body 字符串计算 SHA256 后填入此行。

在线签名原串预演沙盒

实时生成待签名字符串
拼接生成的 StringToSign:

                                
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "net/http"
    "strconv"
    "time"
)

func SignRequest(method, path, canonicalQuery, secretKey string) (map[string]string, error) {
    ts := strconv.FormatInt(time.Now().UnixMilli(), 10)
    nonce := "n_" + ts + "_8f92a1"
    
    payload := fmt.Sprintf("%s\n%s\n%s\n%s\n%s", method, path, canonicalQuery, ts, nonce)
    mac := hmac.New(sha256.New, []byte(secretKey))
    mac.Write([]byte(payload))
    signature := hex.EncodeToString(mac.Sum(nil))

    return map[string]string{
        "X-Access-Key": "ak_live_98f2a10c4b7e",
        "X-Timestamp":  ts,
        "X-Nonce":      nonce,
        "X-Signature":  signature,
    }, nil
}
import time
import uuid
import hmac
import hashlib
import requests

ACCESS_KEY = "ak_live_98f2a10c4b7e"
SECRET_KEY = "sk_prod_your_private_secret_key_here"

def build_auth_headers(method: str, path: str, query_str: str) -> dict:
    timestamp = str(int(time.time() * 1000))
    nonce = uuid.uuid4().hex[:16]
    
    string_to_sign = f"{method.upper()}\n{path}\n{query_str}\n{timestamp}\n{nonce}"
    signature = hmac.new(
        SECRET_KEY.encode("utf-8"),
        string_to_sign.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
    
    return {
        "X-Access-Key": ACCESS_KEY,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
        "Accept-Encoding": "gzip, br"
    }
const crypto = require('crypto');

function generateOddsApiHeaders(method, path, canonicalQuery, accessKey, secretKey) {
  const timestamp = Date.now().toString();
  const nonce = crypto.randomBytes(8).toString('hex');
  
  const stringToSign = [
    method.toUpperCase(),
    path,
    canonicalQuery,
    timestamp,
    nonce
  ].join('\n');

  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(stringToSign, 'utf8')
    .digest('hex');

  return {
    'X-Access-Key': accessKey,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature
  };
}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.HexFormat;

public class RuiJuSigner {
    public static String sign(String method, String path, String query, String ts, String nonce, String secret) throws Exception {
        String payload = String.join("\n", method.toUpperCase(), path, query, ts, nonce);
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256Hmac.init(secretKey);
        byte[] hash = sha256Hmac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
        return HexFormat.of().formatHex(hash);
    }
}
RESTful Endpoint Directory

核心接口端点目录与请求参数字典

点击下方任意端点条目即可展开查阅其完整的 Query 参数约束、默认值、数据类型以及 cURL 调用示例。足球专项盘口字段定义可同步参阅 足球盘口接口。

Snapshots & Historical Trajectory

盘口全量快照与历史赔率变动接口规范

全量盘口快照 (Snapshot API) GET /v3/football/odds/snapshot

多机构盘口矩阵同步(初盘 vs 即时盘)

用于冷启动初始化或定时对账。单次调用返回指定赛事列表下所有主流数据商(涵盖 Pinnacle、Bet365、SBO、皇冠等 18+ 核心源)的初盘(Opening Odds)与当前即时盘(Current Live/Pre-match Odds)。

主盘与附加盘口线 (Mainline & Alt Lines)
通过参数 line_depth=all 可同时拉取诸如 -0.5, -0.75, -1.0, -1.25 等同场次多层亚洲让球深盘数据。
增量水位版本对比 (Version Sequence)
每个盘口节点均附带 64 位递增 update_seq 序列号,便于本地缓存比对丢弃过期报文。
赔率历史流水 (History Tick API) GET /v3/football/odds/history

毫秒级历史变盘轨迹与滚球比分关联

针对量化模型训练、水位走势图表绘制及赛后复盘场景,提供从开盘时刻至完场哨响的完整赔率跳动时间序列(Time-Series Ticks)。

比赛时间 主客比分 盘口线 (Line) 主队水位 / 客队水位 状态
Pre-match 0 - 0 -0.5/1 0.94 / 0.96 OPEN
24'18" 0 - 0 -0.5 0.88 / 1.02 OPEN
37'02" (危险进攻) 0 - 0 -0.5 0.88 / 1.02 SUSPENDED
38'15" (进球后重开) 1 - 0 -1.25 0.98 / 0.90 OPEN
Full-Duplex WebSocket Stream

实时赔率流 WebSocket 协议与交互帧规范

查看滚球流压测基准

对于滚球(In-Play)高频赔率变动与瞬时封盘信号(Bet Stop),强烈建议使用 WebSocket 持久连接替代 HTTP 轮询。连接建立后须在 5秒内发送鉴权订阅帧,并维持每 15秒一次的应用层 Ping/Pong 心跳。

1. 频道订阅指令帧 (Client -> Server) op: "subscribe"
{
  "op": "subscribe",
  "req_id": "sub_1001",
  "args": [
    {
      "channel": "football.odds.delta",
      "market_types": ["AH", "OU", "1X2"],
      "bookmakers": ["pinnacle", "bet365"]
    },
    {
      "channel": "football.betstop.signal"
    }
  ]
}
2. 应用层心跳保活帧 (Ping / Pong) 间隔: 15,000ms
// 客户端发送:
{"op": "ping", "ts": 1714568415000}

// 服务端响应:
{"op": "pong", "ts": 1714568415000, "server_ts": 1714568415004}
WSS 增量推送帧实时模拟器 (Delta Frame Inspector)
Data Schema & Serialization

标准响应报文结构(JSON 与 Protobuf IDL)

Content-Type: application/json; charset=utf-8
{
  "code": 0,
  "message": "OK",
  "trace_id": "tr_sz01_99481029481a",
  "server_ts": 1714568420812,
  "data": {
    "match_id": 8492014,
    "sport_id": 1,
    "league": {
      "league_id": 10039,
      "name_zh": "英格兰足球超级联赛",
      "name_en": "English Premier League",
      "tier": 1
    },
    "match_status": "IN_PLAY",
    "match_clock": {
      "period": "2H",
      "minute": 64,
      "second": 19,
      "score_home": 2,
      "score_away": 1,
      "corners_home": 6,
      "corners_away": 4,
      "red_cards_home": 0,
      "red_cards_away": 0
    },
    "markets": [
      {
        "market_type": "AH",
        "market_name": "亚洲让球盘 (全场滚球)",
        "bookmaker_id": 102,
        "bookmaker_code": "pinnacle",
        "update_seq": 90048192041,
        "updated_at": 1714568420795,
        "bet_stop": false,
        "lines": [
          {
            "line_id": "ln_8492014_102_ah_main",
            "is_main": true,
            "handicap": "-0.5",
            "base_score": "2-1",
            "status": "OPEN",
            "odds": {
              "format": "HK",
              "home": "0.920",
              "away": "0.980",
              "malay_home": "0.920",
              "malay_away": "-1.020"
            }
          }
        ]
      }
    ]
  }
}
Error Dictionary & Rate Limiting

赔率API状态码字典与网关频控策略

标准业务错误码与故障排查建议

业务状态码 (code) HTTP 状态 宏定义标识 触发原因与研发处理方案

网关令牌桶频控等级 (Token Bucket Quotas)

授权级别 REST 并发配额 WSS 并发连接数 超限退避策略
开发者沙盒 (Sandbox) 60 req / min 2 路长连接 触发 HTTP 429,冷却 10 秒
专业版 (Pro Stream) 1,200 req / min 25 路长连接 支持突发弹性 20% 缓冲
企业专线 (Enterprise BGP) 6,000+ req / min 不限 (独占集群) 独立网关节点与双链路热备

频控响应头实时监测

每次 HTTP 响应均包含以下频控遥测 Header,建议客户端中间件据此实现自适应限流与指数退避重试(Exponential Backoff):

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1148
X-RateLimit-Reset: 1714568460
Retry-After: 0

想要跳过底层签名拼接与断线重连逻辑?

我们提供原生封装了本地内存盘口树、自动序列号校验与 Protobuf 解码器的官方多语言 SDK,或直接查阅生产环境高并发架构最佳实践。