# Quick Start

> Go from zero to your first executed trade — register, create a sub-account, deposit, quote, and trade — all against the MyStocks sandbox with no approval required.

Go from zero to your first executed trade — all against the sandbox, no approval required.

This guide covers customer accounts and trading. For prices and charts only, start with the [Market Data guide](/partners/docs/getting-started-market-data). For other workflows, browse the [integration guides](/partners/docs/guides).

[View QuickstartChecklist in the HTML guide](https://partners.mystocks.africa/partners/docs/quickstart)

### Register and get your API key

[Try endpoint: createRegister](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=createRegister)

Sign in (or sign up) on the [partner portal](/partners/sandbox) first — `/register` authenticates
with your **Firebase ID token** from that session, not an API key. The easiest path is the portal's
"Create Key" or "Rotate Key" button, which calls this endpoint for you. Rotation is explicit because
calling it again invalidates the previous sandbox key.

```bash
curl -X POST https://mystocks.africa/api/sandbox/v1/register \
  -H "Authorization: Bearer <firebase-id-token>"
```

```json
{ "apiKey": "sk_sandbox_xxxxxxxxxxxxxxxx", "walletBalance": 100000, "currency": "USD" }
```

### Create a sub-account for your end-user

[Try endpoint: createUsers](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=createUsers)

Each of your end-users gets an isolated wallet. Alternatively use
`POST /api/sandbox/v1/partner/auto-register` (idempotent — safe to call on every login).

```sh
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users \
-H "Authorization: Bearer sk_sandbox_<your_key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-user-42-001" \
-d '{ "externalId": "user_42", "displayName": "Jane Doe", "email": "jane@example.com" }'
```

```javascript
const user = await fetch("https://mystocks.africa/api/sandbox/v1/partner/users", {
method: "POST",
headers: { Authorization: "Bearer sk_sandbox_<your_key>", "Content-Type": "application/json", "Idempotency-Key": "create-user-42-001" },
body: JSON.stringify({ externalId: "user_42", displayName: "Jane Doe", email: "jane@example.com" }),
}).then((res) => res.json());
```

```python
user = requests.post(
  "https://mystocks.africa/api/sandbox/v1/partner/users",
  headers={"Authorization": "Bearer sk_sandbox_<your_key>", "Idempotency-Key": "create-user-42-001"},
  json={"externalId": "user_42", "displayName": "Jane Doe", "email": "jane@example.com"},
).json()
```

```sdk
const user = await client.subAccounts.create({
externalId: "user_42",
displayName: "Jane Doe",
email: "jane@example.com",
}, { idempotencyKey: "create-user-42-001" });
```

```json
{
  "subAccountId": "usr_xxxxxxxxxxxx",
  "externalId": "user_42",
  "displayName": "Jane Doe",
  "kycStatus": "NONE",
  "status": "active",
  "wallet": { "currency": "USD", "balance": 0 }
}
```

### Deposit funds

[Try endpoint: createDeposit](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=createDeposit)

Production deposits follow collection of a real customer payment. Sandbox deposits move virtual funds only. Send a USD amount or a supported local amount and currency; MyStocks reads the managed FX configuration and returns the USD credit and conversion metadata. Unsupported currencies or unavailable rates fail without moving funds. Use conversion quote terms and the applied rate in the receipt; bulk `/fx/rates` export is disabled. Never assume a fixed conversion rate.

```bash
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/deposit \
  -H "Authorization: Bearer sk_sandbox_<your_key>" \
  -H "Idempotency-Key: dep_user42_001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 65000, "currency": "KES", "note": "Mpesa ref mpesa_QHJ29SK" }'
```

The following response is illustrative **only if the configured rate is 130 KES per USD**; the actual rate and balances are returned by the API. Sandbox responses also include `simulationOnly: true`.

```json
{ "message": "Deposit successful.", "subAccountId": "usr_xxxxxxxxxxxx", "amount": 500, "currency": "USD", "fxRate": 130, "fxSource": "MYSTOCKS_MANAGED_FX", "newSubBalance": 500, "newMasterBalance": 99500 }
```

### Optional: assert KYC

[Try endpoint: createKyc](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=createKyc)

You run KYC in your own onboarding flow, then assert the result. The sandbox permits synthetic
customers to trade without KYC so a new integration can reach its first fill immediately. Production
still requires `VERIFIED`; an unverified production sub-account receives `403 KYC_REQUIRED`. Use this
optional sandbox step, or the `KYC_REQUIRED` simulation scenario in the API Tester, to exercise your
production error and recovery UX.

```bash
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/kyc \
  -H "Authorization: Bearer sk_sandbox_<your_key>" \
  -H "Idempotency-Key: kyc_user42_001" \
  -H "Content-Type: application/json" \
  -d '{ "status": "VERIFIED", "level": "BASIC", "reference": "kyc_provider_ref_123" }'
```

```json
{ "message": "KYC status updated.", "subAccountId": "usr_xxxxxxxxxxxx", "kycStatus": "VERIFIED", "kycLevel": "BASIC" }
```

### Get a quote (returns the required quoteId)

[Try endpoint: getQuote](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=getQuote)

Every MARKET trade — sandbox and production — starts with a quote. LIMIT, STOP and STOP\_LIMIT orders follow the quote-free resting-order contract in the trading guide. It returns the latest delayed price observation, the full fee
breakdown, and a single-use `quoteId` that expires after 60 seconds.

```bash
curl "https://mystocks.africa/api/sandbox/v1/partner/quote/SCOM.KE?type=BUY&quantity=1000&subAccountId=usr_xxxxxxxxxxxx" \
  -H "Authorization: Bearer sk_sandbox_<your_key>"
```

This illustration uses 130 KES/USD, a client price of 16.5 KES, a 0.75% fee and cent rounding. Live quotes disclose their actual terms; do not calculate an execution price from this example.

```json
{
  "quoteId": "qt_9f2c81d4b7a3",
  "quoteExpiresAt": "2026-07-07T09:46:00Z",
  "quoteTtlSeconds": 60,
  "symbol": "SCOM.KE",
  "name": "Safaricom PLC",
  "exchange": "NSE",
  "currency": "KES",
  "type": "BUY",
  "quantity": 1000,
  "localPrice": 16.5,
  "usdPrice": 0.126923,
  "gross": 126.92,
  "fee": 0.95,
  "totalCost": 127.87,
  "sufficientFunds": true
}
```

### Place a trade on behalf of the sub-account

[Try endpoint: createUserTrade](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=createUserTrade)

Pass the `quoteId` from the previous step within 60 seconds. You can use the full exchange-qualified
symbol (`SCOM.KE`) or just the bare ticker (`SCOM`) — the API resolves it automatically.

```sh
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/trade \
-H "Authorization: Bearer sk_sandbox_<your_key>" \
-H "Idempotency-Key: trade_user42_001" \
-H "Content-Type: application/json" \
-d '{ "symbol": "SCOM.KE", "type": "BUY", "quantity": 1000, "quoteId": "qt_9f2c81d4b7a3" }'
```

```javascript
const order = await fetch("https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/trade", {
method: "POST",
headers: {
  Authorization: "Bearer sk_sandbox_<your_key>",
  "Idempotency-Key": "trade_user42_001",
  "Content-Type": "application/json",
},
body: JSON.stringify({ symbol: "SCOM.KE", type: "BUY", quantity: 1000, quoteId: "qt_9f2c81d4b7a3" }),
}).then((res) => res.json());
```

```python
order = requests.post(
  "https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/trade",
  headers={"Authorization": "Bearer sk_sandbox_<your_key>", "Idempotency-Key": "trade_user42_001"},
  json={"symbol": "SCOM.KE", "type": "BUY", "quantity": 1000, "quoteId": "qt_9f2c81d4b7a3"},
).json()
```

```sdk
const order = await client.subAccounts.trade(
"usr_xxxxxxxxxxxx",
{ symbol: "SCOM.KE", type: "BUY", quantity: 1000, quoteId: "qt_9f2c81d4b7a3" },
{ idempotencyKey: "trade_user42_001" },
);
```

```json
{
  "status": "FILLED",
  "orderId": "ord_xxxxxxxxxxxx",
  "subAccountId": "usr_xxxxxxxxxxxx",
  "type": "BUY",
  "symbol": "SCOM.KE",
  "quantity": 1000,
  "totalCost": 127.87,
  "newSubBalance": 372.13,
  "note": "Order filled instantly in sandbox. Live production trades are PENDING until filled or rejected."
}
```

## Check order history (or use webhooks)

```bash
curl "https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/orders?limit=1" \
  -H "Authorization: Bearer sk_sandbox_<your_key>"
```

In sandbox, sub-account trades settle instantly (`FILLED`) with no admin queue. In production,
status progresses `PENDING → FILLED` (or `REJECTED`) through the execution flow during exchange hours. v1 may emit legacy `COMPLETED` as an alias of `FILLED`.

## Settlement timeline — production

| Phase                     | Timeline                                                                                                             | Notes                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| MyStocks live fill target | Within 5 minutes                                                                                                     | Market orders submitted during exchange hours. Outside hours → queued for next session.          |
| Exchange settlement       | Read the configured market cycle from `GET /market/settlement` and verify the current broker/CSD terms before launch | A configured cycle is an operational expectation, not proof that a particular order has settled. |

The **MyStocks execution target** is when your `PENDING` order becomes `FILLED` — this triggers the
`order.filled` webhook and credits shares/proceeds to the wallet. The **exchange settlement cycle**
(T+2/T+3) governs when the underlying title and custody transfer through the exchange depository; it
can leave credited SELL proceeds unavailable for withdrawal. Ledger balance, available-to-trade cash and withdrawable cash are distinct; read buying power and settlement fields before cash-out. Full per-exchange data is at `GET /api/v1/partner/market/settlement`.

## Order lifecycle

1\. POST /trade: submit order

2\. PENDING: funds escrowed

3\. FILLED: order.filled

A `PENDING` order can instead terminate as `REJECTED` (BUY escrow refunded · `order.rejected`) or,
while still `PENDING`, be `CANCELLED` by your `DELETE` (`order.cancelled`).

> **Sandbox only:** orders skip the escrow wait and resolve immediately as `FILLED`. A live order can be
> cancelled while it is still `PENDING` (or `WORKING`, for resting limit/stop orders) — once it reaches a
> terminal state (`FILLED`, `REJECTED`, `CANCELLED`, or `EXPIRED`) the DELETE returns HTTP 409.

### Cancelling a PENDING order

While an order is still `PENDING`, cancel it with a DELETE. For BUY orders the escrowed funds are
refunded atomically; SELL orders carry no wallet impact so cancellation is immediate. Once an order
has filled (`FILLED`) or otherwise reached a terminal state (`REJECTED`, `CANCELLED`, `EXPIRED`) it can no
longer be cancelled (HTTP 409). A
successful cancellation fires an `order.cancelled` webhook so downstream systems react without polling.

```bash
# Cancel a sub-account order
curl -X DELETE "https://mystocks.africa/api/v1/partner/users/usr_xxxxxxxxxxxx/orders/ord_xxxxxxxxxxxx" \
  -H "Authorization: Bearer pk_live_<your_key>" \
  -H "Idempotency-Key: cancel-subaccount-order-ord_xxxxxxxxxxxx"

# Cancel a master-account order
curl -X DELETE "https://mystocks.africa/api/v1/partner/orders/ord_xxxxxxxxxxxx" \
  -H "Authorization: Bearer pk_live_<your_key>" \
  -H "Idempotency-Key: cancel-master-order-ord_xxxxxxxxxxxx"
```

### Modifying a resting order (replace)

A resting `LIMIT`/`STOP`/`STOP_LIMIT` order sits in status `WORKING` until its price triggers. While
`WORKING` you can modify its `limitPrice`, `stopPrice`, and/or `quantity` with a `PATCH` — the order
keeps the **same `orderId`**, and the BUY escrow or SELL unit reservation is adjusted by the delta
atomically. Increasing a BUY escrow beyond the available balance returns `400 INSUFFICIENT_FUNDS`; the
`replaceable` field on the order tells you when a modify is allowed. Market orders cannot be modified —
cancel and re-submit instead. Requires an `Idempotency-Key`.

```bash
# Re-price and re-size a WORKING resting order (same orderId)
curl -X PATCH "https://mystocks.africa/api/v1/partner/users/usr_xxxxxxxxxxxx/orders/ord_xxxxxxxxxxxx" \
  -H "Authorization: Bearer pk_live_<your_key>" \
  -H "Idempotency-Key: replace_ord_xxxxxxxxxxxx_1" \
  -H "Content-Type: application/json" \
  -d '{ "limitPrice": 21.5, "quantity": 150 }'
```

A successful modify fires an `order.replaced` webhook and writes a `REPLACE` execution report.

> **Skip polling — use webhooks.** Register a webhook URL to receive `order.filled`, `order.rejected`,
> and `order.cancelled` events in real time. See [Webhooks](/partners/docs/webhooks), and the
> [Going Live](/partners/docs/going-live) checklist when you're ready to switch to production.

## Can I choose Hosted API, OnPrem or both?

Yes. Select **Hosted API**, **OnPrem** or **Both** when applying. Your connection preference does not grant an entitlement. One partner account shows **API access** and **Installations & licenses** as separate sections on the dashboard overview. You can change your personal connection preference there.

The **Sandbox / Live** selector checks access on the server. Hosted Live approval and an OnPrem production activation are separate decisions. An OnPrem evaluation remains Sandbox-only even if the same organization has Hosted Live approval. Conversely, a separately approved Hosted Live service is not disabled merely because an installation license expires. Existing accounts retain their previous access policy until partner operations makes an explicit Hosted Live decision.

| Credential                      | Purpose                                                             | Lifecycle                                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sandbox API key                 | Synthetic calls in `/api/sandbox/v1/`; quotes delayed by 15 minutes | Created and rotated in the Sandbox console; cannot authorize Live calls                                                                                      |
| Production API key              | Approved Live API calls in `/api/v1/partner/`                       | Issued/rotated for the organization, independently suspendable and revocable; API scopes and commercial entitlements still apply                             |
| Installation license credential | Authorizes a particular gateway, installation identity and domain   | Temporary with an admin-set expiry or permanent and revocable; retrieval, renewal, domain verification and installation proof are separate from API approval |

Partner operations uses **Access & deployments** in `/admin/partners/{partnerId}` to review Hosted Live approval independently from domain verification, installation status, license expiry and the next required action. An approval or block requires an authorized administrator, a review reason, explicit confirmation and recent sign-in. It records audit evidence and queues a customer notification. Installation production activation retains its own DNS, identity and commercial checks.
