> ## Documentation Index
> Fetch the complete documentation index at: https://pamm-api.codench.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={null}
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={null}
{
  "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.

## 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={null}
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={null}
{
  "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.

## 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={null}
{
  "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.

<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.
</Warning>

<CardGroup cols={2}>
  <Card title="Previous: Subscription endpoints" icon="arrow-left" href="/reference/subscriptions">
    Return to relationship contracts.
  </Card>

  <Card title="Next: Performance fee endpoints" icon="arrow-right" href="/reference/performance-fees">
    Open fee configuration and reconciliation contracts.
  </Card>
</CardGroup>