Przewodnik po API WEEX: od klucza API do pierwszego podpisanego zlecenia

Większość integracji API WEEX nie zawodzi z powodu logiki strategii. Zawodzą one w pierwszej godzinie na czterech rzeczach, które nie są oczywiste, dopóki się na nie nie natkniesz: klucz, który właśnie utworzyłeś, nie jest jeszcze aktywny, para, którą chcesz handlować, nie znajduje się na białej liście API, twoje połączenie WebSocket jest odrzucane, ponieważ nie wysłałeś nagłówka User-Agent, a twój podpis jest błędny o bajt, ponieważ podpisałeś ponownie zserializowane ciało zamiast dokładnego ciągu, który wysłałeś.

Ten przewodnik przeprowadzi Cię przez API WEEX od początku do końca — tworzenie kluczy, uprawnienia, zasady podpisywania, limity szybkości, kody błędów, które faktycznie wstrzymują kompilacje, oraz punkty końcowe paper-trading, które pozwalają przetestować to wszystko bez ryzykowania kapitału. Wszystko poniżej zostało sprawdzone względem dokumentacji V3 na żywo w dniu 21 sierpnia 2026 r.

Co obejmuje API WEEX: spot, futures i WebSocket

API WEEX jest podzielone na dwa niezależne produkty z dwiema niezależnymi domenami REST. Spot znajduje się pod adresem api-spot.weex.com w ścieżce /api/v3. Futures znajduje się pod adresem api-contract.weex.com w ścieżce /capi/v3. Dzielą one schemat podpisywania i zestaw nagłówków, ale nic więcej — oddzielne flagi uprawnień, oddzielne hosty WebSocket, oddzielne parametry zleceń.

Punkty końcowe dzielą się na dwie klasy dostępu. Publiczne punkty końcowe (czas serwera, głębokość arkusza zleceń, klines, stopa finansowania, tickery 24h) nie wymagają żadnego uwierzytelnienia, co czyni je najszybszym sposobem na potwierdzenie, że Twoja ścieżka sieciowa działa, zanim dotkniesz podpisywania. Prywatne punkty końcowe — salda, pozycje, zlecenia — wymagają pełnego podpisu z czterema nagłówkami przy każdym żądaniu.

W przypadku wszystkiego na poziomie ticka, WEEX kieruje Cię w stronę WebSocket zamiast odpytywania REST, i jest to słuszna decyzja: kanały publiczne przenoszą strumienie tickerów, głębokości i transakcji, a kanał prywatny przenosi aktualizacje konta, pozycji i zleceń. Odpytywanie głębokości przez REST w celu zbudowania arkusza zleceń wyczerpie Twój budżet wagi IP bez żadnych korzyści.

Jeden punkt odniesienia dla skali: na dzień 21 sierpnia 2026 r. kontrakt wieczysty BTC/USDT notował ostatnią cenę 65 088,8 USDT w arkuszu futures WEEX — ten sam tick, który zwraca Twoje wywołanie /capi/v3/market/ticker24h.

Jak utworzyć klucz API WEEX i ustawić uprawnienia

Klucze tworzy się z poziomu Konto → Zarządzanie API na platformie internetowej. Każde konto może posiadać do 10 grup kluczy API.

Tworzenie zwraca trzy wartości, a trzecia jest tą, którą ludzie tracą:

• APIKey — publiczny identyfikator, wysyłany w nagłówku ACCESS-KEY.
• SecretKey — sekret podpisywania HMAC. Pokazywany tylko raz.
• Passphrase — zdefiniowana przez użytkownika, wysyłana w ACCESS-PASSPHRASE. Nie można jej zmienić ani odzyskać. Jeśli ją zgubisz, tworzysz klucz od nowa.

Trzy szczegóły konfiguracji powodują więcej zgłoszeń do pomocy technicznej niż wszystko inne razem wzięte:

1. Nowe klucze domyślnie są w trybie Tylko do odczytu. Uprawnienie do handlu to oddzielne pole wyboru i jest specyficzne dla produktu — Spot dla handlu spot, Futures dla kontraktów. Zaznaczenie jednego nie włącza drugiego. Złożenie zlecenia na kluczu Tylko do odczytu zwraca -1052.
2. Klucze potrzebują około 15 minut na globalną propagację. Klucz, który uwierzytelnia się poprawnie, a następnie zawodzi w innym punkcie końcowym, zazwyczaj po prostu nie jest jeszcze w pełni aktywny. Poczekaj, zanim zaczniesz debugować swój podpis.
3. Utrzymuj hasło (passphrase) alfanumeryczne. WEEX wyraźnie zaleca brak znaków specjalnych. Niezgodności kodowania w znakach specjalnych to wyjątkowo uciążliwa klasa błędów do śledzenia.

