Choose your API

Partner API Specification

MyStocks Partner API

September 2026 B2B specification, integration fundamentals, product reference, and clarifications for the current online API contract.

Integration guides Get a sandbox key

Explore endpoints

2 of 2

POST

/trade

Place trade

Full endpoint documentation

Sandbox unsupportedcreateTrade

Places a BUY or SELL order on your own partner account (not a sub-account — use /users/{userId}/trade for those). Sandbox master trading is unsupported and returns HTTP 422; use POST /users/{userId}/trade with a funded sandbox sub-account instead. BUY — escrows USD from your master wallet. Settlement is T+3 for most African exchanges. SELL — requires you to hold the shares. Proceeds are credited on settlement. Pass Idempotency-Key to make retries safe. The same key returns the cached order within 24 h.

Parameters

This endpoint has no path or query parameters.

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

symbolstringRequired

Stock symbol. Accepts exchange-qualified (SCOM.KE, DANGCEM.NG) or bare ticker (SCOM) -- auto-resolved when unambiguous. Returns 422 with match list if ambiguous.

Example: "SCOM.KE"

typeBUY | SELLRequired

Order direction.

Example: "BUY"

quantitynumber

Number of shares. Whole-share markets require integer quantities; fractional-enabled markets allow up to 6 decimal places. Mutually exclusive with cashValue.

Example: 500

cashValuenumber

USD notional amount for cash-mode fractional investing. Mutually exclusive with quantity and must match the cashValue used to obtain quoteId for MARKET orders.

Example: 50

quoteIdstring

Fresh pre-trade quote ID from GET /quote/{symbol}. Quotes expire after 60 seconds and can be used once. Required for MARKET orders, including the default when orderType is omitted; ignored for LIMIT/STOP/STOP_LIMIT.

Example: "qt_2f4d5a7b8c9e4f01a2b3c4d5e6f78901"

orderTypeMARKET | LIMIT | STOP | STOP_LIMIT

MARKET (default): quote-gated and routed to automatic MyStocks internal-book execution. LIMIT/STOP/STOP_LIMIT are resting orders — they are placed WITHOUT a quote, escrow at the trigger price, rest in status WORKING, and route to automatic internal-book execution when the latest delayed price observation crosses the trigger (during market hours). BUY LIMIT fills at/below limitPrice; SELL LIMIT at/above; BUY STOP triggers at/above stopPrice; SELL STOP at/below. Prices are in the stock's LOCAL trading currency. Fires order.triggered on activation.

limitPricenumber

Local-currency limit price. Required for LIMIT and STOP_LIMIT.

stopPricenumber

Local-currency stop/trigger price. Required for STOP and STOP_LIMIT.

clientOrderIdstring

Optional partner-supplied order reference. Must be unique per partner when supplied.

Example: "partner-ord-10001"

timeInForceDAY | GTC | GTD

Order validity instruction, enforced by the OMS lifecycle daemon. GTC (default) keeps the order live until executed or cancelled. DAY orders auto-cancel if not executed within 24 hours; GTD orders auto-cancel at expiresAt. On expiry, BUY escrow is refunded, SELL reservations are released, and an order.cancelled webhook fires. IOC is not supported by the current MyStocks internal-book order contract.

expiresAtstring

Required for GTD orders. Stored for OMS expiry governance.

orderInstructionstring

Optional free-text execution instruction for the MyStocks internal-book engine.

stopLossnumber

Optional. Order auto-cancels if the stock falls below this USD price before settlement.

Example: 0.11

takeProfitnumber

Optional. Order auto-settles if the stock rises above this USD price before settlement.

Example: 0.16

Response fields

orderIdstring

Unique order ID. Use to poll status or cancel.

Example: "ord_abc123xyz"

symbolstring

Example: "SCOM.KE"

namestring

Example: "Safaricom PLC"

exchangestring

Example: "NSE"

orderTypeMARKET | LIMIT | STOP | STOP_LIMIT

Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.

Example: "LIMIT"

limitPricenumber | null

Limit price in the stock's local currency (LIMIT / STOP_LIMIT only).

stopPricenumber | null

Stop price in the stock's local currency (STOP / STOP_LIMIT only).

