Actualización de la API Coinbase en sgcWebSockets

Integración de la API Coinbase Advanced Trade en Delphi

Coinbase Advanced Trade es la plataforma de trading profesional de uno de los exchanges de criptomonedas más utilizados del mundo. El componente TsgcWSAPI_Coinbase para Delphi proporciona acceso completo tanto a la API WebSocket como a la REST, permitiendo streaming de datos de mercado en tiempo real, gestión de órdenes, monitorización de cuentas y seguimiento de balances de futures desde una interfaz Delphi unificada.

Índice de contenidos

• Visión general
• Configuración
• API WebSocket
• REST API - cuentas
• REST API - productos y datos de mercado
• REST API - órdenes
• REST API - fills
• REST API - posiciones
• Ejemplo de código completo
• Notas y mejores prácticas

Visión general

La API Coinbase Advanced Trade reemplaza a la antigua API Coinbase Pro y proporciona una interfaz moderna para trading profesional de criptomonedas. Soporta tanto trading spot para una amplia variedad de activos crypto como contratos futures. La API usa dos mecanismos de transporte:

Transporte	Caso de uso	Autenticación
WebSocket	Streaming en tiempo real de datos de mercado, eventos de usuario y balances de futures	Requerida para canales privados, opcional para públicos
REST	Consultas de cuenta, colocación de órdenes, datos de producto y obtención de fills	Requerida para todos los endpoints privados

Configuración

Configura el componente TsgcWSAPI_Coinbase con tus credenciales API para acceder a los endpoints privados. Los endpoints públicos de datos de mercado pueden accederse sin autenticación.

Propiedad	Tipo	Descripción
Coinbase.ApiKey	String	Tu API key de Coinbase Advanced Trade
Coinbase.ApiSecret	String	Tu API secret de Coinbase Advanced Trade, usado para firmar peticiones

Nota: genera tus credenciales API desde la Coinbase Developer Platform. Al crear una key, selecciona el tipo de API Advanced Trade y asigna solo los permisos que tu aplicación necesite. Para aplicaciones solo de datos de mercado, puedes evitar crear API keys y usar únicamente los endpoints públicos.

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;

API WebSocket

La API WebSocket proporciona canales de streaming en tiempo real para datos de mercado y eventos privados de cuenta. Los canales públicos entregan datos de mercado generales sin autenticación, mientras que los canales privados envían eventos específicos de la cuenta.

Canales públicos

Método	Descripción
SubscribeHeartBeat / UnSubscribeHeartBeat	Connection health monitoring via periodic heartbeat messages for a given product
SubscribeStatus / UnSubscribeStatus	Product status updates including trading status and auction info
SubscribeTicker / UnSubscribeTicker	Real-time ticker data including price, 24h volume, and best bid/ask
SubscribeTickerBatch / UnSubscribeTickerBatch	Batched ticker updates delivered at reduced frequency for lower bandwidth usage
SubscribeLevel2 / UnSubscribeLevel2	Full Level 2 order book snapshots and incremental updates
SubscribeCandles / UnSubscribeCandles	Real-time OHLCV candle data for charting
SubscribeMarketTrades / UnSubscribeMarketTrades	Real-time feed of all trades executed on the exchange for a given product

Canales privados

Método	Descripción
SubscribeUser / UnSubscribeUser	Real-time updates on your orders (new, filled, cancelled) and account activity
SubscribeFuturesBalanceSummary / UnSubscribeFuturesBalanceSummary	Real-time updates on your futures account balance, margin, and liquidation price

// 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 - cuentas

Los endpoints de Accounts permiten consultar tu portfolio de Coinbase. Cada cuenta representa una única divisa o activo en tu portfolio con sus balances disponibles y retenidos.

Método	Descripción
ListAccounts	Returns a paginated list of all accounts in your portfolio with balances
GetAccount	Returns details for a single account by its 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 - productos y datos de mercado

Los endpoints de Products proporcionan datos de mercado, incluyendo pares de trading disponibles, snapshots del order book, datos históricos de candles, trades recientes y la hora actual del servidor. Todos son endpoints públicos y no requieren autenticación.

Método	Descripción
GetPublicProducts	Returns a list of all available products (trading pairs) with their details
GetPublicProduct	Returns details for a single product by its ID (e.g., BTC-USD)
GetPublicProductBook	Returns the current order book for a given product
GetPublicProductCandles	Returns OHLCV candle data for a product within a date range and granularity
GetTrades	Returns recent trades for a given product
GetTime	Returns the current Coinbase server time

