Referência Completa da API REST

Domine a Smart Money API com nossa referência REST abrangente. Aprenda todos os endpoints, parâmetros, métodos de autenticação e padrões de integração para inteligência de derivativos de cripto e dados de rastreamento de baleias.

Visão Geral

A Smart Money API fornece acesso RESTful a dados em tempo real de derivativos de criptomoedas em três grandes exchanges: Bybit, Binance e Hyperliquid. Nossa API agrega posições de carteiras de baleias, taxas de funding, métricas de juro aberto, dados de liquidação e sinais on-chain em uma única interface unificada. Se você está construindo algoritmos de trading, sistemas de gerenciamento de risco ou ferramentas de análise de mercado, a API REST oferece acesso programático direto a toda a inteligência Smart Money.

Com mais de 229 símbolos de trading descobertos automaticamente e 600+ carteiras de baleias monitoradas, a API fornece inteligência de mercado abrangente. Conexões WebSocket em tempo real fornecem atualizações em menos de um segundo, enquanto nossos endpoints REST lidam com consultas em lote, recuperação de dados históricos e análise de portfólio em escala.

Todas as requisições devem incluir credenciais de autenticação válidas. Usuários do nível gratuito têm 20 requisições por dia limitadas a BTC. O nível Trader (400 requisições/dia) e o nível Pro (4.000 requisições/dia) desbloqueiam todos os símbolos e recursos avançados.

Autenticação

A Smart Money API usa autenticação por chave de API. O método principal é o X-API-Key cabeçalho da requisição. Você pode gerar chaves de API a partir do seu painel. Um JWT de sessão via Authorization: Bearer é aceito como alternativa para sessões de navegador/painel, mas clientes de API devem usar X-API-Key.

Autenticação por Chave de API (principal)

Envie sua chave de API no X-API-Key cabeçalho em cada requisição. Nunca coloque sua chave em uma 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 Sessão (alternativa)

Sessões de navegador/painel podem passar um JWT de sessão via Authorization: Bearer (válido por 24 horas). Clientes programáticos devem preferir X-API-Key.

Python

import requests
import json

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

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

URL Base & Endpoints

Todas as requisições da API são enviadas para https://api.smartmoneyapi.com. A API está organizada em categorias de recursos lógicos com prefixos de versão. A versão estável atual é v1.

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

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

Formato da Resposta

Todas as respostas da API são retornadas como objetos JSON com um formato de envelope padrão. Respostas bem-sucedidas retornam códigos de status HTTP 200-299 com dados no corpo da resposta. Respostas de erro incluem mensagens detalhadas e sugestões de resolução.

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 Posições de Baleias

Recupere posições detalhadas de carteiras de baleias monitoradas em todas as exchanges. Este endpoint mostra alavancagem em tempo real, preços de entrada, preços de liquidação e P&L não realizado para posições de alto valor.

GET /v1/whales/events PRO

Parâmetro	Tipo	Descrição
symbol	string	Par de trading (ex: BTCUSDT, ETHUSDT) opcional
exchange	string	Filtrar por exchange: bybit, binance, hyperliquid opcional
min_position_size	number	Tamanho mínimo da posição no ativo base opcional
direction	string	Apenas posições long ou short opcional
page	integer	Número da página, padrão 1 opcional
limit	integer	Resultados por página, máximo 100, padrão 50 opcional

Exemplo de Requisição:

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 Taxas de Funding

Acesse taxas de funding em tempo real e históricas em Bybit, Binance e Hyperliquid. Taxas de funding são críticas para arbitragem, estratégias swing e hedge de derivativos. Nossa API agrega taxas com granularidade de 15 minutos e fornece análise histórica.

GET /v1/funding-rates FREE

Parâmetro	Tipo	Descrição
symbol	string	Par de trading (ex: BTCUSDT) obrigatório
exchange	string	Exchange: bybit, binance, hyperliquid opcional
interval	string	1h, 4h, 1d, padrão 1h opcional
limit	integer	Períodos históricos a retornar, máximo 500 opcional

Exemplo de Requisição:

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 Interesse Aberto

Monitore o interesse agregado aberto de todos os traders alavancados. A divergência do interesse aberto em relação ao movimento de preço sinaliza potenciais reversões e oportunidades de continuação de tendência. Acompanhe tanto o IO absoluto quanto as taxas de mudança do IO.

GET /v1/open-interest TRADER

Parâmetro	Tipo	Descrição
symbol	string	Par de negociação obrigatório
exchange	string	bybit, binance ou hyperliquid opcional
granularity	string	1m, 5m, 15m, 1h, 4h, 1d, padrão 15m opcional

Endpoint de Liquidações

Retorna duas visões complementares para um símbolo: níveis projetados por alavancagem níveis (uma estimativa de onde estão os clusters de liquidação) e um realized_heatmap — a INTENSIDADE REAL de liquidações forçadas executadas (preço × tempo) agregada ao vivo a partir de feeds WebSocket de exchanges públicas: Binance, OKX, Bybit, Bitget e BitMEX. O heatmap está presente quando o stream tem dados para o símbolo.

GET /v1/liquidations TRADER

Parâmetro	Tipo	Descrição
symbol	string	Símbolo do ativo, padrão BTC opcional

Trader retorna risco em cascata, distâncias mais próximas e totais/por lado realizados. Pro retorna níveis projetados completos níveis além do realized_heatmap (matrizes, clusters por preço, contagens por exchange).

Liquidações On-Chain DeFi

