Guía de Autenticación

Aprende cómo autenticarte con Smart Money API usando claves API, tokens JWT y OAuth 2.0. Protege tus integraciones con métodos de autenticación estándar de la industria y mejores prácticas.

Resumen

Smart Money API admite múltiples métodos de autenticación para diferentes casos de uso. Elige el método que mejor se adapte a tu integración:

Claves API (principal): Envía tu clave en el X-API-Key encabezado de la solicitud para todas las llamadas a la API REST. Este es el método recomendado para bots y uso de servidor a servidor.

JWT de Sesión (alternativo): Las sesiones del navegador/panel se autentican con 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.

OAuth 2.0: Autenticación de grado empresarial para aplicaciones multi-usuario e integraciones de terceros. Los usuarios autorizan a tu aplicación para acceder a sus datos.

Todas las solicitudes a la API deben realizarse sobre HTTPS. Las solicitudes HTTP no cifradas serán rechazadas. Además, nunca comprometas las claves API en el control de versiones ni las compartas públicamente.

Claves API

Las claves API son credenciales únicas emitidas para tu cuenta. Cada clave representa un conjunto único de permisos y cuotas. Puedes generar múltiples claves para diferentes aplicaciones o entornos (desarrollo, pruebas, producción).

Generar una Clave API

Genera claves API desde la consola de tu cuenta:

Navega a Smart Money Console
Selecciona "Claves API" en la barra lateral
Haz clic en "Generar Nueva Clave"
Elige el tipo de clave (Desarrollo, Pruebas, Producción)
Establece el límite de tasa y las características
Copia y almacena la clave de forma segura

¡Guarda tu clave API inmediatamente! No podrás verla nuevamente. Si la pierdes, necesitarás generar una nueva clave.

Formato de la Clave

Las claves API siguen un formato estándar:

Formato de la Clave

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

Los prefijos de las claves indican el entorno:

sk_live_ — Claves de producción con cuota completa

sk_test_ — Claves de prueba con cuota reducida y datos de desarrollo

sk_dev_ — Claves de desarrollo personal con datos de sandbox

Encabezado X-API-Key (principal)

Envía tu clave API en el X-API-Key encabezado de la solicitud para todas las solicitudes a la API. Nunca coloques tu clave en una URL.

Encabezado HTTP

HTTP

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

Ejemplo cURL

Shell

curl -X GET https://api.smartmoneyapi.com/v1/whales/events \
  -H "X-API-Key: sm_your_key" \
  -H "Content-Type: application/json"

Ejemplo en Python

Python

import requests

api_key = "sm_your_key"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.smartmoneyapi.com/v1/whales/events",
    headers=headers
)

data = response.json()

Autenticación con Token JWT

Para sesiones de larga duración y comunicación de servidor a servidor, intercambia tu clave API por un token JWT. Los tokens JWT duran 24 horas y reducen la necesidad de almacenar tu clave API en el código de la aplicación.

Obtener un Token JWT

Envía tu clave API mediante POST al endpoint JWT para obtener un token:

cURL

curl -X POST https://api.smartmoneyapi.com/auth/jwt \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m"
  }'

Respuesta JWT

JSON

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Usar el Token JWT

Usa el token JWT en el encabezado Authorization como lo harías con las claves API:

Python

import requests
import json
from datetime import datetime, timedelta

class JWTAuth:
    def __init__(self, api_key):
        self.api_key = api_key
        self.token = None
        self.token_expires = None

    def get_valid_token(self):
        # Verifica si el token actual sigue siendo válido
        if self.token and self.token_expires > datetime.now():
            return self.token

        # Obtén un nuevo token
        response = requests.post(
            "https://api.smartmoneyapi.com/auth/jwt",
            json={"api_key": self.api_key}
        )

        data = response.json()
        self.token = data["token"]
        self.token_expires = datetime.now() + timedelta(seconds=data["expires_in"])

        return self.token

    def request(self, method, url, **kwargs):
        token = self.get_valid_token()
        headers = kwargs.get("headers", {})
        headers["Authorization"] = f"Bearer {token}"
        kwargs["headers"] = headers

        return requests.request(method, url, **kwargs)

# Uso
auth = JWTAuth("sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m")
response = auth.request(
    "GET",
    "https://api.smartmoneyapi.com/v1/whales/events"
)
print(response.json())

OAuth 2.0

OAuth 2.0 es para aplicaciones que necesitan acceder a múltiples cuentas de usuario. Los usuarios otorgan permiso a tu aplicación para acceder a sus datos sin compartir sus claves API.

Flujo de OAuth 2.0

