API product catalogSub-Accounts & White-Label Retail KYC

Subscribe (bond/fund/deal)

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/subscribe

Sandbox availablecreateSubscribe

Subscribes a sub-account to a bond, money market fund, or private credit/pre-IPO deal. Funds are escrowed from the sub-account wallet on submission. For FUND subscriptions: specify units. For OPPORTUNITY / PRE_IPO: specify amount in USD. The sub-account must be KYC-verified (kycStatus: VERIFIED).

Parameters

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

fundingWalletCurrencystring

Convert explicitly to USD before submitting an order

assetTypeBOND | FUND | OPPORTUNITY | PRE_IPORequired

Asset class to subscribe to.

Example: "FUND"

assetIdstringRequired

Firestore document ID. Obtain from the list endpoints (/bonds, /funds, /opportunities).

Example: "FUND_ID_FROM_CATALOGUE"

unitsnumber

Whole units to subscribe. Required for BOND and FUND.

Example: 500

amountnumber

USD commitment amount. Required for OPPORTUNITY and PRE_IPO.

Example: 1000

Response fields

messagestring

subscriptionIdstring

amountEscrowednumber

Response codes

201Subscription created.

400Insufficient wallet balance.

403KYC not verified.

Request reference

Sandbox available

userId 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/subscribe

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "subscriptionId": {
      "type": "string"
    },
    "amountEscrowed": {
      "type": "number"
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/subscribe' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "assetType": "FUND",
  "assetId": "fund_mmf_africa",
  "units": 500
}'

POST /users/{userId}/redeem

GET /users/{userId}/tax-lots