Czym jest WhiteBIT API?

WhiteBIT API to narzędzie automatyzacji, które umożliwia programistom tworzenie aplikacji do interakcji z naszą giełdą. Dzięki niemu można m.in.: tworzyć i zarządzać zleceniami kupna i sprzedaży kryptowalut, uzyskiwać informacje o rynku, sprawdzać saldo konta i wiele więcej.

Jak korzystać z WhiteBIT API?

Przed rozpoczęciem korzystania z API, należy włączyć dwuetapową weryfikację (2FA) na swoim koncie. 

Następnie trzeba wygenerować klucze API, które służą do uwierzytelnienia użytkownika i integracji z API.

Aby aktywować klucze, wykonaj następujące kroki:

• Przejdź do ustawień API na swoim koncie i wybierz “Edytuj” w odpowiedniej sekcji.
• Po kliknięciu “Wygeneruj klucz API”, wprowadź swój kod 2FA.
• W oknie, które się pojawi, zobaczysz parę kluczy API – zachowaj je, ponieważ będą one potrzebne do dalszej autoryzacji operacji w interfejsie API.

Upewnij się, że bezpiecznie przechowujesz swój Klucz Tajny, ponieważ po zamknięciu tej strony nie będzie można go przywrócić. Klucz Publiczny jest zawsze dostępny i nie stanowi zagrożenia podczas przekazywania go stronom trzecim. W przeciwieństwie do Klucza Tajnego, Klucz Publiczny sam w sobie nie stwarza ryzyka niepożądanych działań.

• Na tej samej stronie możesz również wybrać końcowe punkty API (endpoint), które zamierzasz używać. Zaleca się wybranie wszystkich dostępnych punktów podczas testowania kluczy API, ponieważ później można to edytować. Bardziej szczegółowe informacje na temat endpointów zostaną przedstawione dalej w artykule.
• Następnie potwierdź swoje działania, wprowadzając kod 2FA;
• I oto, twoje klucze API są gotowe do użycia!

Po utworzeniu pary kluczy API można również zmienić dostęp IP. Dzięki funkcji ograniczenia dostępu za pomocą adresów IP, można dodać własne adresy IPv4 i IPv6 do listy zaufanych adresów IP.

W przypadku aktywacji tej funkcji, jeśli żądanie otrzymania kluczy API zostanie wysłane z innego adresu IP, klucze API zostaną automatycznie dezaktywowane. Na adres e-mail zostanie wysłane powiadomienie z informacją o publicznym kluczu i adresie IP, z którego zostało wysłane żądanie.

Jeśli ten adres IP należy do сiebie i jest zaufany, możesz ponownie aktywować API, dodając go do listy zaufanych adresów IP.

Ogólnie rzecz biorąc, można dodać do listy zaufanych maksymalnie 20 adresów IP.

Wracając do listy dostępnych punktów końcowych (endpoint) do wykorzystania, warto zauważyć, że każda z przedstawionych kategorii i podkategorii odpowiada za określoną grupę operacji do zarządzania kontem na giełdzie. Możesz tworzyć i używać swoich kluczy do wykonywania operacji w jednej lub kilku z następujących dostępnych kategorii:

• Depozyty;
• Wypłaty;
• Przelewy między saldami;
• Saldo i historia portfela;
• Kody;
• Saldo handlowe i historia;
• Zarządzanie zleceniami.

Szczegółowe informacje na temat funkcjonalności API naszej giełdy można znaleźć w instrukcji technicznej, przedstawionej w prostym i dostępnym formacie.

Rozszerzona dokumentacja jest również dostępna w ogólnodostępnym repozytorium oprogramowania na GitHubie.

Aby przetestować funkcjonalność naszego API, możesz również skorzystać z tokenów DEMO.

Szybkie tworzenie klucza API za pomocą OAuth

Szybkie tworzenie kluczy API przez OAuth umożliwia natychmiastowe połączenie aplikacji partnerskich z WhiteBIT bez konieczności ręcznej konfiguracji kluczy API.

Podczas integracji z aplikacjami zewnętrznymi użytkownicy tradycyjnie musieli ręcznie tworzyć klucze API, kopiować poufne dane i konfigurować uprawnienia — był to czasochłonny proces. Integracja OAuth 2.0 z WhiteBIT zapewnia bezpieczną autoryzację opartą na tokenach dla aplikacji partnerskich, umożliwiając im dostęp do platformy WhiteBIT w imieniu użytkowników. Implementacja ta jest zgodna ze standardami branżowymi, a jednocześnie oferuje specjalistyczne funkcje opracowane specjalnie z myślą o handlu kryptowalutami i zarządzaniu kontami.

