BitMEX è uno dei principali exchange di derivati su criptovalute, specializzato nel trading con leva di futures e contratti perpetual. Il componente TsgcWSAPI_Bitmex fornisce agli sviluppatori Delphi l'accesso sia all'API WebSocket sia all'API REST, abilitando lo streaming dei dati di mercato in tempo reale, l'esecuzione di ordini, la gestione delle posizioni e operazioni complete sull'account da un unico componente.
Indice
- Panoramica
- Per iniziare
- API WebSocket
- API REST: dati di mercato
- API REST: trading
- API REST: posizioni
- Esempio di codice
- Configurazione e note
Panoramica
A differenza di molti componenti per exchange che supportano solo WebSocket, il componente TsgcWSAPI_Bitmex offre un approccio a doppia interfaccia. L'API WebSocket fornisce streaming in tempo reale di trade, aggiornamenti del libro degli ordini, quote e dati dell'account tramite sottoscrizioni basate su topic. L'API REST (accessibile tramite la proprietà REST_API) fornisce metodi request-response sincroni per piazzare ordini, gestire posizioni e interrogare i dati di mercato. Questa combinazione è ideale per costruire applicazioni di trading complete che hanno bisogno sia di feed di dati live sia di un'esecuzione precisa degli ordini.
Per iniziare
Crea un componente TsgcWebSocketClient e un TsgcWSAPI_Bitmex, collegali e configura le tue credenziali. La connessione WebSocket viene attivata tramite il client, mentre l'API REST è accessibile tramite la proprietà REST_API.
oClient := TsgcWebSocketClient.Create(nil);
oBitmex := TsgcWSAPI_Bitmex.Create(nil);
oBitmex.Client := oClient;
oBitmex.Bitmex.ApiKey := 'your_api_key';
oBitmex.Bitmex.ApiSecret := 'your_api_secret';
oClient.Active := True;API WebSocket
L'API WebSocket di BitMEX usa un modello di sottoscrizione basato su topic. Ti sottoscrivi a un topic (opzionalmente filtrato per strumento) e ricevi uno stream continuo di aggiornamenti. Il componente fornisce tre metodi WebSocket principali.
| Metodo | Descrizione |
|---|---|
Subscribe |
Sottoscrive a uno stream topic, opzionalmente filtrato per simbolo dello strumento. |
Unsubscribe |
Annulla la sottoscrizione da uno stream topic precedentemente sottoscritto. |
Authenticate |
Autentica la sessione WebSocket per l'accesso ai topic privati. |
Topic disponibili
I topic definiscono il tipo di dati che ricevi. Puoi sottoscriverti a più topic simultaneamente. Il formato di sottoscrizione è topic:symbol dove il filtro symbol è opzionale.
| Topic | Autenticazione richiesta | Descrizione |
|---|---|---|
trade |
No | Esecuzioni di trade live sull'exchange. |
instrument |
No | Dati degli strumenti inclusi funding rate e info di settlement. |
orderBookL2 |
No | Libro degli ordini Level 2 completo con aggiornamenti incrementali. |
quote |
No | Quote bid e ask migliori al top del book. |
execution |
Sì | Esecuzioni e fill di trade del tuo account. |
margin |
Sì | Saldo del margine dell'account e aggiornamenti del saldo disponibile. |
order |
Sì | I tuoi ordini aperti e gli aggiornamenti di stato degli ordini. |
position |
Sì | Le tue posizioni aperte e gli aggiornamenti di P&L non realizzato. |
Esempi di sottoscrizione WebSocket
// Sottoscrive ai trade XBTUSD
oBitmex.Subscribe('trade:XBTUSD');
// Sottoscrive al libro degli ordini Level 2
oBitmex.Subscribe('orderBookL2:XBTUSD');
// Sottoscrive alle migliori quote bid/ask
oBitmex.Subscribe('quote:XBTUSD');
// Autentica per i topic privati
oBitmex.Authenticate;
// Sottoscrive agli aggiornamenti dei tuoi ordini (richiede autenticazione)
oBitmex.Subscribe('order');
// Sottoscrive agli aggiornamenti delle tue posizioni (richiede autenticazione)
oBitmex.Subscribe('position');
// Annulla la sottoscrizione dai trade
oBitmex.Unsubscribe('trade:XBTUSD');API REST: dati di mercato
L'API REST è accessibile tramite la proprietà REST_API del componente. I metodi dei dati di mercato restituiscono stringhe JSON che puoi parsare nella tua applicazione. Sono chiamate sincrone che ritornano immediatamente con i dati richiesti.
| Metodo | Descrizione |
|---|---|
GetInstruments |
Recupera un elenco di tutti gli strumenti disponibili sull'exchange. |
GetInstrumentsActive |
Recupera solo gli strumenti attivamente scambiati. |
GetOrderBook |
Recupera lo snapshot corrente del libro degli ordini per uno strumento. |
GetQuotes |
Recupera i dati recenti delle quote (bid/ask). |
GetTrades |
Recupera i dati pubblici recenti dei trade. |
GetExecutions |
Recupera i dati grezzi di esecuzione del tuo account. |
GetExecutionsTradeHistory |
Recupera la cronologia delle esecuzioni di trade del tuo account. |
// Ottiene il libro degli ordini per XBTUSD
ShowMessage(oBitmex.REST_API.GetOrderBook('XBTUSD'));
// Ottiene tutti gli strumenti attivi
ShowMessage(oBitmex.REST_API.GetInstrumentsActive);
// Ottiene i trade recenti
ShowMessage(oBitmex.REST_API.GetTrades('XBTUSD'));
// Ottiene le quote recenti
ShowMessage(oBitmex.REST_API.GetQuotes('XBTUSD'));API REST: trading
I metodi di trading ti permettono di piazzare, modificare e annullare ordini. L'API REST supporta diversi tipi di ordine inclusi market, limit, stop e stop-limit. Tutti i metodi di trading richiedono autenticazione.
| Metodo | Descrizione |
|---|---|
PlaceOrder |
Piazza un nuovo ordine con pieno controllo dei parametri. |
PlaceMarketOrder |
Piazza un ordine market che viene eseguito immediatamente al miglior prezzo. |
PlaceLimitOrder |
Piazza un ordine limit a un prezzo specificato. |
PlaceStopOrder |
Piazza un ordine stop (market) attivato a un prezzo stop. |
PlaceStopLimitOrder |
Piazza un ordine stop-limit con prezzi sia di trigger sia di limit. |
AmendOrder |
Modifica prezzo, quantità o altri parametri di un ordine esistente. |
CancelOrder |
Annulla un ordine specifico tramite il suo identificatore. |
CancelAllOrders |
Annulla tutti gli ordini aperti in una volta. |
CancelAllOrdersAfter |
Imposta un dead man's switch che annulla tutti gli ordini dopo un timeout. |
GetOrders |
Recupera tutti gli ordini, opzionalmente filtrati per stato. |
Esempi di piazzamento ordini
// Piazza un ordine limit: compra 100 contratti di XBTUSD a $30.000
ShowMessage(oBitmex.REST_API.PlaceLimitOrder(bmsBuy, 'XBTUSD', 100, 30000));
// Piazza un ordine market: vendi 50 contratti di XBTUSD
ShowMessage(oBitmex.REST_API.PlaceMarketOrder(bmsSell, 'XBTUSD', 50));
// Piazza un ordine stop: si attiva quando il prezzo raggiunge $28.000
ShowMessage(oBitmex.REST_API.PlaceStopOrder(bmsSell, 'XBTUSD', 100, 28000));
// Piazza un ordine stop-limit: si attiva a $28.000, prezzo limit $27.500
ShowMessage(oBitmex.REST_API.PlaceStopLimitOrder(bmsSell, 'XBTUSD', 100, 28000, 27500));
// Annulla un ordine specifico
ShowMessage(oBitmex.REST_API.CancelOrder('order-id-here'));
// Annulla tutti gli ordini aperti
ShowMessage(oBitmex.REST_API.CancelAllOrders);CancelAllOrdersAfter agisce come un dead man's switch. Annulla tutti gli ordini se non viene rinnovato entro il timeout specificato. È utile come meccanismo di sicurezza per evitare ordini incontrollati se la tua applicazione perde la connettività.
API REST: posizioni
I metodi di gestione delle posizioni ti permettono di interrogare, chiudere e configurare le tue posizioni aperte, incluse le impostazioni di leva e margine.
| Metodo | Descrizione |
|---|---|
GetPosition |
Recupera la posizione corrente per uno strumento. |
ClosePosition |
Chiude una posizione aperta piazzando un ordine market di chiusura. |
SetPositionIsolate |
Commuta tra modalità cross e isolated margin per una posizione. |
SetPositionLeverage |
Imposta il moltiplicatore di leva per una posizione. |
SetPositionRiskLimit |
Imposta il limite di rischio per una posizione. |
SetPositionTransferMargin |
Trasferisce margine verso o da una posizione isolated. |
Esempi di gestione delle posizioni
// Ottiene la posizione corrente per XBTUSD
ShowMessage(oBitmex.REST_API.GetPosition('XBTUSD'));
// Imposta la leva a 10x
ShowMessage(oBitmex.REST_API.SetPositionLeverage('XBTUSD', 10));
// Passa alla modalità isolated margin
ShowMessage(oBitmex.REST_API.SetPositionIsolate('XBTUSD', True));
// Chiude la posizione al prezzo di mercato
ShowMessage(oBitmex.REST_API.ClosePosition('XBTUSD'));Esempio di codice
L'esempio seguente dimostra un workflow completo che combina sottoscrizioni WebSocket e chiamate API REST: connessione, sottoscrizione ai trade live, interrogazione del libro degli ordini e piazzamento di un ordine limit.
oClient := TsgcWebSocketClient.Create(nil);
oBitmex := TsgcWSAPI_Bitmex.Create(nil);
oBitmex.Client := oClient;
oBitmex.Bitmex.ApiKey := 'your_api_key';
oBitmex.Bitmex.ApiSecret := 'your_api_secret';
oClient.Active := True;
// Sottoscrive ai trade
oBitmex.Subscribe('trade:XBTUSD');
// REST: ottiene il libro degli ordini
ShowMessage(oBitmex.REST_API.GetOrderBook('XBTUSD'));
// REST: piazza un ordine limit
ShowMessage(oBitmex.REST_API.PlaceLimitOrder(bmsBuy, 'XBTUSD', 100, 30000));Configurazione e note
Credenziali API
Genera la tua api key e il secret dalle impostazioni del tuo account BitMEX. Puoi creare chiavi con permessi specifici (order, withdraw, ecc.). Per i bot di trading, crea una chiave solo con i permessi di cui hai bisogno ed evita di abilitare i permessi di prelievo se non strettamente necessario.
Supporto testnet
BitMEX fornisce un ambiente testnet su testnet.bitmex.com per sviluppo e test. Configura il componente per usare l'endpoint testnet per testare la tua integrazione con fondi simulati prima di andare in produzione. Il gruppo di proprietà Bitmex include impostazioni per selezionare tra ambiente di produzione e testnet.
Enumerazione del lato ordine
I metodi di trading usano i valori di enumerazione bmsBuy e bmsSell per specificare la direzione dell'ordine. Sono specifici del componente BitMEX.
Utilizzo WebSocket vs REST
Usa le sottoscrizioni WebSocket per lo streaming di dati in tempo reale dove la bassa latenza è critica (visualizzazioni di prezzi live, visualizzazione del libro degli ordini, monitoraggio delle esecuzioni). Usa l'API REST per operazioni on-demand come piazzare ordini, interrogare posizioni e recuperare dati storici. Le due interfacce si completano a vicenda e possono essere usate simultaneamente.
Rate limit
BitMEX impone rate limit sulle chiamate dell'API REST. I limiti variano per endpoint ma sono tipicamente 60 richieste al minuto per la maggior parte degli endpoint di trading e 30 richieste al minuto per la modifica e l'annullamento di ordini. Monitora gli header di rate limit nelle risposte per evitare di essere bloccato temporaneamente. Le sottoscrizioni WebSocket non sono soggette ai rate limit REST.
Simboli degli strumenti
BitMEX usa un proprio formato di simboli degli strumenti. Il contratto Bitcoin perpetual è XBTUSD, mentre i contratti futures includono un suffisso di data di scadenza (es. XBTM25). Usa GetInstrumentsActive per scoprire tutti gli strumenti attualmente negoziabili e i loro simboli.
CancelAllOrdersAfter con un timer periodico nella tua applicazione come rete di sicurezza. Se la tua applicazione va in crash o perde la connettività, tutti gli ordini verranno annullati automaticamente dopo il timeout specificato, proteggendoti da movimenti di mercato imprevisti.