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

# Financial operation endpoints

> Contracts for Investor deposits, withdrawals, and MT5 balance queries.

## Deposit to an Investor

`POST /api/v1/investor/deposit`

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `login` | string | Yes | Investor MT5 login. |
| `amount` | decimal | Yes | Positive amount with a minimum of `0.01`. |
| `currency` | string | No | Defaults to `USD`. |
| `comment` | string | No | CRM reconciliation reference; defaults to `API Deposit`. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST \
  "https://pamm-api.example.com/api/v1/investor/deposit?login=146600&amount=1000&currency=USD&comment=CRM-DEP-8451" \
  -H "Authorization: Bearer YOUR_CRM_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "action": "deposit",
  "login": "146600",
  "amount": 1000.0,
  "currency": "USD",
  "deal_id": 990001,
  "message": "Deposit completed in MT5",
  "first_deposit_checked": true,
  "min_deposit_required": "0"
}
```

If an active Master exists and this is the first deposit, the service can validate the Master's minimum deposit. Store `deal_id` and the CRM comment.

### Deposit response fields

| Field | Type | Meaning |
| - | - | - |
| `status`, `action` | string | `success` and `deposit`. |
| `login` | string | Credited Investor login. |
| `amount` | number | Credited amount after monetary normalization. |
| `currency` | string | Operation currency. |
| `deal_id` | integer | MT5 balance deal ID; save it for reconciliation. |
| `cashflow_key` | string | Persisted deposit ledger reference returned by current deployments. |
| `message` | string | Human-readable result, not a machine status. |
| `first_deposit_checked` | boolean | Indicates the first-deposit check; not a Master mirror confirmation. |
| `min_deposit_required` | decimal string | Minimum used by that check. |

This endpoint uses query parameters, not a JSON request body. A completed Investor deposit does not prove that the asynchronous Master mirror has completed.

## Withdraw from an Investor

`POST /api/v1/investor/withdraw`

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `login` | string | Yes | Investor MT5 login. |
| `amount` | decimal | Yes | Requested positive amount with a minimum of `0.01`. |
| `currency` | string | No | Defaults to `USD`. |
| `comment` | string | No | CRM reference; defaults to `API Withdraw`. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST \
  "https://pamm-api.example.com/api/v1/investor/withdraw?login=146600&amount=1000&currency=USD&comment=CRM-WD-1208" \
  -H "Authorization: Bearer YOUR_CRM_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "action": "withdraw",
  "login": "146600",
  "requested_amount": 1000.0,
  "effective_withdraw": 980.0,
  "currency": "USD",
  "message": "Withdrawal completed in MT5",
  "check_open_positions": true,
  "perf_fee_pending_at_request": "20.00",
  "balance_before": "1000.00",
  "available_after_perf_fee": "980.00",
  "mt5_deal_id": 990050
}
```

Open Master positions block the withdrawal. Pending fees are crystallized first, so `effective_withdraw` can be lower than the request.

### Withdrawal response fields

| Field | Type | Meaning |
| - | - | - |
| `status`, `action` | string | `success` and `withdraw`. |
| `login`, `currency` | string | Investor login and operation currency. |
| `requested_amount` | number | Normalized amount requested. |
| `effective_withdraw` | number | Amount actually withdrawn after reserving pending PF; can be zero. |
| `perf_fee_pending_at_request` | decimal string | Fee preview at request time. |
| `balance_before` | decimal string | Balance used by the withdrawal checks. |
| `available_after_perf_fee` | decimal string | Balance remaining after the fee reservation. |
| `check_open_positions` | boolean | Whether the open-Master-position check was enabled. External CRM requests use the default `true`; do not override this safeguard. |
| `mt5_deal_id` | integer or null | Withdrawal balance deal; null when the effective withdrawal is zero. |
| `message` | string | Human-readable result. |

Like deposit, withdrawal uses query parameters, not a JSON request body. Treat `effective_withdraw`, rather than the requested amount, as the executed withdrawal.

## Retrieve an MT5 balance

`GET /api/v1/info/balance/{mt5_login}`

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `mt5_login` | string | Yes | Operational MT5 login to query. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mt5_login": "146600",
  "balance": 1000.0,
  "ok": true,
  "error": null
}
```

When `ok` is false, `balance` can be `null` and `error` contains the cause. A Master balance can lag behind the Investor-side command while the mirror operation is processed.

| Response field | Type | Meaning |
| - | - | - |
| `mt5_login` | string | Requested account login. |
| `balance` | number or null | MT5 balance, not equity or available withdrawal capital. |
| `ok` | boolean | Whether the MT5 read succeeded. |
| `error` | string or null | Read failure description, null on success. |

> [!WARNING]
>
> These commands do not accept a CRM idempotency key. Prevent duplicates in your own ledger and reconcile `deal_id`, `mt5_deal_id`, comments, and balances before retrying an uncertain request.

> [card] [Previous: Subscription endpoints](https://pamm-api.exuratech.com/reference/subscriptions.md)
>
> Return to relationship contracts.

> [card] [Next: Performance fee endpoints](https://pamm-api.exuratech.com/reference/performance-fees.md)
>
> Open fee configuration and reconciliation contracts.


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