Complete REST API Reference

Master the Smart Money API with our comprehensive REST reference. Learn all endpoints, parameters, authentication methods, and real-world integration patterns for crypto derivatives intelligence and whale tracking data.

Overview

The Smart Money API provides RESTful access to real-time cryptocurrency derivatives data across three major exchanges: Bybit, Binance, and Hyperliquid. Our API aggregates whale wallet positions, funding rates, open interest metrics, liquidation data, and on-chain signals into a single unified interface. Whether you're building trading algorithms, risk management systems, or market analysis tools, the REST API gives you direct programmatic access to all Smart Money intelligence.

With over 229 auto-discovered trading symbols and 600+ monitored whale wallets, the API provides comprehensive market intelligence. Real-time WebSocket connections deliver sub-second updates, while our REST endpoints handle batch queries, historical data retrieval, and portfolio analysis at scale.

All requests must include valid authentication credentials. Free tier users have 200 requests per day limited to BTC. Trader tier (3,000 requests/day) and Pro tier (15,000 requests/day) unlock all symbols and advanced features.

Authentication

The Smart Money API uses API key authentication. The primary method is the X-API-Key request header. You can generate API keys from your dashboard. A session JWT via Authorization: Bearer is accepted as a fallback for browser/dashboard sessions, but API clients should use X-API-Key.

API Key Authentication (primary)

Send your API key in the X-API-Key header on every request. Never put your key in a URL.

HTTP

GET /v1/whales/events HTTP/1.1
Host: api.smartmoneyapi.com
X-API-Key: sm_your_key
Content-Type: application/json

Session JWT (fallback)

Browser/dashboard sessions may pass a session JWT via Authorization: Bearer (valid for 24 hours). Programmatic clients should prefer X-API-Key.

Python

import requests
import json

# Get JWT token
response = requests.post(
  "https://api.smartmoneyapi.com/auth/jwt",
  json={"api_key": "sk_live_abc123xyz789"}
)
token = response.json()["token"]

# Use JWT for subsequent requests
headers = {"Authorization": f"Bearer {token}"}
whales = requests.get(
  "https://api.smartmoneyapi.com/v1/whales/events",
  headers=headers
)
print(whales.json())

Base URL & Endpoints

All API requests go to https://api.smartmoneyapi.com. The API is organized into logical resource categories with version prefixes. Current stable version is v1.

Base URL: https://api.smartmoneyapi.com/v1

WebSocket URL: wss://ws.smartmoneyapi.com/stream

Response Format

All API responses are returned as JSON objects with a standard envelope format. Successful responses return HTTP 200-299 status codes with data in the response body. Error responses include detailed error messages and resolution suggestions.

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"
}

Whale Positions Endpoint

Retrieve detailed positions from monitored whale wallets across all exchanges. This endpoint shows real-time leverage, entry prices, liquidation prices, and unrealized P&L for high-value positions.

GET /v1/whales/events PRO

Parameter	Type	Description
symbol	string	Trading pair (e.g., BTCUSDT, ETHUSDT) optional
exchange	string	Filter by exchange: bybit, binance, hyperliquid optional
min_position_size	number	Minimum position size in base asset optional
direction	string	long or short positions only optional
page	integer	Pagination page number, default 1 optional
limit	integer	Results per page, max 100, default 50 optional

Example Request:

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"

Funding Rates Endpoint

Access real-time and historical funding rates across Bybit, Binance, and Hyperliquid. Funding rates are critical for arbitrage trading, swing strategies, and derivatives hedging. Our API aggregates rates with 15-minute granularity and provides historical rate analysis.

GET /v1/funding-rates FREE

Parameter	Type	Description
symbol	string	Trading pair (e.g., BTCUSDT) required
exchange	string	Exchange: bybit, binance, hyperliquid optional
interval	string	1h, 4h, 1d, default 1h optional
limit	integer	Historical periods to return, max 500 optional

Example Request:

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();

Open Interest Endpoint

Monitor aggregate open interest across all leverage traders. Open interest divergence from price movement signals potential reversals and trend continuation opportunities. Track both absolute OI and OI change rates.

GET /v1/open-interest TRADER

Parameter	Type	Description
symbol	string	Trading pair required
exchange	string	bybit, binance, or hyperliquid optional
granularity	string	1m, 5m, 15m, 1h, 4h, 1d, default 15m optional

Liquidations Endpoint

Returns two complementary views for a symbol: leverage-projected levels (an estimate of where liquidation clusters sit) and a realized_heatmap — the REAL executed forced-liquidation intensity (price × time) aggregated live from public exchange WebSocket feeds: Binance, OKX, Bybit, Bitget, and BitMEX. The heatmap is present when the stream has data for the symbol.

GET /v1/liquidations TRADER

Parameter	Type	Description
symbol	string	Asset symbol, default BTC optional

Trader returns cascade risk, nearest distances, and realized totals/by-side. Pro returns full projected levels plus the full realized_heatmap (matrices, per-price clusters, per-exchange counts).

