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.
Top-up and payout state machines are in Order & Money Lifecycles.
Partner account
Master wallet balance plus an aggregate portfolio summary across all sub-accounts. Useful as a dashboard home-screen data source.
/account
Get partner account
Full endpoint documentationlistAccountReturns your partner profile — tier, wallet balance, API key metadata, and feature flags.
Parameters
walletContract1 | 2queryOpt in to actual currency wallets. Legacy indicative views remain unchanged.
Example: 1
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
accountIdstringbusinessNamestringemailstringwalletobjectwallet.currencystringExample: "USD"
wallet.balancenumberwallet.reservednumberwallet.availablenumberwalletContractVersion1 | 2walletModelUSD_LEDGER_WITH_INDICATIVE_EQUIVALENTS | NATIVE_CURRENCY_WALLETSsupportedConversionCurrenciesstring[]currencyWalletsobject[]currencyWallets[].currencystringcurrencyWallets[].balanceKindstringcurrencyWallets[].cashBalancenumbercurrencyWallets[].reservednumbercurrencyWallets[].externallyReservednumbercurrencyWallets[].totalCashnumbercurrencyWallets[].availablenumbercurrencyWallets[].withdrawablenumbercurrencyWallets[].availableForConversionnumbercurrencyWallets[].policyEligiblebooleancurrencyWallets[].internalTransferAvailablenumberTraceable available funds for internal transfers
currencyWallets[].nativeFundingEnabledbooleancurrencyWallets[].nativePayoutEnabledbooleancurrencyWallets[].conversionEnabledbooleanwalletsobject[]wallets[].balanceKindstringwallets[].indicativebooleanwallets[].spendablebooleanwallets[].currencystringExample: "KES"
wallets[].balancenumberExample: 65000
wallets[].availablenumberExample: 65000
wallets[].ledgerCurrencystringExample: "USD"
wallets[].ledgerBalancenumberExample: 500
wallets[].fxRatenumberExample: 130
wallets[].fxSourcestringExample: "MYSTOCKS_MANAGED_FX"
wallets[].fxRateAsOfstring | nullmanagedFxobjectmanagedFx.ledgerCurrencystringExample: "USD"
managedFx.sourcestringExample: "MYSTOCKS_MANAGED_FX"
managedFx.rateConventionstringExample: "local currency units per USD"
managedFx.supportedCurrenciesstring[]managedFx.asOfstring | nullportfolioValuenumberinvestedCapitalnumberrealizedGainUsdnumberenvironmentproduction | sandboxpilotobjectControlled-production policy. When enabled, production mutations fail closed unless admission, ownership, feature, limit, and reconciliation controls pass.
pilot.enabledbooleanRequiredpilot.statusNOT_APPROVED | APPROVED | PAUSED | COMPLETEDRequiredpilot.operationalOwnerunionpilot.incidentContactunionpilot.manualTreasuryReviewbooleanRequiredAlways true for a controlled pilot; master-wallet top-ups and payouts remain pending until MyStocks treasury review.
pilot.featuresobjectRequiredpilot.limitsobjectRequiredpilot.reconciliationobjectRequiredpilot.readinessobjectRequiredEvidence and approvals required before mutations may resume and before the controlled pilot may complete.
Response codes
200Partner account details.401Invalid API key.Top-up
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.
/topup
Request top-up
Full endpoint documentationcreateTopupNotifies MyStocks that you have sent a wire transfer to top up your master wallet. An admin confirms the wire receipt and credits your wallet (typically within 1 business day). Provide your wire transfer reference in paymentReference so we can match the incoming funds. paymentReference is unique per partner after normalization; duplicate references return 409. Sandbox: the request auto-approves instantly — the master wallet is credited in the same call and topup.confirmed fires, so the funding webhook path is fully testable. Production requests stay PENDING until the remittance is confirmed.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Idempotency-KeystringheaderRequiredUnique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.
Example: dep_user42_1743152580
Request body
amountnumberRequiredUSD amount to top up. Must be positive.
Example: 10000
paymentReferencestringRequiredYour wire transfer reference or payment ID. Unique per partner after normalization; duplicate references return 409.
Example: "WIRE-2026-05-001"
paymentMethodstringPayment method, e.g. SWIFT wire, SEPA, ACH.
Example: "SWIFT wire"
notesstringOptional note to the MyStocks operations team.
Response fields
messagestringrequestIdstringRequiredamountnumberRequiredcurrencystringRequiredstatusPENDING | APPROVEDRequiredLive awaits treasury review; Sandbox approves virtual funds immediately.
paymentReferencestringResponse codes
201Top-up request received./topup
List top-up requests
Full endpoint documentationlistTopupReturns all master wallet top-up requests and their approval status.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
requestsobject[]Requiredrequests[].requestIdstringRequiredrequests[].amountnumberRequiredrequests[].currencystringRequiredrequests[].statusPENDING | APPROVED | COMPLETED | REJECTEDRequiredrequests[].createdAtstring | nullRequiredrequests[].processedAtstring | nullrequests[].adminNotestring | nullrequests[].paymentReferencestringcountintegerRequiredhasMorebooleanRequirednextCursorstring | nullRequiredResponse codes
200Top-up request list.Treasury controls
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.
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.
/float
Master-account float / funding headroom
Full endpoint documentationgetFloatThe partner aggregates their end-users' deposits and remits to the master account (POST /topup); the master wallet funds sub-account deposits. This returns the funding headroom so the partner knows when to remit: masterBalanceUsd, pending top-ups, any credit line, availableToFundUsd, and a floatStatus of HEALTHY / LOW / DEPLETED / ON_CREDIT. Pair with the float.low and topup.confirmed webhooks.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
currencystringExample: "USD"
masterBalanceUsdnumberCurrent master wallet balance (negative when drawn on the credit line).
reservedCashUsdnumberCash unavailable for spending
completenessobjectcompleteness.completebooleancompleteness.warningsstring[]pendingTopupsUsdnumberSum of PENDING top-up requests awaiting MyStocks confirmation.
pendingPayoutsUsdnumberSum of PENDING payout requests awaiting MyStocks processing.
creditLimitUsdnumberCredit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only).
outstandingCreditUsdnumberCredit currently drawn (present when masterBalanceUsd is negative).
availableToFundUsdnumberCash balance less reservations, plus approved credit only when there are no cash reservations.
lowBalanceThresholdUsdnumberMaster balance below which a float.low webhook fires (partner-set via PATCH /float).
minimumFloatUsdnumberPartner treasury policy floor for the master account.
floatStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | UNKNOWNtreasuryStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | BELOW_MINIMUM | UNKNOWNreminderSettingsobjectreminderSettings.autoTopupReminderEnabledbooleanreminderSettings.recipientsstring[]reminderSettings.frequencyHoursintegerreminderSettings.shouldRemindNowbooleanexposureobjectPartner treasury exposure dashboard.
exposure.subAccountCountintegerexposure.pendingTopupsUsdnumberexposure.pendingPayoutsUsdnumberexposure.pendingOrderExposureUsdnumberexposure.outstandingCreditUsdnumberexposure.availableToFundUsdnumberexposure.netLiquidityUsdnumberexposure.pendingCreditLimitRequestsobject[]Response codes
200Float status./float
Update treasury float controls
Full endpoint documentationupdateFloatThresholdSets lowBalanceThresholdUsd — the master balance below which a float.low webhook fires. creditLimitUsd is set by MyStocks only.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Idempotency-KeystringheaderRequiredUnique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.
Example: dep_user42_1743152580
Request body
lowBalanceThresholdUsdnumberExample: 500
minimumFloatUsdnumberExample: 5000
autoTopupReminderEnabledbooleanExample: true
autoTopupReminderRecipientsstring[]autoTopupReminderFrequencyHoursintegerExample: 24
Response fields
currencystringExample: "USD"
masterBalanceUsdnumberCurrent master wallet balance (negative when drawn on the credit line).
reservedCashUsdnumberCash unavailable for spending
completenessobjectcompleteness.completebooleancompleteness.warningsstring[]pendingTopupsUsdnumberSum of PENDING top-up requests awaiting MyStocks confirmation.
pendingPayoutsUsdnumberSum of PENDING payout requests awaiting MyStocks processing.
creditLimitUsdnumberCredit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only).
outstandingCreditUsdnumberCredit currently drawn (present when masterBalanceUsd is negative).
availableToFundUsdnumberCash balance less reservations, plus approved credit only when there are no cash reservations.
lowBalanceThresholdUsdnumberMaster balance below which a float.low webhook fires (partner-set via PATCH /float).
minimumFloatUsdnumberPartner treasury policy floor for the master account.
floatStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | UNKNOWNtreasuryStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | BELOW_MINIMUM | UNKNOWNreminderSettingsobjectreminderSettings.autoTopupReminderEnabledbooleanreminderSettings.recipientsstring[]reminderSettings.frequencyHoursintegerreminderSettings.shouldRemindNowbooleanexposureobjectPartner treasury exposure dashboard.
exposure.subAccountCountintegerexposure.pendingTopupsUsdnumberexposure.pendingPayoutsUsdnumberexposure.pendingOrderExposureUsdnumberexposure.outstandingCreditUsdnumberexposure.availableToFundUsdnumberexposure.netLiquidityUsdnumberexposure.pendingCreditLimitRequestsobject[]Response codes
200Updated float status./float
Request a credit-limit change
Full endpoint documentationcreateFloatCreditLimitRequestOpens a MyStocks treasury review workflow for a partner credit-limit increase or decrease. Requires a full key and Idempotency-Key.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Idempotency-KeystringheaderRequiredUnique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.
Example: dep_user42_1743152580
Request body
requestedCreditLimitUsdnumberRequiredExample: 25000
expectedMonthlyVolumeUsdnumberExample: 500000
reasonstringExample: "Higher expected deposit volume after launch."
Response fields
requestIdstringstatusstringExample: "PENDING"
currentCreditLimitUsdnumberrequestedCreditLimitUsdnumbermessagestringResponse codes
201Credit-limit request opened.409A credit-limit request is already pending.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.
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.
/payout
Request payout
Full endpoint documentationcreatePayoutRequests a cash withdrawal from your master wallet to a bank account. An admin reviews and processes payouts within 2 business days. The requested amount is reserved immediately from your wallet balance. Sandbox payout creation is unsupported and returns HTTP 422 because virtual funds cannot be paid out.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Idempotency-KeystringheaderRequiredUnique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.
Example: dep_user42_1743152580
Request body
amountnumberRequiredUSD to withdraw. Must not exceed master wallet balance.
Example: 5000
bankDetailsobjectRequiredbankDetails.bankNamestringRequiredName of the receiving bank.
Example: "Equity Bank Kenya"
bankDetails.accountNamestringRequiredAccount holder name.
Example: "ACME Fintech Ltd"
bankDetails.accountNumberstringRequiredBank account number or IBAN.
Example: "0123456789"
bankDetails.swiftCodestringSWIFT/BIC code for international wires.
Example: "EQBLKENA"
notesstringOptional note to the MyStocks team.
Response fields
messagestringrequestIdstringRequiredamountnumberRequiredcurrencystringRequiredstatusstringRequiredreservedAmountUsdnumberRequiredResponse codes
201Payout request submitted.400Insufficient master wallet balance.422Payout requests are not available in sandbox; no funds are moved./payout
List payout requests
Full endpoint documentationlistPayoutReturns all payout requests from your master wallet.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
requestsobject[]Requiredrequests[].requestIdstringRequiredrequests[].amountnumberRequiredrequests[].currencystringRequiredrequests[].statusPENDING | APPROVED | COMPLETED | REJECTEDRequiredrequests[].createdAtstring | nullRequiredrequests[].processedAtstring | nullrequests[].adminNotestring | nullrequests[].reservedAmountUsdnumberrequests[].reservationVersioninteger | nullcountintegerRequiredhasMorebooleanRequirednextCursorstring | nullRequiredResponse codes
200Payout request list./account
Get partner account
Full endpoint documentationlistAccountReturns your partner profile — tier, wallet balance, API key metadata, and feature flags.
Parameters
walletContract1 | 2queryOpt in to actual currency wallets. Legacy indicative views remain unchanged.
Example: 1
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
accountIdstringbusinessNamestringemailstringwalletobjectwallet.currencystringExample: "USD"
wallet.balancenumberwallet.reservednumberwallet.availablenumberwalletContractVersion1 | 2walletModelUSD_LEDGER_WITH_INDICATIVE_EQUIVALENTS | NATIVE_CURRENCY_WALLETSsupportedConversionCurrenciesstring[]currencyWalletsobject[]currencyWallets[].currencystringcurrencyWallets[].balanceKindstringcurrencyWallets[].cashBalancenumbercurrencyWallets[].reservednumbercurrencyWallets[].externallyReservednumbercurrencyWallets[].totalCashnumbercurrencyWallets[].availablenumbercurrencyWallets[].withdrawablenumbercurrencyWallets[].availableForConversionnumbercurrencyWallets[].policyEligiblebooleancurrencyWallets[].internalTransferAvailablenumberTraceable available funds for internal transfers
currencyWallets[].nativeFundingEnabledbooleancurrencyWallets[].nativePayoutEnabledbooleancurrencyWallets[].conversionEnabledbooleanwalletsobject[]wallets[].balanceKindstringwallets[].indicativebooleanwallets[].spendablebooleanwallets[].currencystringExample: "KES"
wallets[].balancenumberExample: 65000
wallets[].availablenumberExample: 65000
wallets[].ledgerCurrencystringExample: "USD"
wallets[].ledgerBalancenumberExample: 500
wallets[].fxRatenumberExample: 130
wallets[].fxSourcestringExample: "MYSTOCKS_MANAGED_FX"
wallets[].fxRateAsOfstring | nullmanagedFxobjectmanagedFx.ledgerCurrencystringExample: "USD"
managedFx.sourcestringExample: "MYSTOCKS_MANAGED_FX"
managedFx.rateConventionstringExample: "local currency units per USD"
managedFx.supportedCurrenciesstring[]managedFx.asOfstring | nullportfolioValuenumberinvestedCapitalnumberrealizedGainUsdnumberenvironmentproduction | sandboxpilotobjectControlled-production policy. When enabled, production mutations fail closed unless admission, ownership, feature, limit, and reconciliation controls pass.
pilot.enabledbooleanRequiredpilot.statusNOT_APPROVED | APPROVED | PAUSED | COMPLETEDRequiredpilot.operationalOwnerunionpilot.incidentContactunionpilot.manualTreasuryReviewbooleanRequiredAlways true for a controlled pilot; master-wallet top-ups and payouts remain pending until MyStocks treasury review.
pilot.featuresobjectRequiredpilot.limitsobjectRequiredpilot.reconciliationobjectRequiredpilot.readinessobjectRequiredEvidence and approvals required before mutations may resume and before the controlled pilot may complete.
Response codes
200Partner account details.401Invalid API key./float
Master-account float / funding headroom
Full endpoint documentationgetFloatThe partner aggregates their end-users' deposits and remits to the master account (POST /topup); the master wallet funds sub-account deposits. This returns the funding headroom so the partner knows when to remit: masterBalanceUsd, pending top-ups, any credit line, availableToFundUsd, and a floatStatus of HEALTHY / LOW / DEPLETED / ON_CREDIT. Pair with the float.low and topup.confirmed webhooks.
Parameters
This endpoint has no path or query parameters.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
currencystringExample: "USD"
masterBalanceUsdnumberCurrent master wallet balance (negative when drawn on the credit line).
reservedCashUsdnumberCash unavailable for spending
completenessobjectcompleteness.completebooleancompleteness.warningsstring[]pendingTopupsUsdnumberSum of PENDING top-up requests awaiting MyStocks confirmation.
pendingPayoutsUsdnumberSum of PENDING payout requests awaiting MyStocks processing.
creditLimitUsdnumberCredit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only).
outstandingCreditUsdnumberCredit currently drawn (present when masterBalanceUsd is negative).
availableToFundUsdnumberCash balance less reservations, plus approved credit only when there are no cash reservations.
lowBalanceThresholdUsdnumberMaster balance below which a float.low webhook fires (partner-set via PATCH /float).
minimumFloatUsdnumberPartner treasury policy floor for the master account.
floatStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | UNKNOWNtreasuryStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | BELOW_MINIMUM | UNKNOWNreminderSettingsobjectreminderSettings.autoTopupReminderEnabledbooleanreminderSettings.recipientsstring[]reminderSettings.frequencyHoursintegerreminderSettings.shouldRemindNowbooleanexposureobjectPartner treasury exposure dashboard.
exposure.subAccountCountintegerexposure.pendingTopupsUsdnumberexposure.pendingPayoutsUsdnumberexposure.pendingOrderExposureUsdnumberexposure.outstandingCreditUsdnumberexposure.availableToFundUsdnumberexposure.netLiquidityUsdnumberexposure.pendingCreditLimitRequestsobject[]Response codes
200Float status.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.
Was this page useful?
Your signal helps us tighten partner onboarding docs.
Last updated on
Sub-Accounts
Create and manage end-user sub-accounts — each with an isolated USD wallet, portfolio, and order history. Covers create/auto-register, list/fetch, freeze, deposit, withdraw, and the KYC assertion API with an optional structured compliance profile.
Local-Currency Trading
Understand how MyStocks-managed funding, withdrawal, and execution FX work with local-market prices and USD wallets.