Smart Money API
Un'API di intelligence di livello professionale che aggrega dati derivati, metriche on-chain e attività dei portafogli dei grandi investitori in un unico punteggio di fiducia per il tuo bot di trading.
https://api.smartmoneyapi.com/v1Principi di progettazione
Quattro idee modellano ogni endpoint e ogni punteggio restituito da questa API. Sono anche i limiti onesti di ciò che promette — e non promette.
Prima la strategia, non il segnale. Questo non è un feed di segnali di acquisto/vendita. Tu porti la strategia e l'ingresso; l'API ti dice se la struttura di mercato circostante — posizionamento derivati, finanziamento, interesse aperto, liquidazioni, flusso on-chain e consenso dei grandi investitori — è d'accordo con il trade che vuoi già fare.
Punteggio di fiducia, non previsione binaria. Ogni risposta porta un punteggio graduato confidence (ALTO / MEDIO / BASSO) e un composite da -1.0 a +1.0. Non ci sono garanzie e nessuna chiamata oracolare — ottieni una lettura calibrata sull'accordo, con le ragioni dietro di esso, in modo da poter dimensionare proporzionalmente alla convinzione.
Supporto decisionale, non consigli di esecuzione. L'API restituisce una raccomandazione CONFERMA / RIDUCI / SALTA e un moltiplicatore di dimensione per la tua logica su cui agire. Non effettua mai ordini e nulla qui è un consiglio finanziario. Rimani responsabile per il rischio, la dimensione e l'esecuzione.
Metriche viventi, non garanzie fisse. Tassi di vincita, statistiche di regime e cifre di accuratezza sono calcolati da un campione mobile e si muovono con i mercati. Le pubblichiamo onestamente, anche quando sono mediocri. Tratta ogni metrica come un'osservazione corrente, non una promessa sul futuro.
Per chi è questa API
Questa API è progettata per sviluppatori di bot, algoritmi e agenti AI per crypto che già dispongono di un segnale long/short — da una strategia TA, un modello ML, una pipeline Freqtrade, un alert TradingView o un agente LLM — e desiderano una rapida decisione pre-trade CONFERMA / RIDUCI / SALTA prima di impegnare capitale.
Un ciclo tipico: la tua strategia genera "vai long su BTC" → chiami GET /v1/confirm?symbol=BTC&direction=long → confermi, riduci o salti l'ingresso e ridimensioni di size_mult. Una chiamata, singola risposta JSON a bassa latenza, nessuna infrastruttura aggiuntiva.
È non un generatore di segnali autonomo, un prodotto di charting o una piattaforma di esecuzione. Se non hai un tuo segnale da filtrare, inizia con la pagina delle performance per vedere come si è comportato il punteggio prima di integrarlo in un bot live.
Ottenere l'accesso
1 — Registrati. Crea un account gratuito su signup (email/password o Google). Nessuna carta di credito richiesta per il piano gratuito.
2 — Apri la tua dashboard. La tua dashboard mostra la tua chiave API, il piano attuale e l'utilizzo in tempo reale rispetto alla tua quota giornaliera.
3 — Copia la tua chiave API. Le chiavi hanno il prefisso sm_. Inseriscila come X-API-Key header in ogni richiesta (vedi Autenticazione). Aggiorna in qualsiasi momento sul pagina dei prezzi per aumentare i limiti e sbloccare più simboli ed endpoint.
Specifiche, SDK e Ricettario
Tutto ciò che ti serve per integrare rapidamente, sia che scriva il codice da solo o lo affidi a un agente di programmazione.
| Risorsa | Cos'è |
|---|---|
| Ricettario | Ricette copia-incolla per le integrazioni più comuni — conferma prima dell'ingresso, filtra un segnale Freqtrade, dimensiona per moltiplicatore, gestisci 402/429 e collegalo a un agente di programmazione. |
| Specifica OpenAPI | Definizione OpenAPI leggibile da macchina di ogni endpoint. Importa in Postman/Insomnia, genera client o alimenta un LLM. A github.com/tashiardit/smartmoneyapi-docs. |
| Client Python | Libreria client Python ufficiale su github.com/tashiardit/smartmoneyapi-python. |
| /llms.txt | Un riassunto in testo semplice dell'API adatto agli LLM. Puntaci Claude, Codex o Cursor (vedi Agenti di Programmazione). |
Guida rapida in 2 minuti
Passo 1 — URL di base. Ogni endpoint si trova sotto:
Passo 2 — Ottieni la tua chiave API. Registrati gratuitamente (nessuna carta di credito richiesta) e copia la tua chiave dal pannello di controllo. Inviarla come X-API-Key intestazione in ogni richiesta.
Passo 3 — La tua prima chiamata. Incolla questo nel tuo terminale e sostituisci sm_your_key con la chiave dal tuo pannello di controllo:
Risposta attesa:
"ts": 1710940821,
"symbol": "BTC",
"direction": "long",
"composite": 0.74,
"confidence": "HIGH",
"action": "CONFIRM",
"size_mult": 1.5,
"deriv_score": 0.81,
"onchain_score": 0.68,
"whale_score": 0.73,
"reasons": ["Tasso di funding positivo su tutte le piattaforme", "Balene: 67% consenso long"]
}
Quando confidence è HIGH o MEDIUM e action è CONFIRM, scala la dimensione della tua posizione per size_mult. Questo è l'intero ciclo di integrazione. Vedi Campi della Risposta per il riferimento completo ai campi.
Autenticazione
Tutte le richieste richiedono una chiave API inviata come X-API-Key intestazione HTTP.
La tua chiave API è disponibile nel pannello di controllo dopo la registrazione. Mantieni la tua chiave segreta — non esporla in codice client o repository pubblici.
/v1/ws/ticket con l' X-API-Key intestazione, quindi connettiti con il biglietto restituito. Vedi Autenticazione WebSocket (biglietti).Accesso con Google (Firebase Auth)
Gli utenti possono autenticarsi utilizzando il loro account Google tramite Firebase Authentication. Dopo un accesso Google riuscito sul client, scambia il token ID Firebase con una sessione API collegata. Il sistema sincronizza automaticamente la tua identità Google con il sistema di chiavi API.
Corpo della Richiesta
| Campo | Tipo | Descrizione |
|---|---|---|
| id_tokenobbligatorio | string | Token ID Firebase ottenuto dopo l'accesso Google sul client |
Esempio di Risposta
"api_key": "sm_your_linked_key",
"uid": "firebase_uid_abc123",
"email": "[email protected]",
"plan": "trader",
"synced": true
}
Limiti di Frequenza
| Piano | Chiamate/Giorno | Limite a Scoppio | Ritardo Dati |
|---|---|---|---|
| Free | 50 | 2/min | 60 secondi |
| Trader | 1,000 | 20/min | Tempo reale |
| Pro | 5,000 | 60/min | In tempo reale |
| Enterprise | 100,000 | 400/min | In tempo reale |
Gli header dei limiti di frequenza sono inclusi in ogni risposta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
URL base
Tutti gli endpoint seguenti sono relativi a questo URL base. Tutte le risposte sono in JSON con Content-Type: application/json.
Errori
Gli errori utilizzano codici di stato HTTP standard e un corpo JSON coerente. Valuta sempre in base al codice di stato, non al testo della risposta. I tre più comuni che incontrerai:
| Stato | Codice | Significato e cosa fare |
|---|---|---|
| 401 | non autorizzato | Chiave API mancante o non valida. Verifica che l'header X-API-Key sia presente e corretto. |
| 402 | pagamento_richiesto | L'endpoint o il simbolo richiede un piano superiore a quello associato alla tua chiave (es. una chiave gratuita che chiama il flusso WebSocket). Aggiorna o torna a un endpoint pubblico. |
| 429 | limite_frequenza_superato | Limite giornaliero o a raffica raggiunto. Riduci la frequenza e riprova dopo X-RateLimit-Reset; non insistere. |
Ogni errore restituisce la stessa struttura:
"error": "rate_limit_exceeded",
"message": "Limite giornaliero di 50 chiamate raggiunto. Si resetta alle 00:00 UTC.",
"status": 429
}
Per la lista completa dei codici di stato (400 / 403 / 500 / 503 e altri), vedi Codici di errore. Un'integrazione robusta tratta i 5xx e 429 come transitori (riprova con backoff) e 401/402/403 come terminali (correggi la chiave o il piano).
Migliori pratiche di sicurezza
Invia la chiave nell'header, mai nell'URL. Passa sempre X-API-Key come header HTTP. Le chiavi nelle query string (?key=) vengono registrate da proxy, bilanciatori di carico e cronologia del browser — il vecchio metodo ?key= auth non è più accettato sugli endpoint WebSocket per questo motivo.
Mantieni le chiavi lato server. Non incorporare mai una chiave API in JavaScript lato client, in un bundle di app mobile o in un repository pubblico. Caricala da una variabile d'ambiente o da un gestore di segreti. Se una chiave viene compromessa, ruotala.
Ruota periodicamente le chiavi. Rigenera la tua chiave dal dashboard secondo una pianificazione e immediatamente se sospetti che sia stata esposta. La vecchia chiave smette di funzionare al momento della generazione di una nuova.
Usa ticket per i socket browser. Per flussi in tempo reale dal browser, scambia la tua chiave con un ticket monouso invece di connetterti con la chiave raw — vedi Autenticazione WebSocket (ticket).
Utilizzo con agenti di codifica / LLM
Stai sviluppando con Claude Code, Codex, Cursor o qualsiasi agente di codifica LLM? Puoi fornire all'agente tutto ciò di cui ha bisogno per integrare correttamente questa API in un colpo solo. Sono disponibili due riferimenti machine-readable:
| Risorsa | URL |
|---|---|
| Riepilogo per LLM | https://smartmoneyapi.com/llms.txt |
| Specifica OpenAPI | github.com/tashiardit/smartmoneyapi-docs |
Indirizza il tuo agente al file /llms.txt (convenzione llms.txt) per una panoramica concisa, poi alla specifica OpenAPI per le strutture esatte di richiesta/risposta. Un prompt one-line che funziona bene:
Leggi https://smartmoneyapi.com/llms.txt e la specifica OpenAPI su
github.com/tashiardit/smartmoneyapi-docs, poi aggiungi un controllo pre-trade
al mio bot che chiama GET /v1/confirm e salta gli ingressi
a meno che l'azione non sia CONFIRM.
Vedi il Cookbook per una ricetta completa per agenti di codifica.
Endpoint
GET /confirm
L'endpoint principale. Restituisce un punteggio di confidenza composito e una raccomandazione di azione per una direzione di trade specifica. Chiamalo prima di aprire qualsiasi posizione.
Copertura, in termini semplici. /confirm attualmente valuta BTC, ETH e SOL — i simboli con una storia sufficiente per confermare onestamente. Lo screener derivati separatamente monitora ~519 mercati derivati per funding, OI e dati di liquidazione, e il tracciamento delle balene copre 600+ wallet. Pro sblocca lo screener completo, export e una copertura di mercato più ampia; /confirm il supporto ai simboli viene ampliato man mano che ogni mercato accumula un track record affidabile.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolobbligatorio | string | Simbolo dell'asset. Uno di: BTC, ETH, SOL (Trader+) |
| directionobbligatorio | string | Direzione del trade: long o short |
| sourceopzionale | string | Etichetta per la fonte del tuo segnale (registrata per analisi). Max 32 caratteri. |
Esempio di richiesta
"https://api.smartmoneyapi.com/v1/confirm?symbol=BTC&direction=long"
Esempio di risposta
"ts": 1710940821,
"symbol": "BTC",
"direction": "long",
"composite": 0.74,
"confidence": "HIGH",
"action": "CONFIRM_FULL",
"size_mult": 1.5,
deriv_score: 0.81,
onchain_score: 0.68,
whale_score: 0.73,
x_score: 0.0,
fattori: {
derivati: { punteggio: 0.81, peso: 0.40, ponderato: 0.324 },
onchain: { punteggio: 0.68, peso: 0.35, ponderato: 0.238, fonte: coinmetrics, disponibile: True },
whale: { punteggio: 0.73, peso: 0.25, fattore_di_obsolescenza: 1.0, ponderato: 0.183 }
},
rettifiche: { accordo: 0.0, tendenza: 0.0, news_macro: 0.0 },
pesi: { derivati: 0.40, onchain: 0.35, whale_intel: 0.25 },
copertura: { derivati: True, balena: True, onchain: True },
motivi: [
Tasso di funding positivo su tutte le piattaforme,
LSR favorevole ai long: 1.42,
Balene: 67% consenso long,
MVRV sopra 1.0 — bullish on-chain
]
}
Trasparente per design. Ogni risposta include un factors oggetto che mostra il punteggio × peso = contributo ponderato, un adjustments oggetto per modifiche post-filtro, il weights utilizzato, e una coverage mappa. La componente on-chain utilizza dati reali gratuiti di Coin Metrics (MVRV / flussi exchange / indirizzi attivi) quando non è impostata una chiave Glassnode. Questo è un punteggio di confluenza multifattoriale — supporto decisionale, non una garanzia di vincita.
I simboli non tracciati sono segnalati onestamente. Un simbolo esterno all'universo tracciato di derivati/balene restituisce un esplicito "confidence":"NO_DATA" / "action":"NO_DATA_SKIP" con "unsupported":true — mai un LOW.
Campi della Risposta
| Campo | Tipo | Descrizione |
|---|---|---|
| ts | integer | Timestamp Unix del calcolo |
| symbol | string | Simbolo dell'asset (BTC/ETH/SOL) |
| direction | string | Direzione richiesta (long/short) |
| composite | float | Punteggio composito di confluenza da -1.0 (contro estremo) a +1.0 (forte conferma). Non è una percentuale di vincita. |
| base_composite | float | Punteggio composito prima dell'applicazione degli aggiustamenti post-filtro |
| confidence | string | HIGH / MEDIUM / LOW / VETO / NO_DATA |
| action | string | CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP |
| size_mult | float | Moltiplicatore suggerito per la dimensione della posizione (es. 0.0 – 1.5) |
| unsupported | bool | true quando il simbolo non è coperto (abbinato a NO_DATA) |
| deriv_score | float | Sotto-punteggio derivati (-1 a 1) |
| onchain_score | float | Sotto-punteggio on-chain (-1 a 1) |
| whale_score | float | Sotto-punteggio consenso delle balene (-1 a 1) |
| x_score | float | Sotto-punteggio X/sentiment social (-1 a 1); 0 quando non utilizzato |
| factors | object | Dettaglio per componente: score × weight = weighted per derivati / onchain / whale / x_sentiment (onchain include source) |
| adjustments | object | Aggiustamenti post-filtro con segno (accordo, trend, rsi_1h, news_macro, momentum, time_of_day, streak_decay) |
| weights | object | Set di pesi effettivamente utilizzato per questa valutazione |
| coverage | object | {derivatives, whale, onchain} — quali componenti avevano dati reali |
| reasons | array | Spiegazioni leggibili per il punteggio |
GET /snapshot
Restituisce un'istantanea completa del mercato, inclusi tutti i sotto-punteggi, le metriche grezze e i valori degli indicatori per un determinato simbolo. Utile per dashboard e registrazione.
GET /onchain
Restituisce metriche on-chain grezze: MVRV, SOPR, flusso netto degli exchange, rapporto di realized cap e classificazione della posizione nel ciclo.
GET /v1/derivatives/*
Screener derivati cross-exchange su 500+ simboli: mappa termica dei funding rate, classifiche dell'open interest e rilevamento di segnali long/short ratio. Le prime 10 righe sono pubbliche; lo screener completo richiede Trader o Pro. Endpoint: /v1/derivatives/screener, /v1/derivatives/funding, /v1/derivatives/oi, /v1/derivatives/signals.
GET /v1/options/*
Analitiche delle opzioni BTC & ETH provenienti da Deribit (pubbliche, senza autenticazione): put/call ratio, max pain e open interest per strike. Endpoint: /v1/options/summary, /v1/options/pcr, /v1/options/oi.
GET /v1/etf/*
Flussi netti giornalieri degli ETF spot BTC & ETH e dettaglio per fondo (pubblico). Endpoint: /v1/etf/flows, /v1/etf/funds.
GET /v1/historical/*
Dati storici di funding, open interest, long/short ratio (Binance) e OHLCV (CoinGecko) per backtesting. Endpoint: /v1/historical/funding, /v1/historical/oi, /v1/historical/lsr, /v1/historical/ohlcv.
GET /v1/dex/*
Coppie in trend, ricerca di token e dettagli delle coppie con DexScreener (pubblico, senza autenticazione). Endpoint: /v1/dex/trending, /v1/dex/search, /v1/dex/token, /v1/dex/pair.
GET /v1/news/*
Intelligence sulle notizie: notizie su politiche/geopolitica/crypto classificate per impatto, più Fear & Greed (pubblico, senza autenticazione). Endpoint: /v1/news/trump, /v1/news/general, /v1/news/impact, /v1/news/fear-greed.
GET /whales
Restituisce dati di consenso sui portafogli whale: suddivisione long/short, esposizione notazionale totale, top 10 posizioni (solo Pro) e conteggio portafogli.
GET /signals
Restituisce un flusso dei segnali HIGH/MEDIUM più recenti su tutti gli asset monitorati. Utile per la scansione delle opportunità.
GET /v1/strategies/*
Cronistoria trasparente e in sola lettura per le strategie di trading automatizzate che eseguono in base ai segnali Smart Money — incluso il deriv40 SmartMoney Copytrade strategy (account=9). Tutti gli endpoint accettano un ?account=<id> parametro di query e restituiscono JSON. Nessuna autenticazione richiesta (cronistoria pubblica).
Endpoint
GET /v1/strategies/stats?account=9— metriche principali:total_trades,win_rate,profit_factor,total_pnl_usdt,account_growth_percent,initial_equity,current_equity,max_drawdown_portfolio,max_drawdown_trade.GET /v1/strategies/equity?account=9— curva del capitale per grafici:{ initial_equity, curve: [{ time, equity }] }.GET /v1/strategies/trades?account=9&limit=500— registro dei trade chiusi: array (o{trades:[…]}) disymbol,direction,entry_price,exit_price,pnl_usdt,pnl_percent,pnl_percent_net.GET /v1/strategies/active?account=9— posizioni attualmente aperte: array (o{positions:[…]}) disymbol,side/direction,entry_price,unrealized_pnl.GET /v1/strategies/signals— suddivisione per tipo di segnale che alimenta le strategie (conteggio / vittorie / tasso di vittoria / pnl medio per tipo di segnale).
Le performance passate non sono indicative dei risultati futuri. I dati sono backfillati su un singolo regime di ~3 mesi più trade live e sono mostrati pre-fee dove indicato.
GET /export
Scarica i dati storici dei segnali in CSV per backtesting. Parametri: symbol, from (unix ts), to (unix ts).
GET /health
Controllo dello stato del sistema. Restituisce la freschezza dei dati per ogni sorgente e lo stato generale dell'API. Nessuna autenticazione richiesta.
"status": "ok",
"uptime_s": 1209600,
"sources": {
"bybit": { "lag_s": 42, "ok": true },
"binance": { "lag_s": 38, "ok": true },
"hyperliquid": { "lag_s": 61, "ok": true },
"onchain": { "lag_s": 290, "ok": true }
}
}
GET /usage
Restituisce le statistiche correnti di utilizzo dell'API: chiamate oggi, totali mensili, limiti di quota e tempi di reset.
POST /webhooks
Registra un URL HTTPS per ricevere notifiche in tempo reale firmate quando un segnale viene attivato sugli asset monitorati. Le consegne includono un X-SmartMoney-Event header e una firma HMAC-SHA256 in X-SmartMoney-Signature, con fino a 3 tentativi di ritrasmissione con backoff.
Corpo della richiesta
| Campo | Tipo | Descrizione |
|---|---|---|
| urlrequired | string | Endpoint HTTPS a cui inviare gli eventi (deve iniziare con https://) |
| eventsrequired | array | Nomi degli eventi, es. ["HIGH","MEDIUM","VETO"] o ["*"] |
| symbolsrequired | array | Simboli da filtrare, es. ["BTC","ETH"] o ["*"] |
| secretrequired | string | Il tuo segreto per la firma, ≥ 16 caratteri (memorizzato in hash) |
Verifica della firma
La chiave HMAC è l'hex digest SHA-256 del tuo segreto registrato. Calcola l'HMAC-SHA256 del corpo della richiesta grezzo con quella chiave e confronta (in tempo costante) con X-SmartMoney-Signature. Vedi il Guida all'implementazione dei Webhook.
Intelligenza
GET /analysis
Restituisce una classificazione dei regimi di mercato basata sull'IA con rilevamento di conflitti tra segnali. Analizza l'accordo tra segnali incrociati, identifica divergenze tra dati derivati, on-chain e dati delle balene, e produce un riassunto in linguaggio naturale con fattori di rischio prospettici e una raccomandazione con orizzonte temporale.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolobbligatorio | string | Simbolo dell'asset: BTC, ETH, o SOL |
Risposta di esempio
"ts": 1710940821,
"symbol": "BTC",
"regime": "late_cycle_divergence",
"regime_label": "Late Cycle — Signal Divergence",
"summary": "BTC è in una fase avanzata di ciclo rialzista con forza on-chain in conflitto con l'eccesso di derivati. Le balene stanno riducendo l'esposizione mentre il LSR retail aumenta.",
"signal_conflicts": [
"Punteggio balene ribassista mentre punteggio onchain rialzista",
"Tasso di funding al massimo da 3 mesi — rischio potenziale di squeeze"
],
"risk_factors": ["Funding elevato", "Divergenza OI", "Riduzione balene"],
"recommendation": "Riduci l'esposizione long, stringi gli stop. Evita nuovi long sopra il prezzo corrente.",
"time_horizon": "4h–12h"
}
GET /liquidations
Restituisce due visualizzazioni complementari: (1) proiezione della leva levels — una stima di dove si trovano i cluster di liquidazione; e (2) un realized_heatmap — l' REAL eseguito intensità di liquidazione forzata (prezzo × tempo), aggregata in tempo reale dai feed WebSocket pubblici degli exchange: Binance, OKX, Bybit, Bitget, BitMEX. La heatmap è presente quando lo stream ha dati per il simbolo (assente in un mercato molto calmo o subito dopo l'avvio).
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | Simbolo dell'asset (predefinito BTC). La heatmap reale copre i simboli perp scambiati attivamente. |
Risposta di esempio
"symbol": "BTC",
"cascade_risk": "ALTO",
"nearest_long_liq_pct": -3.2,
"nearest_short_liq_pct": 4.1,
// Liquidazioni REAL eseguite — in tempo reale da 5 exchange
"realized_heatmap": {
"window_minutes": 240, "price_min": 91000.0, "price_max": 99000.0,
"clusters": [ { "price": 93250.0, "notional": 4820000.0, "count": 37, "dominant_side": "long" } ],
"by_side": { "long": 6100000.0, "short": 2400000.0 },
"totals": { "total_notional": 8500000.0, "count": 214 },
"exchanges": { "binance": 120, "okx": 40, "bybit": 34, "bitget": 12, "bitmex": 8 }
}
}
cascade_risk, distanze più vicine e totali/ per lato realizzati. Piano Pro: proiezione completa levels più la completa realized_heatmap (matrici, cluster per prezzo, conteggi per exchange). La stima proiettata risponde a "dove sono gli stop"; la heatmap realizzata mostra "cosa è stato effettivamente liquidato."GET /liquidations/heatmap
Public heatmap di liquidazione per livello di prezzo. Restituisce una matrice prezzo × tempo in stile Coinglass di REAL eseguite liquidazioni forzate, raggruppate per il prezzo a cui ogni liquidazione è stata registrata — aggregate in tempo reale dai feed WebSocket pubblici degli exchange: Binance, OKX, Bybit, Bitget, BitMEX. Il clusters array è l'output pratico: bucket di prezzo classificati per notional liquidato, ciascuno con il lato dominante. I dati dipendono dallo stream live — un simbolo molto tranquillo o un gateway appena riavviato restituisce la struttura vuota ben formata più un onesto note. I livelli mostrati sono solo liquidazioni reali, mai stimate.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | Simbolo dell'asset (predefinito BTC). |
| window_minutesopzionale | int | Finestra temporale di look-back in minuti (predefinito 240, limitata a 5–1440). |
| price_bucketsopzionale | int | Numero di bucket di prezzo (predefinito 50, limitato a 5–100). |
Risposta di esempio
"symbol": "BTC", "window_minutes": 240, "price_buckets": 50,
"price_min": 91000.0, "price_max": 99000.0, "price_bucket_size": 160.0,
"price_levels": [ 91080.0, 91240.0, … ], "time_buckets": [ … ],
"matrix": [ [ … ] ], "long_matrix": [ [ … ] ], "short_matrix": [ [ … ] ],
"clusters": [
{ "price": 93250.0, "notional": 4820000.0, "long_notional": 4100000.0,
"short_notional": 720000.0, "count": 37, "dominant_side": "long" }
],
"by_side": { "long": 6100000.0, "short": 2400000.0 },
"totals": { "long_liq_notional": 6100000.0, "short_liq_notional": 2400000.0, "total_notional": 8500000.0, "count": 214 },
"exchanges": { "binance": 120, "okx": 40, "bybit": 34, "bitget": 12, "bitmex": 8 },
"generated_at": 1710940200, "public": true
}
totals.count è 0, clusters è vuoto, e un note campo spiega il motivo. È un registro delle liquidazioni eseguite — non una previsione. Per la stima proiettata "dove si trovano gli stop", utilizza l'endpoint autenticato /liquidations endpoint.GET /liquidations/onchain
Eseguiti liquidazioni on-chain DeFi catturate direttamente dai nostri nodi completi BSC + Avalanche — indipendenti da qualsiasi bot di trading. Copre Venus/Cream e Moolah su BSC, e AAVE V3/V2, Benqi, BankerJoe, Granary e Vinium su Avalanche. Il livello Pro restituisce inoltre at_risk posizioni (dipendenti dal bot, potrebbero essere assenti).
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| chainopzionale | string | bsc o avax. Ometti per tutte le chain. |
| limitopzionale | integer | Numero massimo di righe (predefinito 100, massimo 500). Ordine dal più recente. |
Risposta di esempio
"chain": "bsc", "count": 2,
"liquidations": [
{ "chain": "bsc", "protocol": "Venus", "borrower": "0x2be6…8dfa",
"debt_symbol": "DAI", "repay_usd": 426.15,
"collateral_symbol": "WBNB", "tx_hash": "0x718c…7c0e", "block": 89170816, "ts": 1710940200 }
],
"summary": {
"window_hours": 24, "enabled": true,
"by_protocol": { "bsc:Venus": { "count": 61, ripagare_usd_noto: 148230.55 } },
nodi: { bsc: { raggiungibile: True, blocco_testa: 89173010, eventi_totali: 61 } }
}
}
GET /smart-stop
Calcola livelli intelligenti di stop-loss basati sull'attuale mappa del calore delle liquidazioni, bande di volatilità e struttura del mercato. Restituisce raccomandazioni di stop a livelli e suggerimenti di take-profit calibrati sul prezzo di ingresso e sulla tolleranza al rischio.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| simbolorichiesto | stringa | Simbolo dell'asset: BTC, ETH, o SOL |
| direzionerichiesto | stringa | Direzione della posizione: long o short |
| prezzo_ingressoopzionale | float | Il tuo prezzo di ingresso. Predefinito al prezzo di mercato corrente se omesso. |
| rischio_pctopzionale | float | Rischio massimo accettabile come % del conto. Predefinito: 2.0 |
Esempio di Risposta
simbolo: BTC,
direzione: long,
prezzo_ingresso: 96420,
stop: {
stretto: { prezzo: 95100, nota: Sotto la struttura di 1h. Ideale per scalping. },
raccomandato: { prezzo: 93800, nota: Sotto il principale cluster di liquidazione a $94K. Stop standard per swing. },
ampio: { prezzo: 91200, nota: Sotto la zona di domanda di 4h. Stop per posizioni di trading. }
},
evita_zone: [
{ basso: 94200, alto: 94800, motivo: Cluster di liquidazione denso — alto rischio di slippage }
],
suggerimenti_take_profit: [
{ tp1: 98500, tp2: 101000, tp3: 104200 }
]
}
recommended stop. Piano Pro: Tutti e tre i livelli di stop, avoid_zones, e suggerimenti completi di take-profit.GET /funding-arb
Identifica opportunità di arbitraggio sui tassi di finanziamento tra exchange in tempo reale. Restituisce opportunità classificate con rendimento annualizzato stimato, coppia di exchange ottimale e l'azione di copertura necessaria per catturare lo spread.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| spread_minimoopzionale | float | Spread minimo del tasso di finanziamento da includere (come decimale). Predefinito: 0.01 |
| simboloopzionale | stringa | Filtra per un asset specifico. Ometti per scansionare tutti gli asset supportati. |
Esempio di Risposta
ts: 1710940821,
opportunità: [
{
simbolo: BTC,
spread: 0.032,
apr: 84.2,
exchange_long: hyperliquid,
exchange_short: bybit,
azione: Long HYPE / Short BYBIT,
profitto_stimato_8h_usd: 26.4
}
]
}
Variante pubblica gratuita Nessuna autenticazione
Un endpoint pubblico senza chiave restituisce le prime 10 opportunità con uno screener cross-exchange in tempo reale, ideale per l'embedding o controlli rapidi. Rimuove lo storico dello spread per simbolo e campi pesanti ed è servito da una cache di 120 secondi. Quando non ci sono spread di finanziamento cross-exchange nella finestra di freschezza, restituisce un opportunities array vuoto con un note — mai dati fabbricati.
opportunità: [
{
simbolo: OGN,
spread_pct: 0.297667,
apr_annualizzato: 325.95,
exchange_long: bybit,
exchange_short: hyperliquid,
profitto_stimato_per_10k: 29.77,
note_sul_rischio: Spread basso — assicurati che le commissioni non consumino il margine di arbitraggio.
}
],
simboli_scansionati: 222,
ts: 1783268753,
pubblico: True,
limitato: True
}
GET /smart-money/flow
Un indice ponderato per qualità indice direzionale delle balene per simbolo, valutato -100 (denaro delle balene orientato allo short) a +100 (orientato al long). Costruito da migliaia di portafogli di balene Hyperliquid tracciati — ciascuno ponderato in base al proprio storico di vincite e PnL e attenuato dalla recentezza. Questo è un indice di posizionamento, non un segnale di acquisto/vendita o una previsione di prezzo. I simboli con pochi portafogli contribuenti sono etichettati thin e valutati onestamente. Pagina live: smart-money-flow.html.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| simboloopzionale | stringa | Singolo simbolo (es. BTC). Ometti per ottenere tutti i simboli tracciati classificati per |score|. |
| window_hoursopzionale | int | Finestra di punteggio, limitata a 1..168. Predefinito 24. |
Esempio di Risposta
simboli: [
{
simbolo: SPX,
punteggio: -90.93,
direzione: forte_short,
n_portafogli: 26,
long_usd: 184200.0, short_usd: 2410000.0,
ponderato_per_qualità: True,
qualità_campionaria: ricco,
principali_contributori: [ { portafoglio: 0x31ca…974b, direzione: short, valore_usd: 5338.25, peso: 0.4948 } ]
}
],
window_hours: 24,
ponderato_per_qualità: True,
ts: 1783270000,
nota: Indice di posizionamento direzionale delle balene ponderato per qualità (-100..+100). Non è una previsione di prezzo o un segnale di acquisto/vendita.
}
top_contributors. I pesi dei portafogli sono limitati a [0.25,1.0]; il PnL è un proxy non realizzato dagli ultimi snapshot di posizione.GET /v1/whales/crowding
Combinato contesto di posizionamento e affollamento delle balene per simbolo, unito tra Hyperliquid + GMX v2 + Jupiter Perps. Restituisce il notionale lordo/netto, lo skew direzionale, i conteggi dei portafogli e delle sedi, la concentrazione delle posizioni (quota top-3 + HHI), una leva media ponderata e bucket di prossimità alla liquidazione (notionale $ entro il 5% e il 10% del prezzo di liquidazione stimato, diviso long/short). Questo è contesto, non un segnale direzionale. I campi che non sono derivabili sono null e vengono visualizzati come — — es. lev_wavg/crowding_index quando nessuna posizione ha leva. Le distanze di liquidazione sono una stima del margine isolato (pct_to_liq ≈ 1/lev + upnl/notional − mmr, mmr = 0.01), non prezzi di liquidazione riportati dall'exchange.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| min_notionalopzionale | float | Notionale lordo combinato minimo (USD) per includere un simbolo. Predefinito: 1000000. |
Esempio di Richiesta
Esempio di Risposta
"ok": True, "ts": 1783423500, min_notional: 1000000, n_symbols: 92,
symbols: [
{
symbol: BTC,
gross_usd: 2447900000.0, net_usd: -51000000.0, skew: -0.021,
n_whales: 414, n_venues: 3,
venues: {
hl: { gross: 1900000000.0, net: -40000000.0, n_whales: 272 },
gmx: { gross: 320000000.0, net: -6000000.0, n_whales: 59 },
jupiter: { gross: 227900000.0, net: -5000000.0, n_whales: 83 }
},
conc_top3: 0.159, hhi: 0.011, lev_wavg: 19.1,
liq_within_5pct: { long: 621700000.0, short: 665600000.0 },
liq_within_10pct: { long: 840000000.0, short: 910000000.0 },
crowding_index: 0.003
}
],
caveats: [ Le distanze di liquidazione sono stime a margine isolato, non riportate dagli exchange. ]
}
skew è net/gross ∈ [-1,1]; crowding_index = |skew|·conc_top3·min(lev/20,1). Solo i venue effettivamente presenti appaiono in venues. Le posizioni senza leva sono escluse dai bucket di liquidazione piuttosto che essere presupposte. I chiamanti anonimi ricevono i top 10 simboli per gross (con gated: true); Trader+ riceve la lista completa.GET /v1/options/gex
Dealer gamma exposure (GEX) analisi per BTC & ETH, calcolate in tempo reale dalla catena di opzioni pubblica di Deribit (no auth). Restituisce il GEX netto del dealer per strike (convenzione dealer-short SpotGamma), il livello di gamma-flip (strike dove il GEX netto cumulativo attraversa lo zero), la struttura a termine dell'IV (volatilità implicita ATM per giorni alla scadenza), e uno skew dell'IV a scadenza frontale (risk reversal proxy 25Δ). Il regime GEX è positive (dealer long gamma → soppressione della volatilità) o negative (amplificazione della volatilità). Completamente autonomo — ricalcolato ad ogni chiamata, nessuna dipendenza da DB memorizzato.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | BTC o ETH solo. Default: BTC. |
Esempio di richiesta
Esempio di risposta
"symbol": "BTC", "available": true, "spot": 63203.0,
"net_gex": 18240000.0, "regime": "positive",
"gamma_flip": 64919.82, "gamma_flip_pct": 2.72,
"call_gex": 31200000.0, "put_gex": -12960000.0,
"by_strike": [
{ "strike": 60000, "net_gex": -2100000.0 },
{ "strike": 65000, "net_gex": 4800000.0 }
],
"term_structure": [
{ "expiry": "8JUL26", "dte": 0.76, "atm_iv": 62.1 },
{ "expiry": "27MAR26", "dte": 14.2, "atm_iv": 58.4 }
],
"skew": {
"expiry": "8JUL26", "dte": 0.76,
"put_iv": 69.69, "atm_iv": 62.1, "call_iv": 55.34,
"risk_reversal": 14.35, "bias": "downside_fear"
}
}
available: false con pannelli vuoti — mai GEX fabbricati. Lo skew IV utilizza un proxy di strike fisso ±10% per 25Δ (il vero 25-delta richiede il calcolo del delta per strike); adeguato per la visualizzazione, documentato come approssimazione.GET /v1/liquidations/simulate
Interactive stress-test di liquidazione a cascataDato un movimento ipotetico del prezzo, restituisce le posizioni con leva stimate che verrebbero liquidate, il volume forzato per livello di prezzo/lato/exchange e una lettura della profondità della cascata. Un movimento al ribasso liquida long il cui prezzo di liquidazione si trova al di sopra o al livello del target; un movimento al rialzo liquida short il cui prezzo di liquidazione si trova al di sotto o al livello del target. Due metodi indipendenti vengono combinati: prezzi di liquidazione esatti dalle posizioni delle balene Hyperliquid tracciate con leva reale /prezzo di ingresso, più cluster statistici di bande di OI per exchange (leva della folla dedotta dal funding). Tutto è chiaramente etichettato estimated: true — non può conoscere il margine per account, cross vs isolated, margine aggiuntivo o ADL.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | Simbolo dell'asset. Default: BTC. |
| move_pctopzionale | float | Movimento ipotetico del prezzo in percentuale (negativo = giù, positivo = su). Default: -5. |
Esempio di richiesta
Esempio di risposta
"ok": true, "estimated": true, "symbol": "BTC",
"ref_price": 63000.0, "move_pct": -5.0, "target_price": 59850.0,
"triggered_notional_usd": 380000000.0,
"cascade_depth": 0.029, "cascade_bucket": "low",
"by_exchange": { "hyperliquid": 260000000.0, "binance": 80000000.0, "bybit": 40000000.0 },
"by_side": { "long": 380000000.0, "short": 0.0 },
"clusters": [
{ "price": 60100.0, "side": "long", "notional_usd": 42000000.0, "whale_usd": 18000000.0, "oi_usd": 24000000.0 }
],
"whale_positions_used": 272, "exchanges": 3,
"realized_context": { "available": true, "coverage_hours": 17.8, "by_side_24h": { "long": 6100000.0, "short": 2400000.0 } },
"methodology": { "disclaimer": "Stimato — non può conoscere il margine per account, cross vs isolated, margine aggiuntivo o ADL." }
}
ok: true, empty: true un messaggio in inglese semplice, non barre false. realized_context è un campione giovane e in crescita dal flusso live di liquidazioni forzate, mostrato solo come contesto — non rende mai la proiezione "realizzata".GET /v1/wallet/{addr}/profile
Un profilo wallet cross-venue costruito interamente dagli snapshot live delle posizioni delle balene tracciate. Per una balena Hyperliquid tracciata, restituisce le posizioni aperte correnti, una serie temporale di PnL non realizzato / esposizione / conteggio posizioni time series, una timeline di attività OPEN/CLOSE/FLIP (ricostruita differenziando snapshot consecutivi), l'etichetta decodificata della leaderboard HL e un riepilogo open-book. Pagina live: wallet-profiler.html.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| addrobbligatorio | string | Indirizzo del wallet (segmento del percorso), es. /v1/wallet/0x3bcae23e…/profile. |
| daysopzionale | integer | Finestra di look-back per la serie e la timeline. Default: 30. |
Esempio di richiesta
Esempio di risposta
"ok": true, "wallet": "0x3bcae23e…", "tracked": true,
"first_seen_ts": 1782827733, "latest_snapshot_ts": 1783418468, "as_of": 1783418468,
"hyperliquid": {
"label": { "name": "Andre is back", "score": 74,
"window_pnl_usd": 1307000, percentuale_vittorie: 71, operazioni: 42 },
posizioni: [
{ piattaforma: hyperliquid, simbolo: ETH, direzione: short,
dimensione: 1200.0, prezzo_ingresso: 1800.0, pnl_non_realizzato: 34800.0,
leva: 20.0, valore_usd: 2160000.0 }
],
serie: [ { ts: 1783330000, pnl_non_realizzato: 42000.0, esposizione_usd: 18400000.0, posizioni: 5 } ],
cronologia: [ { ts: 1783400000, evento: inversione, simbolo: ETH,
direzione: short, da_direzione: long, valore_usd: 2160000.0 } ],
riepilogo: {
posizioni_aperte: 5, in_profitto: 3, in_perdita: 2, long: 0, short: 5,
pnl_non_realizzato_totale: -12000.0, esposizione_totale_usd: 21000000.0, leva_media: 19.9,
giorni_finestra: 30, istantanee_nella_finestra: 474,
pnl_realizzato: None, nota_pnl_realizzato: Non derivabile — vengono visualizzate solo le istantanee aperte, mai le chiusure.
}
}
}
pnl è il mark-to-market non realizzato di HL stesso, value_usd è notazionale aperto. Il P&L realizzato per round-trip non è disponibile (vediamo solo istantanee aperte, mai chiusure) ed è mostrato come null / —; gli eventi di chiusura nella cronologia non contengono dati sul P&L. Un indirizzo valido ma non tracciato restituisce tracked: false con una nota; un indirizzo non valido restituisce ok: false, error: "invalid_address" (HTTP 400). L'etichetta HL-leaderboard è la posizione di HL al momento della scoperta, non calcolata da noi.GET /flows
Restituisce dati sui flussi di capitale tra asset che mostrano schemi di rotazione tra BTC, ETH e SOL in diverse finestre temporali. Utile per identificare quale asset sta accumulando capitale e quale viene distribuito in un dato momento.
Esempio di risposta
ts: 1710940821,
flussi: {
BTC: { 1h: 142000000, 4h: 380000000, 12h: -90000000, 24h: 220000000 },
ETH: { 1h: -38000000, 4h: -110000000, 12h: 55000000, 24h: -80000000 },
SOL: { 1h: 12000000, 4h: 29000000, 12h: 18000000, 24h: 44000000 }
},
rotazioni_rilevate: [
Capitale in rotazione da ETH a BTC in una finestra di 4h,
Accumulo di SOL costante in tutte le finestre
]
}
GET /whale-events
Restituisce cambiamenti significativi nelle posizioni delle balene — aperture, chiusure e inversioni di direzione — rilevati tra i portafogli tracciati e gli indirizzi on-chain nella finestra temporale specificata.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| simboloopzionale | stringa | Filtra per asset. Ometti per tutti gli asset monitorati. |
| significativitàopzionale | stringa | Filtra per significatività dell'evento: high, medium, o all. Predefinito: all |
| oreopzionale | intero | Finestra temporale di look-back in ore. Predefinito: 24 |
Esempio di risposta
simbolo: BTC,
riepilogo: {
inversioni_a_long: 3,
inversioni_a_short: 1,
nuove_aperture: 7,
chiusure: 2
},
eventi: [
{
tipo: inverti_long,
portafoglio: 0xWhale...a4f2,
direzione: long,
size_usd: 4200000,
ts: 1710938400
}
]
}
summary oggetto solamente. Piano Pro: Feed events completo con identificatori di portafoglio, dimensioni e timestamp.GET /regimes/history
Restituisce i dati storici di classificazione dei regimi per un determinato asset. Utilizzalo per backtestare le performance storiche di specifici tipi di regime, la durata tipica di ogni regime e come si evolvono le transizioni tra regimi nel tempo.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | Simbolo dell'asset. Predefinito: BTC |
| regimeopzionale | string | Filtra per un tipo di regime specifico, es. late_cycle_divergence. Ometti per tutti i regimi. |
| daysopzionale | integer | Finestra temporale di look-back in giorni. Predefinito: 30. Massimo: 365 |
Risposta di esempio
symbol: BTC,
current_regime: late_cycle_divergence,
regime_summary: {
late_cycle_divergence: { occurrences: 4, avg_duration_h: 38, avg_return_pct: -2.1 },
accumulation: { occurrences: 6, avg_duration_h: 72, avg_return_pct: 5.4 },
breakout: { occurrences: 3, avg_duration_h: 18, avg_return_pct: 9.2 }
},
transitions: [
{ from: accumulation, to: breakout, ts: 1710850000 },
{ from: breakout, to: late_cycle_divergence, ts: 1710915000 }
]
}
/analysis per validare le ipotesi strategiche rispetto ai dati storici delle performance dei regimi.GET /exchange-health
Restituisce lo stato di salute in tempo reale per tutti gli exchange monitorati, inclusi latenza per exchange, tassi di errore e indicatori di obsolescenza dei dati. Nessuna autenticazione richiesta — endpoint accessibile pubblicamente.
Risposta di esempio
overall_status: ok,
ts: 1710940821,
exchanges: {
bybit: { status: ok, latency_ms: 42, error_rate_1h: 0.0, last_data_age_s: 18 },
binance: { status: ok, latency_ms: 38, error_rate_1h: 0.0, last_data_age_s: 22 },
hyperliquid: { status: degraded, latency_ms: 310, error_rate_1h: 0.04, last_data_age_s: 95 },
okx: { status: ok, latency_ms: 55, error_rate_1h: 0.0, last_data_age_s: 30 }
}
}
GET /sentiment
Restituisce un indice Fear & Greed (0-100) calcolato in tempo reale dal sentiment dei derivati, attività delle balene, volatilità e segnali sociali. Include una scomposizione dei componenti e una cronologia di 24 ore per l'analisi delle tendenze.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | Simbolo dell'asset. Predefinito: BTC |
Risposta di esempio
"symbol": "BTC",
"score": 72,
"label": "Greed",
"components": {
"volatility": 65,
"momentum": 78,
"derivatives": 70,
"whale_activity": 75,
"social": 68
},
"history_24h": [
{ "ts": 1710940800, "score": 68, "label": "Greed" },
{ "ts": 1710937200, "score": 65, "label": "Greed" }
],
"ts": 1710940821
}
Integrazioni
GET /tradingview/setup
Restituisce la configurazione personalizzata dell'integrazione con TradingView: URL del webhook, segreto per la validazione e indicatori Pine Script pronti all'uso che si collegano direttamente alla Smart Money API. Copia e incolla lo script Pine Script in TradingView per sovrapporre i nostri segnali su qualsiasi grafico.
Risposta di esempio
"webhook_url": "https://api.smartmoneyapi.com/v1/tradingview/webhook",
"webhook_secret": "tvs_a1b2c3...",
"pine_scripts": {
"composite_indicator": "// Smart Money Composite v1\n//@version=5\nindicator(...)...",
"whale_activity": "// Whale Activity Overlay v1\n...",
"funding_dashboard": "// Funding Rate + LSR Dashboard v1\n..."
}
}
POST /tradingview/webhook
Riceve un alert da TradingView, lo elabora tramite /confirm, e restituisce la conferma. TradingView non può inviare header personalizzati, quindi autenticati includendo il tuo webhook secret nel corpo JSON (questo endpoint non utilizza X-API-Key). La risposta include la conferma e aggiunge un livello superiore action di CONFIRMED (confidenza del demone HIGH/MEDIUM) o VETOED.
Corpo della richiesta
"secret": "your_webhook_secret",
"symbol": "BTC",
"direction": "long",
"timeframe": "1h",
"strategy": "EMA crossover",
"price": 67500.0
}
Richiesto: secret, symbol, direction (long|short). Opzionale: source, timeframe, strategy, price.
Personalizzazione
GET /preferences
Restituisce le attuali impostazioni di personalizzazione, inclusi i parametri predefiniti dei trade, il profilo di rischio, la watchlist e le preferenze di notifica.
Aggiorna le preferenze inviando un corpo JSON con un sottoinsieme dei campi seguenti. I campi omessi conservano i valori attuali.
Campi delle preferenze
| Campo | Tipo | Descrizione |
|---|---|---|
| default_trade_size_usd | float | Dimensione predefinita della posizione in USD per i calcoli di Kelly e smart-stop |
| risk_tolerance | string | conservative, moderate, o aggressive |
| default_risk_pct | float | Rischio predefinito per trade come % del conto. Utilizzato da /smart-stop quando risk_pct è omesso |
| watchlist | array | Lista ordinata di simboli di asset, es. ["BTC","ETH","SOL"] |
| notification_email | string | Indirizzo email per la ricezione degli alert |
| timezone | string | Stringa IANA del fuso orario, es. America/New_York |
"default_trade_size_usd": 5000,
"risk_tolerance": "moderate",
"default_risk_pct": 1.5,
"watchlist": ["BTC", "ETH", "SOL"]
}
GET /watchlist
Restituisce uno snapshot dello stato di conferma e le metriche di rischio chiave per tutti i simboli nella tua watchlist configurata. Fornisce una panoramica multi-asset senza dover effettuare chiamate /confirm separate per ogni simbolo.
Esempio di risposta
"ts": 1710940821,
"watchlist": [
{
"symbol": "BTC",
"confidence": "HIGH",
"action": "CONFIRM",
"regime": "accumulation",
"cascade_risk": "LOW"
},
{
"symbol": "ETH",
"confidence": "MEDIUM",
"action": "REDUCE",
"regime": "late_cycle_divergence",
"cascade_risk": "HIGH"
},
{
"symbol": "SOL",
"confidence": "HIGH",
"action": "CONFIRM",
"regime": "breakout",
"cascade_risk": "MEDIUM"
}
]
}
Streaming in tempo reale (Swap live)
Stream degli swap DEX ≥ $500 rilevati in tempo reale dai nostri nodi BSC e Avalanche. Sono disponibili due trasporti: uno stream pubblico Server-Sent Events (SSE) per client gratuiti/browser e un firehose WebSocket a bassa latenza per i piani a pagamento. Gli eventi vengono trasmessi entro pochi secondi dall'inclusione in un blocco.
Stream SSE pubblico (Gratuito)
Non è richiesta autenticazione. Supporto nativo EventSource in tutti i browser moderni. Il server emette swap eventi e heartbeat periodici per mantenere attiva la connessione.
es.addEventListener("swap", e => {
const swap = JSON.parse(e.data);
console.log(swap.chain, swap.pair, swap.amount_usd);
});
WebSocket Firehose (A pagamento)
Autenticazione (consigliata): non inserire mai la tua chiave di lunga durata nell'URL — viene registrata dai proxy e salvata nella cronologia del browser. Invia invece la tua chiave via POST a /v1/ws/ticket utilizzando l'header sicuro X-API-Key , quindi apri il socket con il ticket monouso restituito ticket (valido ~60s, utilizzabile una volta). I client lato server che possono impostare header possono invece passare X-API-Key direttamente durante l'handshake. Le chiavi del piano gratuito ricevono una 402 payment_required risposta. Un hello frame viene inviato alla connessione con il tuo piano e la soglia di trasmissione.
const r = await fetch("https://api.smartmoneyapi.com/v1/ws/ticket", {
method: "POST", headers: { "X-API-Key": "sm_xxx" }
});
const { ticket } = await r.json();
// 2. Apri il socket con il ticket monouso
const ws = new WebSocket(`wss://api.smartmoneyapi.com/v1/ws/live-swaps?ticket=${ticket}`);
ws.onmessage = e => {
const swap = JSON.parse(e.data);
if (swap.type === "swap") console.log(swap);
};
Autenticazione WebSocket (ticket)
Perché: non inserire mai la tua chiave API in un URL WebSocket — le query string vengono registrate da proxy, load balancer e salvate nella cronologia del browser. Invece, scambia la tua chiave con un ticket a breve durata e monouso ticket tramite una normale richiesta POST autenticata, quindi connettiti con quel ticket.
Flusso: POST a /v1/ws/ticket con il tuo X-API-Key header → ricevi { "ticket": "…", "expires_in": 60 }. Quindi apri wss://api.smartmoneyapi.com/v1/ws/live-swaps?ticket=<ticket>. Il ticket è monouso e scade in ~60 secondi. I client lato server che possono impostare gli header della richiesta possono invece passare X-API-Key direttamente durante l'handshake WebSocket — nessun ticket necessario.
Genera un ticket monouso per un handshake WebSocket autenticato. Autenticati con l'header X-API-Key (la tua chiave non lascia mai gli header della richiesta). Il ticket restituito può essere riscattato una volta su /v1/ws/live-swaps prima che scada.
"https://api.smartmoneyapi.com/v1/ws/ticket"
Esempio di risposta
"ticket": "wst_9f3c1a8e4b2d…",
"expires_in": 60
}
Campi della risposta
| Campo | Tipo | Descrizione |
|---|---|---|
| ticket | string | Token monouso da aggiungere come ?ticket= nell'URL WebSocket. Riscattato una volta, poi invalidato. |
| expires_in | number | Secondi rimanenti prima che il ticket scadi (~60). Genera un nuovo ticket per ogni tentativo di connessione. |
Nota: il legacy ?key= autenticazione tramite query-param è non più accettata sui endpoint WebSocket per motivi di sicurezza. Usa un ticket (client browser) o l'header X-API-Key durante l'handshake (client lato server).
Snapshot REST
Restituisce gli ultimi N swap trasmessi dal buffer circolare. Utile per il primo rendering su dashboard prima che la connessione allo stream si apra. Disponibile anche: /v1/live-swaps/status per le statistiche del broadcaster.
Schema dell'evento
| Campo | Tipo | Descrizione |
|---|---|---|
| chain | string | bsc o avalanche |
| dex | string | Nome del router (es. pancakeswap_v2, traderjoe) o unknown_dex |
| swapper | string | Indirizzo 0x completo del wallet che ha eseguito lo swap |
| swapper_short | string | Forma abbreviata per la visualizzazione (es. 0xb300…028d) |
| swapper_url | string | Link diretto al swapper sull'esploratore di blocchi della chain |
| tx_hash | string | Hash della transazione |
| explorer_url | string | Link diretto alla transazione su BscScan / Snowtrace |
| token_in | string | Simbolo del token venduto (es. USDT) |
| token_out | string | Simbolo del token acquistato |
| amount_usd | number | Valore in USD dello swap (minimo: $500) |
| pair | string | Etichetta formattata della coppia (es. USDT → USDC) |
| block | number | Numero del blocco in cui lo swap è stato minato |
| timestamp | number | Secondi Unix epoch |
| significance | string | low / medium / high / critical basato sulla dimensione in USD |
| seq | number | Numero di sequenza di trasmissione monotono — usato per rilevare gap |
POST /alerts/conditions
Crea regole di allerta personalizzate che si attivano quando una metrica specificata supera una soglia. Gli alert vengono consegnati via webhook, email o nel feed di notifiche della dashboard in base alle tue preferenze.
Restituisce una lista di tutte le condizioni di allerta configurate con i loro ID, definizioni e stato attuale.
Rimuove definitivamente una condizione di allerta tramite il suo ID.
Restituisce gli eventi di attivazione degli alert recenti con timestamp, condizioni corrispondenti e il valore della metrica al momento dell'attivazione.
Crea allerta — Corpo della richiesta
| Campo | Tipo | Descrizione |
|---|---|---|
| namerequired | string | Etichetta leggibile per questo avviso (max 64 caratteri) |
| metricobbligatorio | string | La metrica da monitorare. Vedi la tabella delle metriche disponibili qui sotto. |
| symbolopzionale | string | Contesto dell'asset. Richiesto per metriche legate al simbolo come funding_rate. |
| operatorobbligatorio | string | Operatore di confronto: gt, lt, eq, crosses_above, crosses_below |
| thresholdobbligatorio | float | Valore numerico da confrontare con la metrica |
| deliveryopzionale | string | Canale di consegna, es. telegram (predefinito) o webhook |
| cooldown_minutesopzionale | integer | Minuti minimi tra riattivazioni (predefinito 60) |
La lista aggiornata delle metriche e operatori validi è restituita da GET /v1/alerts/conditions come available_metrics e available_operators.
Metriche Disponibili
| Metrica | Descrizione |
|---|---|
| funding_rate | Tasso di funding corrente per il simbolo (come decimale) |
| global_lsr | Rapporto long/short globale per il simbolo |
| long_pct | Percentuale di account in posizione long per il simbolo |
| top_trader_lsr | Rapporto long/short dei top trader per il simbolo |
| taker_ratio | Rapporto acquirente/venditore taker per il simbolo |
| mvrv | Rapporto Valore di Mercato/Valore Realizzato (BTC/ETH) |
| sopr | Rapporto di Profitto degli Output Spesi (BTC/ETH) |
| exchange_net_flow | Segnale di flusso netto on-chain degli exchange |
| accumulation | Segnale di accumulo on-chain |
| whale_long_pct | Percentuale di portafogli whale tracciati in posizione long per il simbolo |
| whale_n_wallets | Numero di portafogli whale tracciati con una posizione nel simbolo |
| composite_long | Punteggio composito per il simbolo interrogato in direzione long |
| composite_short | Punteggio composito per il simbolo interrogato in direzione short |
| funding_spread | Spread di funding cross-venue per il simbolo |
"name": "Picco del tasso di funding BTC",
"metric": "funding_rate",
"symbol": "BTC",
"operator": "gt",
"threshold": 0.05
}
GET /kelly
Restituisce raccomandazioni di dimensionamento della posizione secondo il Criterio di Kelly calibrate sulla performance storica del segnale per il simbolo, livello di confidenza e direzione specificati. Basa la dimensione della posizione sui tassi di vittoria empirici per evitare over-leveraging.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolobbligatorio | string | Simbolo dell'asset: BTC, ETH, o SOL |
| confidenceopzionale | string | Livello di confidenza del segnale da modellare: HIGH, MEDIUM, o LOW. Predefinito: HIGH |
| directionopzionale | string | Direzione del trade: long o short. Predefinito: long |
| account_sizeopzionale | float | Dimensione dell'account in USD per il calcolo suggested_size_usd. Predefinito: 10000 |
Esempio di Risposta
"symbol": "BTC",
"confidence": "HIGH",
"direction": "long",
"win_rate": 0.68,
"avg_reward_risk_ratio": 2.1,
"kelly_fraction": 0.36,
"half_kelly": 0.18,
"suggested_size_usd": 1800,
"samples": 142,
"note": "Si consiglia Half-Kelly per il trading live per tenere conto degli errori di stima."
}
GET /performance
Restituisce statistiche storiche di accuratezza per i segnali emessi dall'API, suddivisi per livello di confidenza. Utile per comprendere l'affidabilità dei segnali prima di impegnare capitale.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| symbolopzionale | string | Filtra per asset. Ometti per statistiche aggregate su tutti i simboli. |
| daysopzionale | integer | Finestra di look-back in giorni. Predefinito: 30 |
Esempio di Risposta
"symbol": "BTC",
"period_days": 30,
"by_confidence": {
"HIGH": { "win_rate": 0.71, "samples": 58, "avg_return_pct": 3.4 },
"MEDIUM": { "win_rate": 0.54, "samples": 84, "avg_return_pct": 1.2 }
}
}
Statistiche & Segnali
GET /v1/stats
Statistiche di performance oneste a livello di sito provenienti da smart_money_confirm risultati di chiamate distinte. Restituisce tassi di successo ai livelli di confidenza HIGH e MEDIUM, accuratezza complessiva, fattore di profitto e una suddivisione per simbolo. Tutte le cifre sono in-sample durante la finestra di punteggio; consulta calibration.html per il contesto e la metodologia forward-holdout.
Esempio di Risposta
"high_winrate": 0.714,
"high_winrate_n": 14,
"medium_winrate": 0.530,
"medium_winrate_n": 34,
"overall_accuracy": 0.613,
"overall_accuracy_n": 48,
"profit_factor": 1.77,
"avg_win_pct": 4.2,
"winrate_horizon": "24h",
"winrate_basis": "chiamate di conferma distinte, risultati risolti in 24h",
"winrate_by_symbol": {
"BTC": { "win_rate": 0.68, "n": 22 },
"ETH": { "win_rate": 0.55, "n": 18 },
"SOL": { "win_rate": 0.60, "n": 8 }
},
"forward_holdout": {
"win_rate": 0.59,
"high_win_rate": 0.70,
"high_n": 10,
"is_distinct_from_insample": false
}
}
forward_holdout oggetto è l'unico numero accumulato su dati che lo scorer non ha mai visto — osserva crescere nel tempo. Vedi calibration.html per la metodologia completa e il confine tra in-sample e forward-test.GET /v1/signals/performance
Tracciamento degli esiti dei segnali su più orizzonti di risoluzione (4h, 12h, 24h, 72h). Restituisce tassi di successo per orizzonte, conteggi totali dei segnali e una suddivisione per tipo di segnale.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| daysopzionale | integer | Finestra di look-back in giorni. Predefinito: 30 |
| signal_typeopzionale | string | Filtra per tipo, ad esempio smart_money_confirm o regime_flip. Ometti per tutti i tipi. |
| symbolopzionale | string | Filtra per simbolo asset, ad esempio BTC. Ometti per aggregato su tutti i simboli. |
Esempio di Risposta
"signal_type": "smart_money_confirm",
"symbol": "BTC",
"days": 30,
"total_signals": 48,
orizzonti: {
4h: { tasso di successo: 0.65, risolti: 46 },
12h: { tasso di successo: 0.61, risolti: 44 },
24h: { tasso di successo: 0.58, risolti: 40 },
72h: { tasso di successo: 0.54, risolti: 32 }
},
ripartizione_per_tipo: {
smart_money_confirm: { conteggio: 35, tasso_di_successo_24h: 0.61 },
cambio_di_regime: { conteggio: 13, tasso_di_successo_24h: 0.47 }
}
}
GET /v1/signals/recent
Feed dei segnali HIGH e MEDIUM pubblicati di recente su tutti i simboli monitorati. Ogni voce include il tipo di segnale, il livello di confidenza, la direzione e lo stato di risoluzione, se disponibile.
Risposta di esempio
signals: [
{
id: 1042,
simbolo: BTC,
direzione: long,
tipo_segnale: smart_money_confirm,
confidenza: HIGH,
composito: 0.74,
ts: 1710940821,
risolto: true,
risultato_24h: vittoria
}
],
conteggio: 50
}
GET /v1/signals/{id}/outcome
Risultato risolto per un singolo segnale tramite il suo ID numerico. Restituisce successo/fallimento per ogni orizzonte di risoluzione (4h, 12h, 24h, 72h) insieme al prezzo al momento del segnale e alla risoluzione.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| idobbligatorio | intero | ID del segnale (segmento del percorso), es. /v1/signals/1042/outcome |
Risposta di esempio
"id": 1042,
"symbol": "BTC",
"direction": "long",
"confidence": "HIGH",
"entry_price": 63200.0,
"ts": 1710940821,
"outcomes": {
"4h": { "result": "win", "price": 64100.0, "pct": 1.41 },
"12h": { "result": "win", "price": 65200.0, "pct": 3.16 },
"24h": { "result": "win", "price": 65800.0, "pct": 4.11 },
"72h": { "result": "pending", "price": null, "pct": null }
}
}
GET /v1/confirm-winrate
Conferma il breakdown del tasso di vincita dei segnali per la chiave API personale dell'utente autenticato. Restituisce i tassi di vincita distinti per chiamata a ogni livello di confidenza, il fattore di profitto e le cifre per simbolo. Richiede un X-API-Key header valido.
Richiesta di esempio
"https://api.smartmoneyapi.com/v1/confirm-winrate"
Risposta di esempio
"high_winrate": 0.714,
"high_n": 14,
"medium_winrate": 0.530,
medium_n: 34,
overall_accuracy: 0.613,
overall_n: 48,
profit_factor: 1.77,
winrate_horizon: 24h,
by_symbol: {
BTC: { win_rate: 0.68, n: 22 },
ETH: { win_rate: 0.55, n: 18 }
}
}
Shadow Gate
Un registro personale immutabile e di sola aggiunta per le decisioni di trading. Invia le tue decisioni di trading prima o dopo averle eseguite; il sistema calcola un punteggio di conferma rispetto al motore Smart Money e aggiunge una riga permanente. Usalo per costruire un tracciamento temporale onesto di quanto il segnale dell'API sia stato allineato con le tue decisioni — completamente indipendente dal pool globale dei tassi di vincita. Le risposte dei tier Free e Trader hanno i campi delle prove rimossi; Pro restituisce l'analisi completa. Un ritardo di tier si applica ai dati del tier Free.
Invia una decisione. Idempotente sull' Idempotency-Key header della richiesta — reinviare la stessa chiave restituisce la riga esistente senza creare un duplicato. Il sistema chiama immediatamente il motore di conferma e aggiunge il risultato come una riga immutabile del registro.
Request Body
| Campo | Tipo | Descrizione |
|---|---|---|
| symbolrequired | string | Simbolo dell'asset, es. BTC |
| siderequired | string | Direzione del trade: long or short |
| strategy_idoptional | string | Etichetta strategica definita dal chiamante (massimo 64 caratteri). Memorizzata così com'è per raggruppamento e filtraggio. |
Example Request
-H "X-API-Key: sm_your_key" \
-H "Idempotency-Key: my-signal-20260701-001" \
-H "Content-Type: application/json" \
-d '{"symbol":"BTC","side":"long","strategy_id":"ema_crossover"}' \
"https://api.smartmoneyapi.com/v1/shadow-gate/decisions"
Example Response
"id": 318,
"symbol": "BTC",
"side": "long",
"strategy_id": "ema_crossover",
"decision": "CONFIRM",
"confidence": "HIGH",
"composite": 0.74,
"size_mult": 1.5,
"ts": 1710940821,
"resolved": false
}
factors / adjustments campi delle prove. Pro restituisce l'analisi completa di conferma. Un ritardo di tier si applica a Free — la riga viene scritta immediatamente ma il punteggio di conferma potrebbe riflettere dati memorizzati nella cache fino a 60 secondi precedenti.Elenca le tue decisioni shadow-gate, dalla più recente alla più vecchia. Limitato al proprietario — vengono restituite solo le decisioni inviate dalla tua chiave API.
Parametri
| Parametro | Tipo | Descrizione |
|---|---|---|
| limitoptional | integer | Numero massimo di righe da restituire. Default: 50, max: 200 |
| cursoroptional | string | Cursore di paginazione opaco dal campo next_cursor di una risposta precedente. Ometti per la prima pagina. |
Example Response
"decisions": [
{ "id": 318, "symbol": "BTC", "side": "long", "decision": "CONFIRM", "confidence": "HIGH", "composite": 0.74, "size_mult": 1.5, "ts": 1710940821, "resolved": false },
{ "id": 317, "symbol": "ETH", "side": "short", "decision": "SKIP", "confidence": "LOW", "composite": -0.12, "size_mult": 0.0, "ts": 1710937000, "resolved": true }
],
"count": 2,
"next_cursor": null
}
Decisione singola per ID, inclusa l'evidenza completa di conferma per il livello Pro. Le risposte dei livelli Free e Trader hanno factors e adjustments rimossi. Restituisce 403 se la decisione appartiene a una chiave API diversa.
Esempio di risposta (Pro)
"id": 318,
"symbol": "BTC",
"side": "long",
"strategy_id": "ema_crossover",
"decision": "CONFIRM",
"confidence": "HIGH",
"composite": 0.74,
"size_mult": 1.5,
"factors": {
"derivatives": { "score": 0.81, "weight": 0.40, "weighted": 0.324 },
"onchain": { "score": 0.68, "weight": 0.35, "weighted": 0.238 },
"whale": { "score": 0.73, "weight": 0.25, "weighted": 0.183 }
},
"ts": 1710940821,
"resolved": false,
"outcome": null
}
Risolvi manualmente l'esito di una decisione. Chiama questo endpoint dopo aver chiuso il trade per registrare il risultato finale nella riga del registro. Una volta risolta, la riga è immutabile e non può essere modificata nuovamente.
Corpo della richiesta
| Campo | Tipo | Descrizione |
|---|---|---|
| outcomerequired | string | Esito del trade: win o loss |
| exit_priceoptional | float | Prezzo di uscita del trade. Memorizzato per riferimento; utilizzato per calcolare il P&L % se fornito. |
| pnl_pctoptional | float | P&L realizzato come percentuale della dimensione della posizione, es. 3.5 o -1.2 |
Esempio di risposta
"id": 318,
"resolved": true,
"outcome": "win",
"exit_price": 65800.0,
"pnl_pct": 4.1,
"resolved_at": 1711027200
}
Codici di errore
| Stato | Codice | Descrizione |
|---|---|---|
| 400 | invalid_params | Parametri di query mancanti o non validi |
| 401 | unauthorized | Chiave API mancante o non valida |
| 403 | plan_restriction | Endpoint non disponibile nel tuo piano attuale |
| 429 | rate_limit_exceeded | Limite giornaliero o burst raggiunto |
| 500 | internal_error | Errore del server — controlla /health per lo stato della sorgente |
| 503 | data_stale | Sorgente dati non disponibile; restituiti gli ultimi dati conosciuti |
Esempi di codice
Python
r = requests.get(
"https://api.smartmoneyapi.com/v1/confirm",
params={"symbol": "BTC", "direction": "long"},
headers={X-API-Key: sm_your_key}
)
data = r.json()
print(data[confidence]) # HIGH / MEDIUM
print(data[size_mult]) # 1.5 / 1.0
API_KEY = sm_your_key
BASE_URL = https://api.smartmoneyapi.com/v1
def confirm_trade(symbol, direction):
resp = requests.get(
f{BASE_URL}/confirm,
params={symbol: symbol, direction: direction},
headers={X-API-Key: API_KEY},
timeout=5
)
resp.raise_for_status()
return resp.json()
# Nel tuo ciclo di trading:
signal = confirm_trade(BTC, long)
if signal[confidence] not in [HIGH, MEDIUM]:
print(Salto — fiducia insufficiente)
else:
size = base_size * signal[size_mult]
place_order(symbol, direction, size)
JavaScript / Node.js
async function confirmTrade(symbol, direction) {
const params = new URLSearchParams({ symbol, direction });
const res = await fetch(
`https://api.smartmoneyapi.com/v1/confirm?${params}`,
{ headers: { 'X-API-Key': API_KEY } }
);
if (!resok) throw new Error(`Errore API: ${resstatus}`);
return res.json();
}
// Utilizzo
confirmTrade('BTC', 'long').then(data => {
console.log(dataconfidence, datasize_mult);
});
cURL
curl -X GET \
-H X-API-Key: sm_your_key \
https://api.smartmoneyapi.com/v1/confirm?symbol=BTC&direction=long
# Ottieni dati sulle balene
curl -X GET \
-H X-API-Key: sm_your_key \
https://api.smartmoneyapi.com/v1/whales?symbol=BTC
# Controlla l'utilizzo
curl -X GET \
-H X-API-Key: sm_your_key \
https://api.smartmoneyapi.com/v1/usage
Integrazione Freqtrade
Aggiungi la conferma di Smart Money a qualsiasi strategia Freqtrade sovrascrivendo il confirm_trade_entry metodo.
from freqtrade.strategy import IStrategy
class SmartMoneyStrategy(IStrategy):
SM_API_KEY = "sm_your_key"
SM_BASE = "https://api.smartmoneyapi.com/v1"
def confirm_trade_entry(self, pair, order_type,
amount, rate, time_in_force,
current_time, entry_tag, **kwargs):
symbol = pair.split("/")[0]
if symbol not in ["BTC", "ETH", "SOL"]:
return True # Salta il controllo per simboli non supportati
try:
r = requests.get(
f"{self.SM_BASE}/confirm",
params={"symbol": symbol, "direction": "long"},
headers={"X-API-Key": self.SM_API_KEY},
timeout=3
).json()
return r.get("confidence") in ["HIGH", "MEDIUM"]
except:
return True # In caso di errore API, procedi comunque
CCXT + Smart Money
exchange = ccxt.bybit({
"apiKey": "YOUR_BYBIT_KEY",
"secret": "YOUR_BYBIT_SECRET"
})
SM_KEY = "sm_your_key"
def smart_trade(symbol, side, amount):
# Controlla prima la conferma
conf = requests.get(
"https://api.smartmoneyapi.com/v1/confirm",
params={"symbol": symbol, "direction": side},
headers={"X-API-Key": SM_KEY}
).json()
if conf["confidence"] not in ["HIGH", "MEDIUM"]:
print(f"Saltando {symbol} {side} — fiducia insufficiente.")
return None
adj_amount = amount * conf["size_mult"]
order = exchange.create_market_order(
f"{symbol}/USDT", side, adj_amount
)
print(f"Ordine eseguito: {adj_amount} {symbol} {side}")
return order
Consulta la pagina dello stato dell'API per informazioni in tempo reale sullo stato, o usa il nostro modulo di contatto.