Aktualizacja API XTB w sgcWebSockets

Integracja Trading API XTB xStation5 w Delphi

XTB to jedna z wiodących europejskich platform handlowych online, oferująca dostęp do forex, indeksów, towarów, akcji i kryptowalut przez platformę xStation5. Komponent TsgcWSAPI_XTB zapewnia kompletną integrację Delphi z API xStation5 przez pojedyncze połączenie WebSocket — obejmującą uwierzytelnianie, pobieranie danych rynkowych, zarządzanie kontem, realizację transakcji i subskrypcje strumieniowe w czasie rzeczywistym. Ten artykuł opisuje każdą dostępną metodę i pokazuje, jak zacząć w ciągu kilku minut.

Spis treści

• Przegląd architektury
• Uwierzytelnianie
• Metody danych rynkowych
• Metody konta
• Metody handlu
• Subskrypcje strumieniowe
• Metody pomocnicze
• Pierwsze kroki — przykład kodu
• Dokumentacja konfiguracji
• Wskazówki i uwagi

Przegląd architektury

W odróżnieniu od wielu giełd kryptowalut, które rozdzielają funkcjonalność między punkty końcowe REST i kanały WebSocket, API XTB xStation5 działa całkowicie przez pojedyncze połączenie WebSocket. Każde żądanie — od pobrania listy symboli do złożenia transakcji — jest wysyłane i odbierane jako wiadomość JSON przez to samo gniazdo. Drugie gniazdo strumieniowe jest zarządzane automatycznie dla subskrypcji w czasie rzeczywistym (saldo, świece, ticki, transakcje i inne).

Komponent TsgcWSAPI_XTB abstrahuje to wszystko. Wystarczy przypisać TsgcWebSocketClient, skonfigurować dane uwierzytelniające, aktywować klienta i wywoływać metody wysokiego poziomu, takie jak GetAllSymbols lub SubscribeTickPrices.

Uwierzytelnianie

Uwierzytelnianie jest obsługiwane automatycznie po połączeniu klienta WebSocket, przy użyciu danych uwierzytelniających ustawionych w grupie właściwości XTB. W razie potrzeby możesz też wywoływać te metody jawnie.

Metoda	Opis
Login	Uwierzytelnia się na serwerze xStation5 przy użyciu UserId i Password. Wywoływana automatycznie przy połączeniu.
Logout	Kończy uwierzytelnioną sesję i rozłącza się z serwerem.

Metody danych rynkowych

Te metody pobierają informacje o instrumentach, wyceny, wykresy, wiadomości i godziny handlu z serwera xStation5. Wszystkie wywołania to żądanie/odpowiedź przez połączenie WebSocket.

Metoda	Opis
GetAllSymbols	Zwraca listę wszystkich instrumentów dostępnych na platformie.
GetSymbol	Zwraca szczegółowe informacje dla określonego symbolu.
GetTickPrices	Zwraca bieżące ceny tick (kupno/sprzedaż) dla podanych symboli.
GetTradingHours	Zwraca godziny handlu dla podanych instrumentów.
GetCalendar	Zwraca kalendarz ekonomiczny nadchodzących zdarzeń.
GetChartLastRequest	Zwraca dane świecowe wykresu od podanego znacznika czasu do chwili bieżącej.
GetChartRangeRequest	Zwraca dane świecowe wykresu dla określonego zakresu dat.
GetNews	Zwraca tematy wiadomości z platformy handlowej XTB.
GetStepRules	Zwraca reguły kroku dla obliczeń wolumenu.
GetServerTime	Zwraca bieżący czas serwera.
GetVersion	Zwraca numer wersji API.

Metody konta

Metody konta pozwalają sprawdzić profil użytkownika, poziomy depozytu i obliczenia zysku bez opuszczania sesji WebSocket.

Metoda	Opis
GetCurrentUserData	Zwraca informacje o aktualnie zalogowanym użytkowniku (imię, waluta, dźwignia itp.).
GetMarginLevel	Zwraca bieżący poziom depozytu zabezpieczającego, wartość kapitału i saldo konta.
GetMarginTrade	Oblicza oczekiwany depozyt zabezpieczający dla podanego instrumentu i wolumenu.
GetIbsHistory	Zwraca historię prowizji brokera wprowadzającego (IB).
GetProfitCalculation	Oblicza szacowany zysk dla podanego scenariusza transakcji.

Metody handlu

Te metody obejmują wszystko: od odczytu otwartych i historycznych pozycji po składanie i monitorowanie transakcji handlowych.

Metoda	Opis
GetTrades	Zwraca listę aktualnie otwartych transakcji. Przekaż True, aby uwzględnić tylko otwarte pozycje.
GetTradesHistory	Zwraca zamknięte transakcje w podanym zakresie czasowym.
GetTradeRecords	Zwraca rekordy transakcji dla podanych numerów zleceń.
TradeTransaction	Wykonuje transakcję handlową (otwórz, zamknij, zmodyfikuj lub usuń zlecenie).
TradeTransactionStatus	Sprawdza bieżący status wcześniej złożonej transakcji handlowej.

Subskrypcje strumieniowe

Metody strumieniowe otwierają kanały danych w czasie rzeczywistym na dedykowanym połączeniu strumieniowym. Każda subskrypcja ma odpowiednią metodę anulowania, aby zatrzymać odbieranie aktualizacji.

