API product catalogSub-Accounts & White-Label Retail KYC

Quote an explicit wallet currency conversion

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/fx/quote

Sandbox availablecreateSubAccountCurrencyQuote

Requires an Idempotency-Key and an owned active account. Sandbox conversion is virtual. Live requires verified identity, approved currencies, traceable funding origin and operational acceptance. Quotes use shared managed rates, fee policy and 60-second expiry. Confirmation consumes a quote atomically; it never spends indicative display equivalents. Historical untraceable balances are not automatically eligible.

Parameters

userIdstringpathRequired

Example: CUSTOMER_ID_FROM_USERS

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Request body

fromCurrencystringRequired

Example: "KES"

toCurrencystringRequired

Example: "USD"

amountnumberRequired

Example: 65000

Response fields

quoteIdstring

conversionIdstring

fromCurrencystring

toCurrencystring

sourceAmountnumber

targetAmountnumber

feeAmountnumber

feeCurrencystring

feePercentnumber

ratenumber

rateConventionstring

expiresAtstring

sourcestring

rateAsOfstring | null

simulationOnlyboolean

statusCOMPLETED

sourceBalancenumber

targetBalancenumber

Response codes

200Authoritative managed FX terms or completed conversion receipt. See the FX model guide for field meanings.

400Invalid parameters or missing idempotency key

403Currency

404Account or quote not found

409Expired or consumed quote

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/fx/quote

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "quoteId": {
      "type": "string"
    },
    "conversionId": {
      "type": "string"
    },
    "fromCurrency": {
      "type": "string"
    },
    "toCurrency": {
      "type": "string"
    },
    "sourceAmount": {
      "type": "number"
    },
    "targetAmount": {
      "type": "number"
    },
    "feeAmount": {
      "type": "number"
    },
    "feeCurrency": {
      "type": "string"
    },
    "feePercent": {
      "type": "number"
    },
    "rate": {
      "type": "number"
    },
    "rateConvention": {
      "type": "string"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "source": {
      "type": "string"
    },
    "rateAsOf": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "simulationOnly": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "COMPLETED"
      ]
    },
    "sourceBalance": {
      "type": "number"
    },
    "targetBalance": {
      "type": "number"
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/fx/quote' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "fromCurrency": "KES",
  "toCurrency": "USD",
  "amount": 65000
}'

POST /users/{userId}/fx/convert

GET /users/{userId}/gains