# Reports

> Read-only reporting across all sub-accounts — AUM, positions, fees, revenue, dividends, monthly invoices, dividend calendar, audit log, usage analytics, the daily reconciliation pack, per-order executions, and the unified client-activity feed. Most support ?format=csv.

Portfolio snapshots, revenue reporting, dividends, and audit logs across all sub-accounts. All
reporting endpoints are read-only and safe to call on every page load. Most support `?format=csv` for
spreadsheet or data-warehouse export.

## AUM

`GET` `/report/aum`

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

Current aggregate cash and stored portfolio valuations across your sub-accounts, with a per-account breakdown. This is not a historical snapshot and does not represent streaming market valuations. Live uses stored holding `currentValue`; Sandbox uses units times the stored `currentUsdPrice`. `generatedAt` marks response assembly, not quote freshness or an atomic valuation timestamp.

```json
{
  "partnerKey": "example-partner", "totalAum": 150, "totalCash": 50,
  "totalPortfolioValue": 100, "currency": "USD", "subAccountCount": 1,
  "generatedAt": "2026-10-07T10:00:00.000Z", "historical": false,
  "valuationBasis": "stored_holdings_currentValue",
  "breakdown": [{ "subAccountId": "usr_example", "externalId": "customer-1", "cash": 50, "portfolioValue": 100, "totalValue": 150 }]
}
```

Empty reports include `breakdown: []` and zero totals. `?format=csv` downloads the same per-account values. Invalid formats return 400. Historical `?asOf=` requests return **422 `HISTORICAL_REPORT_UNSUPPORTED`**; do not use this endpoint for historical reconciliation. The separate reconciliation report retains its documented date filters.

## Positions

`GET` `/report/positions`

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

All open equity positions across all sub-accounts. Supports `?exchange=`, `?symbol=`, `?format=csv`.

```json
{ "positions": [{ "subAccountId": "usr_abc123", "symbol": "SCOM.KE", "quantity": 1000, "avgCostUsd": 0.01269, "currentPriceUsd": 0.0126, "marketValue": 12.6, "unrealizedPnl": -0.09 }], "totalValue": 38400.0, "count": 1 }
```

## Fees & revenue

`GET` `/report/fees` · `GET` `/report/revenue`

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

`/report/fees` — trading fees paid across all sub-accounts (base fees + partner markup). `/report/revenue`
— partner markup revenue per trade with net payable. Both filter by `?from=`/`?to=`.

```jsonc
// /report/fees
{ "period": { "from": "2026-05-01", "to": "2026-05-31" }, "totalBaseFees": 62.25, "totalMarkupFees": 18.75, "totalFees": 81.0, "tradeCount": 83, "currency": "USD" }

// /report/revenue
{ "period": { "from": "2026-05-01", "to": "2026-05-31" }, "totalMarkupRevenue": 124.5, "totalTrades": 83, "netPayable": 124.5, "currency": "USD" }
```

## Dividends & calendar

`GET` `/report/dividends` · `GET` `/dividends/calendar`

`/report/dividends` — aggregated dividend report across all sub-accounts, with per-account breakdown.
`/dividends/calendar` — upcoming declarations; `partnerEligible: true` flags dividends where at least
one of your sub-accounts holds the stock.

```jsonc
// /dividends/calendar
{ "dividends": [{ "symbol": "EQTY.KE", "name": "Equity Group Holdings", "declarationDate": "2026-07-15", "exDividendDate": "2026-07-22", "paymentDate": "2026-08-01", "amountPerShare": 4.0, "currency": "KES", "partnerEligible": true }], "count": 1 }
```

## Invoice

`GET` `/report/invoice`

Monthly statement of account with platform fees owed, partner markup earned, float movements, payouts,
issued invoices, and manual adjustments. Pass `?month=YYYY-MM` or `?format=csv`.

```json
{
  "month": "2026-05",
  "summary": { "feesOwed": 62.25, "markupEarned": 124.5, "approvedTopups": 10000, "processedPayouts": 2500 },
  "statementOfAccount": {
    "feesOwedUsd": 62.25,
    "markupEarnedUsd": 124.5,
    "floatMovements": [{ "type": "TOPUP", "status": "APPROVED", "amount": 10000 }],
    "payouts": [{ "status": "COMPLETED", "amount": 2500 }],
    "invoices": [],
    "adjustments": [],
    "netPartnerPositionUsd": 7532.25
  }
}
```

## Reconciliation

`GET` `/report/reconciliation`

Daily reconciliation pack for B2B operations: cash ledger, securities ledger, unsettled trades, fees,
dividends, corporate actions, and custody positions across the master account and all sub-accounts.
Pass `?asOf=YYYY-MM-DD` (or `?from=`/`?to=`). Add
`?format=csv&section=cash|securities|unsettled|fees|dividends|custody|summary` to download one section.

```json
{ "asOf": "2026-06-30", "summary": { "cashTotalUsd": 45230.5, "securitiesTotalUsd": 38400.0, "unsettledCount": 2, "feesTotalUsd": 81.0 }, "cash": [{ "accountType": "SUBACCOUNT", "userId": "usr_abc123", "balanceUsd": 1240.0 }], "unsettled": [{ "orderId": "ord_abc123", "symbol": "SCOM.KE", "status": "PENDING", "totalUsd": 126.0 }] }
```

## Executions

`GET` `/orders/{orderId}/executions` · `GET` `/users/{userId}/orders/{orderId}/executions`

OMS-style execution reports for an order — every lifecycle transition (accepted, locked, settled,
rejected, cancelled) with timestamps. Available for partner-level and sub-account orders.

Filled orders do not return an empty execution list. For orders created before the immutable execution
journal existed, the endpoint derives one compatibility FILL from the order record and marks it
`synthetic: true` with `sourceEvidence: "LEGACY_ORDER_STATE"`. Native journal reports remain immutable
and authoritative; consumers can distinguish the compatibility row explicitly.

```json
{ "orderId": "ord_abc123", "executions": [{ "sequence": 1, "event": "ACCEPTED", "at": "2026-06-30T09:00:01Z" }, { "sequence": 3, "event": "FILLED", "at": "2026-06-30T10:12:00Z", "settledUsd": 126.0 }], "count": 3 }
```

## Audit, usage & activity

`GET` `/audit` · `GET` `/usage` · `GET` `/client-activity`

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

`/audit` — paginated API call log (endpoint, method, status, IP, user-agent, latency) including key
events (`key.rotated`, `key.revoked`, `settings.updated`). `/usage` — 90-day rolling analytics: requests
per day, error rate, current rate-limit window. `/client-activity` — unified reverse-chronological feed
of trades, deposits, withdrawals, subscriptions, redemptions, and KYC changes across all sub-accounts.

```jsonc
// /usage
{ "tier": "starter", "limitPerMinute": 100, "currentWindow": { "requestsUsed": 43, "requestsRemaining": 57, "resetsAt": "2026-06-04T09:46:00Z" }, "daily": [{ "date": "2026-06-04", "requests": 1240, "errors": 3 }] }
```
