Add offset/limit pagination to list endpoints

.env.example

@@ -61,6 +61,8 @@ QUEUE_CONCURRENCY=5
 # Counters are stored in Redis so every API replica enforces the same budget.
 THROTTLE_AUTH_LIMIT=10
 THROTTLE_API_LIMIT=120
+# Per-agent tier: agent-identified traffic (x-agent-id / agent-bound API keys).
+THROTTLE_AGENT_LIMIT=300
 THROTTLE_WEBHOOK_LIMIT=30
 THROTTLE_TTL=60
 # Burst limits — short-term spike allowance per tier (requests per second)

API_DOCUMENTATION.md

@@ -83,8 +83,9 @@ List wallets for the organization.
 **Query Parameters:**
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| page | number | No | Page number (default: 1) |
-| limit | number | No | Items per page (default: 10) |
+| offset | number | No | Rows to skip (default: 0); mutually exclusive with `page` |
+| page | number | No | Page number, alternative to `offset` (default: 1) |
+| limit | number | No | Items per page (default: 50, max: 200) |
 
 **Authentication:** Bearer token required
 
@@ -168,8 +169,9 @@ List transactions for the organization.
 **Query Parameters:**
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| page | number | No | Page number (default: 1) |
-| limit | number | No | Items per page (default: 10) |
+| offset | number | No | Rows to skip (default: 0); mutually exclusive with `page` |
+| page | number | No | Page number, alternative to `offset` (default: 1) |
+| limit | number | No | Items per page (default: 50, max: 200) |
 
 **Authentication:** Bearer token required
 
@@ -228,8 +230,9 @@ List policies for the organization.
 **Query Parameters:**
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| page | number | No | Page number (default: 1) |
-| limit | number | No | Items per page (default: 10) |
+| offset | number | No | Rows to skip (default: 0); mutually exclusive with `page` |
+| page | number | No | Page number, alternative to `offset` (default: 1) |
+| limit | number | No | Items per page (default: 50, max: 200) |
 
 **Authentication:** Bearer token required
 
@@ -322,8 +325,9 @@ List budgets for the organization.
 **Query Parameters:**
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| page | number | No | Page number (default: 1) |
-| limit | number | No | Items per page (default: 10) |
+| offset | number | No | Rows to skip (default: 0); mutually exclusive with `page` |
+| page | number | No | Page number, alternative to `offset` (default: 1) |
+| limit | number | No | Items per page (default: 50, max: 200) |
 
 **Authentication:** Bearer token required
 
@@ -372,6 +376,51 @@ Delete a budget.
 
 ---
 
+## Request Correlation
+
+Every response includes the selected request ID in the `x-request-id` header and the standard response envelope. A caller-supplied ID is accepted only when it is 1-128 ASCII characters, starts with a letter or digit, and otherwise contains only letters, digits, `.`, `_`, `:`, or `-`. Invalid values are replaced with a server-generated UUID. The selected ID is propagated as typed event/job metadata and is isolated per concurrent request.
+
+## Audit History (`/audit`)
+
+### GET `/audit`
+List audit records in reverse chronological order using a stable `(createdAt, id)` keyset.
+
+**Query Parameters:** `limit` defaults to 20 and is bounded to 1-100; `cursor` is the opaque `nextCursor` from the previous response; optional `actorId`, `action`, `resourceId`, `from`, and `to` filters apply within the authenticated organization. `from` and `to` are inclusive ISO 8601 timestamps and `from` must not be later than `to`.
+
+The response `meta` includes `limit`, `hasNext`, and `nextCursor` (null on the final page). New records inserted after a page is read do not shift subsequent pages.
+
+**Example:** `GET /audit?limit=20&actorId=user-123&action=wallet.created`
+
+## Outbound Webhook Signatures
+
+Webhook creation and secret rotation responses disclose the signing secret once. Later list, get, update, delivery, and audit responses never include it. Store the secret securely and rotate it when compromised.
+
+Every delivery includes `x-astroid-signature`, `x-astroid-signature-version`, `x-astroid-timestamp`, and `x-astroid-event-id`. `x-astroid-delivery` remains an alias for the event ID. The signature header is `v1=<lowercase hex HMAC-SHA256>` and the version header is `v1`.
+
+The canonical signed bytes are UTF-8 `v1.<timestamp>.<event-id>.` followed by the exact raw HTTP body bytes. Each retry uses the same event ID and body, with a fresh timestamp and signature. Consumers should also reject timestamps outside their chosen replay window.
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function verifyAstroidWebhook({ secret, headers, rawBody }) {
+  const version = headers['x-astroid-signature-version'];
+  const timestamp = headers['x-astroid-timestamp'];
+  const eventId = headers['x-astroid-event-id'];
+  const received = headers['x-astroid-signature'];
+  if (version !== 'v1' || !/^\d{1,12}$/.test(timestamp) || !eventId) return false;
+  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
+
+  const prefix = Buffer.from(`v1.${timestamp}.${eventId}.`, 'utf8');
+  const expected = createHmac('sha256', secret)
+    .update(Buffer.concat([prefix, rawBody]))
+    .digest();
+  const match = /^v1=([0-9a-f]{64})$/.exec(received);
+  if (!match) return false;
+  const actual = Buffer.from(match[1], 'hex');
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+```
+
 ## Health Probes (`/health`)
 
 The liveness and readiness probes are served **outside** the API prefix, so
@@ -424,10 +473,27 @@ under the API prefix at `GET /{API_PREFIX}/health/readiness`,
 ## Common Types
 
 ### Pagination Query
+Every list endpoint accepts the same query parameters.
+
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| page | number | 1 | Page number |
-| limit | number | 10 | Items per page |
+| offset | number | 0 | Zero-based number of rows to skip. Mutually exclusive with `page` |
+| page | number | 1 | 1-based page number, an alternative to `offset` |
+| limit | number | 50 | Items per page, capped at 200 |
+| sort | string | createdAt | Sort field (restricted to an allow-list per endpoint) |
+| order | `asc` \| `desc` | desc | Sort direction |
+
+Negative, non-integer or non-numeric values, a `limit` above 200, or supplying both `offset` and `page` return `400 Bad Request`.
+
+Paginated responses carry the total row count in the `X-Total-Count` header and in `meta`:
+```json
+{
+  "success": true,
+  "data": [],
+  "meta": { "offset": 50, "page": 2, "limit": 50, "total": 120, "totalPages": 3, "hasNext": true, "hasPrev": true },
+  "requestId": "req_..."
+}
+```
 
 ### Error Response
 All endpoints return errors as [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details with `Content-Type: application/problem+json`: