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

2026-05-28 17:15:18 +04:00
parent 3b50311a81
commit 4017aee800
3 changed files with 97 additions and 0 deletions
--- a/Reference/Payment
+++ b/Reference/Payment
@@ -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: