完整REST API参考

通过我们全面的REST参考文档掌握Smart Money API。了解所有端点、参数、认证方法及加密货币衍生品情报与鲸鱼追踪数据的实际集成模式。

概述

Smart Money API提供对Bybit、Binance和Hyperliquid三大交易所实时加密货币衍生品数据的RESTful访问。我们的API将鲸鱼钱包仓位、资金费率、未平仓合约指标、强平数据及链上信号聚合至统一接口。无论您正在构建交易算法、风险管理系统还是市场分析工具，REST API都能让您直接以编程方式获取所有Smart Money情报。

API涵盖229+自动发现的交易对和600+监控中的鲸鱼钱包，提供全面的市场情报。实时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）可选
exchange	string	按交易所筛选：bybit、binance、hyperliquid 可选
min_position_size	number	基础资产最小仓位规模可选
direction	string	仅多头或空头仓位可选
page	integer	分页页码，默认为1 可选
limit	integer	每页结果数，上限100，默认为50 可选

示例请求：

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）必填
exchange	string	交易所：bybit、binance、hyperliquid 可选
interval	string	1h、4h、1d，默认为1h 可选
limit	integer	返回的历史周期数，上限500 可选

示例请求：

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 TRADER

参数	类型	描述
symbol	string	交易对必填
exchange	string	bybit、binance 或 hyperliquid 选填
granularity	string	1m、5m、15m、1h、4h、1d，默认15m 选填

强平端点

返回交易对的两种互补视图：杠杆预测 levels （预估强平聚集价位）与 realized_heatmap ——实时聚合自Binance、OKX、Bybit、Bitget和BitMEX等交易所公开WebSocket数据的实际执行强平强度（价格×时间）。当该交易对存在数据流时，热力图将显示。

GET /v1/liquidations TRADER

参数	类型	描述
symbol	string	资产代码，默认BTC 选填

Trader 返回级联风险、最近距离及实际总量/分方向数据。 Pro 返回完整预测 levels 及完整 realized_heatmap （矩阵数据、按价格聚类、分交易所计数）。

链上DeFi强平

直接从我们本地运行的BSC和Avalanche全节点捕获的DeFi借贷协议强平数据——独立于任何交易机器人。覆盖BSC上的Venus/Cream和Moolah，以及Avalanche上的AAVE V3/V2、Benqi、BankerJoe、Granary和Vinium。需认证密钥（Trader+）；Pro版额外返回依赖机器人的风险仓位。

GET /v1/liquidations/onchain TRADER

参数	类型	描述
chain	string	bsc或avax；留空表示全部选填
limit	integer	最大行数，默认100，上限500（按最新优先）选填

确认端点

该 /v1/confirm 端点返回基于规则的多因子 confluence 综合评分，结合衍生品、链上数据（免费Coin Metrics指标：MVRV/交易所流量/活跃地址）和巨鲸仓位。该 composite 评分范围从-1.0到+1.0（非0-100），每次响应均包含透明的 factors 分项明细（单因子评分×权重）、 adjustments, 权重及 coverage。此为决策支持工具，非必胜保证。未追踪的交易对将明确返回NO_DATA/unsupported结果，而非伪造的LOW评分。

GET /v1/confirm TRADER

参数： 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 PRO

参数	类型	描述
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:
        """获取鲸鱼仓位，可选符号过滤"""
        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:
        """获取当前及历史资金费率"""
        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):
        """持续监控鲸鱼仓位活动"""
        while True:
            positions = self.get_whale_positions(symbol)
            if positions["success"]:
                for pos in positions["data"]["positions"]:
                    print(f"鲸鱼 {pos['wallet_address'][:10]}: "
                          f"{pos['position_type']} "
                          f"{pos['position_size']} {symbol} "
                          f"盈亏: {pos['pnl_percent']}%")
            time.sleep(interval_seconds)

# 用法
client = SmartMoneyClient("sk_live_abc123xyz789")
whales = client.get_whale_positions("BTCUSDT")
print(f"鲸鱼仓位总数: {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）。升级至Trader或Pro计划可解锁所有交易对和高级功能。

获取API密钥

解锁专业版功能

完整访问鲸鱼仓位、确认评分、链上数据及每日2000+次API请求。

查看价格