Sporttery Odds API

English · 简体中文

A Cloudflare Worker REST API + local MCP server that implements a clean, agent-callable 竞彩足球 (China Sports Lottery football) odds service. It serves the latest odds and derives everything purely from those odds — implied & no-vig probabilities, 返还率 (return rate), fair odds, Kelly/value vs. a reference, and full 单关/过关 (parlay) prize calculation.

┌── live odds ──────────────┐   ┌── pure math (no upstream) ──────────────┐
│ GET /api/matches          │   │ POST /api/derive   赔率推导               │
│ GET /api/match/:id        │   │ POST /api/value    凯利指数/价值          │
└───────────────────────────┘   │ POST /api/parlay   单关/过关奖金          │
                                 │ GET  /api/parlay/types · GET /api/meta   │
                                 └──────────────────────────────────────────┘

• Agent-first. JSON in / JSON out, open CORS, self-describing /api/meta, optional API-key auth, plus a local MCP server exposing the same power.
• Pure, tested math. All derivation/parlay logic lives in dependency-free modules with unit tests — no build step (npm test).
• Simple data path. Per-colo Cache → upstream (optionally through an upstream-reachable relay via UPSTREAM_PROXY). The local MCP server fetches sporttery directly.

⚠️ Geo-block. The upstream is geo-restricted and rejects datacenter IPs (incl. Cloudflare) with HTTP 567. To serve live odds from the deployed Worker, set UPSTREAM_PROXY to a forwarding relay that can reach the upstream. When the runtime can reach the upstream directly (local dev, or the MCP server), no proxy is needed. The compute endpoints (derive/value/parlay) need no upstream and work everywhere.

---

Table of contents

• Quick start
• Project layout
• Architecture & data flow
• Authentication
• REST endpoints
• The math (赔率推导)
• Pools & outcome codes
• Parlay (过关) rules
• MCP server (local stdio)
• Deployment
• Configuration
• Caching