# Fund Flow

> Fund your master wallet via top-up requests to MyStocks operations and repatriate surplus via payout requests. Includes the aggregate partner account summary. Both money-movement endpoints are idempotent.

Request top-ups from MyStocks operations to fund your master wallet, and submit payout requests to
repatriate surplus funds. Both endpoints are idempotent — always pass `Idempotency-Key` to prevent
duplicate submissions.

1\. Top-up: POST /topup

2\. PENDING: remittance in flight

3\. APPROVED: topup.confirmed

Top-up and payout state machines are in [Order & Money Lifecycles](/partners/docs/lifecycles).

## Partner account

`GET` `/account`

Master wallet balance plus an aggregate portfolio summary across all sub-accounts. Useful as a
dashboard home-screen data source.

```bash
curl "https://mystocks.africa/api/v1/partner/account" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "masterWalletBalance": 94500, "totalAum": 45230.5, "subAccountCount": 142, "currency": "USD" }
```

## Top-up

`POST` `/topup` · `GET` `/topup`

Submit a master-wallet top-up request to MyStocks operations. When funds are credited a
`wallet.credited` webhook fires. Use `GET` to list all previous top-up requests with their status.

amount (number, required): USD amount requested.

reference (string, optional): Your internal transfer reference for reconciliation.

```bash
curl -X POST "https://mystocks.africa/api/v1/partner/topup" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: topup_20260609_001" \
  -H "Content-Type: application/json" \
  -d '{"amount":10000,"reference":"wire_TXN987654"}'
```

```json
{ "id": "tup_abc123", "amount": 10000, "currency": "USD", "status": "PENDING", "reference": "wire_TXN987654", "createdAt": "2026-06-09T10:00:00Z" }
```

## Treasury controls

`GET` `/float` · `PATCH` `/float` · `POST` `/float`

`GET /float` is the partner treasury dashboard: master balance, pending top-ups, pending payouts,
approved credit line, credit drawn, available funding headroom, pending order exposure, and pending
credit-limit requests.

Use `PATCH /float` to set your minimum float, low-balance threshold, and automatic top-up reminder
recipients. The scheduled reminder worker emails those recipients and fires `float.low` when the
master wallet falls below the configured threshold.

```json
{
  "lowBalanceThresholdUsd": 500,
  "minimumFloatUsd": 5000,
  "autoTopupReminderEnabled": true,
  "autoTopupReminderRecipients": ["treasury@partner.example"],
  "autoTopupReminderFrequencyHours": 24
}
```

Use `POST /float` to request a credit-limit change. MyStocks treasury approves or rejects it from the
admin queue; all credit-limit changes are written to the partner audit log.

```json
{ "requestedCreditLimitUsd": 25000, "expectedMonthlyVolumeUsd": 500000, "reason": "Launch liquidity buffer" }
```

## Payout

`POST` `/payout` · `GET` `/payout`

Submit a payout request with the USD amount and beneficiary bank details. The request atomically reserves cash in the master wallet; the balance remains owned by the partner, but the reserved portion cannot fund customers, trades or conversions. Treasury processing debits the reserved amount once. Rejection releases it. Credit draws pause while master cash is reserved, so a credit line cannot consume payout collateral.

`GET /account` exposes `wallet.balance`, `wallet.reserved` and `wallet.available`. `GET /float` includes `reservedCashUsd` and `completeness`. An `UNKNOWN` treasury status means exposure is unavailable or capped; refresh and investigate before relying on the totals.

amount (number, required): Positive USD amount with at most two decimal places.

bankName (string, required): Beneficiary bank.

accountName (string, required): Beneficiary account name.

accountNumber (string, required): Beneficiary account number.

swiftCode (string, optional): SWIFT/BIC when required by the settlement route.

notes (string, optional): Additional treasury instructions.

```bash
curl -X POST "https://mystocks.africa/api/v1/partner/payout" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: payout_example_001" \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"bankName":"Example Bank","accountName":"Example Partner","accountNumber":"YOUR_ACCOUNT_NUMBER"}'
```

```json
{"requestId":"pay_example","amount":5000,"currency":"USD","status":"PENDING","reservedAmountUsd":5000,"message":"Payout request submitted and cash reserved. Treasury review and settlement confirmation are required."}
```

The list response uses `{requests, count, hasMore, nextCursor}` and uppercase request statuses. Sandbox deliberately does not initiate master payouts.

### Existing unreserved requests

Requests created before reservation support need explicit treasury review. `/admin/partners` blocks processing those legacy requests. First establish whether a bank transfer has already occurred. If none occurred, reject and recreate the request to reserve cash. If a transfer already occurred, reconcile the exact bank and ledger records before any correction; never resend it automatically.

## Recovering interrupted financial requests

Keep the original `Idempotency-Key` and operation namespace. Financial success receipts are committed with the cash/order change for funding, withdrawals, stock orders, subscriptions and supported redemptions. If the HTTP response is lost, retry the same request and key. Do not change the key to bypass a processing response.

`GET /report/operation?operation=withdraw_USER_ID&idempotencyKey=ORIGINAL_KEY` reads that partner's receipt. Other namespaces include `deposit_USER_ID`, `trade_USER_ID`, `subscribe_USER_ID`, `redeem_USER_ID`, `topup` and `payout`. It returns `COMPLETED` with the stored response or `IN_PROGRESS` with recovery guidance. A 404 is not proof that an older mutation did not execute; investigate the ledger before resubmission. This read does not initiate or reverse transfers.

Partner customer withdrawals always exclude internally reserved cash and unsettled USD proceeds in the debit transaction. This rule is independent of the retail settlement-holds flag. Existing trading escrow already deducted from wallet cash is not deducted again. Native transfers remain explicit operations and do not represent external bank payouts.
