Atualização da API MEXC no sgcWebSockets

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

MEXC é uma exchange global de criptomoedas que suporta negociação spot e contratos de futuros perpétuos em centenas de pares de tokens. Desenvolvedores Delphi podem integrar com a MEXC por meio de dois componentes dedicados: TsgcWSAPI_MEXC para o mercado Spot e TsgcWSAPI_MEXC_Futures para o mercado Futures. Cada componente oferece assinaturas WebSocket para dados em tempo real e uma interface REST para consultas sob demanda e gerenciamento de ordens. Este artigo detalha todos os métodos disponíveis em ambos os mercados.

Índice

Visão Geral da Arquitetura

A MEXC oferece superfícies de API separadas para seus mercados Spot e Futures. Na biblioteca sgcWebSockets, isso é refletido por dois componentes distintos:

Ambos os componentes seguem o mesmo padrão: atribua um TsgcWebSocketClient, configure as credenciais da API, ative o cliente para assinaturas WebSocket e acesse REST_API para chamadas HTTP síncronas.

API WebSocket Spot

A API WebSocket Spot fornece dados de mercado em tempo real por meio de canais públicos e atualizações de conta por canais privados. Cada assinatura possui um método de cancelamento correspondente.

Canais Públicos

Assinar Cancelar Descrição
SubscribeTrade UnSubscribeTrade Execuções de negociação em tempo real para um símbolo.
SubscribeKline UnSubscribeKline Atualizações ao vivo de candlestick/kline para um símbolo e intervalo.
SubscribeDiffDepth UnSubscribeDiffDepth Atualizações incrementais de profundidade do livro de ordens (stream diff).
SubscribeBookDepth UnSubscribeBookDepth Snapshots completos do livro de ordens em um nível específico.
SubscribeBookTicker UnSubscribeBookTicker Melhor preço e quantidade de compra/venda para um símbolo específico.
SubscribeBookTickerBatch UnSubscribeBookTickerBatch Melhores preços de compra/venda para todos os símbolos em um único stream.
SubscribeMiniTickers UnSubscribeMiniTickers Dados de ticker resumidos (preço, volume) para todos os símbolos.
SubscribeMiniTicker UnSubscribeMiniTicker Dados de ticker resumidos para um símbolo específico.

Canais Privados

Os canais privados requerem autenticação e entregam atualizações em tempo real sobre a atividade da sua conta. Ative o stream de dados do usuário por meio da propriedade MEXCUserDataStreams.UserStream.

Assinar Cancelar Descrição
SubscribeAccountUpdate UnSubscribeAccountUpdate Atualizações de saldo e posição da conta quando ocorrem alterações.
SubscribeAccountDeals UnSubscribeAccountDeals Notificações em tempo real quando suas ordens são executadas (negociações).
SubscribeAccountOrders UnSubscribeAccountOrders Alterações de status de ordens (criada, parcialmente executada, executada, cancelada).

API REST Spot

A API REST Spot é acessível por meio de oMEXC.REST_API (do tipo TsgcHTTP_API_MEXC_Spot). Os endpoints públicos não requerem autenticação; os endpoints privados requerem uma chave e um segredo de API válidos.

Endpoints Públicos

Método Descrição
Ping Testa a conectividade com o servidor da API MEXC.
GetServerTime Retorna o horário atual do servidor MEXC.
GetDefaultSymbols Retorna a lista de símbolos de negociação padrão.
GetExchangeInformation Retorna as regras de negociação da exchange e informações dos símbolos (filtros, precisão, status).
GetOrderBook Retorna o livro de ordens (ofertas de compra e venda) para um símbolo em uma profundidade específica.
GetTrades Retorna as negociações públicas recentes de um símbolo.
GetAggregateTrades Retorna registros de negociações agregadas/comprimidas.
GetKlines Retorna dados históricos de kline/candlestick para um símbolo e intervalo.
GetAveragePrice Retorna o preço médio atual de um símbolo.
Get24hrTicker Retorna estatísticas de variação de preço em janela deslizante de 24 horas.
GetPriceTicker Retorna o preço mais recente de um ou todos os símbolos.
GetBookTicker Retorna o melhor preço e quantidade de compra/venda do livro de ordens.

Endpoints Privados

