Aggiornamento API Coinbase per sgcWebSockets

Integrazione dell'API Coinbase Advanced Trade in Delphi

Coinbase Advanced Trade e' la piattaforma di trading professionale di uno degli exchange di criptovalute piu' utilizzati al mondo. Il componente TsgcWSAPI_Coinbase per Delphi fornisce accesso completo sia all'API WebSocket sia a quella REST, abilitando lo streaming di dati di mercato in tempo reale, la gestione degli ordini, il monitoraggio dell'account e il tracking dei saldi futures da un'interfaccia Delphi unificata.

Indice

• Panoramica
• Configurazione
• WebSocket API
• REST API - Accounts
• REST API - Products and Market Data
• REST API - Ordini
• REST API - Fills
• REST API - Positions
• Esempio di codice completo
• Note e best practice

Panoramica

L'API Coinbase Advanced Trade sostituisce la vecchia API Coinbase Pro e fornisce un'interfaccia moderna per il trading professionale di criptovalute. Supporta sia il trading spot per una vasta gamma di asset crypto sia i contratti futures. L'API utilizza due meccanismi di trasporto:

Trasporto	Caso d'uso	Autenticazione
WebSocket	Streaming in tempo reale di dati di mercato, eventi utente e saldi futures	Richiesta per i canali privati, facoltativa per quelli pubblici
REST	Query sull'account, piazzamento ordini, dati di prodotto e recupero dei fill	Richiesta per tutti gli endpoint privati

Configurazione

Configura il componente TsgcWSAPI_Coinbase con le tue credenziali API per accedere agli endpoint privati. Gli endpoint pubblici dei dati di mercato sono accessibili senza autenticazione.

Proprietà	Tipo	Descrizione
Coinbase.ApiKey	String	La tua API key Coinbase Advanced Trade
Coinbase.ApiSecret	String	Il tuo API secret Coinbase Advanced Trade, usato per firmare le richieste

Note: Genera le tue credenziali API dalla Coinbase Developer Platform. Quando crei una key, seleziona il tipo di API Advanced Trade e assegna solo i permessi che servono alla tua applicazione. Per applicazioni di soli dati di mercato puoi saltare del tutto la creazione delle API key e usare solo gli endpoint pubblici.

var
  oClient: TsgcWebSocketClient;
  oCoinbase: TsgcWSAPI_Coinbase;
begin
  oClient := TsgcWebSocketClient.Create(nil);
  oCoinbase := TsgcWSAPI_Coinbase.Create(nil);
  oCoinbase.Client := oClient;
  // Configure API credentials
  oCoinbase.Coinbase.ApiKey := 'your_api_key';
  oCoinbase.Coinbase.ApiSecret := 'your_api_secret';
  // Connect to Coinbase
  oClient.Active := True;
end;

WebSocket API

L'API WebSocket fornisce canali di streaming in tempo reale per dati di mercato ed eventi privati dell'account. I canali pubblici recapitano dati a livello di mercato senza autenticazione, mentre i canali privati trasmettono eventi specifici dell'account.

Canali pubblici

Metodo	Descrizione
SubscribeHeartBeat / UnSubscribeHeartBeat	Monitoraggio della salute della connessione tramite messaggi heartbeat periodici per un dato prodotto
SubscribeStatus / UnSubscribeStatus	Aggiornamenti di stato del prodotto, inclusi stato di trading e informazioni d'asta
SubscribeTicker / UnSubscribeTicker	Dati ticker in tempo reale, inclusi prezzo, volume 24h e miglior bid/ask
SubscribeTickerBatch / UnSubscribeTickerBatch	Aggiornamenti ticker batch recapitati a frequenza ridotta per consumare meno banda
SubscribeLevel2 / UnSubscribeLevel2	Snapshot completi del libro degli ordini Level 2 e aggiornamenti incrementali
SubscribeCandles / UnSubscribeCandles	Dati candle OHLCV in tempo reale per il charting
SubscribeMarketTrades / UnSubscribeMarketTrades	Feed in tempo reale di tutte le operazioni eseguite sull'exchange per un dato prodotto

Canali privati

Metodo	Descrizione
SubscribeUser / UnSubscribeUser	Aggiornamenti in tempo reale sui tuoi ordini (nuovi, eseguiti, annullati) e sull'attivita' dell'account
SubscribeFuturesBalanceSummary / UnSubscribeFuturesBalanceSummary	Aggiornamenti in tempo reale sul saldo dell'account futures, margine e prezzo di liquidazione

