Referencia completa de la API REST

Domina la API Smart Money con nuestra referencia REST exhaustiva. Aprende todos los endpoints, parámetros, métodos de autenticación y patrones de integración en el mundo real para inteligencia de derivados cripto y seguimiento de datos de ballenas.

Resumen

La API Smart Money proporciona acceso RESTful a datos en tiempo real de derivados de criptomonedas en tres exchanges principales: Bybit, Binance y Hyperliquid. Nuestra API agrega posiciones de carteras de ballenas, tasas de financiación, métricas de interés abierto, datos de liquidación y señales on-chain en una única interfaz unificada. Ya sea que estés construyendo algoritmos de trading, sistemas de gestión de riesgos o herramientas de análisis de mercado, la API REST te brinda acceso programático directo a toda la inteligencia Smart Money.

Con más de 229 símbolos de trading descubiertos automáticamente y más de 600 carteras de ballenas monitoreadas, la API proporciona inteligencia de mercado integral. Las conexiones WebSocket en tiempo real ofrecen actualizaciones en menos de un segundo, mientras que nuestros endpoints REST manejan consultas por lotes, recuperación de datos históricos y análisis de cartera a escala.

Todas las solicitudes deben incluir credenciales de autenticación válidas. Los usuarios del nivel gratuito tienen 20 solicitudes por día limitadas a BTC. Los niveles Trader (400 solicitudes/día) y Pro (4,000 solicitudes/día) desbloquean todos los símbolos y funciones avanzadas.

Autenticación

La API Smart Money utiliza autenticación por clave API. El método principal es el X-API-Key encabezado de solicitud. Puedes generar claves API desde tu panel. Un JWT de sesión a través de Authorization: Bearer se acepta como alternativa para sesiones de navegador/panel, pero los clientes API deben usar X-API-Key.

Autenticación por clave API (principal)

Envía tu clave API en el X-API-Key encabezado en cada solicitud. Nunca coloques tu clave en una URL.

HTTP

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

JWT de sesión (alternativa)

Las sesiones de navegador/panel pueden pasar un JWT de sesión a través de Authorization: Bearer (válido por 24 horas). Los clientes programáticos deben preferir X-API-Key.

Python

import requests
import json

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

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

URL base y endpoints

Todas las solicitudes API van a https://api.smartmoneyapi.com. La API está organizada en categorías de recursos lógicos con prefijos de versión. La versión estable actual es v1.

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

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

Formato de respuesta

Todas las respuestas de la API se devuelven como objetos JSON con un formato de envoltura estándar. Las respuestas exitosas devuelven códigos de estado HTTP 200-299 con datos en el cuerpo de la respuesta. Las respuestas de error incluyen mensajes detallados y sugerencias de resolución.

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

Endpoint de posiciones de ballenas

Recupera posiciones detalladas de carteras de ballenas monitoreadas en todos los exchanges. Este endpoint muestra el apalancamiento en tiempo real, precios de entrada, precios de liquidación y P&L no realizado para posiciones de alto valor.

GET /v1/whales/events PRO

Parámetro	Tipo	Descripción
symbol	string	Par de trading (ej., BTCUSDT, ETHUSDT) opcional
exchange	string	Filtrar por exchange: bybit, binance, hyperliquid opcional
min_position_size	number	Tamaño mínimo de posición en el activo base opcional
direction	string	Solo posiciones long o short opcional
page	integer	Número de página de paginación, predeterminado 1 opcional
limit	integer	Resultados por página, máximo 100, predeterminado 50 opcional

Ejemplo de solicitud:

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"

Endpoint de tasas de financiación

Accede a tasas de financiación en tiempo real e históricas en Bybit, Binance y Hyperliquid. Las tasas de financiación son críticas para el trading de arbitraje, estrategias de swing y cobertura de derivados. Nuestra API agrega tasas con granularidad de 15 minutos y proporciona análisis de tasas históricas.

GET /v1/funding-rates FREE

