API bota handlowego Hyperliquid: projektowanie i testy

Granice API bota handlowego Hyperliquid

Publiczne API oddziela żądania informacyjne od podpisanych działań giełdowych. Zbuduj porównywalną granicę w aplikacji. Komponent pobierający metadane rynku nie powinien automatycznie otrzymywać uprawnień handlowych, a ekran wyświetlający salda nie powinien potrzebować dostępu do prywatnych danych podpisywania.

Przedstawiaj operacje odczytu i operacje zmieniające stan jako różne możliwości. Umożliwia to testowanie obserwacji i analizy przy niedostępnej możliwości handlu. Pozwala też aplikacji odrzucić nieoczekiwane działanie przed dotarciem do dowolnego modułu podpisującego, zamiast liczyć na odmowę dalszego API.

Adapter API powinien zwracać reszcie programu uporządkowane fakty. Unikaj udostępniania luźno typowanego obiektu, który każda strategia interpretuje inaczej. Jeśli jeden komponent traktuje brakujące pole jako zero, a drugi jako niewiadomą, ta sama odpowiedź może autoryzować sprzeczne decyzje.

Ustal poprawną reprezentację aktywa

Identyfikatory tokenów spot HyperCore, identyfikatory par i identyfikator aktywa używany w działaniu zlecenia nie są zamienne. Ustal bieżące metadane dla wybranego środowiska i zachowuj powiązanie użyte w propozycji. Skopiowanie przykładu liczbowego z dokumentacji do innego rynku lub środowiska nie jest wiarygodną metodą identyfikacji.

Typowany wewnętrzny zapis rynku może zawierać osobno czytelny symbol, aktywo bazowe, aktywo kwotowania, środowisko i identyfikator wykonania. Zapobiega to przypadkowemu użyciu etykiety interfejsu jako argumentu wykonania. Ułatwia też wykrywanie zmian schematu, ponieważ każde pole ma określony cel.

Opis tożsamości aktywów oferuje przydatną podstawę pojęciową. W teście integracji celowo podaj identyfikator tokena tam, gdzie oczekiwany jest identyfikator pary, i sprawdź odrzucenie niezgodności przez aplikację. Test używający tylko jednego dobrze znanego aktywa może nigdy nie ujawnić tej klasy błędu.

Oddziel tożsamość konta od tożsamości podpisującego

Konto, którego salda są odczytywane, może różnić się od agenta API podpisującego dla niego dozwolone działania. Obecna dokumentacja wyraźnie rozróżnia te role. Modeluj je jako osobne pola, zamiast polegać na jednej zmiennej nazwanej „portfel”, oznaczającej wszędzie obie rzeczy.

Zweryfikuj również tryb konta. Dla kont zunifikowanych i kont z depozytem zabezpieczającym dla portfela udokumentowana odpowiedź spotClearinghouseState reprezentuje salda handlowe obejmujące produkty spot i perpetual. Strategia skupiona na spot nadal musi uwzględniać odpowiednie zobowiązania między tymi produktami przy ocenie dostępnych zasobów.

Ten podział ma znaczenie podczas rozwiązywania problemów. Pusty wynik zapytania o konto może odzwierciedlać niepoprawny wybór adresu. Nie powinien natychmiast uruchamiać instrukcji zasilenia ani resetu salda. Najpierw ustal, o które konto zapytano i czy odpowiada kontu wskazanemu w zatwierdzonym zamiarze handlowym.

Używaj jawnego kontekstu przy obsłudze subkont lub innych obsługiwanych układów kont. Wywołujący powinien określać konto docelowe, a rejestr podpisujących ustalać zatwierdzone uprawnienie dla tego kontekstu. Nie pozwalaj domyślnemu kontu po cichu zastępować brakującego pola konta w żądaniu zmieniającym stan.

Traktuj podpisywanie jako implementację protokołu

Dokumentacja podpisywania opisuje więcej niż jeden schemat i podkreśla szczegóły serializacji. Podpis, z którego można lokalnie odzyskać tożsamość podpisującego, sam w sobie nie dowodzi, że usługa zdalna zinterpretuje zamierzone dane żądania. Implementacja musi odpowiadać rzeczywistemu formatowi działania, środowisku i reprezentacji kanonicznej.

Używaj przejrzanego, wersjonowanego kodu podpisywania i testuj go na znanych danych testowych. Zachowuj niepodpisane kanoniczne dane żądania do sprawdzenia w formie wykluczającej sekrety. Przykład testowy powinien ujawniać podpisane pola publiczne i to, jak zmiana jednego pola zmienia wynikową wiadomość do autoryzacji.

