Tipos de órdenes

Los ocho tipos de órdenes, las cuatro políticas de vigencia y qué campos requiere cada uno.

OrderRequest es el cuerpo de cada operación que envía órdenes: POST /orders, POST /orders/batch (como elementos de un arreglo) y POST /orders/preview, más sus gemelas /api/v1.

Esta página cubre lo que se aplica a todas las operaciones, que las páginas de endpoint generadas omiten. Esas páginas indican lo que el contrato declara para una operación. La matriz de requisitos de abajo es lo que necesitas para construir una orden válida, y es idéntica en todas ellas.

Para la vista del trader sobre para qué sirve cada tipo, consulta Tipos de órdenes en la sección Exchange.

Esquema de envío de órdenes

Admite órdenes Limit y Market simples y seis tipos de órdenes condicionales (StopLimit, StopMarket, TakeProfitLimit, TakeProfitMarket, TrailingStop, TrailingLimit). Los requisitos de los campos dependen de order_type:

• Familia límite (Limit, StopLimit, TakeProfitLimit): requieren un price límite.
• Condicionales sin trailing (StopLimit, StopMarket, TakeProfitLimit, TakeProfitMarket): requieren un trigger_price (el campo heredado stop_price se acepta como alternativa cuando falta trigger_price).
• TrailingStop es solo de mercado, así que se activa como orden de mercado, y requiere trailing_offset_bps. No acepta un price límite ni un trigger_price (el ancla del disparador se deriva del precio de marca y del offset).
• TrailingLimit sigue al precio igual que TrailingStop, pero activa una orden límite en lugar de una orden de mercado. Requiere tanto trailing_offset_bps (el disparador trailing) como limit_offset_bps (el offset del límite en el momento de la activación). No acepta price, trigger_price ni stop_price. La plataforma calcula el precio límite en el momento de la activación a partir del precio de marca que cruzó el offset.

Campos obligatorios por tipo de orden

market_id, side, order_type, quantity y time_in_force son obligatorios para todos los tipos de órdenes. Los cuatro campos condicionales se resuelven así:

order_type	price	trigger_price	trailing_offset_bps	limit_offset_bps	Se activa como
Limit	Obligatorio	No se usa	Se ignora	Se ignora	— (queda en el libro de inmediato)
Market	Omitir	No se usa	Se ignora	Se ignora	— (se ejecuta de inmediato)
StopLimit	Obligatorio	Obligatorio	Se ignora	Se ignora	Límite
StopMarket	Omitir	Obligatorio	Se ignora	Se ignora	Mercado
TakeProfitLimit	Obligatorio	Obligatorio	Se ignora	Se ignora	Límite
TakeProfitMarket	Omitir	Obligatorio	Se ignora	Se ignora	Mercado
TrailingStop	No se acepta	No se acepta	Obligatorio	Se ignora	Mercado
TrailingLimit	No se acepta	No se acepta	Obligatorio	Obligatorio	Límite

Cómo leer la matriz:

• Obligatorio. La solicitud se rechaza sin él.
• Omitir. El campo no forma parte de una orden de la familia mercado, y no hay precio límite que definir.
• No se usa / No se acepta. El contrato indica que este tipo de orden no usa el campo. Los tipos trailing derivan su disparador del precio de marca y del offset.
• Se ignora. El campo puede estar presente, pero no tiene efecto para este tipo de orden.

Los cuatro tipos condicionales sin trailing solo difieren en la dirección del disparador. StopLimit y StopMarket se activan cuando el precio de marca cruza trigger_price en la dirección adversa, y TakeProfitLimit y TakeProfitMarket se activan en la dirección favorable.

stop_price está deprecado

stop_price está deprecado en favor de trigger_price. Las reglas:

• trigger_price es el umbral de activación canónico.
• stop_price se acepta solo como alternativa, cuando falta trigger_price.
• Cuando se envían ambos, prevalece trigger_price y stop_price se descarta.
• Ambos se ignoran por completo en las órdenes Limit, Market, TrailingStop y TrailingLimit.

Las integraciones nuevas deberían enviar trigger_price y nunca stop_price.

Vigencia

time_in_force es obligatorio en cada orden y acepta una de cuatro políticas:

