Referință completă API REST

Stăpânește API-ul Smart Money cu referința noastră completă REST. Învață toate endpoint-urile, parametrii, metodele de autentificare și modelele de integrare pentru informații despre derivatele crypto și datele de urmărire a balenelor.

Prezentare generală

API-ul Smart Money oferă acces REST la date în timp real despre derivatele cripto pe trei burse majore: Bybit, Binance și Hyperliquid. API-ul nostru agregă pozițiile portofoliilor balenelor, ratele de finanțare, metricile privind interesul deschis, datele despre lichidări și semnalele on-chain într-o singură interfață unificată. Fie că construiești algoritmi de tranzacționare, sisteme de gestionare a riscului sau instrumente de analiză a pieței, API-ul REST îți oferă acces programatic direct la toate informațiile Smart Money.

Cu peste 229 de simboluri de tranzacționare descoperite automat și peste 600 de portofolii de balene monitorizate, API-ul oferă informații complete despre piață. Conexiunile WebSocket în timp real oferă actualizări sub-secundă, în timp ce endpoint-urile noastre REST gestionează interogări în lot, preluarea datelor istorice și analiza portofoliului la scară.

Toate cererile trebuie să includă credențiale de autentificare valide. Utilizatorii din nivelul gratuit au 20 de cereri pe zi limitate la BTC. Nivelul Trader (400 de cereri/zi) și nivelul Pro (4.000 de cereri/zi) deblochează toate simbolurile și funcțiile avansate.

Autentificare

API-ul Smart Money folosește autentificare prin cheie API. Metoda principală este X-API-Key antetul cererii. Poți genera chei API din panoul tău. Un JWT de sesiune prin Authorization: Bearer este acceptat ca rezervă pentru sesiunile din browser/panou, dar clienții API ar trebui să folosească X-API-Key.

Autentificare cu cheie API (principală)

Trimite cheia ta API în X-API-Key antetul fiecărei cereri. Nu pune niciodată cheia într-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 de sesiune (rezervă)

Sesiunile din browser/panou pot trimite un JWT de sesiune prin Authorization: Bearer (valabil pentru 24 de ore). Clienții programatici ar trebui să prefere X-API-Key.

Python

import requests
import json

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

# Folosește JWT pentru cererile ulterioare
headers = {"Authorization": f"Bearer {token}"}
whales = requests.get(
  "https://api.smartmoneyapi.com/v1/whales/events",
  headers=headers
)
print(whales.json())

URL de bază și endpoint-uri

Toate cererile API se trimit la https://api.smartmoneyapi.com. API-ul este organizat în categorii logice de resurse cu prefixe de versiune. Versiunea stabilă curentă este v1.

URL de bază: https://api.smartmoneyapi.com/api/v1

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

Formatul răspunsului

Toate răspunsurile API sunt returnate ca obiecte JSON cu un format standard de înveliș. Răspunsurile de succes returnează coduri de stare HTTP 200-299 cu date în corpul răspunsului. Răspunsurile de eroare includ mesaje detaliate de eroare și sugestii de rezolvare.

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 pentru pozițiile balenelor

Preia poziții detaliate din portofoliile balenelor monitorizate pe toate bursele. Acest endpoint arată levierul în timp real, prețurile de intrare, prețurile de lichidare și P&L nerealizat pentru poziții de valoare mare.

GET /v1/whales/events PRO

Parametru	Tip	Descriere
symbol	string	Pereche de tranzacționare (de ex., BTCUSDT, ETHUSDT) opțional
exchange	string	Filtrează după bursă: bybit, binance, hyperliquid opțional
min_position_size	number	Dimensiunea minimă a poziției în activul de bază opțional
direction	string	Poziții long sau short doar opțional
page	integer	Numărul paginii de paginare, implicit 1 opțional
limit	integer	Rezultate pe pagină, maxim 100, implicit 50 opțional

Exemplu de cerere:

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 pentru ratele de finanțare