Nie diagnozuj problemów przez wypisywanie kluczy prywatnych, fraz odzyskiwania lub obiektów zawierających sekrety. Błędy mogą zawierać publiczne identyfikatory kont, kategorie działań i bezpieczny identyfikator korelacji. Celem diagnostyki jest wyjaśnienie niezgodności, a nie odtworzenie uprawnień podpisywania w każdym miejscu docelowym dzienników.

Koordynuj nonce według uprawnień podpisywania

Wartości nonce działań HyperCore nie podlegają zwykłemu sekwencyjnemu modelowi nonce transakcji Ethereum. Integracja powinna używać udokumentowanych reguł właściwych podpisującemu i koordynować wszystkie procesy współdzielące tożsamość podpisującą. Osobne strategie nie są niezależnymi domenami nonce tylko dlatego, że ich ustawienia pojawiają się na różnych ekranach.

Trwały koordynator nonce może zapewnić jedną ścieżkę przydziału dla zatwierdzonych działań. Testuj współbieżne żądania, restarty procesów i zmiany zegara. Koordynator powinien zapobiegać przypadkowemu ponownemu użyciu bez założenia, że zegar systemowy zawsze płynnie przesuwa się naprzód lub żądania nadchodzą w kolejności utworzenia.

Cykl życia agenta zasługuje na własną procedurę. Oficjalne wskazówki ostrzegają przed ponownym użyciem adresów wyrejestrowanych agentów po możliwym usunięciu ich stanu nonce. Traktuj wymianę poświadczeń jako kontrolowaną zmianę z nowymi uprawnieniami i uzgadnianiem, a nie okazję do ponownego użycia starych podpisanych wiadomości.

Zachowuj zamierzone wartości dziesiętne

Ceny i ilości potrzebują precyzji właściwej rynkowi. Binarna arytmetyka zmiennoprzecinkowa może zmienić wartość dziesiętną przed serializacją, więc używaj dokładnej reprezentacji wartości, których precyzja wpływa na autoryzację. Wartość przejrzana przez użytkownika lub regułę powinna być tą samą wartością przekazaną do warstwy podpisywania.

Zaokrąglanie jest decyzją, a nie późniejszą kwestią formatowania. Zaokrąglenie ilości zakupu w górę może zwiększyć wydatek. Zaokrąglenie ceny limit w niekorzystnym kierunku może zmienić maksymalny akceptowany koszt. Określ dozwolony kierunek i po zaokrągleniu ponownie sprawdź wynikową kwotę względem limitu strategii.

Dla przykładowej ilości 12,3456 przy dozwolonym kroku 0,01 ilość zaokrąglona w dół wynosi 12,34. Dopuszczalność tego wyniku nadal zależy od innych ograniczeń wybranego rynku. Przejście jednej kontroli precyzji nie dowodzi poprawności lub odpowiedniości ekonomicznej całego zlecenia.

Obsługa zleceń w API bota handlowego Hyperliquid

Obsługa zleceń w API bota handlowego Hyperliquid powinna odróżniać odpowiedzi transportu od wyników poszczególnych działań. Normalna odpowiedź HTTP może zawierać odrzucenie na poziomie zlecenia, a przyjęte zlecenie może pozostać otwarte zamiast w pełni się zrealizować. Normalizuj te różnice do stanów konsekwentnie używanych przez strategię.

Zachowuj identyfikator zamierzonego działania, wszelki identyfikator zlecenia klienta, zwróconą tożsamość zlecenia i zaobserwowany wynik. Każdy pełni inną rolę. Identyfikator wygenerowany przez klienta pomaga powiązać pracę, ale jego obecność nie usuwa potrzeby odpytywania i uzgadniania niepewnego wyniku zgodnie z rzeczywistą semantyką interfejsu.

Przewodnik po obsłudze systemu automatycznego wyjaśnia, dlaczego niepewność potrzebuje pełnoprawnego stanu. Unikaj ścieżek kodu, w których każdy wyjątek oznacza niepowodzenie, a każdy brak wyjątku zakończenie. Te dwa skróty mogą odpowiednio tworzyć zduplikowane działania lub ukrywać niezrealizowane zobowiązania.

Waliduj całe żądania przed wysłaniem

