BitMEX es uno de los principales exchanges de derivados de criptomonedas, especializado en trading apalancado de futuros y contratos perpetuos. El componente TsgcWSAPI_Bitmex proporciona a los desarrolladores Delphi acceso tanto a la API WebSocket como REST, habilitando streaming de datos de mercado en tiempo real, ejecución de órdenes, gestión de posiciones y operaciones de cuenta completas desde un único componente.
Ãndice de contenidos
- Visión general
- Primeros pasos
- API WebSocket
- REST API: datos de mercado
- REST API: trading
- REST API: posiciones
- Ejemplo de código
- Configuración y notas
Visión general
A diferencia de muchos componentes de exchange que solo soportan WebSocket, el componente TsgcWSAPI_Bitmex ofrece un enfoque de doble interfaz. La API WebSocket proporciona streaming en tiempo real de trades, actualizaciones del order book, quotes y datos de cuenta mediante suscripciones basadas en topics. La REST API (accesible mediante la propiedad REST_API) proporciona métodos sÃncronos de petición/respuesta para colocar órdenes, gestionar posiciones y consultar datos de mercado. Esta combinación es ideal para construir aplicaciones de trading completas que necesiten tanto data feeds en vivo como ejecución precisa de órdenes.
Primeros pasos
Crea un componente TsgcWebSocketClient y un TsgcWSAPI_Bitmex, enlázalos y configura tus credenciales. La conexión WebSocket se activa a través del cliente, mientras que la REST API se accede mediante la propiedad 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
La API WebSocket de BitMEX usa un modelo de suscripción basado en topics. Te suscribes a un topic (opcionalmente filtrado por instrumento) y recibes un stream continuo de actualizaciones. El componente proporciona tres métodos WebSocket principales.
| Método | Descripción |
|---|---|
Subscribe |
Se suscribe a un stream de topic, opcionalmente filtrado por sÃmbolo de instrumento. |
Unsubscribe |
Se desuscribe de un stream de topic al que estabas suscrito. |
Authenticate |
Autentica la sesión WebSocket para acceder a topics privados. |
Topics disponibles
Los topics definen el tipo de datos que recibes. Puedes suscribirte a varios topics simultáneamente. El formato de suscripción es topic:symbol, donde el filtro de sÃmbolo es opcional.
| Topic | Auth requerida | Descripción |
|---|---|---|
trade |
No | Ejecuciones de trades en vivo en el exchange. |
instrument |
No | Datos del instrumento, incluyendo funding rates e info de settlement. |
orderBookL2 |
No | Order book Level 2 completo con actualizaciones incrementales. |
quote |
No | Mejores quotes de bid y ask en la cabecera del libro. |
execution |
Yes | Ejecuciones y fills de trades de tu cuenta. |
margin |
Yes | Actualizaciones del margin y del saldo disponible de la cuenta. |
order |
Yes | Tus órdenes abiertas y actualizaciones del estado de las órdenes. |
position |
Yes | Tus posiciones abiertas y actualizaciones de P&L no realizado. |
Ejemplos de suscripción WebSocket
// Subscribe to XBTUSD trades
oBitmex.Subscribe('trade:XBTUSD');
// Subscribe to the Level 2 order book
oBitmex.Subscribe('orderBookL2:XBTUSD');
// Subscribe to best bid/ask quotes
oBitmex.Subscribe('quote:XBTUSD');
// Authenticate for private topics
oBitmex.Authenticate;
// Subscribe to your order updates (requires auth)
oBitmex.Subscribe('order');
// Subscribe to your position updates (requires auth)
oBitmex.Subscribe('position');
// Unsubscribe from trades
oBitmex.Unsubscribe('trade:XBTUSD');REST API: datos de mercado
La REST API se accede a través de la propiedad REST_API del componente. Los métodos de datos de mercado devuelven cadenas JSON que puedes parsear en tu aplicación. Son llamadas sÃncronas que devuelven inmediatamente los datos solicitados.
| Método | Descripción |
|---|---|
GetInstruments |
Recupera una lista de todos los instrumentos disponibles en el exchange. |
GetInstrumentsActive |
Recupera solo instrumentos con trading activo. |
GetOrderBook |
Recupera el snapshot actual del order book de un instrumento. |
GetQuotes |
Recupera datos recientes de quote (bid/ask). |
GetTrades |
Recupera datos de trades públicos recientes. |
GetExecutions |
Recupera los datos de ejecución en bruto de tu cuenta. |
GetExecutionsTradeHistory |
Recupera el historial de ejecuciones de trade de tu cuenta. |
// Get the order book for XBTUSD
ShowMessage(oBitmex.REST_API.GetOrderBook('XBTUSD'));
// Get all active instruments
ShowMessage(oBitmex.REST_API.GetInstrumentsActive);
// Get recent trades
ShowMessage(oBitmex.REST_API.GetTrades('XBTUSD'));
// Get recent quotes
ShowMessage(oBitmex.REST_API.GetQuotes('XBTUSD'));REST API: trading
Los métodos de trading permiten colocar, modificar y cancelar órdenes. La REST API soporta varios tipos de orden, incluidos market, limit, stop y stop-limit. Todos los métodos de trading requieren autenticación.
| Método | Descripción |
|---|---|
PlaceOrder |
Coloca una nueva orden con control total de los parámetros. |
PlaceMarketOrder |
Coloca una orden market que se ejecuta de inmediato al mejor precio. |
PlaceLimitOrder |
Coloca una orden limit al precio especificado. |
PlaceStopOrder |
Coloca una orden stop (market) que se dispara a un precio stop. |
PlaceStopLimitOrder |
Coloca una orden stop-limit con precio de disparo y precio lÃmite. |
AmendOrder |
Modifica el precio, cantidad u otros parámetros de una orden existente. |
CancelOrder |
Cancela una orden concreta por su identificador. |
CancelAllOrders |
Cancela todas las órdenes abiertas a la vez. |
CancelAllOrdersAfter |
Establece un dead man's switch que cancela todas las órdenes tras un timeout. |
GetOrders |
Recupera todas las órdenes, opcionalmente filtradas por estado. |
Ejemplos de colocación de órdenes
// Place a limit order: Buy 100 contracts of XBTUSD at $30,000
ShowMessage(oBitmex.REST_API.PlaceLimitOrder(bmsBuy, 'XBTUSD', 100, 30000));
// Place a market order: Sell 50 contracts of XBTUSD
ShowMessage(oBitmex.REST_API.PlaceMarketOrder(bmsSell, 'XBTUSD', 50));
// Place a stop order: triggers when price reaches $28,000
ShowMessage(oBitmex.REST_API.PlaceStopOrder(bmsSell, 'XBTUSD', 100, 28000));
// Place a stop-limit order: triggers at $28,000, limit price $27,500
ShowMessage(oBitmex.REST_API.PlaceStopLimitOrder(bmsSell, 'XBTUSD', 100, 28000, 27500));
// Cancel a specific order
ShowMessage(oBitmex.REST_API.CancelOrder('order-id-here'));
// Cancel all open orders
ShowMessage(oBitmex.REST_API.CancelAllOrders);CancelAllOrdersAfter funciona como un dead man's switch. Cancela todas las órdenes si no se renueva dentro del timeout especificado. Es útil como mecanismo de seguridad para evitar órdenes descontroladas si tu aplicación pierde conectividad.
REST API: posiciones
Los métodos de gestión de posiciones permiten consultar, cerrar y configurar tus posiciones abiertas, incluyendo apalancamiento y ajustes de margen.
| Método | Descripción |
|---|---|
GetPosition |
Recupera la posición actual de un instrumento. |
ClosePosition |
Cierra una posición abierta colocando una orden market de cierre. |
SetPositionIsolate |
Alterna entre modo de margin cross e isolated para una posición. |
SetPositionLeverage |
Establece el multiplicador de apalancamiento de una posición. |
SetPositionRiskLimit |
Establece el risk limit de una posición. |
SetPositionTransferMargin |
Transfiere margin desde o hacia una posición isolated. |
Ejemplos de gestión de posiciones
// Get current position for XBTUSD
ShowMessage(oBitmex.REST_API.GetPosition('XBTUSD'));
// Set leverage to 10x
ShowMessage(oBitmex.REST_API.SetPositionLeverage('XBTUSD', 10));
// Switch to isolated margin mode
ShowMessage(oBitmex.REST_API.SetPositionIsolate('XBTUSD', True));
// Close the position at market price
ShowMessage(oBitmex.REST_API.ClosePosition('XBTUSD'));Ejemplo de código
El siguiente ejemplo muestra un workflow completo combinando suscripciones WebSocket y llamadas REST API: conectar, suscribirse a trades en vivo, consultar el order book y colocar una orden 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;
// Subscribe to trades
oBitmex.Subscribe('trade:XBTUSD');
// REST: Get order book
ShowMessage(oBitmex.REST_API.GetOrderBook('XBTUSD'));
// REST: Place a limit order
ShowMessage(oBitmex.REST_API.PlaceLimitOrder(bmsBuy, 'XBTUSD', 100, 30000));Configuración y notas
Credenciales API
Genera tu API key y secret desde la configuración de cuenta de BitMEX. Puedes crear keys con permisos especÃficos (order, withdraw, etc.). Para bots de trading, crea una key solo con los permisos que necesites y evita habilitar permisos de retirada salvo que sea estrictamente necesario.
Soporte de testnet
BitMEX proporciona un entorno testnet en testnet.bitmex.com para desarrollo y pruebas. Configura el componente para usar el endpoint de testnet y probar tu integración con fondos simulados antes de pasar a producción. El grupo de propiedades Bitmex incluye ajustes para seleccionar entre entornos de producción y testnet.
Enumeración del lado de la orden
Los métodos de trading usan los valores de enumeración bmsBuy y bmsSell para especificar la dirección de la orden. Son especÃficos del componente BitMEX.
Uso de WebSocket vs REST
Usa suscripciones WebSocket para streaming de datos en tiempo real donde la baja latencia es crÃtica (visualización de precios en vivo, visualización del order book, monitorización de ejecuciones). Usa la REST API para operaciones bajo demanda como colocar órdenes, consultar posiciones y obtener datos históricos. Las dos interfaces se complementan y pueden usarse simultáneamente.
Rate limits
BitMEX aplica rate limits a las llamadas a la REST API. Los lÃmites varÃan según el endpoint pero suelen ser 60 solicitudes por minuto para la mayorÃa de endpoints de trading y 30 por minuto para modificación y cancelación de órdenes. Monitoriza las cabeceras de rate limit en las respuestas para evitar ser bloqueado temporalmente. Las suscripciones WebSocket no están sujetas a los rate limits REST.
SÃmbolos de instrumento
BitMEX usa su propio formato de sÃmbolo de instrumento. El contrato perpetual de Bitcoin es XBTUSD, mientras que los contratos de futuros incluyen un sufijo de fecha de expiración (p. ej. XBTM25). Usa GetInstrumentsActive para descubrir todos los instrumentos negociables actualmente y sus sÃmbolos.
CancelAllOrdersAfter con un timer periódico en tu aplicación como red de seguridad. Si tu aplicación se cae o pierde conectividad, todas las órdenes se cancelarán automáticamente tras el timeout especificado, protegiéndote de movimientos inesperados del mercado.