Seria Binance API Część I - Handel Spot z Postman

Spis Treści

• Wprowadzenie
• Wymagania wstępne
  • Klucze testnet'u
  • Pobieranie i instalacja Postman
• Tworzenie środowiska
• Importowanie kolekcji
• Składanie żądań
• Przemyślenia końcowe

Wprowadzenie

Zrozumienie i używanie interfejsu API do handlu kryptowalutami może otworzyć wiele możliwości, jeśli chodzi o wchodzenie i wychodzenie z pozycji. Dzięki prostej wiedzy na temat kodowania możesz podłączyć się do zaplecza giełdy, aby zautomatyzować swoje strategie handlowe. Pomijając stronę internetową, jesteś w stanie zastosować znacznie szybszą ścieżkę do odpowiedniego silnika dla aplikacji o wysokiej wydajności.

Celem tej serii jest zapoznanie z interfejsem API REST Binance i nauczenie, jak z niego korzystać. Na końcu powinieneś mieć pewność, że potrafisz sprawnie zbierać informacje na temat rynków i swojej pozycji oraz posiadać umiejętność złożenia szeregu różnych rodzajów zleceń.

W tym artykule będziemy używać Postman do komunikacji z giełdą. Nie martw się - nie będziemy narażać żadnych prawdziwych funduszy.

Wymagania wstępne

Klucze testnet'u

Użyjemy sieci testowej do naszych celów. Pozwoli nam to na wykorzystanie funduszy bez realnej wartości do zabawy. Działają one dokładnie tak samo, jak prawdziwe monety i tokeny, więc gdy już poczujesz się pewnie z interfejsem API, możesz zacząć używać prawdziwego kapitału.

1. Zacznij od przejścia do Sieci Testowej Spot.
2. Aby uzyskać dostęp, musisz zalogować się na konto GitHub. Jeśli nie posiadasz takowego, stwórz je.
3. Kliknij opcję Uwierzytelnij i zaloguj się przez GitHub.
4. W obszarze Kluczy API zobaczysz informację, że nie masz zarejestrowanych kluczy. Kliknij przycisk Generuj HMAC_SHA256, aby utworzyć parę.
5. Na następnym ekranie nadaj klawiszom etykietę. Nazwij je, jak chcesz i naciśnij Generuj. 
6. Otrzymasz dwa klucze: Klucz API i Klucz Tajny. Ważne jest, aby je teraz zapisać. Jeśli tego nie zrobisz, musisz ponownie rozpocząć proces tworzenia klucza. Zalecamy przechowywanie ich w notatniku na komputerze w celu późniejszego łatwego wklejenia.

Uwaga: etykietowanie kluczy jest czymś, co warto zrobić, gdy używasz prawdziwej giełdy w celu zarządzania różnymi kluczami. Twoje konto może mieć wiele kluczy z różnymi uprawnieniami. Jeśli korzystasz z kilku botów handlowych, użycie osobnych kluczy z opisowymi etykietami ułatwia zarządzanie uprawnieniami lub usuwanie poszczególnych kluczy bez zmiany wszystkich swoich botów.

Pobieranie i instalacja Postman

Postman to platforma Współpracy API. To dla nas idealny punkt wyjścia - będziemy mieli dostęp do kolekcji żądań Binance, które przetestujemy bez konieczności pisania kodu.

Program jest dostępny dla systemów operacyjnych Mac, Windows i Linux. Przejdź na stronę Pobieranie i pobierz plik .zip.

Po zakończeniu pobierania znajdź go w eksploratorze plików i zainstaluj. Uruchom aplikację i jesteśmy gotowi! Pamiętaj, że możesz utworzyć konto, aby się zalogować, ale nie jest to konieczne. Jeśli chcesz pominąć ten krok, po prostu wybierz opcję w dolnej części okna.

Tworzenie środowiska

Na tym etapie powinieneś mieć interfejs podobny do następującego.

Chcemy najpierw stworzyć nasze środowisko. To tylko sposób na dodanie zmiennych do zestawu żądań, z którymi będziemy pracować. Aby to zrobić, najpierw musimy pobrać informacje z repozytorium Binance GitHub. Przejdź tutaj i pobierz plik .zip.

Pobieranie nie powinno zająć bardzo długo. Znajdź plik w eksploratorze plików i rozpakuj. Następnie możemy wrócić do Postman.

Kliknij ikonę koła zębatego w prawym górnym rogu (jak pokazano powyżej). Zostaniesz powitany przez okienko Zarządzaj Środowiskami. 