Walidator żądania powinien badać pełny kontekst: środowisko, konto, instrument, typ działania, precyzję, wielkość, warunek ceny, budżet i uprawnienie. Walidacja pól osobno jest konieczna, lecz niewystarczająca. Dwa poprawne pola nadal mogą tworzyć niepoprawne połączenie, na przykład identyfikator jednego środowiska i podpisujący skonfigurowany dla innego.

Na tej granicy twórz przydatne powody odrzucenia. „Instrument nieobsługiwany w wybranym środowisku” daje więcej podstaw do działania niż ogólny błąd API wykryty później. Oddziel odrzucenie wynikające z zasad biznesowych od nieprawidłowych danych, aby monitorowanie odróżniało normalną dyscyplinę strategii od usterek integracji.

Walidator powinien też odrzucać nieznane pola działania, gdy aplikacja oczekuje stałego schematu. Ciche przekazywanie dowolnych dodatkowych pól utrudnia kontrolę aktualizacji i niezaufanych danych wejściowych. Świadomie przeglądaj nowo obsługiwane pola, w tym ich wpływ na opłaty, uprawnienia lub znaczenie istniejącego zlecenia.

Modeluj partie bez utraty poszczególnych wyników

Grupowanie w partie może zmniejszać narzut komunikacji, ale nie uzasadnia traktowania wszystkich zawartych działań jako jednego nierozróżnialnego wyniku. Zachowuj indeks lub tożsamość każdego żądanego działania i przypisuj każdą odpowiedź do poprawnego zamiaru. Częściowa awaria partii nie może powodować odtwarzania w ciemno już przyjętej pracy.

Testuj nietypowe połączenia, takie jak jedno poprawne działanie, jeden błąd precyzji i jedno działanie niespełniające ograniczenia biznesowego. Aplikacja powinna rozumieć, czy interfejs odrzucił całą partię, czy zwrócił osobne wyniki. To zachowanie musi wynikać z udokumentowanego schematu i zaobserwowanych dowodów testowych, a nie założeń.

Ta sama dyscyplina dotyczy partii anulowania. Anulowanie kilku zleceń nie dowodzi, że żadne nie zrealizowało się przed anulowaniem. Uzgodnij każde zlecenie i powiązane realizacje przed aktualizacją aktywów lub zwolnieniem całej zarezerwowanej kwoty.

Przywracaj stan po utracie odpowiedzi

Przekroczenie czasu oczekiwania po wysłaniu tworzy problem informacyjny. Zdalny system mógł przyjąć działanie, mimo że klient nie otrzymał wyniku. Procedura przywracania powinna używać zapisanego zamiaru i dostępnych dowodów zlecenia do zbadania sytuacji przed decyzją o zasadności nowego działania.

Jeden hipotetyczny test usterki może zatrzymać klienta natychmiast po opuszczeniu procesu przez żądanie. Po restarcie system powinien znaleźć zamiar w stanie wysyłania, zachować rezerwację zasobów i rozpocząć uzgadnianie. Nie powinien resetować zamiaru do stanu bez próby tylko dlatego, że nie zapisano odpowiedzi.

Określ, jak długo nierozstrzygnięta praca może pozostać w tym stanie i co blokuje. Ścieżka eskalacji z określonymi granicami jest lepsza zarówno od bezterminowego cichego czekania, jak i natychmiastowych ponowień. Operator potrzebuje informacji pozwalających odróżnić chwilowe opóźnienie obserwacji od trwałej niespójności wymagającej zbadania.

Łącz strumienie ponownie z planem stanu

Subskrypcja WebSocket jest mechanizmem transportu, a nie trwałą gwarancją kompletności lokalnego obrazu konta. Ponowne połączenie może obejmować początkowe migawki, nowe zdarzenia i brakujące przedziały. Używaj udokumentowanego znaczenia kanału do ustalenia sposobu łączenia tych obserwacji bez duplikowania realizacji lub utraty zmian.

Utrzymuj jasne rozróżnienie między otrzymaną wiadomością a zastosowanym przejściem stanu. Jeśli to samo zdarzenie zostanie zaobserwowane ponownie, dwukrotne zastosowanie może podwoić raportowane aktywa lub koszty. Stałe identyfikatory zdarzeń i trwały zapis zastosowania pomagają uczynić odtwarzanie bezpiecznym.

Sygnał kontrolny może wykazywać aktywne połączenie, podczas gdy określony rynek przestał się aktualizować. Śledź aktualność według odpowiedniego strumienia danych, a nie tylko aktywności gniazda. Strategia powinna wiedzieć, czy obserwacje arkusza, konta i wykonania są dostatecznie aktualne dla zamierzonych zastosowań.

