Data Models & Schema Reference

Complete reference for Smart Money API data models. Learn the structure and field definitions for all response objects including whale positions, funding rates, liquidations, and AI confirmation scores.

Overview

Understanding API response structures is essential for building integrations. This reference documents all data model definitions, field types, constraints, and examples. All timestamps are in ISO 8601 UTC format. All prices and amounts are returned as strings to prevent floating-point precision loss.

Whale Position Object

Represents a large position held by a monitored whale wallet on a leverage trading exchange.

Field	Type	Description
id	string	Unique position identifier
wallet_address	string	Whale wallet address (0x... format)
exchange	string	bybit, binance, or hyperliquid
symbol	string	Trading pair (BTCUSDT, ETHUSDT, etc.)
position_type	string	long or short
position_size	string	Size in base asset (e.g., BTC)
entry_price	string	Average entry price in USDT
current_price	string	Current mark price in USDT
liquidation_price	string	Price at which position gets liquidated
pnl	string	Unrealized P&L in USDT
pnl_percent	number	Unrealized P&L as percentage
leverage	integer	Leverage multiplier (1-20x)
margin_balance	string	Total margin balance in USDT
used_margin	string	Used margin in USDT
available_margin	string	Available margin in USDT
margin_ratio	number	Available margin / used margin ratio
funding_rate	string	Current funding rate (hourly %)
time_opened	string	ISO 8601 timestamp when opened
last_updated	string	ISO 8601 timestamp of last update

Example Whale Position

JSON

{
  "id": "pos_1a2b3c4d5e6f7g8h",
  "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
  "exchange": "bybit",
  "symbol": "BTCUSDT",
  "position_type": "long",
  "position_size": "15.5",
  "entry_price": "42150.00",
  "current_price": "43200.50",
  "liquidation_price": "34560.00",
  "pnl": "16577.75",
  "pnl_percent": 3.91,
  "leverage": 5,
  "margin_balance": "129000.00",
  "used_margin": "126225.00",
  "available_margin": "2775.00",
  "margin_ratio": 0.022,
  "funding_rate": "0.00012",
  "time_opened": "2026-03-15T08:30:00Z",
  "last_updated": "2026-03-21T14:35:45Z"
}

Funding Rate Object

Represents funding rates across multiple exchanges for a single symbol and time period.

JSON

{
  "timestamp": "2026-03-21T14:00:00Z",
  "symbol": "BTCUSDT",
  "bybit": {
    "rate": "0.000120",
    "next_funding_time": "2026-03-21T16:00:00Z",
    "next_rate": "0.000145"
  },
  "binance": {
    "rate": "0.000098",
    "next_funding_time": "2026-03-21T16:00:00Z",
    "next_rate": "0.000115"
  },
  "hyperliquid": {
    "rate": "0.000140",
    "next_funding_time": "2026-03-21T16:00:00Z",
    "next_rate": "0.000160"
  },
  "aggregated": {
    "mean": "0.000119",
    "median": "0.000120",
    "highest": "0.000160",
    "lowest": "0.000098",
    "spread": "0.000062"
  }
}

Liquidation Object

Represents a forced liquidation of a leveraged position.

JSON

{
  "id": "liq_1a2b3c4d5e6f7g8h",
  "exchange": "binance",
  "symbol": "BTCUSDT",
  "direction": "long",
  "position_size": "12.5",
  "liquidation_price": "41000.00",
  "size_usd": "512500.00",
  "timestamp": "2026-03-21T14:35:12Z"
}

Open Interest Object

Represents aggregate open interest across all leverage traders.

JSON

{
  "symbol": "BTCUSDT",
  "timestamp": "2026-03-21T14:00:00Z",
  "total_oi_usd": "12456000000.00",
  "long_oi_usd": "7234000000.00",
  "short_oi_usd": "5222000000.00",
  "long_short_ratio": 1.385,
  "oi_change_percent": 2.34,
  "exchanges": {
    "bybit": {
      "long": "3456000000.00",
      "short": "2123000000.00"
    },
    "binance": {
      "long": "2567000000.00",
      "short": "2234000000.00"
    },
    "hyperliquid": {
      "long": "1211000000.00",
      "short": "865000000.00"
    }
  }
}

Confirmation Score Object

AI-generated trading signal combining whale positions, on-chain data, funding rates, and market sentiment.

JSON

{
  "symbol": "BTCUSDT",
  "overall_score": 78,
  "signal": "bullish",
  "confidence": 0.85,
  "timestamp": "2026-03-21T14:30:00Z",
  "components": {
    "whale_score": 82,
    "on_chain_score": 75,
    "funding_score": 68,
    "liquidation_score": 72,
    "sentiment_score": 85
  },
  "reasoning": "Large whale accumulation with positive on-chain signals",
  "next_update": "2026-03-21T14:45:00Z"
}

On-Chain Metrics Object

On-chain analytics for Bitcoin and Ethereum.

JSON

{
  "asset": "bitcoin",
  "timestamp": "2026-03-21T00:00:00Z",
  "exchange_flow": {
    "inflow_btc": "245.67",
    "outflow_btc": "812.34",
    "net_flow_btc": "-566.67"
  },
  "whale_wallets": {
    "count": 412,
    "total_btc": "1243567.89",
    "change_24h": 15.23
  },
  "mvrv_ratio": 1.42,
  "nupl": 0.68,
  "realized_price": "42156.50"
}

Error Response Object

Standard error response format for all endpoints.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "symbol",
        "error": "Invalid trading pair format"
      }
    ],
    "resolution": "Use format like BTCUSDT"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Explore All Data Models

Review complete schema definitions and field constraints for your integration.