Atualização da API KuCoin no sgcWebSockets

· Recursos
Integração da API KuCoin Spot e Futures em Delphi

Os componentes TsgcWSAPI_Kucoin e TsgcWSAPI_Kucoin_Futures oferecem acesso completo em Delphi à exchange KuCoin, abrangendo dados de mercado em tempo real via WebSocket, streams de conta privada e uma API REST completa para negociação, saques e consultas de mercado. Este guia cobre todos os métodos disponíveis nas versões spot e futuros, com detalhes de configuração e exemplos de código funcionais.

Índice

Spot WebSocket API

A Spot WebSocket API oferece streaming em tempo real para dados de mercado e eventos de conta privada. Os canais públicos estão disponíveis sem autenticação, enquanto os canais privados exigem credenciais de API válidas.

Canais Públicos

Os canais públicos transmitem dados de mercado para todos os clientes conectados sem exigir autenticação. Cada método de inscrição possui um método de cancelamento correspondente.

Método Descrição
SubscribeSymbolTicker Assina atualizações de ticker em tempo real para um símbolo de negociação específico.
SubscribeAllSymbolsTicker Assina atualizações de ticker para todos os símbolos da exchange.
SubscribeSymbolSnapshot Assina dados de snapshot para um símbolo específico, incluindo estatísticas de 24h.
SubscribeMarketSnapshot Assina atualizações de snapshot do mercado como um todo.
SubscribeLevel2MarketData Assina alterações no livro de ordens Level 2 (profundidade total).
SubscribeLevel2_5BestAskBid Assina os 5 melhores níveis de venda e compra do livro de ordens.
SubscribeLevel2_50BestAskBid Assina os 50 melhores níveis de venda e compra do livro de ordens.
SubscribeKlines Assina dados de candlestick/kline para um símbolo no intervalo especificado.
SubscribeMatchExecutionData Assina dados de execução de negociações em tempo real para um símbolo.
SubscribeIndexPrice Assina atualizações de preço do índice para um símbolo.
SubscribeMarkPrice Assina atualizações do preço de marcação para um símbolo.
SubscribeOrderBookChanged Assina eventos de alteração no livro de ordens de um símbolo.
Nota: Todo método Subscribe listado acima possui um método UnSubscribe correspondente (ex.: UnSubscribeSymbolTicker) para interromper o recebimento de atualizações daquele canal.

Canais Privados

Os canais privados exigem credenciais de API válidas e fornecem atualizações em tempo real sobre suas ordens, saldos, posições e atividades de margem.

Método Descrição
SubscribeTradeOrders Assina atualizações em tempo real das suas ordens de negociação (abertas, executadas, canceladas).
SubscribeAccountBalance Assina alterações de saldo da conta em tempo real.
SubscribePositionStatus Assina atualizações de status de posição para negociação com margem.
SubscribeMarginTradeOrders Assina atualizações de ordens de negociação com margem.
SubscribeStopOrder Assina atualizações de acionamento e status de ordens stop.

Spot REST API

A Spot REST API é acessada pela propriedade REST_API de TsgcWSAPI_Kucoin. Todos os métodos retornam strings JSON. A API cobre contas, saques, gerenciamento de ordens, ordens stop e dados de mercado.

Contas

Método Descrição
GetAccounts Retorna uma lista de todas as contas (principal, negociação, margem).
GetAccount Retorna detalhes de uma conta específica pelo ID da conta.
GetAccountBalanceSubAccount Retorna o saldo de uma subconta.
InnerTransfer Transfere fundos entre suas contas internas (ex.: da principal para a de negociação).

Saques

Método Descrição
GetWithdrawalsList Retorna uma lista dos registros de saque recentes.
GetHistoricalWithdrawalsList Retorna registros históricos de saques além da janela recente.
GetWithdrawalsQuotas Retorna a cota e os limites de saque para uma determinada moeda.
ApplyWithdraw Inicia um saque para um endereço externo.
CancelWithdraw Cancela um saque pendente pelo seu ID.

Ordens

Método Descrição
PlaceOrder Envia uma nova ordem spot (mercado ou limite, compra ou venda).
PlaceMarginOrder Envia uma ordem de margem com fundos emprestados.
CancelOrderByClientOid Cancela uma ordem usando o ID de ordem atribuído pelo cliente.
GetOrder Retorna detalhes de uma ordem específica pelo ID atribuído pela exchange.
GetOrderByClientOid Retorna detalhes de uma ordem específica pelo ID atribuído pelo cliente.
ListFills Retorna uma lista de ordens executadas (negociações realizadas).
GetRecentFills Retorna os registros de execução mais recentes.

Ordens Stop

Método Descrição
PlaceStopOrder Envia uma ordem stop que é acionada quando o preço stop é atingido.
PlaceStopMarketOrder Envia uma ordem stop-mercado que executa ao preço de mercado após ser acionada.
PlaceStopLimitOrder Envia uma ordem stop-limite que cria uma ordem limite após ser acionada.
CancelStopOrder Cancela uma ordem stop pelo ID atribuído pela exchange.
CancelStopOrderByClientOid Cancela uma ordem stop pelo ID atribuído pelo cliente.
CancelAllStopOrders Cancela todas as ordens stop ativas, com filtro opcional por símbolo.
GetStopOrder Retorna detalhes de uma ordem stop específica pelo ID atribuído pela exchange.
GetStopOrderByClientOid Retorna detalhes de uma ordem stop específica pelo ID atribuído pelo cliente.
ListStopOrders Retorna uma lista de todas as ordens stop ativas.

