Aggiornamento API Kucoin per sgcWebSockets

6 marzo 2026 · Funzionalità

Integrazione delle API Spot e Futures di KuCoin in Delphi

I componenti TsgcWSAPI_Kucoin e TsgcWSAPI_Kucoin_Futures forniscono un accesso Delphi completo all'exchange KuCoin, coprendo dati di mercato WebSocket in tempo reale, stream privati dell'account e un'API REST completa per il trading, i prelievi e le query di mercato. Questa guida copre ogni metodo disponibile sia per spot che per futures, con dettagli di configurazione ed esempi di codice funzionanti.

Indice

API WebSocket Spot
- Canali pubblici
- Canali privati
API REST Spot
API WebSocket Futures
- Canali pubblici
- Canali privati
API REST Futures
Esempio di codice
Configurazione e note

API WebSocket Spot

L'API WebSocket spot fornisce streaming in tempo reale per dati di mercato ed eventi privati dell'account. I canali pubblici sono disponibili senza autenticazione, mentre i canali privati richiedono credenziali API valide.

Canali pubblici

I canali pubblici trasmettono dati di mercato a tutti i client connessi senza richiedere autenticazione. Ogni metodo subscribe ha un corrispondente metodo unsubscribe.

Metodo	Descrizione
`SubscribeSymbolTicker`	Iscriviti agli aggiornamenti del ticker in tempo reale per uno specifico simbolo di trading.
`SubscribeAllSymbolsTicker`	Iscriviti agli aggiornamenti del ticker per tutti i simboli sull'exchange.
`SubscribeSymbolSnapshot`	Iscriviti ai dati snapshot per un simbolo specifico, incluse le statistiche delle 24h.
`SubscribeMarketSnapshot`	Iscriviti agli aggiornamenti snapshot di tutto il mercato.
`SubscribeLevel2MarketData`	Iscriviti ai cambiamenti del book degli ordini di Livello 2 (profondità completa).
`SubscribeLevel2_5BestAskBid`	Iscriviti ai 5 migliori livelli ask e bid del book degli ordini.
`SubscribeLevel2_50BestAskBid`	Iscriviti ai 50 migliori livelli ask e bid del book degli ordini.
`SubscribeKlines`	Iscriviti ai dati candlestick/kline per un simbolo all'intervallo specificato.
`SubscribeMatchExecutionData`	Iscriviti ai dati di match/esecuzione in tempo reale per gli scambi su un simbolo.
`SubscribeIndexPrice`	Iscriviti agli aggiornamenti dell'index price per un simbolo.
`SubscribeMarkPrice`	Iscriviti agli aggiornamenti del mark price per un simbolo.
`SubscribeOrderBookChanged`	Iscriviti agli eventi di cambiamento del book degli ordini per un simbolo.

Nota: ogni metodo Subscribe elencato sopra ha una controparte UnSubscribe corrispondente (es. UnSubscribeSymbolTicker) per smettere di ricevere aggiornamenti per quel canale.

Canali privati

I canali privati richiedono credenziali API valide e forniscono aggiornamenti in tempo reale sui tuoi ordini, saldi, posizioni e attività di margine.

Metodo	Descrizione
`SubscribeTradeOrders`	Iscriviti agli aggiornamenti in tempo reale sui tuoi ordini di trading (aperti, eseguiti, cancellati).
`SubscribeAccountBalance`	Iscriviti ai cambiamenti del saldo dell'account in tempo reale.
`SubscribePositionStatus`	Iscriviti agli aggiornamenti dello stato delle posizioni per il margin trading.
`SubscribeMarginTradeOrders`	Iscriviti agli aggiornamenti degli ordini di margin trade.
`SubscribeStopOrder`	Iscriviti agli aggiornamenti di trigger e stato degli stop order.

API REST Spot

L'API REST spot è accessibile tramite la proprietà REST_API di TsgcWSAPI_Kucoin. Tutti i metodi restituiscono stringhe JSON. L'API copre account, prelievi, gestione degli ordini, stop order e dati di mercato.

Account

Metodo	Descrizione
`GetAccounts`	Restituisce una lista di tutti gli account (main, trade, margin).
`GetAccount`	Restituisce i dettagli per un account specifico tramite ID account.
`GetAccountBalanceSubAccount`	Restituisce il saldo di un sub-account.
`InnerTransfer`	Trasferisce fondi tra i tuoi account interni (es. main a trade).

Prelievi

Metodo	Descrizione
`GetWithdrawalsList`	Restituisce un elenco dei record di prelievo recenti.
`GetHistoricalWithdrawalsList`	Restituisce record storici di prelievo oltre la finestra recente.
`GetWithdrawalsQuotas`	Restituisce la quota di prelievo e i limiti per una data valuta.
`ApplyWithdraw`	Avvia un prelievo verso un indirizzo esterno.
`CancelWithdraw`	Cancella un prelievo in sospeso tramite il suo ID.