cancelableboolean

Whether the order can be cancelled now (DELETE). True while PENDING or WORKING.

replaceableboolean

Whether the order can be modified now (PATCH). True only for a WORKING resting order.

typeBUY | SELL

PENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED.

quoteIdstring | null

Pre-trade quote ID consumed by this order.

quoteExpiresAtstring | null

quoteUsdPricenumber | null

clientOrderIdstring | null

Partner-supplied order reference.

omsStatusstring | null

Canonical OMS lifecycle status.

timeInForcestring | null

filledQuantitynumber

remainingQuantitynumber

averageFillPricenumber | null

executionVenuestring | null

lastExecutionReportIdstring | null

executionSlaunion

Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING.

quantityinteger

priceAtOrdernumber

Stock price in local currency at submission.

usdPriceAtOrdernumber

USD equivalent of priceAtOrder.

fxRateAtOrdernumber | null

Managed FX rate used for local-to-USD conversion at order submission.

fxSourcestring | null

fxRateAsOfstring | null

fxConversionunion

feenumber

Total fee in USD (base + partner markup).

baseFeenumber

MyStocks base broker fee (0.75% of gross).

partnerMarkupFeenumber

Your markup fee component. Zero if markupBps = 0.

totalAmountnumber

BUY: gross + fee. SELL: gross - fee.

currencystring

Example: "USD"

localCurrencystring

Example: "KES"

rejectionCodestring | null

Structured rejection code. Populated when status = REJECTED.

rejectionReasonstring | null

Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED.

cancelledAtstring | null

settledAtstring | null

Set when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence.

createdAtstring

settlementStatusPENDING | SETTLED | FAILED

orderLifecyclestring | null

EXPIRED for expiry; expiry is not a rejection.

cancelReasonstring | null

Response codes

201Order placed.

400Insufficient wallet balance.

409Idempotency conflict — duplicate in-flight.

422Business rule violation in production; master-account trading is not available in sandbox.

Request reference

