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

# Open a market trade

> Buy or sell with price and decimals resolved by the backend.

`POST /api/v1/orders/market` requires trading permission, a verified account, and
`Idempotency-Key`. Send `side: "buy"` or `side: "sell"`.

## Recommended request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"login":104205,"symbol":"EURUSD","volume":100,"side":"buy","comment":"REST API"}
```

`volume` remains in MT5 units: **100 = 0.01 lots**, 1000 = 0.10 lots, and
10000 = 1 lot. Do not send `0.01` as `volume`. This contract does not convert
from lots or accept a `volume_lots` field.

| Field | Constraint |
| - | - |
| `login` | Positive integer; account verified with your token |
| `symbol` | Exact broker symbol, between 1 and 32 characters |
| `volume` | Positive integer in MT5 units |
| `side` | `buy` or `sell` |
| `comment` | Optional; up to 31 characters; default `REST API` |

## Automatic price and decimals

Omit `price` and `digits`. The backend queries account data and the effective
symbol configuration, validates volume and opening permissions, and obtains the
applicable quote. It uses Ask for buys and Bid for sells. Price decimals come
from the symbol. This internal information is not returned.

Although the partner does not send a price, the Dealer request includes `PriceOrder`
and `Digits`. The final execution price is not guaranteed to equal the quote.
Automatic mode requires a quote no older than 60 seconds by default, configurable
by the operator; freshness is checked again immediately before submission.
Missing or invalid quotes produce `502`; stale quotes produce `503`.

Market openings and position closings automatically select a filling policy using
MT5's effective symbol configuration for the account's group. FOK is preferred
when allowed; otherwise IOC is used when supported. Request/Instant execution
allows FOK independently of fill flags. Market/Exchange execution uses the symbol's
FOK/IOC flags; if neither is supported the API returns `422` before submission.

FOK executes the entire volume or cancels. IOC may execute less than requested and
cancels the remainder. A successful submission is not proof of a complete fill:
query the execution result and positions to determine the actual volume. A close
may leave part of the position open. The API never resubmits an unfilled remainder
or retries with another filling policy. Reusing the same idempotency key returns
the original submitted response. The selected policy is recorded in audit logs.
This also applies when legacy explicit `price` and `digits` are supplied.
Pending orders retain RETURN filling, as required by MT5.

## Compatibility

Existing integrations may still send **both** deprecated fields `price` and
`digits`. They retain the previous explicit behavior: the API uses those values
without automatically querying quotes. Symbol settings are still read to select FOK/IOC. Sending only one
produces `422`. Omit both to use automatic mode. Closing positions accepts only login and optional volume/comment; all execution parameters are resolved by the server.

## Submission and result

Save the body as `opening.json` and persist one unique key per intent.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body -X POST "$API_BASE/api/v1/orders/market" \
  -H "Authorization: Bearer $MT5_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $OPEN_KEY" \
  --data-binary @opening.json
```

Store `answer.id` or `answer.ID` and query [the result](/trading/results).
`retcode: "0 Done"` confirms receipt, not execution. Retrying the same key and body
returns the stored response without requoting or trading again; changing the body
produces `409`. For errors after key reservation, follow
[idempotency and recovery](/trading/idempotency).

For limit, stop, and stop-limit orders, use [pending orders](/trading/pending).