Jak wywołać API giełdy: klucze, podpisy i kody błędów

Większość osób, które po raz pierwszy próbują wywołać API giełdy, nie zawodzi na logice handlowej. Zawodzą na etapie "uścisku dłoni" (handshake) — znacznik czasu spóźniony o 40 sekund, pole wyboru uprawnień, którego nigdy nie zaznaczyli, lub hasło z myślnikiem. Giełda odrzuca żądanie, zwraca numer, a samouczek, z którego korzystali, nie wyjaśnia, co ten numer oznacza.

Ten przewodnik prowadzi przez pełną ścieżkę: czym jest API giełdy, które wywołania wymagają klucza, jak faktycznie budowany jest podpis oraz — co jest częścią, którą prawie nikt nie publikuje — mapowanie konkretnych kodów błędów, które napotkasz, wraz z rozwiązaniem dla każdego z nich. Przykłady wykorzystują przewodnik integracji API WEEX, ponieważ jest to jedno z niewielu centrów deweloperskich giełd, które publikuje swój model uprawnień, opóźnienia propagacji i limity stawek na operację. Wszystko poniżej zostało sprawdzone z dokumentacją deweloperską WEEX na żywo w dniu 28 lipca 2026 r.; FAQ API spot platformy posiada datę ostatniej aktualizacji 14 kwietnia 2026 r.

Co robi API giełdy i które wywołania wymagają klucza

API giełdy to zestaw punktów końcowych HTTP i WebSocket, które pozwalają Twojemu oprogramowaniu robić to, co w przeciwnym razie robiłbyś klikając: odczytywać ceny, sprawdzać saldo, składać zlecenie, anulować je. Nic bardziej mistycznego.

Podział, który ma znaczenie operacyjne, to publiczne kontra prywatne. Publiczne punkty końcowe obsługują dane rynkowe i konfigurację platformy i nie wymagają żadnego uwierzytelniania — możesz je wywołać z przeglądarki. Prywatne punkty końcowe dotyczą Twojego konta i każdy z nich musi posiadać podpis.

Praktyczny wniosek: możesz zbudować i przetestować całą połowę danych bota, zanim kiedykolwiek wygenerujesz klucz. Zrób to najpierw. Nic to nie kosztuje i ujawnia błędy formatowania symboli i wyrównania świec, gdy promień rażenia jest jeszcze zerowy.

Jak utworzyć klucz API i określić jego uprawnienia

W WEEX przepływ to Konto → Zarządzanie API → Utwórz klucz API, a następnie weryfikacja bezpieczeństwa. Każde konto może posiadać do 10 grup kluczy API, co wystarcza do uruchomienia oddzielnych kluczy dla badań, testów i produkcji — i powinieneś to robić, ponieważ skompromitowany klucz jest wtedy ograniczonym incydentem, a nie całkowitym.

Z tego ekranu wychodzą trzy poświadczenia i nie są one zamienne:

• APIKey — publiczny identyfikator, którego giełda używa do wyszukania Ciebie.
• SecretKey — klucz prywatny, którym podpisuje się Twój kod. Jest wyświetlany tylko raz.
• Passphrase — fraza, którą wybierasz. Jeśli ją zgubisz, nie można jej odzyskać ani zresetować; usuwasz klucz i zaczynasz od nowa. WEEX wymaga również, aby nie zawierała żadnych znaków specjalnych — tylko znaki alfanumeryczne. To realne ograniczenie, a nie sugestia, a fraza z interpunkcją jest zaskakująco częstą przyczyną błędów uwierzytelniania.

Model uprawnień to część, nad którą warto się zatrzymać. Nowo utworzony klucz jest domyślnie tylko do odczytu, a zakresy handlowe są opcjonalne i niezależne.

Z tej tabeli wynikają dwie rzeczy. Po pierwsze, jeśli zbudowałeś bota spot i zaznaczyłeś tylko "Tylko do odczytu", każde wysłane zlecenie zostanie odrzucone — to najczęstsza skarga typu "mój klucz nie działa". Po drugie, co bardziej przydatne: na tej liście nie ma zakresu wypłat. Klucz API WEEX nie może przenieść środków poza platformę. Ten limit strukturalny jest wart więcej niż jakakolwiek rada dotycząca higieny kluczy, ponieważ ogranicza to, co atakujący może zrobić ze skradzionym kluczem, do handlu, którego nie autoryzowałeś, a nie do opróżnionego portfela.

Zanim opuścisz ten ekran, powiąż adres IP. WEEX wyraźnie oznacza nieograniczone klucze jako ryzyko bezpieczeństwa, a biała lista jest różnicą między wyciekiem klucza jako sytuacją awaryjną a irytacją.