Parámetro	Tipo	Descripción
symbol	string	Par de trading (ej., BTCUSDT) requerido
exchange	string	Exchange: bybit, binance, hyperliquid opcional
interval	string	1h, 4h, 1d, predeterminado 1h opcional
limit	integer	Períodos históricos a devolver, máximo 500 opcional

Ejemplo de solicitud:

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

Endpoint de Interés Abierto

Monitorea el interés abierto agregado de todos los traders con apalancamiento. La divergencia del interés abierto respecto al movimiento del precio señala posibles reversiones y oportunidades de continuación de tendencia. Rastrea tanto el interés abierto absoluto como las tasas de cambio del interés abierto.

GET /v1/open-interest TRADER

Parámetro	Tipo	Descripción
symbol	string	Par de trading requerido
exchange	string	bybit, binance, o hyperliquid opcional
granularity	string	1m, 5m, 15m, 1h, 4h, 1d, por defecto 15m opcional

Endpoint de Liquidaciones

Devuelve dos vistas complementarias para un símbolo: niveles proyectados por apalancamiento niveles (una estimación de dónde se encuentran los clusters de liquidación) y un realized_heatmap — la INTENSIDAD REAL de liquidaciones forzadas ejecutadas (precio × tiempo) agregada en vivo desde los feeds WebSocket de intercambios públicos: Binance, OKX, Bybit, Bitget y BitMEX. El mapa de calor está presente cuando el stream tiene datos para el símbolo.

GET /v1/liquidations TRADER

Parámetro	Tipo	Descripción
symbol	string	Símbolo del activo, por defecto BTC opcional

Trader devuelve el riesgo de cascada, las distancias más cercanas y los totales/por lado realizados. Pro devuelve los niveles proyectados completos niveles más el realized_heatmap completo (matrices, clusters por precio, recuentos por exchange).

Liquidaciones On-Chain DeFi

Liquidaciones ejecutadas en protocolos de préstamos DeFi capturadas directamente desde nuestros propios nodos completos de BSC y Avalanche — independientes de cualquier bot de trading. Cubre Venus/Cream y Moolah en BSC, y AAVE V3/V2, Benqi, BankerJoe, Granary y Vinium en Avalanche. Requiere una clave autenticada (Trader+); Pro adicionalmente devuelve posiciones en riesgo dependientes de bots.

GET /v1/liquidations/onchain TRADER

Parámetro	Tipo	Descripción
chain	string	bsc o avax; omitir para todos opcional
limit	integer	Máximo de filas, por defecto 100, máximo 500 (los más recientes primero) opcional

Endpoint de Confirmación

El /v1/confirm endpoint devuelve una puntuación de confluencia basada en reglas y múltiples factores confluencia que combina derivados, datos on-chain (gratis de Coin Metrics: MVRV / flujo de exchange / direcciones activas) y posicionamiento de ballenas. La compuesta oscila entre -1.0 y +1.0 (no 0–100) y cada respuesta incluye un desglose transparente de factores (puntuación por componente × peso), ajustes, pesos, y cobertura. Es un apoyo para la toma de decisiones, no una tasa de acierto garantizada. Un símbolo no rastreado devuelve un resultado explícito NO_DATA / no soportado en lugar de un LOW fabricado.

GET /v1/confirm TRADER

Parámetros: symbol (BTC/ETH/SOL) y direction (long/short). confidence es uno de HIGH / MEDIUM / LOW / VETO / NO_DATA; action es uno de CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP; size_mult es el multiplicador sugerido para el tamaño de la posición.

Endpoints de Datos On-Chain

Accede a métricas on-chain de Bitcoin y Ethereum, incluyendo flujos de exchange, movimientos de carteras de ballenas, ratio MVRV, NUPL, condiciones de gasto y volatilidad realizada. Estas métricas identifican ciclos de acumulación/distribución y proporcionan señales tempranas de reversiones importantes.

GET /v1/on-chain/metrics PRO

Parámetro	Tipo	Descripción
asset	string	bitcoin o ethereum required
metrics	array	Métricas específicas: exchange_flows, mvrv, nupl, whale_moves opcional
interval	string	1d (diario), 1w (semanal), por defecto 1d opcional