1. Wybierz Importuj i przejdź do właśnie wypakowanego folderu (binance-postman-api). 
2. Wejdź w niego, a następnie przejdź do folderu środowisk.
3. Zobaczysz teraz dwa pliki (jeden dla sieci głównej i jeden dla sieci testowej). Tym, którego szukamy, jest binance_com_spot_testnet_api.postman_environment.json. Upewnij się, że masz właściwy, ponieważ nasze klucze nie będą działać z tym drugim.

Jesteśmy już prawie na miejscu. Kliknij Binance Spot Testnet API, a zobaczysz zmienne pokazane poniżej. Edytuj dwa parametry zaznaczone na czerwono, wklejając wcześniej zapisane klucze. Kliknij aktualizuj i wyjdź z tego okienka.

Na tym ekranie pozostaw pola sygnatury czasowej i podpisu puste. Te dwie wartości zostaną automatycznie utworzone dla każdego żądania.

Jest jeszcze jedna rzecz do zrobienia. Po prawej stronie ikony koła zębatego kliknęliśmy, aby skonfigurować środowisko. Zobaczysz tam teraz menu z napisem Brak Środowiska. Kliknij i wybierz Binance Spot Testnet API.

Importowanie kolekcji

Teraz zaimportujemy kolekcję - jest to obszerny asortyment żądań, które robią dla nas ciężką pracę, gdy wykonujemy call'e. Aby załadować je do naszego środowiska:

1. Kliknij Importuj w lewym górnym rogu.
2. W wyskakującym okienku w karcie Plik wybierz Prześlij Pliki.
3. Po raz kolejny szukamy folderu binance-postman-api. Znajdź go i otwórz.
4. Tym razem wprowadź kolekcje do podkatalogu.
5. Ponownie są tutaj dwa pliki. Jeden z nich współpracuje z interfejsem API futures. Natomiast my chcemy pracować z tym "spot", więc musisz wybrać plik binance_spot_api_v1.postman_collection.json.
6. Powinien zostać wyświetlony ekran potwierdzenia, identyfikujący import w formacie Postman Collection. Wybierz Importuj.

W karcie Kolekcje po lewej stronie okna zauważysz, że mamy folder z ponad 100 żądaniami. Gratulacje! Możemy zaczynać. W następnej sekcji przyjrzymy się rodzajom żądań, które możemy złożyć.

Składanie Żądań

Jeśli rozwiniesz foldery w karcie Kolekcje, zobaczysz, że mamy do czynienia z wieloma różnymi żądaniami. Z kodowania kolorami można zauważyć, że istnieją trzy rodzaje metod, których możemy użyć:

• GET: Metoda GET służy do pobierania danych z serwera. Wykorzystamy ją, aby uzyskać informacje o saldzie konta, cenach aktywów itp.
• POST: Ogólnie używamy metody POST do tworzenia informacji na serwerze. Jest to potrzebne w przypadku składania zleceń, żądań wypłaty itp.
• DELETE: Metoda DELETE to żądanie usunięcia informacji przez serwer. Przyda się do anulowania zleceń.

Znajdź listę symboli i zasady handlu

Czas na nasze pierwsze żądanie! Otrzymamy symbole, którymi możemy handlować na giełdzie, a także zasady handlu:

GET /exchangeInfo

To żądanie nie wymaga żadnych dodatkowych parametrów - możesz je skopiować i wkleić w pasku adresu, dzięki czemu otrzymasz odpowiedź. W przypadku żądań, w których uwzględniamy kilka parametrów, Postman ułatwia ich przeglądanie i modyfikowanie.

Aby załadować to żądanie, wybierz Rynek (Market) > Informacje Giełdowe (Exchange Information). Pojawi się następująca karta:

Nie musimy tutaj nic więcej robić, więc kliknij Wyślij. Otrzymasz wtedy odpowiedź:

W najwyżej podświetlonej sekcji zobaczysz kilka ważnych informacji:

• status odpowiedzi (200 oznacza, że nam się udało, 400-499 oznacza, że napotkaliśmy problem)

• czas potrzebny na odpowiedź (mniej niż sekunda)

• rozmiar odpowiedzi (~22KB).

W drugim polu znajduje się większość odpowiedzi. Sekcja "pretty" jest przyjemniejsza dla oczu. Zawiera informacje o samej giełdzie, a także o parach, którymi możesz handlować oraz o ich minimalnych/maksymalnych kwotach.

