API product catalogExecution & Order Management (OMS)

Pre-trade fee quote

Execution & Order Management (OMS)

GET

/quote/{symbol}

Pre-trade fee quote

Sandbox availablegetQuote

Returns a pre-trade fee quote using the latest delayed price observation. Includes the local and USD price, gross order cost, base fee, partner markup fee, and total cost for BUY or estimated proceeds for SELL. Also returns whether the partner wallet has sufficient balance/holdings. Size the quote with either quantity (share mode) or cashValue (cash mode) — they are mutually exclusive, and the subsequent trade must use the same mode and value. Cash-mode quotes return an indicative fractional quantity; the order is sized at execution price and validated against the quoted cashValue. Quotes remain valid for 60 seconds to protect quote-to-fill price integrity. Mobile clients should display quoteExpiresAt, refresh when 10 seconds remain or whenever the app resumes, and require confirmation again if the refreshed cost, proceeds, fee, or quantity changes. Fetching a replacement quote does not place an order. Always fetch a quote immediately before placing a trade to confirm the current cost.

Parameters

symbolstringpathRequired

Exchange-qualified ticker (e.g. SCOM.KE) or bare ticker.

Example: SCOM.KE

typeBUY | SELLquery

Order direction. Defaults to BUY.

Example: BUY

quantitynumberquery

Number of shares to quote (fractional allowed). Mutually exclusive with cashValue. Defaults to 1 when neither is passed.

Example: 500

cashValuenumberquery

USD amount to quote in cash mode (fractional investing). Mutually exclusive with quantity. The trade must then be placed with the same cashValue and this quoteId.

Example: 50

subAccountIdstringquery

Optional sub-account ID when quoting a trade for /users/{userId}/trade. The account must exist under the authenticated partner key.

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

quoteIdstring

Quote ID to submit in the subsequent trade request.

quoteTtlSecondsinteger

Example: 60

quoteIssuedAtstring

quoteExpiresAtstring

sourceUpdatedAtstring | null

Timestamp of the source market price used for this quote.

dataFreshnessSecondsinteger | null

Age in seconds of the source market price when the quote was issued.

asOfstring | null

Canonical timestamp of the upstream price observation; equivalent to sourceUpdatedAt.

ageSecondsinteger | null

Canonical price age in seconds; equivalent to dataFreshnessSeconds.

staleboolean

True when the price observation is older than two refresh intervals.

delayModeDELAYED | END_OF_DAY

delayMinutesinteger

Example: 15

refreshIntervalSecondsinteger

Example: 900

providermstocks | mansa

disclaimerstring

Plain-English delayed-price warning.

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.

dataQuality.asOfstring | nullRequired

Timestamp of the exchange observation, not the time the API response was generated.

dataQuality.ageSecondsinteger | nullRequired

Age of the price in seconds (now − asOf).

dataQuality.stalebooleanRequired

True when the price is older than two refresh intervals.

dataQuality.delayModeDELAYED | END_OF_DAYRequired

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.

dataQuality.delayMinutesintegerRequired

Exchange feed latency class in minutes. This is distinct from the API refresh target.

Example: 15

dataQuality.refreshIntervalSecondsintegerRequired

Target interval between API ingestion refreshes during the published coverage window.

Example: 900

dataQuality.providermstocks | mansaRequired

MyStocks ingestion connector for this exchange feed. This field does not describe exchange licensing or partner entitlement.

dataQuality.disclaimerstringRequired

Plain-English statement of what this price is and is not.

symbolstring

Example: "SCOM.KE"

namestring

exchangestring

currencystring

Example: "KES"

ledgerCurrencystring

Example: "USD"

fxRatenumber

Managed FX rate used to convert local price to USD.

fxSourcestring

Example: "MYSTOCKS_MANAGED_FX"

fxRateAsOfstring | null

fxConversionobject

fxConversion.sourceCurrencystring

Example: "KES"

fxConversion.sourceAmountnumber

Example: 65000

fxConversion.targetCurrencystring

Example: "USD"

fxConversion.targetAmountnumber

Example: 500

fxConversion.ratenumber

Example: 130

fxConversion.rateConventionstring

Example: "KES per USD"

fxConversion.sourceMYSTOCKS_MANAGED_FX | PARTNER_PROVIDED_LEGACY

fxConversion.asOfstring | null

typeBUY | SELL

quantityinteger

localPricenumber

Current price in the stock's local currency.

usdPricenumber

Current price converted to USD.

grossnumber

quantity × usdPrice.

baseFeenumber

MyStocks base broker fee (0.75% of gross).

partnerMarkupFeenumber

Partner markup component of the fee. Zero if markupBps = 0.

feenumber

