速率限制與配額
了解 Smart Money API 的速率限制、各訂閱等級的每日配額，以及最大化 API 使用效率的優化策略。
概述
Smart Money API 實施每日請求配額以確保服務品質和用戶公平性。每個訂閱等級包含不同的每日限制。當您超過每日配額時，將收到 429 Too Many Requests 錯誤，直到 UTC 午夜配額重置為止。
速率限制按 API 金鑰應用。每個金鑰有獨立的配額。您可以為不同應用生成多個金鑰，並分別監控使用情況。
訂閱等級配額
| 等級 | 每日請求 | 價格 | 功能 |
|---|---|---|---|
| 免費 | 20 次請求/日 | $0 | BTC, ETH, SOL, 資金費率, 清算數據 |
| 交易者 | 400 次請求/日 | $29/月 | 全幣種、巨鯨持倉、未平倉量數據 |
| 專業版 | 4,000 次請求/日 | $79/月 | 確認分數、鏈上數據、Webhook |
| 企業版 | 自訂 | 自訂 | 專屬支援、自訂整合 |
速率限制回應標頭
每個 API 回應都包含顯示當前配額狀態的標頭：
HTTP 標頭
X-Requests-Limit: 200
X-Requests-Remaining: 147
X-Requests-Reset: 1711116000
X-Requests-Reset-ISO: 2026-03-22T00:00:00Z
| 標頭 | 說明 |
|---|---|
X-Requests-Limit |
每日允許的總請求數（例如交易者等級為 200） |
X-Requests-Remaining |
當日剩餘請求數 |
X-Requests-Reset |
配額重置的 Unix 時間戳 |
X-Requests-Reset-ISO |
配額重置的 ISO 8601 時間戳 |
發送請求前檢查配額
Python
import requests
from datetime import datetime
def check_quota_before_request(api_key):
response = requests.head(
"https://api.smartmoneyapi.com/v1/whales/events",
headers={"Authorization": f"Bearer {api_key}"}
)
limit = int(response.headers.get("X-Requests-Limit", 0))
remaining = int(response.headers.get("X-Requests-Remaining", 0))
reset_unix = int(response.headers.get("X-Requests-Reset", 0))
reset_time = datetime.fromtimestamp(reset_unix)
percent_used = (limit - remaining) / limit * 100
print(f"Quota: {remaining}/{limit} requests ({percent_used:.1f}% used)")
print(f"Resets at: {reset_time}")
if remaining < 5:
print("WARNING: Approaching quota limit!")
return False
return True
# Check before making requests
if check_quota_before_request("sk_live_abc123xyz789"):
print("Safe to proceed with API calls")
每日速率窗口
速率限制採用 24 小時滾動窗口。您的配額每日 UTC 午夜（00:00 UTC）重置。確切重置時間由 X-Requests-Reset-ISO 標頭提供。
範例：交易者等級（400 次請求/日）
- 第 1 天（3 月 21 日）： 00:00 UTC 時有 200 次請求可用
- 10:30 UTC： 已發送 75 次請求，剩餘 125 次
- 15:45 UTC： 再發送 100 次請求，剩餘 25 次
- 23:59 UTC： 仍剩餘 25 次請求（無法累積）
- 第 2 天（3 月 22 日 00:00 UTC）： 配額重置為 200 次
優化策略
1. 快取 API 回應
巨鯨持倉不會每秒變化。快取結果 30-60 秒並提供快取數據，而非發送新 API 請求。
Python
import requests
import time
class CachedClient:
def __init__(self, api_key, cache_ttl=60):
self.api_key = api_key
self.cache_ttl = cache_ttl
self.cache = {}
self.cache_time = {}
def get_whale_positions(self, symbol):
cache_key = f"whales:{symbol}"
now = time.time()
# Return cached data if still fresh
if cache_key in self.cache:
age = now - self.cache_time[cache_key]
if age < self.cache_ttl:
print(f"Served from cache (age: {age:.1f}s)")
return self.cache[cache_key]
# Fetch fresh data
response = requests.get(
f"https://api.smartmoneyapi.com/v1/whales/events?symbol={symbol}",
headers={"Authorization": f"Bearer {self.api_key}"}
)
data = response.json()
self.cache[cache_key] = data
self.cache_time[cache_key] = now
return data
# Usage: Cache for 60 seconds
client = CachedClient("sk_live_abc123xyz789", cache_ttl=60)
whales1 = client.get_whale_positions("BTCUSDT") # API call
whales2 = client.get_whale_positions("BTCUSDT") # From cache
whales3 = client.get_whale_positions("BTCUSDT") # From cache
2. 使用 WebSocket 獲取即時數據
WebSocket 連接即時推送更新且不計入速率限制。訂閱串流以接收即時更新，減少 REST API 調用次數。
3. 策略性批量請求
盡可能合併多個幣種的單一請求，而非為每個幣種發送獨立請求。這可將 API 調用減少高達 10 倍。
4. 請求時應用篩選
在查詢參數中應用篩選條件（幣種、交易所、最小持倉量）以精確獲取所需數據，避免後處理需求。
處理速率限制錯誤
指數退避重試
Python
import requests
import time
def request_with_retry(url, api_key, max_retries=5):
for attempt in range(max_retries):
try:
response = requests.get(
url,
headers={"Authorization": f"Bearer {api_key}"},
timeout=10
)
if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# Rate limited - back off exponentially
wait_time = min(2 ** attempt, 300) # Max 5 minutes
reset_time = response.headers.get("X-Requests-Reset-ISO")
print(f"Rate limited. Retrying in {wait_time}s (resets at {reset_time})")
time.sleep(wait_time)
elif response.status_code >= 500:
# Server error - retry
wait_time = 2 ** attempt
print(f"Server error {response.status_code}. Retrying in {wait_time}s")
time.sleep(wait_time)
else:
# Other error - don't retry
raise Exception(f"HTTP {response.status_code}: {response.text}")
except requests.exceptions.Timeout:
wait_time = 2 ** attempt
print(f"Timeout. Retrying in {wait_time}s")
time.sleep(wait_time)
raise Exception("Max retries exceeded")
# Usage
data = request_with_retry(
"https://api.smartmoneyapi.com/v1/whales/events",
"sk_live_abc123xyz789"
)
print(data)