Método Descrição
NewOrder Cria uma nova ordem spot (mercado, limite ou outros tipos suportados).
TestNewOrder Valida uma nova ordem sem realmente criá-la (simulação).
CancelOrder Cancela uma ordem aberta específica pelo ID da ordem.
CancelAllOrders Cancela todas as ordens abertas de um símbolo.
GetOrder Retorna o status e os detalhes de uma ordem específica.
GetOpenOrders Retorna todas as ordens atualmente abertas (não executadas).
GetAllOrders Retorna todas as ordens (abertas, executadas, canceladas) dentro de um intervalo de tempo.
GetAccountInformation Retorna os saldos e permissões da conta.
GetMyTrades Retorna o histórico de negociações para um símbolo.
GetSubAccounts Retorna uma lista de subcontas vinculadas à conta principal.
GetDepositAddress Retorna o endereço de depósito para uma moeda e rede específicas.
GetWithdrawHistory Retorna os registros de histórico de saques.
Withdraw Inicia um saque para um endereço externo.
GetCapitalConfig Retorna a configuração de capital (redes suportadas, valores mínimos/máximos de saque, taxas).

API WebSocket Futures

A API WebSocket Futures fornece dados em tempo real específicos para contratos de futuros perpétuos. Todos os canais são públicos e não requerem autenticação. Cada assinatura possui um método de cancelamento correspondente.

Assinar Cancelar Descrição
SubscribeDeal UnSubscribeDeal Execuções de negociação/deal de futuros em tempo real.
SubscribeTickers UnSubscribeTickers Dados de ticker para todos os contratos de futuros.
SubscribeTicker UnSubscribeTicker Dados de ticker para um contrato de futuros específico.
SubscribeDepth UnSubscribeDepth Atualizações incrementais de profundidade do livro de ordens para futuros.
SubscribeDepthFull UnSubscribeDepthFull Snapshots completos do livro de ordens para futuros.
SubscribeKline UnSubscribeKline Atualizações ao vivo de candlestick/kline para contratos de futuros.
SubscribeFundingRate UnSubscribeFundingRate Atualizações em tempo real da taxa de financiamento para contratos perpétuos.
SubscribeIndexPrice UnSubscribeIndexPrice Atualizações em tempo real do preço de índice.
SubscribeFairPrice UnSubscribeFairPrice Atualizações em tempo real do preço justo/mark utilizado para cálculos de liquidação.

API REST Futures

A API REST Futures é acessível por meio de oMEXCFut.REST_API (do tipo TsgcHTTP_API_MEXC_Futures). Abrange dados de mercado, gerenciamento de conta, controle de posições e operações de ordens.

Endpoints Públicos

Método Descrição
GetPing Testa a conectividade com o servidor da API MEXC Futures.
GetServerTime Retorna o horário atual do servidor de futuros.
GetContracts Retorna uma lista de todos os contratos de futuros disponíveis e suas especificações.
GetDepth Retorna a profundidade do livro de ordens para um contrato de futuros.
GetDeals Retorna o histórico público recente de negociações/deals para um contrato de futuros.
GetKlines Retorna dados históricos de kline/candlestick para um contrato de futuros.
GetIndexPrice Retorna o preço de índice atual de um contrato.
GetFairPrice Retorna o preço justo/mark atual de um contrato.
GetFundingRate Retorna a taxa de financiamento atual e prevista para um contrato perpétuo.

Endpoints Privados

Método Descrição
GetAccountAssets Retorna os saldos de ativos da conta de futuros e informações de margem.
GetPositionList Retorna todas as posições de futuros abertas com tamanho, preço de entrada e PnL.
SetPositionLeverage Define o multiplicador de alavancagem para um contrato de futuros específico.
PlaceOrder Cria uma nova ordem de futuros (mercado, limite ou outros tipos suportados).
CancelOrder Cancela uma ordem de futuros aberta específica.
CancelAllOrders Cancela todas as ordens de futuros abertas para um contrato.
GetOpenOrders Retorna todas as ordens de futuros atualmente abertas.
GetOrderHistory Retorna o histórico de ordens de futuros (executadas, canceladas, etc.).
GetFundingHistory Retorna o histórico de pagamentos de taxas de financiamento.

Primeiros Passos — Exemplos de Código

Exemplo de Mercado Spot

O exemplo a seguir conecta ao WebSocket Spot da MEXC, assina negociações em tempo real, consulta informações da exchange via REST e cria uma ordem de compra a mercado. 

var
  oClient: TsgcWebSocketClient;
  oMEXC: TsgcWSAPI_MEXC;
