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

# Synchronize leader history

> Import previous trades from an MT5 account and retrieve progress.

Use this workflow when adding an account as a leader that has already traded in MT5. The platform imports its previous trades to calculate metrics, charts, and historical results correctly before receiving new subscribers.

> [!NOTE]
>
> By default, all available trading history is imported from the MT5 account creation date. Only trades originated by the leader are included; deposits, withdrawals, and trades copied by MAM from another account are excluded.

> [!NOTE]
>
> If MT5 does not provide the registration date, the process starts from the date when the account was registered in MAM. In that case, send `from_at` explicitly if you need to import an earlier period.

## Automatic synchronization for existing leaders

When registering an existing leader with `POST /api/v1/mam/accounts/add`, the import starts automatically. You do not need to call another endpoint or send an additional parameter:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://mam-api.example.com/api/v1/mam/accounts/add" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mt5_login": "139682",
    "name": "Imported leader",
    "currency": "USD",
    "account_mode": "HEDGING",
    "can_be_leader": true,
    "can_be_follower": false,
    "status": "ACTIVE"
  }'
```

The account is registered immediately and history is imported in the background. Retrieve the synchronization status before enabling subscriptions.

* An account registered as a leader automatically imports its previous history.
* An account registered only as a follower is available immediately because it does not need the import.
* An account created from scratch through `/accounts/create` also does not need a history import because it has no previous trades.

## Promote an existing account to leader

If an account initially registered as a follower later becomes a leader, use:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://mam-api.example.com/api/v1/mam/accounts/139682" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "can_be_leader": true
  }'
```

When `can_be_leader` changes from `false` to `true`, the history import starts automatically. Editing other data on an account that was already a leader does not restart the process.

> [!WARNING]
>
> Registering the account does not mean history processing is complete. A `201` response confirms account registration; synchronization status is retrieved separately.

> [!NOTE]
>
> This behavior also applies when the account is registered through `/api/v1/mam/accounts/add-existing`. Synchronization is always managed by the MAM API without additional steps for the integrator.

## Request synchronization manually

You may request another synchronization after registration, for example to retry a failed import or include a specific interval.

### Complete history

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://mam-api.example.com/api/v1/mam/accounts/139682/history-sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "required_before_subscription": true,
    "requested_by": "bridge-crm"
  }'
```

When `from_at` and `to_at` are omitted, all available history is imported and the response reports `sync_mode="FULL"`.

### Specific interval

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://mam-api.example.com/api/v1/mam/accounts/139682/history-sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_at": "2026-01-01T00:00:00Z",
    "to_at": "2026-08-18T00:00:00Z",
    "required_before_subscription": true,
    "requested_by": "bridge-crm"
  }'
```

If you send at least one date, the mode is `RANGE`. When sending both, `to_at` must be later than `from_at`. Use ISO 8601 timestamps in UTC.

The `202` response contains the process status. If the account already has a `PENDING` or `RUNNING` synchronization, the API returns that process instead of starting another one in parallel.

## Retrieve the status

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://mam-api.example.com/api/v1/mam/accounts/139682/history-sync" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The request returns the most recent synchronization:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": 42,
  "account_id": 375,
  "account_login": "139682",
  "status": "RUNNING",
  "sync_mode": "FULL",
  "from_at": null,
  "to_at": "2026-08-18T14:00:03",
  "cursor_at": "2026-05-01T00:00:00",
  "last_deal_id": 25755253,
  "required_before_subscription": true,
  "requested_source": "ACCOUNT_IMPORT",
  "requested_by": null,
  "claimed_by": "history-worker-1",
  "lease_expires_at": "2026-08-18T14:10:03",
  "attempt_count": 1,
  "deals_seen": 1842,
  "deals_created": 1819,
  "error_message": null,
  "started_at": "2026-08-18T14:00:03",
  "completed_at": null,
  "created_at": "2026-08-18T14:00:00",
  "updated_at": "2026-08-18T14:01:20"
}
```

`deals_seen` indicates how many eligible trades were reviewed, and `deals_created` indicates how many were new to MAM. A lower `deals_created` value is normal when part of the history was already recorded.

| Status | Action |
| - | - |
| `PENDING` | Wait for it to start. |
| `RUNNING` | Retrieve again at a moderate interval, such as every 5 to 15 seconds. |
| `COMPLETED` | History import is complete and the leader can receive subscribers. |
| `FAILED` | Review `error_message` and create a new request after correcting the cause. |
| `CANCELLED` | Create a new request if synchronization is still required. |

## Effect on subscriptions

Automatic leader import is required. Until it reaches `COMPLETED`, the API does not allow validation or creation of a new subscription for that account.

| Error code | Meaning |
| - | - |
| `HISTORY_SYNC_IN_PROGRESS` | The import remains `PENDING` or `RUNNING`. |
| `HISTORY_SYNC_FAILED` | The latest required synchronization failed. |
| `HISTORY_SYNC_REQUIRED` | The required synchronization was canceled and must be requested again. |

All three cases return `409` and include `status` and the technical identifier `history_sync_job_id`, which allow you to retrieve or retry the corresponding synchronization.

## Do not confuse this with balance movements

The history synchronization described above reconstructs the leader's trades. To include deposits or withdrawals made directly in MT5, use:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/mam/accounts/{account_login}/balance-transactions/sync-mt5
```

This reconciliation endpoint is independent and does not replace trade history synchronization.


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