Ordini

Metodo	Descrizione
`PlaceOrder`	Piazza un nuovo ordine spot (market o limit, buy o sell).
`PlaceMarginOrder`	Piazza un ordine di margine con fondi presi in prestito.
`CancelOrderByClientOid`	Cancella un ordine usando l'ID ordine assegnato dal client.
`GetOrder`	Restituisce i dettagli per un ordine specifico tramite il suo ID assegnato dall'exchange.
`GetOrderByClientOid`	Restituisce i dettagli per un ordine specifico tramite il suo ID assegnato dal client.
`ListFills`	Restituisce un elenco di ordini eseguiti (esecuzioni di scambi).
`GetRecentFills`	Restituisce i record di fill più recenti.

Stop Order

Metodo	Descrizione
`PlaceStopOrder`	Piazza uno stop order che si attiva quando viene raggiunto lo stop price.
`PlaceStopMarketOrder`	Piazza uno stop-market order che si esegue al prezzo di mercato una volta attivato.
`PlaceStopLimitOrder`	Piazza uno stop-limit order che crea un ordine limit una volta attivato.
`CancelStopOrder`	Cancella uno stop order tramite il suo ID assegnato dall'exchange.
`CancelStopOrderByClientOid`	Cancella uno stop order tramite il suo ID assegnato dal client.
`CancelAllStopOrders`	Cancella tutti gli stop order attivi, opzionalmente filtrati per simbolo.
`GetStopOrder`	Restituisce i dettagli per uno stop order specifico tramite il suo ID assegnato dall'exchange.
`GetStopOrderByClientOid`	Restituisce i dettagli per uno stop order specifico tramite il suo ID assegnato dal client.
`ListStopOrders`	Restituisce un elenco di tutti gli stop order attivi.

Dati di mercato

Metodo	Descrizione
`GetSymbolList`	Restituisce un elenco dei simboli di trading disponibili.
`GetAllTickers`	Restituisce i dati ticker per tutte le coppie di trading.
`GetMarketList`	Restituisce un elenco dei mercati disponibili.
`GetPartOrderBook100`	Restituisce le prime 100 voci del book degli ordini per un simbolo.
`GetFullOrderBook`	Restituisce il book degli ordini completo per un simbolo (dati di Livello 3).
`GetHistories`	Restituisce la cronologia recente degli scambi per un simbolo.
`GetKLines`	Restituisce i dati candlestick/kline per un simbolo a un dato intervallo.
`GetCurrencies`	Restituisce un elenco di tutte le valute supportate.
`GetCurrencyDetail`	Restituisce dettagli per una valuta specifica (info catena, precisione, ecc.).
`GetFiatPrice`	Restituisce il prezzo fiat per le valute specificate (es. valore in USD di BTC).

API WebSocket Futures

L'API WebSocket futures è fornita da TsgcWSAPI_Kucoin_Futures e offre streaming in tempo reale per dati dei contratti futures ed eventi privati dell'account.

Canali pubblici

Metodo	Descrizione
`SubscribeSymbolTickerV2`	Iscriviti agli aggiornamenti ticker V2 per un simbolo di contratto futures.
`SubscribeSymbolTicker`	Iscriviti agli aggiornamenti ticker per un simbolo di contratto futures.
`SubscribeLevel2MarketData`	Iscriviti ai dati del book degli ordini di Livello 2 per un contratto futures.
`SubscribeExecutionData`	Iscriviti ai dati di match/esecuzione in tempo reale per gli scambi futures.
`SubscribeLevel2_5BestAskBid`	Iscriviti ai 5 migliori livelli ask/bid per un contratto futures.
`SubscribeLevel2_50BestAskBid`	Iscriviti ai 50 migliori livelli ask/bid per un contratto futures.
`SubscribeContractMarketData`	Iscriviti ai dati di mercato a livello di contratto (funding rate, mark price, ecc.).
`SubscribeSystemAnnouncements`	Iscriviti agli annunci di sistema e avvisi di manutenzione.
`SubscribeTransactionStatistics`	Iscriviti alle statistiche aggregate delle transazioni per un contratto futures.

Nota: ogni metodo Subscribe elencato nelle tabelle futures ha una controparte UnSubscribe corrispondente per smettere di ricevere aggiornamenti per quel canale.

Canali privati

Metodo	Descrizione
`SubscribeTradeOrders`	Iscriviti agli aggiornamenti in tempo reale sui tuoi ordini di trade futures.
`SubscribeStopOrder`	Iscriviti agli aggiornamenti di trigger e stato degli stop order per i futures.
`SubscribeAccountBalance`	Iscriviti ai cambiamenti del saldo del conto futures in tempo reale.
`SubscribePositionChange`	Iscriviti agli eventi di cambiamento di posizione (apertura, chiusura, liquidazione).

API REST Futures