Dados de Mercado

Método Descrição
GetSymbolList Retorna uma lista de símbolos de negociação disponíveis.
GetAllTickers Retorna dados de ticker para todos os pares de negociação.
GetMarketList Retorna uma lista de mercados disponíveis.
GetPartOrderBook100 Retorna as 100 principais entradas do livro de ordens de um símbolo.
GetFullOrderBook Retorna o livro de ordens completo de um símbolo (dados Level 3).
GetHistories Retorna o histórico de negociações recentes de um símbolo.
GetKLines Retorna dados de candlestick/kline de um símbolo em um determinado intervalo.
GetCurrencies Retorna uma lista de todas as moedas suportadas.
GetCurrencyDetail Retorna detalhes de uma moeda específica (info de rede, precisão, etc.).
GetFiatPrice Retorna o preço em moeda fiduciária para as moedas especificadas (ex.: valor em USD do BTC).

Futures WebSocket API

A Futures WebSocket API é fornecida pelo componente TsgcWSAPI_Kucoin_Futures e oferece streaming em tempo real para dados de contratos futuros e eventos de conta privada.

Canais Públicos

Método Descrição
SubscribeSymbolTickerV2 Assina atualizações de ticker V2 para um símbolo de contrato futuro.
SubscribeSymbolTicker Assina atualizações de ticker para um símbolo de contrato futuro.
SubscribeLevel2MarketData Assina dados do livro de ordens Level 2 para um contrato futuro.
SubscribeExecutionData Assina dados de execução de negociações de futuros em tempo real.
SubscribeLevel2_5BestAskBid Assina os 5 melhores níveis de venda/compra para um contrato futuro.
SubscribeLevel2_50BestAskBid Assina os 50 melhores níveis de venda/compra para um contrato futuro.
SubscribeContractMarketData Assina dados de mercado no nível do contrato (taxa de financiamento, preço de marcação, etc.).
SubscribeSystemAnnouncements Assina anúncios gerais do sistema e avisos de manutenção.
SubscribeTransactionStatistics Assina estatísticas agregadas de transações para um contrato futuro.
Nota: Todo método Subscribe listado nas tabelas de futuros possui um método UnSubscribe correspondente para interromper o recebimento de atualizações daquele canal.

Canais Privados

Método Descrição
SubscribeTradeOrders Assina atualizações em tempo real das suas ordens de futuros.
SubscribeStopOrder Assina atualizações de acionamento e status de ordens stop para futuros.
SubscribeAccountBalance Assina alterações de saldo da conta de futuros em tempo real.
SubscribePositionChange Assina eventos de alteração de posição (abertura, fechamento, liquidação).

Futures REST API

A Futures REST API é acessada pela propriedade REST_API de TsgcWSAPI_Kucoin_Futures. Esses métodos cobrem gerenciamento de margem, limites de risco, histórico de financiamento e consultas ao livro de ordens.

Método Descrição
AddMarginManually Adiciona margem manualmente a uma posição de futuros.
ObtainFuturesRiskLimitLevel Retorna o nível de limite de risco atual para um contrato futuro.
AdjustRiskLimitLevel Ajusta o nível de limite de risco de um contrato futuro.
GetFundingHistory Retorna o histórico de taxas de financiamento de um contrato futuro.
GetPartOrderBook100 Retorna as 100 principais entradas do livro de ordens de futuros.
GetFullOrderBook Retorna o livro de ordens de futuros completo.
GetLevel2PullingMessages Retorna mensagens de pulling Level 2 para atualizações incrementais do livro de ordens.
GetInterestRateList Retorna a lista de taxas de juros usadas nos cálculos de financiamento.
GetIndexList Retorna a lista de composição do índice para um contrato futuro.

Exemplo de Código

O exemplo a seguir demonstra como criar e configurar o componente TsgcWSAPI_Kucoin para negociação spot, autenticar-se na API, obter tickers via REST, enviar uma ordem e assinar um stream de ticker em tempo real 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;

Tratando Eventos WebSocket

Atribua um tratador de eventos para processar as mensagens recebidas. O evento fornece o tópico, o assunto e os dados JSON de cada atualização. 

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;

Configuração e Notas

Propriedades de Configuração

Tanto o TsgcWSAPI_Kucoin (spot) quanto o TsgcWSAPI_Kucoin_Futures (futuros) compartilham as mesmas propriedades de autenticação, acessadas pela propriedade Kucoin.

Propriedade Tipo Descrição
Kucoin.ApiKey String Sua chave de API do KuCoin. Gere-a na página de Gerenciamento de API do KuCoin.
Kucoin.ApiSecret String Seu segredo de API do KuCoin. Mantenha este valor seguro e nunca o exponha em código do lado do cliente.
Kucoin.Passphrase String A frase secreta que você definiu ao criar a chave de API. Obrigatória em todas as requisições autenticadas.

Notas Importantes

Segurança: Nunca inclua sua chave de API, segredo ou frase secreta diretamente no código de produção. Use um arquivo de configuração seguro ou variável de ambiente para armazenar as credenciais.