API product catalogExecution & Order Management (OMS)

Place trade

Execution & Order Management (OMS)

POST

/trade

Place trade

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

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

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"
    }
  }
}

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"
}'

GET /quote/{symbol}

GET /users/{userId}/preflight