API MEXC Futures

Os contratos perpétuos e de entrega da MEXC expõem uma API de streaming dedicada documentada na especificação oficial Futures WebSocket. O componente TsgcWSAPI_MEXC_Futures encapsula a conexão, o handshake de login e o gerenciamento de tópicos necessários para consumir dados de derivativos em tempo real.

 

A MEXC também mantém uma interface REST para trading de derivativos. O componente TsgcHTTP_API_MEXC_Futures contido em sgcHTTP_API_MEXC complementa os feeds WebSocket com auxiliares HTTP que mapeiam um-para-um aos endpoints oficiais.

 

Configuração do componente

O endpoint WebSocket de Futures é wss://contract.mexc.com/edge. As mensagens são codificadas como objetos JSON e a exchange exige frames ping/pong periódicos, que são tratados automaticamente pelo componente.

 

Para receber notificações privadas (dados de ordem e de conta), você deve autenticar. Defina MEXCAPI.ApiKey e MEXCAPI.ApiSecret antes de ativar o cliente WebSocket. Quando as credenciais estão presentes, o componente assina uma requisição de login (HMAC SHA256) assim que o socket conecta.

 

var
  WSClient: TsgcWebSocketClient;
  Futures: TsgcWSAPI_MEXC_Futures;
begin
  WSClient := TsgcWebSocketClient.Create(nil);
  Futures := TsgcWSAPI_MEXC_Futures.Create(nil);
  Futures.Client := WSClient;
  Futures.MEXCAPI.ApiKey := 'YOUR_KEY';
  Futures.MEXCAPI.ApiSecret := 'YOUR_SECRET';
  if WSClient.Connect then
    Futures.SubscribeDepth('BTC_USDT', True);
end;

 

Properties

• Client: transporte WebSocket utilizado pelo componente da API. O suporte a Heartbeat é habilitado para manter o socket ativo.
• MEXCAPI.ApiKey / ApiSecret: necessários para assinar a requisição de login. Sem credenciais, apenas canais públicos são acessíveis.
• RawMessages: ignora o parser JSON quando habilitado, para que os quadros de texto bruto sejam expostos por meio dos eventos base.
• MEXCAPI.Resubscribe: se habilitado, após uma reconexão o cliente se inscreve automaticamente de novo nos canais que estavam ativos antes da desconexão (por padrão false).

 

Eventos

• OnConnect / OnDisconnect: notificações de ciclo de vida do WebSocket.
• OnMEXCLogin: gerado após um login autenticado bem-sucedido.
• OnMEXCSubscribed / OnMEXCUnsubscribed: confirmação de mudanças de subscrição. O evento expõe o nome do canal retornado pela MEXC.
• OnMEXCMessage: entrega cada atualização de mercado ou de conta junto com o identificador do canal.
• OnMEXCError: acionado quando o servidor responde com um payload rs.error (parâmetros inválidos, falha de autenticação, etc.).
• OnMEXCException: reporta exceções locais geradas ao processar dados JSON ou ao realizar operações de rede.

 

O seguinte manipulador registra confirmações de assinatura e imprime snapshots de profundidade recebidos:

 

procedure TMainForm.MEXCSubscribed(Sender: TObject; const aChannel, aRaw: string);
begin
  Memo1.Lines.Add('Subscribed to ' + aChannel);
end;
procedure TMainForm.MEXCMessage(Sender: TObject; const aChannel, aRaw: string);
begin
  if SameText(aChannel, 'push.depth') then
    Memo1.Lines.Add(aRaw);
end;

 

Métodos de assinatura WebSocket

Cada helper envolve uma requisição sub/unsub conforme descrito pela API oficial. Utilize o método UnSubscribe* correspondente para cancelar o stream.

 

Method	Parâmetros	Descrição
SubscribeDeal	Symbol	Negociações executadas no contrato (canal: deal).
SubscribeTickers	–	Estatísticas globais de ticker para todos os contratos.
SubscribeTicker	Symbol	Resumo do ticker para um único instrumento.
SubscribeDepth	Symbol, Compress	Atualizações incrementais do order book
SubscribeDepthFull	Symbol, Level	Snapshots de profundidade completa com número configurável de níveis (padrão 20).
SubscribeKline	Symbol, Interval	Dados de candlestick para os timeframes suportados (Min1, Min5, Min15, Min30, Min60, Hour4, Hour12, Day1, Week1, Month1).
SubscribeFundingRate	Symbol	Anúncios mais recentes da taxa de funding.
SubscribeIndexPrice	Symbol	Stream subjacente do preço de índice.
SubscribeFairPrice	Symbol	Atualizações de preço Mark (justo) enviadas pela exchange.

 

Quando o servidor confirma uma requisição, o evento OnMEXCSubscribed é disparado com o nome do canal (por exemplo rs.sub.depth.BTC_USDT). Erros são encaminhados através de OnMEXCError, incluindo a mensagem do servidor para solução de problemas.

