API product catalogExecution & Order Management (OMS)

Portfolio

Execution & Order Management (OMS)

GET

/portfolio

Portfolio

Sandbox availablelistPortfolio

Returns all open equity positions on your partner account — current holdings, average cost, unrealised P&L, and market value in USD.

Parameters

This endpoint has no path or query parameters.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

accountTypeMASTER | SUBACCOUNTRequired

subAccountIdstring

externalIdstring

summaryobjectRequired

summary.walletBalancenumberRequired

summary.portfolioValuenumberRequired

summary.investedCapitalnumberRequired

summary.unrealisedPnlnumberRequired

summary.totalValuenumberRequired

holdingsobject[]Required

holdings[].symbolstringRequired

holdings[].stockNamestring | null

holdings[].exchangestring | null

holdings[].currencystringRequired

holdings[].unitsnumberRequired

holdings[].avgCostnumberRequired

holdings[].currentUsdPricenumberRequired

holdings[].localPricenumber

holdings[].currentValuenumberRequired

holdings[].investedCapitalnumberRequired

holdings[].unrealisedPnlnumberRequired

holdings[].priceIsLivebooleanRequired

Backwards-compatible freshness flag. True only when the production catalogue price is within the delayed-feed freshness window; never implies real-time tick data.

holdings[].lastPriceUpdatestring | null

holdings[].asOfstring | nullRequired

Upstream capture timestamp for the price used in this valuation.

holdings[].stalebooleanRequired

True when the price timestamp is missing or older than the published freshness window.

holdings[].priceSourcePRODUCTION_CATALOGUE | SANDBOX_HOLDINGRequired

holdings[].dataQualityobjectRequired

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.

holdings[].idstring

Legacy master-account alias.

holdings[].namestring | null

Legacy alias of stockName.

holdings[].costBasisnumber

Legacy alias of avgCost.

holdings[].amountInvestednumber

Legacy alias of investedCapital.

holdings[].localCurrencystring | null

holdings[].gainLossnumber

Legacy alias of unrealisedPnl.

holdings[].liquidityStatusstring | null

countinteger

Legacy master-account total retained for compatibility.

totalValuenumber

totalInvestednumber

currencyUSD

Response codes

200Portfolio positions.

Sandbox playground

Read-only sandbox request

Sandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/portfolio

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "required": [
    "accountType",
    "summary",
    "holdings"
  ],
  "properties": {
    "accountType": {
      "type": "string",
      "enum": [
        "MASTER",
        "SUBACCOUNT"
      ]
    },
    "subAccountId": {
      "type": "string"
    },
    "externalId": {
      "type": "string"
    },
    "summary": {
      "type": "object",
      "required": [
        "walletBalance",
        "portfolioValue",
        "investedCapital",
        "unrealisedPnl",
        "totalValue"
      ],
      "properties": {
        "walletBalance": {
          "type": "number"
        },
        "portfolioValue": {
          "type": "number"
        },
        "investedCapital": {
          "type": "number"
        },
        "unrealisedPnl": {
          "type": "number"
        },
        "totalValue": {
          "type": "number"
        }
      }
    },
    "holdings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "symbol",
          "currency",
          "units",
          "avgCost",
          "currentUsdPrice",
          "currentValue",
          "investedCapital",
          "unrealisedPnl",
          "priceIsLive",
          "asOf",
          "stale",
          "priceSource",
          "dataQuality"
        ],
        "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. True only when the production catalogue price is within the delayed-feed freshness window; 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",
            "description": "True when the price timestamp is missing or older than the published freshness window."
          },
          "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."
              }
            }
          },
          "id": {
            "type": "string",
            "deprecated": true,
            "description": "Legacy master-account alias."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "deprecated": true,
            "description": "Legacy alias of stockName."
          },
          "costBasis": {
            "type": "number",
            "deprecated": true,
            "description": "Legacy alias of avgCost."
          },
          "amountInvested": {
            "type": "number",
            "deprecated": true,
            "description": "Legacy alias of investedCapital."
          },
          "localCurrency": {
            "type": [
              "string",
              "null"
            ],
            "deprecated": true
          },
          "gainLoss": {
            "type": "number",
            "deprecated": true,
            "description": "Legacy alias of unrealisedPnl."
          },
          "liquidityStatus": {
            "type": [
              "string",
              "null"
            ],
            "deprecated": true
          }
        }
      }
    },
    "count": {
      "type": "integer",
      "description": "Legacy master-account total retained for compatibility."
    },
    "totalValue": {
      "type": "number",
      "deprecated": true
    },
    "totalInvested": {
      "type": "number",
      "deprecated": true
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD"
      ]
    }
  }
}

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

GET /orders/{orderId}/executions

GET /portfolio/history