API product catalogSub-Accounts & White-Label Retail KYC

Sub-account portfolio

Sub-Accounts & White-Label Retail KYC

GET

/users/{userId}/portfolio

Sandbox availablegetUserPortfolio

Returns all open equity positions held by a sub-account, with current market value and unrealised P&L in USD.

Parameters

userIdstringpathRequired

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

subAccountIdstring

externalIdstring

summaryobject

summary.walletBalancenumber

summary.portfolioValuenumber

summary.investedCapitalnumber

summary.unrealisedPnlnumber

summary.totalValuenumber

holdingsobject[]

holdings[].symbolstring

holdings[].stockNamestring | null

holdings[].exchangestring | null

holdings[].currencystring

holdings[].unitsnumber

holdings[].avgCostnumber

holdings[].currentUsdPricenumber

holdings[].localPricenumber

holdings[].currentValuenumber

holdings[].investedCapitalnumber

holdings[].unrealisedPnlnumber

holdings[].priceIsLiveboolean

Backwards-compatible freshness flag for the delayed production catalogue; never implies real-time tick data.

holdings[].lastPriceUpdatestring | null

holdings[].asOfstring | null

Upstream capture timestamp for the price used in this valuation.

holdings[].staleboolean

holdings[].priceSourcePRODUCTION_CATALOGUE | SANDBOX_HOLDING

holdings[].dataQualityobject

The published market-data freshness contract. African equity quotes are supplied by the exchanges on a 15-minute-delayed basis, not in real time. MyStocks holds full exchange data rights. The API refresh target is 900 seconds during the published coverage window, with an end-of-day pass after market close.

Response codes

200Sub-account portfolio holdings and aggregate values.

Sandbox playground

Read-only sandbox request

userId Required · pathSandbox API keyYour key stays in this page’s memory.

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

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "subAccountId": {
      "type": "string"
    },
    "externalId": {
      "type": "string"
    },
    "summary": {
      "type": "object",
      "properties": {
        "walletBalance": {
          "type": "number"
        },
        "portfolioValue": {
          "type": "number"
        },
        "investedCapital": {
          "type": "number"
        },
        "unrealisedPnl": {
          "type": "number"
        },
        "totalValue": {
          "type": "number"
        }
      }
    },
    "holdings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "stockName": {
            "type": [
              "string",
              "null"
            ]
          },
          "exchange": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "units": {
            "type": "number"
          },
          "avgCost": {
            "type": "number"
          },
          "currentUsdPrice": {
            "type": "number"
          },
          "localPrice": {
            "type": "number"
          },
          "currentValue": {
            "type": "number"
          },
          "investedCapital": {
            "type": "number"
          },
          "unrealisedPnl": {
            "type": "number"
          },
          "priceIsLive": {
            "type": "boolean",
            "description": "Backwards-compatible freshness flag for the delayed production catalogue; never implies real-time tick data."
          },
          "lastPriceUpdate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "asOf": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Upstream capture timestamp for the price used in this valuation."
          },
          "stale": {
            "type": "boolean"
          },
          "priceSource": {
            "type": "string",
            "enum": [
              "PRODUCTION_CATALOGUE",
              "SANDBOX_HOLDING"
            ]
          },
          "dataQuality": {
            "type": "object",
            "description": "The published market-data freshness contract. African equity quotes are supplied by the exchanges on a 15-minute-delayed basis, not in real time. MyStocks holds full exchange data rights. The API refresh target is 900 seconds during the published coverage window, with an end-of-day pass after market close.\n",
            "required": [
              "asOf",
              "ageSeconds",
              "stale",
              "delayMode",
              "delayMinutes",
              "refreshIntervalSeconds",
              "provider",
              "disclaimer"
            ],
            "properties": {
              "asOf": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Timestamp of the exchange observation, not the time the API response was generated."
              },
              "ageSeconds": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Age of the price in seconds (now − asOf)."
              },
              "stale": {
                "type": "boolean",
                "description": "True when the price is older than two refresh intervals."
              },
              "delayMode": {
                "type": "string",
                "enum": [
                  "DELAYED",
                  "END_OF_DAY"
                ],
                "description": "DELAYED — exchange-supplied data in the 15-minute-delayed latency class. END_OF_DAY — outside the window; this is the most recent close, not a live quote.\n"
              },
              "delayMinutes": {
                "type": "integer",
                "example": 15,
                "description": "Exchange feed latency class in minutes. This is distinct from the API refresh target."
              },
              "refreshIntervalSeconds": {
                "type": "integer",
                "example": 900,
                "description": "Target interval between API ingestion refreshes during the published coverage window."
              },
              "provider": {
                "type": "string",
                "enum": [
                  "mstocks",
                  "mansa"
                ],
                "description": "MyStocks ingestion connector for this exchange feed. This field does not describe exchange licensing or partner entitlement."
              },
              "disclaimer": {
                "type": "string",
                "description": "Plain-English statement of what this price is and is not."
              }
            }
          }
        }
      }
    }
  }
}

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

GET /users/{userId}/orders/{orderId}/executions

GET /users/{userId}/portfolio/history