API product catalogSub-Accounts & White-Label Retail KYC

Sub-account wallet

Sub-Accounts & White-Label Retail KYC

GET

/users/{userId}/wallet

Sub-account wallet

Sandbox availablelistWallet

Returns USD wallet data, indicative currency equivalents and opt-in actual currency wallets for a sub-account. Transaction history is returned separately by GET /users/{userId}/transactions.

Parameters

walletContract1 | 2query

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

Example: 1

userIdstringpathRequired

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

subAccountIdstringRequired

externalIdstring

walletobjectRequired

wallet.currencystring

wallet.balancenumber

walletContractVersion1 | 2

walletModelUSD_LEDGER_WITH_INDICATIVE_EQUIVALENTS | NATIVE_CURRENCY_WALLETS

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

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

managedFxobject

managedFx.ledgerCurrencystring

Example: "USD"

managedFx.sourcestring

Example: "MYSTOCKS_MANAGED_FX"

managedFx.rateConventionstring

Example: "local currency units per USD"

managedFx.supportedCurrenciesstring[]

managedFx.asOfstring | null

Response codes

200Actual USD wallet, indicative views and opt-in actual currency wallets. Transaction history is a separate endpoint.

Sandbox playground

Read-only sandbox request

walletContract Optional · queryuserId Required · pathSandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/wallet

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "required": [
    "subAccountId",
    "wallet"
  ],
  "properties": {
    "subAccountId": {
      "type": "string"
    },
    "externalId": {
      "type": "string"
    },
    "wallet": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "const": "USD"
        },
        "balance": {
          "type": "number"
        }
      }
    },
    "walletContractVersion": {
      "type": "integer",
      "enum": [
        1,
        2
      ]
    },
    "walletModel": {
      "type": "string",
      "enum": [
        "USD_LEDGER_WITH_INDICATIVE_EQUIVALENTS",
        "NATIVE_CURRENCY_WALLETS"
      ]
    },
    "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"
          }
        }
      }
    },
    "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"
          }
        }
      }
    },
    "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"
        }
      }
    }
  }
}

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

GET /users/{userId}/transactions

GET /users/{userId}/watchlist