Subskrypcja	Anulowanie	Opis
SubscribeBalance	UnSubscribeBalance	Aktualizacje salda i wartości kapitału w czasie rzeczywistym.
SubscribeCandles	UnSubscribeCandles	Aktualizacje świec/wykresów na żywo dla symbolu.
SubscribeKeepAlive	UnSubscribeKeepAlive	Okresowe wiadomości heartbeat podtrzymujące połączenie.
SubscribeNews	UnSubscribeNews	Strumieniowe wiadomości z platformy w czasie rzeczywistym.
SubscribeProfits	UnSubscribeProfits	Aktualizacje zysku/straty na otwartych pozycjach w czasie rzeczywistym.
SubscribeTickPrices	UnSubscribeTickPrices	Ceny tick kupno/sprzedaż na żywo dla symbolu.
SubscribeTrades	UnSubscribeTrades	Aktualizacje w czasie rzeczywistym przy otwieraniu, zamykaniu lub modyfikowaniu transakcji.
SubscribeTradeStatus	UnSubscribeTradeStatus	Zmiany statusu transakcji handlowych w czasie rzeczywistym.
SubscribePing	—	Subskrybuje strumieniowy ping podtrzymujący połączenie (anulowanie nie jest potrzebne).

Uwaga: subskrypcje strumieniowe wymagają wcześniejszego pomyślnego zalogowania. Identyfikator sesji strumieniowej jest uzyskiwany automatycznie podczas uwierzytelniania.

Metody pomocnicze

Metoda	Opis
Ping	Wysyła ping do serwera w celu weryfikacji aktywności połączenia i zapobiegania timeoutom.

Pierwsze kroki — przykład kodu

Poniższy przykład tworzy połączenie z serwerem demo XTB, uwierzytelnia się, pobiera symbole i dane użytkownika, subskrybuje ceny tick i aktualizacje salda na żywo oraz pobiera otwarte transakcje.

var
  oClient: TsgcWebSocketClient;
  oXTB: TsgcWSAPI_XTB;
begin
  // Create the WebSocket client
  oClient := TsgcWebSocketClient.Create(nil);
  // Create the XTB API component
  oXTB := TsgcWSAPI_XTB.Create(nil);
  oXTB.Client := oClient;
  // Configure credentials
  oXTB.XTB.UserId := 'your_user_id';
  oXTB.XTB.Password := 'your_password';
  oXTB.XTB.Demo := True;
  // Connect and authenticate
  oClient.Active := True;
  // After the login event fires, call API methods:
  oXTB.GetAllSymbols;
  oXTB.GetCurrentUserData;
  // Subscribe to real-time tick prices for EURUSD
  oXTB.SubscribeTickPrices('EURUSD', 0, 0);
  // Subscribe to balance updates
  oXTB.SubscribeBalance;
  // Get all open trades
  oXTB.GetTrades(False);
end;

Obsługa odpowiedzi

Wszystkie odpowiedzi docierają asynchronicznie przez zdarzenia komponentu. Przypisz handlery do zdarzeń takich jak OnXTBResponse i OnXTBStreamingResponse, aby przetwarzać zwracane dane JSON. Każda odpowiedź zawiera identyfikator polecenia, dzięki czemu możesz kierować ją do odpowiedniej logiki przetwarzania.

Dokumentacja konfiguracji

Cała konfiguracja jest zgrupowana pod właściwością XTB komponentu TsgcWSAPI_XTB.

Właściwość	Typ	Opis
XTB.UserId	String	Identyfikator użytkownika twojego konta XTB.
XTB.Password	String	Hasło do twojego konta XTB.
XTB.Demo	Boolean	Ustaw True, aby połączyć się z serwerem demo; False dla serwera produkcyjnego.

Wskazówki i uwagi

Demo vs. produkcja

Zawsze twórz i testuj z ustawieniem XTB.Demo := True. Serwer demo używa tej samej powierzchni API co produkcja, ale łączy się ze środowiskiem sandbox z wirtualnymi środkami. Przełącz na False dopiero, gdy jesteś gotowy na handel na żywo.

Podtrzymanie połączenia

Serwer XTB rozłącza bezczynne sesje po upływie czasu oczekiwania. Użyj SubscribePing lub wywołuj Ping okresowo, aby podtrzymać połączenie. Metoda SubscribeKeepAlive na połączeniu strumieniowym służy podobnemu celowi.

Architektura pojedynczego połączenia

W odróżnieniu od giełd z oddzielnymi punktami końcowymi REST, XTB kieruje każde polecenie przez wiadomości WebSocket. Upraszcza to architekturę komponentu: potrzebujesz tylko TsgcWebSocketClient i TsgcWSAPI_XTB — żadne dodatkowe komponenty HTTP nie są wymagane.

Obsługa błędów

W przypadku niepowodzenia żądania serwer zwraca odpowiedź JSON z kodem i opisem błędu. Obsługuj je w zdarzeniu odpowiedzi, sprawdzając pole status. Typowe problemy to nieprawidłowe dane uwierzytelniające, wygasłe sesje i ograniczanie szybkości przy zbyt wielu żądaniach.

Limity szybkości: API XTB egzekwuje limity żądań na sekundę. Unikaj wysyłania serii żądań w ciasnych pętlach. Rozłóż wywołania w czasie lub korzystaj z subskrypcji strumieniowych dla danych, które często się aktualizują.