Jak szybko utworzyć klucz API za pomocą OAuth

1. Musisz zainicjować połączenie za pośrednictwem aplikacji zewnętrznej. System przekieruje cię na stronę autoryzacji OAuth WhiteBIT.
2. Zaloguj się (jeśli jeszcze tego nie zrobiłeś) i przejrzyj zakresy dostępu OAuth: tworzenie, odczyt i usuwanie kluczy API.
3. Następnie wybierz konkretne endpointy, które planujesz wykorzystywać dla klucza API, stosując te same zasady co w przypadku kluczy tworzonych ręcznie.
4. W oknie modalnym zostaną wyraźnie wyświetlone wszystkie wybrane endpointy. Jeśli lista zawiera uprawnienia do wypłaty środków, musisz je wyraźnie potwierdzić, zaznaczając odpowiednie pole przed kontynuowaniem.
5. W przypadku wszystkich autoryzacji OAuth musisz potwierdzić swoje działania poprzez wprowadzenie kodu 2FA.
6. Po pomyślnej weryfikacji MFA aplikacja wymienia kod autoryzacyjny na token dostępu OAuth i wywołuje endpoint tworzenia klucza API. Tajny klucz API jest udostępniany tylko raz i nie może zostać ponownie pobrany.

Implementacja WhiteBIT OAuth 2.0 obsługuje szeroki zakres dostępnych endpointów, o które można wnioskować podczas konfiguracji klienta, w tym:

• Dostęp do informacji o koncie;
• Saldo i historia transakcji;
• Zarządzanie zleceniami (odczyt, tworzenie i usuwanie);
• Dostęp do danych rynkowych;
• Historia handlu;
• A także bardziej wyspecjalizowane uprawnienia dostępu.

Rozszerzona dokumentacja jest również dostępna w publicznym repozytorium oprogramowania na GitHub.

Najważniejsze informacje:

• Jeden klucz dla pary platforma-użytkownik. Dozwolony jest tylko jeden aktywny klucz API utworzony za pomocą OAuth dla jednej platformy i jednego użytkownika. Jeśli klucz już istnieje, nowy nie może zostać utworzony do momentu usunięcia istniejącego.
• Tokeny OAuth mają krótki okres ważności. Tokeny dostępu są ważne przez 4 godziny i mogą być używane wyłącznie do tworzenia, zarządzania i usuwania kluczy API — nie do handlu ani wypłaty środków.
• Ograniczenia adresów IP są stosowane automatycznie. Klucze utworzone za pomocą OAuth są ograniczone do zakresów adresów IP zarejestrowanych przez platformę. Nie możesz przeglądać ani modyfikować listy dozwolonych adresów IP dla tych kluczy.
• Klucze są niezmienne po utworzeniu. Endpointy, lista dozwolonych adresów IP oraz nazwa klucza nie mogą być edytowane. Dezaktywacja i ponowna aktywacja nie są obsługiwane — możliwe jest jedynie usunięcie klucza.
• Warunki automatycznego usunięcia: brak aktywności API przez 14 dni, cofnięcie dostępu przez platformę, zmiana hasła do konta lub zablokowanie konta z przyczyn związanych z AML lub zgodnością regulacyjną.
• Globalny limit liczby kluczy API (50 kluczy API) obejmuje wszystkie klucze utworzone ręcznie oraz za pomocą OAuth.

WhiteBIT Webhook

Webhook jest używany do otrzymywania informacji zwrotnych od serwera na temat wykonania różnych procesów na twoim koncie, takich jak pomyślne wypłacenie środków lub aktywacja kodu WB.

Aby aktywować klucze Webhook, należy wykonać te same kroki co w przypadku kluczy API w sekcji ustawień Webhook na twoim koncie. Istnieje kilka sposobów aktywacji:

• Dodanie publicznego klucza do rekordu domeny TXT, wskazanego podczas tworzenia klucza;
• Dodanie pliku "whiteBIT-verification.txt" z treścią twojego publicznego klucza Webhook do głównego katalogu twojej strony internetowej;
• Utworzenie punktu końcowego „check-wb-webhooks” na twoim serwerze, który zwróci publiczny klucz Webhook.

Aby rozpocząć aktywację klucza Webhook, musisz go najpierw utworzyć na giełdzie. Należy pamiętać, że można utworzyć tylko jeden klucz Webhook. Aby to zrobić, wykonaj następujące kroki:

• Przejdź do sekcji ustawień Webhook na swoim koncie i wybierz “Edytuj” w odpowiedniej sekcji;
• Tak jak w przypadku tworzenia kluczy API, zapisz klucz tajny (Secret Key) w bezpiecznym miejscu. Po zamknięciu strony przyciskiem “Potwierdź”, klucz tajny nie będzie już dostępny;
• Gotowe! Klucz Webhook został utworzony.

Należy pamiętać, że tak jak w przypadku kluczy API, utworzenie klucza Webhook nie aktywuje go automatycznie. Należy przesunąć suwak w aktywną pozycję, aby aktywować Webhook.

Szczegółowe informacje na temat ustawień i korzystania z Webhook są dostępne w odpowiedniej sekcji naszej dokumentacji Webhook.

Webhook Service Level Agreement (SLA)

Ciągłe wysyłanie webhooków wymaga od serwerów klienta stabilnej pracy i poprawnych odpowiedzi. W przypadku problemów po stronie serwera klienta (wolne działanie, brak odpowiedzi lub niepoprawna odpowiedź) następuje ponowna wysyłka webhooka. W sytuacji dużej liczby ponownych wysyłek system jest obciążony, co spowalnia dostarczanie webhooków do wszystkich klientów.

Aby rozwiązać tego typu opóźnienia, wprowadzono SLA (Service Level Agreement), czyli automatyczne sprawdzanie jakości działania webhooka klienta. Zasada jego działania polega na tym, że jeśli SLA spadnie poniżej ustalonego poziomu (90%), wysyłka webhooków do klienta zostaje wyłączona.

Webhook uznaje się za nieprzetworzony w następujących przypadkach:

• odpowiedź zajmuje więcej niż 3 sekundy;
• status HTTP ≠ 200.

Zwróć uwagę: każdy taki webhook zostanie ponownie wysłany maksymalnie 5 razy.

Obliczanie SLA odbywa się według wzoru: SLA = (liczba udanych webhooków) / (łączna liczba prób wysyłki).

Na przykład, jeśli w ciągu dnia otrzymano 90 udanych webhooków ze 100 wysłanych, SLA wyniesie 90%.

WebSocket Best Bid/Ask w Czasie Rzeczywistym

Dostęp do danych rynkowych w czasie rzeczywistym jest kluczowym wymogiem w handlu wysokich częstotliwości oraz w zautomatyzowanych systemach realizacji zleceń. Aby sprostać temu zapotrzebowaniu, wdrożyliśmy dedykowany strumień WebSocket, który dostarcza na żywo aktualizacje najlepszych ofert kupna (bid) i sprzedaży (ask) dla wszystkich obsługiwanych rynków. Strumień ten został zoptymalizowany pod kątem niskich opóźnień i wysokiej niezawodności, umożliwiając systemom transakcyjnym podejmowanie decyzji na podstawie najbardziej aktualnych danych cenowych.

Co Oferuje Strumień 

Strumień WebSocket Best Bid/Ask zapewnia ciągły przepływ danych odzwierciedlający ceny z najwyższej warstwy księgi zleceń dla każdego symbolu. Każda aktualizacja zawiera najwyższą dostępną cenę kupna (najlepszy bid) i najniższą dostępną cenę sprzedaży (najlepszy ask), wraz z odpowiadającymi ilościami oraz identyfikatorem pary handlowej. Struktura została zoptymalizowana tak, aby dostarczać wyłącznie najbardziej istotne dane, eliminując zbędny szum, a jednocześnie zachowując dokładność i szybkość.

 

Każda wiadomość zawiera dwa znaczniki czasu, aby zapewnić pełną przejrzystość i wspierać operacje wrażliwe na opóźnienia. Pierwszy to czas zdarzenia (Event Time), czyli moment, w którym serwer WebSocket wysyła wiadomość. Drugi to czas aktualizacji (Update Time), który wskazuje, kiedy dane cenowe zostały ostatnio zmodyfikowane na poziomie silnika dopasowującego. To podejście z podwójnym znacznikiem czasu umożliwia klientom dokładne obliczenie opóźnień transmisji i weryfikację aktualności danych. Spójność ta ułatwia integrację dla klientów zaznajomionych z podobnymi protokołami danych rynkowych.

Zalety Operacyjne

Ten strumień jest szczególnie przydatny w przypadkach wymagających natychmiastowego dostępu do dokładnych danych cenowych, takich jak zautomatyzowane systemy handlowe czy algorytmy market-makingowe. Pozwala klientom na bieżąco monitorować warunki rynkowe, wykrywać zmiany spreadu i realizować transakcje w oparciu o aktualne dane.

 