Opciones de granularidad de candles

Valor	Descripción
ONE_MINUTE	1-minute candles
FIVE_MINUTE	5-minute candles
FIFTEEN_MINUTE	15-minute candles
THIRTY_MINUTE	30-minute candles
ONE_HOUR	1-hour candles
TWO_HOUR	2-hour candles
SIX_HOUR	6-hour candles
ONE_DAY	Daily candles

// 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 - órdenes

Los endpoints de Orders proporcionan gestión completa del ciclo de vida de la orden. Puedes colocar nuevas órdenes (market, limit o stop), consultar órdenes existentes, cancelar órdenes y previsualizar resultados antes de ejecutarlas.

Método	Descripción
PlaceNewOrder	Place a new order with full parameter control
PlaceMarketOrder	Convenience method for placing a market order (buy or sell at current price)
PlaceLimitOrder	Convenience method for placing a limit order at a specified price
PlaceStopOrder	Convenience method for placing a stop order that triggers at a specified price
ListOrders	Returns a paginated list of orders, optionally filtered by status or product
GetOrder	Returns details for a single order by its ID
CancelOrder	Cancel one or more open orders by their IDs
EditOrder	Modify an existing order (e.g., change price or size)
EditOrderPreview	Preview the result of an order edit without executing it
PreviewOrder	Preview the result of a new order without placing it (estimated fees, 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.ListOrders);
// Cancel an order by ID
oCoinbase.REST_API.CancelOrder('order-id-here');

Consejo: usa PreviewOrder antes de colocar órdenes en vivo para ver comisiones y resultados estimados sin arriesgar fondos reales. Es especialmente útil para órdenes market donde el precio final de ejecución depende de la profundidad del order book.

REST API - fills

Los fills representan las ejecuciones individuales que componen una orden completada o parcialmente rellenada. Una única orden puede resultar en varios fills si se empareja contra varias órdenes en reposo del libro. Puedes consultar fills por order ID, product ID o trade ID.

Método	Descripción
GetFillsByOrderId	Returns all fills for a specific order
GetFillsByProductId	Returns all fills for a specific product (e.g., BTC-USD)
GetFillsByTradeId	Returns fill details for a specific 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 - posiciones

El endpoint Positions se usa para gestionar posiciones de futures. Permite cerrar una posición de futures abierta.

Método	Descripción
ClosePosition	Closes an open futures position for a given product

Ejemplo de código completo

El siguiente ejemplo muestra un workflow completo: conectar con Coinbase, listar cuentas, obtener datos históricos de candles, suscribirse a un ticker en tiempo real y colocar una orden 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;

Notas y mejores prácticas

Permisos de la API Key

Al generar API keys en la Coinbase Developer Platform, sigue el principio de mínimo privilegio. Para un dashboard de solo lectura, habilita únicamente el permiso View. Para un bot de trading, añade el permiso Trade pero deja Transfer deshabilitado salvo que tu aplicación necesite mover fondos entre cuentas.

Constantes del lado de la orden

Al colocar órdenes, usa las constantes de enumeración Delphi para el lado de la orden:

Constante	Descripción
cosBuy	Orden de compra (adquirir la divisa base)
cosSell	Orden de venta (vender la divisa base)

Ticker vs. TickerBatch

Usa SubscribeTicker cuando necesites cada actualización de precio en tiempo real (p. ej., para un motor de ejecución de órdenes). Usa SubscribeTickerBatch cuando solo necesites snapshots periódicos (p. ej., para un dashboard) -- entrega los mismos datos a una frecuencia reducida, ahorrando ancho de banda y procesamiento.

Rate limits

Coinbase Advanced Trade impone rate limits a las llamadas a la REST API. Los límites varían por categoría de endpoint (público vs. privado, lectura vs. escritura). Evita hacer polling de endpoints REST en bucles cerrados; en su lugar, usa suscripciones WebSocket para datos en tiempo real y reserva las llamadas REST para consultas bajo demanda y operaciones de orden.

Consejo: para una aplicación de trading robusta, combina el canal SubscribeUser para actualizaciones de estado de órdenes en tiempo real con SubscribeTicker para precios de mercado en vivo. Usa los métodos REST PlaceMarketOrder o PlaceLimitOrder para ejecutar trades y confirma la ejecución mediante el canal de usuario en lugar de hacer polling de GetOrder.