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

<FlowDiagram
  direction="horizontal"
  nodes={[
    { label: 'Top-up', sublabel: 'POST /topup', tone: 'accent' },
    { label: 'PENDING', sublabel: 'remittance in flight' },
    { label: 'APPROVED', sublabel: 'topup.confirmed', tone: 'success' },
  ]}
/>

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

## Partner account

<MethodTag m="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

<MethodTag m="POST" /> `/topup` · <MethodTag m="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.

<ParamTable fields={[
  { name: 'amount',    type: 'number', required: true,  desc: 'USD amount requested.' },
  { name: 'reference', type: 'string', required: false, desc: '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

<MethodTag m="GET" /> `/float` · <MethodTag m="PATCH" /> `/float` · <MethodTag m="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

<MethodTag m="POST" /> `/payout` · <MethodTag m="GET" /> `/payout`

Submit a payout request to repatriate funds from your master wallet to your settlement account.
MyStocks operations processes and debits your master wallet on fulfilment. Use `GET` to list all
previous payout requests.

<ParamTable fields={[
  { name: 'amount',    type: 'number', required: true,  desc: 'USD amount to repatriate.' },
  { name: 'reference', type: 'string', required: false, desc: 'Your internal reference for reconciliation.' },
]} />

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

```json
{ "id": "pay_abc123", "amount": 5000, "currency": "USD", "status": "PENDING", "reference": "payout_REF123", "createdAt": "2026-06-09T10:00:00Z" }
```