Accesează ratele de finanțare în timp real și istorice pe Bybit, Binance și Hyperliquid. Ratele de finanțare sunt critice pentru tranzacționarea arbitraj, strategii swing și hedging pe derivate. API-ul nostru agregă ratele cu granularitate de 15 minute și oferă analize istorice ale ratelor.

GET /v1/funding-rates FREE

Parametru	Tip	Descriere
symbol	string	Pereche de tranzacționare (de ex., BTCUSDT) obligatoriu
exchange	string	Bursă: bybit, binance, hyperliquid opțional
interval	string	1h, 4h, 1d, implicit 1h opțional
limit	integer	Perioade istorice de returnat, maxim 500 opțional

Exemplu de cerere:

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 pentru Interes Deschis

Monitorizează interesul deschis agregat pentru toți comercianții cu levier. Divergența interesului deschis față de mișcarea prețului semnalează potențiale reversări și oportunități de continuare a trendului. Urmărește atât OI absolut, cât și ratele de schimbare ale OI.

GET /v1/open-interest TRADER

Parametru	Tip	Descriere
symbol	string	Pereche de tranzacționare obligatoriu
exchange	string	bybit, binance sau hyperliquid opțional
granularity	string	1m, 5m, 15m, 1h, 4h, 1d, implicit 15m opțional

Endpoint pentru Lichidări

Returnează două perspective complementare pentru un simbol: niveluri proiectate cu levier niveluri (o estimare a locului unde se află clusterele de lichidare) și un realized_heatmap — INTENSITATEA reală a lichidărilor forțate executate (preț × timp) agregată în timp real din fluxurile WebSocket ale burselor publice: Binance, OKX, Bybit, Bitget și BitMEX. Harta termică este prezentă atunci când fluxul are date pentru simbol.

GET /v1/liquidations TRADER

Parametru	Tip	Descriere
symbol	string	Simbolul activului, implicit BTC opțional

Trader returnează riscul în cascadă, distanțele cele mai apropiate și totalurile realizate/pe parte. Pro returnează nivelurile proiectate complete niveluri plus întregul realized_heatmap (matrice, clustere pe preț, numărări pe bursă).

Lichidări On-Chain DeFi

Lichidări executate pe protocoalele de împrumut DeFi capturate direct de la nodurile noastre locale complete BSC și Avalanche — independent de orice bot de tranzacționare. Acoperă Venus/Cream și Moolah pe BSC, și AAVE V3/V2, Benqi, BankerJoe, Granary și Vinium pe Avalanche. Necesită o cheie autentificată (Trader+); Pro returnează în plus pozițiile în risc dependente de bot.

GET /v1/liquidations/onchain TRADER

Parametru	Tip	Descriere
chain	string	bsc sau avax; omite pentru toate opțional
limit	integer	Număr maxim de rânduri, implicit 100, maxim 500 (cele mai noi primele) opțional

Endpoint de Confirmare

Endpoint-ul /v1/confirm returnează un scor de confluență bazat pe reguli, multi-factor confluence combinând derivate, on-chain (Coin Metrics gratuit: MVRV / flux de schimb / adrese active) și poziționarea balenelor. Scorul composite variază de la -1.0 la +1.0 (nu 0–100) și fiecare răspuns include o defalcare transparentă a factors (scor pe factor × pondere), adjustments, ponderile, și coverage. Este un suport de decizie, nu o rată de câștig garantată. Un simbol netransat returnează un rezultat explicit NO_DATA / nesuportat în loc de unul fabricat LOW.

GET /v1/confirm TRADER

Parametri: symbol (BTC/ETH/SOL) și direction (long/short). confidence este unul dintre HIGH / MEDIUM / LOW / VETO / NO_DATA; action este unul dintre CONFIRM_FULL / CONFIRM_REDUCED / CONFIRM_MINIMAL / VETO_SKIP / NO_DATA_SKIP; size_mult este multiplicatorul sugerat pentru dimensiunea poziției.

Endpoint-uri pentru Date On-Chain

Accesează metrici on-chain pentru Bitcoin și Ethereum, inclusiv fluxuri de schimb, mișcări ale portofelelor balenelor, raportul MVRV, NUPL, condiții de cheltuială și volatilitate realizată. Aceste metrici identifică cicluri de acumulare/distribuție și oferă semnale timpurii pentru reversări majore.

