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

# From MT5 accounts to an active allocation

> A broker backend walkthrough with independent creation, promotion and subscription.

Send requests from your backend over HTTPS. Use `Authorization: Bearer <broker API key>` and `Content-Type: application/json`. Never ship the key in browser or mobile code. Paths below are relative to `/api/v1/mamx`. Omit `server`: the instance identifies its own MT5 server. Example logins and groups are placeholders; use actual MT5 responses.

## 1. Create or import a trading account

**Create** when no MT5 login exists. The minimum body for `POST /accounts/create` creates an investor:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "request_key": "crm-investor-0001",
  "platform_group": "demo\\MAMX",
  "name": "Example investor"
}
```

Use an existing MT5 hedging group, not a mask. For a **master**, use a separate request key and name, and add `"can_be_leader": true` and `"can_be_follower": false`. The default currency is USD with two decimal places; for other MT5 group settings, supply the matching currency or precision. A confirmed creation returns **201**, `mt5_login` and initial credentials. Never log this response.

**Import** when the login already exists. Send `POST /accounts/add`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mt5_login": "100002"
}
```

For a master, add the same two role flags as for creation. The agent reads the exact MT5 user and group. The user must be enabled and in a hedging group; leaders must allow trading, investors must already have trading disabled. Missing users are rejected. Registration does not create an MT5 account, change credentials or move funds.

Both endpoints can return **202** while the agent verifies or provisions the account. Follow `status_url` or poll `GET /operations/{operation_id}`. For password delivery after asynchronous creation, see [Operations](https://mamx-api.exuratech.com/guides/operations.md). Do not interpret a pending login as proof that registration succeeded.

## 2. Create the leader profile and payment account

Send `POST /leaders` with the **registered trading login**, not the account's internal ID:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "request_key": "crm-leader-0001",
  "account_login": "100001",
  "strategy_name": "Example strategy"
}
```

The default performance fee is 20%, charged monthly. Omit `payment_account_login` to create a payment account in the master group. To link an existing one, add e.g. `"payment_account_login":"100003"`. The agent checks MT5. The login must be distinct, unused for another MAMX role, trading-disabled, and match the master's currency and currency precision. A bad supplied login **does not** trigger fallback creation.

The response is **202**. Wait for `DONE`; store `evidence.result.master_id` (the **leader ID**) and `payment_account_login` from the result. Existing payment accounts retain their own credentials.

## 3. Fund and subscribe the investor

Registration does not fund any account. The master can register with no deposit, but proportional settlement needs a valid positive denominator. See [Funding](https://mamx-api.exuratech.com/guides/funding-and-fees.md).

Send `POST /allocations`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "leader_login": "100001",
  "follower_login": "100002"
}
```

This creates an active balance-based allocation. For equity-based allocation, add `"allocation_mode": "EQUITY"`. For safe retries, add an `idempotency_key` and persist it before sending. Replaying the same key and payload returns the current allocation without reactivating a cancelled one. Save the returned allocation `id`.

## 4. Update or end the relationship

* `PATCH /accounts/{account_login}`: edit the name or eligible role with an `Idempotency-Key` header. A role change requires no conflicting master, allocation or payment links and no live positions or pending orders. It does not move the account to another MT5 group.
* `PATCH /leaders/{leader_id}`: edit the strategy name, fee rate or fee period. A term change crystallizes accrued fees under the old terms; a rename alone does not. Use an `Idempotency-Key` header.
* `PATCH /allocations/{allocation_id}`: update allocation settings. Completed imports and already established partial chains are not rewritten.
* `POST /allocations/{allocation_id}/unsubscribe`: stop future participation and settle outstanding obligations. This is **not** a withdrawal. If a captured import must finish first, wait and retry after the conflict clears.
* `DELETE /accounts/{account_login}`: remove the account **from MAMX**, not from MT5. It does not withdraw funds, fabricate exit trades or erase history. Deleting a master ends its allocations but does not delete its investors. Track any `final_fee_ids` until paid; repeated deletion does not charge again.

The newest `/accounts/add` and manual payment option require the matching API **and agent** build. An older instance's Swagger may not advertise them.


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