Aggiornamento API Bybit per sgcWebSockets

Integrazione delle API WebSocket e REST Bybit V5 in Delphi

Bybit e' uno dei principali exchange di derivati e spot di criptovalute, con contratti perpetual, futures, spot trading e opzioni. Il componente TsgcWSAPI_Bybit offre l'integrazione completa in Delphi con l'API unificata Bybit V5 — combinando sottoscrizioni WebSocket per dati di mercato in tempo reale ed eventi privati, e un'interfaccia REST completa per trading, gestione delle posizioni e query sull'account. Questo articolo copre ogni metodo disponibile e ti mostra come connetterti, sottoscrivere e fare trading.

Indice

• Panoramica dell'architettura
• WebSocket API — Canali pubblici
• WebSocket API — Canali privati
• REST API — Market Data
• REST API — Trading
• REST API — Position Management
• REST API — Account
• Per iniziare — esempio di codice
• Riferimento configurazione
• Suggerimenti e note

Panoramica dell'architettura

L'API Bybit V5 e' un'interfaccia unificata che consolida spot, linear perpetual, inverse perpetual, inverse futures e opzioni sotto un unico set di endpoint. Il componente TsgcWSAPI_Bybit supporta entrambi i canali:

• WebSocket — Dati di mercato pubblici in tempo reale (libri degli ordini, trade, ticker, kline, liquidazioni) ed eventi privati dell'account (posizioni, esecuzioni, ordini, aggiornamenti del wallet).
• REST — Query e azioni on-demand tramite oBybit.REST_API, per recupero dei dati di mercato, piazzamento e gestione degli ordini, configurazione delle posizioni e informazioni sull'account.

Seleziona la categoria di prodotto tramite la proprieta' BybitClient, che determina l'endpoint WebSocket: bybSpot, bybLinear, bybInverse o bybPerpetual.

WebSocket API — Canali pubblici

I canali pubblici forniscono dati di mercato in tempo reale senza autenticazione. Ogni metodo di sottoscrizione ha un metodo unsubscribe corrispondente.

Subscribe	Unsubscribe	Descrizione
SubscribeOrderBook	UnSubscribeOrderBook	Snapshot della profondita' del libro degli ordini in tempo reale e aggiornamenti incrementali.
SubscribeTrade	UnSubscribeTrade	Esecuzioni di operazioni in tempo reale come avvengono sull'exchange.
SubscribeTicker	UnSubscribeTicker	Statistiche ticker su finestra mobile di 24 ore (prezzo, volume, variazione).
SubscribeKLine	UnSubscribeKLine	Aggiornamenti in tempo reale di candle/kline per un intervallo specificato.
SubscribeLiquidation	UnSubscribeLiquidation	Eventi di liquidazione su tutto l'exchange.
SubscribeLT_KLine	UnSubscribeLT_KLine	Aggiornamenti kline/candle per leveraged token.
SubscribeLT_Ticker	UnSubscribeLT_Ticker	Dati ticker per leveraged token.
SubscribeLT_Nav	UnSubscribeLT_Nav	Aggiornamenti del net asset value per leveraged token.

WebSocket API — Canali privati

I canali privati richiedono autenticazione tramite API key e secret. Forniscono aggiornamenti in tempo reale sull'attivita' del tuo account.

Subscribe	Unsubscribe	Descrizione
SubscribePosition	UnSubscribePosition	Aggiornamenti in tempo reale delle posizioni (size, prezzo di ingresso, PnL, leva).
SubscribeExecution	UnSubscribeExecution	Conferme di esecuzione delle operazioni quando i tuoi ordini vengono eseguiti.
SubscribeOrder	UnSubscribeOrder	Cambi di stato dell'ordine (nuovo, parzialmente eseguito, eseguito, annullato).
SubscribeWallet	UnSubscribeWallet	Variazioni di saldo del wallet su tutte le coin.
SubscribeGreek	UnSubscribeGreek	Aggiornamenti delle greche delle opzioni (delta, gamma, theta, vega).
SubscribeDcp	UnSubscribeDcp	Eventi di protezione dalla disconnessione per il monitoraggio della salute della connessione.

REST API — Market Data