Wygląda to na wiele informacji, ale format sprawia, że bardzo łatwo jest z nimi pracować. Podczas pisania skryptów do interakcji, z łatwością będziesz mógł wybrać określone właściwości konkretnych elementów z odpowiedzi.

Sprawdź salda konta

Sprawdźmy, jakie zasoby posiadamy i ile ich jest:

GET /account

Możemy to znaleźć w Handel (Trade) > Informacje o Koncie (Account Information). Kliknij na to, a zobaczysz podobny układ do poprzedniego. Pamiętaj też, że mamy dwie nowe zmienne: znacznik czasu (timestamp) i podpis. Podpis jest środkiem bezpieczeństwa. Ponieważ teraz prosimy o podanie poufnych informacji, udowodnimy, że jesteśmy właścicielem konta. 

Znacznik czasu informuje serwer o wysłaniu żądania. Ponieważ sieci mogą być zawodne lub aktualnie w przestoju, serwer może otrzymać nasze zapytanie znacznie później niż zamierzono. Jeśli minie zbyt wiele czasu, wniosek zostanie odrzucony. Możesz określić czas oczekiwania za pomocą parametru recvWindow, którego domyślna wartość wynosi 5000 milisekund.

Postman obsługuje za nas generowanie obu tych pól. Kliknij wyślij, a otrzymasz odpowiedź. Pod saldami powinieneś zobaczyć sześć aktywów - BNB, BTC, BUSD, ETH, LTC i TRX. Saldo zostanie podzielone na wolne i zablokowane. Nie zablokowaliśmy jeszcze żadnych, więc wszystkie Twoje zasoby powinny być wolne.

Gratulujemy nowo odkrytego (nieistniejącego) bogactwa!

Jak uzyskać aktualną cenę dla symbolu

Możemy zająć się uzyskaniem bieżącej ceny składnika aktywów na różne sposoby. Być może najprostszy, polega na wykonaniu następującego żądania:

GET /api/v3/ticker/24hr

Jak można się domyślać, dostarczy nam to informacji o cenach aktywów z ostatnich dwudziestu czterech godzin. Znajdź to w Rynek (Market) > 24hr Ticker Price Change Statistics. Domyślną parą, witającą nas jako symbol jest BTCUSDT. 

Możesz wysłać to od razu, aby zobaczyć zestawienie informacji o cenie, zmienić symbol (na BNBBUSD, LTCUSDT itp.) lub odznaczyć zmienną, aby otrzymać dane dla 40 par.

Mamy również prostsze rozwiązanie (Rynek (Market) > Symbol Price Ticker), które zwraca bieżącą cenę danego aktywa:

GET /api/v3/price

Podobnie jak w poprzednim przypadku, możesz zmienić zmienną symbolu lub całkowicie ją usunąć i uzyskać najnowszą cenę dla wszystkich symboli.

Sprawdź aktualną głębokość księgi zleceń

Głębokość księgi zleceń (zwana również głębokością rynku lub DOM) może nam wiele powiedzieć o rynku. Wykonamy calla, który zwróci przydatne informacje:

GET api/v3/depth

Gdy wysyłamy to z wartościami domyślnymi (Rynek (Market) > Księga Zleceń (Orderbook)), dostajemy odpowiedź, która mówi nam o bidach i askach na BTCUSDT. Serwer testnet nie dostarczy tylu danych, co rzeczywisty, dlatego poniżej znajduje się zrzut ekranu tego, co można zobaczyć w prawdziwym środowisku:

W podświetlonej sekcji powyżej widzimy pierwszego bida. Ponieważ patrzymy na księgę BTCUSDT, górna liczba to cena, którą ktoś jest skłonny zapłacić za Twoje BTC. Poniżej znajduje się kwota, którą chce kupić. Oznacza to zatem, że zlecenie to prosi (ask) o 0.999 BTC według stawki 9704.65 USDT za BTC. Gdybyśmy nadal przewijali w dół, zaobserwowalibyśmy spadek cen ofert – reprezentujący nabywców, którzy zapłaciliby mniej. 

Najlepsza oferta będzie oczywiście najbardziej atrakcyjna. To powiedziawszy, jeśli próbujesz sprzedać, na przykład, 3 BTC, będziesz w stanie sprzedać tylko 0.999 BTC za najlepszą cenę. Musisz przyjmować kolejne (tańsze) oferty, aż całe zlecenie zostanie zrealizowane.

