# 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

<MethodTag m="GET" /> `/report/aum`

<TryEndpoint id="listAum" />

Total assets under management across all sub-accounts, broken down by asset class and exchange.

```json
{ "totalAum": 45230.5, "currency": "USD", "breakdown": { "equities": 38400.0, "bonds": 4200.0, "funds": 2630.5, "opportunities": 0 }, "byExchange": { "NSE": 22100, "NGX": 10300, "JSE": 6000 } }
```

## Positions

<MethodTag m="GET" /> `/report/positions`

<TryEndpoint id="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

<MethodTag m="GET" /> `/report/fees` · <MethodTag m="GET" /> `/report/revenue`

<TryEndpoint id="listFees" label="Try fees report" />

`/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

<MethodTag m="GET" /> `/report/dividends` · <MethodTag m="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

<MethodTag m="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

<MethodTag m="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

<MethodTag m="GET" /> `/orders/{orderId}/executions` · <MethodTag m="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

<MethodTag m="GET" /> `/audit` · <MethodTag m="GET" /> `/usage` · <MethodTag m="GET" /> `/client-activity`

<TryEndpoint id="listClientActivity" label="Try client activity" />

`/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 }] }
```