Valor	Significado
GTC	Good-till-cancelled. Queda en el libro hasta que se ejecute o se cancele.
IOC	Immediate-or-cancel. Ejecuta lo que puede de inmediato y cancela el resto.
FOK	Fill-or-kill. Se ejecuta por completo de inmediato o se cancela en su totalidad.
PostOnly	Rechaza la orden si tomaría liquidez (cruzaría el libro) al entrar, lo que garantiza que quede en el libro como maker.

PostOnly es el único valor que el contrato describe en detalle. Las descripciones de arriba para GTC, IOC y FOK dan el significado estándar de cada sigla, que el contrato en sí no explica.

Campos de OrderRequest

Campo	Tipo	Obligatorio	Descripción
market_id	string	Sí	Identificador del mercado, p. ej. BTC-USDX-PERP.
side	Buy / Sell	Sí	Lado de la orden.
order_type	Limit / Market / StopLimit / StopMarket / TakeProfitLimit / TakeProfitMarket / TrailingStop / TrailingLimit	Sí	Tipo de orden. Limit y Market son incondicionales. Los seis restantes son condicionales. StopLimit / StopMarket se activan cuando el precio de marca cruza trigger_price en la dirección adversa. TakeProfitLimit / TakeProfitMarket se activan en la dirección favorable. TrailingStop se activa como orden de mercado cuando el precio de marca retrocede desde su mejor extremo registrado en trailing_offset_bps. TrailingLimit se activa de la misma forma, pero deja en el libro una orden límite con un precio desplazado respecto del precio de activación en limit_offset_bps.
price	string decimal	Condicional	Precio límite. Obligatorio para las órdenes de la familia límite (Limit, StopLimit, TakeProfitLimit). Omítelo en las órdenes de la familia mercado y en las trailing.
quantity	string decimal	Sí	Tamaño de la orden. Decimal de precisión arbitraria serializado como cadena (sin pérdida). Analízalo con un tipo decimal, nunca con un float.
time_in_force	GTC / IOC / FOK / PostOnly	Sí	Política de vigencia. PostOnly rechaza la orden si tomaría liquidez (cruzaría el libro) al entrar, lo que garantiza que quede en el libro como maker.
reduce_only	boolean	No	El contrato declara el campo sin descripción. Consulta Limitaciones conocidas.
stop_price	string decimal o null	No, deprecado	Deprecado. Usa trigger_price en su lugar. Umbral de activación heredado para la familia Stop / Take profit. Se acepta como alternativa solo cuando falta trigger_price. Cuando se envían ambos, prevalece trigger_price. Se ignora en las órdenes Limit, Market, TrailingStop y TrailingLimit.
trigger_price	string decimal o null	Condicional	Umbral de activación canónico para las órdenes condicionales sin trailing (StopLimit, StopMarket, TakeProfitLimit, TakeProfitMarket), que lo requieren (el campo heredado stop_price se acepta como alternativa cuando se omite este). No lo usan las órdenes Limit, Market, TrailingStop ni TrailingLimit.
trailing_offset_bps	entero (mínimo 0) o null	Condicional	Offset trailing en puntos básicos (1 bp = 0.01%). Obligatorio para las órdenes TrailingStop y TrailingLimit, y se ignora en todos los demás tipos de órdenes. El disparador trailing se activa cuando el precio de marca retrocede esa cantidad de puntos básicos desde su mejor extremo registrado. TrailingStop activa una orden de mercado, y TrailingLimit activa una orden límite con el precio fijado por limit_offset_bps. Se acepta un valor de 0, que activa el disparador en la primera evaluación del precio de marca después del envío (no se requiere retroceso).
limit_offset_bps	entero (0–9999) o null	Condicional	Offset en puntos básicos para el precio límite activado (solo TrailingLimit; obligatorio junto con trailing_offset_bps). Cuando el disparador trailing se activa en fire_price, la orden límite inyectada queda en fire_price × (1 + offset) para compras / × (1 − offset) para ventas, redondeada al tick hacia el límite más ajustado. Un valor de 0 deja el límite exactamente en fire_price. Se ignora en otros tipos de órdenes.

La admisión de órdenes se rige por la desigualdad de margen

La plataforma acepta una orden solo si la cuenta sigue cumpliendo el requisito de margen inicial una vez incluida la reserva propia de la orden. Esa es la desigualdad de admisión de órdenes (M.13) del modelo de margen del Exchange. Consulta Matemática del margen.

Un 400 en POST /orders con un motivo de margen insuficiente significa que esa desigualdad no se cumple. Usa POST /orders/preview para evaluarla sin enviar la orden.