概述版本政策向後兼容性 V1 至 V2 遷移端點變更響應格式更新棄用時間表重大變更逐步遷移指南支援與資源

API 文件

API 遷移指南 — 版本升級

規劃並執行無縫的 API 版本升級。了解重大變更、棄用時間表以及 Smart Money API 版本間遷移的最佳實踐。

發佈於 2026 年 3 月 21 日 • 16 分鐘閱讀 • 進階

遷移概述

Smart Money API 持續開發並定期更新。本指南涵蓋版本管理、重大變更及如何無停機遷移整合。

遷移核心原則：

語意化版本控制 — 嚴格遵循 MAJOR.MINOR.PATCH 格式
長期支援 — 前一主要版本支援 24 個月以上
棄用警告 — 所有重大變更提前 6 個月通知
並行版本 — 遷移期間可同時運行 v1 和 v2
自動化測試 — 提供測試套件相容性工具

當前狀態： v1（現行版本）、v2（測試版，2026 年第二季正式推出）。v1 支援至 2028 年第一季。

版本政策

語意化版本控制

版本格式
API 版本：MAJOR.MINOR.PATCH
範例：2.1.3
MAJOR (2) - 重大變更，新架構
MINOR (1) - 向後兼容的功能
PATCH (3) - 錯誤修正、安全性更新

版本發佈週期

階段	持續時間	特性
Alpha	2-4 週	頻繁重大變更，僅供測試
Beta	4-8 週	基本穩定，收集社群回饋
發佈候選版	2-4 週	生產環境就緒，最終優化
正式發佈	24+ 個月	完整生產環境支援

30 秒取得 API 金鑰

準備開發？立即獲取免費 API 金鑰（每日 100 次呼叫，免綁卡），開始獲取實時巨鯨、資金費率及鏈上數據。

取得 API 金鑰 →

向後兼容性

版本相容性

在主要版本內，可安全升級至較新的次要/修補版本：

端點 URL — 保持不變
必填欄位 — 永不移除（僅新增可選欄位）
HTTP 狀態碼 — 現有情境維持不變
響應結構 — 核心欄位保持一致
身份驗證 — 驗證機制無變更

漸進式棄用

棄用時間表
// 第 1 個月：公告棄用
// 功能標記 Deprecation 標頭
Deprecation: version="2.2", sunset="2026-09-01"
// 第 3-6 個月：主動棄用期
// API 返回警告但仍可運作
X-Deprecation-Warning: 此端點將於 2026-09-01 移除
// 第 6 個月：最終移除
// 端點返回 410 Gone
HTTP/1.1 410 Gone

V1 至 V2 遷移

主要變更

REST API 重新設計 — 更清晰的資源端點
響應格式 — 統一包裝結構，強化錯誤處理
身份驗證 — 新增 OAuth 2.0 支援（仍可使用 API 金鑰）
速率限制 — 更細緻且明確的規則
Webhooks — 重新設計事件格式與簽章

端點對照表

v1 端點	v2 端點	變更內容
GET /whales	GET /v2/whales/tracking	重新組織，新增篩選功能
GET /funding	GET /v2/derivatives/funding-heatmap	必填交易所參數
GET /positions	GET /v2/derivatives/positions	新增聚合選項

端點變更

請求參數變更

V1 請求
// V1: 資金費率
GET /v1/funding?symbol=BTCUSDT&exchange=binance

V2 請求
// V2: 相同數據，結構更清晰
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

響應格式更新

V1 回應結構

V1 格式
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

V2 回應結構

V2 格式
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

關鍵差異： 無狀態包裝、欄位名稱更清晰、標準化元數據。

棄用時間表

計劃棄用項目

功能	公告日期	終止日期	替代方案
/v1/whales	2026年1月	2028年1月	/v2/whales/tracking
/v1/funding	2026年1月	2028年1月	/v2/derivatives/funding-heatmap
僅限API金鑰驗證	2026年3月	2027年3月	OAuth 2.0（金鑰仍可用）
Webhook v1格式	2026年第二季	2027年第二季	Webhook v2格式

重大變更詳情

移除的端點

/v1/stats — 由 /v2/metrics 取代
/v1/historical — 由帶新參數的 /v2/historical 取代
/v1/alerts/create — 由 POST /v2/alerts 取代

參數變更

limit — 預設值從100改為20（請明確指定！）
timeframe — 歷史查詢現為必填
sort — 格式從 "field asc" 改為 "field:asc"

回應欄位變更

funding → funding_rate
price → mark_price
vol → volume_quote

逐步遷移步驟

階段1：規劃（第1-2週）

審核現有整合中的棄用功能
將v1端點對應至v2等效項目
識別影響程式碼的重大變更
規劃測試策略與時間表

階段2：開發（第3-4週）

在版本控制中建立v2分支
將所有API端點更新為v2 URL
更新請求/回應處理邏輯
在沙盒環境執行單元測試

階段3：測試（第5-6週）

執行完整整合測試套件
測試錯誤情境與邊界案例
對v2端點進行負載測試
更新程式碼的安全性審核

階段4：預發佈（第7週）

將v2程式碼部署至預發環境
執行完整驗收測試
取得利害關係人簽核
準備回滾計劃

階段5：正式環境（第8週）

藍綠部署至正式環境
監控指標與錯誤率
待命處理支援問題
逐步淘汰v1程式碼

支援與資源

可用工具

遷移驗證工具 — 檢查程式碼中的棄用用法
API升級檢查器 — 比較v1與v2相容性
遷移檢查清單 — 含任務與時間表的PDF
程式碼範例 — 遷移前後樣本

取得協助

電郵：[email protected]
文件：參見 changelog-versioning.html
Discord：社群支援頻道
企業版：專屬遷移工程師

立即開始遷移

使用全面的遷移工具、文件和支援升級至API v2。支援零停機遷移。

探索V2

V1支援至2028年1月。立即規劃您的遷移。