Jeden haczyk czasowy, o którym dokumentacja mówi jasno, a większość przewodników zewnętrznych pomija: nowo utworzone lub zmodyfikowane klucze API potrzebują około 15 minut na propagację w systemie. Jeśli Twoje pierwsze wywołanie nie udaje się natychmiast po zaznaczeniu nowego pola uprawnień, poczekaj, zanim zaczniesz przepisywać kod podpisu. Wiele osób debugowało działający kod przez godzinę z tego powodu.

Pełne kroki konfiguracji pole po polu znajdują się w przewodniku przygotowania integracji API WEEX.

Jak wywołać API giełdy: cztery nagłówki i ciąg podpisu

Oto mechanizm, sprowadzony do podstaw. Każde prywatne żądanie zawiera cztery nagłówki uwierzytelniające oraz typ zawartości. Giełda niezależnie przelicza Twój podpis z otrzymanego żądania; jeśli jej wynik pasuje do Twojego, żądanie jest autentyczne.

Sam podpis to hash ciągu, który składasz w ustalonej kolejności:

timestamp + metoda HTTP wielkimi literami + ścieżka żądania + ? + ciąg zapytania + body

Połącz je, zahashuj za pomocą HMAC SHA256 przy użyciu SecretKey, a następnie zakoduj wynik w Base64. Jeśli nie ma ciągu zapytania, usuń ? i segment zapytania. Jeśli nie ma body, pomiń je. Metoda musi być wielkimi literami. Ścieżka to ścieżka punktu końcowego, a nie pełny URL.

Trzy szczegóły powodują większość niedopasowań podpisu:

1. Okno znacznika czasu wynosi 30 sekund. WEEX odrzuca każde żądanie, którego ACCESS-TIMESTAMP odbiega o więcej niż 30 sekund od czasu serwera. Jeśli zegar Twojej maszyny dryfuje — a kontenery i maszyny wirtualne dryfują stale — będziesz otrzymywać sporadyczne błędy, które wyglądają na losowe. Odpytaj punkt końcowy czasu serwera giełdy przy starcie, oblicz przesunięcie i zastosuj je. Nie ufaj lokalnemu zegarowi.
2. Body, które podpisujesz, musi być identyczne bajt po bajcie z body, które wysyłasz. Ponowna serializacja JSON między podpisaniem a wysłaniem zmienia kolejność kluczy lub formatowanie numeryczne, a hash przestaje pasować. Podpisz dokładny ciąg, który przekażesz.
3. Symbole są rozróżnialne wielkością liter i muszą być wielkimi literami, i muszą być dokładnymi wartościami zwróconymi przez punkt końcowy produktu/symbolu platformy. Zgadywanie formatu to sposób na uzyskanie błędu nieprawidłowego symbolu na aktywie, które wyraźnie istnieje.

Punkty końcowe znajdują się w oddzielnych domenach według linii produktów — żądania spot trafiają do api-spot.weex.com, futures do api-contract.weex.com, ze strumieniami WebSocket na ws-spot.weex.com. Skierowanie wywołania spot do hosta futures powoduje błędy, które wyglądają jak problemy z autoryzacją, ale nimi nie są.

Dlaczego moje pierwsze wywołanie API nie udaje się? Dekodowanie kodów błędów

To tutaj samouczek zazwyczaj się kończy, a zaczyna zgłoszenie do pomocy technicznej. Poniższa tabela mapuje błędy uwierzytelniania i uprawnień, które najprawdopodobniej zobaczysz przy pierwszej integracji, na ich rzeczywistą przyczynę i rozwiązanie.

Ten błąd 403 WebSocket zasługuje na uwagę. Nie ma nic wspólnego z Twoimi poświadczeniami, nie daje kodu błędu do wyszukania i jest spowodowany pominięciem, które większość bibliotek HTTP robi w milczeniu. To rodzaj błędu, który zjada popołudnie.

Pełna lista znajduje się w odniesieniu do kodów błędów API WEEX.

Jakie są limity stawek API giełdy?

Limity stawek to rzecz, która działa dobrze w testach, a psuje się na produkcji, ponieważ gryzą tylko wtedy, gdy zmienność rośnie, a Twój bot zaczyna strzelać. Domyślnie w WEEX jest to 10 żądań na sekundę, z bardziej rygorystycznymi opublikowanymi limitami dla konkretnych operacji.

Warto mieć dwie interpretacje tej tabeli. Zasada wsadowa jest ważna: partia obejmująca cztery pary handlowe z dziesięcioma zleceniami każda liczy się jako pojedyncze żądanie. Każda strategia market-makingowa lub gridowa, która składa zlecenia pojedynczo, marnuje swój budżet bez powodu. A fakt, że limity anulowania są luźniejsze niż limity składania, mówi Ci, że platforma oczekuje rotacji kwotowań — strategie kwotowania są uwzględnione w budżecie, spamowanie pojedynczymi zleceniami nie.