Gli endpoint dei dati di mercato sono pubblici e non richiedono autenticazione. Accedi tramite oBybit.REST_API.

Metodo	Descrizione
GetServerTime	Restituisce il timestamp del server Bybit.
GetKLine	Restituisce dati storici di kline/candle per un simbolo e un intervallo.
GetMarkPriceKLine	Restituisce dati kline del mark price (utilizzati per i calcoli di PnL e liquidazione).
GetIndexPriceKLine	Restituisce dati kline del prezzo dell'indice.
GetPremiumIndexPriceKLine	Restituisce dati kline del premium index price per contratti perpetual.
GetInstrumentsInfo	Restituisce le specifiche degli strumenti (tick size, lot size, limiti di leva, ecc.).
GetOrderBook	Restituisce lo snapshot corrente del libro degli ordini a una data profondita'.
GetTickers	Restituisce le ultime informazioni ticker per uno o tutti i simboli.
GetFundingRateHistory	Restituisce i record storici del funding rate per contratti perpetual.
GetPublicRecentTradingHistory	Restituisce le operazioni pubbliche piu' recenti per un simbolo.
GetOpenInterest	Restituisce i dati di open interest per contratti derivati.
GetHistoricalVolatility	Restituisce la volatilita' storica per le opzioni.
GetInsurance	Restituisce lo storico del saldo dell'insurance fund.
GetRiskLimit	Restituisce i risk limit tier per un dato simbolo.
GetDeliveryPrice	Restituisce il delivery price per futures e opzioni scaduti.
GetLongShortRatio	Restituisce il rapporto long/short per un dato simbolo e periodo.

REST API — Trading

Gli endpoint di trading richiedono autenticazione tramite API key con i permessi appropriati. Questi metodi permettono di piazzare, modificare e annullare ordini.