GET /v1/on-chain/metrics PRO

Parametru	Tip	Descriere
asset	string	bitcoin sau ethereum obligatoriu
metrics	array	Metrici specifice: exchange_flows, mvrv, nupl, whale_moves opțional
interval	string	1d (zilnic), 1w (săptămânal), implicit 1d opțional

Referință pentru Modele de Date

Înțelegerea structurii răspunsurilor API este esențială pentru integrare. Mai jos sunt definițiile complete ale modelelor de date utilizate în toate endpoint-urile.

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

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

Exemple de cod

Mai jos sunt exemple de cod pregătite pentru producție pentru modele comune de integrare.

Monitorizarea pozițiilor balenelor în 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:
        """Preia pozițiile balenelor cu filtru opțional pentru simbol"""
        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:
        """Obține ratele de fondare curente și istorice"""
        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):
        """Monitorizează continuu pozițiile balenelor"""
        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)

# Utilizare
client = SmartMoneyClient("sk_live_abc123xyz789")
whales = client.get_whale_positions("BTCUSDT")
print(f"Poziții totale ale balenelor: {whales['data']['total']}")

Bune practici și sfaturi de performanță

Folosește paginare: Întotdeauna paginează seturile mari de rezultate. Folosește parametrii limit și page pentru a prelua date în bucăți de 50-100 de înregistrări, nu toate datele deodată.

Cachează răspunsurile: Pozițiile balenelor nu se schimbă în fiecare secundă. Cachează rezultatele pentru 30-60 de secunde pentru a reduce apelurile API și a îmbunătăți performanța.

Filtrează devreme: Folosește parametrii de interogare (symbol, exchange, direction) pentru a filtra datele pe server, nu în codul aplicației tale.

Gestionează limitele de rată: Implementează logică de reluare cu backoff exponențial. Când atingi limitele de rată (status 429), așteaptă și reîncearcă.

Folosește WebSocket pentru timp real: Pentru date în flux, preferă conexiunile WebSocket în loc să interoghezi endpointurile REST. Vei economisi lățime de bandă și vei obține latență sub secundă.

Validează marcajele temporale: Toate marcajele temporale sunt în format ISO 8601 UTC. Întotdeauna convertește în fusul orar local pentru afișare și întotdeauna stochează în UTC.

Gestionează deconectările: Implementează logică de reconectare automată cu backoff exponențial pentru conexiunile WebSocket.

Monitorizează-ți cota: Verifică antetul X-Requests-Remaining în răspunsuri. Planifică-ți utilizarea API pentru a rămâne în limita nivelului tău.

Modele comune de integrare

Modelul 1: Alertă la acumularea balenelor

Configurează alerte când pozițiile balenelor depășesc un prag, semnalând potențiale tendințe ascendente sau faze de acumulare.

Modelul 2: Detectarea arbitrajului ratelor de fondare

Detectează automat când diferențele dintre ratele de fondare depășesc pragurile profitabile pe diferite exchange-uri, permițând algoritmii de arbitraj între exchange-uri.

Modelul 3: Monitorizarea cascadei de lichidări

Urmărește lichidările mari și poziționează algoritmul pentru a profita de lichidările în cascadă și de mișcările de preț cu impact ridicat.

Modelul 4: Confirmare multi-semnal

Combină pozițiile balenelor, ratele de fondare, metricile on-chain și scorurile noastre de confirmare AI pentru semnale de intrare cu încredere ridicată.

Gata să începi?

Obține cheia ta API din consolă și începe să construiești astăzi. Toate conturile noi beneficiază de acces gratuit la nivelul de bază cu 20 de cereri pe zi (BTC, ETH, SOL). Actualizează la Trader sau Pro pentru acces nelimitat la toate simbolurile și funcții avansate.

Obține cheia API

Deblochează funcții Pro

Obține acces complet la pozițiile balenelor, scoruri de confirmare, date on-chain și peste 2000 de cereri API zilnice.

Vezi prețurile