Giacenze Crypto

API pubblica delle quotazioni

Un'API pubblica e senza autenticazione che fornisce quotazioni cripto in euro, ricavate dallo stato delle pool di scambio decentralizzate on-chain. Giacenze Crypto può interrogarla per alleggerire le importazioni, ma non è l'unica fonte di prezzo del programma. Qui trovi come usarla e come i prezzi vengono reperiti.

In breve

Il servizio è offerto così com'è, senza garanzie di continuità o accuratezza: è pensato per alleggerire le importazioni dell'applicazione, non come fonte di prezzo primaria per terzi. Le monete coperte sono poche decine (vedi /v1/monete); per tutto il resto l'applicazione ricade sul recupero locale dagli exchange.

GET /v1/prezzo — prezzo puntuale

Restituisce i punti prezzo salvati in una finestra di ±10 minuti attorno a un istante.

Parametri

ParametroObbligatorioFormatoNote
symbolsìstringaCase-insensitive, es. BTC, ETH. Deve essere fra le monete gestite.
timestampsìintero, ms epochNon può essere nel futuro.

Risposte

200 — risolto: la finestra ±10 minuti attorno al timestamp è coperta (con o senza prezzi trovati in quei minuti).

{
  "esito": "risolto",
  "punti": [
    { "timestamp": 1786794780000, "prices": { "onchain": 1878.9204789926403 } }
  ]
}

503 — non disponibile: la finestra non è coperta — non ancora, o mai per scelta (storico precedente all'inizio della raccolta, monete di cui si ha solo il prezzo corrente). Corpo { "esito": "non disponibile" }, nessun campo punti.

Poiché la finestra ±10 minuti si estende anche dopo il timestamp, una richiesta per un istante negli ultimi 10 minuti risulta sempre non disponibile: quel minuto non è ancora passato. È atteso, non un difetto.

400: symbol mancante, timestamp mancante/non numerico o nel futuro, moneta non gestita ({ "errore": "moneta \"PIPPO\" non gestita da questo servizio" }).

Esempi

curl "https://giacenzecrypto.it/v1/prezzo?symbol=ETH&timestamp=1786794780000"
curl "https://giacenzecrypto.it/v1/prezzo?symbol=PIPPO&timestamp=1786794780000"   # -> 400

GET /v1/prezzi — prezzi su intervallo

Restituisce tutti i punti prezzo salvati per un intervallo, in una sola richiesta, invece di una raffica di chiamate a /v1/prezzo. Indica anche quali sotto-intervalli risultano coperti e quali no.

Parametri

ParametroObbligatorioFormatoNote
symbolsìstringaCome sopra.
dasìintero, ms epochEstremo iniziale, incluso.
asìintero, ms epochEstremo finale, incluso. Se nel futuro viene ridotto ad "adesso" (non è un errore: qui si legge direttamente l'archivio).

Vincoli: da ≤ a, l'intervallo non può essere interamente nel futuro, l'ampiezza a − da non può superare 31 giorni. Oltre il tetto la risposta è 400 con il massimo nel messaggio.

Paginazione

Gli estremi sono inclusivi, quindi per la pagina successiva si parte da da = a della pagina precedente + 1. I campi da/a nella risposta sono quelli effettivi (con a eventualmente ridotto ad "adesso"): usare quelli per calcolare la pagina dopo.

Risposta — 200

La risposta è 200 ogni volta che la richiesta è valida: una copertura parziale è la norma per un intervallo, non un errore.

{
  "esito": "ok",
  "symbol": "ETH",
  "da": 1786790000000,
  "a": 1786794780000,
  "punti": [
    { "timestamp": 1786790040000, "prices": { "onchain": 1875.11 } },
    { "timestamp": 1786794780000, "prices": { "onchain": 1878.92 } }
  ],
  "coperto":    [ { "start": 1786790040000, "end": 1786794780000 } ],
  "nonCoperto": [ { "start": 1786790000000, "end": 1786790039999 } ],
  "troncato": false
}

400: parametri mancanti o non numerici, a < da, intervallo interamente nel futuro, ampiezza oltre il tetto, moneta non gestita.

Esempi

curl "https://giacenzecrypto.it/v1/prezzi?symbol=ETH&da=1786790000000&a=1786794780000"

# pagina successiva: da = (a precedente) + 1
curl "https://giacenzecrypto.it/v1/prezzi?symbol=ETH&da=1786794780001&a=1789382780000"

GET /v1/monete — trasparenza

Elenca ogni moneta gestita, da quando esistono dati per ciascuna e da quale/i pool on-chain ne viene ricavato il prezzo — così che chiunque possa verificare una quotazione interrogando direttamente la stessa pool. Nessun parametro.

{
  "monete": [
    {
      "symbol": "BTC",
      "esposta": true,
      "disponibileDal": 1740787200000,
      "disponibileDalIso": "2026-03-01T00:00:00.000Z",
      "pool":          { "rete": "eth", "indirizzo": "0x99ac…", "versione": "v3", "nota": "WBTC/USDC 0.3%" },
      "poolSecondaria": { "rete": "eth", "indirizzo": "0x9db9…", "versione": "v3", "nota": "…" }
    }
  ],
  "endpointsRpc": { "eth": ["https://…"], "bsc": ["https://…"], "solana": ["https://…"] },
  "note": "…"
}

GET /health

Sonda di stato, senza autenticazione né limite: { "ok": true } quando il servizio risponde.

Come vengono reperiti i prezzi

I prezzi non provengono dai listini degli exchange centralizzati: le loro condizioni d'uso vietano la ridistribuzione dei dati di mercato a terzi. Vengono invece letti direttamente dallo stato delle pool di scambio decentralizzate (DEX) on-chain, che è dato pubblico della blockchain, di nessuno in particolare, leggibile da chiunque tramite un nodo RPC.

Le pool esatte e i nodi RPC usati sono elencati da /v1/monete: ogni prezzo servito è ricontrollabile interrogando la stessa pool allo stesso blocco.

Servizio informativo, offerto senza garanzie di disponibilità o di esattezza. I dati on-chain possono contenere anomalie (bassa liquidità, scambi manipolati); l'applicazione applica controlli propri e resta responsabilità di chi li usa verificarne l'adeguatezza. Codice sorgente del servizio nel repository del progetto, cartella ServizioPrezzi/.