Sandbox unsupported

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/v1/partner/trade

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "example": "ord_abc123xyz",
      "description": "Unique order ID. Use to poll status or cancel."
    },
    "symbol": {
      "type": "string",
      "example": "SCOM.KE"
    },
    "name": {
      "type": "string",
      "example": "Safaricom PLC"
    },
    "exchange": {
      "type": "string",
      "example": "NSE"
    },
    "orderType": {
      "type": "string",
      "enum": [
        "MARKET",
        "LIMIT",
        "STOP",
        "STOP_LIMIT"
      ],
      "description": "Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.",
      "example": "LIMIT"
    },
    "limitPrice": {
      "type": [
        "number",
        "null"
      ],
      "description": "Limit price in the stock's local currency (LIMIT / STOP_LIMIT only)."
    },
    "stopPrice": {
      "type": [
        "number",
        "null"
      ],
      "description": "Stop price in the stock's local currency (STOP / STOP_LIMIT only)."
    },
    "cancelable": {
      "type": "boolean",
      "description": "Whether the order can be cancelled now (DELETE). True while PENDING or WORKING."
    },
    "replaceable": {
      "type": "boolean",
      "description": "Whether the order can be modified now (PATCH). True only for a WORKING resting order."
    },
    "type": {
      "type": "string",
      "enum": [
        "BUY",
        "SELL"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "PENDING",
        "WORKING",
        "PARTIALLY_FILLED",
        "PROCESSING",
        "COMPLETED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "EXPIRED"
      ],
      "description": "PENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED."
    },
    "quoteId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pre-trade quote ID consumed by this order."
    },
    "quoteExpiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "quoteUsdPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "clientOrderId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Partner-supplied order reference."
    },
    "omsStatus": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "RECEIVED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "null"
      ],
      "description": "Canonical OMS lifecycle status."
    },
    "timeInForce": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "DAY",
        "GTC",
        "GTD",
        "null"
      ]
    },
    "filledQuantity": {
      "type": "number"
    },
    "remainingQuantity": {
      "type": "number"
    },
    "averageFillPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "executionVenue": {
      "type": [
        "string",
        "null"
      ]
    },
    "lastExecutionReportId": {
      "type": [
        "string",
        "null"
      ]
    },
    "executionSla": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "model": {
              "type": "string",
              "enum": [
                "LIVE_DEALING_DESK"
              ],
              "description": "Execution path covered by this SLA."
            },
            "minMinutes": {
              "type": "integer",
              "example": 1,
              "description": "Earliest expected live execution window, in minutes."
            },
            "maxMinutes": {
              "type": "integer",
              "example": 5,
              "description": "Maximum live execution window, in minutes."
            },
            "targetMinutes": {
              "type": "integer",
              "example": 5,
              "description": "Deadline used by monitoring for breach detection."
            },
            "clockStartedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the order entered the live execution queue."
            },
            "targetFillBy": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "Latest expected fill or rejection timestamp."
            },
            "status": {
              "type": "string",
              "enum": [
                "WITHIN_SLA",
                "BREACHED",
                "MET",
                "CANCELLED"
              ]
            },
            "breachedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "lastCheckedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING."
    },
    "quantity": {
      "type": "integer"
    },
    "priceAtOrder": {
      "type": "number",
      "description": "Stock price in local currency at submission."
    },
    "usdPriceAtOrder": {
      "type": "number",
      "description": "USD equivalent of priceAtOrder."
    },
    "fxRateAtOrder": {
      "type": [
        "number",
        "null"
      ],
      "description": "Managed FX rate used for local-to-USD conversion at order submission."
    },
    "fxSource": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "MYSTOCKS_MANAGED_FX",
        "PARTNER_PROVIDED_LEGACY",
        "null"
      ]
    },
    "fxRateAsOf": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "fxConversion": {
      "anyOf": [
        {
          "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": "null"
        }
      ]
    },
    "fee": {
      "type": "number",
      "description": "Total fee in USD (base + partner markup)."
    },
    "baseFee": {
      "type": "number",
      "description": "MyStocks base broker fee (0.75% of gross)."
    },
    "partnerMarkupFee": {
      "type": "number",
      "description": "Your markup fee component. Zero if markupBps = 0."
    },
    "totalAmount": {
      "type": "number",
      "description": "BUY: gross + fee. SELL: gross - fee."
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "localCurrency": {
      "type": "string",
      "example": "KES"
    },
    "rejectionCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Structured rejection code. Populated when status = REJECTED.",
      "enum": [
        "INSUFFICIENT_FUNDS",
        "KYC_REQUIRED",
        "MARKET_CLOSED",
        "COMPLIANCE_HOLD",
        "TECHNICAL_ISSUE",
        "OTHER",
        "null"
      ]
    },
    "rejectionReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED."
    },
    "cancelledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "settledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Set when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "canonicalStatus": {
      "type": "string",
      "enum": [
        "PENDING",
        "WORKING",
        "PARTIALLY_FILLED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "EXPIRED"
      ]
    },
    "settlementStatus": {
      "type": "string",
      "enum": [
        "PENDING",
        "SETTLED",
        "FAILED"
      ]
    },
    "orderLifecycle": {
      "type": [
        "string",
        "null"
      ],
      "description": "EXPIRED for expiry; expiry is not a rejection."
    },
    "cancelReason": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

curl -X POST 'https://mystocks.africa/api/v1/partner/trade' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "symbol": "SCOM.KE",
  "type": "BUY",
  "quantity": 100,
  "quoteId": "qt_paste_from_quote_response"
}'

The September 2026 MyStocks Partner API & Developer Platform Specification brings together eight commercial API products, their endpoint inventory, error vocabulary, webhook events, and integration requirements.

Download PartnerAPI.pdf (339 pages) · Browse all eight products · Open API Reference

Environments and authentication

Environment	Base URL	Standard API key prefix
Production	`https://mystocks.africa/api/v1/partner`	`pk_live_`
Sandbox	`https://mystocks.africa/api/sandbox/v1/partner`	`sk_sandbox_`

Send API credentials using Authorization: Bearer or x-api-key. Read-only data keys, OAuth client credentials, and Firebase-authenticated console operations have distinct scopes and requirements. Follow the authentication guide and each operation's security definition in the API Reference.

