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

# Subscription endpoints

> Contracts for assigning, unassigning, and querying PAMM relationships.

## Assign an Investor

`POST /api/v1/investor/assign`

| Body field | Type | Required | Description |
| - | - | - | - |
| `master_login` | string | Yes | Master trading MT5 login. |
| `investor_login` | string | Yes | Investor MT5 login. |
| `perf_fee` | object or null | No | Omit or send null to inherit the Master's default when assigning. |
| `perf_fee.rate` | decimal | Yes, if the object is supplied | Rate from `0` to `1`; zero inherits the Master's default. |
| `perf_fee.enabled` | boolean | No | Defaults to `true`. Explicit `false` disables collection, including when inheriting the default. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "master_login": "146512",
  "investor_login": "146600",
  "perf_fee": {
    "rate": 0.30,
    "enabled": true
  }
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": 980,
  "master_id": 375,
  "investor_id": 410,
  "status": "ACTIVE",
  "in_pool": true,
  "started_at": "2026-07-21T13:20:00",
  "balance_baseline_op_id": 445001,
  "ended_at": null,
  "created_at": "2026-07-21T13:20:00"
}
```

The Investor balance must meet the Master's `min_deposit`, the Investor cannot have open positions, and the initial mirror can still be queued after the response.

### Fee initialization rules

| Submitted value | Stored rate | Stored enabled flag |
| - | - | - |
| `perf_fee` omitted or null | Master's `default_perf_fee` | `true` if the default is positive, otherwise `false`. |
| `rate > 0` | Submitted rate | Submitted `enabled`, or `true` if omitted. |
| `rate = 0`, Master default positive | Master's `default_perf_fee` | Submitted `enabled`, or `true` if omitted. |
| `rate = 0`, Master default zero | `0` | `false`. |

When `perf_fee` is supplied as an object, `rate` is still required: an empty object or an object with only `enabled` is invalid. A zero rate requests inheritance, not an opt-out; use `{"rate": 0, "enabled": false}` to inherit the rate but disable collection. After assignment, use `/investor/perf-fee/update` to change an existing Investor. Later Master default updates do not change existing Investor settings or reset their HWM. Verify the stored result through the Investor fee read endpoint; the assignment response does not contain the effective rate.

To inherit the Master default without an explicit fee object:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "master_login": "146512",
  "investor_login": "146600"
}
```

> [!NOTE]
>
> Optional `perf_fee` and inherited-rate opt-out require the updated PAMM API deployment. Older versions require the object and ignore `enabled=false` when `rate=0`. Check the target deployment's OpenAPI contract before using the new behavior.

### Assignment response fields

| Field | Type | Meaning |
| - | - | - |
| `id` | integer | Subscription ID. |
| `master_id`, `investor_id` | integer | Internal account IDs, not MT5 logins. |
| `status` | string | `ACTIVE` on successful assignment. |
| `in_pool` | boolean | Whether the relationship participates in the pool. |
| `started_at`, `created_at` | datetime | Subscription start and record creation. |
| `balance_baseline_op_id` | integer or null | MT5 balance-operation baseline used for synchronization. |
| `ended_at` | datetime or null | Relationship end, null while active. |

## Unassign an Investor

`POST /api/v1/subscriptions/unassign`

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `master_login` | string | Yes | Active Master MT5 login. |
| `investor_login` | string | Yes | Investor MT5 login. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST \
  "https://pamm-api.example.com/api/v1/subscriptions/unassign?master_login=146512&investor_login=146600" \
  -H "Authorization: Bearer YOUR_CRM_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "subscription": {
    "id": 980,
    "master_login": "146512",
    "investor_login": "146600",
    "status": "PAUSED",
    "in_pool": false,
    "started_at": "2026-07-21T13:20:00",
    "ended_at": null
  },
  "payout_enqueued": true,
  "mt5_transfer_id": 7410,
  "amount": -980.0
}
```

The operation can be blocked by open Master positions. Pending performance fees settle first. If mirrored balance remains, poll until `CANCELLED`; a second command while `PAUSED` returns `409`.

### Unassignment response fields

| Field | Type | Meaning |
| - | - | - |
| `subscription` | object | Updated relationship identity and state. |
| `subscription.id` | integer | Subscription ID. |
| `subscription.master_login`, `investor_login` | string | MT5 relationship logins. |
| `subscription.status`, `in_pool` | string, boolean | Exit state and pool participation. |
| `subscription.started_at`, `ended_at` | datetime, datetime or null | Relationship dates. |
| `payout_enqueued` | boolean | Whether a mirrored capital-removal transfer was queued. |
| `mt5_transfer_id` | integer or null | Queued transfer identifier; not an MT5 deal ID. |
| `amount` | number | Signed mirrored capital movement; this does not mean the transfer has settled. |

## List subscriptions

`GET /api/v1/info/subscriptions`

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `master_login` | string | No | Filter by Master MT5 login. |
| `investor_login` | string | No | Filter by Investor MT5 login. |
| `status` | enum | No | `ACTIVE`, `PAUSED`, or `CANCELLED`. |
| `search` | string | No | Searches Master/Investor login or name. |
| `search_side` | enum | No | `master` or `investor`; omitted searches both. |
| `limit` | integer | No | Range `1..200`; truncates the flat array when `page` is omitted. |
| `page` | integer | No | Minimum `1`; when present, switches the response to a paginated object. |
| `page_size` | integer | No | Defaults to `50`; range `1..200`; used with `page`. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": 980,
    "status": "ACTIVE",
    "in_pool": true,
    "started_at": "2026-07-21T13:20:00",
    "ended_at": null,
    "master_login": "146512",
    "investor_login": "146600"
  }
]
```

### Subscription list response fields

Without `page`, the response is an array. Each record includes `id`, `status`, `in_pool`, `started_at`, `ended_at`, `master_login`, `investor_login`, `master_name`, and `investor_name`. Names can be null. The effective PF is not included; read the Investor fee configuration separately.

With `page=1&page_size=50`, the response is:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 50,
  "has_more": false
}
```

`items` contains the same relationship records; `total` is the matching count, `page` and `page_size` describe the requested window, and `has_more` indicates another page.

## List active Investors for a Master

`GET /api/v1/info/master/{master_login}/investors`

| Path parameter | Type | Required | Meaning |
| - | - | - | - |
| `master_login` | string | Yes | Master trading MT5 login. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": 410,
    "mt5_login": "146600",
    "name": "Investor Demo"
  }
]
```

Only subscriptions with `ACTIVE`, `in_pool=true`, and no `ended_at` are included.

The response is an array of Investor `id` (internal integer), `mt5_login` (string), and `name` (string).

## Resolve the active Master

`GET /api/v1/info/investor/{investor_login}/master`

| Path parameter | Type | Required | Meaning |
| - | - | - | - |
| `investor_login` | string | Yes | Investor MT5 login. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "master_login": "146512",
  "name": "Momentum Weekly",
  "started_at": "2026-07-21T13:20:00"
}
```

When there is no active Master, the response fields are `null`.

`master_login` is the trading login, `name` the Master alias, and `started_at` the relationship start time. This route does not return the fee rate.

> [card] [Previous: Investor endpoints](https://pamm-api.exuratech.com/reference/investors.md)
>
> Return to Investor account contracts.

> [card] [Next: Financial operations](https://pamm-api.exuratech.com/reference/operations.md)
>
> Open deposit, withdrawal, and balance contracts.


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