Powiąż białą listę IP, gdy jesteś na ekranie tworzenia. Niepowiązany klucz to poświadczenie, które działa z dowolnego miejsca w Internecie, a jeśli maszyna, która go posiada, zostanie przejęta, biała lista jest jedyną rzeczą stojącą między atakującym a Twoimi pozycjami.

API spot WEEX vs API futures: różnice, które mają znaczenie

To jest tabela, którą warto mieć otwartą podczas budowania. Oba produkty wyglądają symetrycznie, ale takie nie są.

Dwa z tych punktów są najbardziej krytyczne. Futures wymaga newClientOrderId przy każdym zleceniu, więc baza kodu stworzona pod spot, która go pomija, zostanie odrzucona w momencie skierowania jej na kontrakty. A POST_ONLY istnieje tylko w futures — strategia typu maker-only napisana pod API spot nie ma natywnego sposobu, aby zagwarantować, że nie przekroczy spreadu.

Parametry TP/SL w futures zasługują na więcej uwagi, niż zazwyczaj otrzymują. Dołączenie tpTriggerPrice i slTriggerPrice do zlecenia wejścia oznacza, że Twój stop istnieje na giełdzie od momentu otwarcia pozycji, zamiast być umieszczanym przez kolejne wywołanie, które może nie przetrwać awarii procesu lub partycji sieciowej. Możesz również wybrać źródło wyzwalania dla każdej nogi przez TpWorkingType i SlWorkingType — MARK_PRICE dla stopa jest bezpieczniejszym domyślnym ustawieniem, ponieważ CONTRACT_PRICE może zostać podbity przez pojedynczą transakcję na mało płynnej parze.

Jak poprawnie podpisać żądanie API WEEX

Każde prywatne wywołanie przenosi cztery nagłówki: ACCESS-KEY, ACCESS-SIGN, ACCESS-PASSPHRASE, ACCESS-TIMESTAMP, plus Content-Type: application/json.

Zasada podpisywania jest identyczna w obu domenach. Zbuduj ten ciąg:

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

Pomiń ? i queryString, gdy nie ma parametrów zapytania; pomiń body, gdy go nie ma. Zastosuj HMAC-SHA256 z Twoim SecretKey, a następnie zakoduj wynik w Base64.

import base64, hashlib, hmac, json, time, requests

API_KEY, SECRET, PASSPHRASE = "...", "...", "..."
BASE = "https://api-contract.weex.com"
path = "/capi/v3/order"
body = json.dumps({
    "symbol": "BTCUSDT", "side": "BUY", "positionSide": "LONG",
    "type": "LIMIT", "timeInForce": "GTC", "quantity": "0.01",
    "price": "60000", "newClientOrderId": "my-order-0001",
}, separators=(",", ":"))

ts = str(int(time.time() * 1000))
message = ts + "POST" + path + body
sign = base64.b64encode(
    hmac.new(SECRET.encode(), message.encode(), hashlib.sha256).digest()
).decode()

r = requests.post(BASE + path, data=body, headers={
    "ACCESS-KEY": API_KEY, "ACCESS-SIGN": sign,
    "ACCESS-PASSPHRASE": PASSPHRASE, "ACCESS-TIMESTAMP": ts,
    "Content-Type": "application/json",
})

Zwróć uwagę na data=body, a nie json=payload. Podpisz dokładne bajty, które przesyłasz. Jeśli Twój klient HTTP ponownie zserializuje słownik — zmieniając kolejność kluczy lub wstawiając spacje po separatorach — serwer obliczy inny skrót i otrzymasz -1047, bez żadnej wskazówki, że przyczyną była spacja.

Okno czasowe wynosi 30 sekund względem czasu serwera WEEX. Jeśli zegar Twojego hosta dryfuje, żądania zaczynają sporadycznie zawodzić w sposób, który wygląda jak błąd podpisywania. Wywołaj GET /capi/v3/market/time i śledź przesunięcie zamiast ufać czasowi lokalnemu.

Prywatne kanały WebSocket podpisują się inaczej i to łapie ludzi: wiadomość to tylko timestamp + requestPath, gdzie requestPath to /v3/ws/private. Brak metody, brak ciała.

