# Daily Processes and Reconciliation

> Run a repeatable daily control process for cash, securities, unsettled trades, fees, dividends, corporate actions, and custody positions.

Persist each complete reconciliation pack as part of your operational evidence. The API response alone is not an immutable historical snapshot. Run it after the relevant market close and again after settlement windows or correction events.

## Daily sequence

1. Fetch `GET /report/reconciliation?asOf=YYYY-MM-DD`.
2. Persist the JSON response, `X-Request-ID`, and retrieval timestamp.
3. Compare the cash section with MyStocks wallet balances and your internal ledger.
4. Compare securities with sub-account holdings and custody positions.
5. Classify every unsettled trade by order, execution, expected settlement date, and status.
6. Reconcile fees, dividends, and corporate-action distributions.
7. Record exceptions with an owner, expected resolution date, and supporting event IDs.
8. Export CSV sections for operations or audit retention.

## Available sections

Use `format=csv` with one of `cash`, `securities`, `unsettled`, `fees`, `dividends`, `corporate_actions`, `custody_positions`, or `summary`. The JSON response is better for automated ingestion; CSV is useful for review and data-warehouse loads.

```bash
curl 'https://mystocks.africa/api/v1/partner/report/reconciliation?asOf=2026-06-30' \
  -H 'Authorization: Bearer pk_live_<your_key>'
```

## Exception handling

The JSON response includes `proof.status`:

- `BALANCED` — beneficial units match pooled custody units within tolerance;
- `EXCEPTIONS` — inspect `proof.custody.exceptions` for the exact instrument and unit difference;
- `INCOMPLETE` — no pooled custody records were available, so custody equality has not been proven.

`proof.cashRollForward` states completed credits, completed debits, net movement, the derived opening
balance, and the equation used to reach the reported closing balance. This is an internal ledger
roll-forward; partners should still compare it with their own opening balance and external bank records.

Do not infer a missing record as a zero balance. Investigate stale data, unsettled trades, rejected orders, corporate-action adjustments, and custody differences. Use `/client-activity`, order executions, signed events, and the [Statements and Confirms](/partners/docs/statements-confirms) workflow to resolve mismatches.

The reconciliation endpoint is read-only. It is safe to retry, but persist the request ID and source period so repeated exports do not create duplicate internal records.

## Sandbox reconciliation limits

`GET /api/sandbox/v1/partner/report/reconciliation` reads current virtual USD wallets and holdings, including the master account and at most 500 sub-accounts. It returns `status: INCOMPLETE`, actual ledger totals, null custody totals and `fixture: false`. There is no independent custody comparison. Use `format=csv` for current account totals. Historical `asOf`, `from` or `to` receive HTTP 422; section filtering receives HTTP 400. Do not treat simulated fills, event delivery or virtual balances as live settlement proof.

## 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.

## Currency-specific statement snapshots

In `/admin/partners`, historical cash reconciliation accepts one supported currency per report. Supply opening and closing statement balances and evidence for that same currency, including firm and customer scope. Other currencies are excluded and require separate reports. Completed reports retain their source cutoff and digest; sign-off requires a balanced complete scan and explicit review. Corrections after the cutoff require a new report rather than rewriting a signed result.

The current reconciliation API's cash proof remains USD-only and excludes non-USD movements from its USD roll-forward. Current wallet views are not historical snapshots. Operator-attested cash boundaries are not independent bank/custody integration proof; securities, external settlement and custody acceptance remain separate obligations.

## Completeness and retention

Check completeness warnings, per-account record limits and account-count limits before accepting totals. A bounded/truncated response is not a complete business ledger. Use paginated underlying account, transaction and order reads to collect the full cohort, or keep the signoff blocked until operations provides a complete export. Date filters can select transactions while wallet and position values remain current-state; do not label those values as an historical end-of-day balance. Retain a dated, hashed snapshot in your approved immutable evidence store and compare it with independent broker/custodian and bank/provider statements. A ledger-only roll-forward does not establish external settlement.