// Subscribe to real-time ticker for BTC-USD
oCoinbase.SubscribeTicker('BTC-USD');
// Subscribe to Level 2 order book updates
oCoinbase.SubscribeLevel2('BTC-USD');
// Subscribe to candle data for charting
oCoinbase.SubscribeCandles('ETH-USD');
// Subscribe to live market trades
oCoinbase.SubscribeMarketTrades('BTC-USD');
// Subscribe to private user channel (requires API key)
oCoinbase.SubscribeUser('BTC-USD');
// Subscribe to futures balance updates
oCoinbase.SubscribeFuturesBalanceSummary;

REST API - Accounts

Gli endpoint Accounts permettono di interrogare il tuo portafoglio Coinbase. Ogni account rappresenta una singola valuta o asset nel tuo portafoglio con i saldi available e held.

Metodo	Descrizione
ListAccounts	Restituisce un elenco paginato di tutti gli account del tuo portafoglio con i relativi saldi
GetAccount	Restituisce i dettagli di un singolo account tramite il suo UUID

// List all accounts in your portfolio
ShowMessage(oCoinbase.REST_API.ListAccounts);
// Get details for a specific account by UUID
ShowMessage(oCoinbase.REST_API.GetAccount('account-uuid-here'));

REST API - Products and Market Data

Gli endpoint Products forniscono dati di mercato inclusi coppie di trading disponibili, snapshot del libro degli ordini, dati storici delle candele, operazioni recenti e l'ora corrente del server. Sono tutti endpoint pubblici e non richiedono autenticazione.

Metodo	Descrizione
GetPublicProducts	Restituisce un elenco di tutti i prodotti disponibili (coppie di trading) con i relativi dettagli
GetPublicProduct	Restituisce i dettagli di un singolo prodotto tramite il suo ID (ad esempio BTC-USD)
GetPublicProductBook	Restituisce il libro degli ordini corrente per un dato prodotto
GetPublicProductCandles	Restituisce dati candle OHLCV per un prodotto entro un intervallo di date e granularita'
GetTrades	Restituisce le operazioni recenti per un dato prodotto
GetTime	Restituisce l'ora corrente del server Coinbase

Opzioni di granularita' delle candele

Valore	Descrizione
ONE_MINUTE	Candele a 1 minuto
FIVE_MINUTE	Candele a 5 minuti
FIFTEEN_MINUTE	1Candele a 5 minuti
THIRTY_MINUTE	Candele a 30 minuti
ONE_HOUR	Candele a 1 ora
TWO_HOUR	Candele a 2 ore
SIX_HOUR	Candele a 6 ore
ONE_DAY	Candele giornaliere

// Get all available products
ShowMessage(oCoinbase.REST_API.GetPublicProducts);
// Get details for BTC-USD
ShowMessage(oCoinbase.REST_API.GetPublicProduct('BTC-USD'));
// Get hourly candles for January 2024
ShowMessage(oCoinbase.REST_API.GetPublicProductCandles(
  'BTC-USD', '2024-01-01', '2024-01-31', 'ONE_HOUR'));
// Get recent trades
ShowMessage(oCoinbase.REST_API.GetTrades('BTC-USD'));

REST API - Ordini

Gli endpoint Ordini forniscono la gestione completa del ciclo di vita degli ordini. Puoi piazzare nuovi ordini (market, limit o stop), interrogare gli ordini esistenti, annullare ordini e fare il preview dei risultati prima dell'esecuzione.

Metodo	Descrizione
PlaceNewOrder	Piazza un nuovo ordine con pieno controllo dei parametri
PlaceMarketOrder	Metodo di comodo per piazzare un ordine market (acquisto o vendita al prezzo corrente)
PlaceLimitOrder	Metodo di comodo per piazzare un ordine limit a un prezzo specificato
PlaceStopOrder	Metodo di comodo per piazzare un ordine stop che si attiva a un prezzo specificato
ListOrdini	Restituisce un elenco paginato di ordini, opzionalmente filtrato per stato o prodotto
GetOrder	Restituisce i dettagli di un singolo ordine tramite il suo ID
CancelOrder	Annulla uno o piu' ordini aperti tramite i relativi ID
EditOrder	Modifica un ordine esistente (ad esempio cambiare prezzo o size)
EditOrderPreview	Anteprima del risultato di una modifica dell'ordine senza eseguirla
PreviewOrder	Anteprima del risultato di un nuovo ordine senza piazzarlo (commissioni stimate, slippage)

// Place a market buy order for 0.001 BTC
ShowMessage(oCoinbase.REST_API.PlaceMarketOrder(cosBuy, 'BTC-USD', 0.001));
// Place a limit buy order at $40,000
ShowMessage(oCoinbase.REST_API.PlaceLimitOrder(cosBuy, 'BTC-USD', 0.001, 40000));
// List all open orders
ShowMessage(oCoinbase.REST_API.ListOrdini);
// Cancel an order by ID
oCoinbase.REST_API.CancelOrder('order-id-here');