Przewijaj dalej, a zobaczysz aski. Są funkcjonalnie podobne do bidów, z tym że reprezentują zlecenia sprzedaży BTC za USDT. 

Złóż zlecenie testowe

Teraz opublikujemy zlecenie testowe.

POST api/v3/order/test

Mimo że korzystamy tylko z funduszy testnetu, ta prośba w rzeczywistości nie składa zamówienia. Może się przydać do testowania zleceń przed ich faktycznym wysłaniem. Znajdziesz to w Handel (Trade) > Test New Order (TRADE).

Widać tutaj, że mamy do czynienia z wieloma parametrami. Przejdźmy przez te zaznaczone:

• symbol - natknęliśmy się na to wcześniej. To jest para, którą chcesz handlować.
• side - tutaj określ, czy chcesz KUPIĆ (BUY), czy SPRZEDAĆ (SELL). W przypadku pary BTCUSDT BUY wskazuje, że chcesz kupić BTC za USDT, natomiast SELL, że sprzedawać BTC za USDT.
• type – rodzaj zlecenia, które chcesz złożyć. Możliwe wartości (wyszczególnione tutaj):
  • LIMIT
  • MARKET
  • STOP_LOSS
  • STOP_LOSS_LIMIT
  • TAKE_PROFIT
  • TAKE_PROFIT_LIMIT
  • LIMIT_MAKER
• timeInForce- ten parametr wyraża sposób wykonania zlecenia:
  • GTC (ważne do anulowania) - być może najpopularniejsza konfiguracja, GTC upewni się, że Twoje zlecenie jest ważne, dopóki nie zostanie spełnione lub do momentu anulowania.
  • FOK (spełnij lub anuluj) - FOK zleca giełdzie wykonanie całego zlecenia jednocześnie. Jeśli giełda nie jest w stanie tego zrobić, zostanie ono natychmiast anulowane.
  • IOC (natychmiastowe lub anulowane) - całość lub część zlecenia musi zostać wykonana natychmiast lub jest anulowana. W przeciwieństwie do FOK zlecenia nie są anulowane, jeśli można je częściowo zrealizować.
• quantity - po prostu ilość zasobu, którą chcesz kupić lub sprzedać.
• price - cena, po której chcesz sprzedać. W przypadku pary BTCUSDT jest to wyrażone w USDT.
• newClientOrderId - identyfikator zlecenia. To nie jest pole obowiązkowe, ale możesz nadać mu identyfikator, który ułatwi późniejsze operacje. W przeciwnym razie jest on generowany losowo przez giełdę.

W porządku! Utwórzmy teraz zlecenie testowe. Będziemy stosować automatycznie generowane wartości: zlecenie limit sprzedaży 0.1 BTC za USDT za 9,000$. Naciśnij Wyślij. Jeśli to się powiedzie, otrzymamy {} jako odpowiedź. 

Złóż rzeczywiste zlecenie

Czas na złożenie prawdziwego (fałszywego) zlecenia. 

POST /api/v3/order

Przejdź do Handel (Trade) > Nowe Zlecenie (New Order). Zaznajomiłeś się już ze zleceniami testowymi, więc podane tutaj parametry nie powinny być zaskoczeniem. Zostawmy wszystkie wartości takimi, jakie są, ale ponieważ jesteśmy "bykami", zmienimy cenę, za którą sprzedajemy, na $40,000 USD. Dostosuj wartość ceny, następnie naciśnij Wyślij (Send).

Zwrócone zostanie wiele szczegółów na temat zlecenia, jeśli składanie się powiedzie.

Sprawdź status otwartego zlecenia

Otrzymaliśmy potwierdzenie, że zlecenie zostało złożone w poprzedniej sekcji, lecz co, jeśli chcemy to sprawdzić później? Mamy do dyspozycji kilka możliwości.

GET /api/v3/openOrders

Znajdziesz to w Handel (Trade) > Current Open Orders(USER_DATA). BTCUSDT jest wybrane domyślnie. Jeśli klikniesz Send, otrzymasz wszystkie otwarte zlecenia BTCUSDT (do tej pory powinieneś zobaczyć tylko to, które wcześniej ustawiliśmy). Możesz nie określać symbolu, w takim wypadku system zwróci wszystkie otwarte zlecenia.

GET /api/v3/allOrders

