Riferimento completo API REST

Padroneggia la Smart Money API con il nostro riferimento REST completo. Scopri tutti gli endpoint, i parametri, i metodi di autenticazione e i modelli di integrazione reali per l'intelligence sui derivati crypto e il tracciamento delle balene.

Panoramica

La Smart Money API offre accesso RESTful ai dati in tempo reale sui derivati delle criptovalute su tre exchange principali: Bybit, Binance e Hyperliquid. La nostra API aggrega le posizioni dei portafogli delle balene, i tassi di funding, le metriche di open interest, i dati sulle liquidazioni e i segnali on-chain in un'unica interfaccia. Che tu stia costruendo algoritmi di trading, sistemi di gestione del rischio o strumenti di analisi di mercato, l'API REST ti dà accesso programmatico diretto a tutta l'intelligenza Smart Money.

Con oltre 229 simboli di trading rilevati automaticamente e più di 600 portafogli di balene monitorati, l'API fornisce un'intelligenza di mercato completa. Le connessioni WebSocket in tempo reale forniscono aggiornamenti in meno di un secondo, mentre i nostri endpoint REST gestiscono query batch, recupero di dati storici e analisi del portafoglio su larga scala.

Tutte le richieste devono includere credenziali di autenticazione valide. Gli utenti del piano gratuito hanno 20 richieste al giorno limitate a BTC. I piani Trader (400 richieste/giorno) e Pro (4.000 richieste/giorno) sbloccano tutti i simboli e le funzionalità avanzate.

Autenticazione

La Smart Money API utilizza l'autenticazione tramite chiave API. Il metodo principale è l'header di richiesta X-API-Key . Puoi generare le chiavi API dalla tua dashboard. Un JWT di sessione tramite Authorization: Bearer è accettato come soluzione alternativa per le sessioni del browser/dashboard, ma i client API dovrebbero utilizzare X-API-Key.

Autenticazione con chiave API (principale)

Invia la tua chiave API nell'header X-API-Key in ogni richiesta. Non inserire mai la tua chiave in un URL.

HTTP

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

JWT di sessione (alternativa)

Le sessioni del browser/dashboard possono passare un JWT di sessione tramite Authorization: Bearer (valido per 24 ore). I client programmatici dovrebbero preferire X-API-Key.

Python

import requests
import json

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

# Usa il JWT per le richieste successive
headers = {"Authorization": f"Bearer {token}"}
whales = requests.get(
  "https://api.smartmoneyapi.com/v1/whales/events",
  headers=headers
)
print(whales.json())

URL base ed endpoint

Tutte le richieste API vanno a https://api.smartmoneyapi.com. L'API è organizzata in categorie logiche di risorse con prefissi di versione. La versione stabile attuale è v1.

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

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

Formato della risposta

Tutte le risposte dell'API vengono restituite come oggetti JSON con un formato standard. Le risposte di successo restituiscono codici di stato HTTP 200-299 con i dati nel corpo della risposta. Le risposte di errore includono messaggi di errore dettagliati e suggerimenti per la risoluzione.

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 Posizioni delle balene

Recupera le posizioni dettagliate dai portafogli delle balene monitorati su tutti gli exchange. Questo endpoint mostra la leva in tempo reale, i prezzi di ingresso, i prezzi di liquidazione e il P&L non realizzato per le posizioni di alto valore.

GET /v1/whales/events PRO

Parametro	Tipo	Descrizione
symbol	string	Coppia di trading (es. BTCUSDT, ETHUSDT) opzionale
exchange	string	Filtra per exchange: bybit, binance, hyperliquid opzionale
min_position_size	number	Dimensione minima della posizione nell'asset base opzionale
direction	string	Solo posizioni long o short opzionale
page	integer	Numero di pagina per la paginazione, predefinito 1 opzionale
limit	integer	Risultati per pagina, massimo 100, predefinito 50 opzionale

Esempio di richiesta:

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 Tassi di funding

Accedi ai tassi di funding in tempo reale e storici su Bybit, Binance e Hyperliquid. I tassi di funding sono fondamentali per il trading di arbitraggio, le strategie swing e la copertura dei derivati. La nostra API aggrega i tassi con granularità di 15 minuti e fornisce analisi dei tassi storici.

