认证指南
了解如何使用 API 密钥、JWT 令牌和 OAuth 2.0 与 Smart Money API 进行认证。通过行业标准的认证方法和最佳实践来确保您的集成安全。
概述
Smart Money API 支持多种认证方法，适用于不同的使用场景。选择最适合您集成的方法：
API 密钥（主要）： 在所有 REST API 调用中，将您的密钥发送到 X-API-Key 请求头中。这是推荐用于机器人和服务器到服务器使用的方法。
会话 JWT（备用）： 浏览器/仪表板会话通过 Authorization: Bearer使用会话 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']}个鲸鱼持仓记录")