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

# Accounts

> Public endpoints for MAM accounts, metrics, and balance movements.

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/v1/mam/accounts` | Lists accounts with filters and pagination. |
| `POST` | `/api/v1/mam/accounts/query` | Retrieves a batch of logins through the body. |
| `POST` | `/api/v1/mam/accounts/add` | Registers an account that already exists in MT5. |
| `POST` | `/api/v1/mam/accounts/create` | Creates an MT5 account and registers it in MAM. |
| `GET` | `/api/v1/mam/accounts/{account_login}` | Retrieves an account by login. |
| `PATCH` | `/api/v1/mam/accounts/{account_login}` | Updates explicitly sent fields. |
| `GET` | `/api/v1/mam/accounts/{account_login}/metrics` | Retrieves balance, equity, margin, and free margin from MT5. |
| `POST` | `/api/v1/mam/accounts/{account_login}/deposit` | Credits balance idempotently. |
| `POST` | `/api/v1/mam/accounts/{account_login}/withdraw` | Withdraws after resolving accrued fees. |
| `GET` | `/api/v1/mam/accounts/{account_login}/balance-transactions` | Lists the account's balance history. |
| `POST` | `/api/v1/mam/accounts/{account_login}/balance-transactions/sync-mt5` | Reconciles balance movements made directly in MT5. |
| `POST` | `/api/v1/mam/accounts/{account_login}/history-sync` | Requests synchronization for an imported leader. |
| `GET` | `/api/v1/mam/accounts/{account_login}/history-sync` | Retrieves the most recent history synchronization. |

## Listing filters

The listing supports `status`, `can_be_leader`, `can_be_follower`, search, cursor or page, limit, and sorting. Use the `/query` endpoint when you need to send a large set of `account_logins`.

## Register existing accounts

`POST /accounts/add` registers an account that already exists in MT5. Behavior depends on the requested role:

| Input | Result |
| - | - |
| `can_be_leader=true` | Registers the account and automatically starts importing its previous trades. |
| `can_be_leader=false` | Registers the account as a follower and makes it available immediately. |

The import runs in the background. Retrieve `/history-sync` and wait for `COMPLETED` before subscribing investors to the leader.

## Promote to leader

`PATCH /accounts/{account_login}` automatically starts the history import when `can_be_leader` changes from `false` to `true`. Updating other fields on an account that was already a leader does not import history again.

`POST /accounts/create` does not start a history import, even when the new account is registered as a leader, because it has just been created in MT5 and has no previous trades.

## Sensitive responses

`GET /accounts/{account_login}` and `POST /accounts/create` may include stored or generated credentials. Do not send these responses to a web client or retain them in logs.

## Financial operations

The shared body for deposits and withdrawals is:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": 250,
  "idempotency_key": "withdrawal:crm-transaction-10084"
}
```

## History synchronization

The body of `POST /accounts/{account_login}/history-sync` accepts:

| Field | Purpose |
| - | - |
| `from_at` | Optional start in ISO 8601. |
| `to_at` | Optional end in ISO 8601; must be later than `from_at`. |
| `required_before_subscription` | When `true`, blocks eligibility and creation until `COMPLETED`. |
| `requested_by` | Optional reference for the requesting operator or system. |

Without dates, `sync_mode` is `FULL`; with at least one date it is `RANGE`. The response includes `status`, `cursor_at`, `last_deal_id`, `attempt_count`, `deals_seen`, `deals_created`, `error_message`, `started_at`, and `completed_at`.

## MT5 balance reconciliation

`POST /accounts/{account_login}/balance-transactions/sync-mt5` accepts `lookback_hours` as a query parameter and optional `from_at`/`to_at`. It records deposits as `EXTERNAL_DEPOSIT` and withdrawals as `EXTERNAL_WITHDRAWAL`, with a reference to the MT5 deal. Already reconciled deals are skipped.


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