Total fee (baseFee + partnerMarkupFee).

feeRatenumber

Effective fee rate as a percentage (e.g. 0.75).

totalCostnumber

BUY only — gross + fee. The amount escrowed on order submission.

estimatedProceedsnumber

SELL only — gross - fee. Estimated wallet credit on settlement.

walletBalancenumber

Partner master wallet balance in USD.

sufficientFundsboolean

BUY only — true if walletBalance >= totalCost.

unitsnumber

SELL only — units of this stock currently held.

sufficientHoldingsboolean

SELL only — true if units >= quantity.

notestring

Example: "This is a quote only. No order has been placed."

Response codes

200Fee quote for the requested symbol, type, and quantity.

404Symbol or scoped sub-account not found. Unknown sub-accounts return `SUBACCOUNT_NOT_FOUND` and no quote is created.

Sandbox playground

Read-only sandbox request

symbol Required · pathtype Optional · queryquantity Optional · querycashValue Optional · querysubAccountId Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/quote/%7Bsymbol%7D

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "quoteId": {
      "type": "string",
      "description": "Quote ID to submit in the subsequent trade request."
    },
    "quoteTtlSeconds": {
      "type": "integer",
      "example": 60
    },
    "quoteIssuedAt": {
      "type": "string",
      "format": "date-time"
    },
    "quoteExpiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "sourceUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Timestamp of the source market price used for this quote."
    },
    "dataFreshnessSeconds": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Age in seconds of the source market price when the quote was issued."
    },
    "asOf": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Canonical timestamp of the upstream price observation; equivalent to sourceUpdatedAt."
    },
    "ageSeconds": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Canonical price age in seconds; equivalent to dataFreshnessSeconds."
    },
    "stale": {
      "type": "boolean",
      "description": "True when the price observation is older than two refresh intervals."
    },
    "delayMode": {
      "type": "string",
      "enum": [
        "DELAYED",
        "END_OF_DAY"
      ]
    },
    "delayMinutes": {
      "type": "integer",
      "example": 15
    },
    "refreshIntervalSeconds": {
      "type": "integer",
      "example": 900
    },
    "provider": {
      "type": "string",
      "enum": [
        "mstocks",
        "mansa"
      ]
    },
    "disclaimer": {
      "type": "string",
      "description": "Plain-English delayed-price warning."
    },
    "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."
        }
      }
    },
    "symbol": {
      "type": "string",
      "example": "SCOM.KE"
    },
    "name": {
      "type": "string"
    },
    "exchange": {
      "type": "string"
    },
    "currency": {
      "type": "string",
      "example": "KES"
    },
    "ledgerCurrency": {
      "type": "string",
      "example": "USD"
    },
    "fxRate": {
      "type": "number",
      "description": "Managed FX rate used to convert local price to USD."
    },
    "fxSource": {
      "type": "string",
      "example": "MYSTOCKS_MANAGED_FX"
    },
    "fxRateAsOf": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "fxConversion": {
      "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": {
      "type": "string",
      "enum": [
        "BUY",
        "SELL"
      ]
    },
    "quantity": {
      "type": "integer"
    },
    "localPrice": {
      "type": "number",
      "description": "Current price in the stock's local currency."
    },
    "usdPrice": {
      "type": "number",
      "description": "Current price converted to USD."
    },
    "gross": {
      "type": "number",
      "description": "quantity × usdPrice."
    },
    "baseFee": {
      "type": "number",
      "description": "MyStocks base broker fee (0.75% of gross)."
    },
    "partnerMarkupFee": {
      "type": "number",
      "description": "Partner markup component of the fee. Zero if markupBps = 0."
    },
    "fee": {
      "type": "number",
      "description": "Total fee (baseFee + partnerMarkupFee)."
    },
    "feeRate": {
      "type": "number",
      "description": "Effective fee rate as a percentage (e.g. 0.75)."
    },
    "totalCost": {
      "type": "number",
      "description": "BUY only — gross + fee. The amount escrowed on order submission."
    },
    "estimatedProceeds": {
      "type": "number",
      "description": "SELL only — gross - fee. Estimated wallet credit on settlement."
    },
    "walletBalance": {
      "type": "number",
      "description": "Partner master wallet balance in USD."
    },
    "sufficientFunds": {
      "type": "boolean",
      "description": "BUY only — true if walletBalance >= totalCost."
    },
    "units": {
      "type": "number",
      "description": "SELL only — units of this stock currently held."
    },
    "sufficientHoldings": {
      "type": "boolean",
      "description": "SELL only — true if units >= quantity."
    },
    "note": {
      "type": "string",
      "example": "This is a quote only. No order has been placed."
    }
  }
}

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

GET /portfolio/performance

POST /trade