Referencia de API¶

Conceptos comunes ¶

Volumen, precios, tipos de órdenes y vigencia

Volumen¶

El volumen se especifica en centavos (unidades de 0.0000001 lotes).

Lotes	Volumen (centavos)
0.01	`100,000`
0.1	`1,000,000`
1.0	`10,000,000`

Precios¶

Los valores de precio están en pipettes. Para convertir: precio_mostrado = valor_pipette / 10^dígitos_pip

Para EURUSD (5 dígitos), un valor de pipette de 112345 = 1.12345.

Tipos de órdenes¶

Tipo	Descripción	Campos obligatorios
`MARKET`	Ejecutar inmediatamente al precio actual	`symbolId`, `tradeSide`, `volume`
`LIMIT`	Ejecutar al precio límite o mejor	+ `limitPrice`
`STOP`	Activar cuando el mercado alcance el precio de detención	+ `stopPrice`
`MARKET_RANGE`	Ejecutar dentro de un rango de precios	+ `baseSlippagePrice`
`STOP_LIMIT`	Orden límite activada al precio de detención	+ `stopPrice`, `limitPrice`

Vigencia¶

Política	Descripción
`GOOD_TILL_CANCEL`	La orden permanece activa hasta que se ejecute o se cancele
`GOOD_TILL_DATE`	La orden vence en el `expirationTimestamp` especificado
`IMMEDIATE_OR_CANCEL`	Ejecutar lo que esté disponible inmediatamente, cancelar el resto

Información de cuenta ¶

GET /v1/balance Get account balance

Devuelve el saldo de la cuenta, el capital y el margen libre.

Parámetros

Sin parámetros.

Respuestas

200 Respuesta exitosa

Response body

{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}

Campo	Tipo	Descripción
`balance`	double	Saldo de cuenta en moneda de depósito
`equity`	double	Saldo + P&L flotante
`freeMargin`	double	Margen disponible para nuevas operaciones
`balanceVersion`	int64	Contador de versión de saldo
`moneyDigits`	int32	Decimales para valores monetarios
`depositAssetId`	int64	ID del activo de moneda de depósito

GET /v1/symbols Obtener símbolos disponibles

Devuelve todos los símbolos disponibles para operar en la cuenta.

Parámetros

Sin parámetros.

Respuestas

200 Array de objetos Symbol

Response body

[
  {
    "symbolId": 1,
    "symbolName": "EURUSD",
    "enabled": true,
    "baseAssetId": 2,
    "quoteAssetId": 1,
    "description": "Euro vs US Dollar"
  }
]

Symbol

Campo	Tipo	Descripción
`symbolId`	int64	ID del símbolo (utilizado en otras llamadas de API)
`symbolName`	string	Nombre del símbolo (p. ej., "EURUSD")
`enabled`	boolean	Si el símbolo es operable
`baseAssetId`	int64	ID del activo base
`quoteAssetId`	int64	ID del activo de cotización
`description`	string	Descripción legible

GET /v1/assets Obtener activos disponibles

Devuelve los activos disponibles (monedas).

Parámetros

Sin parámetros.

Respuestas

200 Array de objetos Asset

Response body

[
  {
    "assetId": 1,
    "name": "USD",
    "displayName": "US Dollar"
  }
]

Asset

Campo	Tipo	Descripción
`assetId`	int64	ID del activo
`name`	string	Código del activo (p. ej., "USD")
`displayName`	string	Nombre para mostrar

Datos de mercado ¶

GET /v1/prices Obtener precios al contado

Devuelve los precios de oferta/demanda actuales para los símbolos especificados. Esta es una instantánea: la API no admite transmisión.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`symbolId`	query	int64[]		ID de símbolos separados por comas

Respuestas

200 Array de objetos SpotPrice

Response body

[
  {
    "symbolId": 1,
    "bid": 112340,
    "ask": 112355,
    "high": 112890,
    "low": 111950,
    "sessionClose": 112100,
    "timestamp": 1700000000000
  }
]

SpotPrice

Campo	Tipo	Descripción
`symbolId`	int64	ID del símbolo
`bid`	int64	Mejor precio de oferta (pipettes)
`ask`	int64	Mejor precio de demanda (pipettes)
`high`	int64	Máximo de la sesión (pipettes)
`low`	int64	Mínimo de la sesión (pipettes)
`sessionClose`	int64	Cierre de la sesión anterior (pipettes)
`timestamp`	int64	Marca de tiempo de la cotización (epoch ms)

