# Account trade list (USER_DATA)

## API Description

Executed deals for the account. A deal is the atomic execution record: a market entry, an exit, a
partial close, or a balance-affecting operation.

> **Today this endpoint returns CLOSING deals only.** It reads the broker's stored deal history, and
> that history currently persists only the deals that close or reduce a position — so `entry` is
> `OUT`, `INOUT` or `OUT_BY`, never `IN`. The opening deal of a round trip does not appear here.
> Realised P\&L still reconciles, because profit, commission and swap are booked on the exit; what you
> cannot reconstruct from this endpoint alone is the entry price, which is on the `DEAL` event
> ([user data stream](/user-data-streams/deal.md)) at the moment of the fill.

## HTTP Request

```http
GET /v1/userTrades
```

## Request Weight

5

## Request Parameters

| Name | Type | Mandatory | Description |
| - | - | - | - |
| `login` | LONG | YES | |
| `symbol` | STRING | NO | Exact, case-sensitive. |
| `startTime` | LONG | NO | Inclusive, Unix ms. |
| `endTime` | LONG | NO | Inclusive, Unix ms. |
| `fromId` | LONG | NO | Return deals with a `dealId` greater than or equal to this. Overrides the time window. |
| `limit` | INT | NO | Default `500`, maximum `1000`. |
| `recvWindow`, `timestamp`, `signature` | | | |

- With no window, the last **7 days** are returned. `endTime` alone returns the 7 days ending at
  `endTime`; `startTime` alone runs from `startTime` to now.
- `endTime - startTime` may not exceed **7 days** (`-1127`) — including the implicit "now" when only
  `startTime` is sent. `endTime` before `startTime` is `-1128`.
- The window applies to the deal's close time. `fromId` ignores it entirely.
- Ordered oldest first, by `dealId`.

> **Pre-release:** this endpoint returns `[]` on staging — see
> [Known limitations](/known-limitations.md#get-v1usertrades-is-empty-on-staging).

## Response Example

```json
[
  {
    "login": 100123,
    "dealId": 55512400,
    "orderId": 44412399,
    "positionId": 44412345,
    "symbol": "XAUUSD",
    "side": "SELL",
    "entry": "OUT",
    "volume": "0.10",
    "price": "2331.60",
    "profit": "1.8000",
    "commission": "-0.7000",
    "swap": "0.0000",
    "comment": "signal-7",
    "time": 1789012600000
  },
  {
    "login": 100123,
    "dealId": 55512455,
    "orderId": 44412450,
    "positionId": 44412400,
    "symbol": "BTCUSD",
    "side": "BUY",
    "entry": "OUT",
    "volume": "0.05",
    "price": "64135.00",
    "profit": "-12.5000",
    "commission": "-0.4000",
    "swap": "-0.1200",
    "comment": "",
    "time": 1789012900000
  }
]
```

| Field | Type | Description |
| - | - | - |
| `dealId` | LONG | Deal ticket. The natural key — **dedupe on it.** |
| `orderId` | LONG | Order that produced the deal. |
| `positionId` | LONG | Position the deal opened, added to, or closed. |
| `side` | ENUM | `BUY` / `SELL`, **as the broker's history writer stored it.** See the caveat below — do not assume it is the deal's own direction. |
| `entry` | ENUM | `OUT` closing or partially closing, `INOUT` close-and-reverse, `OUT_BY` closed by an opposite position. `IN` does not currently occur here. See [Common Definition](/common-definition.md#deal-entry). |
| `volume` | DECIMAL | Lots. |
| `price` | DECIMAL | Execution price. |
| `profit` | DECIMAL | Realised profit. Non-zero only on `OUT`, `INOUT` and `OUT_BY`. |
| `commission` | DECIMAL | Commission charged on this deal. Usually negative. |
| `swap` | DECIMAL | Swap booked with this deal. |
| `comment` | STRING | Comment stored on the deal. |
| `time` | LONG | Execution time, Unix ms (MT5 resolution is seconds). |

**Notes**

- **`side` is the stored direction, and its meaning depends on which writer produced the row.** The
  live deal-stream writer stores the direction of the **closed position** (MT5 exits a long with a
  SELL deal, so it inverts the deal's action deliberately, for display); the older history sync
  stores the **deal's** own action. Nothing on the row says which wrote it, so this API surfaces the
  stored value rather than guessing. **If you need the deal's true direction, take it from the
  `DEAL` event's `S` field**, which is unambiguous. Making `side` deal-accurate here requires the raw
  deal action to be persisted alongside the row — a planned broker-side follow-up.
- Realised P\&L for a round trip is the sum of `profit + commission + swap` over the deals sharing a
  `positionId`. Do not read `profit` alone.
- Only trading deals are returned. Balance operations, credit grants, commission postings and other
  non-trading deal types are excluded, so this endpoint does not reconcile to the account balance on
  its own.
- Deals are **append-only** on the trade server, but a broker correction can modify or remove one.
  Re-reading a window can therefore differ from a previous read; `dealId` remains the key.
- This endpoint reads the broker's stored deal history, not the trade server directly, so a deal can
  take a moment to appear here after the `DEAL` event on the user data stream. The stream is the
  low-latency path; this endpoint is the durable one.