Canais privados

Os canais privados exigem uma API key válida. O componente autentica automaticamente quando as credenciais são fornecidas.

Method	Descrição
SubscribePersonalOrder	Atualizações de ordens pessoais.
SubscribePersonalOrderDeal	Atualizações de execução (fill) de ordens pessoais.
SubscribePersonalPosition	Atualizações de posição pessoal.
SubscribePersonalPlanOrder	Atualizações de ordem do plano pessoal (trigger).
SubscribePersonalStopOrder	Atualizações de stop orders pessoais.
SubscribePersonalStopPlanOrder	Atualizações de ordens de plano de stop pessoal.
SubscribePersonalRiskLimit	Atualizações do limite de risco pessoal.
SubscribePersonalADLLevel	Atualizações de nível pessoal de ADL (auto-deleveraging).
SubscribePersonalAsset	Atualizações de ativos pessoais.

 

 

 

Endpoints REST públicos

Métodos REST disponíveis publicamente.

 

Method	Descrição
GetPing	Verifica a acessibilidade da API via /api/v1/ping.
GetServerTime	Retorna o timestamp do servidor de /api/v1/time.
GetContracts	Fornece a lista de contratos disponíveis (/api/v1/contract/detail).
GetDepth	Baixa a profundidade do order book de /api/v1/contract/depth; use o parâmetro opcional limit (padrão 50) para selecionar o número de níveis.
GetDeals	Recupera as negociações recentes usando /api/v1/contract/deals com um limit opcional (padrão 100).
GetKlines	Retorna dados de candlestick por meio de /api/v1/contract/kline com filtros opcionais startTime, endTime e limit (padrão 200).
GetIndexPrice	Obtém o preço de índice subjacente para o símbolo solicitado (/api/v1/contract/indexPrice).
GetFairPrice	Retorna o fair (mark) price de um contrato de /api/v1/contract/fairPrice.
GetFundingRate	Reporta a taxa de funding mais recente de um símbolo utilizando /api/v1/contract/fundingRate.
GetAllTickers	Obtém todos os tickers de contratos de futuros com resumos de preços em tempo real.
GetFundingRateHistory	Obtém registros históricos de funding rate de um contrato.
GetFairPriceKline	Obtém dados de kline/candlestick do preço fair (mark) para um contrato.
GetIndexPriceKline	Obtém dados de kline/candlestick do preço de índice para um contrato.

 

Endpoints REST privados

Os endpoints privados de derivativos exigem credenciais de API. O componente assina cada requisição com o timestamp e o recvWindow automaticamente.

 

Method	Descrição
GetAccountAssets	Retorna os saldos de margin de /api/v1/private/account/assets.
GetPositionList	Lista as posições atuais via /api/v1/private/position/list, opcionalmente filtradas por símbolo.
SetPositionLeverage	Atualiza a alavancagem de um símbolo e, se fornecido, o modo de margem.
PlaceOrder	Coloca uma ordem de futures em /api/v1/private/order fornecendo symbol, side, positionSide, type e quantity além de price opcional, clientOrderId e parâmetros extras.
CancelOrder	Cancela uma ordem específica utilizando /api/v1/private/order/cancel por orderId ou clientOrderId.
CancelAllOrders	Cancela todas as ordens abertas de um símbolo via /api/v1/private/order/cancel-all.
GetOpenOrders	Lista as ordens abertas atuais através de /api/v1/private/order/list/open com um filtro de símbolo opcional.
GetOrderHistory	Recupera o histórico de ordens (/api/v1/private/order/list/history) com parâmetros opcionais de símbolo, intervalo de tempo e limite.
GetFundingHistory	Retorna pagamentos de funding passados de /api/v1/private/account/funding com os filtros opcionais startTime, endTime e limit.
GetOpenPositions	Obtém todas as posições atualmente abertas.
ChangeMargin	Altera o valor da margem de uma posição.
GetPositionMode	Obter o modo de posição atual (one-way ou hedge mode).
ChangePositionMode	Altera o modo de posição entre one-way e hedge mode.
PlaceBatchOrder	Coloca várias ordens de futuros em uma única requisição em lote.
GetOrderDetail	Obter informações detalhadas de uma ordem específica.
GetOrderDealDetails	Obtém os detalhes de fill/deal de uma ordem específica.
PlaceTriggerOrder	Coloca uma ordem trigger (plan) que é executada quando as condições são atendidas.
CancelTriggerOrder	Cancelar uma ordem de trigger específica.
CancelAllTriggerOrders	Cancelar todas as ordens trigger abertas.
GetTriggerOrders	Obter a lista de ordens de gatilho (plano).
GetStopOrders	Obtém a lista de ordens stop.
CancelStopOrder	Cancela uma ordem stop específica.
CancelAllStopOrders	Cancela todas as ordens stop abertas.