Handel (Trade) > All Orders (USER_DATA) daje wgląd do wszystkich zleceń - nie tylko otwartych. Tutaj musisz podać symbol. OrderId, startTime, endTime i limit są parametrami opcjonalnymi, które mogą pomóc Ci zawęzić wyszukiwanie. Nie będziemy ich ruszać, więc odznacz je. Kliknij Send, a zobaczysz taką samą odpowiedź jak wcześniej. Jeśli masz jakieś zamknięte lub anulowane zlecenia, również je tu dostrzeżesz. 

Możemy także zapytać o konkretne zlecenia za pomocą:

GET /api/v3/order

Wejdź w Handel (Trade) > Query Order (USER_DATA). Musisz podać orderId lub origClientOrderId (opcjonalny tag „newClientOrderId”, który możesz dodać do zleceń). Odznacz orderId. W przypadku origClientOrderId podamy domyślny tag z wcześniejszej sekcji - „my_order_id_1”. Wypełnij pole i naciśnij Send, aby uzyskać odpowiedź.

Anuluj zlecenie

Po pewnym czasie możemy zdecydować, że cel $40,000 jest trochę zbyt optymistyczny, więc chcemy go anulować. W takim przypadku użylibyśmy:

DELETE /api/v3/order

W sekcji Trade > Cancel Order widnieje możliwość, która pozwoli nam wyodrębnić zlecenia do anulowania. Odznacz orderId i newClientOrderId i podaj „my_order_id_1” jako wartość origClientOrderId.

Po wysłaniu tego żądania, zwrócone zostanie zlecenie. Jeśli przewiniesz w dół do „statusu”, zobaczysz, że rzeczywiście zostało anulowane. Aby to potwierdzić, ponownie użyj GET /api/v3/openOrders (zwracające pustą listę) lub GET /api/v3/order z parametrem origClientOrderId.

Złóż zlecenie, które wypełnia się natychmiast

Nasze poprzednie zlecenie nie zostało zrealizowane, ponieważ było to zlecenie typu limit, które uruchomi się dopiero, gdy cena BTC osiągnie $40,000. W przypadku zlecenia market mówimy w zasadzie „kupuj/sprzedawaj za dowolną cenę, na jaką obecnie wyceniany jest dany zasób”. Zrealizuje się ono natychmiast.

W tym celu wróćmy do opcji Trade > New Order. Pokażemy typ odpowiedzi (newOrderRespType) będący parametrem, który możemy dostosować w zależności od tego, jaką odpowiedź chcemy uzyskać od serwera. Istnieją trzy opcje: ACK, RESULT lub FULL - tutaj możesz zobaczyć przykłady każdej odpowiedzi. Sprawdźmy ACK, który da nam proste potwierdzenie, że zlecenie zostało otrzymane.

Poniżej widać, że zamierzamy złożyć zlecenie market na sprzedaż BNB za BUSD po bieżącej cenie rynkowej.

Pamiętaj, że odpowiedź daje nam minimalną ilość informacji:

Możesz sprawdzić, czy zlecenie zostało zrealizowane za pomocą /api/v3/allOrders.

Sprawdzanie transakcji

Na koniec spójrzmy na komendę do sprawdzenia twoich transakcji:

GET /api/v3/myTrades

Znajduje się to w sekcji Trade > Account Trade List (USER_DATA). Pozwala sprawdzić każdą transakcję pod kątem określonego symbolu. Jeśli chcesz zobaczyć wszystkie swoje transakcje dla domyślnego symbolu (BTCUSDT), po prostu odznacz startTime, endTime i fromId. Odpowiedź zwróci do 500 transakcji - zwiększ limit, jeśli chcesz zobaczyć więcej.

Debugowanie przez Postman

W Postmanie można ujawniać nieprzetworzone żądanie HTTP i odpowiedź.

To menu otworzy konsolę Postman, w której pokazane zostaną szczegóły każdego żądania.

Przemyślenia końcowe

Celem tego przewodnika było wprowadzenie do interfejsu API Binance bez pisania ani jednego wiersza kodu. Jeśli nadążałeś, powinieneś mieć teraz ogólny zamysł tego, w jaki sposób możemy wysłać żądanie i przesłać informacje.

W następnych odsłonach tej serii przedstawimy podstawowe koncepcje kodowania, które pozwolą nam zautomatyzować kupno i sprzedaż kryptowalut i innych zasobów cyfrowych. 

Masz pytania w międzyczasie? Odwiedź nasze rozwijające się forum Społeczności Deweloperów Binance lub zapoznaj się z dokumentacją.