Cascade fees

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

{
  "upstream_master_login": "139682",
  "downstream_master_login": "146493",
  "fee_rate": 0.20
}

The request returns 201 with the agreement:

{
  "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:

{
  "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.

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:

{
  "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.

{
  "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.

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.

Conventions

Resources

Endpoints

Agreement creation

Agreement requirements

List and retrieve agreements

Update and deactivate

List charges

Source types

Charge statuses

Charge response

Operational summary

​Endpoints

​Agreement creation

​Agreement requirements

​List and retrieve agreements

​Update and deactivate

​List charges

​Source types

​Charge statuses

​Charge response

​Operational summary

Endpoints

Agreement creation

Agreement requirements

List and retrieve agreements

Update and deactivate

List charges

Source types

Charge statuses

Charge response

Operational summary