API product catalogSub-Accounts & White-Label Retail KYC

Deposit to sub-account

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/deposit

Sandbox availablecreateDeposit

Native opt-in: ?walletContract=2 transfers actual specified currency between firm and customer wallets. Body contains only amount and currency. Requires traceable funding origin and settled available funds. Live requires approved currency capabilities and partner policy. No FX or external bank payout occurs. The v2 response contains transferId, direction, currency, amount, sourceBalance, targetBalance, simulationOnly, and externalPayout=false. Legacy v1 behavior below remains unchanged. Credits USD from your master wallet into a sub-account's wallet. Your master wallet must have sufficient balance — check via GET /account. Managed FX model — pass a USD ledger amount (amount or amountUsd) or pass amount with a non-USD currency such as KES. MyStocks converts supported non-USD amounts into the USD ledger using the managed conversion terms from the FX quote endpoints; bulk rate export is disabled. Sandbox uses the same conversion model but virtual balances only. Missing FX rates and unsupported currencies are rejected. Pass Idempotency-Key to make deposit retries safe on network failure.

Parameters

walletContract1 | 2query

Version 2 transfers actual currency without FX. Internal transfer only; body contains amount and currency.

Example: 1

userIdstringpathRequired

Example: usr_abc123

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

amountnumber

USD ledger amount to deposit, unless currency is a non-USD ISO code. If currency is non-USD, amount is interpreted in that currency and converted to USD by MyStocks managed FX.

Example: 500

amountUsdnumber

Explicit USD ledger amount. Use this when you also include local display fields.

Example: 500

currencystring

Currency of amount. Defaults to USD. Non-USD amounts are converted with MyStocks managed FX.

Example: "KES"

notestring

Optional description shown in the transaction history.

Example: "Mpesa STK push ref KE2482"

localAmountnumber

Equivalent amount in the user local currency. Stored for audit and compliance only.

Example: 65000

localCurrencystring

ISO 4217 code for the local amount.

Example: "KES"

fxRatenumber

Legacy partner-provided exchange rate. Omit this to use MyStocks managed FX.

Example: 130

Response fields

See the response format and API Reference for this endpoint.

Response codes

200Deposit processed.

400Master wallet has insufficient balance.

409Idempotency conflict.

Request reference

Sandbox available

walletContract Optional · queryuserId Required · path

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

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

Open in API Tester API Reference

Response schema

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "subAccountId": {
          "type": "string"
        },
        "externalId": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        },
        "amountUsd": {
          "type": "number"
        },
        "currency": {
          "type": "string"
        },
        "requestedAmount": {
          "type": "number"
        },
        "requestedCurrency": {
          "type": "string"
        },
        "newSubBalance": {
          "type": "number"
        },
        "newMasterBalance": {
          "type": "number"
        },
        "localAmount": {
          "type": [
            "number",
            "null"
          ]
        },
        "localCurrency": {
          "type": [
            "string",
            "null"
          ]
        },
        "fxRate": {
          "type": [
            "number",
            "null"
          ]
        },
        "fxSource": {
          "type": [
            "string",
            "null"
          ]
        },
        "simulationOnly": {
          "type": "boolean"
        },
        "fxConversion": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "sourceCurrency": {
                  "type": "string",
                  "example": "KES"
                },
                "sourceAmount": {
                  "type": "number",
                  "example": 65000
                },
                "targetCurrency": {
                  "type": "string",
                  "example": "USD"
                },
                "targetAmount": {
                  "type": "number",
                  "example": 500
                },
                "rate": {
                  "type": "number",
                  "example": 130
                },
                "rateConvention": {
                  "type": "string",
                  "example": "KES per USD"
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "MYSTOCKS_MANAGED_FX",
                    "PARTNER_PROVIDED_LEGACY"
                  ]
                },
                "asOf": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    {
      "type": "object",
      "required": [
        "transferId",
        "currency",
        "amount",
        "status",
        "externalPayout"
      ],
      "properties": {
        "transferId": {
          "type": "string"
        },
        "subAccountId": {
          "type": "string"
        },
        "direction": {
          "type": "string",
          "enum": [
            "deposit",
            "withdraw"
          ]
        },
        "currency": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        },
        "sourceBalance": {
          "type": "number"
        },
        "targetBalance": {
          "type": "number"
        },
        "status": {
          "type": "string",
          "const": "COMPLETED"
        },
        "simulationOnly": {
          "type": "boolean"
        },
        "externalPayout": {
          "type": "boolean",
          "const": false
        }
      }
    }
  ]
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/deposit' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 500,
  "localAmount": 655000,
  "localCurrency": "KES",
  "fxRate": 1310,
  "note": "mpesa_QHJ29SK"
}'

GET /users/{userId}/buying-power

GET /users/{userId}/devices