Metodo	Descrizione
PlaceOrder	Piazza un nuovo ordine con pieno controllo dei parametri (tipo, side, prezzo, quantita', time-in-force, ecc.).
PlaceMarketOrder	Metodo di comodo che piazza un ordine market (viene eseguito immediatamente al miglior prezzo disponibile).
PlaceLimitOrder	Metodo di comodo che piazza un ordine limit a un prezzo specificato.
AmendOrder	Modifica un ordine aperto esistente (prezzo, quantita' o altri parametri).
CancelOrder	Annulla uno specifico ordine aperto tramite order ID.
GetOpenOrdini	Restituisce tutti gli ordini attualmente aperti (non eseguiti).
CancelAllOrdini	Annulla tutti gli ordini aperti, opzionalmente filtrati per simbolo o categoria.
GetOrderHistory	Restituisce lo storico degli ordini (eseguiti, annullati, rifiutati) entro un intervallo di tempo.

REST API — Position Management

Gli endpoint sulle posizioni permettono di interrogare e configurare le tue posizioni in derivati, inclusi leva, margin mode, risk limit e impostazioni di stop-loss/take-profit.

Metodo	Descrizione
GetPositionInfo	Restituisce i dettagli correnti della posizione (size, prezzo di ingresso, PnL non realizzato, margine).
SetLeverage	Imposta la leva per un dato simbolo.
SwitchCrossIsolatedMargin	Passa tra modalita' cross margin e isolated margin.
SetTPSLMode	Configura la modalita' take-profit/stop-loss (posizione totale o parziale).
SwitchPositionMode	Passa tra modalita' one-way e hedge mode.
SetRiskLimit	Imposta il risk limit tier per un simbolo, che influenza la leva massima.
SetTradingStop	Imposta trailing stop, take-profit o stop-loss su una posizione esistente.
SetAutoAddMargin	Abilita o disabilita l'auto-add margin per le posizioni in isolated margin.
AddOrReduceMargin	Aggiunge o rimuove manualmente margine da una posizione in isolated margin.
GetExecution	Restituisce i record di esecuzione/fill per le tue operazioni.
GetClosedPNL	Restituisce i record di profit and loss chiusi.
ConfirmNewRiskLimit	Conferma una modifica del risk limit quando e' richiesto margine aggiuntivo.

REST API — Account

Gli endpoint dell'account forniscono i saldi del wallet, la configurazione dell'account e i log delle transazioni.

Metodo	Descrizione
GetWalletBalance	Restituisce i saldi del wallet su tutte le coin o per un tipo di account specifico.
GetAccountInfo	Restituisce le informazioni dell'account unificato (margin mode, stato dell'account, ecc.).
GetTransactionLog	Restituisce lo storico delle transazioni (depositi, prelievi, operazioni, funding fee, ecc.).

Per iniziare — esempio di codice

L'esempio seguente mostra una configurazione completa: connessione all'endpoint linear perpetual di Bybit, query dei dati ticker via REST, piazzamento di un ordine limit, controllo del saldo del wallet e sottoscrizione agli aggiornamenti delle operazioni in tempo reale via WebSocket.

var
  oClient: TsgcWebSocketClient;
  oBybit: TsgcWSAPI_Bybit;
begin
  // Create the WebSocket client
  oClient := TsgcWebSocketClient.Create(nil);
  // Create the Bybit API component
  oBybit := TsgcWSAPI_Bybit.Create(nil);
  oBybit.Client := oClient;
  // Configure API credentials
  oBybit.Bybit.ApiKey := 'your_api_key';
  oBybit.Bybit.ApiSecret := 'your_api_secret';
  // Select the product category
  oBybit.BybitClient := bybLinear;
  // Connect to the WebSocket
  oClient.Active := True;
  // REST: Get ticker information for BTCUSDT
  ShowMessage(oBybit.REST_API.GetTickers('BTCUSDT'));
  // REST: Place a limit buy order
  ShowMessage(oBybit.REST_API.PlaceLimitOrder(bbsBuy, 'BTCUSDT', 0.001, 30000));
  // REST: Get wallet balance
  ShowMessage(oBybit.REST_API.GetWalletBalance);
  // WebSocket: Subscribe to real-time trades for BTCUSDT
  oBybit.SubscribeTrade('BTCUSDT');
end;

REST vs WebSocket

Usa l'API REST per operazioni on-demand come piazzare ordini, interrogare i saldi e recuperare dati storici. Usa le sottoscrizioni WebSocket per flussi di dati continui a bassa latenza. Le due possono essere usate contemporaneamente — le chiamate REST sono indipendenti dallo stato della connessione WebSocket.

Riferimento configurazione

Proprietà	Tipo	Descrizione
Bybit.ApiKey	String	La tua API key Bybit per le richieste autenticate.
Bybit.ApiSecret	String	Il tuo API secret Bybit per firmare le richieste.
Bybit.TestNet	Boolean	Imposta su True per connetterti all'ambiente testnet di Bybit; False per la mainnet.
Bybit.SignatureExpires	Integer	Tempo di scadenza in secondi per la firma HMAC (il default e' di solito sufficiente).
BybitClient	Enum	Categoria di prodotto: bybSpot, bybLinear, bybInverse o bybPerpetual.

Suggerimenti e note

Prima la testnet

Inizia sempre lo sviluppo con Bybit.TestNet := True. La testnet di Bybit fornisce un ambiente di simulazione completo con fondi di test. Puoi creare una API key separata per la testnet su testnet.bybit.com.

API V5 unificata

L'API V5 unifica tutti i tipi di prodotto sotto un unico set di endpoint. La proprieta' BybitClient determina a quale stream WebSocket ti connetti, mentre l'API REST instrada automaticamente verso la categoria corretta in base alle richieste.

Metodi di comodo per gli ordini

Mentre PlaceOrder ti da' pieno controllo su ogni parametro, i metodi di comodo PlaceMarketOrder e PlaceLimitOrder coprono gli scenari piu' comuni con meno parametri. Usa il metodo completo quando ti servono opzioni avanzate come reduce-only, time-in-force o trigger condizionali.

Rate limit

Bybit applica rate limit sia su REST sia su WebSocket. I limiti REST sono in genere per endpoint (ad esempio 10 richieste al secondo per il piazzamento degli ordini). Le sottoscrizioni WebSocket hanno un limite sul numero di topic simultanei. Monitora gli header di risposta e i codici di errore per restare nei limiti.

Note: Le connessioni WebSocket di Bybit inviano ping frame periodici. Il componente TsgcWSAPI_Bybit li gestisce automaticamente, mantenendo viva la tua connessione senza codice aggiuntivo.