API product catalogTreasury, Cash Management & FX Settlement

Update treasury float controls

Treasury, Cash Management & FX Settlement

PATCH

/float

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

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

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

GET /float

POST /float