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

# Deal history

> Read executions and charges by verified account and timestamp range.

`GET /api/v1/accounts/{login}/deals` reads the verified account's MT5 history.
It appears in `/openapi/partners.json`, under the existing `/api/v1` prefix.
This is a read-only query: no `Idempotency-Key` or trading enablement is required.

## Access and parameters

The token needs `GET:/api/v1/accounts/*/deals` or a covering permission such as
`GET:/api/v1/accounts/*`. Existing tokens with that broad permission already cover
the route. The same token must hold an active verification for this account.

| Parameter | Meaning |
| - | - |
| `login` | Verified account in the path; positive integer. |
| `from` | Required inclusive start, Unix timestamp in **UTC seconds**. |
| `to` | Required inclusive end, Unix timestamp in **UTC seconds**, at least `from`. |
| `offset` | Zero-based offset; default `0`, maximum `4294967295`. |
| `total` | Maximum page size, `1`–`100`; default `100`. Not the overall matching count. |

Do not send milliseconds or date strings. Accepted timestamps range from `0`
to `253402300799`. Keep the same `from` and `to` while paging.

```bash theme={null}
curl --fail-with-body --get "$API_BASE/api/v1/accounts/167848/deals" \
  -H "Authorization: Bearer $MT5_API_TOKEN" \
  --data-urlencode "from=1790812800" \
  --data-urlencode "to=1792540799" \
  --data-urlencode "offset=0" \
  --data-urlencode "total=100"
```

This example covers October 1, 2026 at 00:00:00 UTC through October 20, 2026 at
23:59:59 UTC. Use timezone-aware dates when converting to timestamps.

## Response fields

The response contains `retcode` and an `answer` list. An empty list is a successful
query with no records on that page. Numbers may be strings: preserve precision
and use decimal arithmetic for monetary amounts.

| Field | Meaning |
| - | - |
| `Deal` | Unique deal ticket; use it for deduplication. |
| `Login`, `Order`, `PositionID` | Account, order and associated position; distinct from a trading request ID. |
| `Symbol`, `Action`, `Entry`, `Reason` | Instrument, action, entry/exit and reason. |
| `Time`, `TimeMsc` | Deal time in Unix seconds and milliseconds, respectively. |
| `Price`, `PriceSL`, `PriceTP`, `Digits` | Execution price, historical protection levels and price precision. |
| `Volume`, `VolumeClosed` | Executed and closed volumes: `10000 = 1 lot`. |
| `VolumeExt`, `VolumeClosedExt` | Higher-precision representations: `100000000 = 1 lot`. Do not add them to their corresponding standard volumes. |
| `Profit`, `Storage`, `Commission`, `Fee` | Signed profit, swap, commission and additional fee in account currency. |
| `DigitsCurrency` | Account currency precision. |

`Storage` is the swap field in this API. Missing or `null` values are unavailable,
not zero. Explicit zeros remain zero.

## Closed deals and position results

The route returns all deals in the period, including entries, exits and balance
transactions. For buy/sell deals (`Action` 0/1), `Entry` identifies `0` entry,
`1` exit, `2` reversal or `3` close-by. An exit can be partial; a reversal combines
a close with a new entry.

When all four amounts are available, the booked net amount of a deal is
`Profit + Storage + Commission + Fee`, preserving the original signs. Group
**all deals by `PositionID`**, including entries that may carry commission, for
a position's complete booked result. If the entry predates `from`, extend the
query. A partial date range is not a complete lifetime result.

An exit alone does not prove the whole position is closed. Account for partial
closes and reversals, and read open positions for current state. Daily/monthly
charges or records with `PositionID=0` may not belong to one position. Do not
allocate them arbitrarily or add them to every position. This route neither
allocates unassociated charges nor computes a net result per position.

## Pagination

Advance `offset` by the number of received rows. Stop on an empty page or a page
shorter than `total`; request another page when it is full. History is not a locked
snapshot: new activity and corrections can change it. Deduplicate by `Deal` when
synchronizing and reconcile periods that may receive corrections. Preserve MT5's
order instead of assuming another sort order.

```python theme={null}
from datetime import datetime, timezone

start = int(datetime(2026, 10, 1, tzinfo=timezone.utc).timestamp())
end = int(datetime(2026, 10, 21, tzinfo=timezone.utc).timestamp()) - 1
offset, page_size = 0, 100
deals_by_id = {}
while True:
    page = client.deals(167848, start, end, offset=offset, total=page_size)["answer"]
    for deal in page:
        deals_by_id[str(deal["Deal"])] = deal
    if len(page) < page_size:
        break
    offset += len(page)
```

`client` is an authenticated instance of the supplied Python client. A `401` means
invalid token; `403`, missing permission or verification; `422`, invalid query.
Do not interpret `502/503` as an empty history.

Concept reference: [MetaQuotes deal properties](https://www.mql5.com/en/docs/constants/tradingconstants/dealproperties).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.