GET /v1/trendbars Obtener datos históricos OHLCV

Devuelve datos históricos de velas (OHLCV) para un símbolo.

Parámetros

Nombre	Ubicado en	Tipo	Configuración predeterminada	Descripción
`symbolId`	query	int64	–	ID del símbolo
`period`	query	string	–	Período de barra
`fromTimestamp`	query	string	–	Hora de inicio (ISO-8601)
`toTimestamp`	query	string	–	Hora de finalización (ISO-8601)
`count`	query	int32	`100`	Máximo de barras a devolver

Períodos disponibles

M_1 M_2 M_3 M_4 M_5 M_10 M_15 M_30 H_1 H_2 H_3 H_4 H_6 H_8 H_12 D_1 W_1 MN_1

Respuestas

200 Array de objetos Trendbar

Response body

[
  {
    "timestamp": 1700000000000,
    "open": 112340.0,
    "high": 112890.0,
    "low": 111950.0,
    "close": 112500.0,
    "volume": 4521
  }
]

Trendbar

Campo	Tipo	Descripción
`timestamp`	int64	Hora de apertura de la barra (epoch ms)
`open`	double	Precio de apertura (pipettes)
`high`	double	Precio máximo (pipettes)
`low`	double	Precio mínimo (pipettes)
`close`	double	Precio de cierre (pipettes)
`volume`	int64	Volumen del tic

Órdenes ¶

POST /v1/orders Colocar una nueva orden

Coloca una nueva orden de operaciones. Devuelve un ExecutionResponse.

Parámetros

Sin parámetros de ruta o consulta.

Cuerpo de la solicitud application/json

Campo	Tipo	Descripción
`symbolId`	int64	Símbolo a operar
`orderType`	string	`MARKET`, `LIMIT`, `STOP`, `MARKET_RANGE`, `STOP_LIMIT`
`tradeSide`	string	`BUY` o `SELL`
`volume`	int64	Volumen en centavos
`limitPrice`	double	Precio límite: requerido para `LIMIT`, `STOP_LIMIT`
`stopPrice`	double	Precio de activación del stop: requerido para `STOP`, `STOP_LIMIT`
`stopLoss`	double	Precio de stop loss
`takeProfit`	double	Precio de take profit
`comment`	string	Comentario de texto libre (máx. 256 caracteres)
`label`	string	Etiqueta de bot (máx. 100 caracteres)
`timeInForce`	string	`GOOD_TILL_CANCEL`, `GOOD_TILL_DATE`, `IMMEDIATE_OR_CANCEL`
`baseSlippagePrice`	double	Precio base para el deslizamiento: requerido para `MARKET_RANGE`
`slippageInPoints`	int32	Deslizamiento máximo en puntos
`expirationTimestamp`	int64	Marca de tiempo de vencimiento (epoch ms): para `GOOD_TILL_DATE`

Example request body

{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}

Respuestas

200 ExecutionResponse: orden aceptada o ejecutada

400 INVALID_REQUEST o TRADING_BAD_VOLUME

422 NOT_ENOUGH_MONEY

409 MARKET_CLOSED

Example success response

{
  "orderId": 12345,
  "positionId": 67890,
  "executionType": "ORDER_FILLED",
  "order": { "..." : "..." },
  "position": { "..." : "..." },
  "deal": { "..." : "..." }
}

GET /v1/orders Obtener órdenes pendientes

Devuelve todas las órdenes pendientes (no ejecutadas).

Parámetros

Sin parámetros.

Respuestas

200 Matriz de objetos Order pendientes

PUT /v1/orders/{orderId} Modificar una orden pendiente

Modifica una orden pendiente existente. Devuelve un ExecutionResponse.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`orderId`	ruta	int64		La orden a modificar

Cuerpo de la solicitud application/json

Cualquier subconjunto de los siguientes campos.

Campo	Tipo	Descripción
`volume`	int64	Nuevo volumen en centavos
`limitPrice`	double	Nuevo precio límite
`stopPrice`	double	Nuevo precio de stop
`stopLoss`	double	Nuevo precio de stop loss
`takeProfit`	double	Nuevo precio de take profit
`expirationTimestamp`	int64	Nueva marca de tiempo de vencimiento (epoch ms)

