Atualização da API XTB no sgcWebSockets

Integração da API de Negociação XTB xStation5 em Delphi

XTB é uma das principais plataformas de negociação online da Europa, oferecendo acesso a forex, índices, commodities, ações e criptomoedas por meio de sua plataforma xStation5. O componente TsgcWSAPI_XTB fornece uma integração Delphi completa com a API xStation5 por uma única conexão WebSocket — cobrindo autenticação, recuperação de dados de mercado, gerenciamento de conta, execução de negociações e assinaturas de streaming em tempo real. Este artigo percorre todos os métodos disponíveis e demonstra como começar em minutos.

Índice

• Visão Geral da Arquitetura
• Autenticação
• Métodos de Dados de Mercado
• Métodos de Conta
• Métodos de Negociação
• Assinaturas de Streaming
• Métodos Utilitários
• Primeiros Passos — Exemplo de Código
• Referência de Configuração
• Dicas e Notas

Visão Geral da Arquitetura

Ao contrário de muitas exchanges de criptomoedas que dividem a funcionalidade entre endpoints REST e canais WebSocket, a API XTB xStation5 opera inteiramente por uma única conexão WebSocket. Cada requisição — desde obter uma lista de símbolos até executar uma negociação — é enviada e recebida como uma mensagem JSON no mesmo socket. Um segundo socket de streaming é gerenciado automaticamente para assinaturas em tempo real (saldo, candles, ticks, negociações e mais).

O componente TsgcWSAPI_XTB abstrai tudo isso para você. Basta atribuir um TsgcWebSocketClient, configurar suas credenciais, ativar o cliente e chamar métodos de alto nível como GetAllSymbols ou SubscribeTickPrices.

Autenticação

A autenticação é realizada automaticamente quando o cliente WebSocket se conecta, usando as credenciais definidas no grupo de propriedades XTB. Você também pode chamar esses métodos explicitamente se necessário.

Método	Descrição
Login	Autentica no servidor xStation5 usando UserId e Password. Chamado automaticamente ao conectar.
Logout	Encerra a sessão autenticada e desconecta do servidor.

Métodos de Dados de Mercado

Esses métodos recuperam informações de instrumentos, preços, gráficos, notícias e horários de negociação do servidor xStation5. Todas as chamadas são requisição/resposta sobre a conexão WebSocket.

Método	Descrição
GetAllSymbols	Retorna uma lista de todos os instrumentos disponíveis na plataforma.
GetSymbol	Retorna informações detalhadas de um símbolo específico.
GetTickPrices	Retorna os preços de tick atuais (bid/ask) para os símbolos especificados.
GetTradingHours	Retorna os horários de negociação dos instrumentos informados.
GetCalendar	Retorna o calendário econômico de eventos futuros.
GetChartLastRequest	Retorna dados de candles do gráfico a partir de um timestamp específico até o momento atual.
GetChartRangeRequest	Retorna dados de candles do gráfico para um intervalo de datas específico.
GetNews	Retorna tópicos de notícias da plataforma de negociação XTB.
GetStepRules	Retorna as regras de passo para cálculos de volume.
GetServerTime	Retorna o horário atual do servidor.
GetVersion	Retorna o número da versão da API.

Métodos de Conta

Os métodos de conta permitem inspecionar seu perfil de usuário, níveis de margem e cálculos de lucro sem sair da sessão WebSocket.

Método	Descrição
GetCurrentUserData	Retorna informações sobre o usuário atualmente logado (nome, moeda, alavancagem, etc.).
GetMarginLevel	Retorna o nível de margem, patrimônio e saldo atuais da conta.
GetMarginTrade	Calcula a margem esperada para um determinado instrumento e volume.
GetIbsHistory	Retorna o histórico de comissões do Introducing Broker (IB).
GetProfitCalculation	Calcula o lucro estimado para um cenário de negociação específico.

Métodos de Negociação

Esses métodos cobrem tudo, desde a leitura de posições abertas e históricas até o envio e monitoramento de transações de negociação.

Método	Descrição
GetTrades	Retorna uma lista das negociações abertas no momento. Passe True para incluir apenas posições abertas.
GetTradesHistory	Retorna negociações encerradas dentro de um intervalo de tempo especificado.
GetTradeRecords	Retorna registros de negociação para números de ordem especificados.
TradeTransaction	Executa uma transação de negociação (abrir, fechar, modificar ou excluir uma ordem).
TradeTransactionStatus	Verifica o status atual de uma transação de negociação enviada anteriormente.

Assinaturas de Streaming

Os métodos de streaming abrem canais de dados em tempo real em uma conexão de streaming dedicada. Cada assinatura possui um método de cancelamento correspondente para interromper o recebimento de atualizações.

