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

# Configure cascade fees

> Share a downstream master's performance-fee income with its direct upstream master.

A cascade fee lets an upstream master receive a percentage of the performance fees earned by a direct downstream master.

It is separate from trade propagation:

| Configuration | What it controls |
| - | - |
| `propagation_mode="CASCADE"` | Allows a master that is also a follower to copy upstream trades to its own followers. |
| Cascade fee agreement | Shares part of that downstream master's performance-fee income with its direct upstream master. |

## Example hierarchy

Consider this direct hierarchy:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Master A (upstream)
  └── Master B (downstream and follower of A)
        └── Investor C (follower of B)
```

If Master B receives `200.00 USD` in performance fees from its followers and the agreement with Master A has `fee_rate=0.20`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Cascade fee = 200.00 × 0.20 = 40.00 USD
```

The system debits `40.00 USD` from Master B's PAYMENT account and credits `40.00 USD` to Master A's PAYMENT account.

> [!NOTE]
>
> The fee is calculated on the performance fee actually credited to Master B. It is not calculated on Investor C's profit, Master B's balance, or trading volume.

Cascade-fee credits do not generate another cascade fee. Each agreement applies only to the regular performance-fee income of its direct downstream master.

## Requirements

Before activating an agreement, confirm all of the following:

* The upstream and downstream accounts are different, active MAM masters.
* The downstream master is enabled as a follower and uses `propagation_mode="CASCADE"`.
* An active direct allocation exists from the upstream master to the downstream master.
* Both masters have valid dedicated PAYMENT accounts.
* The two PAYMENT accounts are different and use the same currency.
* The downstream master does not already have another active cascade-fee agreement.

The rate must be greater than `0` and no greater than `1`. Send `0.20` for 20%.

## Activate an agreement

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://mam-api.example.com/api/v1/mam/cascade-fee-agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upstream_master_login": "139682",
    "downstream_master_login": "146493",
    "fee_rate": 0.20
  }'
```

An identical request for the same active relationship and rate is safe to repeat. To change the upstream parent, deactivate the existing agreement first and then activate the new direct relationship.

## When the charge is created

The cascade fee does not have an independent schedule. A charge is created only after the downstream master receives a performance-fee credit.

This means it follows the downstream master's performance-fee collection events:

| Performance-fee trigger | Cascade-fee behavior |
| - | - |
| Calendar cutoff | Created after the resulting performance-fee credit is confirmed. |
| Follower withdrawal | Created if the withdrawal crystallizes and credits a performance fee. |
| Allocation unsubscription | Created if termination crystallizes and credits a performance fee. |
| `performance_fee_period="OFF"` | No performance fee is collected, so no cascade fee is created. |

The API snapshots the credited performance-fee amount and the agreement rate:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
fee_amount = gross_pf_amount × fee_rate
```

The final amount is rounded to the two-decimal precision used for MT5 balance operations.

## Settlement lifecycle

Cascade-fee settlement is asynchronous:

1. A charge is created after the downstream performance-fee credit.
2. The amount is reserved in the downstream PAYMENT account.
3. The downstream PAYMENT account is debited.
4. The upstream PAYMENT account is credited.
5. The charge reaches `EXECUTED`.

If the upstream credit needs to be retried after the downstream debit, the charge remains `DEBITED`. The debit is not repeated.

## PAYMENT balance and withdrawals

Retrieve the downstream master's PAYMENT balance with its operational login:

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

The response distinguishes the MT5 amount from the amount available through the MAM API:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "master_login": "146493",
  "payment_account_login": "146494",
  "balance": 500.00,
  "equity": 500.00,
  "free_margin": 500.00,
  "credit": 0.00,
  "mt5_withdrawable": 500.00,
  "reserved_cascade_fee_amount": 40.00,
  "withdrawable": 460.00,
  "currency": "USD"
}
```

Always use `withdrawable`. It subtracts pending cascade-fee obligations from the amount reported as withdrawable by MT5.

> [!WARNING]
>
> Do not withdraw directly from the PAYMENT account in MT5. An external withdrawal can consume reserved funds and cause a cascade fee to become `UNCOLLECTED`.

## Update or deactivate

Update the rate for future charges:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://mam-api.example.com/api/v1/mam/cascade-fee-agreements/146493" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fee_rate": 0.15}'
```

Deactivate the agreement:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X DELETE "https://mam-api.example.com/api/v1/mam/cascade-fee-agreements/146493" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The path identifies the downstream master. Updating the rate affects only charges created afterward. Deactivation prevents future charges but does not cancel charges that already exist.

## Reconcile charges

List charge history with filters such as master login, status, currency, and date:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G "https://mam-api.example.com/api/v1/mam/cascade-fees/charges" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "upstream_master_login=139682" \
  --data-urlencode "status=EXECUTED" \
  --data-urlencode "currency=USD" \
  --data-urlencode "from_at=2026-09-01T00:00:00Z" \
  --data-urlencode "to_at=2026-10-01T00:00:00Z" \
  --data-urlencode "limit=100"
```

Use `GET /api/v1/mam/cascade-fees/summary` for counts and amounts grouped by currency. The complete filters, response fields, and status definitions are available in the [cascade-fee reference](https://mam-api.exuratech.com/reference/cascade-fees.md).

> [!NOTE]
>
> Cascade-fee processing events are currently internal service events. They are not delivered to the customer webhook registered through `/api/v1/mam/webhooks`.


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