API product catalogSub-Accounts & White-Label Retail KYC

Sub-account buying power (settlement-aware)

Sub-Accounts & White-Label Retail KYC

GET

/users/{userId}/buying-power

Sandbox availablegetSubAccountBuyingPower

Settlement-aware balance for a sub-account. buyingPowerUsd is cash available to trade (unsettled SELL proceeds are usable for new buys, as is standard). withdrawableUsd excludes unsettled SELL proceeds, which remain locked until exchange settlement (T+N) — this is the free-riding guard. settlements[] lists each unsettled tranche and its settlement date.

Parameters

userIdstringpathRequired

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

accountTypeMASTER | SUBACCOUNT

subAccountIdstring | null

currencystring

Example: "USD"

cashBalanceUsdnumber

Current USD wallet balance.

buyingPowerUsdnumber

Cash available to place new orders (already net of open-BUY escrow; includes unsettled SELL proceeds).

unsettledUsdnumber

SELL proceeds credited but not yet settled at the exchange (T+N).

withdrawableUsdnumber

Cash available to withdraw — cashBalanceUsd minus unsettledUsd. The free-riding guard.

pendingBuyEscrowUsdnumber

Funds locked in open (PENDING) BUY orders.

settlementsobject[]

settlements[].amountUsdnumber

settlements[].settlesOnstring

settlements[].symbolstring | null

settlements[].exchangestring | null

settlements[].orderIdstring | null

Response codes

200Settlement-aware balance.

404Sub-account not found.

Sandbox playground

Read-only sandbox request

userId Required · pathSandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/buying-power

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "description": "Settlement-aware balance for a master or sub-account.",
  "properties": {
    "accountType": {
      "type": "string",
      "enum": [
        "MASTER",
        "SUBACCOUNT"
      ]
    },
    "subAccountId": {
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "cashBalanceUsd": {
      "type": "number",
      "description": "Current USD wallet balance."
    },
    "buyingPowerUsd": {
      "type": "number",
      "description": "Cash available to place new orders (already net of open-BUY escrow; includes unsettled SELL proceeds)."
    },
    "unsettledUsd": {
      "type": "number",
      "description": "SELL proceeds credited but not yet settled at the exchange (T+N)."
    },
    "withdrawableUsd": {
      "type": "number",
      "description": "Cash available to withdraw — cashBalanceUsd minus unsettledUsd. The free-riding guard."
    },
    "pendingBuyEscrowUsd": {
      "type": "number",
      "description": "Funds locked in open (PENDING) BUY orders."
    },
    "settlements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amountUsd": {
            "type": "number"
          },
          "settlesOn": {
            "type": "string",
            "format": "date-time"
          },
          "symbol": {
            "type": [
              "string",
              "null"
            ]
          },
          "exchange": {
            "type": [
              "string",
              "null"
            ]
          },
          "orderId": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/buying-power' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

PATCH /users/{userId}

POST /users/{userId}/deposit