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

# Reconcile performance fees

> Understand calendar periods, collection triggers, credits, and follower-level reconciliation.

Performance fees are calculated per allocation over profit above its high-water mark (HWM). The fee is debited from the follower and credited to the leader's separate PAYMENT account.

## Calendar-based periods

`performance_fee_period` is configured on the leader profile. Periods are aligned to the UTC calendar; they do not begin when the leader or allocation was created.

In the current ExuraCopy configuration, a closed period becomes eligible for scheduled crystallization five minutes after its calendar boundary. MT5 settlement is asynchronous and may complete after that eligibility time.

| Value | Calendar window | Scheduled cutoff in UTC | Example |
| - | - | - | - |
| `OFF` | No period | No automatic or lifecycle collection | Performance fee collection is disabled. |
| `MINUTELY` | One calendar minute | Every minute boundary, eligible five minutes later | `19:36:00`–`19:37:00`, eligible from `19:42:00`. |
| `HOURLY` | One calendar hour | At minute `00`, eligible five minutes later | `18:00`–`19:00`, eligible from `19:05`. |
| `DAILY` | One UTC day | `00:00`, eligible at `00:05` | July 1 from `00:00` to July 2 at `00:00`. |
| `WEEKLY` | Sunday to Sunday | Sunday `00:00`, eligible at `00:05` | June 21 `00:00` to June 28 `00:00`. |
| `SEMIMONTHLY` | Days 1–16 or day 16–next month | Day 1 and day 16 at `00:00`, eligible at `00:05` | July 1–16, then July 16–August 1. |
| `MONTHLY` | One calendar month | First day of the next month at `00:00`, eligible at `00:05` | June 1 `00:00` to July 1 `00:00`. |

> [!WARNING]
>
> `SEMIMONTHLY` means two fixed calendar windows. It is not “every 15 days” from the subscription date. `WEEKLY` closes on Sunday at `00:00 UTC`.

## Collection outside the scheduled cutoff

An applicable pending fee is also crystallized before either of these lifecycle operations:

| Trigger | Behavior |
| - | - |
| Follower withdrawal | The fee is processed before the available withdrawal amount is finalized. |
| Allocation unsubscription | The fee is processed as part of the controlled termination workflow. |

These triggers do not wait for the next calendar cutoff. When the period is `OFF`, no performance fee is collected.

## How the HWM affects collection

* A fee is charged only when cumulative eligible profit is above the stored HWM.
* Losses or profit below the HWM do not generate a new fee.
* After collection, the HWM advances so the same profit is not charged twice.
* A calendar cutoff with no chargeable profit can still be recorded as processed.

## Performance fees in a cascade hierarchy

When a master is also the downstream follower of another master, a separate cascade-fee agreement can share part of its performance-fee income with its direct upstream master. The cascade fee is created only after the downstream performance-fee credit is confirmed; it is not another charge on the investor's profit.

See [Configure cascade fees](https://mam-api.exuratech.com/guides/cascade-fees.md) for the hierarchy requirements, calculation, PAYMENT-account reservation, and reconciliation endpoints.

## Retrieve the PAYMENT balance

Use the leader's operational login, not the PAYMENT login:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://mam-api.example.com/api/v1/mam/leaders/139682/payment-account/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The response includes `balance`, `equity`, `free_margin`, `credit`, `mt5_withdrawable`, `reserved_cascade_fee_amount`, and `withdrawable`. Use `withdrawable` to authorize a withdrawal because it excludes MT5 credit and any pending cascade-fee obligation.

## Retrieve received credits

`GET /api/v1/perf-fee/transactions` requires `master_login` and accepts `from_at`, `to_at`, `limit`, and `cursor`.

For a grouped credit, `investor_mt5_login` may be `null`. Use the transaction's `run_id` to retrieve its composition.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G "https://mam-api.example.com/api/v1/perf-fee/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "master_login=139682" \
  --data-urlencode "from_at=2026-07-01T00:00:00Z" \
  --data-urlencode "to_at=2026-08-01T00:00:00Z" \
  --data-urlencode "limit=50"
```

## Break down by follower

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /api/v1/perf-fee/master/{master_login}/investor-payments?run_id={run_id}
```

The sum of `amount` across `EXECUTED` items for a `run_id` must match the corresponding consolidated credit. This detail is the correct source for distributing a fee across followers, sponsors, or an IB network.

## Withdraw earnings

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://mam-api.example.com/api/v1/mam/leaders/139682/payment-account/withdraw" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "idempotency_key": "payment-withdrawal:crm-84721"
  }'
```

The `idempotency_key` must contain between 8 and 120 characters. Repeating exactly the same request does not debit MT5 again.

> [!WARNING]
>
> Do not withdraw directly from MT5 or manually deposit into the operational account to simulate fees. Use the published endpoints to preserve traceability.


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