Convenzioni dell'API
Regole valide per tutti gli endpoint: struttura degli URL, envelope della risposta, simboli, unità, timestamp, paginazione e cache.
URL di base e versionamento
Tutti gli endpoint si trovano sotto un unico URL di base e si chiamano con HTTPS GET. I percorsi attuali corrispondono alla versione v1. All'interno della v1 le modifiche sono additive: possono essere aggiunti campi ed endpoint, mentre i campi esistenti mantengono nome, tipo e significato. Una modifica incompatibile verrebbe rilasciata sotto un nuovo percorso e annunciata prima nel registro delle modifiche.
URL di base
https://www.coinboss.com/apiEnvelope della risposta
Ogni risposta JSON ha un flag success al livello principale. Gli endpoint del livello dati raccolto in proprio (percorsi sotto /api/sd) condividono gli stessi blocchi aggiuntivi:
| Campo | Descrizione |
|---|---|
| success | true quando la chiamata è riuscita. Va sempre controllato. |
| schema | Identificativo e versione principale della struttura della risposta. |
| now | Ora del server al momento in cui la risposta è stata composta, in millisecondi. |
| coverage | Quali exchange sono inclusi, quali non sono disponibili e perché, e quali sono stati esclusi perché obsoleti. |
| method | La formula o la regola alla base di ogni aggregato della risposta. |
| meta | Fonti, timestamp, finestra, grado di qualità, flag di obsolescenza, durata della cache e comportamento di ripiego. |
Gli endpoint meno recenti restituiscono success più un campo data e possono non includere coverage, method o meta. Le relative pagine di riferimento documentano i campi esatti.
Monete, contratti ed exchange
- I parametri coin accettano il simbolo di base in maiuscolo, per esempio BTC o PEPE.
- I contratti con moltiplicatore, come 1000PEPE o kPEPE, vengono accorpati alla moneta di base, con conversione delle quantità.
- Gli identificativi degli exchange sono in minuscolo, per esempio binance, okx, bybit, hyperliquid.
- I simboli dei contratti sono restituiti così come li denomina l'exchange. Dove un endpoint li riunisce, i contratti con margine in USDT, USDC e coin e i futures a scadenza si distinguono tramite un campo con il tipo di contratto.
- I contratti perpetui su azioni tokenizzate e materie prime che condividono il ticker con un asset crypto sono esclusi dagli aggregati crypto.
Unità
- I campi che terminano in _usd esprimono un valore nozionale in dollari statunitensi.
- I tassi di finanziamento sono frazioni, non percentuali: 0.0001 equivale a 0.01%. I campi che terminano in _8h sono normalizzati a un intervallo di 8 ore; l'intervallo originale è restituito accanto al tasso grezzo.
- I campi che terminano in _pct sono percentuali: 1.5 equivale a 1.5%.
- L'open interest è il valore nozionale unilaterale in USD, salvo diversa indicazione nella descrizione del campo. Gli exchange che pubblicano valori bilaterali sono segnalati nel blocco method.
- Alcuni endpoint legacy restituiscono i decimali come stringhe per preservarne la precisione. La tabella dei campi indica il tipo come string(decimal).
Timestamp
- I timestamp sono in millisecondi dall'epoca Unix, in UTC, salvo diversa indicazione nella descrizione del campo.
- observed_at è il timestamp dell'exchange relativo al record più recente incluso, oppure null quando l'exchange non lo fornisce.
- received_at è il momento in cui il collector di CoinBoss ha archiviato quel record.
- fetched_at è il momento in cui la risposta è stata composta. In una risposta servita dalla cache precede l'ora della chiamata di un intervallo che può arrivare al TTL della cache.
- Le serie giornaliere usano i confini di giornata UTC.
Finestre e intervalli
- I parametri di finestra usano token brevi: 1h, 4h, 12h, 24h e, su alcuni endpoint, 3d, 7d, 30d, 90d. La pagina di riferimento elenca i valori accettati da ciascun endpoint.
- Un valore di finestra sconosciuto viene rifiutato con INVALID_PARAM oppure sostituito dal valore predefinito documentato, come indicato per ciascun parametro.
- La dimensione dei bucket delle serie temporali dipende dalla finestra ed è indicata nella pagina di riferimento.
Paginazione e ordinamento
- Gli endpoint di elenco usano limit e offset, oppure page e size, come documentato per ciascun endpoint. I limiti hanno un tetto massimo; un valore superiore viene ridotto al tetto.
- Quando una risposta include total, questo indica il numero di righe prima della paginazione.
- L'ordinamento è fisso, a meno che l'endpoint non documenti un parametro di ordinamento.
Null, zero e valori assenti
- null significa che il valore è sconosciuto o non disponibile. 0 indica uno zero misurato.
- Nei grafici un null va rappresentato come un'interruzione. Non interpolare.
- Un campo contrassegnato come «può essere assente» in una tabella dei campi può mancare del tutto dall'oggetto; va trattato come null.
Cache
- Ogni endpoint ha un TTL della cache del server, indicato nella relativa pagina di riferimento e in meta.cache_ttl_s. L'header X-Cache riporta HIT, STALE o MISS.
- Davanti alla maggior parte degli endpoint GET c'è una cache edge di breve durata, di circa dieci secondi.
- Un polling più frequente del TTL restituisce dati identici e non fa che consumare il limite di richieste.
WebSocket
WebSocket
wss://www.coinboss.com/ws- Il flusso è JSON in sola modalità push. Ogni messaggio ha un campo type.
- Dopo una disconnessione, riconnettersi dopo un'attesa e recuperare i dati mancanti dall'endpoint HTTP corrispondente.
Documentazione leggibile dalle macchine
Il catalogo, i parametri e la tabella dei campi di ogni endpoint, lo stato e la matrice della qualità sono disponibili in JSON sotto /api/meta, e l'intero catalogo come documento OpenAPI 3.