API product catalogExecution & Order Management (OMS)

List orders

Execution & Order Management (OMS)

GET

/orders

List orders

Sandbox availablelistOrders

Returns your partner order history. Filter by status, symbol, or date range. Filters from/to are enforced against createdAt. ISO dates cover full UTC days. Sparse matches may yield an empty page with hasMore=true; follow nextCursor. Each call scans at most 1000 source records. Invalid limits, dates and cursors return 400.

Parameters

symbolstringquery

Example: SCOM.KE

fromstringquery

ISO date (whole UTC day) or timezone-qualified ISO date-time; invalid or reversed bounds return 400.

Example: 2026-01-01

tostringquery

ISO date (whole UTC day) or timezone-qualified ISO date-time; invalid or reversed bounds return 400.

Example: 2026-03-31

cursorstringquery

Opaque cursor from nextCursor of the previous response. Omit for the first page.

limitintegerquery

Example: 50

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

ordersobject[]Required

orders[].orderIdstring

Unique order ID. Use to poll status or cancel.

Example: "ord_abc123xyz"

orders[].symbolstring

Example: "SCOM.KE"

orders[].namestring

Example: "Safaricom PLC"

orders[].exchangestring

Example: "NSE"

orders[].orderTypeMARKET | LIMIT | STOP | STOP_LIMIT

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

Example: "LIMIT"

orders[].limitPricenumber | null

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

orders[].stopPricenumber | null

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

orders[].cancelableboolean

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

orders[].replaceableboolean

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

orders[].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.

orders[].quoteIdstring | null

Pre-trade quote ID consumed by this order.

orders[].quoteExpiresAtstring | null

orders[].quoteUsdPricenumber | null

orders[].clientOrderIdstring | null

Partner-supplied order reference.

orders[].omsStatusstring | null

Canonical OMS lifecycle status.

orders[].timeInForcestring | null

orders[].filledQuantitynumber

orders[].remainingQuantitynumber

orders[].averageFillPricenumber | null

orders[].executionVenuestring | null

orders[].lastExecutionReportIdstring | null

orders[].executionSlaunion

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

orders[].quantityinteger

orders[].priceAtOrdernumber

Stock price in local currency at submission.

orders[].usdPriceAtOrdernumber

USD equivalent of priceAtOrder.

orders[].fxRateAtOrdernumber | null

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

orders[].fxSourcestring | null

orders[].fxRateAsOfstring | null

orders[].fxConversionunion

orders[].feenumber

Total fee in USD (base + partner markup).

orders[].baseFeenumber

MyStocks base broker fee (0.75% of gross).

orders[].partnerMarkupFeenumber

Your markup fee component. Zero if markupBps = 0.

orders[].totalAmountnumber

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

orders[].currencystring

Example: "USD"

orders[].localCurrencystring

Example: "KES"

orders[].rejectionCodestring | null

Structured rejection code. Populated when status = REJECTED.

orders[].rejectionReasonstring | null

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

orders[].cancelledAtstring | null

orders[].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.

orders[].createdAtstring

countintegerRequired

hasMorebooleanRequired

nextCursorstring | nullRequired

Response codes

200Order list.

Sandbox playground

Read-only sandbox request

status Optional · querysymbol Optional · queryfrom Optional · queryto Optional · querycursor Optional · querylimit Optional · querySandbox API keyYour key stays in this page’s memory.

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

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "required": [
    "orders",
    "count",
    "hasMore",
    "nextCursor"
  ],
  "properties": {
    "orders": {
      "type": "array",
      "items": {
        "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"
          }
        }
      }
    },
    "count": {
      "type": "integer"
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

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

GET /opportunities/{id}

DELETE /orders/{orderId}