Tworzenie zapytania webhook

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Webhooki to niezwykle elastyczne i potężne narzędzie do automatyzacji handlu na platformie Psyll, umożliwiające szybkie i precyzyjne składanie zleceń na giełdzie za pomocą standardowych zapytań HTTP POST. Ta metoda pozwala na integrację z zewnętrznymi systemami, takimi jak TradingView, i tworzenie w pełni automatycznych strategii handlowych.

W tym rozdziale szczegółowo omówimy, jak konstruować zapytania, jakie są typy akcji, a także przedstawimy praktyczne przykłady użycia, potencjalne ograniczenia oraz scenariusze błędów.

Struktura zapytania webhook

Każde zapytanie do webhooka Psyll musi być sformatowane w postaci obiektu JSON i zawierać trzy podstawowe pola:

  • action - Typ operacji, którą system ma wykonać. Możliwe wartości to: BUY, SELL, SET.
  • quantity - Liczba jednostek aktywa, która ma być kupiona, sprzedana lub ustawiona. Obsługiwane są wartości ułamkowe, co pozwala na bardzo precyzyjne sterowanie pozycją.
  • symbol - Symbol pary handlowej zgodny z konwencją giełdy (np. BTCUSDCETHBTC).

Przykładowe zapytanie:

"action": "BUY",
"quantity": 0.0021,
"symbol": "BTCUSDC"

To zapytanie nakazuje platformie Psyll złożyć zlecenie kupna 0.0021 BTC na parze BTC/USDC.

Akcja BUY

Po otrzymaniu zapytania z action ustawionym na BUY, system natychmiast składa zlecenie kupna na wskazanej parze handlowej na giełdzie powiązanej z kontem użytkownika. Zlecenie zostanie zrealizowane, o ile na rachunku dostępny jest wystarczający kapitał. W przypadku niewystarczających środków, giełda może odrzucić zlecenie lub zrealizować je częściowo. Webhooki składają zlecenia typu market (rynek), które są realizowane po aktualnej, najlepszej cenie dostępnej na giełdzie.

Zalecamy monitorowanie statusu zlecenia w odpowiedzi zwrotnej webhooka, która zawiera szczegóły dotyczące zlecenia (np. ID zlecenia, status, ilość zrealizowanych jednostek).

Przykładowy scenariusz:

Chcemy kupić 0.5 ETH na parze ETHUSDT.

"action": "BUY"
"quantity": 0.5"
"symbol": "ETHUSDT"

W wyniku wykonania tego webhooka zostanie złożone zlecenie kupna 0.5 ETH. Jeśli na koncie użytkownika jest wystarczająco dużo USDT, zlecenie zostanie natychmiast zrealizowane.

Akcja SELL

Działanie jest analogiczne do BUY, ale dotyczy sprzedaży aktywów. System składa zlecenie sprzedaży dokładnie takiej liczby jednostek, jaka została wskazana w polu quantity.

Przykładowy scenariusz:

Chcemy sprzedać 0.25 BTC, aby zrealizować zysk.

"action": "SELL"
"quantity": 0.25
"symbol": "BTCUSDT"

W odpowiedzi system potwierdzi, że zlecenie sprzedaży zostało złożone. Po jego realizacji na Twoim koncie pojawi się równowartość 0.25 BTC w walucie USDT.

Akcja SET

Akcja SET jest najbardziej zaawansowana i umożliwia precyzyjną kontrolę wielkości pozycji. System najpierw sprawdza aktualne saldo danego aktywa, a następnie oblicza różnicę między nim a wartością zdefiniowaną w quantity. W zależności od wyniku, automatycznie składa zlecenie kupna lub sprzedaży.

  • Jeśli aktualne saldo jest większe niż quantity system automatycznie składa zlecenie sprzedaży nadwyżki.
  • Jeśli aktualne saldo jest mniejsze niż quantity system automatycznie składa zlecenie kupna brakującej ilości, by wyrównać saldo.
  • Jeśli salda są równe quantity: Nie są podejmowane żadne działania.

Ta funkcjonalność pozwala na automatyczne utrzymywanie pozycji na ustalonym poziomie bez konieczności ręcznego monitorowania i składania osobnych zleceń.

Przykład 1: Sprzedaż nadmiaru