L'API REST futures è accessibile tramite la proprietà REST_API di TsgcWSAPI_Kucoin_Futures. Questi metodi coprono la gestione dei margini, i limiti di rischio, la cronologia del funding e le query del book degli ordini.

Metodo	Descrizione
`AddMarginManually`	Aggiungi manualmente margine a una posizione futures.
`ObtainFuturesRiskLimitLevel`	Restituisce il livello di limite di rischio corrente per un contratto futures.
`AdjustRiskLimitLevel`	Regola il livello di limite di rischio per un contratto futures.
`GetFundingHistory`	Restituisce la cronologia del funding rate per un contratto futures.
`GetPartOrderBook100`	Restituisce le prime 100 voci del book degli ordini futures.
`GetFullOrderBook`	Restituisce il book degli ordini futures completo.
`GetLevel2PullingMessages`	Restituisce messaggi pulling di Livello 2 per aggiornamenti incrementali del book.
`GetInterestRateList`	Restituisce l'elenco dei tassi di interesse usati per i calcoli di funding.
`GetIndexList`	Restituisce l'elenco di composizione dell'indice per un contratto futures.

Esempio di codice

L'esempio seguente dimostra come creare e configurare il componente TsgcWSAPI_Kucoin per il trading spot, autenticarsi con l'API, recuperare ticker via REST, piazzare un ordine e iscriversi a uno stream ticker in tempo reale via WebSocket.

var
  oClient: TsgcWebSocketClient;
  oKucoin: TsgcWSAPI_Kucoin;
begin
  // Create the WebSocket client
  oClient := TsgcWebSocketClient.Create(nil);
  oKucoin := TsgcWSAPI_Kucoin.Create(nil);
  oKucoin.Client := oClient;
  // Configure API credentials
  oKucoin.Kucoin.ApiKey := 'your_api_key';
  oKucoin.Kucoin.ApiSecret := 'your_api_secret';
  oKucoin.Kucoin.Passphrase := 'your_passphrase';
  // Connect to KuCoin
  oClient.Active := True;
  // REST: Get all tickers
  ShowMessage(oKucoin.REST_API.GetAllTickers);
  // REST: Place a limit order
  ShowMessage(oKucoin.REST_API.PlaceOrder(myOrder));
  // WebSocket: Subscribe to BTC-USDT ticker
  oKucoin.SubscribeSymbolTicker('BTC-USDT');
end;

Gestione degli eventi WebSocket

Assegna un gestore di evento per elaborare i messaggi in arrivo. L'evento fornisce il topic, il subject e i dati JSON per ogni aggiornamento.

procedure TForm1.OnKucoinEvent(Sender: TObject;
  const aTopic, aSubject, aData: string);
begin
  // aTopic identifies the channel
  // aSubject provides the specific symbol or identifier
  // aData contains the JSON payload
  Memo1.Lines.Add(aTopic + ' [' + aSubject + ']: ' + aData);
end;

Configurazione e note

Proprietà di configurazione

Sia TsgcWSAPI_Kucoin (spot) che TsgcWSAPI_Kucoin_Futures (futures) condividono le stesse proprietà di autenticazione, accessibili tramite la proprietà Kucoin.

Proprietà	Tipo	Descrizione
`Kucoin.ApiKey`	Stringa	La tua API key KuCoin. Generala dalla pagina API Management di KuCoin.
`Kucoin.ApiSecret`	Stringa	Il tuo API secret KuCoin. Mantieni questo valore al sicuro e non esporlo mai nel codice client.
`Kucoin.Passphrase`	Stringa	La passphrase che hai impostato durante la creazione dell'API key. Richiesta per tutte le richieste autenticate.

Note importanti

Sicurezza: non scrivere mai a hard-code la tua API key, secret o passphrase direttamente nel codice di produzione. Usa un file di configurazione sicuro o una variabile d'ambiente per memorizzare le credenziali.

Usa TsgcWSAPI_Kucoin per il trading spot e TsgcWSAPI_Kucoin_Futures per il trading futures. Ogni componente si connette a un endpoint KuCoin diverso.
La proprietà Passphrase è obbligatoria per KuCoin e viene impostata durante la creazione dell'API key sul sito KuCoin.
Tutti i metodi REST restituiscono stringhe JSON. Usa un parser JSON (come TJSONObject da System.JSON) per analizzare le risposte.
I canali WebSocket pubblici non richiedono autenticazione e possono essere usati per dati di mercato senza impostare credenziali API.
I canali WebSocket privati e tutti i metodi REST che modificano lo stato dell'account richiedono credenziali API valide.
KuCoin applica rate limit sia sulle API REST che WebSocket. Consulta la documentazione ufficiale di KuCoin per i limiti correnti.
Le connessioni WebSocket usano un sistema di autenticazione basato su token. Il componente gestisce automaticamente l'acquisizione e il rinnovo dei token.