Documentazione API



Cosa sono le API

Le API di Bitgrail consentono ai propri clienti di accedere e controllare i propri account grazie a software di terze parti. Sono disponibili le API websocket, e le API GET/POST sia per le chiamate pubbliche che per le chiamate private (relative all'account dell'utente).

Attualmente, la versione stabile e disponibile è la v1.

Limiti per le richieste

Non si dovrebbero fare oltre le 60 chiamate al minuto o potremmo momentaneamente bannare il vostro indirizzi IP.
Per le API in tempo reale è sempre preferibile utilizzare il websocket.

Esempi

Di seguito riportiamo alcuni script che sono stati realizzati per interagire con le API di BitGrail.

API [Websocket] Pubbliche

API Push

Esempio https://bitgrail.com/api/v1/websocket.html

Attraverso il server websocket wss://api.bitgrail.com è possibile iscriversi ai canali dei vari market (es. BTC-XRB) e così ottenere:

Un array contenente l'order book delle offerte

  • price - Il prezzo offerto per ogni singola coin
  • amount - Il totale delle coin richieste

Un array contenente l'order book delle richieste

  • price - Il prezzo richiesto per ogni singola coin
  • amount - Il totale delle coin offerte

Un array contenente gli ultimi scambi effettuati

  • date - La data dello scambio
  • price - Il prezzo per singola coin dello scambio
  • amount - Il totale delle coin scambiate

API [GET] Pubbliche

Mercati

GET https://bitgrail.com/api/v1/markets

Restituisce un JSON con un array dei tickers dei vari mercati disponibili su BitGrail:

  • Market
    • last - Ultimo prezzo di scambio
    • high - Prezzo di scambio più alto nelle ultime 24 ore
    • low - Prezzo di scambio più basso nelle ultime 24 ore
    • volume - Volume di scambio delle ultime 24 ore
    • coinVolume - Importo di coin scambiato nelle ultime 24 ore
    • bid - Offerta più alta attualmente
    • ask - Richiesta più bassa attualmente

Ticker

GET https://bitgrail.com/api/v1/$FIAT-$COIN/ticker

Restituisce un JSON con:

  • last - Ultimo prezzo di scambio
  • high - Prezzo di scambio più alto nelle ultime 24 ore
  • low - Prezzo di scambio più basso nelle ultime 24 ore
  • volume - Volume di scambio delle ultime 24 ore
  • coinVolume - Importo di coin scambiato nelle ultime 24 ore
  • bid - Offerta più alta attualmente
  • ask - Richiesta più bassa attualmente

Order book

GET https://bitgrail.com/api/v1/$FIAT-$COIN/orderbook

Restituisce un JSON composto da due array:

Un array contenente l'order book delle offerte formato da

  • price - Il prezzo offerto per ogni singola coin
  • amount - Il totale delle coin richieste

Un array contenente l'order book delle richieste formato da

  • price - Il prezzo richiesto per ogni singola coin
  • amount - Il totale delle coin offerte

Storico trade

GET https://bitgrail.com/api/v1/$FIAT-$COIN/tradehistory

Restituisce un JSON con un array delle ultime 500 transazioni così composto:

  • date - La data dello scambio
  • price - Il prezzo per singola coin dello scambio
  • amount - Il totale delle coin scambiate

API [POST] Private

Autenticazione

Per poter utilizzare le API private, è cenessario creare una coppia di chiavi per effettuare l'autenticazione dell'utente.

Tutte le chiamate private devono essere composte da una chiamata HTTP POST, contenente le due headers seguenti:

  • KEY - L'API Key pubblica
  • SIGNATURE - I parametri POST criptati tramite l'algoritmo HMAC-SHA512 con la vostra API Key segreta

Le chiamate private, inoltre, hanno tutte bisogno di un ulteriore parametro POST aggiuntivo, il nonce

  • nonce - Un numero intero, sempre superiore al nonce della chiamata precedente.

Saldi

POST https://bitgrail.com/api/v1/balances

Per ottenere le balances di tutte le coin presenti su BitGrail non occorrono parametri oltre a quelli per l'autenticazione.

Le chiamate, se effettuata con successo, resituirà un array contenente come indice il codice della coin e i seguenti parametri:

  • balance - La balance a disposizione dell'utente.
  • reserved - La balance attualmente non disponibile (es. bloccata da ordini aperti).

Ordine d'acquisto

POST https://bitgrail.com/api/v1/buyorder

