GET可用
單一幣種的持倉量摘要
單一幣種的持倉量摘要（各交易所 OI 與變化）
GET
/api/oi/summary請求
查詢參數
| 名稱 | 型別 | 必填 | 預設值 | 可用值 | 說明 |
|---|---|---|---|---|---|
| coin | string | 選填 | BTC | — | 基礎幣種代號（大寫，例如 BTC）。 範例: BTC |
請求範例
curl -s "https://www.coinboss.com/api/oi/summary?coin=BTC"回應欄位
欄位表由真實回應產生，因此列出的正是端點實際回傳的內容。路徑中的 a[] 代表陣列元素，{*} 代表以動態名稱（例如幣種或交易所）為鍵的物件。
| 欄位 | 型別 | 單位 | 說明 |
|---|---|---|---|
| success | boolean | — | 請求成功時為 true。失敗時回應內容為 `{ success: false, code, error, request_id }`。 |
| coin | string | — | 幣種代號，大寫（例如 BTC）。 |
| price | number | — | 以計價貨幣表示的最新價格（除非另有註明，否則為 USD 或 USDT）。 |
| total_usd | number | USD | 總數。 |
| total_change_24h_pct | number | % | 總持倉量的 24h 變化：取目前與最接近 24 小時前的小時快照中皆存在的交易所，(Σ 當前 − Σ 前值) ÷ Σ 前值。 |
| total_change_24h_basis | object | — | `total_change_24h_pct` 的輸入值：配對到的交易所、基準小時、因基準凍結而被排除的合約，以及規則名稱；無法提供變化值時為 null。 |
| total_change_24h_basis.n_matched | number | — | 比較區間兩端皆存在的項目。 |
| total_change_24h_basis.prev_hour_ts | number | ms | 前一個小時區間的起始時間。 |
| total_change_24h_basis.frozen_excluded | object | — | 因來源數值沒有變動而被排除的資料列。 |
| total_change_24h_basis.frozen_excluded.n_baseline | number | — | 基準快照中的項目。 |
| total_change_24h_basis.frozen_excluded.n_current | number | — | 當前快照中的項目。 |
| total_change_24h_basis.frozen_excluded.cur_usd | number | USD | 當前值。 |
| total_change_24h_basis.frozen_excluded.prev_usd | number | USD | 基準值。 |
| total_change_24h_basis.rule | string | — | 比較規則的名稱；一律為 `same_exchange_pairing_nearest_hour_excl_frozen_baseline`。 |
| exchange_count | number | — | 交易所數量。 |
| data | array | — | 回應主體資料。 |
| data[] | object | — | 回應主體資料。 |
| data[].exchange | string | — | 交易所 ID，小寫（例如 `binance`）。 |
| data[].oi_usd | number | USD | 持倉量，以 USD 名義價值計。 |
| data[].share_pct | number | % | 佔總額的比例。 |
| data[].change_24h_pct | number|null | % | 24h 漲跌幅（百分比）。 |
| data[].change_4h_pct | number|null | % | 該交易所持倉量相對於其最接近 4 小時前之小時快照的變化；CME 每日公布一次，因此一律為 null。 |
| data[].is_daily | boolean | — | 僅出現在 CME 資料列且為 true，其持倉量每個交易日公布一次；其他資料列不含此欄位。 可能不存在 |
產生於 2026-11-11 23:00 UTC，依據 4 筆真實回應。
回應範例
/api/oi/summary?coin=BTC · 真實回應，擷取於 2026-11-13 03:57:41 UTC。 較長的陣列與對應表已截短顯示：data 原有 22 個項目。
- "success"true
- "coin""BTC"
- "price"68907.3
- "total_usd"49032953661.26
- "total_change_24h_pct"-3.57
- "total_change_24h_basis"
- "n_matched"22
- "prev_hour_ts"1794456000000
- "frozen_excluded"
- "rule""same_exchange_pairing_nearest_hour_excl_frozen_baseline"
- "exchange_count"22
- "data"
已驗證的樣本
除了上方的範例之外，探針還會以下列參數呼叫此端點，並在每次呼叫時檢查結構描述。
| 參數 | HTTP | 延遲 | 結果 |
|---|---|---|---|
| coin=ETH | 200 | 36 ms | 通過 |
| coin=SOL | 200 | 22 ms | 通過 |
| coin=ARKM | 200 | 22 ms | 通過 |
檢查於 2026-11-13 03:57:41 UTC
詳細資訊
- 身分驗證
- 無。公開端點。
- 速率限制
- 每個 IP 每分鐘 1200 次請求
- 伺服器快取
- 60s
- 邊緣微快取
- 10s
- 更新頻率
- 多數交易所每 60 s（與行情一併寫入；binance 前 50 名與 okx 有專用的 60 s 排程）；binance / bingx / aster / gate / htx 全量掃描每 5 min；幣本位／USDC 本位／交割合約每 120 s（每 5 min 併入共用資料表）；cme 每個交易日一次（04:10 UTC）
- 時間視窗
- 最新快照；變化以最接近「現在 - 24 h」與「現在 - 4 h」的小時區間為基準（誤差在 +/- 1 h 內）
- 資料來源
- 持倉量由自有採集器輪詢 22 家衍生品交易所（例如 binance、okx、bybit、gate、bitget、hyperliquid）的公開 REST API 取得，另加 CME 官方的每日成交量／持倉量報告。
- 交易所覆蓋範圍
- 23 個有新鮮資料列的來源（22 家交易所 + cme）；涵蓋所有合約類型（USDT／USDC／USD 正向、幣本位反向、永續與交割）；bybit 與 gate 依交易所揭露的口徑回報雙邊持倉量；超過 3 h（cme：120 h）的資料列會被排除
- 排序
- 固定的交易所順序（binance、cme、okx、bybit、bitget、gate、htx……），其後依字母排序
- 單位
- oi_usd in USD notional; share_pct / change_*_pct in percent; price in USD
- 計算方法
- per exchange: oi_usd = SUM over fresh contracts of the coin; share_pct = oi_usd / total x 100; change = (cur - prev) / prev x 100 with same-contract pairing (frozen baselines excluded); total_change_24h_pct = same-exchange paired change across all exchanges; cme compared with its previous published value and has no 4 h change
- 時間戳記
- Unix epoch 毫秒（UTC），除非欄位說明另有註明
- 回應格式
- json
- 穩定性
- 穩定版
即時狀態
可用檢查於 2026-11-13 03:57:41 UTCHTTP 20034 ms結構描述相符
近 30 天可用率
410 次檢查中有 100% 通過
錯誤
所有端點的失敗回應都採用同一種結構。完整清單請見錯誤頁面。 錯誤與速率限制 →
| 錯誤碼 | HTTP | 意義 | 處理方式 |
|---|---|---|---|
| INVALID_PARAM | 400 | 缺少必填參數，或某個值不被接受。已知時，`param` 會指出是哪個參數。 | 請勿原樣重試；請修正請求。 |
| UNAUTHORIZED | 401 | 已送出 `CB-API-KEY` 標頭，但金鑰未知或已撤銷。公開資料不需要金鑰——請移除該標頭或改用有效的金鑰。 | 請勿原樣重試。 |
| FORBIDDEN | 403 | 此路由不屬於公開 API（內部或僅限帳戶使用）。 | 請勿重試。 |
| NOT_FOUND | 404 | 未知的路由，或所請求的幣種／交易所／基金不存在。 | 請勿重試；請對照目錄檢查路徑與識別碼。 |
| RATE_LIMITED | 429 | 請求數超過每分鐘上限。`Retry-After` 會指出需等待的秒數。 | 等待 `Retry-After` 指定的時間後，再以退避策略重試。 |
| INTERNAL | 500 | 非預期的伺服器錯誤。訊息刻意保持籠統；回報時請附上 `request_id`。 | 幾秒後重試一次；若問題持續，請附上請求 ID 回報。 |
| UPSTREAM_FAILED | 503 | 此端點背後的資料來源未及時回應。不會以過期或替代的數字代替回傳。 | 以退避策略重試；並查看狀態頁面。 |
| UNAVAILABLE | 501 / 503 | 資料集暫時尚未就緒（快取預熱中），或此端點目前尚無合法的公開來源。 | 稍後重試；目錄會標示出設計上即無法使用的端點。 |
| REQUEST_FAILED | 200 | 部分舊版端點會以 HTTP 200 回應但帶有 `success: false`。請務必檢查 `success`，而不只是 HTTP 狀態碼。 | 視訊息而定；請當作失敗的請求處理。 |
試用
GET
/api/oi/summary可用參數
string · 預設 BTC — Base coin symbol (uppercase, e.g. BTC).
請求 URL
https://www.coinboss.com/api/oi/summary?coin=BTC選擇一個端點並按下「送出請求」。回應內容、標頭與耗時會顯示在這裡。
此分類的其他端點
- 單一幣種的持倉量 /api/sd/oi
- 各幣種跨交易所持倉量排行 /api/market/open-interest
- 單一幣種的 OI 堆疊圖序列 /api/oi/chart
- 單一幣種的彙總持倉量歷史 /api/oi/history
- 持倉量矩陣 /api/oi/matrix
- 單一幣種的持倉量摘要 /api/oi/summary