Jeśli ilość aktywa w portfelu jest mniejsza niż żądana do sprzedaży, giełda odrzuci zlecenie. 

Aktualny stan konta to 0.023 BTC. Chcemy utrzymać pozycję na poziomie 0.01 BTC.

"action": "SET"
"quantity": 0.01
"symbol": "BTCUSDT

System automatycznie wyliczy, że trzeba sprzedać 0.023 - 0.01 = 0.013 BTC. Zostanie złożone zlecenie sprzedaży 0.013 BTC, a po jego realizacji na koncie pozostanie dokładnie 0.01 BTC.

Przykład 2: Dokupienie aktywa

Aktualny stan konta to 0.005 BTC. Chcemy zwiększyć pozycję do 0.01 BTC.

"action": "SET"
"quantity": 0.01
"symbol": "BTCUSDT"

System obliczy, że brakuje 0.01 - 0.005 = 0.005 BTC. Zostanie złożone zlecenie kupna 0.005 BTC, by wyrównać saldo do wartości 0.01 BTC.

Giełd typu futures
W przypadku rynków kontraktów terminowych (futures) interpretacja akcji BUY i SELL może różnić się od rynków spot. Na przykład zlecenie SELL może otworzyć pozycję krótką (short), a zlecenie BUY może zmniejszyć lub całkowicie zamknąć istniejącą pozycję krótką, w zależności od bieżącego stanu konta i ustawień kontraktu.
DUST
Często gdy chcemy sprzedaż resztki aktywa, tak zwany "DUST", system odrzuca zlecenie gdyż kwota minimalna cena zlecenia nie została osiągnięta. W wielu przypadkach jest nie jest to problematyczne i może zostać zignorowane.

Potencjalne wyjątki i obsługa błędów

  • Brak środków lub niewystarczający balans: Przy próbie kupna bez wystarczającej ilości waluty bazowej (np. USDT) lub sprzedaży bez wystarczającej ilości waluty notowanej (np. BTC), webhook zwróci błąd informujący o niewystarczających środkach.
  • Niedostępność aktywa: Niektóre giełdy mogą nie obsługiwać wybranych par symboli. W takim przypadku webhook zwróci błąd informujący o nieprawidłowym symbolu.
  • Limit dzienny: W zależności od planu subskrypcyjnego, na koncie może obowiązywać limit liczby zleceń dziennie. Po jego przekroczeniu webhook nie zrealizuje kolejnych zapytań, zwracając błąd daily_limit_exceeded.
  • Błędy komunikacji: W przypadku problemów sieciowych lub błędów API giełdy, webhook może zwrócić błąd tymczasowy. Zaleca się wdrożenie mechanizmu retry w systemie wysyłającym zapytania, aby ponowić próbę po krótkim czasie.

Praktyczne wskazówki

Webhooki są bardzo elastyczne, jednak z uwagi na dynamiczny charakter rynku i różne warunki giełd, warto zawsze:

  • Monitorować statusy zleceń: Regularnie sprawdzaj odpowiedzi webhooka i statusy zleceń na platformie giełdowej.
  • Testować zapytania: Zawsze testuj zapytania na środowisku testowym lub z minimalnymi kwotami, aby uniknąć niechcianych operacji.
  • Stosować logiczne warunki: Używaj złożonych warunków po stronie TradingView lub innego systemu sygnałowego, aby unikać nadmiernego generowania zapytań w warunkach zmienności.
  • Weryfikować symbol pary: Upewnij się, że symbol pary jest poprawny i obsługiwany przez giełdę, z którą jesteś połączony.
  • Bezpieczne przechowywanie danych: Adres webhooka i wszelkie klucze API powinny być przechowywane w bezpieczny sposób.

Integracja TradingView

Integracja z alertami TradingView

Platforma Psyll pozwala na łatwą integrację z alertami TradingView. Wystarczy skonfigurować alert na platformie TradingView, a w jego treści umieścić odpowiedni obiekt JSON, odpowiadający strukturze webhooka.

Dzięki temu procesowi cała strategia może działać w pełni automatycznie, bez konieczności ręcznej interwencji, nawet w najbardziej zmiennych warunkach rynkowych.

