OREStats API v1

付费端点位于 /api/v1/*。每一个请求都必须带上 Authorization: Bearer ore_… 头。请至 /pricing 订阅。

通过 API 订阅

向 POST /api/v1/subscribe 发出请求，并带上 { ownerPubkey }——服务器会返回一组唯一的识别码（nonce）与应付 ORE 数量。
将上一步 POST 响应中指定金额（priceOre）的 ORE，转至同一份响应中的金库地址，并把识别码（nonce）放入转账的备注字段（SPL Memo）。
向 PUT /api/v1/subscribe 发出请求，并带上 { nonce, txSig, ownerPubkey }——服务器会在链上验证、激活订阅，并返回您的 API 密钥。
之后所有 /api/v1/* 的请求，请带上 Authorization: Bearer ore_… 头。

付款信息

金库钱包: A9HLwE6wCm7Hedo7771nwsX8TyArv7rgdVQMo9dgDGZF

ORE 代币合约: oreoU2P8bN6jkk3jbaiVxYnG1dCXcYxwhwyK9jSybcp

网络: Solana 主网

GET/api/v1/pricing公开

用途：查询当前一个月订阅所需的 ORE 数量。价格随订阅人数阶梯式上调；响应中也会告诉您下一个阈值、以及到达阈值后的新价格。

响应：

{
  "activeSubs": 17,
  "oreNow": 0.1,
  "nextThreshold": 100,
  "oreAtNextThreshold": 0.2,
  "treasury": "...",
  "oreMint": "..."
}

POST/api/v1/subscribe公开

用途：订阅流程第一步。返回一笔一次性的 SPL 代币转账指令（含金额与识别用备注），请用您的钱包签名后发送。

参数：

ownerPubkey— Solana base58 编码的公钥，将成为这把 API 密钥的拥有者

请求体：

{ "ownerPubkey": "..." }

响应：

{
  "nonce": "ore-pay-...",
  "priceOre": 0.1,
  "instructions": { "to": "...", "memo": "ore-pay-...", "amountBaseUnits": "10000000000", "mint": "..." },
  "expiresAt": "..."
}

PUT/api/v1/subscribe公开

用途：订阅流程第二步。SPL 转账上链确认后，提交交易签名换取 API 密钥。明文密钥只会显示这一次。

参数：

nonce— 上一步 POST /subscribe 返回的识别码
txSig— 已确认的 SPL 转账签名，必须带有第一步的备注
ownerPubkey— 必须与付款钱包（POST 时带入的）为同一把

请求体：

{ "nonce": "...", "txSig": "...", "ownerPubkey": "..." }

响应：

{
  "apiKey": "ore_xxx (shown ONCE)",
  "subscriberId": "sub_...",
  "paidUntil": "..."
}

GET/api/v1/live付费（须带 Bearer 密钥）

用途：当前轮次的实时快照——每格当前的下注金额、剩余秒数、上一轮结果。开销极轻，可放心每 1-2 秒轮询。

响应：

当前轮次快照（已投注金额、人数、剩余秒数、上一轮结果）

GET/api/v1/stream付费（须带 Bearer 密钥）

用途： /live 端点的实时推送版本。每次链上的赌盘或轮次账户有变动，就推送最新快照。随时断线重连都行，下一条事件即为最新状态。

响应：

服务器推送事件（SSE）流；每次链上的赌盘或轮次数据变动，就推送最新快照

GET/api/v1/stats付费（须带 Bearer 密钥）

用途：整体累计统计：累计卡方检验、每格命中次数与累计投注 SOL、历史累计投注 SOL、实际庄家抽成。

响应：

聚合统计数据（卡方检验、每格命中、累计投注 SOL、实际庄家抽成）

GET/api/v1/rounds?limit=100付费（须带 Bearer 密钥）

用途：最近 N 轮已收录数据（由新到旧）。需要批量抓取时请用本端点；若要低延迟收到新轮次通知，请改用 /events/stream。

参数：

limit— 返回轮数；默认 100，最多 10000

响应：

最近 N 轮已收录数据（轮次 id、每格投注、每格人数、中奖格、总投注、总赔付）

GET/api/v1/rounds/{id}付费（须带 Bearer 密钥）

用途：单轮详情；附上上一轮与下一轮的编号，方便像翻书一样浏览历史。

参数：

id— 轮次编号（路径参数）

响应：

单轮详情，附上上一轮与下一轮的编号

GET/api/v1/grid/{n}?limit=200付费（须带 Bearer 密钥）

用途：单格统计，附上最近的命中 / 未命中序列（1 = 命中、0 = 未命中），方便绘图。

参数：

n— 格子编号 0–24（路径参数）
limit— 序列长度；默认 200

响应：

单格统计，附上最近的命中 / 未命中序列（1 ≤ n ≤ 25）

GET/api/v1/events?since=N&limit=M&kind=X付费（须带 Bearer 密钥）

用途：轮询式事件日志。包含干旱结束、巨额轮、价格阶梯跨越、里程碑、订阅变动等事件。可指定 since 获取该编号之后的新事件。

参数：

since— 事件编号游标；只返回编号大于 since 的事件
limit— 单次最多返回几条；默认 100
kind— 可选的事件类型筛选：drought_broken | big_round | tier | milestone | subscription

响应：

{
  "count": 12,
  "lastId": 47,
  "events": [
    { "id": 47, "ts": "...", "kind": "drought_broken", "grid": 8, "drought": 91, "roundId": 247101 },
    { "id": 48, "ts": "...", "kind": "big_round", "roundId": 247155, "deployedSol": 8.94, "thresholdSol": 8.15, "multiplier": 1.10, "winningSquare": 12, "totalMiners": 209 },
    ...
  ]
}

GET/api/v1/events/stream?since=N&kind=X付费（须带 Bearer 密钥）

用途：与 /events 同一份事件日志的实时推送版。连接时会重放最后 50 条（或 since 之后的事件），之后实时推送新事件。

参数：

since— 可选的重放游标；省略时会重放最后 50 条
kind— 可选的事件类型筛选（同 /events）

响应：

server-sent events; replays last 50 (or events since cursor) on connect, then pushes each new event as it fires (drought / streak / big round / tier / milestone / subscription).

GET/api/v1/dump?from=X&to=Y&limit=10000付费（须带 Bearer 密钥）

用途：历史数据批量导出——以 from / nextFrom 游标翻页获取全部已收录轮次。建议用于初次同步建库；后续改用 /events/stream 做增量更新。

参数：

from— 起始轮次编号（含本条）
to— 可选的结束轮次编号（含本条）
limit— 每页条数；默认 5000，最多 10000

响应：

{
  "count": 5000,
  "from": 228237,
  "to": 233236,
  "hasMore": true,
  "nextFrom": 233237,
  "rounds": [ { id, deployed[25], count[25], winningSquare, totalDeployed, totalWinnings }, ... ]
}

POST/api/v1/reissue公开

用途：重新签发 API 密钥流程第一步。返回一段消息字符串，请用拥有现有订阅的钱包对它签名。

参数：

ownerPubkey— 原始订阅所属的钱包公钥

请求体：

{ "ownerPubkey": "..." }

响应：

{ "nonce": "ore-reissue-...", "message": "OREStats reissue ... @ ...", "expiresAt": "..." }

PUT/api/v1/reissue公开

用途：重新签发流程第二步。提交钱包签名后，旧密钥立即作废，并返回新的密钥（同样只显示一次）。

参数：

nonce— 上一步 POST /reissue 返回的识别码
ownerPubkey— 必须与 POST 时相同的钱包
signatureBase64— 对消息字符串以 ed25519 签名后，再以 base64 编码的字符串

请求体：

{ "nonce": "...", "ownerPubkey": "...", "signatureBase64": "..." }

响应：

{ "apiKey": "ore_xxx (NEW, old key revoked)", "subscriberId": "sub_...", "paidUntil": "..." }

策略实验室

构建、回测、实时追踪参数化策略。创建、回测、分析三个端点共用同一份策略配置 —— 各字段可用值请参阅本区块最下方的对照表。

POST/api/v1/lab/strategies付费（须带 Bearer 密钥）

用途：创建策略。启用后，OREStats 会自动为每一个新轮次记录一条纸面预测，并提供实时模拟统计。

参数：

name— 显示用名称，不可为空字符串
dsl— 完整的策略配置：base_strategy、params、可选的 filters[]；可用值请见下方对照表

请求体：

{
  "name": "my cold-5",
  "dsl": {
    "base_strategy": "cold",
    "params": {
      "bet_size_lamports": 200000,
      "num_squares": 5,
      "sizing_mode": "flat",
      "max_bet_per_square_lamports": 5000000,
      "tx_fee_lamports": 10000
    },
    "filters": [
      { "metric": "current_drought_min", "op": ">=", "value": 30 }
    ]
  }
}

响应：

{
  "strategy": {
    "id": "...", "owner": "...", "name": "...",
    "dsl": { "base_strategy": "...", "params": { ... }, "filters": [ ... ] },
    "createdAt": "...", "updatedAt": "...", "active": true
  }
}

GET/api/v1/lab/strategies付费（须带 Bearer 密钥）

用途：列出您拥有的策略，附上实时模拟统计（已结算轮数、中奖次数、根据实际轮次结果计算的收益率）。

响应：

{
  "count": 3,
  "strategies": [
    {
      "id": "...", "name": "...", "dsl": { ... }, "active": true,
      "stats": { "roundsSettled": 412, "roundsWon": 88, "netProfitSol": 0.123, "roiPercent": 4.7 }
    },
    ...
  ]
}

GET/api/v1/lab/strategies/{id}付费（须带 Bearer 密钥）

用途：读取您拥有的单一策略，附上预测条数。

参数：

id— 策略编号（路径参数）

响应：

{ "strategy": { ... }, "predictionCount": 412 }

PATCH/api/v1/lab/strategies/{id}付费（须带 Bearer 密钥）

用途：改名或切换启用状态。停用的策略不再对新轮次进行预测，但历史数据会保留。

参数：

name— 新的显示名称（选填）
active— true 恢复预测、false 暂停（选填）

请求体：

{ "name": "renamed", "active": false }

响应：

{ "strategy": { ... } }

DELETE/api/v1/lab/strategies/{id}付费（须带 Bearer 密钥）

用途：永久删除您拥有的策略。所有相关预测会一并删除；若该策略已上排行榜，排行榜上的项目也会一并消失。

参数：

id— 策略编号（路径参数）

响应：

{ "ok": true }

GET/api/v1/lab/strategies/{id}/forward付费（须带 Bearer 密钥）

用途：单一策略的实时模拟统计：净利（SOL）、收益率、胜率、权益曲线、最大回撤、最长连败、尚未结算轮数。

参数：

id— 策略编号（路径参数）

响应：

{
  "strategyId": "...",
  "roundsObserved": 432,
  "roundsBet": 412, "roundsWon": 88,
  "squaresBet": 2060, "squaresWon": 92,
  "netProfitSol": 0.12, "totalStakeSol": 2.6,
  "roiPercent": 4.7, "winRate": 0.21, "perSquareWinRate": 0.045,
  "maxDrawdownSol": 0.08, "maxStreak": 12,
  "equityCurve": [{ "round": 247001, "balanceLamports": 0 }, ...],
  "pendingCount": 1
}

POST/api/v1/lab/backtest付费（须带 Bearer 密钥）

用途：在已收录的历史轮次上重新跑一次策略。返回完整回测结果：每轮盈亏、每格贡献、权益曲线、提前结束原因等。

参数：

dsl— 策略配置（与创建时同一份格式）
fromRoundId— 重放区间下界（含本条），选填
toRoundId— 重放区间上界（含本条），选填

请求体：

{
  "dsl": { "base_strategy": "...", "params": { ... }, "filters": [ ... ] },
  "fromRoundId": 200000,
  "toRoundId": 247000
}

响应：

{
  "result": {
    "totalRounds": 47000, "roundsBet": 9200, "roundsWon": 1800,
    "squaresBet": 46000, "squaresWonOn": 1900,
    "netProfitLamports": ..., "netProfitSol": ...,
    "totalStakeLamports": ..., "totalStakeSol": ...,
    "totalRecoveryLamports": ..., "totalRecoverySol": ...,
    "roiPercent": ..., "winRate": ..., "perSquareWinRate": ...,
    "maxStreak": ..., "capHits": ..., "totalCapLossSol": ...,
    "minWalletSol": ..., "maxDrawdownSol": ...,
    "rangeMin": 200000, "rangeMax": 247000,
    "exitedEarly": null,
    "exitRoundId": 0,
    "equityCurve":   [{ "round": ..., "balanceLamports": ... }, ...],
    "perSquare":     [{ "square": 0, "betCount": ..., "winCount": ..., "netLamports": ... }, ...],
    "perRoundPnlLamports": [...],
    "streakRunLengths":    [...]
  }
}

POST/api/v1/lab/analytics付费（须带 Bearer 密钥）

用途：重量级分析包：蒙特卡洛（Monte-Carlo）置信区间，加上四份嵌套回测（参数扫描）。第一次调用约 3-6 秒，缓存预热后在 1 秒内响应。缓存以策略配置为依据。

参数：

dsl— 策略配置（与 backtest 同一份格式）

请求体：

{ "dsl": { ... } }

响应：

{ "analytics": { ... } }

GET/api/v1/lab/leaderboard公开

用途：公开排行榜。只暴露收益率与样本数，策略内容隐藏；订阅者必须通过详情端点才能看到完整策略内容。

响应：

{
  "generatedAt": "...",
  "minRoundsToQualify": 1000,
  "count": 14,
  "entries": [
    { "id": "...", "name": "...", "ownerShort": "abcd...wxyz", "roiPercent": ..., "roundsSettled": ... },
    ...
  ]
}

GET/api/v1/lab/leaderboard/{id}付费（须带 Bearer 密钥）

用途：排行榜单一项目的完整策略内容，附上实时模拟摘要与权益曲线。仅限订阅者使用；公开访客只能看到列表上的收益率。

参数：

id— 策略编号（路径参数）

响应：

{
  "strategy": {
    "id": "...", "name": "...", "ownerShort": "abcd...wxyz",
    "dsl": { ... },
    "createdAt": "..."
  },
  "forwardTest": {
    "roundsSettled": ...,
    "netProfitSol": ...,
    "equityCurve": [{ "round": ..., "balanceLamports": ... }, ...]
  }
}

策略参数（DSL）— 可用值对照表

base_strategy（基础策略） — cold, spread, drought, custom_squares, hot, top_hit_rate, bottom_hit_rate, recent_winners, anti_spread, min_miners, corners, edges, center_block, diagonal_main, diagonal_anti, row, column, checkerboard, all_25

params.sizing_mode（下注额模式） — flat, martingale, reverse_martingale, fibonacci, dalembert, kelly

filters[].metric（触发条件指标） — rounds_since_last_big, consecutive_losses, current_drought_min, current_drought_max, total_deployed_pctile, total_miners, rounds_since_big_round, chi_square_p_recent

filters[].op（比较运算） — < , <= , > , >= , ==

params.* 数值区间（超出范围会被服务器自动夹在区间内）：
  bet_size_lamports             required, (0, 1e8]
  num_squares                   1..25
  drought_threshold             1..1000
  custom_squares                int[] in 0..24
  hit_rate_lookback             50..20000
  row_index, column_index       0..4
  martingale_multiplier         1..10
  loss_streak_threshold         1..100
  dalembert_step_lamports       1..1e6
  kelly_fraction                0.0001..1
  kelly_bankroll_lamports       >= 1
  max_bet_per_square_lamports   1..1e8
  tx_fee_lamports               0..1e7
  stop_loss_streak              1..1000
  cooldown_after_loss_rounds    0..500
  take_profit_lamports          >= 0
  session_stop_loss_lamports    >= 0

用量上限：
  max 100 strategies per account

用量限制与规范

每把 API 密钥：每秒 5 次请求，短时可冲至 60 次。超过会返回 HTTP 429，并在 Retry-After 头附上需等待的秒数。
API 密钥为一次性明文，只显示一次：请务必妥善保存——服务器端只保留哈希值。
共用密钥会被检测到（同一密钥来自多个 IP），可能导致该密钥被吊销。
仪表盘专用端点（/api/live*）必须通过浏览器会话与来源（Origin）验证，不对程序化调用开放。