Przewodnik integracji API WEEX: Autoryzacja, limity i pułapka 403

Większość przewodników po API giełdy kryptowalut kończy się na "utwórz klucz i skieruj na niego swojego bota". To doprowadzi Cię do pierwszego błędu -1052, a nie do działającej integracji. API WEEX to system dwuwarstwowy — spot i futures działają na różnych domenach z różnymi schematami zleceń — a błędy, które kosztują programistów najwięcej czasu, nie są natury koncepcyjnej. Są to brakujący nagłówek User-Agent, zegar, który przesunął się o 31 sekund, oraz para handlowa, która istnieje na giełdzie, ale nie jest włączona do dostępu programistycznego.

Ten przewodnik przeprowadzi Cię przez integrację API WEEX od początku do końca: co obejmuje API, jak zapewnić klucz, który Cię nie zablokuje, jak faktycznie konstruowana jest sygnatura, limity stawek, które napotkasz w produkcji, oraz konkretne błędy, które psują większość pierwszych prób. Każda liczba tutaj pochodzi z dokumentacji WEEX V3 na sierpień 2026 roku.

Co obejmuje API WEEX — a czego nadal nie

API WEEX udostępnia dwie niezależne powierzchnie REST oraz warstwę WebSocket. Nie są one wymienne i jest to pierwsza decyzja strukturalna, którą integracja musi podjąć poprawnie.

Zasięg jest realny, ale ograniczony. Ogłoszenie bety OpenAPI WEEX wymienia ponad 140 obsługiwanych par — ale podział jest nierówny: tabela futures obejmuje około 130 kontraktów wieczystych, podczas gdy lista spot to około 25 par. Jeśli Twoja strategia handluje parą spot o średniej kapitalizacji, sprawdź tę listę przed napisaniem linii kodu, ponieważ fakt, że para jest dostępna w interfejsie internetowym, nie oznacza, że akceptuje zlecenia API.

Dwa braki mają znaczenie dla każdego, kto migruje z innego miejsca. FAQ API spot WEEX, ostatnio zaktualizowane 14 kwietnia 2026 r., stwierdza jasno, że obecnie nie jest obsługiwana ani integracja FIX API, ani TradingView. Jeśli Twój stos wykonawczy zakłada sesję FIX lub alerty webhook kierowane z TradingView, musisz przebudować tę warstwę w oparciu o REST i WebSocket.

Warto również zauważyć: endpointy V1 i V2 są wycofywane, a WEEX zaleca V3 dla nowych kompilacji. Przykładowy kod, który znajdziesz na platformach botów innych firm, może nadal celować w ścieżki V2.

Jak utworzyć klucz API WEEX bez zablokowania się

Tworzenie klucza odbywa się na stronie zarządzania API WEEX w sekcji Konto. Mechanika zajmuje dwie minuty. Decyzje konfiguracyjne trwają dłużej, a trzy z nich są nieodwracalne.

1. Utwórz klucz. Każde konto obsługuje do 10 grup kluczy API. Nowe klucze są domyślnie ustawione na Read Only.
2. Wybierz uprawnienia jawnie. Readonly, Spot i Futures/Contract są niezależne. Zaznaczenie Spot nie daje dostępu do futures, a zlecenie futures wysłane na kluczu tylko dla spot zwraca -1052 INSUFFICIENT_PERMISSIONS zamiast czegoś bardziej opisowego.
3. Ustaw hasło ostrożnie. Własne wytyczne bezpieczeństwa WEEX mówią, aby używać tylko znaków alfanumerycznych — znaki specjalne w haśle są udokumentowanym źródłem błędów autoryzacji. Hasła nie można zmodyfikować ani odzyskać. Jeśli je zgubisz, utwórz nowy klucz.
4. Powiąż listę dozwolonych adresów IP. Do 10 adresów IP, oddzielonych przecinkami. Klucze bez ograniczeń stanowią największe ryzyko powiernicze w konfiguracji API, a WEEX oznacza je jako takie.
5. Czekaj. Nowo utworzone lub zmodyfikowane klucze potrzebują około 15 minut, aby rozprzestrzenić się w systemach WEEX. Programiści rutynowo interpretują to okno jako uszkodzoną sygnaturę i zaczynają przepisywać działający kod.

