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

POST /topup

→

PENDING

remittance in flight

→

APPROVED

topup.confirmed

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.

GET

/account

Get partner account

Full endpoint documentation

Sandbox availablelistAccount

Returns your partner profile — tier, wallet balance, API key metadata, and feature flags.

Parameters

walletContract1 | 2query

Opt in to actual currency wallets. Legacy indicative views remain unchanged.

Example: 1

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

accountIdstring

businessNamestring

emailstring

walletobject

wallet.currencystring

Example: "USD"

wallet.balancenumber

walletContractVersion1 | 2

walletModelUSD_LEDGER_WITH_INDICATIVE_EQUIVALENTS | NATIVE_CURRENCY_WALLETS

supportedConversionCurrenciesstring[]

currencyWalletsobject[]

currencyWallets[].currencystring

currencyWallets[].balanceKindstring

currencyWallets[].cashBalancenumber

currencyWallets[].reservednumber

currencyWallets[].externallyReservednumber

currencyWallets[].totalCashnumber

currencyWallets[].availablenumber

currencyWallets[].withdrawablenumber

currencyWallets[].availableForConversionnumber

currencyWallets[].policyEligibleboolean

currencyWallets[].internalTransferAvailablenumber

Traceable available funds for internal transfers

currencyWallets[].nativeFundingEnabledboolean

currencyWallets[].nativePayoutEnabledboolean

currencyWallets[].conversionEnabledboolean

walletsobject[]

wallets[].balanceKindstring

wallets[].indicativeboolean

wallets[].spendableboolean

wallets[].currencystring

Example: "KES"

wallets[].balancenumber

Example: 65000

wallets[].availablenumber

Example: 65000

wallets[].ledgerCurrencystring

Example: "USD"

wallets[].ledgerBalancenumber

Example: 500

wallets[].fxRatenumber

Example: 130

wallets[].fxSourcestring

Example: "MYSTOCKS_MANAGED_FX"

wallets[].fxRateAsOfstring | null

managedFxobject

managedFx.ledgerCurrencystring

Example: "USD"

managedFx.sourcestring

Example: "MYSTOCKS_MANAGED_FX"

managedFx.rateConventionstring

Example: "local currency units per USD"

managedFx.supportedCurrenciesstring[]

managedFx.asOfstring | null

portfolioValuenumber

investedCapitalnumber

realizedGainUsdnumber

environmentproduction | sandbox

pilotobject

Controlled-production policy. When enabled, production mutations fail closed unless admission, ownership, feature, limit, and reconciliation controls pass.

pilot.enabledbooleanRequired

pilot.statusNOT_APPROVED | APPROVED | PAUSED | COMPLETEDRequired

pilot.operationalOwnerunion

pilot.incidentContactunion

pilot.manualTreasuryReviewbooleanRequired

Always true for a controlled pilot; master-wallet top-ups and payouts remain pending until MyStocks treasury review.

pilot.featuresobjectRequired

pilot.limitsobjectRequired

pilot.reconciliationobjectRequired

pilot.readinessobjectRequired

Evidence and approvals required before mutations may resume and before the controlled pilot may complete.

Response codes

200Partner account details.

401Invalid API key.

Sandbox playground

Read-only sandbox request