Kiedy trafisz na 429, wycofaj się wykładniczo. Ponawianie natychmiast w ciasnej pętli to sposób, w jaki konta uruchamiają kontrolę ryzyka, a WEEX automatycznie wyłączy uprawnienia API na koncie, które generuje trwałe, wysokoczęstotliwościowe nieprawidłowe żądania. Przywrócenie ich oznacza kontakt z pomocą techniczną. Opublikowane notatki o limitach stawek i uprawnieniach znajdują się w FAQ API WEEX.

Czy handel przez API giełdy jest bezpieczny?

Bezpieczny to złe określenie. Klucz API to ograniczona delegacja władzy, a pytanie brzmi, jak ściśle ją ograniczasz.

Ochrony strukturalne wykonują większość pracy. Uprawnienia zakresowe oznaczają, że klucz tylko do odczytu nie może handlować. Brak zakresu wypłat w kluczach WEEX oznacza, że żaden klucz nie może przenieść Twoich środków poza platformę. Biała lista IP oznacza, że skradziony klucz jest bezużyteczny z sieci atakującego. Niezależne zakresy spot i futures oznaczają, że błąd bota spot nie może otworzyć pozycji lewarowanej. Zastosuj te cztery, a realistyczny najgorszy scenariusz spada z "konto opróżnione" do "niechciane transakcje z jednego znanego IP" — możliwe do odzyskania i wykrywalne.

To, co zostaje, zależy od Ciebie:

• Nigdy nie commituj kluczy do repozytorium ani nie osadzaj ich w kodzie po stronie klienta. Używaj zmiennych środowiskowych lub menedżera sekretów.
• Uruchamiaj oddzielne klucze dla każdego środowiska, aby unieważnienie wyciekniętego klucza testowego nie zatrzymało produkcji.
• Rotuj zgodnie z harmonogramem i usuwaj klucze w momencie podejrzenia ekspozycji.
• Loguj każdą odpowiedź, w tym błędy. Skok stopy błędów jest często pierwszym znakiem, że coś jest nie tak, a nie zobaczysz tego, czego nie rejestrujesz.
• Buduj wyłączniki bezpieczeństwa (kill switches) w samym bocie — maksymalna częstotliwość zleceń, maksymalny slippage, maksymalna pozycja — ponieważ limity giełdy chronią giełdę, a nie Twój P&L.

Tryb awarii, który faktycznie kosztuje ludzi pieniądze, rzadko jest skradzionym kluczem. To bot bez wyłącznika, który handluje zepsutym sygnałem przez zmienną godzinę. Napisz wyłącznik, zanim napiszesz strategię.

Przetestuj w trybie demo, zanim wyślesz zlecenie na żywo

WEEX udostępnia symulowane punkty końcowe futures — saldo, złóż zlecenie, pozycje, historia zleceń — które odzwierciedlają interfejs na żywo i rozliczają się w aktywie testowym, a nie w prawdziwym USDT. To właściwe miejsce, aby przetestować części Twojego stosu, które są najtrudniejsze do bezpiecznego przetestowania: częściowe realizacje, wyścigi anuluj/zastąp, logikę ponownego łączenia po zerwaniu WebSocket i to, czy Twoja księgowość pozycji przetrwa restart.

Wdrożenie etapowe, które działa: tylko publiczne punkty końcowe → klucz tylko do odczytu na danych na żywo → punkty końcowe demo dla cyklu życia zlecenia → klucz na żywo przy minimalnym rozmiarze → skalowanie. Każdy etap wyłapuje inną klasę błędów, a tylko ostatni kosztuje pieniądze.

Jeszcze jeden szczegół operacyjny, który psuje długo działające boty: serwer WebSocket okresowo wysyła ping, a Twój klient musi odpowiedzieć pongiem. Brak odpowiedzi więcej niż dziesięć razy powoduje zamknięcie połączenia przez serwer. Bot, który "losowo przestaje otrzymywać dane po kilku godzinach", to prawie zawsze brakujący handler ponga.

Twoja lista kontrolna przed pierwszym wywołaniem na żywo

Poprawne wywołanie API giełdy to krótka lista szczegółów, a nie trudny problem. Ogranicz klucz dokładnie do tego, czego potrzebuje strategia i nic więcej. Powiąż IP. Trzymaj frazę alfanumeryczną i przechowuj ją tam, gdzie jej nie zgubisz. Podpisz dokładne bajty, które wysyłasz. Zsynchronizuj zegar z giełdą, nie serwerem. Grupuj zlecenia. Przeczytaj kod błędu, zanim przepiszesz kod — zazwyczaj mówi Ci odpowiedź. I daj platformie piętnaście minut na propagację nowego klucza, zanim stwierdzisz, że coś jest zepsute.