Use sandbox and paper trading for integration testing. Check the product catalog's sandbox column before calling an operation: production-only endpoints and unsupported stubs are not fully simulated.

Request safety and operational contracts

Topic	Online guidance
Idempotency	Authentication and contract guarantees: mutation requirements, bootstrap exceptions, 24-hour replay retention, and payload mismatch handling.
Rate limits	Tier quotas and response headers: Starter 100, Growth 500, and Enterprise 2,000 requests per minute, with contracted custom limits where applicable.
HTTP errors and dealing-desk rejections	Errors: distinguish synchronous request failures from asynchronous order rejection reasons.
Webhook signatures and retries	Webhooks: event directory, raw-body HMAC-SHA256 verification, delivery logs, and retry behavior.
Event streams	Server-Sent Events: connection limits, heartbeats, replay, and reconnection.
Production readiness	Going live, controlled production pilot, and general availability.

Product and endpoint reference

The product catalog covers all 203 operations across 156 route paths. Every product page includes method, path, operation ID, purpose, sandbox availability, and links to its implementation guides. The interactive reference contains request and response schemas, parameters, examples, and status codes.

The PDF's additional discovery and infrastructure section is separate from this inventory. Use OpenAPI JSON or OpenAPI YAML for public schema discovery. Partner brand discovery supports the hosted tenant experience; scheduler workers are operated by MyStocks and require internal credentials.

Clarifications for the PDF edition

The downloadable PDF is preserved as supplied. Use the following current online guidance when integrating:

PDF wording or example	Online contract clarification
OpenAPI 3.0.3 / API version 1.0.0	The published machine-readable specification declares OpenAPI 3.1.0, API version 1. Use the version declared in the downloaded schema.
`partners.mystock.africa` and tenant examples with `mystock.africa`	The partner domain is `partners.mystocks.africa`; tenant domains use `mystocks.africa`. The documentation is also available at `https://partners.mystocks.africa/partners/docs`.
OAuth JWT and `sec_live_` secret examples	Follow the OAuth client credentials guide: the client secret is the API key; returned access tokens use `ms_oauth_` and expire after 15 minutes. Do not infer a JWT format.
Every operation has strict sandbox parity	Per-operation OpenAPI metadata and the product catalogs identify sandbox availability and unsupported stubs. Master `POST /trade` and `POST /payout` return 422 in sandbox; trade through a sub-account instead.
Every mutation requires idempotency with no exceptions	Credential bootstrap and recovery operations have documented exceptions. See authentication.
`x-ratelimit-reset` is in milliseconds	`X-RateLimit-Reset` is a Unix timestamp in seconds; `Retry-After` is also in seconds.
Per-second burst allowances	Use the published minute quotas and concurrent stream limits; the PDF's burst figures are not a separate documented entitlement.
Real-time market intelligence or order book analytics	African equity quotes are 15-minute delayed. Webhooks and SSE carry account and market-status events, not streaming price ticks or Level-2 depth. See market data.
Six webhook retries across two hours	The retry schedule contains six attempts including the initial attempt, with scheduled retry delays. See webhook delivery semantics; do not treat two hours as a guaranteed total delivery window.
Generated sample values	Treat examples as illustrative; required fields, enums, eligibility, authentication, and response status codes come from the operation contract.

For signature verification, use the webhook guide's examples, including malformed-signature handling, rather than calling timingSafeEqual on unchecked buffers of potentially unequal length.

Appendices and implementation resources

Exchanges, hours, and settlement: use market data and exchange calendars, market-status responses, and the trade lifecycle. The PDF's typical-hours table does not account for holidays or instrument-specific settlement.
KYC: follow sub-account onboarding and KYC, AML, and sanctions. Confirm applicable limits and evidence requirements during onboarding; do not interpret the PDF's tier table as automatic approval or an unlimited trading entitlement.
SDKs and tooling: use SDKs and developer tools for supported package names and installation instructions, and the API Tester for requests.
Support: contact support@mystocks.africa or use the partner support workflow.

Was this page useful?

Your signal helps us tighten partner onboarding docs.

Send note

Last updated on

Partner API Products

Partner Capability Index