速率限制与配额
了解Smart Money API的速率限制、各订阅层级的每日配额及优化策略，最大化您的API使用效率。
概述
Smart Money API实施每日请求配额以确保服务质量和用户公平性。每个订阅层级包含不同的每日限额。当您超出每日配额时，将收到429 Too Many Requests错误，直至UTC午夜配额重置。
速率限制按API密钥独立应用。每个密钥拥有独立的配额。您可为不同应用生成多个密钥并分别监控使用情况。
订阅层级配额
| 层级 | 每日请求数 | 价格 | 功能 |
|---|---|---|---|
| 免费版 | 100次/天 | $0 | BTC, ETH, SOL, 资金费率, 爆仓数据 |
| 交易者版 | 1,000次/天 | $29/月 | 全交易对, 巨鲸持仓, 持仓量数据 |
| 专业版 | 5,000次/天 | $79/月 | 确认分数, 链上数据, Webhooks |
| 企业版 | 自定义 | 自定义 | 专属支持, 定制集成 |
速率限制响应头
每个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 头部提供。
示例：交易者层级（1,000次/天）
- 第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. 策略性批量请求
尽可能合并多交易对的单次请求，而非为每个交易对单独请求。此举可减少高达10倍的API调用。
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)