Serie Binance API Pt. I – Spot trading con Postman

Introduzione

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.

Prerequisiti

Chiavi testnet

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.

1. Inizia visitando lo Spot Test Network.
2. Per accedere, dovrai loggare con un account GitHub. Creane uno se non lo possiedi ancora.
3. Clicca su Authenticate e accedi via GitHub.
4. Sotto API Keys, ti verrà comunicato che non hai chiavi registrate. Clicca su Generate HMAC_SHA256 Key per creare una coppia.
5. Nella schermata successiva, assegna un'etichetta alle chiavi. Chiamale come preferisci e clicca su Generate. 
6. Compariranno due chiavi: la API Key e la Secret Key. A questo punto è importante annotarle. Se non lo fai, dovrai ripetere il processo di creazione delle chiavi. Consigliamo di conservarle nell'app per le note del tuo dispositivo per facilitare il copia-incolla più avanti.

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.

Scaricare e installare Postman

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.

Creare l'ambiente

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. 

1. Seleziona Import e naviga alla cartella in cui hai estratto (binance-postman-api). 
2. Entraci, quindi entra nella cartella environments.
3. Ora vedrai due file (uno per il mainnet e uno per il testnet). Quello che stiamo cercando è binance_com_spot_testnet_api.postman_environment.json. Assicurati di usare quello giusto, perché le nostre chiavi non funzioneranno con l'altro.

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.

Importare la collezione

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:

1. Clicca su Import nell'angolo in alto a sinistra.
2. Nel popup, sotto la scheda File, seleziona Upload Files.
3. Stiamo cercando di nuovo la cartella binance-postman-api. Trovala e aprila.
4. Questa volta, entra nella cartella collections.
5. Anche qui ci sono due file. Uno per lavorare con l'API futures, ma noi stiamo lavorando con quello spot, quindi selezioneremo il file binance_spot_api_v1.postman_collection.json.
6. Ora dovresti vedere una schermata di conferma che identifica l'import come un formato Postman Collection. Seleziona Import.

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.

Effettuare richieste

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:

• GET: Il metodo GET si usa per ottenere cose da un server. Lo utilizzeremo per scoprire informazioni sul saldo del conto, sui prezzi degli asset, ecc.
• POST: In genere, useremo il metodo POST per creare informazioni su un server. E' necessario per operazioni come piazzare ordini, richiedere prelievi, ecc.
• DELETE: Il metodo DELETE è una richiesta al server per cancellare informazioni. Tornerà utile per cancellare gli ordini.

Trova la lista dei simboli e le regole di trading

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.

Controllare i saldi dell'account

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)!

Come ottenere il prezzo attuale per un simbolo

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.

Controllare l'attuale profondità dell'order book

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. 

Effettuare un ordine di prova

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:

• symbol – abbiamo già trovato questo parametro prima. Questa è la coppia in cui vogliamo fare trading.
• side – qui, puoi decidere se vuoi comprare, con BUY, o vendere, con SELL. Nella coppia BTCUSDT, BUY indica che vuoi comprare BTC per USDT, mentre SELL venderà BTC per USDT.
• type – il tipo di ordine che vuoi eseguire. Possibili valore (dettagliati qui):
  • LIMIT
  • MARKET
  • STOP_LOSS
  • STOP_LOSS_LIMIT
  • TAKE_PROFIT
  • TAKE_PROFIT_LIMIT
  • LIMIT_MAKER
• timeInForce– questo parametro esprime le modalità in cui vuoi eseguire l'ordine:
  • GTC (good till canceled) – probabilmente la configurazione più popolare, GTC assicura che il tuo ordine resta valido finché non viene riempito, o finché non lo cancelli.
  • FOK (fill or kill) – FOK indica all'exchange di eseguire un ordine tutto insieme. Se l'exchange non può farlo, l'ordine viene immediatamente cancellato.
  • IOC (immediate or cancel) – l'ordine deve essere eseguito immediatamente del tutto o in parte, altrimenti viene cancellato. A differenza di FOK, gli ordini non vengono cancellati se sono riempiti parzialmente.
• quantity – semplicemente, la quantità dell'asset che vuoi comprare o vendere.
• price – il prezzo a cui vuoi vendere. Per la coppia BTCUSDT, questo si esprime in USDT.
• newClientOrderId – un identificatore per l'ordine. Non è un campo obbligatorio, ma puoi configurarlo con un'etichetta che renderà più facile trovarlo in seguito. Altrimenti, viene generato casualmente dall'exchange.

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. 

Effettuare un ordine reale

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. 

Controllare lo status di un ordine aperto

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.

Cancellare un ordine

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.

Effettuare un ordine che si riempie istantaneamente

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.

Controllare le tue operazioni

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ù.

Debugging con Postman

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.

In chiusura

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.