Tipos de ordem

Os oito tipos de ordem, as quatro políticas de validade e quais campos cada um exige.

OrderRequest é o corpo de toda operação que envia ordens: POST /orders, POST /orders/batch (como elementos do array) e POST /orders/preview, além dos seus gêmeos /api/v1.

Esta página cobre o que vale para todas as operações, e que as páginas de endpoint geradas deixam de fora. Essas páginas informam o que o contrato declara para uma operação. A matriz de requisitos abaixo é o que você precisa para montar uma ordem válida, e ela é idêntica em todas elas.

Para a visão voltada ao trader sobre para que serve cada tipo, consulte Tipos de ordem na seção Exchange.

Schema de envio de ordens

Ele suporta ordens simples Limit e Market e seis tipos de ordem condicionais (StopLimit, StopMarket, TakeProfitLimit, TakeProfitMarket, TrailingStop, TrailingLimit). Os campos exigidos dependem de order_type:

• Família limite (Limit, StopLimit, TakeProfitLimit) exige um price limite.
• Ordens disparáveis, não trailing (StopLimit, StopMarket, TakeProfitLimit, TakeProfitMarket) exigem um trigger_price (o campo legado stop_price é aceito como alternativa quando trigger_price está ausente).
• TrailingStop é somente a mercado, então dispara como uma ordem a mercado, e exige trailing_offset_bps. Ela não aceita um price limite nem um trigger_price (a âncora do disparo é derivada do preço de marca e do offset).
• TrailingLimit acompanha o preço como a TrailingStop, mas dispara uma ordem limite em vez de uma ordem a mercado. Ela exige tanto trailing_offset_bps (o disparo trailing) quanto limit_offset_bps (o offset do limite no momento do disparo). Ela não aceita price, trigger_price nem stop_price. A plataforma calcula o preço limite no momento do disparo a partir do preço de marca que cruzou o offset.

Campos obrigatórios por tipo de ordem

market_id, side, order_type, quantity e time_in_force são obrigatórios em todos os tipos de ordem. Os quatro campos condicionais funcionam assim:

order_type	price	trigger_price	trailing_offset_bps	limit_offset_bps	Dispara como
Limit	Obrigatório	Não usado	Ignorado	Ignorado	— (entra no livro imediatamente)
Market	Omitir	Não usado	Ignorado	Ignorado	— (executa imediatamente)
StopLimit	Obrigatório	Obrigatório	Ignorado	Ignorado	Limite
StopMarket	Omitir	Obrigatório	Ignorado	Ignorado	Mercado
TakeProfitLimit	Obrigatório	Obrigatório	Ignorado	Ignorado	Limite
TakeProfitMarket	Omitir	Obrigatório	Ignorado	Ignorado	Mercado
TrailingStop	Não aceito	Não aceito	Obrigatório	Ignorado	Mercado
TrailingLimit	Não aceito	Não aceito	Obrigatório	Obrigatório	Limite

Como ler a matriz:

• Obrigatório. A requisição é rejeitada sem ele.
• Omitir. O campo não faz parte de uma ordem da família mercado, e não há preço limite a definir.
• Não usado / Não aceito. O contrato diz que este tipo de ordem não usa o campo. Os tipos trailing derivam seu disparo do preço de marca e do offset.
• Ignorado. O campo pode estar presente, mas não tem efeito para este tipo de ordem.

Os quatro tipos disparáveis, não trailing, diferem apenas na direção do disparo. StopLimit e StopMarket disparam quando o preço de marca cruza trigger_price na direção adversa, e TakeProfitLimit e TakeProfitMarket disparam na direção favorável.

stop_price está descontinuado

stop_price está descontinuado em favor de trigger_price. As regras:

• trigger_price é o limiar de disparo canônico.
• stop_price é aceito apenas como alternativa, quando trigger_price está ausente.
• Quando os dois são informados, trigger_price prevalece e stop_price é desconsiderado.
• Os dois são totalmente ignorados em ordens Limit, Market, TrailingStop e TrailingLimit.

Novas integrações devem enviar trigger_price e nunca stop_price.

Validade

time_in_force é obrigatório em toda ordem e aceita uma de quatro políticas:

Valor	Significado
GTC	Good-till-cancelled (válida até ser cancelada). Fica em repouso no livro até ser executada ou cancelada.
IOC	Immediate-or-cancel (imediata ou cancelada). Executa o que puder imediatamente e cancela o restante.
FOK	Fill-or-kill (tudo ou nada). É executada por completo imediatamente ou cancelada inteiramente.
PostOnly	Rejeita a ordem se ela fosse tomar liquidez (cruzar o livro) na entrada, garantindo que fique em repouso como maker.

PostOnly é o único valor que o contrato descreve em detalhes. As descrições acima para GTC, IOC e FOK dão o significado padrão de cada sigla, que o próprio contrato não explicita.

Campos de OrderRequest

Campo	Tipo	Obrigatório	Descrição
market_id	string	Sim	Identificador do mercado, por exemplo BTC-USDX-PERP.
side	Buy / Sell	Sim	Lado da ordem.
order_type	Limit / Market / StopLimit / StopMarket / TakeProfitLimit / TakeProfitMarket / TrailingStop / TrailingLimit	Sim	Tipo de ordem. Limit e Market são incondicionais. Os seis restantes são condicionais. StopLimit / StopMarket disparam quando o preço de marca cruza trigger_price na direção adversa. TakeProfitLimit / TakeProfitMarket disparam na direção favorável. TrailingStop dispara como uma ordem a mercado quando o preço de marca recua trailing_offset_bps a partir do seu melhor extremo observado. TrailingLimit dispara da mesma forma, mas coloca em repouso no livro uma ordem limite com preço afastado do preço de disparo em limit_offset_bps.
price	string decimal	Condicional	Preço limite. Obrigatório em ordens da família limite (Limit, StopLimit, TakeProfitLimit). Omita em ordens da família mercado e trailing.
quantity	string decimal	Sim	Tamanho da ordem. Decimal de precisão arbitrária serializado como string (sem perda). Faça o parse com um tipo decimal, nunca com float.
time_in_force	GTC / IOC / FOK / PostOnly	Sim	Política de validade. PostOnly rejeita a ordem se ela fosse tomar liquidez (cruzar o livro) na entrada, garantindo que fique em repouso como maker.
reduce_only	booleano	Não	O contrato declara o campo sem descrição. Consulte Lacunas conhecidas.
stop_price	string decimal ou null	Não, descontinuado	Descontinuado. Use trigger_price em vez dele. Limiar de disparo legado para a família stop / take profit. Aceito como alternativa apenas quando trigger_price está ausente. Quando os dois são informados, trigger_price prevalece. Ignorado em ordens Limit, Market, TrailingStop e TrailingLimit.
trigger_price	string decimal ou null	Condicional	Limiar de disparo canônico para ordens disparáveis, não trailing (StopLimit, StopMarket, TakeProfitLimit, TakeProfitMarket), que o exigem (o campo legado stop_price é aceito como alternativa quando este é omitido). Não usado por ordens Limit, Market, TrailingStop ou TrailingLimit.
trailing_offset_bps	inteiro (mínimo 0) ou null	Condicional	Offset trailing em pontos-base (1 bp = 0,01%). Obrigatório em ordens TrailingStop e TrailingLimit, e ignorado em todos os outros tipos de ordem. O disparo trailing ocorre quando o preço de marca recua essa quantidade de pontos-base a partir do seu melhor extremo observado. TrailingStop dispara uma ordem a mercado, e TrailingLimit dispara uma ordem limite com preço definido por limit_offset_bps. Um valor 0 é aceito e aciona o disparo na primeira avaliação do preço de marca após o envio (sem necessidade de recuo).
limit_offset_bps	inteiro (0–9999) ou null	Condicional	Offset em pontos-base para o preço limite disparado (apenas TrailingLimit; obrigatório junto com trailing_offset_bps). Quando o disparo trailing ocorre em fire_price, a ordem limite injetada fica em repouso no livro em fire_price × (1 + offset) para compras / × (1 − offset) para vendas, arredondada ao tick em direção ao limite mais restritivo. Um valor 0 coloca o limite exatamente em fire_price. Ignorado em outros tipos de ordem.

A admissão de ordens é regida pela inequação de margem

A plataforma aceita uma ordem apenas se a conta ainda satisfizer a exigência de margem inicial depois que a reserva da própria ordem é incluída. Essa é a inequação de admissão de ordens (M.13) no modelo de margem da Exchange. Consulte Matemática de margem.

Um 400 em POST /orders com um motivo de margem insuficiente é essa inequação falhando. Use POST /orders/preview para avaliá-la sem enviar a ordem.