Respuestas

200 ExecutionResponse con ORDER_REPLACED

404 Orden no encontrada

DELETE /v1/orders/{orderId} Cancelar una orden pendiente

Cancela una orden pendiente. Devuelve un ExecutionResponse.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`orderId`	ruta	int64		La orden a cancelar

Respuestas

200 ExecutionResponse con ORDER_CANCELLED

404 Orden no encontrada

GET /v1/orders/history Obtener historial de órdenes

Devuelve órdenes históricas dentro de un rango de tiempo.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`fromTimestamp`	query	string		Hora de inicio (ISO-8601)
`toTimestamp`	query	string		Hora de finalización (ISO-8601)

Respuestas

200 OrderListResponse

Campo	Tipo	Descripción
`orders`	Order[]	Matriz de órdenes históricas
`hasMore`	boolean	Si hay páginas adicionales disponibles

Posiciones ¶

GET /v1/positions Obtener posiciones abiertas

Devuelve todas las posiciones abiertas y órdenes pendientes.

Parámetros

Sin parámetros.

Respuestas

200 Matriz de objetos Position

Response body

[
  {
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "entryPrice": 112345.0,
    "stopLoss": 112000.0,
    "takeProfit": 113000.0,
    "unrealizedPnl": 155.25,
    "commission": -7.00,
    "swap": -1.20
  }
]

Posición

Campo	Tipo	Descripción
`positionId`	int64	ID de la posición
`symbolId`	int64	ID del símbolo
`tradeSide`	string	`BUY` o `SELL`
`volume`	int64	Volumen en centavos
`entryPrice`	double	Precio de entrada VWAP
`stopLoss`	double	Precio de stop loss
`takeProfit`	double	Precio de take profit
`unrealizedPnl`	double	Beneficio/pérdida flotante
`commission`	double	Comisión cobrada
`swap`	double	Importe de swap

GET /v1/positions/{positionId} Obtener detalles de posición

Devuelve una posición con sus órdenes y operaciones relacionadas.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`positionId`	ruta	int64		El ID de posición

Respuestas

200 PositionDetailResponse

Campo	Tipo	Descripción
`position`	Position	Objeto Position
`orders`	Order[]	Órdenes relacionadas
`deals`	Deal[]	Operaciones relacionadas

PUT /v1/positions/{positionId} Modificar SL/TP de posición

Actualiza el stop loss y/o take profit de una posición abierta. Devuelve un ExecutionResponse.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`positionId`	ruta	int64		El ID de posición

Cuerpo de la solicitud application/json

Campo	Tipo	Descripción
`stopLoss`	double	Nuevo precio de stop loss (`null` para eliminar)
`takeProfit`	double	Nuevo precio de take profit (`null` para eliminar)
`trailingStopLoss`	boolean	Habilitar stop loss dinámico

Example request body

{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}

Respuestas

200 ExecutionResponse

POST /v1/positions/{positionId}/close Cerrar una posición

Cierra una posición abierta total o parcialmente. Use un valor menor que el volumen total de la posición para un cierre parcial. Devuelve un ExecutionResponse.

Parámetros

Nombre	Ubicado en	Tipo	Obligatorio	Descripción
`positionId`	ruta	int64		El ID de posición

Cuerpo de la solicitud application/json

Campo	Tipo	Obligatorio	Descripción
`volume`	int64		Volumen a cerrar en centavos

Example – full close (1 lot)

{
  "volume": 10000000
}

Respuestas

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – margen insuficiente para cierre parcial

Transacciones ¶

GET /v1/deals Obtener historial de operaciones

Devuelve operaciones ejecutadas dentro de un rango de tiempo.

Parámetros

Nombre	Ubicado en	Tipo	Configuración predeterminada	Descripción
`fromTimestamp`	query	string	–	Hora de inicio (ISO-8601)
`toTimestamp`	query	string	–	Hora de finalización (ISO-8601)
`maxRows`	query	int32	`50`	Máximo de operaciones a devolver

Respuestas

200 Matriz de objetos Deal

Response body

