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

# Cascade fees

> Agreement management, charge history, statuses, and operational summaries.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/v1/mam/cascade-fee-agreements` | Activates a direct cascade-fee agreement. |
| `GET` | `/api/v1/mam/cascade-fee-agreements` | Lists agreements with filters and cursor pagination. |
| `GET` | `/api/v1/mam/cascade-fee-agreements/{downstream_master_login}` | Retrieves the agreement assigned to a downstream master. |
| `PATCH` | `/api/v1/mam/cascade-fee-agreements/{downstream_master_login}` | Updates the rate of an active agreement. |
| `DELETE` | `/api/v1/mam/cascade-fee-agreements/{downstream_master_login}` | Deactivates the agreement. |
| `GET` | `/api/v1/mam/cascade-fees/charges` | Lists generated charges and pending operations. |
| `GET` | `/api/v1/mam/cascade-fees/charges/{charge_id}` | Retrieves one charge. |
| `GET` | `/api/v1/mam/cascade-fees/summary` | Summarizes charge counts and amounts by currency. |

All endpoints require the bearer API key used by the rest of the MAM integration.

## Agreement creation

`POST /api/v1/mam/cascade-fee-agreements`

| Body field | Type | Rules |
| - | - | - |
| `upstream_master_login` | string | Required numeric MT5 login of the direct parent master. |
| `downstream_master_login` | string | Required numeric MT5 login of the child master. |
| `fee_rate` | decimal | Greater than `0` and no greater than `1`; `0.20` means 20%. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "upstream_master_login": "139682",
  "downstream_master_login": "146493",
  "fee_rate": 0.20
}
```

The request returns `201` with the agreement:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": 18,
  "upstream_allocation_id": 64,
  "upstream_leader_account_id": 31,
  "upstream_master_login": "139682",
  "upstream_payment_login": "139683",
  "downstream_leader_account_id": 42,
  "downstream_master_login": "146493",
  "downstream_payment_login": "146494",
  "fee_rate": 0.20,
  "status": "ACTIVE",
  "effective_from": "2026-09-01T14:30:00Z",
  "effective_to": null,
  "created_at": "2026-09-01T14:30:00Z",
  "updated_at": "2026-09-01T14:30:00Z"
}
```

Activation validates the live direct allocation and both PAYMENT-account currencies. Repeating the exact active configuration returns the existing agreement without creating a duplicate.

## Agreement requirements

| Requirement | Validation result when it is not met |
| - | - |
| Both accounts exist and are different MAM masters. | `404` for a missing account or `409` for an invalid master role. |
| Both accounts and leader profiles are `ACTIVE`. | `409`. |
| Downstream can be a follower and uses `CASCADE` propagation. | `409`. |
| One active direct allocation connects upstream to downstream. | `409`. |
| Each master has a distinct dedicated PAYMENT account. | `409`. |
| Both PAYMENT accounts use the same currency. | `409`; the response identifies both currencies. |
| MT5 currency validation is available. | `502` when the validation cannot be completed. |

One downstream master can have only one agreement. To assign a different parent, deactivate the current agreement and then activate the new one.

## List and retrieve agreements

`GET /api/v1/mam/cascade-fee-agreements` accepts:

| Query parameter | Values |
| - | - |
| `status` | `ACTIVE` or `INACTIVE`. |
| `upstream_master_login` | Exact operational MT5 login. |
| `downstream_master_login` | Exact operational MT5 login. |
| `cursor` | Returns agreement IDs lower than the cursor. |
| `limit` | From `1` to `500`; default `100`. |

The response contains `items`, `next_cursor`, and `has_more`, ordered from newest ID to oldest.

Use `GET /api/v1/mam/cascade-fee-agreements/{downstream_master_login}` to retrieve the active or inactive agreement record for one downstream master.

## Update and deactivate

`PATCH /api/v1/mam/cascade-fee-agreements/{downstream_master_login}` accepts only:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "fee_rate": 0.15
}
```

The agreement must be active and must still match the active direct allocation. The new rate applies only to charges created after the update.

`DELETE /api/v1/mam/cascade-fee-agreements/{downstream_master_login}` changes the agreement to `INACTIVE` and sets `effective_to`. It is safe to repeat for an inactive agreement.

> [!WARNING]
>
> Deactivation does not cancel `PENDING`, `CLAIMED`, or `DEBITED` charges that were created while the agreement was active.

## List charges

`GET /api/v1/mam/cascade-fees/charges` accepts:

| Query parameter | Values |
| - | - |
| `status` | Any cascade-fee charge status listed below. |
| `source_type` | `PERFORMANCE_FEE_BATCH` or `PERFORMANCE_FEE_SETTLEMENT`. |
| `upstream_master_login` | Exact operational MT5 login. |
| `downstream_master_login` | Exact operational MT5 login. |
| `currency` | Three-letter currency code. |
| `from_at` | Inclusive creation time in ISO 8601. |
| `to_at` | Exclusive creation time in ISO 8601; must be later than `from_at`. |
| `cursor` | Returns charge IDs lower than the cursor. |
| `limit` | From `1` to `500`; default `100`. |

The response is ordered from newest ID to oldest and contains `items`, `next_cursor`, and `has_more`.

### Source types

| Value | Meaning |
| - | - |
| `PERFORMANCE_FEE_BATCH` | The downstream master received one consolidated credit containing multiple performance-fee settlements. |
| `PERFORMANCE_FEE_SETTLEMENT` | The downstream master received one performance-fee settlement directly. |

### Charge statuses

| Status | Meaning |
| - | - |
| `PENDING` | Created and waiting for settlement; the amount is reserved. |
| `CLAIMED` | Being processed; the amount remains reserved. |
| `DEBITED` | Removed from the downstream PAYMENT account; upstream credit is pending or being retried. |
| `EXECUTED` | Downstream debit and upstream credit are both confirmed. |
| `FAILED` | Processing failed before a confirmed debit and requires operational review. |
| `UNCOLLECTED` | The downstream PAYMENT account did not have enough balance to collect the fee. |
| `CANCELLED` | The charge was cancelled and will not be processed. |

`PENDING`, `CLAIMED`, and `DEBITED` are actionable states. They also prevent deletion of either related MAM account until the obligation reaches a terminal state.

## Charge response

Use `GET /api/v1/mam/cascade-fees/charges/{charge_id}` for a single item. A charge snapshots the agreement and performance-fee credit that produced it:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": 91,
  "source_type": "PERFORMANCE_FEE_BATCH",
  "source_id": 73,
  "agreement_id": 18,
  "upstream_allocation_id": 64,
  "upstream_leader_account_id": 31,
  "upstream_master_login": "139682",
  "downstream_leader_account_id": 42,
  "downstream_master_login": "146493",
  "upstream_payment_login": "139683",
  "downstream_payment_login": "146494",
  "currency": "USD",
  "gross_pf_amount": 200.00,
  "fee_rate": 0.20,
  "fee_amount": 40.00,
  "status": "EXECUTED",
  "debit_attempts": 1,
  "credit_attempts": 1,
  "claimed_at": null,
  "claimed_by": null,
  "next_attempt_at": null,
  "downstream_debit_mt5_deal_id": 91001,
  "upstream_credit_mt5_deal_id": 91002,
  "error_message": null,
  "debited_at": "2026-09-01T14:30:04Z",
  "executed_at": "2026-09-01T14:30:05Z",
  "created_at": "2026-09-01T14:30:02Z",
  "updated_at": "2026-09-01T14:30:05Z"
}
```

`gross_pf_amount` is the performance fee credited to the downstream master. `fee_amount` is that amount multiplied by the snapshotted `fee_rate`, rounded to two decimals.

## Operational summary

`GET /api/v1/mam/cascade-fees/summary` accepts `upstream_master_login`, `downstream_master_login`, `currency`, `from_at`, and `to_at`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total_count": 9,
  "actionable_count": 2,
  "oldest_actionable_at": "2026-09-01T14:30:02Z",
  "currencies": [
    {
      "currency": "USD",
      "pending_count": 1,
      "claimed_count": 0,
      "debited_count": 1,
      "executed_count": 6,
      "failed_count": 0,
      "uncollected_count": 1,
      "cancelled_count": 0,
      "reserved_amount": 40.00,
      "awaiting_credit_amount": 25.00,
      "executed_amount": 360.00
    }
  ]
}
```

| Summary field | Meaning |
| - | - |
| `reserved_amount` | Total in `PENDING` or `CLAIMED`, still reserved in downstream PAYMENT accounts. |
| `awaiting_credit_amount` | Total already debited but not yet credited upstream. |
| `executed_amount` | Total successfully transferred. |

> [!NOTE]
>
> The agent claim and acknowledgement routes are internal settlement interfaces and are not part of the customer integration. Cascade-fee events are also not sent to the public MAM webhook.


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