API product catalogSub-Accounts & White-Label Retail KYC

Withdraw from sub-account

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/withdraw

Sandbox availablecreateWithdraw

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. Moves USD from a sub-account's wallet back to your master wallet. Use this when your user requests a cash-out. The funds are immediately available in your master wallet. Pass a USD ledger amount or a supported local amount + currency; non-USD values are converted with MyStocks managed FX. Sandbox uses the same conversion model but virtual balances only. Missing FX rates and unsupported currencies are rejected. Pass Idempotency-Key to make withdrawals safe to retry.

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 move, 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: 200

amountUsdnumber

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

Example: 200

currencystring

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

Example: "KES"

notestring

Optional description shown in transaction history.

localAmountnumber

Equivalent in local currency for the audit trail.

Example: 26000

localCurrencystring

ISO 4217 code.

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

200Withdrawal processed.

400Sub-account has insufficient wallet balance.

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/withdraw

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/withdraw' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 200,
  "localAmount": 26000,
  "localCurrency": "KES",
  "fxRate": 130,
  "note": "withdrawal for user_42"
}'

DELETE /users/{userId}/watchlist/{symbol}

GET /users/summary