# Hosted API operational handoff

> Coordinate hosted approval, funding, execution, payouts and reconciliation with MyStocks operations.

# How does my trading app connect to MyStocks operations?

Sandbox is an isolated simulation. Hosted Live approval, API credentials, installation licensing and external settlement are separate states. A successful Sandbox journey never approves a production organization or moves real funds.

| Partner action               | Admin task                                                                   | Shared state and evidence                                                        |
| ---------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Submit hosted application    | Review identity and business, approve the organization and production access | Application and organization status, authorized decision, notification and audit |
| Remit firm funding           | Match payment reference, currency and actual receipt before crediting float  | One canonical ledger credit, reference, reviewer and available firm balance      |
| Fund a customer              | Review exceptions and available firm float                                   | Atomic firm-to-customer transfer, customer wallet and ledger entries             |
| Submit a stock order         | Review partner-attributed order in `/admin/dealing-room`                     | Order ID, partner business name, reserved cash/units, executions and remainder   |
| Subscribe to a fund or bond  | Review the corresponding pending investment order and allocation             | Reserved USD, NAV/FX, approved allocation, holding and transaction               |
| Return customer cash to firm | Review account restrictions and settlement holds                             | Customer debit and firm credit; this is not an external payout                   |
| Request an external payout   | Authorize treasury decision and confirm provider outcome                     | Beneficiary, reserved amount, approval, provider reference and ledger            |
| Reconcile a period           | Compare the canonical ledger with independent payment/custody records        | As-of period, discrepancies, evidence and signed review                          |
| Report a delivery problem    | Review webhook attempts and an owned support case                            | Event ID, signature, retries, communication and audit                            |

## What should I show my customer while an order is pending?

Show the actual API order status, reserved balance and filled versus remaining quantity. Request acceptance is not execution. A fill is not independent settlement. Do not enable withdrawals against unsettled proceeds when settlement holds apply. Use event IDs and idempotent handlers; reconnect an event stream with its last event ID.

## How do I safely retry money movement?

Use the same canonical `subAccountId`, endpoint, payload and `Idempotency-Key` for the same logical operation. A changed payload is a new intent and must not be retried under the old key. Inspect wallet, order and ledger state before resolving an uncertain outcome. Use canonical IDs consistently even when an external-ID alias is supported.

## Can a closed account be reopened?

No. A closed account is terminal and cannot be changed back to active through metadata updates. Frozen accounts can be restored through the authorized lifecycle. Money-moving handlers recheck ownership and active state inside their transaction. Create a new account for a new customer relationship; retain the old account's records for review.

## What evidence completes an acceptance test?

Partner action → admin task → authorized decision → shared state → notification → audit evidence → automated test. Email queue insertion proves notification intent, not inbox delivery. Dealing-room tests prove the internal handoff, not execution at an external exchange. A reconciliation response without independent custody/payment data remains incomplete.

Operations can use [admin readiness](/admin/partners?tab=readiness) to find required decisions and their workspaces. Production-only checks need an isolated approved test integration; the public Sandbox reference app does not execute treasury or dealing-room decisions.

## Currency closure and frozen customer orders

The organization currency workspace shows customer currency closure blockers and next actions. These are currency snapshots: no blockers does not confirm that orders, holdings or settlement checks pass. Closure rechecks all obligations atomically. A frozen customer's pending order can be rejected in the dealing room, but approval cannot create a new fill. Currency policy approval does not bypass customer account status.

## How do I read across my customers?

Use `GET /orders/blotter` for owned customer orders. The master `GET /orders` remains a master-account endpoint. The blotter orders customers by customer ID, then orders by newest `createdAt` within each customer; it is not a globally chronological feed. Each request scans at most 20 customers and 1,000 orders and returns up to 200 matching orders (default 50). Follow `nextCursor` while `hasMore` is true, even when a filtered page is empty. Keep the same filters and environment on continuation.

```bash
curl --get "$API_BASE/orders/blotter" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "symbol=SCOM.KE" \
  --data-urlencode "limit=50"
```

Use `GET /users/summary?userIds=customer-1,external-2` for 1–20 distinct owned customer IDs or external IDs. Unknown and foreign customers receive the same per-item `NOT_FOUND` error. Each account includes its canonical identity, actual currency wallets, USD buying power, currency closure blockers and read timestamp. The request reads each account independently and reuses the wallet accounting checks; it is not an atomic consolidated statement or a replacement for final closure checks. Wallet read cost depends on each customer's wallet, entitlement and order history. Do not add USD and KES balances together.

```bash
curl --get "$API_BASE/users/summary" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "userIds=customer-1,external-2"
```

Set `API_BASE=https://partners.mystocks.africa/api/sandbox/v1/partner` for virtual Sandbox accounts, or `/api/v1/partner` for approved Live access. Customer reads appear in the partner currency workspace and `/admin/partners` currency workspace. Admin reads require ledger-view permission; hosted API reads require the relevant scoped credential.