Przechowuj APIKey, SecretKey i Passphrase podczas tworzenia. Tylko APIKey można odzyskać później.

Jeden nawyk wart przyjęcia od pierwszego dnia: nigdy nie włączaj uprawnień związanych z wypłatami na kluczu, który żyje w procesie handlowym. Oddziel klucze tylko do odczytu do monitorowania od kluczy z uprawnieniami do handlu do egzekucji i nadaj każdemu własne powiązanie IP. Koszt operacyjny to dziesięć minut; tryb awarii, któremu zapobiega, jest całkowity.

Podpisywanie żądania API WEEX: Okno 30 sekund

Każde prywatne wywołanie API WEEX zawiera cztery nagłówki plus typ zawartości:

Wiadomość, którą podpisujesz, to konkatenacja, a reguła konkatenacji zmienia się w zależności od tego, czy istnieje ciąg zapytania:

# queryString obecny
timestamp + METHOD + requestPath + "?" + queryString + body

# queryString nieobecny
timestamp + METHOD + requestPath + body

METHOD jest wielkimi literami. body to surowy ciąg JSON, identyczny bajt po bajcie z tym, co przesyłasz — serializuj raz, podpisz ten ciąg, wyślij ten ciąg. Ponowna serializacja między podpisaniem a wysłaniem jest najczęstszym błędem sygnatury spowodowanym przez samego siebie, ponieważ kolejność kluczy lub białe znaki zmieniają się i hash już nie pasuje.

Przykład z specyfikacji sygnatury WEEX, pobierający głębokość:

1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20

Oraz zlecenie:

1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}

Następnie HMAC-SHA256 z Twoim kluczem tajnym, potem Base64.

Ograniczeniem, które łapie ludzi w produkcji, jest zegar. Żądania są odrzucane, jeśli ACCESS-TIMESTAMP odbiega o więcej niż 30 sekund od czasu serwera WEEX, zwracając -1046 ACCESS_TIMESTAMP_EXPIRED. Kontenery z dryfującymi zegarami, zimne starty serverless i maszyny wirtualne bez NTP zawodzą w ten sposób okresowo — co jest gorsze niż ciągła awaria, ponieważ wygląda jak problem sieciowy. Odpytuj endpoint czasu serwera przy starcie, przechowuj przesunięcie i stosuj je do każdego znacznika czasu.

Prywatne kanały WebSocket używają krótszej wiadomości: timestamp + "/v3/ws/private", podpisanej w ten sam sposób — te same nagłówki, te same kroki HMAC-SHA256 i Base64, tylko inny ciąg.

Limity stawek API WEEX, które faktycznie napotkasz

Przekroczenie limitu zwraca HTTP 429 i 10-sekundowy ban. WEEX dzieli limity na dwa niezależne budżety, co jest częścią, którą większość integracji modeluje niepoprawnie.

Limity stawek pochodzą z dokumentacji API spot WEEX i FAQ, aktualne na 14 kwietnia 2026 r.

Rozróżnienie, które ma znaczenie: składanie zleceń jest ograniczone przez konto, wszystko inne przez IP. Endpointy składania zleceń zużywają zero wagi IP — licznik IP w ich nagłówkach odpowiedzi wskazuje 0. Więc uruchomienie trzech strategii za jednym adresem IP nie potraja Twojego budżetu zleceń (jest on na konto), ale potraja zużycie puli IP o wadze 500 dla danych rynkowych i zapytań.

Czytaj nagłówki zamiast zgadywać. Każda odpowiedź zawiera X-USED-WEIGHT-1M i X-REMAINING-WEIGHT-1M; endpointy zleceń zawierają X-ORDER-COUNT-10S i X-ORDER-REMAINING-10S. Back-off sterowany nagłówkiem pozostałej wagi będzie działał lepiej niż jakikolwiek stały interwał uśpienia, który zakodujesz na sztywno.

Zlecenia Spot i Futures nie dzielą schematu

