Modelos de Datos & Referencia de Esquema

Referencia completa de los modelos de datos de Smart Money API. Aprende la estructura y definiciones de campos para todos los objetos de respuesta, incluyendo posiciones de ballenas, tasas de financiamiento, liquidaciones y puntajes de confirmación de IA.

Resumen

Comprender las estructuras de respuesta de la API es esencial para construir integraciones. Esta referencia documenta todas las definiciones de modelos de datos, tipos de campos, restricciones y ejemplos. Todas las marcas de tiempo están en formato ISO 8601 UTC. Todos los precios y cantidades se devuelven como cadenas para evitar pérdida de precisión en punto flotante.

Objeto Posición de Ballena

Representa una posición grande mantenida por una billetera de ballena monitoreada en un exchange de trading con apalancamiento.

Campo	Tipo	Descripción
id	string	Identificador único de posición
wallet_address	string	Dirección de la billetera de ballena (formato 0x...)
exchange	string	bybit, binance o hyperliquid
symbol	string	Par de trading (BTCUSDT, ETHUSDT, etc.)
position_type	string	long o short
position_size	string	Tamaño en el activo base (ej., BTC)
entry_price	string	Precio de entrada promedio en USDT
current_price	string	Precio de marca actual en USDT
liquidation_price	string	Precio al que la posición se liquida
pnl	string	P&L no realizado en USDT
pnl_percent	number	P&L no realizado como porcentaje
leverage	integer	Multiplicador de apalancamiento (1-20x)
margin_balance	string	Saldo de margen total en USDT
used_margin	string	Margen utilizado en USDT
available_margin	string	Margen disponible en USDT
margin_ratio	number	Relación margen disponible / margen utilizado
funding_rate	string	Tasa de financiamiento actual (% por hora)
time_opened	string	Marca de tiempo ISO 8601 cuando se abrió
last_updated	string	Marca de tiempo ISO 8601 de última actualización

Ejemplo de Posición de Ballena

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

Objeto Tasa de Financiamiento

Representa las tasas de financiamiento en múltiples exchanges para un solo símbolo y período de tiempo.

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

Objeto Liquidación

Representa una liquidación forzada de una posición apalancada.

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

Objeto Interés Abierto

Representa el interés abierto agregado de todos los traders con apalancamiento.

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

Objeto Puntaje de Confirmación

Señal de trading generada por IA que combina posiciones de ballenas, datos on-chain, tasas de financiamiento y sentimiento del mercado.

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": "Acumulación significativa de ballenas con señales on-chain positivas",
  "next_update": "2026-03-21T14:45:00Z"
}

Objeto Métricas On-Chain

Analítica on-chain para Bitcoin y 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"
}

Objeto Respuesta de Error

Formato estándar de respuesta de error para todos los endpoints.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Falló la validación de la solicitud",
    "details": [
      {
        "field": "symbol",
        "error": "Formato de par de trading inválido"
      }
    ],
    "resolution": "Usa formato como BTCUSDT"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Explora Todos los Modelos de Datos

Revisa definiciones completas de esquema y restricciones de campos para tu integración.

Ver Referencia de API REST