docs: sync from backend faf2221, frontend 022ecb6 — Task #7 derived destinations sweep autostart, recordSweep fix, multi-seller checkout

03 - API Reference/Payment API.md

@@ -365,6 +365,90 @@ Payouts are SHKeeper-side outbound transfers (admin pays the seller from a hot w
 ```
 **Response 200:** `{ success, data: { /* payout receipt */ } }`
 
+## Derived Destinations
+
+These endpoints manage per-(buyer, sellerOffer) ephemeral payment addresses.
+
+| Method | Route | Auth | Purpose |
+|--------|-------|------|---------|
+| `GET` | `/api/payment/derived-destinations` | Admin | List destinations with filters/pagination |
+| `POST` | `/api/payment/derived-destinations/sweep` | Admin | Sweep **all** active destinations |
+| `POST` | `/api/payment/derived-destinations/:id/sweep` | Admin | Sweep **one** destination |
+| `POST` | `/api/payment/derived-destinations/:id/balance` | Admin | Refresh on-chain balance for one destination |
+| `GET` | `/api/payment/derived-destinations/config/health` | Admin | Verify xpub and sweep signer config |
+| `POST` | `/api/payment/derived-destinations/cron/start` | Admin | Start the sweep cron |
+| `POST` | `/api/payment/derived-destinations/cron/stop` | Admin | Stop the sweep cron |
+| `GET` | `/api/payment/derived-destinations/cron/status` | Admin | Check if sweep cron is running |
+
+### `GET /api/payment/derived-destinations`
+
+Query params: `buyerId`, `sellerOfferId`, `status` (`active|swept`), `address`, `chainId`, `page`, `limit`.
+
+**Response 200:**
+```json
+{
+  "success": true,
+  "data": {
+    "destinations": [
+      {
+        "_id": "...",
+        "buyerId": "...",
+        "sellerOfferId": "...",
+        "address": "0x...",
+        "derivationPath": "m/44'/60'/0'/0/5",
+        "derivationIndex": 5,
+        "chainId": 56,
+        "status": "active",
+        "balance": "1000000000",
+        "sweepCount": 0,
+        "totalSwept": "0",
+        "createdAt": "..."
+      }
+    ],
+    "pagination": { "page": 1, "limit": 20, "total": 42 }
+  }
+}
+```
+
+### `POST /api/payment/derived-destinations/sweep`
+
+Body: `{ chainId?: number, tokenSymbol?: string, minSweepAmount?: string }` — all optional.
+
+**Response 200:** `{ success: true, data: { results: SweepResult[] } }`
+
+Each `SweepResult`:
+```ts
+{
+  destinationId: string;
+  address: string;
+  status: 'success' | 'error' | 'skipped';
+  txHash?: string;
+  amount?: string;
+  error?: string;
+}
+```
+
+### `POST /api/payment/derived-destinations/:id/sweep`
+
+Same result shape as above, but for a single destination.
+
+### `GET /api/payment/derived-destinations/config/health`
+
+**Response 200:**
+```json
+{
+  "success": true,
+  "data": {
+    "xpubValid": true,
+    "xpubFingerprint": "0xabcd...",
+    "signerType": "build-only",
+    "signerHealthy": true,
+    "chainId": 56,
+    "masterWallet": "0x..."
+  }
+}
+```
+
 ## Status model
 
 [[Payment]] uses the statuses below across all providers:

07 - Development/Environment Variables.md

@@ -310,6 +310,7 @@ DERIVED_DESTINATION_CHAIN_ID=56
 DERIVED_DESTINATION_SWEEP_SIGNER=build-only
 DERIVED_DESTINATION_MIN_SWEEP_AMOUNT=0
 DERIVED_DESTINATION_SWEEP_INTERVAL_MS=300000
+DERIVED_DESTINATION_SWEEP_AUTOSTART=true
 
 # OAuth
 GOOGLE_CLIENT_ID=

09 - Audits/Activity Log.md

@@ -11,6 +11,18 @@ entries on top. Maintained by agents per the rule in `../AGENTS.md`.
 
 ---
 
+### 2026-05-28 — backend@faf2221, frontend@022ecb6 — Task #7 derived destinations: sweep autostart, recordSweep fix, multi-seller checkout UX
+
+**Commits:** backend `faf2221` (2.6.42 → 2.6.43), frontend `022ecb6` (2.6.42 → 2.6.43)
+**Touched:**
+- Backend: `src/app.ts`, `src/models/DerivedDestination.ts`, `src/models/Payment.ts`, `src/services/payment/requestNetwork/requestNetworkPayInService.ts`, `src/services/payment/wallets/derivedDestinations.ts`, `.env.example`
+- Frontend: `src/sections/payment/checkout/rn-in-house-checkout-view.tsx`, `src/sections/request-template/request-template-checkout-payment.tsx`, `src/web3/components/multi-seller-provider-payment.tsx`, `src/sections/payment/checkout/rn-multi-checkout-view.tsx`, `src/app/checkout/request-network/multi/page.tsx`
+**Why:** PRD items D/E/F + frontend cart-aware checkout (A). Auto-start sweep cron on boot; fix `recordSweep` to `$inc` totalSwept instead of `$setOnInsert`; widen Payment unique index to include `sellerOfferId` for multi-seller carts; add multi-seller checkout wrapper and wire into template + request flows.
+**Verification:** Pushed to `integrate-main-into-development` on both repos — Woodpecker builds pending.
+**Linked docs updated:** [[03 - API Reference/Payment API]] (derived-destination endpoints)
+
+---
+
 ### 2026-05-28 — backend@e46be98, frontend@af77b3c — add nick-doc sync rule + version bumps
 
 **Commits:** backend `e46be98` (2.6.24 → 2.6.25), frontend `af77b3c` (2.6.25 → 2.6.26)