To jest rozbieżność, która psuje współdzielone warstwy abstrakcji i nie jest nigdzie wyraźnie zaznaczona w dokumentacji — znajdziesz ją, porównując dwie strony zleceń.

Ten ostatni wiersz zasługuje na podkreślenie. Endpoint futures może zwrócić HTTP 200 z {"success": false, "errorCode": "...", "errorMessage": "..."}. Kod, który sprawdza tylko status HTTP, zarejestruje odrzucone zlecenie jako wypełnione i radośnie przejdzie do budowania pozycji, której nie ma. Sprawdzaj success jawnie w każdej odpowiedzi zlecenia futures.

Istnieje również niespójność w samej dokumentacji. Strona Parametry publiczne API spot nadal wymienia małe litery enums (buy, sell, limit, market) obok pola force, podczas gdy endpointy zleceń V3 pod Trade używają wielkich liter BUY, SELL, LIMIT i timeInForce. Strony endpointów odzwierciedlają V3; strona parametrów zawiera wartości z ery V2. Gdy się nie zgadzają, ufaj stronie endpointu — i wysyłaj -1116 INVALID_ORDER_TYPE do swoich logów jako sygnał, że skopiowałeś z niewłaściwej.

Symbole są wrażliwe na wielkość liter i muszą być wielkimi literami. btcusdt zwraca -1121.

Pięć błędów, które psują większość integracji API WEEX

403 na WebSocket to błąd, który warto zrozumieć. Nie ma nic wspólnego z Twoimi danymi uwierzytelniającymi — krawędź WEEX odrzuca handshake bez nagłówka, więc idealnie podpisana prywatna subskrypcja zawodzi tak samo jak niepodpisana. Programiści debugują swoją sygnaturę przez godzinę, zanim to znajdą. WEEX dokumentuje to w FAQ API spot, a poprawka to jedna linijka.

Utrzymuj połączenia przy życiu poprawnie. Serwer wysyła okresowe pingi — {"event":"ping","time":"..."} na kanałach publicznych, {"type":"ping","time":"..."} na prywatnych — i oczekuje {"method":"PONG","id":1} w odpowiedzi. Pomiń więcej niż 10, a serwer zamknie połączenie. Ciche rozłączenie podczas zmiennej sesji jest sposobem, w jaki bot kończy handlując na nieaktualnej księdze.

Pełna taksonomia błędów znajduje się w FAQ API spot WEEX i odniesieniu do kodów błędów.

Testuj w trybie demo, zanim zaryzykujesz prawdziwy depozyt

WEEX dostarcza symulowane środowisko futures dostępne przez ten sam autoryzowany wzorzec, pod /capi/v3/sim/. Endpoint salda demo zwraca pozycje denominowane w SUSDT — symulowanym USDT — obok availableBalance, frozen i unrealizePnl. PlaceOrder, GetAllPositions i GetOrderHistory w demo są w pełni dostępne.

Używaj go do tego, do czego faktycznie się nadaje: walidacji konstrukcji sygnatury, obsługi błędów i logiki ponownego łączenia. Nie używaj go do walidacji ekonomii strategii. Symulowane miejsce nie ma pozycji w kolejce, zachowania częściowego wypełnienia pod wpływem stresu ani poślizgu cenowego — trzech rzeczy, które oddzielają backtest od P&L.

Dla kalibracji po stronie live: WEEX wycenił kontrakty wieczyste BTC na 65 088,80 USDT na swoim rynku futures BTC/USDT na dzień 21 sierpnia 2026 r., z dźwignią dostępną do 400×. Ten sufit dźwigni jest powodem do bycia konserwatywnym z systemem automatycznym, a nie funkcją, na której warto polegać. Błąd podpisywania, który wyzwala zduplikowane zlecenia, jest przeżywalny przy 3×. Nie jest przy 400×.

Wersja skrócona

API WEEX jest proste, gdy spełnione są trzy warunki: Twój zegar jest zsynchronizowany w oknie 30 sekund, Twój WebSocket wysyła User-Agent, a Twój kod futures sprawdza pole success zamiast statusu HTTP. Wszystko inne — uprawnienia, listy dozwolonych IP, back-off limitu stawek — to standardowa praca integracyjna giełdy.

