Comprendere e utilizzare un'API per il trading di criptovalute può offrire una marea di opportunità per entrare e uscire da posizioni. Con qualche semplice conoscenza in ambito di programmazione, puoi collegarti al backend di un exchange e automatizzare le tue strategie di trading. Aggirando il sito web, puoi prendere una strada molto più veloce verso il motore di abbinamento per applicazioni ad alte prestazioni.
L'obiettivo di questa serie è quello di introdurti alla REST API di Binance e insegnarti come interagire con essa. Raggiunta la conclusione della serie, dovresti essere sicuro delle tue abilità nel richiedere informazioni sui mercati e sulla tua posizione e nel piazzare una serie di tipologie di ordini differenti.
In questo articolo, utilizzeremo Postman per comunicare con l'exchange. Non preoccuparti – non metteremo a rischio fondi reali.
Per i nostri scopi, utilizzeremo il testnet. Questo ci permetterà di giocare con dei fondi senza alcun valore reale. Funzionano nello stesso modo delle monete e token reali, quindi una volta che ti senti a tuo agio con l'API, puoi iniziare a usarlo per il trading di fondi reali.
Nota: assegnare un'etichetta alle tue chiavi è utile quando usi l'exchange reale per gestire diverse chiavi. Il tuo account può avere più chiavi con diversi permessi. Se utilizzi diversi trading bot, usare chiavi separate con etichette descrittive facilita la gestione dei permessi o l'eliminazione di chiavi individuali senza dover modificare tutti i tuoi bot.
Postman è una piattaforma di Collaborazione API. E' un punto di partenza perfetto per noi – otterremo l'accesso a collezioni di richieste Binance che andremo a testare senza dover scrivere una singola linea di codice.
Il programma è disponibile per Mac, Windows e Linux. Visita la pagina Download e scarica il file .zip.
Al termine del download, trova il file nel tuo dispositivo e installalo. Esegui l'applicazione, e siamo pronti a iniziare! Ricorda che puoi creare un account per accedere, ma non è necessario. Se vuoi saltare questo passaggio, basta selezionare l'opzione per farlo nella parte inferiore della finestra.
A questo punto, dovresti vedere un interfaccia che assomiglia a questo.
Vogliamo prima di tutto creare il nostro ambiente. E' semplicemente un modo per aggiungere variabili all'insieme di richieste con cui lavoreremo. Per farlo, dovremo recuperare delle informazioni dalla repository GitHub di Binance. Segui questo link e scarica il file .zip.
Il download non dovrebbe richiedere molto tempo. Trova il file nel tuo explorer e aprilo. Dopodiché, possiamo tornare in Postman.
Clicca sull'icona ingranaggio nell'angolo in alto a destra (illustrata sopra). Troverai il popup Manage Environments.
Quasi finito. Clicca su Binance Spot Testnet API, e vedrai le variabili. Modifica i due parametri indicati in rosso incollando le chiavi che hai salvato prima. Clicca su Update ed esci dal popup.
Su questa schermata, lascia vuoti i campi timestamp e signature. Questi due valori verranno creati automaticamente per ogni richiesta.
Resta un'ultima cosa da fare. A destra dell'icona ingranaggio che abbiamo cliccato per impostare l'ambiente, vedrai un menù a cacata che attualmente dice No Environment. Cliccalo e seleziona Binance Spot Testnet API.
Ora andremo a importare la collezione – si tratta di un grande assortimento di richieste che si occupano del lavoro pesante per noi. Per caricarla nel nostro ambiente:
Nella scheda Collections a sinistra della finestra, vedrai ora una cartella con più di 100 richieste. Congratulazioni! Siamo pronti a iniziare. Nella prossima sezione, daremo un'occhiata alle tipologie di richieste che possiamo effettuare.
Se espandi le cartelle sotto la scheda Collections, vedrai che ci sono un sacco di richieste differenti che possiamo effettuare. Dal codice a colori, potresti notare che esistono tre tipi di metodi che possiamo usare:
E' il momento della nostra prima richiesta! L'obiettivo è quello di ottenere una lista dei simboli che possiamo scambiare sull'exchange e le regole di trading:
GET /exchangeInfo
Questa non richiede nessun parametro aggiuntivo – potresti copiare e incollare questo comando nella tua barra degli indirizzi e otterresti una risposta. Invece, per le richieste in cui includiamo diversi parametri, Postman rende facile vederli e modificarli.
Per caricare questa richiesta, seleziona Market > Exchange Information. Apparirà una scheda come la seguente:
Non dobbiamo fare altro qui, quindi vai avanti e clicca su Send. A questo punto riceverai una risposta:
Nella sezione evidenziata più alta, vedrai alcune informazioni importanti:
lo status della risposta (200 significa che ha avuto successo, 400-499 significa che si è verificato un problema)
il tempo necessario per ricevere la risposta (meno di un secondo)
le dimensioni della risposta (~22KB).
Nel secondo riquadro evidenziato troviamo il grosso della risposta. E' stato colorato e semplificato per renderlo più comprensibile. Questa sezione contiene informazioni sull'exchange stesso, oltre alle coppie in cui puoi fare trading e gli importi minimi/massimi.
Sembrano molte informazioni, ma il formato rende molto facili lavorarci programmaticamente. Quando scrivi script per interagirci, potrai selezionare facilmente proprietà specifiche di elementi specifici dalla risposta.
Controlliamo quali asset abbiamo, e quanto di ciascuno:
GET /account
Questa richiesta è disponibile sotto Trade > Account Information. Cliccala, e vedrai un layout simile alla precedente. Noterai anche che ci sono due nuove variabili: timestamp e signature. La signature è una misura di sicurezza. Dato che ora stiamo richiedendo informazioni sensibili, la signature dimostrerà che siamo davvero i titolari del conto.
Il timestamp comunica al server quando la richiesta è stata inviata. Considerando che i network possono essere inaffidabili o inattivi, il server potrebbe ricevere la nostra richiesta molto più tardi di quanto previsto. Se è passato troppo tempo, respingerà la richiesta. Puoi specificare quanto tempo vuoi aspettare con il parametro recvWindow, fissato di default a 5000 millisecondi.
Postman gestisce la generazione di entrambi i campi per noi. Clicca su Send e riceverai una risposta. Sotto i saldi, dovresti vedere sei asset – BNB, BTC, BUSD, ETH, LTC e TRX. Il saldo sarà diviso tra free e locked. Non abbiamo ancora bloccato niente, quindi i tuoi asset dovrebbero essere tutti liberi.
Congratulazioni per la tua nuova ricchezza (inesistente)!
Possiamo ottenere il prezzo attuale di un asset in vari modi. Forse il più semplice è attraverso la seguente richiesta:
GET /api/v3/ticker/24hr
Come potresti aver capito, questo ci darà le informazioni relative ai prezzi dell'asset nelle ultime ventiquattro ore. Puoi trovare la richiesta in Market > 24hr Ticker Price Change Statistics. La coppia di default che ci viene mostrata come variabile del simbolo è BTCUSDT.
Puoi inviare la richiesta direttamente per ottenere un'analisi delle informazioni di prezzo. Puoi anche cambiare il simbolo (a BNBBUSD, LTCUSDT, ecc.), oppure puoi deselezionare la variabile per ottenere i dati su 40 coppie.
Abbiamo anche una call più semplice (Market > Symbol Price Ticker) che restituisce il prezzo di scambio attuale per un asset:
GET /api/v3/price
Come per la precedente, puoi cambiare la variabile del simbolo o rimuoverla completamente per ottenere i prezzi di tutti i simboli.
La profondità dell'order book (chiamata anche profondità di mercato, o DOM) può dirci molto sul mercato. Eseguiremo una richiesta che restituirà alcune informazioni utili:
GET api/v3/depth
Quando inviamo questa richiesta con i valori di default (Market > Order Book), riceviamo una risposta che ci informa sugli ordini di acquisto e di vendita per BTCUSDT. Il server testnet non fornirà molti dati in confronto a quello vero, quindi qui sotto trovi uno screenshot di ciò che puoi aspettarti in un contesto reale:
Nella sezione evidenziata sopra, possiamo vedere la prima offerta. Dato che stiamo esaminando l'order book di BTCUSDT, il numero superiore è il prezzo che qualcuno è disposto a pagare per i tuoi BTC. Sotto, invece, troviamo la quantità che è disposto a comprare. Quindi, la richiesta ci informa che questo ordine sta chiedendo 0,999 BTC a un prezzo di 9704,65 USDT per BTC. Se continuiamo a scorrere verso il basso, vedremo che il prezzo d'offerta diminuisce – quindi gli acquirenti sono disposti a pagare di meno.
L'offerta superiore sarà naturalmente la più vantaggiosa per chi vuole ricavare un profitto. Detto ciò, se stai cercando di vendere, diciamo, 3 BTC con un ordine market, riuscirai a vendere solo 0,999 BTC al prezzo migliore. Dovrai poi accettare le offerte successive (più basse) fino a quando l'intero ordine viene riempito.
Continuando a scendere troverai gli ordini di vendita. Funzionalmente sono simili a quelli di acquisto, ma rappresentano ordini per vendere BTC in cambio di USDT.
Vediamo come effettuare un ordine di prova.
POST api/v3/order/test
Anche se stiamo usando fondi del testnet, in realtà questa richiesta non piazzerà un ordine. Può essere utile per testare gli ordini prima di effettuarli davvero. Puoi trovarla in Trade > Test New Order (TRADE).
Puoi vedere che ci sono molti più parametri coinvolti. Esaminiamo quelli attivi:
Ok! Creiamo un ordine di prova. Utilizzeremo i valori generati automaticamente: un ordine limit per vendere 0,1 BTC per USDT a 9000$. Clicca su Send. Se l'ordine ha avuto successo, riceverai semplicemente un {} come risposta.
E' ora di effettuare un vero ordine finto.
POST /api/v3/order
Naviga su Trade > New Order. Conosci già gli ordini di prova, quindi i parametri di questa nuova richiesta ti sono familiari. Lasciamo tutti i valori come sono, ma dato che siamo permabull, cambieremo il prezzo di vendita a 40.000$. Modifica il parametro price per riflettere questo cambiamento. Quindi, clicca su Send.
Se ha successo, la tua risposta restituisce una serie di dettagli sull'ordine.
Nella sezione precedente, abbiamo ricevuto la conferma che l'ordine è stato piazzato, ma come facciamo a controllarlo di nuovo più tardi? Abbiamo diverse richieste a disposizione.
GET /api/v3/openOrders
Puoi trovarla in Trade > Current Open Orders (USER_DATA). BTCUSDT è selezionato di default. Cliccando su Send, riceverai una lista dei tuoi ordini aperti su BTCUSDT (finora dovresti vedere solo quello che abbiamo creato prima). Puoi scegliere di non specificare un simbolo, per ricevere una lista di tutti i tuoi ordini aperti.
GET /api/v3/allOrders
Trade > All Orders (USER_DATA) offre una panoramica su tutti gli ordini – non solo quelli aperti. Qui, devi fornire un simbolo. orderId, startTime, endTime e limit sono parametri opzionali che possono aiutarti a restringere la ricerca. In questo caso li lasceremo fuori, quindi puoi disattivarli. Clicca su Send e vedrai la stessa risposta di prima. Se avessi degli ordini chiusi o cancellati, vedresti anche quelli.
Infine, possiamo cercare ordini specifici con:
GET /api/v3/order
Trovi questa richiesta in Trade > Query Order (USER_DATA). Dovrai fornire l'orderId o l'origClientOrderId (l'etichetta opzionale “newClientOrderId” che puoi aggiungere agli ordini). Disattiva orderId. Per origClientOrderId, inseriremo la tag di default appartenente all'ordine di prima – ”my_order_id_1”. Compila il campo e clicca su Send per ottenere la risposta.
Dopo un po', potremmo decidere che l'obiettivo di 40.000$ è troppo ottimista, quindi vogliamo cancellarlo. In questo caso, useremmo:
DELETE /api/v3/order
In Trade > Cancel Order troviamo una richiesta che ci permette di selezionare gli ordini da cancellare. Disattiva orderId e newClientOrderId e inserisci “my_order_id_1” come valore di origClientOrderId.
Quando invii questa richiesta, verrà restituito l'ordine. Se scrolli verso il basso per trovare “status”, vedrai che è stato cancellato. Per confermarlo, usa di nuovo la richiesta GET /api/v3/openOrders (che restituirà una lista vuota) o GET /api/v3/order con l'origClientOrderId.
Il nostro ordine precedente non è stato riempito perché era un ordine limit che si sarebbe attivato solo se il prezzo di BTC avesse raggiunto 40.000$. Con un ordine market, stiamo praticamente dicendo “compra/vendi a qualsiasi prezzo si trovi l'asset al momento”. Questo tipo di ordine verrà riempito all'istante.
Quindi, torniamo in Trade > New Order. Andremo a dimostrare il tipo di risposta (newOrderRespType), un parametro che possiamo regolare in base alla risposta che vogliamo ricevere dal server. Ci sono tre opzioni in questo caso:ACK, RESULT o FULL – puoi vedere esempi di ciascuna risposta qui. Adesso utilizzeremo ACK, che fornirà una semplice conferma di ricezione dell'ordine.
Qui sotto, puoi vedere che stiamo per inviare un ordine market per vendere BNB in cambio di BUSD al prezzo di mercato attuale.
Nota che la risposta ci fornisce informazioni minime:
Puoi verificare che l'ordine è stato riempito con l'endpoint /api/v3/allOrders.
Per concludere, diamo un'occhiata all'endpoint per controllare le operazioni:
GET /api/v3/myTrades
Questa richiesta si trova in Trade > Account Trade List (USER_DATA). Ci permette di controllare ogni operazione per un particolare simbolo. Se vuoi vedere tutte le tue operazioni per il simbolo di default (BTCUSDT), basta disattivare startTime, endTime e fromId. La risposta restituirà fino a 500 operazioni – puoi regolare il parametro limit per vederne di più.
In Postman, è possibile analizzare il codice HTTP grezzo di richieste e risposte.
Questo menu aprirà la console di Postman, che mostra i dettagli di ogni richiesta.
Lo scopo di questa guida era quello di introdurti gentilmente alla API di Binance senza scrivere una singola linea di codice. Se hai seguito le istruzioni, ora dovresti avere un'idea di come possiamo richiedere e inviare informazioni.
Nelle prossime parti di questa serie, introdurremo alcuni concetti di programmazione elementari che ci permettono di automatizzare l'acquisto e la vendita di criptovalute e altri asset digitali.
Hai delle domande? Visita il nostro crescente forum Binance Developer Community, oppure dai un'occhiata alla documentazione.