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

# Operations and safe retries

> Distinguish durable acceptance from MT5 confirmation and choose the right retry key.

Store the business intent, exact amount, login, request key and returned ID before marking an action completed in the CRM. A timeout can happen after MT5 has already executed a write.

| Identifier | Used for |
| - | - |
| MT5 login (string) | Trading account, subscription participants, payment-balance and payment-withdrawal paths. |
| Leader ID | Strategy edits and credit batch lookup. Not interchangeable with the master login. |
| Allocation ID | Subscription reads, edits, termination and individual fees. |
| Operation ID | Status, result and, for eligible newly provisioned accounts, credential retrieval. Not an MT5 deal ticket. |
| MT5 deal ticket / PositionID | Evidence of a specific deal / grouping of related historical fills. Neither is a CRM retry key. |

## Read a response

**201** confirms account registration or creation, or a created allocation depending on the route. **202** means accepted for asynchronous processing. Follow `GET /api/v1/mamx/operations/{operation_id}` until terminal or until intervention is required; use bounded polling/backoff. `PENDING` and `RUNNING` are not completed. `DONE` confirms completion; inspect the operation-specific result. `REJECTED` is a rejection, not a reason for an automatic new financial request. `REVIEW` means evidence or execution is uncertain.

For new account credentials use `GET /api/v1/mamx/operations/{operation_id}/credentials` after completion, with the broker key. Never record credentials in request traces. Imported accounts do not issue new passwords.

## Retry contract by endpoint

| Intent | What the CRM must resend |
| - | - |
| Create account or leader | Same body and `request_key`. |
| Import an account | Same login and role flags; optional explicit `request_key`, otherwise a stable per-login key. |
| Subscribe | Same body and `idempotency_key`. Do not omit it for a retryable CRM integration. |
| Edit account or leader | Same body and `Idempotency-Key` **header**. |
| Deposit, investor withdrawal, payment withdrawal | Same target login, amount and `idempotency_key` in the **body**. |
| Receive webhook | Deduplicate the received `event_id`; do not use webhook arrival order as a sequence number. |

**401**: check the bearer key and broker instance. **422**: fix invalid fields, formats or incompatible inputs. **409**: read the detail and the current operation/allocation. A conflicting idempotency key is not fixed by retrying with altered data. A pending close or PF may need to settle first. **503**: check API configuration, schema and readiness. Do not switch to a fresh key just because the response was lost.

## What to do in REVIEW

Stop automatic retries for that intent. Preserve the operation/task ID, login, amount, timestamps and any MT5 ticket. Send them to the operator, without credentials. The operator checks MT5 against the durable receipt, confirms the old worker is stopped, and only then may authorize recovery using the full documentation. This authorizes reconciliation, **not** an unconditional second debit or trade. Do not delete a receipt, reset a cursor or manually mark the operation DONE to clear the queue.


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