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

# Ordens

> Executando e gerenciando ordens de negociação

## Tipos de Ordem

O VoxFi suporta múltiplos tipos de ordem para diferentes estratégias de negociação:

### Ordens Limitadas

* **`LIMIT_BUY`**: Comprar contratos a um preço específico ou melhor;
* **`LIMIT_SELL`**: Vender contratos a um preço específico ou melhor.

Ordens limitadas são colocadas no orderbook e executam quando correspondidas com uma contraparte.

### Ordens a Mercado

* **`MARKET_BUY_VALUE`**: Comprar contratos imediatamente, gastando até um valor especificado;
* **`MARKET_BUY_QTY`**: Comprar uma quantidade específica de contratos imediatamente ao preço de mercado;
* **`MARKET_SELL`**: Vender uma quantidade específica de contratos imediatamente ao preço de mercado.

Ordens a mercado executam imediatamente contra a liquidez disponível no orderbook.

## Resultados da Ordem

Todas as ordens especificam um resultado:

* **`YES`**: Comprando ou vendendo contratos YES
* **`NO`**: Comprando ou vendendo contratos NO

## Endpoints da API

### Criar Ordem

Cria uma nova ordem no mercado. Suporta diferentes tipos de ordem: limitadas (`LIMIT_BUY`, `LIMIT_SELL`) e a mercado (`MARKET_BUY_VALUE`, `MARKET_BUY_QTY`, `MARKET_SELL`).

[Documentação detalhada + playground](/playground/trade/place-order)

### Cancelar Ordem

Cancela uma ordem limitada aberta do usuário autenticado.

[Documentação detalhada + playground](/playground/trade/cancel-order)

### Queimar contratos

Permite ao usuário queimar seus próprios contratos em um mercado específico.

A operação queima pares equivalentes de contratos YES/NO (X YES e X NO), removendo-os permanentemente da posição do usuário, sem impacto no livro de ordens.

**Parâmetros:**

* `market_id` (obrigatório): ID do mercado onde os contratos serão queimados
* `quantity` (obrigatório): Quantidade de contratos a serem queimados

[Documentação detalhada + playground](/playground/trade/merge-contracts)

### Listar Ordens do Usuário

Obtém todas as ordens abertas do usuário autenticado. Se `eventId` for fornecido, retorna ordens apenas para aquele evento.

[Documentação detalhada + playground](/playground/user/list-user-orders)

## Ciclo de Vida da Ordem

1. **Feita**: Ordem é enviada e validada
2. **Aberta**: Ordem está no orderbook aguardando correspondência
3. **Parcialmente Preenchida**: Alguns contratos foram executados
4. **Preenchida**: Ordem está completamente executada
5. **Cancelada**: Ordem é cancelada antes da execução

## Boas Práticas

* **Verificar Status do Mercado**: Certifique-se de que o mercado está aberto antes de fazer ordens;
* **Monitorar Liquidez**: Verifique a profundidade do orderbook antes de fazer ordens grandes;
* **Usar Ordens Limitadas**: Para melhor controle de preço e possivelmente taxas menores;
* **Cancelar Ordens Não Preenchidas**: Regularmente cancele ordens que não são mais necessárias.

### Obter Atividade do Usuário

Retorna a atividade de negociação do usuário (trades executados) para um determinado mercado.

**Parâmetros:**

* `marketId` (opcional): ID do mercado para filtrar a atividade
* `page` (opcional): Número da página para paginação
* `pageSize` (opcional): Quantidade de itens por página

**Resposta:** Array de objetos `UserActivity` contendo:

* `contract_type`: Tipo de contrato (YES/NO)
* `created_at`: Data e hora da negociação
* `price_ticks`: Preço em ticks (0-100)
* `quantity`: Quantidade de contratos negociados
* `side`: Lado da negociação (BUY/SELL)

[Documentação detalhada + playground](/playground/user/get-user-activity)

### Obter P\&L do Usuário

Retorna o lucro e prejuízo (P\&L) do usuário para um determinado mercado ou evento.

**Parâmetros:**

* `marketId` (opcional): ID do mercado para filtrar o P\&L
* `eventId` (opcional): ID do evento para filtrar o P\&L

**Resposta:** Array de objetos `UserPnl` contendo:

* `event_id`: ID do evento
* `market_id`: ID do mercado
* `event_thumbnail_url`: URL do thumbnail do evento
* `market_thumbnail_url`: URL do thumbnail do mercado
* `event_description`: Descrição do evento
* `market_description`: Descrição do mercado
* `event_slug`: Slug do evento
* `winning_outcome`: O resultado vencedor ("YES"/"NO"/"")
* `settled_at`: Data e hora em que o mercado foi liquidado
* `qty_contracts_bought`: Quantidade total de contratos comprados
* `qty_contracts_bought_yes`: Quantidade de contratos YES comprados
* `qty_contracts_bought_no`: Quantidade de contratos NO comprados
* `qty_contracts_sold`: Quantidade total de contratos vendidos
* `qty_contracts_sold_yes`: Quantidade de contratos YES vendidos
* `qty_contracts_sold_no`: Quantidade de contratos NO vendidos
* `qty_contracts_settled`: Quantidade total de contratos liquidados
* `qty_contracts_settled_yes`: Quantidade de contratos YES liquidados
* `qty_contracts_settled_no`: Quantidade de contratos NO liquidados
* `amount_spent`: Valor total gasto em compras (em centavos)
* `amount_spent_yes`: Valor total gasto na compra de contratos YES (em centavos)
* `amount_spent_no`: Valor total gasto na compra de contratos NO (em centavos)
* `amount_received`: Valor total recebido das vendas antes da liquidação (em centavos)
* `amount_received_yes`: Valor total recebido das vendas de contratos YES antes da liquidação (em centavos)
* `amount_received_no`: Valor total recebido das vendas de contratos NO antes da liquidação (em centavos)
* `amount_settled`: Valor total liquidado (em centavos)
* `amount_settled_yes`: Valor total liquidado para contratos YES (em centavos)
* `amount_settled_no`: Valor total liquidado para contratos NO (em centavos)
* `pnl`: Lucro e prejuízo (em centavos)
* `pnl_yes`: Lucro/prejuízo para contratos YES (em centavos)
* `pnl_no`: Lucro/prejuízo para contratos NO (em centavos)

[Documentação detalhada + playground](/playground/user/get-user-pnl)

### Ciclo de Vida da Ordem

1. **Feita**: Ordem é enviada e validada
2. **Aberta**: Ordem está no orderbook aguardando correspondência
3. **Parcialmente Preenchida**: Alguns contratos foram executados
4. **Preenchida**: Ordem está totalmente executada
5. **Cancelada**: Ordem é cancelada antes da execução

### Boas Práticas

* **Verifique o Status do Mercado**: Certifique-se de que o mercado está aberto antes de enviar ordens;
* **Monitore a Liquidez**: Verifique a profundidade do orderbook antes de enviar ordens grandes;
* **Prefira Ordens Limite**: Para melhor controle de preço e taxas potencialmente menores;
* **Cancele Ordens Não Preenchidas**: Cancele regularmente ordens que não são mais necessárias.