API MEXC Futures

I contratti perpetui e a consegna di MEXC espongono una API di streaming dedicata, documentata nella specifica ufficiale Futures WebSocket. Il componente TsgcWSAPI_MEXC_Futures incapsula la connessione, l'handshake di login e la gestione dei topic necessari per consumare dati sui derivati in tempo reale.

MEXC mantiene anche un'interfaccia REST per il trading di derivati. Il componente TsgcHTTP_API_MEXC_Futures contenuto in sgcHTTP_API_MEXC integra i feed WebSocket con helper HTTP che corrispondono uno a uno agli endpoint ufficiali.

Configurazione del componente

L'endpoint WebSocket Futures è wss://contract.mexc.com/edge. I messaggi sono codificati come oggetti JSON e la piattaforma richiede frame ping/pong periodici che vengono gestiti automaticamente dal componente.

Per ricevere notifiche private (dati di ordini e account) è necessario autenticarsi. Impostare MEXCAPI.ApiKey e MEXCAPI.ApiSecret prima di attivare il client WebSocket. Quando le credenziali sono presenti, il componente firma una richiesta di accesso (HMAC SHA256) non appena il socket si connette.

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;

Proprietà

Client: trasporto WebSocket utilizzato dal componente API. Il supporto heartbeat è abilitato per mantenere attivo il socket.
MEXCAPI.ApiKey / ApiSecret: necessari per firmare la richiesta di login. Senza credenziali sono accessibili solo i canali pubblici.
RawMessages: quando abilitato, bypassa il parser JSON in modo che i frame di testo non elaborati siano esposti tramite gli eventi base.
MEXCAPI.Resubscribe: se abilitato, dopo una riconnessione il client si iscrive di nuovo automaticamente ai canali che erano attivi prima della disconnessione (per impostazione predefinita false).

Eventi

OnConnect / OnDisconnect: Notifiche del ciclo di vita WebSocket.
OnMEXCLogin: generato dopo un accesso autenticato con successo.
OnMEXCSubscribed / OnMEXCUnsubscribed: conferma delle modifiche alla sottoscrizione. L'evento espone il nome del canale restituito da MEXC.
OnMEXCMessage: recapita ogni aggiornamento di mercato o di account insieme all'identificatore del canale.
OnMEXCError: viene generato quando il server risponde con un payload rs.error (parametri non validi, errore di autenticazione, ecc.).
OnMEXCException: segnala le eccezioni locali generate durante l'elaborazione dei dati JSON o l'esecuzione di operazioni di rete.

Il seguente gestore registra le conferme di iscrizione e stampa gli snapshot di profondità in arrivo:

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;

Metodi di sottoscrizione WebSocket

Ogni helper racchiude una richiesta sub/unsub come descritto dall'API ufficiale. Usare il metodo UnSubscribe* corrispondente per annullare lo stream.

Metodo	Parametri	Descrizione
SubscribeDeal	Symbol	Operazioni eseguite sul contratto (canale: deal).
SubscribeTickers	–	Statistiche globali del ticker per tutti i contratti.
SubscribeTicker	Symbol	Riepilogo ticker per un singolo strumento.
SubscribeDepth	Symbol, Compress	Aggiornamenti incrementali del libro degli ordini
SubscribeDepthFull	Symbol, Level	Snapshot di profondità completa con numero di livelli configurabile (predefinito 20).
SubscribeKline	Symbol, Interval	Dati candlestick per i timeframe supportati (Min1, Min5, Min15, Min30, Min60, Hour4, Hour12, Day1, Week1, Month1).
SubscribeFundingRate	Symbol	Ultimi annunci sul tasso di finanziamento.
SubscribeIndexPrice	Symbol	Flusso del prezzo dell'indice sottostante.
SubscribeFairPrice	Symbol	Aggiornamenti del prezzo Mark (equo) inviati dall'exchange.

Quando il server riconosce una richiesta, viene attivato l'evento OnMEXCSubscribed con il nome del canale (ad esempio rs.sub.depth.BTC_USDT). Gli errori vengono inoltrati tramite OnMEXCError, incluso il messaggio del server per la risoluzione dei problemi.

Canali privati

I canali privati richiedono una chiave API valida. Il componente esegue automaticamente l'autenticazione quando vengono fornite le credenziali.

Metodo	Descrizione
SubscribePersonalOrder	Aggiornamenti personali sugli ordini.
SubscribePersonalOrderDeal	Aggiornamenti delle operazioni (fill) degli ordini personali.
SubscribePersonalPosition	Aggiornamenti della posizione personale.
SubscribePersonalPlanOrder	Aggiornamenti degli ordini del piano personale (trigger).
SubscribePersonalStopOrder	Aggiornamenti degli ordini stop personali.
SubscribePersonalStopPlanOrder	Aggiornamenti degli ordini stop personali.
SubscribePersonalRiskLimit	Aggiornamenti del limite di rischio personale.
SubscribePersonalADLLevel	Aggiornamenti del livello ADL (auto-deleveraging) personale.
SubscribePersonalAsset	Aggiornamenti degli asset personali.