Jedna osobliwość dokumentacji, którą warto znać przed kopiowaniem: strona Signature dla futures ilustruje zasadę przy użyciu ścieżek spot (/api/v3/order). Zasada jest poprawna; przykładowe ścieżki nie są tymi dla futures. Użyj /capi/v3/..., gdy jesteś w domenie kontraktów.

Limity szybkości API WEEX: dwa koszyki, nie jeden

WEEX prowadzi dwa niezależne liczniki limitów szybkości, a ich mylenie jest powodem, dla którego boty otrzymują nieoczekiwane błędy 429.

Istotny szczegół: składanie zleceń zużywa zero wagi IP, a anulowania i zapytania zużywają zero liczby zleceń. Są to naprawdę oddzielne rejestry. Pętla market-makingowa, która agresywnie składa i anuluje zlecenia, wyczerpie koszyk ZLECENIA przy składaniu, podczas gdy jej ruch anulujący po cichu drenuje wagę IP — a żaden licznik nie ostrzega o drugim.

Czytaj nagłówki zamiast liczyć żądania po stronie klienta. X-REMAINING-WEIGHT-1M i X-ORDER-REMAINING-1M wracają przy każdym wywołaniu i odzwierciedlają widok serwera, który jest jedynym istotnym widokiem. Przekroczenie limitu zwraca HTTP 429 i wyzwala 10-sekundowy ban, a dalsze próby mimo błędu 429 to najszybsza droga do wyłączenia dostępu do API przez kontrolę ryzyka.

Jeśli uruchamiasz kilka strategii z jednej maszyny, pamiętaj, że koszyk IP jest współdzielony. Dwa boty na jednym serwerze rywalizują o te same 500 wagi na 10 sekund.

Błędy API WEEX, które wstrzymują większość integracji

Odpowiedzi o błędach to para kod i komunikat. Oto te, które pojawiają się podczas integracji, a nie w produkcji:

-1058 zasługuje na konkretny przepływ pracy. Nie każdy kontrakt WEEX jest włączony do handlu API i nie ma sposobu, aby wywnioskować to z interfejsu. Wywołaj GET /capi/v3/market/apiTradingSymbols przy starcie, zbuforuj tablicę i waliduj symbole, zanim strategia zbuduje zlecenie. Ta jedna kontrola eliminuje całą klasę błędów w czasie wykonywania.

Jeszcze dwa, które wyglądają jak błędy, a nimi nie są. Uścisk dłoni WebSocket zwracający 403 prawie zawsze oznacza, że pominąłeś nagłówek User-Agent — treść jest dowolna, ale firewall odrzuca połączenia bez niego. Dokumentacja jest obecnie niezgodna w kwestii błędów anulowania: referencja kodów błędów mapuje -1054 na ogólny błąd systemu, a -3200 na "zlecenie nie istnieje", podczas gdy FAQ futures przypisuje "zlecenie nie istnieje" do -1054. Obsługuj oba kody na ścieżkach anulowania zamiast rozgałęziać się na jeden.

Testuj najpierw na punktach końcowych paper-trading WEEX

WEEX dodał punkty końcowe symulowanego handlu w domenie futures i odzwierciedlają one powierzchnię na żywo wystarczająco blisko, aby być prawdziwym testem na sucho, a nie zabawką:

• GET /capi/v3/sim/balance — symulowane salda, denominowane w SUSDT
• GET /capi/v3/sim/position/allPosition — pozycje, w tym pary long/short w trybie hedge
• POST /capi/v3/sim/order — składanie zleceń przez typowe typy
• GET /capi/v3/sim/order/history — historyczne symulowane wypełnienia

Ta sama domena, te same nagłówki, ta sama zasada podpisywania. Zamiana /capi/v3/order na /capi/v3/sim/order jest często jedyną zmianą potrzebną do przeprowadzenia pełnego testu integracyjnego.

Użyj ich do walidacji części systemu, które psują się tylko w rzeczywistych warunkach: logika ponownego połączenia po zerwanym WebSocket, czy Twoja maszyna stanów zlecenia odzyskuje sprawność, gdy wypełnienie przychodzi przed potwierdzeniem REST, czy Twoje ustalanie wielkości pozycji działa poprawnie przy limicie dźwigni. To są błędy, które kosztują pieniądze w produkcji, a żaden z nich nie wymaga prawdziwego kapitału, aby się ujawnić.

Warto wiedzieć przed architekturą wokół nich: WEEX obecnie nie wspiera ani wykonywania webhooków TradingView, ani bramki FIX. Jeśli Twoja strategia zakładała jedno z nich, zaplanuj zamiast tego REST i WebSocket.

