> ## Documentation Index
> Fetch the complete documentation index at: https://api-trading-docs.vexprofx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Volumen: lotes y unidades MT5

> Conversiones, tamaño de contrato y campos de volumen por endpoint.

## Unidad de volumen de la API

**Todos los campos públicos de volumen usan unidades MT5: 10000 unidades = 1 lote.**
Ningún endpoint de partners recibe ni devuelve el volumen expresado directamente
en lotes. Los ejemplos en lotes son equivalencias para la integración.
La API no convierte automáticamente `volume` desde lotes.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
unidades API = lotes × 10000
lotes = unidades API ÷ 10000
```

| Lotes | Unidades API |
| -: | -: |
| 0,0001 | 1 |
| 0,001 | 10 |
| 0,01 | 100 |
| 0,10 | 1000 |
| 0,50 | 5000 |
| 1 | 10000 |
| 2 | 20000 |

Son equivalencias, no una lista de volúmenes permitidos para todos los activos.
Por ejemplo, `"volume": 1` significa 0,0001 lotes, nunca 1 lote.

## Símbolo y tamaño del contrato

El factor 10000 no cambia por símbolo, broker, grupo de cuenta o `ContractSize`
dentro de este contrato API. `ContractSize` describe el tamaño de un lote del
instrumento; no es el factor para codificar el volumen que debes enviar.

Así, un símbolo con `ContractSize = 1` y otro con `ContractSize = 10` reciben
ambos `"volume": 10000` para solicitar 1 lote. La exposición económica de esos
lotes puede ser diferente. No multipliques ni dividas el volumen API por
`ContractSize`; tampoco calcules margen o beneficio únicamente con esa conversión.

Lo que sí depende del símbolo y de la configuración efectiva del grupo es:

* `VolumeMin`: volumen mínimo, en unidades MT5.
* `VolumeMax`: volumen máximo, en unidades MT5.
* `VolumeStep`: paso permitido, en unidades MT5.

Las validaciones de volumen contrastan esos valores con `volume`: debe estar entre
mínimo y máximo y ser múltiplo del paso. Convertir correctamente no garantiza que
el volumen sea admisible. La API no ajusta ni redondea silenciosamente la cantidad.

Ejemplo de configuración: mínimo 5000 y paso 100 equivalen a un mínimo de 0,5 lotes
y un paso de 0,01 lotes. En ese caso, 0,01 lotes se convierte correctamente en 100,
pero no alcanza el mínimo permitido.

## Campos por endpoint

Las rutas de la tabla se añaden a la URL base de la API.

| Endpoint | Entrada de volumen | Salida de volumen / interpretación |
| - | - | - |
| `POST /api/v1/orders/market` | `volume`: entero en unidades MT5 | Devuelve un ID de solicitud; consultar el resultado para conocer la ejecución. |
| `POST /api/v1/orders/pending` | `volume`: entero en unidades MT5 | Devuelve un ID; colocar la pendiente no confirma que ya se haya ejecutado. |
| `POST /api/v1/positions/{position}/close` | `volume`: entero opcional en unidades MT5 | Omitirlo solicita todo el volumen actual; no garantiza cierre completo si la ejecución es parcial. |
| `GET /api/v1/accounts/{login}/positions` | Sin volumen | `Volume`: volumen actual de cada posición, en unidades MT5. |
| `GET /api/v1/accounts/{login}/orders` | Sin volumen | `VolumeInitial`: inicial; `VolumeCurrent`: remanente. Ambos en unidades MT5. |
| `GET /api/v1/trading/requests/{request_id}` | Sin volumen | En el evento `answer`, `Volume` es solicitado y `ResultVolume` es ejecutado; en el evento `result`, `Volume` es confirmado. Todos en unidades MT5. |
| `POST /api/v1/orders/{order}/cancel` | No acepta volumen | Solicita cancelar la orden pendiente identificada, sin selección de volumen parcial. |
| `POST /api/v1/orders/{order}/modify` | No acepta volumen | `price`, `stop_limit_price`, `sl` y `tp` son precios absolutos. |
| `POST /api/v1/positions/{position}/modify` | No acepta volumen | `sl` y `tp` son precios absolutos; no son lotes, unidades de volumen ni distancias. |

Los demás endpoints de partners no reciben ni exponen un volumen de trading.
`GET /api/v1/accounts/{login}/positions/count` devuelve cantidad de posiciones,
no lotes. `offset` y `total` son parámetros de paginación, no volumen.

Los formatos de resultado pueden variar entre eventos agrupados y resultados
planos. La unidad de los campos no cambia. En cancelaciones o modificaciones de
SL/TP, un volumen cero no indica fallo: interpreta `summary.status` y `mt5_code`.

## Apertura, cierre y ejecución parcial

Para solicitar 0,5 lotes, usa `"volume": 5000` al abrir una orden.
Para solicitar cerrar 0,2 lotes de una posición de 0,5 lotes:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"login":104205,"volume":2000}
```

Envía ese cuerpo a `POST /api/v1/positions/{position}/close`, con el ticket real
y una nueva `Idempotency-Key`. Para solicitar todo el volumen actual, omite
`volume`: `{"login":104205}`. No uses `volume: 0` para un cierre completo.

Un resultado con `Volume = "5000"` y `ResultVolume = "3000"` en el evento
`answer` indica 0,5 lotes solicitados y 0,3 lotes ejecutados. No presupongas que
el volumen solicitado se ejecutó íntegro. Comprueba el resultado y las posiciones;
la API no reenvía automáticamente el remanente IOC.

## Conversión en el cliente

Envía `volume` como número entero JSON. Las respuestas pueden representar los
enteros como cadenas: `"Volume": "5000"` sigue siendo 0,5 lotes. Un campo ausente
o `null` no debe convertirse en cero ni considerarse prueba de no ejecución.

Usa aritmética decimal y comprueba que el resultado de la conversión es entero,
sin truncarlo ni redondearlo. Ejemplo Python, partiendo de una cantidad en texto:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from decimal import Decimal

lotes = Decimal("0.50")
unidades = lotes * 10000
if not unidades.is_finite() or unidades <= 0:
    raise ValueError("El volumen debe ser positivo y finito")
if unidades != unidades.to_integral_value():
    raise ValueError("El volumen no se puede representar en unidades API enteras")
volume = int(unidades)  # 5000; validar además mínimo, máximo y paso del símbolo
```

Si tu interfaz muestra lotes, convierte una vez al preparar la petición y divide
entre 10000 una vez al presentar el volumen recibido. No conviertas dos veces.
No uses campos internos `VolumeExt`: tienen otra escala y no forman parte del
contrato público de estos endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.