Per creare un ordine d'acquisto sono necessari i seguenti parametri POST.

  • market - (Es. BTC-XRB) Il market dove effettuare l'ordine.
  • amount - Un numero decimale con l'importo totale delle coin che si desidera acquistare.
  • price - Un numero decimale con il prezzo disposto a pagare per singola coin.

La chiamata, se effettuata con successo, resituirà un array contenente:

  • orderId - L'identificativo univoco dell'ordine appena effettuato.

Ordine di vendita

POST https://bitgrail.com/api/v1/sellorder

Per creare un ordine di vendita sono necessari i seguenti parametri POST.

  • market - (Es. BTC-XRB) Il market dove effettuare l'ordine.
  • amount - Un numero decimale con l'importo totale delle coin che si desidera vendere.
  • price - Un numero decimale con il prezzo richiesto per singola coin.

La chiamata, se effettuata con successo, resituirà un array contenente:

  • orderId - L'identificativo univoco dell'ordine appena effettuato.

Ordini aperti

POST https://bitgrail.com/api/v1/openorders

Per ottenere la lista degli ordini aperti effettuati da un utente, non sono necessari parametri aggiuntivi.

In caso di successo, la chiamata resituirà un array contenente come indice il codice l'identificativo univoco dell'ordine e i seguenti parametri:

  • data - Il timestamp in formato unix relativo alla data di creazione dell'ordine.
  • market - Il market per cui l'ordine è stato creato.
  • price - Il prezzo per singola coin dell'ordine.
  • amount - Il totale delle coin relativo all'ordine.
  • type - La tipologia di ordine: "sell" per le vendite, "buy" per gli aquisti.

Cancella ordine

POST https://bitgrail.com/api/v1/cancelorder

Per cancellare un ordine creato in precedenza, è necessario il seguente parametro POST.

  • id - L'identificativo univoco dell'ordine da eliminare.

La chiamata restituirà un messaggio di successo o di errore a seconda del caso


Ottieni indirizzo di deposito

POST https://bitgrail.com/api/v1/getdepositaddress

Per ottenere un indirizzo di deposito, è necessario il seguente parametro POST.

  • coin - La coin per la quale si desidera ottenere l'indirizzo di deposito.

La chiamata restituirà un messaggio contenente l'address in caso di successo o un messaggio di errore in caso di fallimento:


Preleva

POST https://bitgrail.com/api/v1/withdraw

Per emettere una richiesta di prelievo, sono necessari i seguenti parametri POST.

  • coin - La cui per la quale si desidere emettere una richiesta di prelievo.
  • amount - L'importo da prelevare.
  • address - L'indirizzo nel quale ricevere l'importo da prelevare.

La chiamata restituirà un messaggio di successo o di errore a seconda del caso


Ultime transazioni

POST https://bitgrail.com/api/v1/lasttrades

Per ottenere la lista degli ultimi trade effettuati da un utente, non sono necessari parametri aggiuntivi.

In caso di successo, la chiamata resituirà un array contenente come indice il codice l'identificativo univoco del trade ed i seguenti parametri:

  • data - Il timestamp in formato unix relativo alla data di trade.
  • market - Il market per cui l'ordine è stato creato.
  • price - Il prezzo per singola coin dell'ordine.
  • amount - Il totale delle coin relativo all'ordine.
  • type - La tipologia di ordine: "sell" per le vendite, "buy" per gli aquisti.

Storico depositi

POST https://bitgrail.com/api/v1/depositshistory

Per ottenere la lista dei depositi effettuati da un utente, è necessario il seguente parametro POST.

  • coin - La coin per la quale si desidera ottenere la lista dei depositi.

La chiamata restituirà, in caso di successo, un array contenente come indice l'id della transazione del deposito ed i seguenti parametri:

  • data - Il timestamp in formato unix relativo alla data di deposito.
  • amount - L'importo depositato.
  • status - Lo stato del deposito.

Storico prelievi

POST https://bitgrail.com/api/v1/withdrawshistory

Per ottenere la lista dei prelievi effettuati da un utente, è necessario il seguente parametro POST.

  • coin - La coin per la quale si desidera ottenere la lista dei prelievi.

La chiamata restituirà, in caso di successo, un array contenente come indice l'id della transazione del prelievo ed i seguenti parametri:

  • data - Il timestamp in formato unix relativo alla data di prelievo.
  • amount - L'importo prelevato.
  • status - Lo stato del prelievo.