Więcej informacji o formacie i interpretacji odpowiedzi zwracanych przez webhook znajdziesz w naszej dokumentacji "Integracja alertow Tradingview"

Integracja ze strategią TradingView (Pine Script)

Psyll obsługuje bezpośrednią integrację z własnymi strategiami stworzonymi w języku Pine Script w TradingView. Dzięki temu możliwe jest, aby sygnały generowane przez strategię - zarówno te dotyczące otwierania, jak i zamykania pozycji - były automatycznie przekazywane do Psyll w formie zapytań webhook. Pozwala to stworzyć w pełni autonomiczny system tradingowy, który działa 24/7, reagując na sygnały w czasie rzeczywistym.

W praktyce proces integracji polega na dodaniu w kodzie strategii specjalnych warunków, które generują powiadomienia wtedy, gdy spełnione zostaną określone kryteria rynkowe. Do każdego alertu przypisuje się treść w formacie JSON zgodnym z wymogami Psyll (np. zawierającym pola action, quantity i symbol) oraz adres webhooka platformy. Po opublikowaniu strategii w TradingView i włączeniu alertów, każde spełnienie warunku w strategii automatycznie skutkuje wysłaniem zapytania HTTP POST do Psyll, co uruchamia odpowiednią akcję na giełdzie.

Dzięki tej integracji możesz:

  • Realizować strategię w trybie w pełni automatycznym, bez ręcznego składania zleceń,
  • Testować i optymalizować strategię w TradingView, a następnie płynnie wdrażać ją w realnych warunkach,
  • Synchronizować działania na wielu rynkach lub w wielu parach handlowych jednocześnie.

Szczegółowe przykłady konfiguracji Pinescript z webhookami Psyll znajdziesz w dokumentacji "Integracja strategii Pinescript Tradingview".

Przykładowe kody aplikacji

W naszej dokumentacji znajdziesz obszerne zestawy przykładów kodów źródłowych, przygotowanych z myślą o łatwej integracji z platformą Psyll. Prezentujemy szczegółowe instrukcje dla różnych środowisk i języków programowania, tak aby każdy mógł szybko uruchomić swoją pierwszą integrację. W sekcji „Przykłady użycia dla różnych języków programowania” umieściliśmy gotowe, proste fragmenty kodu demonstrujące, w jaki sposób wysyłać żądania HTTP do naszych webhooków, odbierać odpowiedzi serwera, obsługiwać kody błędów i implementować logikę automatyzacji w aplikacjach.

Znajdziesz tam m.in. przykłady w Bash, JavaScript, Python, Ruby, Rust, Typescript i PHP, dzięki czemu niezależnie od tego, z jakiej technologii korzystasz, możesz szybko rozpocząć pracę. Każdy przykład jest opatrzony komentarzami, które objaśniają, co dzieje się w poszczególnych liniach kodu, oraz zawiera wskazówki, jak dostosować go do swoich potrzeb.

Dzięki temu nie musisz tracić czasu na eksperymentowanie - wystarczy skopiować kod, wkleić go do swojego projektu i uzupełnić niezbędne dane, takie jak adres webhooka czy parametry żądania.

GitHub

Wszystkie oficjalne repozytoria, biblioteki klienckie, narzędzia wspomagające oraz materiały pomocnicze publikujemy w naszym profilu GitHub: https://github.com/psyll. Znajdziesz tam nie tylko kod źródłowy, ale również dokumentację projektów, instrukcje instalacji, przykłady wdrożeń oraz dodatkowe zasoby dla programistów.

Repozytoria są stale aktualizowane i rozwijane, aby dostarczać użytkownikom najnowsze funkcje oraz poprawki bezpieczeństwa. Każdy projekt jest udostępniany na otwartej licencji, dzięki czemu możesz go swobodnie modyfikować i dostosowywać do własnych potrzeb. W sekcji „Issues” możesz także zgłaszać błędy, proponować nowe funkcje lub dyskutować z innymi deweloperami.

GitHub jest idealnym miejscem, aby rozpocząć pracę z Psyll na poziomie kodu, śledzić zmiany w naszych bibliotekach i czerpać inspirację z przykładów przygotowanych przez społeczność. Dzięki temu możesz rozwijać swoje projekty szybciej i w pełni wykorzystać możliwości integracji z platformą Psyll.