On-Chain DeFi Liquidations

Executed DeFi lending-protocol liquidations captured directly from our own local BSC and Avalanche full nodes — independent of any trading bot. Covers Venus/Cream and Moolah on BSC, and AAVE V3/V2, Benqi, BankerJoe, Granary and Vinium on Avalanche. Requires an authenticated key (Trader+); Pro additionally returns bot-dependent at-risk positions.

GET /v1/liquidations/onchain TRADER

Parameter	Type	Description
chain	string	bsc or avax; omit for all optional
limit	integer	Max rows, default 100, max 500 (newest-first) optional

Confirmation Endpoint

The /v1/confirm endpoint returns a rule-based, multi-factor confluence score combining derivatives, on-chain (free Coin Metrics: MVRV / exchange-flow / active-address), and whale positioning. The composite ranges from -1.0 to +1.0 (not 0–100) and every response includes a transparent factors breakdown (per-leg score × weight), adjustments, weights, and coverage. It is decision support, not a guaranteed win-rate. An untracked symbol returns an explicit NO_DATA / unsupported result rather than a fabricated LOW.

GET /v1/confirm TRADER

Parameters: symbol (BTC/ETH/SOL) and direction (long/short). confidence is one of HIGH / MEDIUM / LOW / VETO / NO_DATA; action is one of CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP; size_mult is the suggested position-size multiplier.

On-Chain Data Endpoints

Access Bitcoin and Ethereum on-chain metrics including exchange flows, whale wallet movements, MVRV ratio, NUPL, spending conditions, and realized volatility. These metrics identify accumulation/distribution cycles and provide early signals for major reversals.

GET /v1/on-chain/metrics PRO

Parameter	Type	Description
asset	string	bitcoin or ethereum required
metrics	array	Specific metrics: exchange_flows, mvrv, nupl, whale_moves optional
interval	string	1d (daily), 1w (weekly), default 1d optional

Data Models Reference

Understanding the structure of API responses is essential for integration. Below are the complete data model definitions used across all endpoints.

WhalePosition Object

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 Object

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
  }
}

Code Examples

Below are production-ready code examples for common integration patterns.

Monitor Whale Positions in 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/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def get_whale_positions(self, symbol: str = None) -> Dict:
        """Fetch whale positions with optional symbol filter"""
        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:
        """Get current and historical funding rates"""
        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):
        """Continuously monitor whale positions"""
        while True:
            positions = self.get_whale_positions(symbol)
            if positions["success"]:
                for pos in positions["data"]["positions"]:
                    print(f"Whale {pos['wallet_address'][:10]}: "
                          f"{pos['position_type']} "
                          f"{pos['position_size']} {symbol} "
                          f"PnL: {pos['pnl_percent']}%")
            time.sleep(interval_seconds)

# Usage
client = SmartMoneyClient("sk_live_abc123xyz789")
whales = client.get_whale_positions("BTCUSDT")
print(f"Total whale positions: {whales['data']['total']}")

Best Practices & Performance Tips

Use pagination: Always paginate large result sets. Use limit and page parameters to fetch data in 50-100 record chunks, not all data at once.

Cache responses: Whale positions don't change every second. Cache results for 30-60 seconds to reduce API calls and improve performance.

Filter early: Use query parameters (symbol, exchange, direction) to filter data server-side, not in your application code.

Handle rate limits: Implement exponential backoff retry logic. When you hit rate limits (429 status), wait and retry.

Use WebSocket for real-time: For streaming data, prefer WebSocket connections over polling REST endpoints. You'll save bandwidth and get sub-second latency.

Validate timestamps: All timestamps are ISO 8601 UTC. Always convert to your local timezone for display and always store in UTC.

Handle disconnections: Implement automatic reconnection logic with exponential backoff for WebSocket connections.

Monitor your quota: Check the X-Requests-Remaining header in responses. Plan your API usage to stay within your tier limit.

Common Integration Patterns

Pattern 1: Alert on Whale Accumulation

Set up alerts when whale positions increase beyond a threshold, signaling potential bull runs or accumulation phases.

Pattern 2: Funding Rate Arbitrage Detection

Automatically detect when funding rate spreads exceed profitable thresholds across exchanges, enabling cross-exchange arbitrage algorithms.

Pattern 3: Liquidation Cascade Monitoring

Track large liquidations and position the algorithm to capitalize on cascading liquidations and high-impact price moves.

Pattern 4: Multi-Signal Confirmation

Combine whale positions, funding rates, on-chain metrics, and our AI confirmation scores for high-conviction entry signals.

Ready to Start?

Get your API key from the console and start building today. All new accounts get free tier access with 200 requests per day (BTC, ETH, SOL). Upgrade to Trader or Pro for unlimited access to all symbols and advanced features.

Get API Key

Unlock Pro Features

Get full access to whale positions, confirmation scores, on-chain data, and 2000+ daily API requests.

View Pricing