GET /v1/funding-rates FREE

Parametro	Tipo	Descrizione
symbol	string	Coppia di trading (es. BTCUSDT) obbligatorio
exchange	string	Exchange: bybit, binance, hyperliquid opzionale
interval	string	1h, 4h, 1d, predefinito 1h opzionale
limit	integer	Periodi storici da restituire, massimo 500 opzionale

Esempio di richiesta:

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 Open Interest

Monitora l'open interest aggregato di tutti i trader con leva. Una divergenza tra l'open interest e il movimento dei prezzi segnala potenziali inversioni e opportunità di continuazione del trend. Tieni traccia sia dell'OI assoluto che dei tassi di variazione dell'OI.

GET /v1/open-interest TRADER

Parametro	Tipo	Descrizione
symbol	string	Coppia di trading obbligatorio
exchange	string	bybit, binance o hyperliquid opzionale
granularity	string	1m, 5m, 15m, 1h, 4h, 1d, default 15m opzionale

Endpoint Liquidazioni

Restituisce due visualizzazioni complementari per un simbolo: i livelli livelli (una stima di dove si trovano i cluster di liquidazione) e una realized_heatmap — l'INTENSITÀ effettiva delle liquidazioni forzate eseguite (prezzo × tempo) aggregata in tempo reale dai feed WebSocket degli exchange pubblici: Binance, OKX, Bybit, Bitget e BitMEX. La heatmap è presente quando lo stream ha dati per il simbolo.

GET /v1/liquidations TRADER

Parametro	Tipo	Descrizione
symbol	string	Simbolo dell'asset, default BTC opzionale

Trader restituisce il rischio a cascata, le distanze più vicine e i totali/divisi per lato realizzati. Pro restituisce i livelli livelli completi più la realized_heatmap completa (matrici, cluster per prezzo, conteggi per exchange).

Liquidazioni On-Chain DeFi

Liquidazioni eseguite sui protocolli di lending DeFi catturate direttamente dai nostri nodi completi locali su BSC e Avalanche — indipendenti da qualsiasi trading bot. Copre Venus/Cream e Moolah su BSC, e AAVE V3/V2, Benqi, BankerJoe, Granary e Vinium su Avalanche. Richiede una chiave autenticata (Trader+); Pro restituisce anche le posizioni a rischio dipendenti dai bot.

GET /v1/liquidations/onchain TRADER

Parametro	Tipo	Descrizione
chain	string	bsc o avax; ometti per tutti opzionale
limit	integer	Numero massimo di righe, default 100, max 500 (più recenti prima) opzionale

Endpoint Conferma

L'endpoint /v1/confirm restituisce un punteggio di confluenza basato su regole e multi-fattore, combinando derivati, on-chain (dati gratuiti di Coin Metrics: MVRV / flussi di exchange / indirizzi attivi) e posizionamento delle balene. Il composito varia da -1.0 a +1.0 (non 0–100) e ogni risposta include una trasparente scomposizione dei fattori (punteggio per componente × peso), aggiustamenti, pesi, e copertura. È un supporto decisionale, non una garanzia di win-rate. Un simbolo non tracciato restituisce un esplicito risultato NO_DATA / non supportato anziché un falso LOW.

GET /v1/confirm TRADER

Parametri: symbol (BTC/ETH/SOL) e direction (long/short). confidence è uno tra HIGH / MEDIUM / LOW / VETO / NO_DATA; action è uno tra CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP; size_mult è il moltiplicatore suggerito per la dimensione della posizione.

Endpoint Dati On-Chain

Accedi a metriche on-chain di Bitcoin ed Ethereum, inclusi flussi di exchange, movimenti di portafogli di balene, rapporto MVRV, NUPL, condizioni di spesa e volatilità realizzata. Queste metriche identificano cicli di accumulo/distribuzione e forniscono segnali precoci per grandi inversioni.

GET /v1/on-chain/metrics PRO

Parametro	Tipo	Descrizione
asset	string	bitcoin o ethereum obbligatorio
metrics	array	Metriche specifiche: exchange_flows, mvrv, nupl, whale_moves opzionale
interval	string	1d (giornaliero), 1w (settimanale), default 1d opzionale

