Guida all'Autenticazione

Scopri come autenticarti con Smart Money API utilizzando chiavi API, token JWT e OAuth 2.0. Proteggi le tue integrazioni con metodi di autenticazione standard del settore e migliori pratiche.

Panoramica

Smart Money API supporta diversi metodi di autenticazione per diversi casi d'uso. Scegli il metodo più adatto alla tua integrazione:

Chiavi API (primario): Invia la tua chiave nell'header X-API-Key della richiesta per tutte le chiamate API REST. Questo è il metodo consigliato per bot e uso server-to-server.

JWT di Sessione (alternativa): Le sessioni del browser/dashboard si autenticano con un JWT di sessione tramite Authorization: Bearer, valido per 24 ore. I client programmatici dovrebbero preferire X-API-Key.

OAuth 2.0: Autenticazione di livello enterprise per applicazioni multi-utente e integrazioni di terze parti. Gli utenti autorizzano la tua app ad accedere ai loro dati.

Tutte le richieste API devono essere effettuate tramite HTTPS. Le richieste HTTP non crittografate verranno rifiutate. Inoltre, non inserire mai le chiavi API nel controllo versione o condividerle pubblicamente.

Chiavi API

Le chiavi API sono credenziali uniche emesse per il tuo account. Ogni chiave rappresenta un singolo set di permessi e quote. Puoi generare più chiavi per diverse applicazioni o ambienti (sviluppo, staging, produzione).

Generazione di una Chiave API

Genera le chiavi API dalla tua console dell'account:

Vai alla Smart Money Console
Seleziona "Chiavi API" dalla barra laterale
Clicca su "Genera Nuova Chiave"
Scegli il tipo di chiave (Sviluppo, Staging, Produzione)
Imposta il limite di frequenza e le funzionalità
Copia e salva la chiave in modo sicuro

Salva immediatamente la tua chiave API! Non potrai più visualizzarla. Se la perdi, dovrai generare una nuova chiave.

Formato della Chiave

Le chiavi API seguono un formato standard:

Formato della Chiave

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

I prefissi delle chiavi indicano l'ambiente:

sk_live_ — Chiavi di produzione con quota completa

sk_test_ — Chiavi di test con quota ridotta e dati di sviluppo

sk_dev_ — Chiavi di sviluppo personale con dati sandbox

Header X-API-Key (primario)

Invia la tua chiave API nell'header X-API-Key della richiesta per tutte le chiamate API. Non inserire mai la chiave in un URL.

Header HTTP

HTTP

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

Esempio cURL

Shell

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

Esempio Python

Python

import requests

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

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

data = response.json()

Autenticazione con Token JWT

Per sessioni di lunga durata e comunicazioni server-to-server, scambia la tua chiave API con un token JWT. I token JWT durano 24 ore e riducono la necessità di memorizzare la chiave API nel codice dell'applicazione.

Ottenere un Token JWT

Invia la tua chiave API tramite POST all'endpoint JWT per ottenere un token:

cURL

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

Risposta JWT

JSON

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

Utilizzo del Token JWT

Utilizza il token JWT nell'header Authorization come le chiavi API:

Python

import requests
import json
from datetime import datetime, timedelta

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

    def get_valid_token(self):
        # Verifica se il token corrente è ancora valido
        if self.token and self.token_expires > datetime.now():
            return self.token

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

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

        return self.token

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

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

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

OAuth 2.0

OAuth 2.0 è per applicazioni che devono accedere a più account utente. Gli utenti concedono alla tua applicazione il permesso di accedere ai loro dati senza condividere le loro chiavi API.

Flusso OAuth 2.0

Smart Money API supporta il flusso Authorization Code per applicazioni web:

L'utente clicca sul pulsante "Connetti con Smart Money"
Il browser reindirizza alla pagina di autorizzazione
L'utente concede i permessi alla tua applicazione
Il browser reindirizza con un codice di autorizzazione
Il tuo backend scambia il codice con un token di accesso
Ora puoi accedere ai dati dell'utente per suo conto

Step 1: Richiesta di Autorizzazione

Reindirizza l'utente all'endpoint di autorizzazione:

URL

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

Step 2: Scambio del Token

Dopo che l'utente ha concesso i permessi, scambia il codice con un token di accesso:

cURL

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

Risposta del Token OAuth

JSON

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

Migliori Pratiche di Sicurezza

Memorizza le Chiavi in Modo Sicuro

Non inserire mai le chiavi API nel controllo versione, hardcodarle nelle applicazioni o condividerle nella documentazione. Utilizza variabili d'ambiente o servizi di gestione delle chiavi sicuri come AWS Secrets Manager, HashiCorp Vault o simili.

Usa Solo HTTPS

Tutte le richieste API devono utilizzare HTTPS (TLS 1.2 o superiore). Le richieste HTTP verranno rifiutate. Ciò garantisce che la tua chiave API e i dati siano crittografati durante il trasferimento.

Limita i Permessi delle Chiavi

Crea chiavi API separate per diverse applicazioni e ambienti. Usa gli scope per limitare ciò a cui ogni chiave può accedere. Non utilizzare chiavi di produzione in sviluppo.

Monitora l'Utilizzo delle Chiavi

Rivedi regolarmente l'utilizzo dell'API nella tua console. Imposta avvisi per attività insolite o quote che si avvicinano ai limiti. Elimina le chiavi che non utilizzi più.

Rotazione delle Chiavi

Ruota regolarmente le tue chiavi API per ridurre il rischio di compromissione. Consigliamo di ruotare le chiavi ogni 90 giorni:

Genera una nuova chiave API nella tua console
Aggiorna le tue applicazioni per utilizzare la nuova chiave
Verifica che tutto funzioni correttamente
Elimina la vecchia chiave dalla tua console

Ambiti & Permessi

Quando crei chiavi API o usi OAuth, specifica quali risorse può accedere la tua chiave:

Ambito	Descrizione	Piano
whale_positions	Leggi le posizioni dei portafogli delle balene	Trader+
funding_rates	Leggi i dati dei tassi di funding	Free+
liquidations	Leggi i feed delle liquidazioni	Free+
open_interest	Leggi i dati dell'open interest	Trader+
confirmation_scores	Leggi i punteggi di conferma dell'AI	Pro+
on_chain	Leggi le metriche on-chain	Pro+

Esempi di Codice per l'Autenticazione

Integrazione Completa in Python

Python

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

class SmartMoneyAuth:
    """Gestisce tutti i metodi di autenticazione per Smart Money API"""

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

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

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

    def headers_bearer(self) -> Dict:
        """Ottieni gli header per l'autenticazione Bearer token"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Ottieni gli header per l'autenticazione JWT"""
        token = self.get_jwt_token()
        return {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

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

# Utilizzo
auth = SmartMoneyAuth("sk_live_abc123xyz789")

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

# Metodo JWT (auto-aggiornante)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"Trovate {whales['data']['total']} posizioni di balene")

Serve aiuto?

Consulta la nostra documentazione API o contatta il supporto se hai bisogno di assistenza con l'autenticazione.

Riferimento API

Genera la tua prima chiave API

Inizia con Smart Money API. Crea il tuo account e genera le credenziali di autenticazione in pochi minuti.

Vai alla Console