# Pagination

> MyStocks list endpoints use cursor-based pagination — pass ?limit= and ?cursor=; every response carries hasMore and nextCursor so you never calculate offsets. Per-endpoint defaults and maximums included.

List endpoints use **cursor-based pagination**. Pass `?limit=` to control page size and `?cursor=` to
advance to the next page. Every paginated response includes `hasMore` and `nextCursor` so you never
need to calculate offsets.

## Request parameters

limit (integer, optional): Items per page. Default and max vary by endpoint (see below). Orders, users and market intelligence reject invalid or out-of-range limits with 400.

cursor (string, optional): Opaque cursor returned as nextCursor in the previous response. Omit on the first request. Treat cursors as opaque strings — do not construct or parse them.

## Response fields

count (integer, optional): Number of items in this page (≤ limit).

hasMore (boolean, optional): true means continue scanning with nextCursor; a filtered page can contain no matches. false means scanning has finished.

nextCursor (string | null, optional): Pass as ?cursor= on the next request. null when hasMore is false.

## Limit defaults & maximums by endpoint

| Endpoint                           | Default | Max |
| ---------------------------------- | ------- | --- |
| `GET /users`                       | 100     | 200 |
| `GET /market-intel`                | 20      | 100 |
| `GET /orders`                      | 50      | 200 |
| `GET /users/{userId}/orders`       | 50      | 200 |
| `GET /users/{userId}/transactions` | 50      | 200 |
| `GET /audit`                       | 50      | 200 |
| `GET /webhooks/{id}/deliveries`    | 20      | 100 |

## Fetching all pages — JavaScript

```javascript
async function fetchAllOrders(apiKey) {
  const orders = [];
  let cursor = null;

  do {
    const url = new URL('https://mystocks.africa/api/v1/partner/orders');
    url.searchParams.set('limit', '200');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, { headers: { 'x-api-key': apiKey } });
    const page = await res.json();

    orders.push(...page.orders);
    cursor = page.nextCursor; // null on the last page
  } while (cursor);

  return orders;
}
```

## Filtered pages and cursor lifetime

Master orders honor `status`, `from` and `to`. Date-only bounds include the entire UTC day; ISO date-times specify precise bounds. Invalid or reversed dates return 400. Users accept `status=active|frozen|closed|ALL` and a direct `externalId` lookup; status also applies to that lookup.

Orders and users scan at most 1,000 records per request. An empty matching page can therefore have `hasMore: true`; continue with its `nextCursor` rather than stopping at `count: 0`. Do not interpret count as the total matching collection size.

Market intelligence accepts `exchange`, `symbol`, `limit` and `cursor`, orders by creation time descending with ID as a tie-breaker, and returns `articles`, `count`, `hasMore`, `nextCursor`.

Keep the same filters when advancing. Cursors are not snapshots: deletions, edits or a changed filter can invalidate them. Unknown cursors return 400 on these endpoints; user cursors must belong to the requesting partner. Restart from the first page if necessary. Do not reuse cursors across keys or environments.

## Customer ledger and Sandbox order queries

Customer transactions in both environments accept inclusive `from` and `to` UTC dates or timezone-aware ISO timestamps. Date-only `to` includes `23:59:59.999Z`. Invalid or reversed bounds, limits outside 1–200 and unknown owned-account cursors return `400 VALIDATION_ERROR`.

Customer order pages and Sandbox test-tool orders return `hasMore` and `nextCursor`. Keep following continuation on empty filtered pages; the per-request scan budget is 1,000 records. `GET /test-tools/orders` requires `subAccountId` in Sandbox.

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