Riferimento Modelli di Dati

Comprendere la struttura delle risposte API è essenziale per l'integrazione. Di seguito sono riportate le definizioni complete dei modelli di dati utilizzati in tutti gli endpoint.

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

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

Esempi di Codice

Di seguito sono riportati esempi di codice pronti per la produzione per modelli di integrazione comuni.

Monitora le Posizioni delle Balene in 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:
        """Recupera le posizioni delle balene con filtro opzionale per simbolo"""
        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:
        """Ottieni i tassi di finanziamento correnti e storici"""
        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):
        """Monitora continuamente le posizioni delle balene"""
        while True:
            positions = self.get_whale_positions(symbol)
            if positions["success"]:
                for pos in positions["data"]["positions"]:
                    print(f"Balena {pos['wallet_address'][:10]}: "
                          f"{pos['position_type']} "
                          f"{pos['position_size']} {symbol} "
                          f"PnL: {pos['pnl_percent']}%")
            time.sleep(interval_seconds)

# Utilizzo
client = SmartMoneyClient("sk_live_abc123xyz789")
whales = client.get_whale_positions("BTCUSDT")
print(f"Posizioni totali delle balene: {whales['data']['total']}")

Best Practice & Suggerimenti sulle Prestazioni

Usa la paginazione: Pagina sempre i set di risultati di grandi dimensioni. Usa i parametri limit e page per recuperare i dati in blocchi di 50-100 record, non tutti i dati in una volta.

Memorizza nella cache le risposte: Le posizioni delle balene non cambiano ogni secondo. Memorizza i risultati per 30-60 secondi per ridurre le chiamate API e migliorare le prestazioni.

Filtra presto: Usa i parametri di query (symbol, exchange, direction) per filtrare i dati lato server, non nel codice della tua applicazione.

Gestisci i limiti di frequenza: Implementa una logica di ritentativi con backoff esponenziale. Quando raggiungi i limiti di frequenza (status 429), attendi e ritenta.

Usa WebSocket per dati in tempo reale: Per i dati in streaming, preferisci le connessioni WebSocket rispetto al polling degli endpoint REST. Risparmierai larghezza di banda e otterrai una latenza inferiore al secondo.

Convalida i timestamp: Tutti i timestamp sono in formato ISO 8601 UTC. Convertili sempre nel tuo fuso orario locale per la visualizzazione e conservali sempre in UTC.

Gestisci le disconnessioni: Implementa una logica di riconnessione automatica con backoff esponenziale per le connessioni WebSocket.

Monitora la tua quota: Controlla l'intestazione X-Requests-Remaining nelle risposte. Pianifica l'uso dell'API per rimanere entro i limiti del tuo livello.

Modelli Comuni di Integrazione

Modello 1: Avviso sull'Accumulo delle Balene

Imposta avvisi quando le posizioni delle balene superano una soglia, segnalando potenziali fasi di accumulo o rialzi.

Modello 2: Rilevamento dell'Arbitraggio sui Tassi di Finanziamento

Rileva automaticamente quando gli spread dei tassi di finanziamento superano soglie redditizie tra gli exchange, abilitando algoritmi di arbitraggio cross-exchange.

Modello 3: Monitoraggio delle Cascate di Liquidazione

Traccia le grandi liquidazioni e posiziona l'algoritmo per sfruttare le liquidazioni a cascata e i movimenti di prezzo ad alto impatto.

Modello 4: Conferma Multi-Segnale

Combina posizioni delle balene, tassi di finanziamento, metriche on-chain e i nostri punteggi di conferma AI per segnali di ingresso ad alta convinzione.

Pronto a Iniziare?

Ottieni la tua chiave API dalla console e inizia a costruire oggi stesso. Tutti i nuovi account ottengono accesso al livello gratuito con 20 richieste al giorno (BTC, ETH, SOL). Passa a Trader o Pro per accesso illimitato a tutti i simboli e funzionalità avanzate.

Ottieni Chiave API

Sblocca Funzionalità Pro

Ottieni l'accesso completo alle posizioni delle balene, ai punteggi di conferma, ai dati on-chain e a 2000+ richieste API giornaliere.

Visualizza Prezzi