Tip: Usa PreviewOrder prima di piazzare ordini live per vedere le commissioni stimate e i risultati di esecuzione senza rischiare fondi reali. E' particolarmente utile per gli ordini market in cui il prezzo finale di esecuzione dipende dalla profondita' del libro degli ordini.

REST API - Fills

I fill rappresentano le esecuzioni individuali che compongono un ordine completato o parzialmente eseguito. Un singolo ordine puo' produrre piu' fill se viene abbinato a piu' ordini in coda nel libro. Puoi interrogare i fill per order ID, product ID o trade ID.

Metodo	Descrizione
GetFillsByOrderId	Restituisce tutti i fill per uno specifico ordine
GetFillsByProductId	Restituisce tutti i fill per uno specifico prodotto (ad esempio BTC-USD)
GetFillsByTradeId	Restituisce i dettagli del fill per uno specifico trade ID

// Get fills for a specific order
ShowMessage(oCoinbase.REST_API.GetFillsByOrderId('order-id-here'));
// Get all fills for BTC-USD
ShowMessage(oCoinbase.REST_API.GetFillsByProductId('BTC-USD'));

REST API - Positions

L'endpoint Positions serve per gestire le posizioni futures. Ti permette di chiudere una posizione futures aperta.

Metodo	Descrizione
ClosePosition	Chiude una posizione futures aperta per un dato prodotto

Esempio di codice completo

L'esempio seguente mostra un workflow completo: connessione a Coinbase, elenco degli account, recupero di dati storici delle candele, sottoscrizione a un ticker in tempo reale e piazzamento di un ordine market.

var
  oClient: TsgcWebSocketClient;
  oCoinbase: TsgcWSAPI_Coinbase;
begin
  // Create and configure the WebSocket client
  oClient := TsgcWebSocketClient.Create(nil);
  oCoinbase := TsgcWSAPI_Coinbase.Create(nil);
  oCoinbase.Client := oClient;
  // Configure API credentials
  oCoinbase.Coinbase.ApiKey := 'your_api_key';
  oCoinbase.Coinbase.ApiSecret := 'your_api_secret';
  // Connect to Coinbase
  oClient.Active := True;
  // REST: List all accounts in your portfolio
  ShowMessage(oCoinbase.REST_API.ListAccounts);
  // REST: Get hourly candles for BTC-USD
  ShowMessage(oCoinbase.REST_API.GetPublicProductCandles(
    'BTC-USD', '2024-01-01', '2024-01-31', 'ONE_HOUR'));
  // WebSocket: Subscribe to real-time ticker
  oCoinbase.SubscribeTicker('BTC-USD');
  // REST: Place a market buy order for 0.001 BTC
  ShowMessage(oCoinbase.REST_API.PlaceMarketOrder(cosBuy, 'BTC-USD', 0.001));
end;

Note e best practice

Permessi delle API key

Quando generi le API key sulla Coinbase Developer Platform, segui il principio del minimo privilegio. Per una dashboard di sola lettura, abilita solo il permesso View. Per un trading bot aggiungi il permesso Trade ma lascia disabilitato Transfer a meno che l'applicazione non debba spostare fondi tra account.

Costanti dell'order side

Quando piazzi ordini, usa le costanti di enumerazione Delphi per l'order side:

Costante	Descrizione
cosBuy	Ordine di acquisto (acquisisce la valuta base)
cosSell	Ordine di vendita (vende la valuta base)

Ticker vs TickerBatch

Usa SubscribeTicker quando hai bisogno di ogni aggiornamento di prezzo in tempo reale (ad esempio per un motore di esecuzione ordini). Usa SubscribeTickerBatch quando ti bastano snapshot periodici (ad esempio per una dashboard) — recapita gli stessi dati a frequenza ridotta, risparmiando banda e overhead di elaborazione.

Rate limit

Coinbase Advanced Trade impone rate limit sulle chiamate all'API REST. I limiti variano per categoria di endpoint (pubblico vs privato, lettura vs scrittura). Evita di fare polling degli endpoint REST in cicli stretti; usa invece le sottoscrizioni WebSocket per i dati in tempo reale e riserva le chiamate REST a query on-demand e operazioni sugli ordini.

Tip: Per un'applicazione di trading robusta, combina il canale SubscribeUser per gli aggiornamenti di stato degli ordini in tempo reale con SubscribeTicker per i prezzi di mercato live. Usa i metodi REST PlaceMarketOrder o PlaceLimitOrder per eseguire le operazioni e conferma l'esecuzione tramite il canale user invece di fare polling di GetOrder.