Jedyną rzeczą, która nie jest standardowa i na którą warto przeznaczyć czas, jest rozbieżność schematu spot/futures. Współdzielona abstrakcja zleceń na obu powierzchniach będzie wyglądać poprawnie w przeglądzie, a zawiedzie w produkcji. Buduj je jako dwa adaptery.

Gotowy do startu? Utwórz klucz w sekcji Konto → Zarządzanie API na WEEX, skieruj go najpierw na tryb demo i rozszerzaj uprawnienia dopiero, gdy Twoje ścieżki ponownego łączenia i błędów zostaną sprawdzone.

FAQ

1. Czy API WEEX jest darmowe?

Tak. Nie ma oddzielnej opłaty za dostęp do API. Płacisz standardowe opłaty transakcyjne spot lub futures od zrealizowanych zleceń, tak samo jak przy handlu ręcznym.

2. Ile kluczy API mogę utworzyć na WEEX?

Do 10 grup kluczy API na konto. Każdy klucz można skonfigurować niezależnie z uprawnieniami Readonly, Spot lub Futures/Contract oraz własną listą dozwolonych adresów IP do 10 adresów.

3. Dlaczego mój klucz API WEEX działa w Postmanie, ale nie z mojego serwera?

Prawie zawsze chodzi o listę dozwolonych IP (-1056) lub dryf zegara (-1046). Środowiska chmurowe często wychodzą z rotującego IP NAT, którego nie ma na Twojej liście dozwolonych, a kontenery bez NTP dryfują poza 30-sekundowe okno sygnatury.

4. Czy API WEEX obsługuje webhooks FIX lub TradingView?

Nie. Według aktualizacji dokumentacji z kwietnia 2026 r. ani FIX API, ani integracja TradingView nie są obsługiwane. REST i WebSocket to dostępne transporty.

5. Ile czasu mija, zanim nowy klucz API WEEX zacznie działać?

Około 15 minut, aby nowy lub zmodyfikowany klucz się rozprzestrzenił. Błędy autoryzacji w tym oknie są oczekiwane i nie są problemem z sygnaturą.

6. Czy mogę testować strategie API WEEX bez prawdziwych środków?

Tak, dla futures. Endpointy demo pod /capi/v3/sim/ akceptują te same autoryzowane żądania i zwracają salda denominowane w SUSDT. Traktuj je jako zestaw testów integracyjnych, a nie backtest strategii.

Ostrzeżenie o ryzyku

Aktywa kryptowalutowe są zmienne, a handel nimi może skutkować częściową lub całkowitą utratą kapitału. Handel przez API koncentruje to ryzyko, zamiast je zmniejszać: błąd logiczny, nieobsłużone odrzucenie lub nieaktualny feed WebSocket może wykonać dziesiątki niezamierzonych zleceń, zanim człowiek to zauważy. WEEX oferuje dźwignię do 400× na niektórych kontraktach wieczystych, co powiększa zarówno poprawne, jak i błędne sygnały — system automatyczny działający na wysokiej dźwigni może zostać zlikwidowany w jednym niekorzystnym ruchu.

Ryzyka specyficzne do uwzględnienia we wdrożeniu API: ryzyko powiernicze wynikające z nieograniczonych lub wyciekłych kluczy, które dają pełną kontrolę handlową nad kontem; ryzyko operacyjne wynikające z dryfu zegara, banów limitów stawek i zerwanych połączeń, które pozostawiają pozycje niezarządzane; ryzyko płynności na rzadko handlowanych parach, gdzie zlecenie rynkowe przesuwa księgę przeciwko Tobie; oraz ryzyko kontrahenta i regulacyjne, ponieważ dostępność handlu API i konkretnych par może się zmienić bez powiadomienia. Powiąż listę dozwolonych IP, trzymaj uprawnienia do wypłat wyłączone na kluczach handlowych, ograniczaj wielkość pozycji w kodzie, a nie w intencji, i testuj ścieżki błędów w trybie demo przed wdrożeniem kapitału. Nic tutaj nie jest poradą inwestycyjną.