WebSocket to protokół komunikacyjny full-duplex oparty na TCP. Full-duplex oznacza, że obie strony mogą asynchronicznie wysyłać do siebie wiadomości za pośrednictwem tego samego kanału komunikacyjnego. Niniejsza sekcja opisuje, jakie wiadomości powinny wymieniać Exchange Plus i klient. Wszystkie wiadomości powinny być prawidłowymi obiektami JSON.
WebSocket API jest używany głównie do uzyskiwania informacji lub wykonywania działań, które nie są dostępne lub trudne do wykonania przy użyciu REST API. Jednak niektóre żądania lub działania można realizować zarówno przez REST API, jak i WebSocket API. Exchange Plus wysyła wiadomości do klienta jako odpowiedź na żądanie wysłane wcześniej przez klienta lub jako powiadomienie o zdarzeniu (bez uprzedniego żądania klienta).
Publiczne wywołania API
Publiczny limit liczby żądań API jest stosowany w celu ochrony systemu przed atakami DDoS i zapewnienia wszystkim klientom równego, stabilnego dostępu do punktów końcowych Exchange Plus API. Publiczne żądania są ograniczane na podstawie adresu IP, z którego są kierowane. Limity żądań są wyznaczane na podstawie kosztu skojarzonego z każdym publicznym wywołaniem API. Domyślnie każde publiczne żądanie ma koszt 1 punktu, jednak dla niektórych żądań koszt ten może być wyższy. Aktualne informacje o kosztach limitów żądań można znaleźć w specyfikacji każdej metody.
Exchange Plus ogranicza wywołania publicznego API do maksymalnie 100 punktów na minutę, biorąc pod uwagę, że każde wywołanie publicznego API ma swój koszt (patrz poniżej). Po osiągnięciu limitu szybkości żądań Exchange Plus odpowiada błędem, wysyła zdarzenie rozłączenia do klienta i następnie zamyka połączenie WS. Exchange Plus wznowi obsługę klienta od początku kolejnej minuty kalendarzowej. W poniższym przykładzie licznik żądań zostanie zresetowany o 11:02:00.000.
| Metoda | Opis |
| GetTicker | Metoda ta służy do pobierania aktualnych informacji o tickerze, w tym danych o bieżących cenach, zmianach ceny i wolumenu w ciągu 24 godzin, ostatniej transakcji itp. dla wybranych aktywów. |
| GetOrderBook | Ta metoda umożliwia klientowi otrzymanie aktualnej migawki arkusza zleceń dla określonej pary handlowej. |
| GetCandles | Korzystając z metody Candles, klient może otrzymywać historyczne świece OHLCV różnych rozdzielczości i typów danych. Klient może wskazać dodatkowe filtry przedziału czasowego i limitu, aby odpowiedź była bardziej precyzyjna. |
| GetTradeHistory | Metoda ta umożliwia klientowi pobieranie danych historycznych dotyczących zrealizowanych transakcji dla wybranej pary handlowej. Żądanie historii transakcji można uzupełnić o dodatkowe parametry filtrowania, takie jak zakres czasowy, zakres identyfikatorów transakcji, strona i inne, aby otrzymać transakcje spełniające kryteria żądania. |
| GetServerTime | Ta metoda służy do uzyskiwania bieżącego czasu na serwerze Exchange Plus. Może być przydatna w aplikacjach wymagających synchronizacji z czasem serwera. |
| GetPairsInfo | Metoda Pair Info umożliwia klientowi pobieranie parametrów dla wszystkich obsługiwanych par handlowych. |
| GetCurrenciesInfo | Metoda Currencies Info umożliwia klientowi uzyskanie parametrów dla wszystkich walut skonfigurowanych w Exchange Plus, a także informacji o dostępności wpłat i wypłat między Exchange Plus a portfelem CEX.IO. |
| GetProcessingInfo | To żądanie umożliwia klientowi uzyskanie szczegółowych informacji o dostępnych opcjach wpłat z zewnętrznych portfeli i wypłat do zewnętrznych portfeli dla każdej obsługiwanej kryptowaluty, w tym nazwy kryptowaluty i dostępnych łańcuchów bloków dla depozytów\wypłat. Ponadto dla każdego obsługiwanego łańcucha bloków podawane są: typ kryptowaluty na danym łańcuchu, aktualna dostępność depozytów\wypłat, minimalne kwoty dla depozytów\wypłat oraz zewnętrzne opłaty za wypłaty. Informacje te zapewniają klientowi większą elastyczność w wyborze łańcucha bloków do uzyskania adresu depozytu i inicjowania zewnętrznych wypłat, co umożliwia wygodniejszy transfer aktywów kryptograficznych do lub z ekosystemu CEX.IO. |
| SubscribeOrderBook | Klient subskrybujący przez WebSocket może subskrybować kanał arkusza zleceń dla wybranej pary handlowej. W odpowiedzi na żądanie subskrypcji arkusza zleceń klient otrzyma bieżącą (początkową) migawkę arkusza zleceń dla żądanej pary z podanym numerem seqId. Aby śledzić kolejne aktualizacje arkusza zleceń, klient musi subskrybować przez WebSocket wiadomości "order_book_increment", zawierające nazwę pary handlowej, numer seqId oraz zmiany poziomów cenowych ofert kupna i sprzedaży. |
| UnSubscribeOrderBook | Anuluj subskrypcję kanału arkusza zleceń. |
| SubscribeTrade | Korzystając z metody Trade Subscribe, klient może subskrybować przez WebSocket strumień na żywo zdarzeń transakcyjnych zachodzących na żądanej parze handlowej. W odpowiedzi na żądanie Trade Subscribe klient otrzyma unikalny identyfikator subskrypcji transakcji, który powinien być następnie używany do rezygnacji z subskrypcji, gdy nie jest już ona potrzebna. Klient powinien subskrybować przez WebSocket komunikaty „tradeHistorySnapshot" i „tradeUpdate", aby otrzymywać migawki historii transakcji oraz zdarzenia transakcji na żywo dla żądanej pary handlowej. |
| UnSubscribeTrade | Anuluj subskrypcję kanału transakcji. |
Przykład: pobierz najnowszy ticker pary BTC-USD
oClient := TsgcWebSocketClient.Create(nil);
oCexPlus := TsgcWSAPI_CexPlus.Create(nil);
oCexPlus.Client := oClient;
oCexPlus.OnCexPlusConnect := OnCexPlusConnectEvent;
oCexPlus.OnCexPlusMessage := OnCexPlusMessageEvent;
oClient.Active := True;
procedure OnCexPlusConnectEvent(Sender: TObject);
begin
oCexPlus.GetTicker('BTC-USD');
end;
procedure OnCexPlusMessageEvent(Sender: TObject; Event, Msg: string);
begin
ShowMessage('Ticker data: ' + Msg);
end;
Prywatne wywołania API
Exchange Plus używa kluczy API do udzielania dostępu do prywatnych API.
Klient może generować, konfigurować i zarządzać kluczami API, ustawiać poziomy uprawnień, adresy IP na białej liście dla klucza API itp. za pośrednictwem terminala Exchange Plus Web Terminal w sekcji zarządzania kluczami API.
Limit kluczy API: Domyślnie klient może mieć do 5 kluczy API.
Aby ograniczyć dostęp do określonych funkcji podczas korzystania z kluczy API, należy zdefiniować konkretny zestaw uprawnień dla każdego klucza API. W razie potrzeby zdefiniowany zestaw uprawnień można później edytować.
Dla kluczy API dostępne są następujące poziomy uprawnień:
| Metoda | Opis |
| GetCurrentFee | Ta metoda wskazuje bieżące opłaty w określonym momencie czasu, z uwzględnieniem aktualnego 30-dniowego wolumenu klienta i dnia tygodnia (opłaty mogą być różne np. w weekendy). |
| GetFeeStrategy | Strategia opłat zwraca wszystkie dostępne opcje opłat, które mogą być zastosowane dla klienta, biorąc pod uwagę jego wolumen obrotu, dzień tygodnia, pary, grupy par itp. Metoda ta dostarcza informacji o ogólnej strategii opłat obejmującej wszystkie możliwe wartości opłat transakcyjnych. Aby otrzymać bieżące opłaty transakcyjne na podstawie wolumenu obrotu klienta z ostatnich 30 dni, należy użyć metody [Current Fee]. Aby uzyskać bieżący 30-dniowy wolumen obrotu, należy użyć metody [Volume]. |
| GetVolume | To żądanie umożliwia klientowi pobranie wolumenu obrotu z ostatnich 30 dni w ekwiwalencie USD. |
| CreateAccount | To żądanie umożliwia klientowi tworzenie nowych kont podrzędnych. Domyślnie klient może mieć do 5 kont podrzędnych, wliczając konto główne. |
| GetAccountStatus | Korzystając z metody Account Status V3, klient może sprawdzić bieżące saldo i jego orientacyjny odpowiednik w przeliczonej walucie (domyślnie „USD"), kwoty zablokowane w otwartych (aktywnych) zleceniach dla każdego subkonta i waluty. Jeśli dla klienta dostępne jest saldo opłaty transakcyjnej, odpowiedź zawiera również ogólne dane salda opłaty transakcyjnej, takie jak nazwa promocji, nazwa waluty, łączne saldo i data wygaśnięcia promocji dotyczącej salda opłaty transakcyjnej. Klient jest odpowiedzialny za śledzenie dostępnego salda transakcyjnego swojego subkonta, czyli bieżącego salda subkonta pomniejszonego o kwotę zablokowaną w otwartych (aktywnych) zleceniach na subkoncie. |
| GetOrders | To żądanie umożliwia klientowi uzyskanie informacji o jego zleceniach. |
| NewOrder | Klient może składać nowe zlecenia przez WebSocket API za pomocą żądania Do My New Order Request. Wraz z odpowiedzią na to żądanie, Exchange Plus wysyła do klienta komunikaty Account Event i Execution Report, jeśli żądanie zakończyło się sukcesem. Komunikat odpowiedzi wskazuje ostatni aktualny status zlecenia dostępny w systemie w momencie wysłania odpowiedzi. Jeśli klient nie otrzymał komunikatu odpowiedzi na Do My New Order Request, może zapytać o bieżący status zlecenia za pomocą żądania Get My Orders Request z parametrem clientOrderId. Podczas wysyłania żądania nowego zlecenia zdecydowanie zaleca się użycie parametru clientOrderId, który odpowiada konkretnemu żądaniu nowego zlecenia po stronie klienta. Exchange Plus unika wielokrotnego składania zleceń z tym samym clientOrderId. Jeśli zidentyfikowano więcej niż jedno nowe zlecenie z identycznym clientOrderId i innymi parametrami zlecenia, Exchange Plus składa tylko pierwsze zlecenie i zwraca jego status klientowi w odpowiedzi na drugie i kolejne żądania nowego zlecenia z tymi samymi parametrami. Jeśli zidentyfikowano więcej niż jedno nowe zlecenie z identycznym clientOrderId, ale z różnymi innymi parametrami zlecenia, Exchange Plus przetwarza tylko pierwsze zlecenie i odrzuca drugie i kolejne żądania nowego zlecenia z tym samym clientOrderId, ale z różnymi innymi parametrami. |
| NewMarketOrder | Składa nowe zlecenie rynkowe. Przeciążona wersja przyjmuje wielkość zlecenia w walucie1 (AmountCcy1) i opcjonalnie w walucie2 (AmountCcy2), wysyłane są tylko te wielkości, które zostały ustawione. |
| NewLimitOrder | Składa nowe zlecenie z limitem. Przeciążona wersja przyjmuje wielkość zlecenia w walucie1 (AmountCcy1) i opcjonalnie w walucie2 (AmountCcy2), wysyłane są tylko te wielkości, które zostały ustawione. |
| CancelOrder | Klient może anulować zlecenia. Wraz z odpowiedzią na to żądanie giełda Exchange Plus wysyła do klienta wiadomości Account Event i Execution Report, jeśli żądanie zakończyło się powodzeniem. Ponadto, jeśli żądanie anulowania zlecenia zostanie odrzucone, Exchange Plus wysyła wiadomość Order Cancellation Rejection. |
| CancelAllOrders | Klient może anulować wszystkie otwarte zlecenia przez WebSocket API. Wraz z odpowiedzią na to żądanie Exchange Plus rozpocznie proces anulowania wszystkich otwartych zleceń i wyśle odpowiednie wiadomości Account Event i Execution Report do klienta. |
| GetTransactionHistory | To żądanie umożliwia klientowi sprawdzenie jego transakcji finansowych (wpłaty, wypłaty, transfery wewnętrzne, prowizje lub transakcje handlowe). |
| GetFundingHistory | Żądanie to umożliwia klientowi wyszukanie transakcji depozytowych i wypłat. |
| InternalTransfer | Klient może żądać transferu środków między swoimi kontami podrzędnymi lub między kontem głównym a kontem podrzędnym. Exchange Plus nie pobiera od Klienta żadnej prowizji za transfery środków między jego kontami. Wraz z odpowiedzią na to żądanie Exchange Plus wysyła do Klienta wiadomości o zdarzeniu na koncie, jeśli żądanie zakończy się pomyślnie. |
| GetDepositAddress | Metoda ta może być używana przez klienta w celu uzyskania adresu kryptowalutowego do wpłaty środków. Adres wpłaty może być generowany dla kont głównych i podkont. Listę dostępnych sieci blockchain do generowania adresów wpłat klient może uzyskać poprzez żądanie Get Processing Info. |
| FundsDepositFromWallet | Klient może wpłacić środki z portfela CEX.IO na konto Exchange Plus. System unika przetwarzania wielu żądań depozytów z tym samym clientTxId. Jeśli zostanie odebranych wiele żądań depozytów z identycznym clientTxId, system przetworzy tylko pierwsze żądanie i odrzuci drugie oraz kolejne żądania z tym samym clientTxId. |
| FundsWithdrawalToWallet | Klient może wypłacić środki z konta Exchange Plus do portfela CEX.IO. System zapobiega wielokrotnym żądaniom wypłaty z tym samym clientTxId. Jeśli zostanie otrzymanych wiele żądań wypłaty z identycznym clientTxId, system przetwarza tylko pierwsze żądanie i odrzuca kolejne żądania z tym samym clientTxId. |
| GetWalletBalance | Pobiera informacje o saldzie portfela CEX.IO. |
| SubscribeAccountEvents | Subskrybuje powiadomienia o zdarzeniach na koncie w czasie rzeczywistym (zmiany salda, realizacje zleceń). |
| UnSubscribeAccountEvents | Anuluje subskrypcję powiadomień o zdarzeniach konta. |
Przykład: pobierz zlecenia.
oClient := TsgcWebSocketClient.Create(nil);
oCexPlus := TsgcWSAPI_CexPlus.Create(nil);
oCexPlus.Client := oClient;
oCexPlus.CexPlus.ApiKey := 'your-api-key';
oCexPlus.CexPlus.ApiSecret := 'your-api-secret';
oCexPlus.OnCexPlusAuthenticated := OnCexPlusAuthenticatedEvent;
oCexPlus.OnCexPlusMessage := OnCexPlusMessageEvent;
oClient.Active := True;
procedure OnCexPlusAuthenticatedEvent(Sender: TObject);
begin
oCexPlus.GetOrders();
end;
procedure OnCexPlusMessageEvent(Sender: TObject; Event, Msg: string);
begin
ShowMessage('Orders: ' + Msg);
end;