体育盘口API文档:接口端点、签名鉴权与实时报文标准
欢迎查阅锐矩盘口API技术开放平台文档中心。本规范面向体育数据架构师与后端研发团队,完整定义全球足球、篮球及综合体育赛事的赛前盘口快照(Pre-match Snapshots)、滚球即时赔率流(In-Play Odds Stream)、亚盘/欧赔/大小球历史变动轨迹的标准接口协议。支持高吞吐 RESTful 轮询与全双工 WebSocket 增量推送。
所有 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% 的全量盘口快照传输体积,显著提升高并发响应速度。 |
API签名鉴权机制与沙盒验签计算器
为保障商业赛事数据流与客户配额安全,所有向 /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后填入此行。
在线签名原串预演沙盒
实时生成待签名字符串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
}
核心接口端点目录与请求参数字典
点击下方任意端点条目即可展开查阅其完整的 Query 参数约束、默认值、数据类型以及 cURL 调用示例。足球专项盘口字段定义可同步参阅 足球盘口接口。
| 参数名 (Parameter) | 数据类型 | 必选 | 说明与枚举值 |
|---|---|---|---|
盘口全量快照与历史赔率变动接口规范
GET /v3/football/odds/snapshot
多机构盘口矩阵同步(初盘 vs 即时盘)
用于冷启动初始化或定时对账。单次调用返回指定赛事列表下所有主流数据商(涵盖 Pinnacle、Bet365、SBO、皇冠等 18+ 核心源)的初盘(Opening Odds)与当前即时盘(Current Live/Pre-match Odds)。
line_depth=all 可同时拉取诸如 -0.5, -0.75, -1.0, -1.25 等同场次多层亚洲让球深盘数据。update_seq 序列号,便于本地缓存比对丢弃过期报文。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 |
实时赔率流 WebSocket 协议与交互帧规范
对于滚球(In-Play)高频赔率变动与瞬时封盘信号(Bet Stop),强烈建议使用 WebSocket 持久连接替代 HTTP 轮询。连接建立后须在 5秒内发送鉴权订阅帧,并维持每 15秒一次的应用层 Ping/Pong 心跳。
{
"op": "subscribe",
"req_id": "sub_1001",
"args": [
{
"channel": "football.odds.delta",
"market_types": ["AH", "OU", "1X2"],
"bookmakers": ["pinnacle", "bet365"]
},
{
"channel": "football.betstop.signal"
}
]
}
// 客户端发送:
{"op": "ping", "ts": 1714568415000}
// 服务端响应:
{"op": "pong", "ts": 1714568415000, "server_ts": 1714568415004}
标准响应报文结构(JSON 与 Protobuf IDL)
{
"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"
}
}
]
}
]
}
}
赔率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,或直接查阅生产环境高并发架构最佳实践。