Endpoint REST pubblici

Metodi REST disponibili pubblicamente.

Metodo	Descrizione
GetPing	Verifica la raggiungibilità dell'API tramite /api/v1/ping.
GetServerTime	Restituisce il timestamp del server da /api/v1/time.
GetContracts	Fornisce l'elenco dei contratti disponibili (/api/v1/contract/detail).
GetDepth	Scarica la profondità del book degli ordini da /api/v1/contract/depth; utilizzare il parametro opzionale limit (predefinito 50) per selezionare il numero di livelli.
GetDeals	Recupera le transazioni recenti tramite /api/v1/contract/deals con un limite facoltativo (predefinito 100).
GetKlines	Restituisce dati candlestick tramite /api/v1/contract/kline con filtri facoltativi startTime, endTime e limit (default 200).
GetIndexPrice	Recupera il prezzo dell'indice sottostante per il simbolo richiesto (/api/v1/contract/index_price).
GetFairPrice	Restituisce il prezzo equo (mark) per un contratto da /api/v1/contract/fair_price.
GetFundingRate	Riporta l'ultimo tasso di finanziamento per un simbolo utilizzando /api/v1/contract/funding_rate.
GetAllTickers	Ottieni tutti i ticker dei contratti futures con riepiloghi dei prezzi in tempo reale.
GetFundingRateHistory	Recupera i record storici del tasso di finanziamento per un contratto.
GetFairPriceKline	Recupera i dati kline/candlestick del prezzo equo (mark price) per un contratto.
GetIndexPriceKline	Recupera i dati kline/candlestick del prezzo indice per un contratto.

Endpoint REST privati

Gli endpoint derivati privati richiedono credenziali API. Il componente firma automaticamente ogni richiesta con il timestamp e il recvWindow.

Modifica non retrocompatibile: le firme di PlaceOrder e SetPositionLeverage sono cambiate per allinearsi agli endpoint contract pubblicati da MEXC, quindi un'applicazione che le richiama non verrà compilata finché non sarà aggiornata. PlaceOrder ha sostituito il proprio parametro positionSide con openType, e SetPositionLeverage ha sostituito marginMode, che l'endpoint non accetta, con positionId, openType e positionType. Sono stati corretti anche diversi percorsi degli endpoint.

Metodo	Descrizione
GetAccountAssets	Restituisce i saldi del margine da /api/v1/private/account/assets.
GetPositionList	Elenca le posizioni correnti tramite /api/v1/private/position/list/history_positions.
SetPositionLeverage	Aggiorna la leva di una posizione tramite /api/v1/private/position/change_leverage. Accetta il symbol e la leverage, più un positionId facoltativo, e openType (1 isolato, 2 cross) e positionType (1 long, 2 short) che sono necessari solo quando la posizione non è ancora aperta.
PlaceOrder	Inserisce un ordine futures su /api/v1/private/order/submit fornendo symbol, side, type, openType (1 isolato, 2 cross), la quantità, che viaggia come vol, e il price, che l'endpoint richiede anche per gli ordini a mercato, più un externalOid facoltativo e parametri aggiuntivi.
CancelOrder	Annulla un ordine specifico utilizzando /api/v1/private/order/cancel tramite orderId o clientOrderId.
CancelAllOrders	Annulla tutti gli ordini aperti per un symbol tramite /api/v1/private/order/cancel_all.
GetOpenOrders	Elenca gli ordini aperti correnti tramite /api/v1/private/order/list/open_orders con un filtro symbol opzionale.
GetOrderHistory	Recupera la cronologia degli ordini (/api/v1/private/order/list/history) con parametri facoltativi di symbol, intervallo temporale e limit.
GetFundingHistory	Restituisce i pagamenti di funding passati da /api/v1/private/account/funding con filtri opzionali startTime, endTime e limit.
GetOpenPositions	Ottieni tutte le posizioni attualmente aperte.
ChangeMargin	Modifica l'importo del margine per una posizione.
GetPositionMode	Ottenere la modalità di posizione corrente (modalità unidirezionale o hedge).
ChangePositionMode	Cambia la modalità di posizione tra modalità unidirezionale e modalità hedge.
PlaceBatchOrder	Invia più ordini futures in un'unica richiesta batch.
GetOrderDetail	Ottiene informazioni dettagliate per un ordine specifico.
GetOrderDealDetails	Ottieni i dettagli di esecuzione/operazione per un ordine specifico.
PlaceTriggerOrder	Inserire un ordine trigger (piano) che viene eseguito quando le condizioni sono soddisfatte.
CancelTriggerOrder	Annulla uno specifico ordine trigger.
CancelAllTriggerOrders	Annulla tutti gli ordini trigger aperti.
GetTriggerOrders	Ottieni l'elenco degli ordini trigger (plan).
GetStopOrders	Ottieni l'elenco degli ordini stop.
CancelStopOrder	Annullare uno specifico ordine stop.
CancelAllStopOrders	Annulla tutti gli ordini stop aperti.