> ## 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.

# Orders

> Placing and managing trading orders

## Order Types

VoxFi supports multiple order types for different trading strategies:

### Limit Orders

* **`LIMIT_BUY`**: Buy contracts at a specific price or better;
* **`LIMIT_SELL`**: Sell contracts at a specific price or better.

Limit orders are placed in the orderbook and execute when matched with a counterparty.

### Market Orders

* **`MARKET_BUY_VALUE`**: Buy contracts immediately, spending up to a specified value;
* **`MARKET_BUY_QTY`**: Buy a specific quantity of contracts immediately at market price;
* **`MARKET_SELL`**: Sell a specific quantity of contracts immediately at market price.

Market orders execute immediately against available liquidity in the orderbook.

## Order Outcomes

All orders specify an outcome:

* **`YES`**: Buying or selling YES contracts
* **`NO`**: Buying or selling NO contracts

## API Endpoints

### Place Order

Creates a new order in the market. Supports different order types: limit orders (`LIMIT_BUY`, `LIMIT_SELL`) and market orders (`MARKET_BUY_VALUE`, `MARKET_BUY_QTY`, `MARKET_SELL`).

[Detailed documentation + playground](/playground/trade/place-order)

### Cancel Order

Cancels an open limit order for the authenticated user.

[Detailed documentation + playground](/playground/trade/cancel-order)

### Merge Contracts

The operation burns matching YES/NO contract pairs (X YES and X NO), permanently removing them from the user’s position without affecting the order book or market price.

**Parameters:**

* `market_id` (required): ID of the market where contracts will be merged
* `quantity` (required): Quantity of contracts to be merged

[Detailed documentation + playground](/playground/trade/merge-contracts)

### List User Orders

Gets all open orders for the authenticated user. If `eventId` is provided, returns orders only for that event.

[Detailed documentation + playground](/playground/user/list-user-orders)

### Get User Activity

Returns the user's trading activity (executed trades) for a given market.

**Parameters:**

* `marketId` (optional): Market ID to filter activity
* `page` (optional): Page number for pagination
* `pageSize` (optional): Number of items per page

**Response:** Array of `UserActivity` objects containing:

* `contract_type`: Type of contract (YES/NO)
* `created_at`: Timestamp of the trade
* `price_ticks`: Price in ticks (0-100)
* `quantity`: Number of contracts traded
* `side`: Trade side (BUY/SELL)

[Detailed documentation + playground](/playground/user/get-user-activity)

### Get User P\&L

Returns the user's profit and loss (P\&L) for a given market or event.

**Parameters:**

* `marketId` (optional): Market ID to filter P\&L
* `eventId` (optional): Event ID to filter P\&L

**Response:** Array of `UserPnl` objects containing:

* `event_id`: Event ID
* `market_id`: Market ID
* `event_thumbnail_url`: URL for event thumbnail
* `market_thumbnail_url`: URL for market thumbnail
* `event_description`: Event description
* `market_description`: Market description
* `event_slug`: Event slug
* `winning_outcome`: The winning outcome ("YES"/"NO"/"")
* `settled_at`: Timestamp when the market was settled
* `qty_contracts_bought`: Total quantity of contracts bought
* `qty_contracts_bought_yes`: Quantity of YES contracts bought
* `qty_contracts_bought_no`: Quantity of NO contracts bought
* `qty_contracts_sold`: Total quantity of contracts sold
* `qty_contracts_sold_yes`: Quantity of YES contracts sold
* `qty_contracts_sold_no`: Quantity of NO contracts sold
* `qty_contracts_settled`: Total quantity of contracts settled
* `qty_contracts_settled_yes`: Quantity of YES contracts settled
* `qty_contracts_settled_no`: Quantity of NO contracts settled
* `amount_spent`: Total amount spent on purchases (in cents)
* `amount_spent_yes`: Total amount spent buying YES contracts (in cents)
* `amount_spent_no`: Total amount spent buying NO contracts (in cents)
* `amount_received`: Total amount received from sales before settlement (in cents)
* `amount_received_yes`: Total amount received from selling YES contracts before settlement (in cents)
* `amount_received_no`: Total amount received from selling NO contracts before settlement (in cents)
* `amount_settled`: Total amount settled (in cents)
* `amount_settled_yes`: Total amount settled for YES contracts (in cents)
* `amount_settled_no`: Total amount settled for NO contracts (in cents)
* `pnl`: Profit and loss (in cents)
* `pnl_yes`: Profit and loss for YES contracts (in cents)
* `pnl_no`: Profit and loss for NO contracts (in cents)

[Detailed documentation + playground](/playground/user/get-user-pnl)

### Order Lifecycle

1. **Placed**: Order is sent and validated
2. **Open**: Order is in the orderbook awaiting match
3. **Partially Filled**: Some contracts have been executed
4. **Filled**: Order is completely executed
5. **Cancelled**: Order is cancelled before execution

### Best Practices

* **Check Market Status**: Make sure the market is open before placing orders;
* **Monitor Liquidity**: Check orderbook depth before placing large orders;
* **Use Limit Orders**: For better price control and potentially lower fees;
* **Cancel Unfilled Orders**: Regularly cancel orders that are no longer needed.