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）驗證，不開放給程式化呼叫。