Jeśli chcesz szerszego obrazu tego, co obsługuje stos API giełdy, zanim zaczniesz budować, przegląd handlu API na WEEX obejmuje zasięg REST i WebSocket, przypadki użycia i kryteria oceny. Gdy będziesz gotowy do wygenerowania poświadczeń i rozpoczęcia integracji, strona API WEEX prowadzi bezpośrednio do tworzenia kluczy i pełnej dokumentacji deweloperskiej.

FAQ

1. Jak wywołać API giełdy bez pisania kodu?

Nie możesz wywołać go bezpośrednio, ale nie musisz sam pisać klienta. Trackery portfela, narzędzia podatkowe i zewnętrzne platformy botów akceptują klucz API giełdy i obsługują żądania za Ciebie. Daj tym narzędziom klucz tylko do odczytu, chyba że naprawdę muszą handlować — większość nie musi.

2. Czy publiczne punkty końcowe danych rynkowych wymagają klucza API?

Nie. Ceny, świece, głębokość arkusza zleceń i lista symboli są nieautoryzowane w WEEX i większości głównych giełd. Jedynym haczykiem są połączenia WebSocket, które wymagają nagłówka User-Agent nawet na kanałach publicznych, w przeciwnym razie firewall zwraca 403.

3. Dlaczego mój klucz API działa dla sald, ale nie dla składania zleceń?

Ponieważ uprawnienie do handlu jest oddzielone od uprawnienia do odczytu i domyślnie jest wyłączone. Włącz zakres Spot lub Futures w zarządzaniu API, a następnie odczekaj około 15 minut na propagację zmiany przed ponowieniem próby. Do tego czasu będziesz nadal widzieć błędy niewystarczających uprawnień.

4. Czy ktoś może wypłacić moje środki, jeśli ukradnie mój klucz API?

Nie w WEEX — klucze API są ograniczone tylko do odczytu i handlu, bez dostępnego uprawnienia do wypłaty. Skradziony klucz nadal mógłby składać niechciane zlecenia, dlatego biała lista IP i szybkie usuwanie kluczy są ważne, ale nie może przenieść aktywów poza platformę.

5. Czym jest błąd znacznika czasu i jak go naprawić?

Żądania są odrzucane, jeśli podpisany znacznik czasu odbiega o więcej niż 30 sekund od czasu serwera giełdy. Rozwiązaniem jest odpytanie punktu końcowego czasu serwera przy starcie aplikacji, zapisanie przesunięcia i zastosowanie go do każdego podpisu, zamiast odczytywania lokalnego zegara systemowego, który dryfuje.

6. Czy WEEX obsługuje alerty TradingView lub API FIX?

Żadne z nich nie jest obsługiwane według aktualizacji dokumentacji platformy z kwietnia 2026 r. Integracje muszą przechodzić przez interfejsy REST i WebSocket. Sprawdź aktualną dokumentację deweloperską przed budowaniem wokół tego, ponieważ obsługiwane protokoły się zmieniają.

7. Ile kluczy API może mieć jedno konto?

Do 10 grup kluczy. Wykorzystaj ten zapas — oddzielne klucze dla rozwoju, testów i produkcji oznaczają, że unieważnienie jednego skompromitowanego poświadczenia nie wyłącza całej operacji.

Ostrzeżenie o ryzyku

Aktywa kryptograficzne są wysoce zmienne, a handel nimi może prowadzić do częściowej lub całkowitej utraty kapitału. Handel API dodaje do tego odrębną warstwę ryzyka: zautomatyzowany system wykonuje błędy z prędkością maszyny, a błąd logiczny, nieaktualny kanał danych rynkowych lub brak wyłącznika bezpieczeństwa mogą kumulować straty znacznie szybciej niż handel ręczny. Pozycje futures z dźwignią otwarte przez API mogą zostać w pełni zlikwidowane. Limity stawek, utrata łączności i rozłączenie WebSocket mogą pozostawić pozycje niezarządzane dokładnie w momencie, gdy zarządzanie ma największe znaczenie. Poświadczenia API to sekrety na okaziciela — każdy, kto je posiada, może handlować na Twoim koncie, i chociaż klucze WEEX nie niosą uprawnień do wypłat, nieautoryzowany handel nadal może powodować realne straty. Testuj w trybie demo, zacznij od minimalnego rozmiaru, instrumentuj wszystko i nigdy nie wdrażaj kapitału, na którego utratę nie możesz sobie pozwolić. Nic tutaj nie jest poradą inwestycyjną.