Synchronize leader history

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.

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.

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:

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:

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.

Registering the account does not mean history processing is complete. A 201 response confirms account registration; synchronization status is retrieved separately.

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

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

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

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:

{
  "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:

POST /api/v1/mam/accounts/{account_login}/balance-transactions/sync-mt5

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

Getting Started

Core Workflow

Operations

Help

Product updates

Synchronize leader history

Automatic synchronization for existing leaders

Promote an existing account to leader

Request synchronization manually

Complete history

Specific interval

Retrieve the status

Effect on subscriptions

Do not confuse this with balance movements

​Automatic synchronization for existing leaders

​Promote an existing account to leader

​Request synchronization manually

​Complete history

​Specific interval

​Retrieve the status

​Effect on subscriptions

​Do not confuse this with balance movements

Automatic synchronization for existing leaders

Promote an existing account to leader

Request synchronization manually

Complete history

Specific interval

Retrieve the status

Effect on subscriptions

Do not confuse this with balance movements