完整REST API參考

透過我們全面的REST參考掌握Smart Money API。學習所有端點、參數、認證方法及實際整合模式，用於加密貨幣衍生品情報與鯨魚追蹤數據。

概述

Smart Money API提供對Bybit、Binance和Hyperliquid三大交易所的即時加密貨幣衍生品數據的RESTful存取。我們的API將鯨魚錢包持倉、資金費率、未平倉合約指標、強制平倉數據及鏈上信號整合至單一統一介面。無論您是建立交易算法、風險管理系統或市場分析工具，REST API都能讓您直接以程式化方式存取所有Smart Money情報。

透過超過229個自動發現的交易對與600多個監控中的鯨魚錢包，API提供全面的市場情報。即時WebSocket連接提供次秒級更新，而我們的REST端點則處理批量查詢、歷史數據檢索與大規模投資組合分析。

所有請求必須包含有效的認證憑證。免費層級用戶每日限20次請求且僅限BTC。交易者層級（1,000次/日）與專業層級（5,000次/日）可解鎖所有交易對與進階功能。

認證

Smart Money API使用API金鑰認證。主要方法是透過 X-API-Key 請求標頭。您可從儀表板生成API金鑰。透過 Authorization: Bearer 的會話JWT可作為瀏覽器/儀表板會話的備用方案，但API客戶端應使用 X-API-Key.

API金鑰認證（主要）

在每個請求的 X-API-Key 標頭中發送您的API金鑰。切勿將金鑰置於URL中。

HTTP

GET /v1/whales/events HTTP/1.1
Host: api.smartmoneyapi.com
X-API-Key: sm_your_key
Content-Type: application/json

會話JWT（備用）

瀏覽器/儀表板會話可透過 Authorization: Bearer 傳遞會話JWT（有效期24小時）。程式化客戶端應優先使用 X-API-Key.

Python

import requests
import json

# 獲取JWT令牌
response = requests.post(
  "https://api.smartmoneyapi.com/auth/jwt",
  json={"api_key": "sk_live_abc123xyz789"}
)
token = response.json()["token"]

# 使用JWT進行後續請求
headers = {"Authorization": f"Bearer {token}"}
whales = requests.get(
  "https://api.smartmoneyapi.com/v1/whales/events",
  headers=headers
)
print(whales.json())

基礎URL與端點

所有API請求發送至 https://api.smartmoneyapi.com。API按版本前綴組織為邏輯資源類別。當前穩定版本為 v1.

基礎URL： https://api.smartmoneyapi.com/api/v1

WebSocket URL： wss://ws.smartmoneyapi.com/stream

回應格式

所有API回應均以標準封裝格式的JSON物件返回。成功回應返回HTTP 200-299狀態碼及回應主體中的數據。錯誤回應包含詳細錯誤訊息與解決建議。

JSON