Referencia de Modelos de Datos

Comprender la estructura de las respuestas de la API es esencial para la integración. A continuación se encuentran las definiciones completas de los modelos de datos utilizados en todos los endpoints.

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

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

Ejemplos de código

A continuación, ejemplos de código listos para producción para patrones comunes de integración.

Monitorear posiciones de ballenas en 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:
        """Obtener posiciones de ballenas con filtro opcional de símbolo"""
        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:
        """Obtener tasas de financiación actuales e históricas"""
        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):
        """Monitorear continuamente posiciones de ballenas"""
        while True:
            positions = self.get_whale_positions(symbol)
            if positions["success"]:
                for pos in positions["data"]["positions"]:
                    print(f"Ballena {pos['wallet_address'][:10]}: "
                          f"{pos['position_type']} "
                          f"{pos['position_size']} {symbol} "
                          f"PnL: {pos['pnl_percent']}%")
            time.sleep(interval_seconds)

# Uso
client = SmartMoneyClient("sk_live_abc123xyz789")
whales = client.get_whale_positions("BTCUSDT")
print(f"Posiciones totales de ballenas: {whales['data']['total']}")

Mejores prácticas y consejos de rendimiento

Usa paginación: Siempre pagina grandes conjuntos de resultados. Usa los parámetros limit y page para obtener datos en bloques de 50-100 registros, no todos a la vez.

Cachea respuestas: Las posiciones de ballenas no cambian cada segundo. Cachea resultados por 30-60 segundos para reducir llamadas a la API y mejorar el rendimiento.

Filtra temprano: Usa parámetros de consulta (symbol, exchange, direction) para filtrar datos del lado del servidor, no en tu código de aplicación.

Maneja límites de tasa: Implementa lógica de reintento con retroceso exponencial. Cuando alcances límites de tasa (estado 429), espera y reintenta.

Usa WebSocket para tiempo real: Para datos en streaming, prefiere conexiones WebSocket sobre endpoints REST de sondeo. Ahorrarás ancho de banda y obtendrás latencia submilisegundo.

Valida marcas de tiempo: Todas las marcas de tiempo son ISO 8601 UTC. Siempre convierte a tu zona horaria local para mostrar y siempre almacena en UTC.

Maneja desconexiones: Implementa lógica de reconexión automática con retroceso exponencial para conexiones WebSocket.

Monitorea tu cuota: Revisa el encabezado X-Requests-Remaining en las respuestas. Planifica tu uso de la API para mantenerte dentro de tu límite de nivel.

Patrones comunes de integración

Patrón 1: Alertas sobre acumulación de ballenas

Configura alertas cuando las posiciones de ballenas superen un umbral, señalando posibles fases de acumulación o corridas alcistas.

Patrón 2: Detección de arbitraje de tasas de financiación

Detecta automáticamente cuando los diferenciales de tasas de financiación superan umbrales rentables entre exchanges, permitiendo algoritmos de arbitraje entre exchanges.

Patrón 3: Monitoreo de cascadas de liquidación

Rastrea grandes liquidaciones y posiciona el algoritmo para capitalizar en cascadas de liquidaciones y movimientos de precio de alto impacto.

Patrón 4: Confirmación multi-señal

Combina posiciones de ballenas, tasas de financiación, métricas on-chain y nuestros puntajes de confirmación de IA para señales de entrada de alta convicción.

¿Listo para comenzar?

Obtén tu clave API desde la consola y empieza a construir hoy. Todas las cuentas nuevas obtienen acceso gratuito con 20 solicitudes diarias (BTC, ETH, SOL). Actualiza a Trader o Pro para acceso ilimitado a todos los símbolos y funciones avanzadas.

Obtener clave API

Desbloquea funciones Pro

Obtén acceso completo a posiciones de ballenas, puntajes de confirmación, datos on-chain y 2000+ solicitudes API diarias.

Ver precios