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

> Validate, create, activate, update, and terminate copy-trading relationships.

Each allocation relates two existing accounts: `leader_login` originates trades and `follower_login` receives them.

## Before creating an allocation

* Both accounts are `ACTIVE` and use `HEDGING`.
* The leader has `can_be_leader=true` and an active profile.
* The follower has `can_be_follower=true`.
* No live allocation exists for the same pair.
* The new relationship does not create a cycle.
* The follower meets `min_deposit`.

Validate the deposit through `POST /api/v1/mam/allocations/subscription-eligibility`. This check does not create resources.

## Allocation modes and mode\_parameter

| Mode | `mode_parameter` |
| - | - |
| `FIXED` | Required. Fixed number of lots requested for the follower. |
| `SCALED` | Required. Direct multiplier of the leader's volume. |
| `EQUITY` | Optional. Multiplier of the equity ratio; `null` is equivalent to `1`. |
| `EQUITY_ROUND_DOWN` | Optional. Multiplier of the equity ratio rounded down; `null` is equivalent to `1`. |
| `BALANCE` | Optional. Multiplier of the balance ratio; `null` is equivalent to `1`. |

When sent, `mode_parameter` must be greater than `0`. A `0.5` multiplier halves the result, while `2` doubles it.

## Leader limit

`max_active_leaders_per_follower` is the maximum number of active subscriptions a follower may have when subscribing to a master. For example, if `max_active_leaders_per_follower=2`, a follower with two or more active subscriptions cannot subscribe. When omitted, the system uses `3` by default.

## Statuses

| Status | Meaning |
| - | - |
| `PAUSED` | Registered, with no new trades copied. |
| `ACTIVE` | Copy trading enabled. |
| `STOPPING` | Controlled termination in progress. |
| `CANCELLED` | Relationship terminated. |
| `ERROR` | Requires operational review. |

> [!WARNING]
>
> Pausing an allocation with open trades is not recommended. If the master closes a trade after follower accounts copied it and the allocation was paused, MAM will not close those follower trades. They remain open even if the allocation later returns to `ACTIVE`.

## Retrieve changes incrementally

Use `GET /api/v1/mam/allocations/events` when your CRM needs to retrieve new allocations and status changes without downloading every allocation again.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://mam-api.example.com/api/v1/mam/allocations/events?after_id=0&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The response contains events in ascending order. Persist the last processed `id` and send it as `after_id` in the next request. If `has_more=true`, continue immediately with `next_cursor` until the pending page is empty.

Common events are `CREATED`, `UPDATED`, and `STATUS_CHANGED`; `payload_json` retains a snapshot of the allocation associated with the change.

> [!NOTE]
>
> This feed supports reconciliation and recovery through polling. It does not replace the `mam.allocation.terminated` webhook, which specifically reports a termination that has already been processed.

## Unsubscription

Use `POST /api/v1/mam/allocations/{allocation_id}/unsubscribe`.

* `KEEP_OPEN`: leaves positions open in MT5 but outside allocation management.
* `CLOSE_ON_UNSUBSCRIBE`: coordinates the closing of linked positions before completion.

> [!WARNING]
>
> Do not change an allocation directly to `CANCELLED` to initiate an unsubscription.


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