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

# Manage accounts

> Create, register, retrieve, and fund MetaTrader 5 accounts.

## Create an MT5 account

Use `POST /api/v1/mam/accounts/create` when the account does not yet exist. `platform_group` must be the actual MT5 group assigned by the broker.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://mam-api.example.com/api/v1/mam/accounts/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Anna",
    "last_name": "Garcia",
    "name": "Anna's account",
    "username": "anna@example.com",
    "platform_group": "real\\MAM",
    "leverage": 100,
    "rights": 9073,
    "currency": "USD",
    "account_mode": "HEDGING",
    "can_be_leader": false,
    "can_be_follower": true,
    "status": "ACTIVE"
  }'
```

The response returns `mt5_login` and the generated credentials. Deliver them through a secure channel and do not record them in plain text.

> [!NOTE]
>
> The MT5 permission profiles supported by this integration are `9073` for trading enabled and `8981` to apply *Trade Disabled*. Send one of these values explicitly.

## Register an existing account

Use `POST /api/v1/mam/accounts/add`. This endpoint registers the account in MAM; it does not create the account or change its MT5 permissions.

When you register an existing account as a leader (`can_be_leader=true`), the platform automatically imports its previous MT5 trades. This makes its metrics and historical results available from the start.

The account can be retrieved and edited during the import, but it cannot receive new subscribers until history synchronization is complete.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mt5_login": "139682",
  "name": "Imported leader",
  "currency": "USD",
  "account_mode": "HEDGING",
  "can_be_leader": true,
  "can_be_follower": false,
  "status": "ACTIVE"
}
```

> [!NOTE]
>
> If the account is registered only as a follower (`can_be_leader=false`), it does not require a history import and becomes available immediately.

If you later enable a follower account to act as a leader through `PATCH /api/v1/mam/accounts/{account_login}`, the history import starts automatically at that time. Editing an account that was already a leader does not import its history again. See the [history synchronization guide](https://mam-api.exuratech.com/guides/history-sync.md) to review progress or repeat the process manually.

## Available synchronization operations

| Need | Endpoint |
| - | - |
| Import a leader's complete trade history or a specific range | `POST /api/v1/mam/accounts/{account_login}/history-sync` |
| Retrieve the progress of that import | `GET /api/v1/mam/accounts/{account_login}/history-sync` |
| Reconcile deposits or withdrawals made directly in MT5 | `POST /api/v1/mam/accounts/{account_login}/balance-transactions/sync-mt5` |

Balance movement synchronization accepts `lookback_hours` from `1` to `2160`, or a `from_at`/`to_at` interval. It is idempotent per MT5 deal: a second run skips movements that have already been recorded.

## Fund and withdraw

Financial operations require a stable `idempotency_key`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": 1000,
  "idempotency_key": "deposit:crm-transaction-84922"
}
```

* Deposit: `POST /api/v1/mam/accounts/{account_login}/deposit`
* Withdrawal: `POST /api/v1/mam/accounts/{account_login}/withdraw`
* Audit: `GET /api/v1/mam/accounts/{account_login}/balance-transactions`

> [!WARNING]
>
> Use `sync-mt5` for controlled reconciliation of external movements. New operations must go through the deposit and withdrawal endpoints to preserve idempotency and traceability.

A follower withdrawal first charges any accrued performance fee. Withdrawing a leader's PAYMENT balance uses a different endpoint.

## Batch queries

To avoid long query strings, `POST /api/v1/mam/accounts/query` accepts up to 1,000 logins in the body and preserves the semantics of the general listing endpoint.

## Copy-trading requirements

* Status `ACTIVE`.
* `account_mode="HEDGING"`.
* `can_be_leader=true` to originate trades.
* `can_be_follower=true` to receive trades.


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