WebSocket è un protocollo di comunicazione full-duplex basato su TCP. Full-duplex significa che entrambe le parti possono inviarsi messaggi in modo asincrono utilizzando lo stesso canale di comunicazione. Questa sezione descrive quali messaggi Exchange Plus e Client devono inviarsi reciprocamente. Tutti i messaggi devono essere oggetti JSON validi.
L'API WebSocket è utilizzata principalmente per ottenere informazioni o eseguire azioni che non sono disponibili o non facili da eseguire utilizzando l'API REST. Tuttavia, alcune richieste o azioni sono possibili sia nell'API REST sia nell'API WebSocket. Exchange Plus invia messaggi al Client come risposta a una richiesta inviata in precedenza dal Client, o come notifica di un evento (senza una precedente richiesta del Client).
Chiamate API pubbliche
Il limite di frequenza delle richieste all'API pubblica è implicito per proteggere il sistema da attacchi DDoS e garantire che tutti i client abbiano lo stesso livello di accesso stabile agli endpoint dell'Exchange Plus API. Le richieste pubbliche sono limitate per indirizzo IP da cui vengono effettuate. I limiti di richiesta sono determinati dal costo associato a ciascuna chiamata API pubblica. Per impostazione predefinita, ogni richiesta pubblica ha un costo di 1 punto, ma per alcune richieste specifiche questo costo può essere superiore. Consultare le informazioni aggiornate sul costo del limite di frequenza nella specifica di ciascun metodo.
Exchange Plus limita le chiamate Public API a un massimo di 100 punti al minuto, considerando che ogni chiamata Public API ha il suo costo (veda di seguito). Se il limite della frequenza delle richieste viene raggiunto, Exchange Plus risponde con un errore, invia l'evento disconnected al client e successivamente chiude la connessione WS. Exchange Plus continuerà a servire il client a partire dal minuto di calendario successivo. Nell'esempio seguente, il contatore delle richieste verrà reimpostato alle 11:02:00.000.
| Method | Description |
| GetTicker | Questo metodo è progettato per ottenere informazioni attuali sul Ticker, inclusi dati sui prezzi correnti, variazioni di prezzo e volume nelle ultime 24 ore, ultimo evento di scambio, ecc. di determinati asset. |
| GetOrderBook | Questo metodo consente al client di ricevere l'istantanea corrente del book degli ordini per una specifica coppia di trading. |
| GetCandles | Tramite il metodo Candles il client può ricevere candele OHLCV storiche di diverse risoluzioni e tipi di dati. Il client può indicare filtri aggiuntivi di intervallo temporale e limite per rendere la risposta più precisa alle esigenze del client. |
| GetTradeHistory | Questo metodo consente al Client di ottenere dati storici sulle operazioni avvenute sulla coppia di trading richiesta. Il Client può integrare la richiesta di storico operazioni con parametri di filtro aggiuntivi, come il periodo temporale, l'intervallo di tradeId, il lato, ecc., per ricevere le operazioni corrispondenti ai parametri della richiesta. |
| GetServerTime | Questo metodo viene utilizzato per ottenere l'ora corrente sul server Exchange Plus. Può essere utile per le applicazioni che devono essere sincronizzate con l'ora del server. |
| GetPairsInfo | Il metodo Pair Info consente al Client di ricevere i parametri per tutte le coppie di trading supportate. |
| GetCurrenciesInfo | Il metodo Currencies Info consente al Client di ricevere i parametri per tutte le valute configurate in Exchange Plus, nonché la disponibilità di deposito e prelievo tra Exchange Plus e CEX.IO Wallet. |
| GetProcessingInfo | Questa richiesta consente al Cliente di ricevere informazioni dettagliate sulle opzioni disponibili per effettuare depositi da portafogli esterni e prelievi verso portafogli esterni per ciascuna criptovaluta supportata, inclusi il nome della criptovaluta e le blockchain disponibili per depositi e prelievi. Inoltre, per ciascuna blockchain supportata sono indicati il tipo di criptovaluta sulla blockchain specificata, la disponibilità attuale di deposito e prelievo, gli importi minimi per depositi e prelievi e le commissioni di prelievo esterno. Le informazioni di elaborazione rendono il Cliente più flessibile nella scelta della blockchain desiderata per ricevere l'indirizzo di deposito e avviare prelievi esterni tramite una determinata blockchain, consentendo così al Cliente di utilizzare il metodo più comodo per trasferire i propri asset crypto da o verso l'ecosistema CEX.IO. |
| SubscribeOrderBook | Il client, iscrivendosi tramite WebSocket, può sottoscrivere il feed del libro degli ordini per la coppia di trading richiesta. In risposta alla richiesta di sottoscrizione al Libro degli Ordini, il client riceverà l'istantanea corrente (iniziale) del libro degli ordini per la coppia richiesta con il numero seqId indicato. Per tracciare i successivi aggiornamenti al Libro degli Ordini, il client deve sottoscrivere tramite WebSocket i messaggi "order_book_increment", che conterranno il nome della coppia di trading, il numero seqId e i delta dei livelli di prezzo Bids e Asks. |
| UnSubscribeOrderBook | Cancellazione dell'iscrizione al canale del libro degli ordini. |
| SubscribeTrade | Utilizzando il metodo Trade Subscribe, il client può sottoscriversi tramite WebSocket al flusso live degli eventi di trade che si verificano sulla coppia di trading richiesta. In risposta alla richiesta Trade Subscribe, il client riceverà un identificatore univoco della sottoscrizione di trade da utilizzare successivamente per l'annullamento della sottoscrizione quando non è più necessaria. Il client deve sottoscriversi tramite WebSocket ai messaggi "tradeHistorySnapshot" e "tradeUpdate" per ricevere snapshot iniziali e periodici della cronologia dei trade, nonché eventi di trade live per la coppia di trading richiesta. |
| UnSubscribeTrade | Annullamento dell'iscrizione al canale di trading. |
Esempio: ottenere l'ultimo ticker della coppia 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;
Chiamate API private
Exchange Plus utilizza chiavi API per consentire l'accesso alle API private.
Il client può generare, configurare e gestire le chiavi API, impostare i livelli di autorizzazione, gli IP nella whitelist per le chiavi API, ecc. tramite Exchange Plus Web Terminal nella sezione Gestione Chiavi API del Profilo.
Limite API Keys: Per impostazione predefinita il Client può avere fino a 5 API Keys.
Per limitare l'accesso a determinate funzionalità durante l'utilizzo delle API Key, è necessario definire un insieme specifico di permessi per ogni API Key. L'insieme di permessi definito può essere modificato successivamente se necessario.
Per le API Key sono disponibili i seguenti livelli di autorizzazione:
| Method | Description |
| GetCurrentFee | Questo metodo indica le commissioni correnti in un momento specifico, tenendo conto del volume aggiornato a 30 giorni del Client e del giorno della settimana (le commissioni possono essere diverse, ad esempio, nei fine settimana). |
| GetFeeStrategy | La strategia delle commissioni restituisce tutte le opzioni di commissione applicabili al Cliente, tenendo conto del volume di trading del Cliente, del giorno della settimana, delle coppie, del gruppo di coppie, ecc. Questo metodo fornisce informazioni sulla strategia generale delle commissioni, che include tutti i possibili valori delle commissioni di trading applicabili al Cliente. Per ricevere le commissioni di trading correnti in base al volume di trading degli ultimi 30 giorni del Cliente, il Cliente deve utilizzare il metodo [Commissione corrente]. Per ricevere il volume di trading corrente degli ultimi 30 giorni, il Cliente deve utilizzare il metodo [Volume]. |
| GetVolume | Questa richiesta consente al cliente di ricevere il proprio volume di trading degli ultimi 30 giorni in equivalente USD. |
| CreateAccount | Questa richiesta consente al cliente di creare un nuovo sotto-account. Per impostazione predefinita, il cliente può avere fino a 5 sotto-account, incluso il conto principale. |
| GetAccountStatus | Tramite il metodo Account Status V3, il Client può visualizzare il saldo attuale e il suo equivalente indicativo nella valuta di conversione (per impostazione predefinita "USD"), gli importi bloccati negli ordini aperti (attivi) per ciascun sotto-account e valuta. Se è disponibile un saldo commissioni di trading per il Client, la risposta conterrà anche i dati generali del saldo commissioni di trading come nome promo, nome valuta, saldo totale e data di scadenza della promo sul saldo commissioni di trading. È responsabilità del Client monitorare il saldo di trading disponibile del proprio sotto-account come saldo attuale del sotto-account ridotto dell'importo del saldo bloccato negli ordini aperti (attivi) del sotto-account. |
| GetOrders | Questa richiesta consente al Client di scoprire informazioni sui propri ordini. |
| NewOrder | Il client può inserire nuovi ordini tramite l'API WebSocket utilizzando Do My New Order Request. Insieme a una risposta a questa richiesta, Exchange Plus invia messaggi Account Event e Execution Report al client se la richiesta ha esito positivo. Il messaggio di risposta indica l'ultimo stato aggiornato dell'ordine disponibile nel sistema al momento dell'invio della risposta. Se il client non ha ricevuto un messaggio di risposta a Do My New Order Request, può interrogare lo stato corrente dell'ordine utilizzando Get My Orders Request con il parametro clientOrderId. Quando si invia una richiesta per un nuovo ordine, si raccomanda vivamente di utilizzare il parametro clientOrderId che corrisponde alla specifica richiesta di nuovo ordine sul lato del client. Exchange Plus evita di inserire più ordini con lo stesso clientOrderId. Se vengono identificati più di un nuovo ordine con lo stesso clientOrderId e gli stessi altri parametri dell'ordine, Exchange Plus inserisce solo il primo ordine e restituisce lo stato di tale ordine al client in risposta alle seconde e successive richieste di nuovo ordine con gli stessi parametri. Se vengono identificati più di un nuovo ordine con lo stesso clientOrderId ma con diversi altri parametri dell'ordine, Exchange Plus elabora solo il primo ordine e rifiuta le seconde e successive richieste di nuovo ordine con lo stesso clientOrderID ma con diversi altri parametri dell'ordine. |
| NewMarketOrder | Inserisce un nuovo ordine a mercato. |
| NewLimitOrder | Inserisce un nuovo ordine limite. |
| CancelOrder | Il client può annullare gli ordini. Insieme alla risposta a questa richiesta, Exchange Plus invia al client messaggi di Account Event e Execution Report se la richiesta ha successo. Inoltre, se la richiesta di annullamento di un ordine viene rifiutata, Exchange Plus invia un messaggio di Order Cancellation Rejection. |
| CancelAllOrders | Il client può annullare tutti gli ordini aperti tramite WebSocket API. Insieme alla risposta a questa richiesta, Exchange Plus avvierà il processo di cancellazione per tutti gli ordini aperti e invierà al client i messaggi Account Event e Execution Report corrispondenti. |
| GetTransactionHistory | Questa richiesta consente al Client di conoscere le proprie transazioni finanziarie (depositi, prelievi, trasferimenti interni, commissioni o operazioni di trading). |
| GetFundingHistory | Questa richiesta consente al client di trovare le proprie transazioni di deposito e prelievo. |
| InternalTransfer | Il client può richiedere il trasferimento di fondi tra i propri sub-account o tra il conto principale e un sub-account. Exchange Plus non addebita alcuna commissione al client per il trasferimento di fondi tra i propri account. Insieme alla risposta a questa richiesta, Exchange Plus invia messaggi di evento account al client se la richiesta ha esito positivo. |
| GetDepositAddress | Questo metodo può essere utilizzato dal Client per ricevere un indirizzo crypto in cui depositare criptovalute. L'indirizzo di deposito può essere generato per account principali e secondari. L'elenco delle blockchain disponibili per la generazione dell'indirizzo di deposito può essere ottenuto dal Client tramite la richiesta Get Processing Info. |
| FundsDepositFromWallet | Il client può depositare fondi dal Wallet CEX.IO all'account Exchange Plus. Il sistema evita l'elaborazione di più richieste di deposito con lo stesso clientTxId. Se vengono ricevute più richieste di deposito con lo stesso clientTxId, il sistema elabora solo la prima richiesta di deposito e rifiuta la seconda e le successive richieste di deposito con lo stesso clientTxId. |
| FundsWithdrawalToWallet | Il client può prelevare fondi dall'account Exchange Plus verso il Portafoglio CEX.IO. Il sistema evita richieste di prelievo multiple con lo stesso clientTxId. Se vengono ricevute più richieste di prelievo con lo stesso clientTxId, il sistema elabora solo la prima e rifiuta la seconda e le successive con lo stesso clientTxId. |
| GetWalletBalance | Recupera le informazioni sul saldo del Wallet CEX.IO. |
| SubscribeAccountEvents | Sottoscrive le notifiche di eventi dell'account in tempo reale (variazioni di saldo, esecuzioni di ordini). |
| UnSubscribeAccountEvents | Annulla l'iscrizione alle notifiche degli eventi dell'account. |
Esempio: ottenere gli ordini.
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;