API 通用約定
適用於所有端點的規則：URL 配置、回應封套、代號、單位、時間戳記、分頁與快取。
基礎 URL 與版本
所有端點都位於同一個基礎 URL 之下，並以 HTTPS GET 呼叫。目前的路徑屬於 v1 版本。在 v1 之內，變更只增不減：可能新增欄位與端點，既有欄位的名稱、型別與意義維持不變。破壞性變更會以新路徑推出，並事先在更新日誌中公告。
基礎 URL
https://www.coinboss.com/api回應封套
每個 JSON 回應的最上層都有 success 旗標。自研資料層的端點（/api/sd 底下的路徑）另外共用下列區塊：
| 欄位 | 說明 |
|---|---|
| success | 呼叫成功時為 true。請務必檢查。 |
| schema | 回應結構的識別碼與主版本號。 |
| now | 組裝回應時的伺服器時間，單位為毫秒。 |
| coverage | 納入了哪些交易所、哪些未提供及其原因，以及哪些因過期而被排除。 |
| method | 回應中每項彙總值背後的公式或規則。 |
| meta | 資料來源、時間戳記、時間視窗、品質等級、過期旗標、快取存活時間與備援行為。 |
較舊的端點回傳 success 與 data 欄位，可能不包含 coverage、method 或 meta。確切欄位請見各自的參考頁面。
幣種、合約與交易所
- coin 參數接受大寫的基礎幣種代號，例如 BTC 或 PEPE。
- 1000PEPE、kPEPE 這類乘數合約會併入其基礎幣種，數量也會一併換算。
- 交易所識別碼一律小寫，例如 binance、okx、bybit、hyperliquid。
- 合約代號依交易所的命名原樣回傳。若端點混合了 USDT 本位、USDC 本位、幣本位合約與交割合約，會以合約類型欄位加以區分。
- 代號與加密資產相同的代幣化股票及商品永續合約，不計入加密貨幣彙總。
單位
- 以 _usd 結尾的欄位為美元名義價值。
- 資金費率以小數表示，而非百分比：0.0001 代表 0.01%。以 _8h 結尾的欄位已歸一為 8 小時週期；原始週期會與原始費率一併回傳。
- 以 _pct 結尾的欄位為百分比：1.5 代表 1.5%。
- 除非欄位說明另有註明，持倉量一律為單邊美元名義價值。公布雙邊數字的交易所會在 method 區塊中註明。
- 部分舊版端點為保留精度，會以字串回傳小數。欄位表中的型別會顯示為 string(decimal)。
時間戳記
- 除非欄位說明另有註明，時間戳記一律為 UTC 的 Unix epoch 毫秒。
- observed_at 是所納入最新紀錄在交易所端的時間戳記；交易所未提供時為 null。
- received_at 是 CoinBoss 採集器儲存該筆紀錄的時間。
- fetched_at 是組裝回應的時間。若回應來自快取，它會比你的呼叫時間早，最多相差一個快取 TTL。
- 每日序列以 UTC 日界為準。
時間視窗與週期
- 時間視窗參數使用簡短代碼：1h、4h、12h、24h，部分端點另支援 3d、7d、30d、90d。各端點可接受的值列於參考頁面。
- 未知的時間視窗值會以 INVALID_PARAM 拒絕，或退回文件記載的預設值，依各參數的說明而定。
- 時間序列的區間大小取決於時間視窗，並標示於參考頁面。
分頁與排序
- 清單端點使用 limit 與 offset，或 page 與 size，依各端點文件而定。筆數設有上限；超過上限的值會被調降為上限。
- 回應若包含 total，它代表分頁前的資料列總數。
- 除非端點文件載明排序參數，否則排序方式固定。
null、0 與缺漏
- null 代表數值未知或無法取得。0 代表實際量測到的零。
- 圖表遇到 null 必須留白，不要內插。
- 欄位表中標示為「可能不存在」的欄位，可能完全不出現在物件中；請比照 null 處理。
快取
- 每個端點都有伺服器快取 TTL，標示於其參考頁面，也會以 meta.cache_ttl_s 回傳。X-Cache 標頭會回報 HIT、STALE 或 MISS。
- 大多數 GET 端點前方還有一層約十秒的短效邊緣快取。
- 輪詢頻率高於 TTL 只會得到相同的資料，徒然消耗你的速率限制額度。
WebSocket
WebSocket
wss://www.coinboss.com/ws- 串流為僅推送的 JSON。每則訊息都有 type 欄位。
- 斷線後請延遲再重新連線，並從對應的 HTTP 端點回補。
機器可讀的文件
端點目錄、每個端點的參數與欄位表、服務狀態以及品質矩陣，都能在 /api/meta 底下以 JSON 取得；整份目錄另提供 OpenAPI 3 文件。