walletContract Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/account

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string"
    },
    "businessName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "wallet": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "example": "USD"
        },
        "balance": {
          "type": "number"
        }
      }
    },
    "walletContractVersion": {
      "type": "integer",
      "enum": [
        1,
        2
      ]
    },
    "walletModel": {
      "type": "string",
      "enum": [
        "USD_LEDGER_WITH_INDICATIVE_EQUIVALENTS",
        "NATIVE_CURRENCY_WALLETS"
      ]
    },
    "supportedConversionCurrencies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "currencyWallets": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Actual separate ledger cash. External escrow has already been debited from cash; do not subtract it again. Live non-USD operations require explicit enablement.",
        "properties": {
          "currency": {
            "type": "string"
          },
          "balanceKind": {
            "type": "string",
            "const": "ACTUAL_WALLET"
          },
          "cashBalance": {
            "type": "number"
          },
          "reserved": {
            "type": "number"
          },
          "externallyReserved": {
            "type": "number"
          },
          "totalCash": {
            "type": "number"
          },
          "available": {
            "type": "number"
          },
          "withdrawable": {
            "type": "number"
          },
          "availableForConversion": {
            "type": "number"
          },
          "policyEligible": {
            "type": "boolean"
          },
          "internalTransferAvailable": {
            "type": "number",
            "description": "Traceable available funds for internal transfers",
            "not bank payouts": null
          },
          "nativeFundingEnabled": {
            "type": "boolean"
          },
          "nativePayoutEnabled": {
            "type": "boolean"
          },
          "conversionEnabled": {
            "type": "boolean"
          }
        }
      }
    },
    "wallets": {
      "type": "array",
      "items": {
        "description": "Indicative equivalents of one USD balance. These views are not separately spendable wallets and must not be summed.",
        "type": "object",
        "properties": {
          "balanceKind": {
            "type": "string",
            "const": "INDICATIVE_EQUIVALENT"
          },
          "indicative": {
            "type": "boolean",
            "const": true
          },
          "spendable": {
            "type": "boolean",
            "const": false
          },
          "currency": {
            "type": "string",
            "example": "KES"
          },
          "balance": {
            "type": "number",
            "example": 65000
          },
          "available": {
            "type": "number",
            "example": 65000
          },
          "ledgerCurrency": {
            "type": "string",
            "example": "USD"
          },
          "ledgerBalance": {
            "type": "number",
            "example": 500
          },
          "fxRate": {
            "type": "number",
            "example": 130
          },
          "fxSource": {
            "type": "string",
            "example": "MYSTOCKS_MANAGED_FX"
          },
          "fxRateAsOf": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      }
    },
    "managedFx": {
      "type": "object",
      "properties": {
        "ledgerCurrency": {
          "type": "string",
          "example": "USD"
        },
        "source": {
          "type": "string",
          "example": "MYSTOCKS_MANAGED_FX"
        },
        "rateConvention": {
          "type": "string",
          "example": "local currency units per USD"
        },
        "supportedCurrencies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "asOf": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "portfolioValue": {
      "type": "number"
    },
    "investedCapital": {
      "type": "number"
    },
    "realizedGainUsd": {
      "type": "number"
    },
    "environment": {
      "type": "string",
      "enum": [
        "production",
        "sandbox"
      ]
    },
    "pilot": {
      "type": "object",
      "description": "Controlled-production policy. When enabled, production mutations fail closed unless admission, ownership, feature, limit, and reconciliation controls pass.",
      "required": [
        "enabled",
        "status",
        "manualTreasuryReview",
        "features",
        "limits",
        "reconciliation",
        "readiness"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "status": {
          "type": "string",
          "enum": [
            "NOT_APPROVED",
            "APPROVED",
            "PAUSED",
            "COMPLETED"
          ]
        },
        "operationalOwner": {
          "anyOf": [
            {
              "allOf": [
                {
                  "type": "object",
                  "required": [
                    "name",
                    "email"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string",
                      "format": "email"
                    },
                    "phone": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "incidentContact": {
          "anyOf": [
            {
              "allOf": [
                {
                  "type": "object",
                  "required": [
                    "name",
                    "email"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string",
                      "format": "email"
                    },
                    "phone": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "manualTreasuryReview": {
          "type": "boolean",
          "description": "Always true for a controlled pilot; master-wallet top-ups and payouts remain pending until MyStocks treasury review."
        },
        "features": {
          "type": "object",
          "required": [
            "customerOnboarding",
            "funding",
            "trading",
            "withdrawals"
          ],
          "properties": {
            "customerOnboarding": {
              "type": "boolean"
            },
            "funding": {
              "type": "boolean"
            },
            "trading": {
              "type": "boolean"
            },
            "withdrawals": {
              "type": "boolean"
            }
          }
        },
        "limits": {
          "type": "object",
          "required": [
            "maxCustomers",
            "maxTransactionUsd",
            "maxDailyCustomerUsd",
            "maxDailyPartnerUsd"
          ],
          "properties": {
            "maxCustomers": {
              "type": "integer",
              "minimum": 1
            },
            "maxTransactionUsd": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "maxDailyCustomerUsd": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "maxDailyPartnerUsd": {
              "type": "number",
              "exclusiveMinimum": 0
            }
          }
        },
        "reconciliation": {
          "type": "object",
          "required": [
            "required",
            "maxAgeHours",
            "blockOnExceptions"
          ],
          "properties": {
            "required": {
              "type": "boolean"
            },
            "maxAgeHours": {
              "type": "number",
              "minimum": 24,
              "maximum": 48
            },
            "blockOnExceptions": {
              "type": "boolean"
            },
            "lastCompletedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "lastStatus": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "BALANCED",
                "EXCEPTIONS",
                "INCOMPLETE",
                null
              ]
            },
            "evidenceUrl": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri"
            }
          }
        },
        "readiness": {
          "type": "object",
          "description": "Evidence and approvals required before mutations may resume and before the controlled pilot may complete.",
          "required": [
            "rollbackPlanUrl",
            "eventDeliveryVerifiedAt",
            "failoverTestedAt",
            "approvals",
            "exitEvidenceUrl"
          ],
          "properties": {
            "rollbackPlanUrl": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri"
            },
            "eventDeliveryVerifiedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "failoverTestedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "approvals": {
              "type": "object",
              "required": [
                "operations",
                "risk",
                "compliance",
                "security"
              ],
              "properties": {
                "operations": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "risk": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "compliance": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "security": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            },
            "exitEvidenceUrl": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri"
            }
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/account' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_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.

POST

/topup

Request top-up

Full endpoint documentation

Sandbox availablecreateTopup

Notifies 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

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique 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

amountnumberRequired

USD amount to top up. Must be positive.

Example: 10000

paymentReferencestringRequired

Your wire transfer reference or payment ID. Unique per partner after normalization; duplicate references return 409.

Example: "WIRE-2026-05-001"

paymentMethodstring

Payment method, e.g. SWIFT wire, SEPA, ACH.

Example: "SWIFT wire"

notesstring

Optional note to the MyStocks operations team.

Response fields

messagestring

topupIdstring

Response codes

201Top-up request received.

Request reference

Sandbox available

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/topup

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "topupId": {
      "type": "string"
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/topup' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 10000,
  "paymentReference": "WIRE-2026-06-001",
  "paymentMethod": "SWIFT wire",
  "notes": "Monthly master wallet top-up"
}'

GET

/topup

List top-up requests

Full endpoint documentation

Sandbox availablelistTopup

Returns all master wallet top-up requests and their approval status.

Parameters

This endpoint has no path or query parameters.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

topupsobject[]

topups[].idstring

topups[].amountnumber

topups[].paymentReferencestring

topups[].statuspending | approved | rejected

topups[].createdAtstring

Response codes

200Top-up request list.

Sandbox playground

Read-only sandbox request

Sandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/topup

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "topups": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "paymentReference": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/topup' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

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.

GET

/float

Master-account float / funding headroom

Full endpoint documentation

Sandbox availablegetFloat

The 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

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

currencystring

Example: "USD"

masterBalanceUsdnumber

Current master wallet balance (negative when drawn on the credit line).

pendingTopupsUsdnumber

Sum of PENDING top-up requests awaiting MyStocks confirmation.

pendingPayoutsUsdnumber

Sum of PENDING payout requests awaiting MyStocks processing.

creditLimitUsdnumber

Credit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only).

outstandingCreditUsdnumber

Credit currently drawn (present when masterBalanceUsd is negative).

availableToFundUsdnumber

masterBalanceUsd + creditLimitUsd — the total still available to fund sub-accounts.

lowBalanceThresholdUsdnumber

Master balance below which a float.low webhook fires (partner-set via PATCH /float).

minimumFloatUsdnumber

Partner treasury policy floor for the master account.

floatStatusHEALTHY | LOW | DEPLETED | ON_CREDIT

treasuryStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | BELOW_MINIMUM

reminderSettingsobject

reminderSettings.autoTopupReminderEnabledboolean

reminderSettings.recipientsstring[]

reminderSettings.frequencyHoursinteger

reminderSettings.shouldRemindNowboolean

exposureobject

Partner treasury exposure dashboard.

exposure.subAccountCountinteger

exposure.pendingTopupsUsdnumber

exposure.pendingPayoutsUsdnumber

exposure.pendingOrderExposureUsdnumber

exposure.outstandingCreditUsdnumber

exposure.availableToFundUsdnumber

exposure.netLiquidityUsdnumber

exposure.pendingCreditLimitRequestsobject[]

Response codes

200Float status.

Sandbox playground

Read-only sandbox request

Sandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/float

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "description": "Master-account funding headroom.",
  "properties": {
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "masterBalanceUsd": {
      "type": "number",
      "description": "Current master wallet balance (negative when drawn on the credit line)."
    },
    "pendingTopupsUsd": {
      "type": "number",
      "description": "Sum of PENDING top-up requests awaiting MyStocks confirmation."
    },
    "pendingPayoutsUsd": {
      "type": "number",
      "description": "Sum of PENDING payout requests awaiting MyStocks processing."
    },
    "creditLimitUsd": {
      "type": "number",
      "description": "Credit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only)."
    },
    "outstandingCreditUsd": {
      "type": "number",
      "description": "Credit currently drawn (present when masterBalanceUsd is negative)."
    },
    "availableToFundUsd": {
      "type": "number",
      "description": "masterBalanceUsd + creditLimitUsd — the total still available to fund sub-accounts."
    },
    "lowBalanceThresholdUsd": {
      "type": "number",
      "description": "Master balance below which a float.low webhook fires (partner-set via PATCH /float)."
    },
    "minimumFloatUsd": {
      "type": "number",
      "description": "Partner treasury policy floor for the master account."
    },
    "floatStatus": {
      "type": "string",
      "enum": [
        "HEALTHY",
        "LOW",
        "DEPLETED",
        "ON_CREDIT"
      ]
    },
    "treasuryStatus": {
      "type": "string",
      "enum": [
        "HEALTHY",
        "LOW",
        "DEPLETED",
        "ON_CREDIT",
        "BELOW_MINIMUM"
      ]
    },
    "reminderSettings": {
      "type": "object",
      "properties": {
        "autoTopupReminderEnabled": {
          "type": "boolean"
        },
        "recipients": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        },
        "frequencyHours": {
          "type": "integer"
        },
        "shouldRemindNow": {
          "type": "boolean"
        }
      }
    },
    "exposure": {
      "type": "object",
      "description": "Partner treasury exposure dashboard.",
      "properties": {
        "subAccountCount": {
          "type": "integer"
        },
        "pendingTopupsUsd": {
          "type": "number"
        },
        "pendingPayoutsUsd": {
          "type": "number"
        },
        "pendingOrderExposureUsd": {
          "type": "number"
        },
        "outstandingCreditUsd": {
          "type": "number"
        },
        "availableToFundUsd": {
          "type": "number"
        },
        "netLiquidityUsd": {
          "type": "number"
        },
        "pendingCreditLimitRequests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "requestId": {
                "type": "string"
              },
              "requestedCreditLimitUsd": {
                "type": "number"
              },
              "currentCreditLimitUsd": {
                "type": "number"
              },
              "status": {
                "type": "string"
              },
              "requestedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/float' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

PATCH

/float

Update treasury float controls

Full endpoint documentation

Sandbox availableupdateFloatThreshold

Sets 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

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Example: dep_user42_1743152580

Request body

lowBalanceThresholdUsdnumber

Example: 500

minimumFloatUsdnumber

Example: 5000

autoTopupReminderEnabledboolean

Example: true

autoTopupReminderRecipientsstring[]

autoTopupReminderFrequencyHoursinteger

Example: 24

Response fields

currencystring

Example: "USD"

masterBalanceUsdnumber

Current master wallet balance (negative when drawn on the credit line).

pendingTopupsUsdnumber

Sum of PENDING top-up requests awaiting MyStocks confirmation.

pendingPayoutsUsdnumber

Sum of PENDING payout requests awaiting MyStocks processing.

creditLimitUsdnumber

Credit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only).

outstandingCreditUsdnumber

Credit currently drawn (present when masterBalanceUsd is negative).

availableToFundUsdnumber

masterBalanceUsd + creditLimitUsd — the total still available to fund sub-accounts.

lowBalanceThresholdUsdnumber

Master balance below which a float.low webhook fires (partner-set via PATCH /float).

minimumFloatUsdnumber

Partner treasury policy floor for the master account.

floatStatusHEALTHY | LOW | DEPLETED | ON_CREDIT

treasuryStatusHEALTHY | LOW | DEPLETED | ON_CREDIT | BELOW_MINIMUM

reminderSettingsobject

reminderSettings.autoTopupReminderEnabledboolean

reminderSettings.recipientsstring[]

reminderSettings.frequencyHoursinteger

reminderSettings.shouldRemindNowboolean

exposureobject

Partner treasury exposure dashboard.

exposure.subAccountCountinteger

exposure.pendingTopupsUsdnumber

exposure.pendingPayoutsUsdnumber

exposure.pendingOrderExposureUsdnumber

exposure.outstandingCreditUsdnumber

exposure.availableToFundUsdnumber

exposure.netLiquidityUsdnumber

exposure.pendingCreditLimitRequestsobject[]

Response codes

200Updated float status.

Request reference

Sandbox available

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/float

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "description": "Master-account funding headroom.",
  "properties": {
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "masterBalanceUsd": {
      "type": "number",
      "description": "Current master wallet balance (negative when drawn on the credit line)."
    },
    "pendingTopupsUsd": {
      "type": "number",
      "description": "Sum of PENDING top-up requests awaiting MyStocks confirmation."
    },
    "pendingPayoutsUsd": {
      "type": "number",
      "description": "Sum of PENDING payout requests awaiting MyStocks processing."
    },
    "creditLimitUsd": {
      "type": "number",
      "description": "Credit line — how far the master balance may go negative while a remittance is in flight (MyStocks-set; 0 = pre-funded only)."
    },
    "outstandingCreditUsd": {
      "type": "number",
      "description": "Credit currently drawn (present when masterBalanceUsd is negative)."
    },
    "availableToFundUsd": {
      "type": "number",
      "description": "masterBalanceUsd + creditLimitUsd — the total still available to fund sub-accounts."
    },
    "lowBalanceThresholdUsd": {
      "type": "number",
      "description": "Master balance below which a float.low webhook fires (partner-set via PATCH /float)."
    },
    "minimumFloatUsd": {
      "type": "number",
      "description": "Partner treasury policy floor for the master account."
    },
    "floatStatus": {
      "type": "string",
      "enum": [
        "HEALTHY",
        "LOW",
        "DEPLETED",
        "ON_CREDIT"
      ]
    },
    "treasuryStatus": {
      "type": "string",
      "enum": [
        "HEALTHY",
        "LOW",
        "DEPLETED",
        "ON_CREDIT",
        "BELOW_MINIMUM"
      ]
    },
    "reminderSettings": {
      "type": "object",
      "properties": {
        "autoTopupReminderEnabled": {
          "type": "boolean"
        },
        "recipients": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        },
        "frequencyHours": {
          "type": "integer"
        },
        "shouldRemindNow": {
          "type": "boolean"
        }
      }
    },
    "exposure": {
      "type": "object",
      "description": "Partner treasury exposure dashboard.",
      "properties": {
        "subAccountCount": {
          "type": "integer"
        },
        "pendingTopupsUsd": {
          "type": "number"
        },
        "pendingPayoutsUsd": {
          "type": "number"
        },
        "pendingOrderExposureUsd": {
          "type": "number"
        },
        "outstandingCreditUsd": {
          "type": "number"
        },
        "availableToFundUsd": {
          "type": "number"
        },
        "netLiquidityUsd": {
          "type": "number"
        },
        "pendingCreditLimitRequests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "requestId": {
                "type": "string"
              },
              "requestedCreditLimitUsd": {
                "type": "number"
              },
              "currentCreditLimitUsd": {
                "type": "number"
              },
              "status": {
                "type": "string"
              },
              "requestedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        }
      }
    }
  }
}

curl -X PATCH 'https://mystocks.africa/api/sandbox/v1/partner/float' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "lowBalanceThresholdUsd": 500,
  "minimumFloatUsd": 5000,
  "autoTopupReminderEnabled": true,
  "autoTopupReminderRecipients": ["treasury@partner.example"],
  "autoTopupReminderFrequencyHours": 24
}'

POST

/float

Request a credit-limit change

Full endpoint documentation

Sandbox availablecreateFloatCreditLimitRequest

Opens 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

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Example: dep_user42_1743152580

Request body

requestedCreditLimitUsdnumberRequired

Example: 25000

expectedMonthlyVolumeUsdnumber

Example: 500000

reasonstring

Example: "Higher expected deposit volume after launch."

Response fields

requestIdstring

statusstring

Example: "PENDING"

currentCreditLimitUsdnumber

requestedCreditLimitUsdnumber

messagestring

Response codes

201Credit-limit request opened.

409A credit-limit request is already pending.

Request reference

Sandbox available

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/float

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "example": "PENDING"
    },
    "currentCreditLimitUsd": {
      "type": "number"
    },
    "requestedCreditLimitUsd": {
      "type": "number"
    },
    "message": {
      "type": "string"
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/float' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "requestedCreditLimitUsd": 25000,
  "expectedMonthlyVolumeUsd": 500000,
  "reason": "Higher expected deposit volume after launch."
}'

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.

POST

/payout

Request payout

Full endpoint documentation

Sandbox unsupportedcreatePayout

Requests 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

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Example: dep_user42_1743152580

Request body

amountnumberRequired

USD to withdraw. Must not exceed master wallet balance.

Example: 5000

bankDetailsobjectRequired

bankDetails.bankNamestringRequired

Name of the receiving bank.

Example: "Equity Bank Kenya"

bankDetails.accountNamestringRequired

Account holder name.

Example: "ACME Fintech Ltd"

bankDetails.accountNumberstringRequired

Bank account number or IBAN.

Example: "0123456789"

bankDetails.swiftCodestring

SWIFT/BIC code for international wires.

Example: "EQBLKENA"

notesstring

Optional note to the MyStocks team.

Response fields

messagestring

payoutIdstring

Response codes

201Payout request submitted.

400Insufficient master wallet balance.

422Payout requests are not available in sandbox; no funds are moved.

Request reference

Sandbox unsupported

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/v1/partner/payout

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "payoutId": {
      "type": "string"
    }
  }
}

curl -X POST 'https://mystocks.africa/api/v1/partner/payout' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "bankDetails": {
    "bankName": "Equity Bank Kenya",
    "accountName": "ACME Fintech Ltd",
    "accountNumber": "0123456789",
    "swiftCode": "EQBLKENA"
  },
  "notes": "Monthly payout"
}'

GET

/payout

List payout requests

Full endpoint documentation

Sandbox availablelistPayout

Returns all payout requests from your master wallet.

Parameters

This endpoint has no path or query parameters.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

payoutsobject[]

payouts[].idstring

payouts[].amountnumber

payouts[].statuspending | approved | rejected

payouts[].createdAtstring

Response codes

200Payout request list.

Sandbox playground

Read-only sandbox request

Sandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/payout

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "payouts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/payout' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

Fund Flow

Partner account

Parameters

Headers

Response fields

Response codes

Top-up

Parameters

Headers

Request body

Response fields

Response codes

Parameters

Headers

Response fields

Response codes

Treasury controls

Parameters

Headers

Response fields

Response codes

Parameters

Headers

Request body

Response fields

Response codes

Parameters

Headers

Request body

Response fields

Response codes

Payout

Parameters

Headers

Request body

Response fields

Response codes

Parameters

Headers

Response fields

Response codes

On this page