Liquidações executadas em protocolos de empréstimos DeFi capturadas diretamente de nossos próprios nós completos locais da BSC e Avalanche — independentes de qualquer bot de negociação. Cobre Venus/Cream e Moolah na BSC, e AAVE V3/V2, Benqi, BankerJoe, Granary e Vinium na Avalanche. Requer uma chave autenticada (Trader+); Pro adicionalmente retorna posições em risco dependentes de bot.

GET /v1/liquidations/onchain TRADER

Parâmetro	Tipo	Descrição
chain	string	bsc ou avax; omitir para todos opcional
limit	integer	Máximo de linhas, padrão 100, máximo 500 (mais recentes primeiro) opcional

Endpoint de Confirmação

O /v1/confirm endpoint retorna uma pontuação de confluência baseada em regras e multifatorial confluence combinando derivativos, on-chain (Coin Metrics gratuitos: MVRV / fluxo de exchange / endereços ativos) e posicionamento de baleias. O composite varia de -1.0 a +1.0 (não 0–100) e cada resposta inclui uma factors transparente adjustments, pesos, e coverage. É suporte para decisão, não uma taxa de vitória garantida. Um símbolo não rastreado retorna um resultado explícito NO_DATA / não suportado em vez de um LOW fabricado.

GET /v1/confirm TRADER

Parâmetros: symbol (BTC/ETH/SOL) e direction (long/short). confidence é um de HIGH / MEDIUM / LOW / VETO / NO_DATA; action é um de CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP; size_mult é o multiplicador sugerido para o tamanho da posição.

Endpoints de Dados On-Chain

Acesse métricas on-chain de Bitcoin e Ethereum, incluindo fluxos de exchange, movimentos de carteiras de baleias, razão MVRV, NUPL, condições de gasto e volatilidade realizada. Essas métricas identificam ciclos de acumulação/distribuição e fornecem sinais precoces para grandes reversões.

GET /v1/on-chain/metrics PRO

Parâmetro	Tipo	Descrição
asset	string	bitcoin ou ethereum obrigatório
metrics	array	Métricas específicas: exchange_flows, mvrv, nupl, whale_moves opcional
interval	string	1d (diário), 1w (semanal), padrão 1d opcional

Referência de Modelos de Dados

Entender a estrutura das respostas da API é essencial para integração. Abaixo estão as definições completas dos modelos de dados usados em todos os 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
  }
}

Exemplos de Código

Abaixo estão exemplos de código prontos para produção para padrões comuns de integração.

Monitorar Posições de Baleias em 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:
        """Buscar posições de baleias com 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:
        """Obter taxas de funding atuais 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):
        """Monitorar continuamente as posições de baleias"""
        while True:
            positions = self.get_whale_positions(symbol)
            if positions["success"]:
                for pos in positions["data"]["positions"]:
                    print(f"Baleia {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"Total de posições de baleias: {whales['data']['total']}")

Melhores Práticas & Dicas de Performance

Use paginação: Sempre pagine grandes conjuntos de resultados. Use os parâmetros limit e page para buscar dados em lotes de 50-100 registros, não todos de uma vez.

Armazene respostas em cache: As posições de baleias não mudam a cada segundo. Armazene os resultados em cache por 30-60 segundos para reduzir chamadas à API e melhorar o desempenho.

Filtre cedo: Use parâmetros de consulta (symbol, exchange, direction) para filtrar dados no servidor, não no código do seu aplicativo.

Lide com limites de taxa: Implemente lógica de retentativa com backoff exponencial. Quando atingir os limites de taxa (status 429), espere e tente novamente.

Use WebSocket para tempo real: Para dados em streaming, prefira conexões WebSocket em vez de endpoints REST de polling. Você economizará largura de banda e terá latência inferior a um segundo.

Valide timestamps: Todos os timestamps estão no formato ISO 8601 UTC. Sempre converta para o seu fuso horário local para exibição e sempre armazene em UTC.

Lide com desconexões: Implemente lógica de reconexão automática com backoff exponencial para conexões WebSocket.

Monitore sua cota: Verifique o cabeçalho X-Requests-Remaining nas respostas. Planeje seu uso da API para permanecer dentro do limite do seu plano.

Padrões Comuns de Integração

Padrão 1: Alerta sobre Acumulação de Baleias

Configure alertas quando as posições de baleias ultrapassarem um limite, sinalizando possíveis fases de acumulação ou bull runs.

Padrão 2: Detecção de Arbitragem de Taxa de Funding

Detecte automaticamente quando os spreads de taxa de funding excederem limites lucrativos entre exchanges, permitindo algoritmos de arbitragem entre exchanges.

Padrão 3: Monitoramento de Cascata de Liquidações

Acompanhe grandes liquidações e posicione o algoritmo para capitalizar em liquidações em cascata e movimentos de preço de alto impacto.

Padrão 4: Confirmação de Múltiplos Sinais

Combine posições de baleias, taxas de funding, métricas on-chain e nossos scores de confirmação de IA para sinais de entrada com alta convicção.

Pronto para Começar?

Obtenha sua chave de API no console e comece a construir hoje. Todas as novas contas recebem acesso ao plano gratuito com 20 solicitações por dia (BTC, ETH, SOL). Atualize para Trader ou Pro para acesso ilimitado a todos os símbolos e recursos avançados.

Obter Chave de API

Desbloqueie Recursos Pro

Tenha acesso completo a posições de baleias, scores de confirmação, dados on-chain e 2000+ solicitações de API diárias.

Ver Preços