{
  "success": true,
  "data": {
    "total": 42,
    "positions": [
      {
        "wallet_address": "0x1234...",
        "symbol": "BTCUSDT",
        "position_size": 15.5,
        "entry_price": 42150.0,
        "current_price": 43200.5,
        "pnl": 16577.75,
        "pnl_percent": 3.91,
        "leverage": 5,
        "funding_rate": 0.00012,
        "last_updated": "2026-03-21T14:30:45Z"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_pages": 1
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

鯨魚持倉端點

從所有交易所監控的鯨魚錢包中檢索詳細持倉。此端點顯示即時槓桿、入場價格、強制平倉價格與未實現損益等高價值持倉資訊。

GET /v1/whales/events PRO

參數	類型	說明
symbol	string	交易對（如BTCUSDT、ETHUSDT） optional
exchange	string	按交易所篩選：bybit、binance、hyperliquid optional
min_position_size	number	基礎資產中的最小持倉量 optional
direction	string	僅限多頭或空頭持倉 optional
page	integer	分頁頁碼，預設1 optional
limit	integer	每頁結果數，最多100，預設50 optional

範例請求：

cURL

curl -X GET "https://api.smartmoneyapi.com/v1/whales/events?symbol=BTCUSDT&min_position_size=10&limit=25" \
  -H "X-API-Key: sm_your_key" \
  -H "Content-Type: application/json"

資金費率端點

存取Bybit、Binance和Hyperliquid的即時與歷史資金費率。資金費率對套利交易、波段策略與衍生品對沖至關重要。我們的API以15分鐘粒度聚合費率並提供歷史費率分析。

GET /v1/funding-rates FREE

參數	類型	說明
symbol	string	交易對（如BTCUSDT） required
exchange	string	交易所：bybit、binance、hyperliquid optional
interval	string	1h、4h、1d，預設1h optional
limit	integer	返回的歷史時段數，最多500 optional

範例請求：

JavaScript

const fetchFundingRates = async () => {
  const response = await fetch(
    "https://api.smartmoneyapi.com/v1/funding-rates?symbol=BTCUSDT&interval=4h&limit=100",
    {
      headers: {
        "X-API-Key": "sm_your_key",
        "Content-Type": "application/json"
      }
    }
  );
  const data = await response.json();
  console.log(data);
};
fetchFundingRates();

未平倉合約端點

監控所有槓桿交易者的總未平倉合約。未平倉合約與價格走勢的背離預示潛在的反轉和趨勢延續機會。追蹤絕對未平倉量及未平倉量變化率。

GET /v1/open-interest 交易員

參數	類型	說明
symbol	string	交易對必填
exchange	string	bybit、binance 或 hyperliquid 選填
granularity	string	1m、5m、15m、1h、4h、1d，預設 15m 選填

強制平倉端點

返回交易對的兩種互補視圖：槓桿預測水平（估計強制平倉集群位置）與 realized_heatmap ——從公開交易所 WebSocket 數據流（Binance、OKX、Bybit、Bitget、BitMEX）即時聚合的實際執行強制平倉強度（價格 × 時間）。當數據流有該交易對資料時，熱力圖會顯示。

GET /v1/liquidations 交易員

參數	類型	說明
symbol	string	資產代號，預設 BTC 選填

交易員 返回級聯風險、最近距離及實際總量/方向。 專業版 返回完整預測水平及完整 realized_heatmap （矩陣、每價格集群、每交易所計數）。

鏈上 DeFi 強制平倉

從本地 BSC 和 Avalanche 全節點直接捕獲的 DeFi 借貸協議強制平倉記錄——獨立於任何交易機器人。涵蓋 BSC 上的 Venus/Cream 和 Moolah，以及 Avalanche 上的 AAVE V3/V2、Benqi、BankerJoe、Granary 和 Vinium。需驗證金鑰（Trader+）；專業版額外返回依賴機器人的風險部位。

GET /v1/liquidations/onchain 交易員

參數	類型	說明
chain	string	bsc 或 avax；省略則查全部選填
limit	integer	最大行數，預設 100，上限 500（由新到舊）選填

確認端點

此 /v1/confirm 端點返回基於規則的多因子匯合分數，結合衍生品、鏈上數據（免費 Coin Metrics：MVRV / 交易所流量 / 活躍地址）和巨鯨持倉。該綜合分數範圍為 -1.0 至 +1.0（非 0–100），每筆回應皆包含透明的因子細項（各項分數 × 權重）、調整, 權重及覆蓋率。此為決策輔助工具，非保證勝率。未追蹤代號會明確返回 NO_DATA / 不支援結果，而非虛構的 LOW。

GET /v1/confirm 交易員

參數： symbol （BTC/ETH/SOL）與 direction （做多/做空）。 confidence 為 HIGH / MEDIUM / LOW / VETO / NO_DATA 之一； action 為 CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP 之一； size_mult 為建議部位規模乘數。

鏈上數據端點

存取比特幣和以太坊鏈上指標，含交易所流量、巨鯨錢包動向、MVRV 比率、NUPL、支出條件和已實現波動率。這些指標識別累積/分配週期，並提供重大反轉的早期訊號。

GET /v1/on-chain/metrics 專業版

參數	類型	說明
asset	string	bitcoin 或 ethereum 必填
metrics	array	特定指標：exchange_flows、mvrv、nupl、whale_moves 選填
interval	string	1d（每日）、1w（每週），預設 1d 選填

數據模型參考

理解 API 回應結構對整合至關重要。以下為所有端點使用的完整數據模型定義。

WhalePosition 物件

JSON

{
  "id": "pos_1a2b3c4d5e6f7g8h",
  "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
  "exchange": "bybit",
  "symbol": "BTCUSDT",
  "position_type": "long",
  "position_size": 15.5,
  "entry_price": 42150.0,
  "current_price": 43200.5,
  "pnl": 16577.75,
  "pnl_percent": 3.91,
  "leverage": 5,
  "margin_balance": 129000.0,
  "used_margin": 126225.0,
  "available_margin": 2775.0,
  "liquidation_price": 34560.0,
  "funding_rate": 0.00012,
  "time_opened": "2026-03-15T08:30:00Z",
  "last_updated": "2026-03-21T14:30:45Z"
}

FundingRateRecord 物件

JSON

{
  "timestamp": "2026-03-21T14:00:00Z",
  "symbol": "BTCUSDT",
  "bybit": {
    "funding_rate": 0.00012,
    "next_rate": 0.00015
  },
  "binance": {
    "funding_rate": 0.00010,
    "next_rate": 0.00013
  },
  "hyperliquid": {
    "funding_rate": 0.00014,
    "next_rate": 0.00016
  },
  "aggregated": {
    "mean": 0.000120,
    "median": 0.000120,
    "spread": 0.000060
  }
}

程式碼範例

以下為常見整合模式的正式環境可用程式碼範例。

用 Python 監控鯨魚倉位

Python

import requests
import time
from typing import List, Dict

class SmartMoneyClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.smartmoneyapi.com/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def get_whale_positions(self, symbol: str = None) -> Dict:
        """Fetch whale positions with optional symbol filter"""
        params = {}
        if symbol:
            params["symbol"] = symbol

        response = requests.get(
            f"{self.base_url}/whales/events",
            headers=self.headers,
            params=params
        )
        return response.json()

    def get_funding_rates(self, symbol: str) -> Dict:
        """Get current and historical funding rates"""
        response = requests.get(
            f"{self.base_url}/funding-rates",
            headers=self.headers,
            params={"symbol": symbol, "limit": 100}
        )
        return response.json()

    def monitor_whale_activity(self, symbol: str, interval_seconds: int = 60):
        """Continuously monitor whale positions"""
        while True:
            positions = self.get_whale_positions(symbol)
            if positions["success"]:
                for pos in positions["data"]["positions"]:
                    print(f"Whale {pos['wallet_address'][:10]}: "
                          f"{pos['position_type']} "
                          f"{pos['position_size']} {symbol} "
                          f"PnL: {pos['pnl_percent']}%")
            time.sleep(interval_seconds)

# Usage
client = SmartMoneyClient("sk_live_abc123xyz789")
whales = client.get_whale_positions("BTCUSDT")
print(f"Total whale positions: {whales['data']['total']}")

最佳實踐與效能優化

使用分頁： 大量資料集務必分頁處理。使用 limit 和 page 參數分批獲取 50-100 筆資料，而非一次性載入全部。

快取回應： 鯨魚倉位不會每秒變動。快取結果 30-60 秒可減少 API 呼叫次數並提升效能。

提前過濾： 使用查詢參數 (symbol, exchange, direction) 在伺服器端過濾資料，而非在應用程式碼中處理。

處理速率限制： 實作指數退避重試邏輯。當觸發速率限制 (429 狀態碼) 時，等待後重試。

使用 WebSocket 即時串流： 串流資料請優先使用 WebSocket 連線而非輪詢 REST 端點。可節省頻寬並獲得次秒級延遲。

驗證時間戳記： 所有時間戳記皆為 ISO 8601 UTC 格式。顯示時請轉換為當地時區，儲存時請保持 UTC。

處理連線中斷： 為 WebSocket 連線實作指數退避的自動重連邏輯。

監控配額用量： 檢查回應中的 X-Requests-Remaining 標頭。規劃 API 使用量以保持在方案限制內。

常見整合模式

模式 1：鯨魚囤貨警報

當鯨魚倉位超過閾值時設定警報，標記潛在多頭行情或囤貨階段。

模式 2：資金費率套利偵測

自動偵測交易所間資金費率價差超過獲利閾值時機，啟動跨交易所套利演算法。

模式 3：清算連鎖監控

追蹤大額清算事件，讓演算法能利用連鎖清算與高衝擊價格波動。

模式 4：多重訊號確認

結合鯨魚倉位、資金費率、鏈上指標與我們的 AI 確認分數，產生高確信度的進場訊號。

準備開始了嗎？

從控制台取得 API 金鑰立即開始開發。新帳戶皆可免費使用基礎方案 (每日 20 次請求，含 BTC, ETH, SOL)。升級至交易者或專業方案可無限使用所有代幣與進階功能。

取得 API 金鑰

解鎖專業功能

完整存取鯨魚倉位、確認分數、鏈上資料與每日 2000+ API 請求。

查看方案