Assinar	Cancelar	Descrição
SubscribeBalance	UnSubscribeBalance	Atualizações de saldo e patrimônio em tempo real.
SubscribeCandles	UnSubscribeCandles	Atualizações ao vivo de candles/gráficos para um símbolo.
SubscribeKeepAlive	UnSubscribeKeepAlive	Mensagens periódicas de keep-alive para manter a conexão ativa.
SubscribeNews	UnSubscribeNews	Feed de notícias em tempo real da plataforma.
SubscribeProfits	UnSubscribeProfits	Atualizações de lucro/perda em tempo real nas posições abertas.
SubscribeTickPrices	UnSubscribeTickPrices	Preços de tick bid/ask ao vivo para um símbolo.
SubscribeTrades	UnSubscribeTrades	Atualizações em tempo real quando negociações são abertas, fechadas ou modificadas.
SubscribeTradeStatus	UnSubscribeTradeStatus	Alterações de status de transações de negociação em tempo real.
SubscribePing	—	Assina o ping de streaming para manter a conexão ativa (sem necessidade de cancelamento).

Nota: As assinaturas de streaming exigem um login bem-sucedido primeiro. O ID da sessão de streaming é obtido automaticamente durante a autenticação.

Métodos Utilitários

Método	Descrição
Ping	Envia um ping ao servidor para verificar se a conexão está ativa e evitar timeouts.

Primeiros Passos — Exemplo de Código

O exemplo a seguir cria uma conexão com o servidor demo do XTB, autentica, recupera símbolos e dados do usuário, assina preços de tick ao vivo e atualizações de saldo, e busca as negociações abertas.

var
  oClient: TsgcWebSocketClient;
  oXTB: TsgcWSAPI_XTB;
begin
  // Create the WebSocket client
  oClient := TsgcWebSocketClient.Create(nil);
  // Create the XTB API component
  oXTB := TsgcWSAPI_XTB.Create(nil);
  oXTB.Client := oClient;
  // Configure credentials
  oXTB.XTB.UserId := 'your_user_id';
  oXTB.XTB.Password := 'your_password';
  oXTB.XTB.Demo := True;
  // Connect and authenticate
  oClient.Active := True;
  // After the login event fires, call API methods:
  oXTB.GetAllSymbols;
  oXTB.GetCurrentUserData;
  // Subscribe to real-time tick prices for EURUSD
  oXTB.SubscribeTickPrices('EURUSD', 0, 0);
  // Subscribe to balance updates
  oXTB.SubscribeBalance;
  // Get all open trades
  oXTB.GetTrades(False);
end;

Tratando Respostas

Todas as respostas chegam de forma assíncrona pelos eventos do componente. Atribua tratadores a eventos como OnXTBResponse e OnXTBStreamingResponse para processar os dados JSON retornados. Cada resposta inclui um identificador de comando para que você possa direcionar ao processamento adequado.

Referência de Configuração

Toda a configuração é agrupada sob a propriedade XTB do componente TsgcWSAPI_XTB.

Propriedade	Tipo	Descrição
XTB.UserId	String	O ID de usuário da sua conta XTB.
XTB.Password	String	A senha da sua conta XTB.
XTB.Demo	Boolean	Defina como True para conectar ao servidor demo; False para o servidor de produção ao vivo.

Dicas e Notas

Demo vs. Ao Vivo

Sempre desenvolva e teste com XTB.Demo := True. O servidor demo usa a mesma superfície de API da produção, mas se conecta a um ambiente sandbox com fundos virtuais. Mude para False somente quando estiver pronto para negociações reais.

Manutenção da Conexão Ativa

O servidor XTB desconecta sessões ociosas após um período de timeout. Use SubscribePing ou chame Ping periodicamente para manter a conexão ativa. O método SubscribeKeepAlive na conexão de streaming tem um propósito semelhante.

Arquitetura de Conexão Única

Ao contrário de exchanges com endpoints REST separados, o XTB roteia todos os comandos por mensagens WebSocket. Isso simplifica a arquitetura do componente: você precisa apenas de um TsgcWebSocketClient e de um TsgcWSAPI_XTB — nenhum componente HTTP adicional é necessário.

Tratamento de Erros

Se uma requisição falhar, o servidor retorna uma resposta JSON de erro com um código e uma descrição de erro. Trate-os no evento de resposta verificando o campo status. Problemas comuns incluem credenciais inválidas, sessões expiradas e limitação de taxa por requisições excessivas.

Limites de taxa: A API XTB impõe limites de requisições por segundo. Evite enviar rajadas de requisições em loops fechados. Espaçe suas chamadas ou use assinaturas de streaming para dados que se atualizam com frequência.