Broker API

Local-Currency Trading

MyStocks Partner API

Understand how MyStocks-managed funding, withdrawal, and execution FX work with local-market prices and USD wallets.

Integration guides Get a sandbox key

Explore endpoints

7 of 7

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"

MyStocks presents a USD-denominated wallet while instruments trade in their exchange currency. The FX responsibility depends on the flow.

Flow	FX responsibility	API behavior
Deposit	MyStocks	Send local `amount` and `currency`; MyStocks converts and credits the USD wallet.
Quote and trade	MyStocks	Quote and execution use the live market conversion at the relevant point in the order flow.
Dividend	MyStocks	Declared local-currency dividends are converted and credited to the USD wallet.
Withdrawal	MyStocks	Send local `amount` and `currency`; MyStocks converts the ledger debit while your payout rail delivers local currency.

Implementation rules

Use amount plus currency for supported non-USD funding and withdrawals.
Record the returned fxRate, fxSource, and fxConversion.asOf conversion metadata.
Treat request fxRate as deprecated legacy compatibility; omit it in new integrations.
Show the quote currency and wallet currency separately in your UI.
Never calculate a trade’s final USD debit from a stale display price.
Treat FX rate, timestamp, spread, and rounding as customer-disclosure data.
Reconcile local-market fills and USD ledger movements together.

See the detailed FX & Currency model, Trading API, and Statements and Confirms.

Wallet balances are USD ledger balances. MyStocks does not provide an end-user FX hedge. Your product must disclose exchange-rate movement between funding, execution, dividend conversion, and withdrawal.

Was this page useful?

Your signal helps us tighten partner onboarding docs.

Send note

Last updated on

Fund Flow

FX & Currency