Smart Money API admite el flujo de Código de Autorización para aplicaciones web:

El usuario hace clic en el botón "Conectar con Smart Money"
El navegador redirige a la página de autorización
El usuario otorga permiso a tu aplicación
El navegador redirige de vuelta con un código de autorización
Tu backend intercambia el código por un token de acceso
Ahora puedes acceder a los datos del usuario en su nombre

Paso 1: Solicitud de Autorización

Redirige al usuario al endpoint de autorización:

URL

https://auth.smartmoneyapi.com/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=whale_positions+funding_rates+liquidations&
state=random_state_string

Paso 2: Intercambio de Token

Después de que el usuario otorgue permiso, intercambia el código por un token de acceso:

cURL

curl -X POST https://auth.smartmoneyapi.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https://yourapp.com/callback"

Respuesta del Token OAuth

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "scope": "whale_positions funding_rates liquidations"
}

Mejores Prácticas de Seguridad

Almacena las Claves de Forma Segura

Nunca comprometas las claves API en el control de versiones, las codifiques directamente en las aplicaciones o las compartas en la documentación. Usa variables de entorno o servicios de gestión de claves seguros como AWS Secrets Manager, HashiCorp Vault o similares.

Usa Solo HTTPS

Todas las solicitudes a la API deben usar HTTPS (TLS 1.2 o superior). Las solicitudes HTTP serán rechazadas. Esto asegura que tu clave API y los datos estén cifrados en tránsito.

Limita los Permisos de las Claves

Crea claves API separadas para diferentes aplicaciones y entornos. Usa ámbitos para limitar lo que cada clave puede acceder. No uses claves de producción en desarrollo.

Monitorea el Uso de las Claves

Revisa regularmente el uso de la API en tu consola. Configura alertas para actividad inusual o cuotas que se acerquen a los límites. Elimina las claves que ya no uses.

Rotación de Claves

Rota tus claves API regularmente para reducir el riesgo de compromiso. Recomendamos rotar las claves cada 90 días:

Genera una nueva clave API en tu consola
Actualiza tus aplicaciones para usar la nueva clave
Prueba que todo funcione correctamente
Elimina la antigua clave desde tu consola

Ámbitos y permisos

Al crear claves API o usar OAuth, especifica qué recursos puede acceder tu clave:

Ámbito	Descripción	Nivel
whale_positions	Leer posiciones de carteras de ballenas	Trader+
funding_rates	Leer datos de tasas de financiación	Free+
liquidations	Leer feeds de liquidaciones	Free+
open_interest	Leer datos de interés abierto	Trader+
confirmation_scores	Leer puntuaciones de confirmación de IA	Pro+
on_chain	Leer métricas on-chain	Pro+

Ejemplos de código de autenticación

Integración completa en Python

Python

import requests
from typing import Optional, Dict
from datetime import datetime, timedelta

class SmartMoneyAuth:
    """Gestiona todos los métodos de autenticación para Smart Money API"""

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.smartmoneyapi.com"
        self.jwt_token = None
        self.jwt_expires = None

    def get_jwt_token(self) -> str:
        """Obtener o actualizar token JWT"""
        if self.jwt_token and self.jwt_expires > datetime.now():
            return self.jwt_token

        response = requests.post(
            f"{self.base_url}/auth/jwt",
            json={"api_key": self.api_key}
        )
        data = response.json()
        self.jwt_token = data["token"]
        self.jwt_expires = datetime.now() + timedelta(seconds=data["expires_in"] - 300)
        return self.jwt_token

    def headers_bearer(self) -> Dict:
        """Obtener cabeceras para autenticación Bearer"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Obtener cabeceras para autenticación JWT"""
        token = self.get_jwt_token()
        return {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    def request(self, method: str, endpoint: str, use_jwt: bool = False, **kwargs) -> Dict:
        """Realizar solicitud autenticada"""
        headers = self.headers_jwt() if use_jwt else self.headers_bearer()
        response = requests.request(
            method,
            f"{self.base_url}{endpoint}",
            headers=headers,
            **kwargs
        )
        return response.json()

# Uso
auth = SmartMoneyAuth("sk_live_abc123xyz789")

# Método Bearer token
whales = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT")

# Método JWT (auto-actualizable)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"Found {whales['data']['total']} whale positions")

¿Necesitas ayuda?

Consulta nuestra documentación API o contacta con soporte si necesitas asistencia con la autenticación.

Referencia API

Genera tu primera clave API

Comienza con Smart Money API. Crea tu cuenta y genera credenciales de autenticación en minutos.

Ir a Consola