Fund Flow

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.

Top-up and payout state machines are in Order & Money 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.

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

{ "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.

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"}'

{ "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.

{
  "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.

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

Payout

POST /payout · 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.

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"}'

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