Podsumowanie

API WEEX jest proste, gdy zrozumiesz, że spot i futures to dwa produkty dzielące schemat podpisywania i prawie nic więcej. Zadbaj o cztery nagłówki, podpisz dokładne bajty, które wysyłasz, zbuforuj białą listę symboli handlowych API, czytaj nagłówki limitów szybkości zamiast liczyć żądania i obsługuj -1047, -1052 oraz -1058 jawnie — to pokrywa większość problemów.

Sekwencja, która marnuje najmniej czasu: utwórz klucz z uprawnieniem Tylko do odczytu, potwierdź, że publiczny punkt końcowy odpowiada, uruchom jedno podpisane prywatne odczytywanie, uruchom pełną strategię przeciwko punktom końcowym paper-trading i dopiero wtedy włącz uprawnienie do handlu i powiąż białą listę IP. Pełne referencje punktów końcowych znajdują się w dokumentacji API futures WEEX oraz dokumentacji API spot WEEX, ze szczegółami uprawnień i limitów szybkości zebranymi w FAQ API futures.

FAQ

1. Czy potrzebuję oddzielnych kluczy API WEEX dla spot i futures?

Nie — jeden klucz może posiadać oba uprawnienia. Ale są to oddzielne pola wyboru i każde jest domyślnie wyłączone. Klucz z zaznaczonym tylko Spot zwróci -1052 przy każdym zleceniu futures i odwrotnie.

2. Jakie są limity szybkości API WEEX?

Dwa niezależne koszyki: 500 wagi na 10 sekund na IP dla ogólnych punktów końcowych REST i 300 zleceń na minutę na konto dla futures. WebSocket jest ograniczony do 20 jednoczesnych połączeń na IP, 100 kanałów na połączenie. Przekroczenie któregokolwiek zwraca HTTP 429 i 10-sekundowy ban.

3. Dlaczego mój klucz API WEEX zwraca -1049 zaraz po utworzeniu?

Nowe i zmodyfikowane klucze potrzebują około 15 minut na propagację w systemach WEEX. Jeśli klucz jest świeży, poczekaj przed dalszym debugowaniem. Jeśli problem nadal występuje, sprawdź, czy hasło zawiera znaki specjalne — WEEX zaleca tylko alfanumeryczne.

4. Czy mogę handlować każdą parą WEEX przez API?

Nie. Tylko pary na białej liście handlu API są dostępne programowo. Wywołaj GET /capi/v3/market/apiTradingSymbols dla aktualnej listy; wszystko poza nią zwraca -1058.

5. Czy WEEX wspiera alerty TradingView lub FIX?

Żadne z nich nie jest wspierane według aktualizacji dokumentacji z kwietnia 2026 r. Automatyzacja działa przez API REST i WebSocket.

6. Jak przetestować strategię API WEEX bez ryzykowania środków?

Użyj punktów końcowych paper-trading futures pod /capi/v3/sim/. Akceptują one to samo uwierzytelnienie i podpisywanie co punkty końcowe na żywo i rozliczają się w symulowanym SUSDT.

Ostrzeżenie o ryzyku

Aktywa kryptowalutowe są zmienne i mogą szybko tracić na wartości; handel nimi może skutkować częściową lub całkowitą utratą kapitału. Handel API koncentruje to ryzyko, zamiast je zmniejszać. Zautomatyzowane systemy mogą złożyć setki zleceń, zanim człowiek zauważy błąd, a błąd podpisu, nieaktualny kanał cenowy lub nieobsłużone ponowne połączenie mogą otworzyć pozycje, których nikt nie zamierzał. Handel futures dodaje ryzyko dźwigni: przy dźwigni dostępnej do 400× na niektórych kontraktach WEEX, niekorzystne ruchy mogą zlikwidować pozycję w kilka sekund, a użycie CONTRACT_PRICE jako wyzwalacza stop na płytkim rynku naraża Cię na stop-outy wywołane knotami świec. Klucze API to także ryzyko powiernicze — niepowiązany klucz z uprawnieniem do handlu to aktywne poświadczenie, które działa z dowolnego IP w Internecie. Powiąż białą listę IP, trzymaj uprawnienia do handlu wyłączone, dopóki integracja nie zostanie przetestowana na punktach końcowych paper-trading i ustalaj wielkość pozycji z założeniem, że Twój własny kod w końcu zacznie działać nieprawidłowo.