Planuj z uwzględnieniem ograniczonej historii

Odpowiedź API może zwracać ograniczony zbiór niedawnych zapisów zamiast wyczerpującej historii konta. Projektuj pobieranie według udokumentowanych limitów stronicowania i przechowywania. Odpowiedź bez dodatkowych elementów nie powinna automatycznie dowodzić odtworzenia całego wcześniejszego okresu.

Przechowuj historię potrzebną do lokalnego uzgadniania i oceny w miarę jej napływu. Wyraźnie zapisuj granice pokrycia i luki. Jeśli późniejsze przywracanie nie może pobrać brakującego przedziału, raport powinien wskazywać lukę, zamiast wypełniać ją zerową aktywnością.

Na przykład różnicę salda konta może wyjaśniać transfer poza dostępną historią realizacji. Poprawnym wnioskiem jest potrzeba dalszych dowodów. Utworzenie syntetycznej transakcji dla wymuszenia zgodności ewidencji zanieczyściłoby zarówno zapisy operacyjne, jak i późniejszą ocenę strategii.

Przydziel budżet żądań

Limity żądań mogą obowiązywać na kilku poziomach i z różnymi wagami. Zbuduj budżet dla rzeczywistej mieszanki zapytań rynkowych, odczytów konta, subskrypcji i podpisanych działań. Jedno oszacowanie żądań na sekundę prawdopodobnie nie opisuje każdego istotnego ograniczenia lub wzorca nagłych skoków.

Stawiaj przywracanie i wiedzę o koncie przed opcjonalnymi widokami. Jeśli aplikacja zbliża się do limitu, ograniczenie zbędnych odświeżeń rynku może zachować zasoby do zbadania nierozstrzygniętego działania. Pętla ponowień z wykładniczym odstępem, ale bez globalnego budżetu, może pogorszyć pierwotną awarię przez zużywanie zasobów potrzebnych do przywrócenia działania.

Podczas testów mierz rzeczywiste liczby wywołań i kategorie błędów. Przewodnik po projektowaniu API omawia ogólne budżetowanie żądań i zbieranie dowodów; zachowuj odrębne metody i limity sieci docelowej. Idee inżynieryjne mogą przenosić się między sieciami, podczas gdy limity liczbowe i schematy odpowiedzi zazwyczaj nie.

Oddziel błędy API od odrzuceń strategii

Cena poza dozwolonym zakresem strategii nie jest awarią usługi. Nieprawidłowy podpis nie jest słabym sygnałem handlowym. Dobrze zorganizowana klasyfikacja błędów rozdziela te niepowodzenia, aby operator mógł reagować na rzeczywisty problem.

Przydatne kategorie obejmują lokalną walidację, autoryzację, transport, zdalny schemat, odrzucenie zlecenia i niezgodność uzgadniania. Każda kategoria może mieć inne zasady ponawiania. Odczyt transportowy można ponowić z rosnącym odstępem, a nieautoryzowane działanie powinno pozostawać zablokowane do zmiany bazowego uprawnienia lub żądania.

Unikaj automatycznego poluzowania limitów po powtarzanych niepowodzeniach. Jeśli zlecenie stale narusza ograniczenie ceny, zwiększenie tolerancji zmienia ekonomiczne zachowanie strategii. Ta decyzja należy do przejrzanej aktualizacji zasad, a nie ogólnej obsługi wyjątków mającej podtrzymać działanie programu.

Testowanie API bota handlowego Hyperliquid

Testowanie API bota handlowego Hyperliquid powinno obejmować testy kontraktowe schematów, deterministyczne przykłady podpisywania, symulowane przejścia konta i kontrole w kontrolowanym środowisku. Każda warstwa odpowiada na inne pytanie. Przykład schematu może dowodzić poprawnego parsowania pola; nie może dowodzić realizacji przyszłego zlecenia na żywo.

Używaj celowo nieprawidłowych i niepełnych przykładów obok udanych odpowiedzi. Usuń wymagane pole tożsamości, zmień reprezentację dziesiętną, zduplikuj zdarzenie i zwróć nieznany status. Adapter powinien jasno zgłaszać błąd lub zachowywać niepewność, zamiast po cichu mapować każdą nową wartość na sukces.

Izoluj uprawnienia testowe. Zestaw testów potrzebujący tylko parsowania i oceny strategii nie powinien mieć możliwości podpisywania. Przy testowaniu integracji właściwej środowisku oznaczaj je wyraźnie i zapobiegaj przełączaniu konfiguracji na inne środowisko w razie niedostępności żądanej usługi.