Jedną z kluczowych zalet tego strumienia jest bardzo niskie opóźnienie — aktualizacje są nadawane natychmiast po zarejestrowaniu zmian wewnętrznego stanu systemu. Zapewnia to, że klienci działają na podstawie możliwie najnowszych informacji. Strumień upraszcza również obliczanie spreadu oraz pozwala na efektywne śledzenie poziomów płynności na najwyższym poziomie księgi zleceń. Dzięki ujawnieniu zarówno czasu aktualizacji danych, jak i czasu wysłania wiadomości, system wspiera kompleksowy monitoring opóźnień sieciowych i okien reakcji rynku.

Integracja i Struktura Wiadomości

Klienci mogą połączyć się z punktem końcowym WebSocket i zasubskrybować aktualizacje wybranych par handlowych. Każda wiadomość jest dostarczana w formacie JSON i zawiera jasno zdefiniowane pola dla symbolu, cen bid i ask, odpowiednich wolumenów oraz dwóch znaczników czasu. Format jest celowo lekki, aby wspierać środowiska o dużym przepływie danych i zredukować złożoność przetwarzania po stronie klienta.

 

Strumień WebSocket Best Bid/Ask stanowi kluczowy element infrastruktury do handlu w czasie rzeczywistym. Oferuje natychmiastowy wgląd w najbardziej konkurencyjne ceny kupna i sprzedaży na rynku, wraz z precyzyjną informacją o czasie. Strumień ten został zaprojektowany tak, aby wspierać szybkie, świadome i zautomatyzowane decyzje handlowe, zapewniając niezawodną podstawę dla każdej strategii opartej na danych z najwyższego poziomu księgi zleceń.

Najczęściej zadawane pytania

Co się stanie z kluczami API i Webhook w przypadku wyłączenia dwuskładnikowego uwierzytelniania 2FA?

• W przypadku wyłączenia 2FA, twoje klucze API i Webhook zostaną wyłączone i można je będzie ponownie aktywować dopiero po włączeniu 2FA.

Czy można tworzyć i aktywować klucze API oraz Webhook przez aplikację mobilną WhiteBIT?

• Niestety, nie. Proces tworzenia i aktywacji kluczy jest dostępny wyłącznie w wersji internetowej naszej giełdy.

Czy klucze API mają termin ważności i ile można ich utworzyć?

• Jeśli klucz API pozostanie nieaktywny przez 14 dni, zostanie automatycznie dezaktywowany w celu utrzymania bezpieczeństwa. Maksymalna liczba kluczy wynosi 50.

Czy można użyć dowolnej domeny do testowania kluczy Webhook?

• Nasz system nie przewiduje takich działań. Aby aktywować klucz Webhook, konieczne jest potwierdzenie prawa własności do domeny.

Możliwe błędy przy korzystaniu z API

This action is unauthorized. Enable your key in API settings.

Jeśli napotkasz ten błąd, sprawdź, czy włączyłeś swój klucz API. Aby go aktywować, przesuń suwak „Dostęp do endpointu” obok wymaganego endpointu.

Jeśli wcześniej ustawiłeś ograniczenie adresów IP, twój klucz API może zostać dezaktywowany przy korzystaniu z nowego adresu IP. Odpowiedni e-mail zostanie wysłany na twój adres poczty elektronicznej.

Uwaga: jeśli jesteś pewien, że korzystałeś z klucza API ze swojego adresu IP, możesz dodać go do listy zaufanych adresów IP. Jeśli nie rozpoznajesz tego adresu IP, musisz utworzyć nowy klucz API.

You don't have permission to use this endpoint. Please contact support for more details.

Endpoint, którego użyłeś, jest dostępny tylko dla klientów B2B.

Too many requests.

Jeśli treść twojego zapytania nie zawiera parametru „nonceWindow”, dodaj go. W przypadku, gdy błąd nie zniknie po dodaniu tego parametru, będziesz musiał utworzyć nowy klucz API.

Jeśli parametr „nonceWindow” jest już używany w treści zapytania, upewnij się, że wartości są podane w milisekundach.

The selected ticker is invalid.

Wprowadzony przez ciebie ticker kryptowaluty jest nieprawidłowy. Proszę sprawdź poprawność zapisu tickera.

Currency is not depositable/withdrawable.

Depozyty/wypłaty wybranej przez ciebie kryptowaluty są obecnie zamknięte. Informacje o dostępności depozytów/wypłat kryptowalut publikowane są na naszym kanale Telegram.