身份驗證指南
了解如何使用 API 密鑰、JWT 令牌和 OAuth 2.0 與 Smart Money API 進行身份驗證。使用行業標準的身份驗證方法和最佳實踐來保護您的集成。
概述
Smart Money API 支持多種身份驗證方法，適用於不同的使用場景。選擇最適合您集成的方法：
API 密鑰（主要）： 在所有 REST API 調用中將您的密鑰發送到 X-API-Key 請求標頭中。這是推薦用於機器人和伺服器對伺服器使用的方法。
Session JWT（備用）： 瀏覽器/儀表板會話通過 Authorization: Bearer使用 session JWT 進行身份驗證，有效期為 24 小時。程序化客戶端應優先使用 X-API-Key.
OAuth 2.0： 適用於多用戶應用程序和第三方集成的企業級身份驗證。用戶授權您的應用程序訪問其數據。
所有 API 請求必須通過 HTTPS 進行。未加密的 HTTP 請求將被拒絕。此外，切勿將 API 密鑰提交到版本控制或公開分享。
API 密鑰
API 密鑰是發給您帳戶的唯一憑證。每個密鑰代表一組權限和配額。您可以為不同的應用程序或環境（開發、測試、生產）生成多個密鑰。
生成 API 密鑰
從您的帳戶控制台生成 API 密鑰：
- 導航到 Smart Money Console
- 從側邊欄中選擇“API 密鑰”
- 點擊“生成新密鑰”
- 選擇密鑰類型（開發、測試、生產）
- 設置速率限制和功能
- 複製並安全存儲密鑰
立即保存您的 API 密鑰！您將無法再次查看它。如果丟失，您需要生成一個新密鑰。
密鑰格式
API 密鑰遵循標準格式：
密鑰格式
sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b
密鑰前綴表示環境：
sk_live_ — 具有完整配額的生產密鑰
sk_test_ — 具有減少配額和開發數據的測試密鑰
sk_dev_ — 具有沙盒數據的個人開發密鑰
X-API-Key 標頭（主要）
在所有 API 請求中將您的 API 密鑰發送到 X-API-Key 請求標頭中。切勿將您的密鑰放在 URL 中。
HTTP 標頭
HTTP
GET /v1/whales/events HTTP/1.1
Host: api.smartmoneyapi.com
X-API-Key: sm_your_key
Content-Type: application/json
cURL 示例
Shell
curl -X GET https://api.smartmoneyapi.com/v1/whales/events \
-H "X-API-Key: sm_your_key" \
-H "Content-Type: application/json"
Python 示例
Python
import requests
api_key = "sm_your_key"
headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}
response = requests.get(
"https://api.smartmoneyapi.com/v1/whales/events",
headers=headers
)
data = response.json()
JWT 令牌身份驗證
對於長期會話和伺服器對伺服器通信，您可以將 API 密鑰交換為 JWT 令牌。JWT 令牌有效期為 24 小時，減少了在應用程序代碼中存儲 API 密鑰的需求。
獲取 JWT 令牌
將您的 API 密鑰 POST 到 JWT 端點以獲取令牌：
cURL
curl -X POST https://api.smartmoneyapi.com/auth/jwt \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m"
}'
JWT 響應
JSON
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"expires_in": 86400,
"token_type": "Bearer"
}
使用 JWT 令牌
像 API 密鑰一樣在 Authorization 標頭中使用 JWT 令牌：
Python
import requests
import json
from datetime import datetime, timedelta
class JWTAuth:
def __init__(self, api_key):
self.api_key = api_key
self.token = None
self.token_expires = None
def get_valid_token(self):
# 檢查當前令牌是否仍然有效
if self.token and self.token_expires > datetime.now():
return self.token
# 獲取新令牌
response = requests.post(
"https://api.smartmoneyapi.com/auth/jwt",
json={"api_key": self.api_key}
)
data = response.json()
self.token = data["token"]
self.token_expires = datetime.now() + timedelta(seconds=data["expires_in"])
return self.token
def request(self, method, url, **kwargs):
token = self.get_valid_token()
headers = kwargs.get("headers", {})
headers["Authorization"] = f"Bearer {token}"
kwargs["headers"] = headers
return requests.request(method, url, **kwargs)
# 使用
auth = JWTAuth("sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m")
response = auth.request(
"GET",
"https://api.smartmoneyapi.com/v1/whales/events"
)
print(response.json())
OAuth 2.0
OAuth 2.0 適用於需要訪問多個用戶帳戶的應用程序。用戶授予您的應用程序訪問其數據的權限，而無需共享其 API 密鑰。
OAuth 2.0 流程
Smart Money API 支持 Web 應用程序的授權碼流程：
- 用戶點擊“連接 Smart Money”按鈕
- 瀏覽器重定向到授權頁面
- 用戶授予您的應用程序權限
- 瀏覽器帶有授權碼重定向回來
- 您的後端將代碼交換為訪問令牌
- 您現在可以代表用戶訪問其數據
步驟 1：授權請求
將用戶重定向到授權端點：
URL
https://auth.smartmoneyapi.com/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=whale_positions+funding_rates+liquidations&
state=random_state_string
步驟 2：令牌交換
用戶授予權限後，將代碼交換為訪問令牌：
cURL
curl -X POST https://auth.smartmoneyapi.com/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https://yourapp.com/callback"
OAuth 令牌響應
JSON
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
"scope": "whale_positions funding_rates liquidations"
}
安全最佳實踐
安全存儲密鑰
切勿將 API 密鑰提交到版本控制、硬編碼到應用程序中或在文檔中分享。使用環境變量或安全的密鑰管理服務，如 AWS Secrets Manager、HashiCorp Vault 或類似服務。
僅使用 HTTPS
所有 API 請求必須使用 HTTPS（TLS 1.2 或更高版本）。HTTP 請求將被拒絕。這確保您的 API 密鑰和數據在傳輸過程中加密。
限制密鑰權限
為不同的應用程序和環境創建單獨的 API 密鑰。使用範圍來限制每個密鑰可以訪問的內容。不要在開發中使用生產密鑰。
監控密鑰使用
定期在控制台中審查 API 使用情況。設置警報以應對異常活動或配額接近限制的情況。刪除不再使用的密鑰。
密鑰輪換
定期輪換您的 API 密鑰以降低洩露風險。我們建議每 90 天輪換一次密鑰：
- 在您的控制台中生成一個新的 API 密鑰
- 更新您的應用程式以使用新金鑰
- 測試一切是否正常運作
- 從控制台刪除舊金鑰
範圍與權限
在創建API金鑰或使用OAuth時，請指定您的金鑰可以訪問哪些資源：
| 範圍 | 描述 | 等級 |
|---|---|---|
| whale_positions | 讀取鯨魚錢包持倉 | Trader+ |
| funding_rates | 讀取資金費率數據 | Free+ |
| liquidations | 讀取清算數據 | Free+ |
| open_interest | 讀取未平倉量數據 | Trader+ |
| confirmation_scores | 讀取AI確認分數 | Pro+ |
| on_chain | 讀取鏈上指標 | Pro+ |
驗證碼範例
完整的Python整合
Python
import requests
from typing import Optional, Dict
from datetime import datetime, timedelta
class SmartMoneyAuth:
"""處理Smart Money API的所有驗證方法"""
def __init__(self, api_key: str):
self.api_key = api_key
self.base_url = "https://api.smartmoneyapi.com"
self.jwt_token = None
self.jwt_expires = None
def get_jwt_token(self) -> str:
"""獲取或刷新JWT令牌"""
if self.jwt_token and self.jwt_expires > datetime.now():
return self.jwt_token
response = requests.post(
f"{self.base_url}/auth/jwt",
json={"api_key": self.api_key}
)
data = response.json()
self.jwt_token = data["token"]
self.jwt_expires = datetime.now() + timedelta(seconds=data["expires_in"] - 300)
return self.jwt_token
def headers_bearer(self) -> Dict:
"""獲取Bearer令牌驗證的標頭"""
return {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json"
}
def headers_jwt(self) -> Dict:
"""獲取JWT驗證的標頭"""
token = self.get_jwt_token()
return {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
def request(self, method: str, endpoint: str, use_jwt: bool = False, **kwargs) -> Dict:
"""進行驗證請求"""
headers = self.headers_jwt() if use_jwt else self.headers_bearer()
response = requests.request(
method,
f"{self.base_url}{endpoint}",
headers=headers,
**kwargs
)
return response.json()
# 用法
auth = SmartMoneyAuth("sk_live_abc123xyz789")
# Bearer令牌方法
whales = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT")
# JWT方法（自動刷新）
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)
print(f"找到 {whales['data']['total']} 個鯨魚持倉")