Testuj anulowanie przy zmieniającym się koncie

Anulowanie jest szczególnie przydatne do testowania wyścigów, ponieważ zlecenie może się zmieniać podczas przesyłania żądania. Wyobraź sobie hipotetyczne zlecenie na 60 tokenów. Klient ostatnio zaobserwował 20 zrealizowanych, a następnie żąda anulowania. Zanim żądanie zacznie działać, realizuje się kolejne 10. Ostateczna pozycja wynosi 30 tokenów, nawet jeśli samo anulowanie pozostałej ilości się powiedzie.

Test powinien więc sprawdzać zarówno końcowy stan zlecenia, jak i końcowe aktywa. Sprawdzenie tylko normalnego zakończenia metody anulowania pomija wynik ekonomiczny. Zachowuj realizacje nadchodzące przed odpowiedzią anulowania, podczas niej i po niej, pozwalając uzgadnianiu ustalić pełny zaobserwowany wynik. Sekwencja powiadomień klienta może różnić się od kolejności zdarzeń rynkowych.

Odróżniaj też anulowanie od instrukcji sprzedaży. Usunięcie zobowiązania kupna nie pozbywa się już nabytych tokenów. Ekran przywracania łączący oba pod jedną etykietą może skłonić operatora do przekonania o zniknięciu ekspozycji, gdy zatrzymano tylko przyszłe wykonanie.

Przykład przywracania wyjścia perpetual stosuje ten sam przegląd wyścigu do instrukcji wyłącznie zmniejszającej pozycję, gdzie końcową pozycję instrumentu pochodnego trzeba ustalić przed określeniem wielkości kolejnego zamknięcia.

Twórz użyteczne zapisy diagnostyczne bez sekretów

Dobry zapis diagnostyczny zawiera kategorię działania, bezpieczne odniesienie do konta, środowisko, tożsamość instrumentu, identyfikator korelacji, znaczniki czasu i znormalizowany wynik. Powinien wyjaśniać etap niepowodzenia i możliwość pozostałego skutku ekonomicznego. Te informacje można zbierać bez przechowywania prywatnych danych autoryzujących działania.

Usuwanie wrażliwych danych musi następować przed dotarciem danych do wspólnej usługi dzienników, raportu awarii lub załącznika dla pomocy. Filtrowanie tylko widoku użytkownika pozostawia inne kopie bez zmian. Testuj ścieżkę diagnostyczną z rozpoznawalnymi fikcyjnymi sekretami i sprawdzaj, że te ciągi nigdy nie występują w eksportowanych zapisach. To przydatna kontrola bezpieczeństwa, ponieważ mierzy rzeczywisty przepływ informacji, zamiast zakładać gwarancję tajności na podstawie nazwy zmiennej.

Znaczenie ma też okres przechowywania. Zachowuj dość dowodów do badania nierozstrzygniętej pracy i oceny niezawodności operacyjnej, ale unikaj bezcelowego kopiowania każdego żądania na czas nieokreślony. Publiczne identyfikatory transakcji i zleceń nadal mogą ujawniać aktywność konta. Eksport powinien być świadomy, zrozumiały i ograniczony do badania, które ma wspierać.

Wersjonuj adapter i jego dowody

Zmiany biblioteki klienta, schematu odpowiedzi lub procedury podpisywania mogą zmieniać zachowanie niezależnie od strategii handlowej. Zapisuj wersje adaptera obok wersji strategii w dzienniku operacyjnym. Pozwala to ustalić, czy nowa awaria zaczęła się po zmianie infrastruktury, a nie rynku.

Oceniaj aktualizacje na zapisanych reprezentatywnych odpowiedziach i przypadkach niekorzystnych. Dodaj nowy przykład testowy, gdy incydent ujawni nieobsłużony warunek, a następnie sprawdź zachowanie wcześniejszych oczekiwanych wyników po naprawie. Unikaj testów jedynie powtarzających szczegóły implementacji bez sprawdzania znaczącego wyniku konta lub działania.

Integracja API bota handlowego Hyperliquid jest kompletna tylko w praktycznym sensie zdefiniowania i przetestowania obsługiwanych operacji przy widoczności nieobsługiwanych przypadków. Najbardziej przydatnym osiągnięciem inżynieryjnym nie jest udane pierwsze żądanie. Jest nim spójny łańcuch dowodów łączący zamierzone działanie, użyte uprawnienia, wynik zdalny i następujący po nim stan konta.