API · 使用说明

天元之弈 · 量化脚本与自动化调用｜适用于竞价排行等只读数据

一、适用场景

开放 API 面向量化脚本、定时任务、内部分析服务等机器调用场景。 与官网浏览器访问不同，脚本需使用 API Key 鉴权，无需 MySQL 直连或爬取网页。

当前开放接口覆盖竞价排行、选股池，以及策略展示跟单： 每日主板分析 / 创业板分析 对应竞价排行 daily/main、daily/chinext，同包返回上证当日开盘仓位档位 indexOpenPosition； 主板选股池 /v1/open/pool/main-board/daily 面向 09:05 拉池，同包返回上证昨收仓位档位 indexClosePosition，供次日竞价建仓门禁使用； 策略展示跟单 /v1/open/showcase/strategies/{code}/today 只回答当天买什么（数据来自展示看板已落库成交，不另算选股）。

二、终端 / 脚本要填什么

调用方不需要在后台登记「终端名称」；系统会根据 IP 与 User-Agent 自动统计活跃来源。

三、调用示例

1. curl · 主板 daily/main

curl -s \
  -H "X-API-Key: ak_live_你的完整Key" \
  "https://www.playwithgod.fun/api/v1/open/market/auction-ranking/daily/main?trade_date=2026-03-17"

2. curl · 创业板 daily/chinext

权限 scope 与主板相同（auction_ranking:daily），响应结构一致，board 为 chinext。

curl -s \
  -H "X-API-Key: ak_live_你的完整Key" \
  "https://www.playwithgod.fun/api/v1/open/market/auction-ranking/daily/chinext?trade_date=2026-03-17"

3. 环境变量 + 项目脚本

export OPEN_API_KEY='ak_live_你的完整Key'
export OPEN_API_BASE='https://www.playwithgod.fun/api'

python3 quant-platform/scripts/jq_sync/fetch_daily_main.py --trade-date 2026-03-17
python3 quant-platform/scripts/jq_sync/fetch_daily_chinext.py --trade-date 2026-03-17

4. Python

import os
import requests

API_KEY = os.environ["OPEN_API_KEY"]
url = "https://www.playwithgod.fun/api/v1/open/market/auction-ranking/daily/main"
resp = requests.get(
    url,
    headers={"X-API-Key": API_KEY},
    params={"trade_date": "2026-03-17"},
    timeout=30,
)
resp.raise_for_status()
body = resp.json()
data = body["data"]      # 业务数据
meta = body.get("meta")  # 缓存、配额等

四、响应格式

成功时返回统一包络结构，业务数据在 data 字段中：

{
  "code": 0,
  "message": "ok",
  "request_id": "req_...",
  "data": {
    "tradeDate": "2026-03-17",
    "board": "main_board",
    "poolCount": 3,
    "items": [ /* Top3：竞价涨幅、收盘涨幅、RSI/MACD、目标价等 */ ],
    "indexOpenPosition": {
      "positionCapPct": 99,
      "openVsMa3Pct": 0.859,
      "openVsMa5Pct": 0.912,
      "cap99Streak": 1,
      "cap20Streak": 0,
      "entryGateAllow": 1,
      "entryGateMode": "ma_dev_band",
      "entryGateReason": "ok_cap99_day1_ma5",
      "regimeLabel": "多头排列·开盘双上",
      "positionRegime": "strong_bull",
      "ruleVersion": "v2"
    }
  },
  "meta": {
    "trade_date": "2026-03-17",
    "board": "main_board",
    "cache_hit": true,
    "used_today": 12,
    "limit_per_day": 2000
  }
}

daily/chinext 响应相同，仅 data.board 为 chinext、items 为创业板 Top3；indexOpenPosition 仍为上证大盘档位，建仓脚本需读取 data.indexOpenPosition.positionCapPct（20～99）。cap99Streak / cap20Streak 为连续处于该档附近的交易日数（含当日）。建仓门禁用库字段 entryGateAllow（1 可开 / 0 禁止）、entryGateMode、entryGateReason，由写入端计算后透出；客户端读 entryGateAllow，缺字段时再回退本地计算。缺 cap20Streak 时请勿把强空档当成 streak=1。

排障时可记录 request_id，便于在后台审计日志中定位。

失败时 HTTP 状态码非 200，响应体通常含业务错误码 code，例如：

{
  "code": 40402,
  "message": "竞价数据未就绪",
  "retry_after_sec": 5
}

五、配额与限制

• 限流与配额按 API Key 计算；多人共用一把 Key 会共用额度。
• 每个账号最多 5 把有效 Key，建议每人自建、专 Key 专用。
• 9:25–9:35 竞价高峰时段缓存 TTL 较短，脚本请避免高频无意义轮询。

六、常见错误

除 HTTP 状态码外，请优先解析响应 JSON 中的 code 字段，勿用字符串包含判断（例如 40401 含子串 401 会误判 Key 失效）。

早盘 9:25–9:35 服务端会对当日请求做短重试；若仍返回 40402，说明竞价入库尚未完成，客户端继续等待重试即可，不是 API Key 问题。

七、主板选股池（09:05）