begin
  // Create the WebSocket client
  oClient := TsgcWebSocketClient.Create(nil);
  // Create the MEXC Spot API component
  oMEXC := TsgcWSAPI_MEXC.Create(nil);
  oMEXC.Client := oClient;
  // Configure API credentials
  oMEXC.MEXCAPI.ApiKey := 'your_api_key';
  oMEXC.MEXCAPI.ApiSecret := 'your_api_secret';
  // Connect to the WebSocket
  oClient.Active := True;
  // WebSocket: Subscribe to real-time trades for BTCUSDT
  oMEXC.SubscribeTrade('BTCUSDT');
  // REST: Get exchange information
  ShowMessage(oMEXC.REST_API.GetExchangeInformation);
  // REST: Place a market buy order for 0.001 BTC
  ShowMessage(oMEXC.REST_API.NewOrder('BTCUSDT', 'BUY', 'MARKET', '', 0.001));
end;

Exemplo de Mercado Futures

Este exemplo conecta ao WebSocket Futures da MEXC, assina um ticker de futuros e consulta os contratos disponíveis via REST. 

var
  oClientFut: TsgcWebSocketClient;
  oMEXCFut: TsgcWSAPI_MEXC_Futures;
begin
  // Create the WebSocket client for futures
  oClientFut := TsgcWebSocketClient.Create(nil);
  // Create the MEXC Futures API component
  oMEXCFut := TsgcWSAPI_MEXC_Futures.Create(nil);
  oMEXCFut.Client := oClientFut;
  // Configure API credentials
  oMEXCFut.MEXCFuturesAPI.ApiKey := 'your_api_key';
  oMEXCFut.MEXCFuturesAPI.ApiSecret := 'your_api_secret';
  // Connect to the WebSocket
  oClientFut.Active := True;
  // WebSocket: Subscribe to futures ticker for BTC_USDT
  oMEXCFut.SubscribeTicker('BTC_USDT');
  // REST: Get all available futures contracts
  ShowMessage(oMEXCFut.REST_API.GetContracts);
end;
Nota: Spot e Futures usam conexões WebSocket separadas e componentes de API separados. Você precisa de uma instância distinta de TsgcWebSocketClient para cada um.

Referência de Configuração

Configuração Spot

Propriedade Tipo Descrição
MEXCAPI.ApiKey String Sua chave de API MEXC para requisições spot autenticadas.
MEXCAPI.ApiSecret String Seu segredo de API MEXC para assinar requisições.
MEXCUserDataStreams.UserStream Boolean Defina como True para habilitar o stream privado de dados do usuário para atualizações de conta, deals e eventos de ordens.

Configuração Futures

Propriedade Tipo Descrição
MEXCFuturesAPI.ApiKey String Sua chave de API MEXC para requisições futures autenticadas.
MEXCFuturesAPI.ApiSecret String Seu segredo de API MEXC para assinar requisições de futuros.

Dicas e Notas

Componentes Separados para Spot e Futures

A MEXC trata Spot e Futures como mercados completamente separados, com endpoints de API diferentes, convenções de nomenclatura de símbolos diferentes (por exemplo, BTCUSDT para spot vs. BTC_USDT para futuros) e escopos de autenticação distintos. Sempre use o componente correto para o mercado-alvo.

Streams de Dados do Usuário

Para receber eventos privados de conta no WebSocket Spot (atualizações de conta, deals, alterações de ordens), você deve definir MEXCUserDataStreams.UserStream := True antes de ativar o cliente. Isso instrui o componente a solicitar uma chave de escuta e estabelecer o stream privado automaticamente.

Teste de Ordens

Use o método TestNewOrder na API REST Spot para validar os parâmetros de uma ordem sem realmente criá-la. Isso é útil para verificar se os parâmetros de símbolo, lado, tipo e quantidade estão corretamente formatados antes de comprometer fundos reais.

Convenções de Nomenclatura de Símbolos

Preste atenção aos diferentes formatos de símbolo entre os dois mercados. O Spot usa pares concatenados como BTCUSDT, enquanto o Futures usa pares separados por sublinhado como BTC_USDT. Usar o formato errado resultará em erros de "símbolo não encontrado".

Limites de Taxa

A MEXC impõe limites de taxa nas APIs REST e WebSocket. Os endpoints REST geralmente permitem um número fixo de requisições por minuto. Se você exceder o limite, receberá um código de status 429. Implemente lógica de recuo adequada ou use assinaturas WebSocket para dados que mudam com frequência.

Dica: Para monitoramento de alta frequência, prefira assinaturas WebSocket em vez de polling nos endpoints REST. As assinaturas entregam dados em tempo real com menor latência e não contam contra os limites de taxa REST.