[
  {
    "dealId": 11111,
    "orderId": 12345,
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "filledVolume": 10000000,
    "executionPrice": 112345.0,
    "executionTimestamp": 1700000000000,
    "dealStatus": "FILLED",
    "commission": -7.00
  }
]

Deal

Campo	Tipo	Descripción
`dealId`	int64	ID de la transacción
`orderId`	int64	Orden que desencadenó esta operación
`positionId`	int64	ID de la posición
`symbolId`	int64	ID del símbolo
`tradeSide`	string	`BUY` o `SELL`
`volume`	int64	Volumen solicitado en centavos
`filledVolume`	int64	Volumen ejecutado en centavos
`executionPrice`	double	Precio de ejecución
`executionTimestamp`	int64	Hora de ejecución (epoch ms)
`dealStatus`	string	Estado – ver valores a continuación
`commission`	double	Comisión cobrada

Valores de dealStatus

Valor	Significado
`FILLED`	Orden completamente ejecutada
`PARTIALLY_FILLED`	Orden parcialmente ejecutada
`REJECTED`	Rechazada por el servidor de trading
`INTERNALLY_REJECTED`	Rechazada internamente antes de llegar al servidor
`ERROR`	Ocurrió un error durante la ejecución
`MISSED`	Orden perdida (p. ej., brecha en el mercado)

Esquemas { #execution-response-schema } ¶

ExecutionResponse ¶

Todas las operaciones de colocación, modificación y cancelación de órdenes devuelven este objeto.

Campo	Tipo	Descripción
`orderId`	int64	ID de orden afectada
`positionId`	int64	ID de posición afectada
`executionType`	string	Tipo de resultado: vea los valores a continuación
`order`	Order	Detalles de la orden (si corresponde)
`position`	Position	Detalles de la posición (si corresponde)
`deal`	Deal	Detalles de la operación (si corresponde)

Valores de executionType

Valor	Significado
`ORDER_ACCEPTED`	Orden pendiente aceptada
`ORDER_FILLED`	Orden completada totalmente
`ORDER_REPLACED`	Orden modificada
`ORDER_CANCELLED`	Orden cancelada
`ORDER_EXPIRED`	Orden vencida
`ORDER_REJECTED`	Orden rechazada
`ORDER_CANCEL_REJECTED`	Solicitud de cancelación rechazada
`ORDER_PARTIAL_FILL`	Orden parcialmente ejecutada
`SWAP`	Swap de posición aplicado
`DEPOSIT`	Depósito en cuenta
`WITHDRAW`	Retirada de cuenta
`BONUS_DEPOSIT_WITHDRAW`	Depósito o retirada de bonificación

Límites de tasa ¶

La pasarela aplica límites de tasa en varios niveles.

Nivel	Descripción
Por IP	Limita el total de solicitudes desde una única dirección IP
Por usuario	Limita el total de solicitudes en todas las cuentas para un único token
Por cuenta	Limita las solicitudes dirigidas a una única cuenta de operaciones

Límite de tasa excedido

Cuando se excede un límite de tasa, la API devuelve 429 Too Many Requests con un encabezado Retry-After.

Manejo de errores ¶

Cuando falla una solicitud, la API devuelve una respuesta de error JSON.

Error response format

{
  "error": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Insufficient free margin for this order",
    "httpStatus": 422,
    "retryAfter": null
  }
}

Códigos de error ¶

Código	HTTP	Descripción
`INVALID_REQUEST`	400	Parámetros de solicitud no válidos o faltantes
`UNAUTHORIZED`	401	Token no válido, caducado o faltante
`TRADING_BAD_VOLUME`	400	El volumen no es válido (por debajo del mínimo o excede la posición)
`NOT_ENOUGH_MONEY`	422	Margen libre insuficiente
`SYMBOL_NOT_FOUND`	404	El ID del símbolo no existe
`MARKET_CLOSED`	409	El mercado para el símbolo está actualmente cerrado
`MAINTENANCE`	503	El servidor de operaciones está en modo de mantenimiento
`TIMEOUT`	504	El servidor de operaciones no respondió a tiempo
`GATEWAY_RATE_LIMIT`	429	Límite de tasa excedido: vea el encabezado `Retry-After`

Gestión del límite de tasa

Cuando recibe una respuesta 429, el encabezado Retry-After y el campo retryAfter indican cuántos segundos debe esperar antes de enviar la siguiente solicitud.