路径 GET /v1/open/pool/main-board/daily，与竞价 daily/main 共用 scope auction_ranking:daily， 不放在 /market/* 下。返回约 500 只主板池标的（含日线门禁字段），并同包返回上证昨收仓位档位 indexClosePosition。

查询参数 trade_date 表示选股池日 T+1（例如 2026-08-21）。 服务端用上一交易日 T（例如 2026-08-20）去读收盘 CAP；data.tradeDate 仍是池日， data.indexClosePosition.tradeDate 才是昨收日，二者不相等。

indexOpenPosition 与 indexClosePosition

客户端次日集合竞价是否建仓，读池接口的 indexClosePosition.entryGateAllow / positionCapPct； 不要用竞价接口的 indexOpenPosition 代替。不单独提供 /index-regime 接口。

indexClosePosition 字段

camelCase；结构对齐 indexOpenPosition，仅将 open* 换成 close*。标的固定上证 SHSE.000001。

meta.data_ready 现表示池 + 昨收 CAP 均就绪（池有行且 indexClosePosition 非空）。 仅池未灌数仍返回 40402；池已有但昨收档位未写入时 HTTP 200，indexClosePosition 为 null，meta.data_ready=false，客户端应短间隔重试。

items 中的 dailyRsi、dailyTrend 等为日线门禁字段；库内列为空时服务端会按 stock_daily 在 API 层补算（截至上一交易日收盘）。

1. curl · 主板池

curl -s \
  -H "X-API-Key: ak_live_你的完整Key" \
  "https://www.playwithgod.fun/api/v1/open/pool/main-board/daily?trade_date=2026-08-21"

{
  "code": 0,
  "data": {
    "tradeDate": "2026-08-21",
    "poolCount": 500,
    "items": [],
    "indexClosePosition": {
      "tradeDate": "2026-08-20",
      "symbol": "SHSE.000001",
      "closePrice": 3894.422,
      "positionCapPct": 31,
      "entryGateAllow": 1,
      "entryGateMode": "ma_dev_band",
      "entryGateReason": "ok_cap",
      "l1RatioMaxAllow": 1,
      "l1NearSweetAllow": 1
    }
  },
  "meta": { "data_ready": true, "trade_date": "2026-08-21" }
}

早盘配套：昨竞价与 tick Top3

以下接口与主板池同一条早盘链路，共用 scope auction_ranking:daily。

2. curl · 昨竞价

curl -s \
  -H "X-API-Key: ak_live_你的完整Key" \
  "https://www.playwithgod.fun/api/v1/open/auction-prev/daily?trade_date=2026-08-22"

3. curl · tick Top3 上报

curl -s -X POST \
  -H "X-API-Key: ak_live_你的完整Key" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: jq-terminal-01" \
  -d '{
    "tradeDate": "2026-08-22",
    "selectionSource": "main_board_tick",
    "poolCount": 63,
    "eligibleCount": 18,
    "scoringVersion": "tick_scoring@1.0.0",
    "updatedAt": "2026-08-22 09:24:52",
    "top3": [{
      "symbol": "SHSE.600000",
      "stockName": "浦发银行",
      "preClose": 12.34,
      "openPrice": 12.56,
      "openChangePct": 1.78,
      "volume": 10303.0,
      "turnover": 12945678.0,
      "auctionTurnoverRatio": 2.3,
      "volumeRatio": 1.8,
      "bidV1": 500.0,
      "auctionScore": 72.0,
      "auctionGrade": "A"
    }]
  }' \
  "https://www.playwithgod.fun/api/v1/open/client/tick-top3/report"

八、策略展示跟单（当天买什么）

只回答四件事：今天开不开仓、买什么、什么价格、什么时候。 鉴权 X-API-Key，scope showcase:copy（新建 Key 默认带上；旧 Key 请重签或新建）。 不另算选股、不代下单、不返回卖出（隔夜默认次日竞价卖，跟单端自行处理）。

工作日看板 09:28 / 09:30 / 09:35 重建。客户端 09:28 起每 30s 轮询到 ready=true 或 09:36，按 orderTime 赶集合竞价。

何时可调

接口全天都能请求（需 X-API-Key）。变的是当天指令何时齐：看 data.ready，不要看 HTTP 是否 200。

旧 Key 若没有 scope showcase:copy，会 403；请在控制台重签或新建 Key。

code：main_ratio_top1_overnight 激进组；main_ratio_stable_h3_5 稳健组。

today 的 data

buyPrice 与展示看板含滑点成交价不同；实盘以撮合为准；不构成投资建议。不返回净值曲线、卖单、滑点、仓位档、跳过原因。

1. curl · 当天买入

curl -s \
  -H "X-API-Key: ak_live_你的完整Key" \
  "https://www.playwithgod.fun/api/v1/open/showcase/strategies/main_ratio_top1_overnight/today"

{
  "code": 0,
  "message": "ok",
  "data": {
    "ready": true,
    "tradeDate": "2026-09-11",
    "orderTime": "09:30",
    "code": "main_ratio_top1_overnight",
    "openPosition": true,
    "symbol": "SZSE.002212",
    "stockName": "天融信",
    "buyPrice": 6.79104
  },
  "meta": { "rebuildAt": "09:28" }
}

2. 示例脚本

python quant-platform/scripts/jq_sync/fetch_showcase_today.py --code main_ratio_stable_h3_5

九、安全建议

• API Key 等同于密码：不要写入代码仓库、截图或群聊。
• 泄露后立即在控制台吊销并新建 Key。
• 生产环境使用专用账号创建 Key，避免长期使用管理员 Key。
• 可在控制台「终端详情」查看活跃 IP，发现异常来源及时吊销。

十、与官网其他接口的区别

文档随产品迭代更新。当前已开放主板/创业板 daily、09:05 主板池与昨竞价、09:24 tick Top3 上报、行业 Top20 levels、绩效对账；dates、全量 list 等将在后续版本开放； Key 管理、终端统计请见 控制台 → API 密钥。