From 24c46d956734de750e9248914afcaa93a8be5ead Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 01/24] Enable the namespace re-export transform
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`typechain` emits `export * as factories from './factories'`, and the
React Native preset does not transform namespace re-exports. The plugin
was declared but never enabled, so `TransactionListTop` failed to parse
the moment `src/plugins/contracts` existed — which it does after any
`npm install`, since `prepare` generates it. Metro needs that transform
as much as jest does, so it belongs in the shared config.
---
 babel.config.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/babel.config.js b/babel.config.js
index 9adf2e4f163..78781a0afbd 100644
--- a/babel.config.js
+++ b/babel.config.js
@@ -4,6 +4,10 @@ module.exports = function (api) {
   return {
     presets: ['module:@react-native/babel-preset'],
     plugins: [
+      // `typechain` emits `export * as factories from './factories'` in
+      // src/plugins/contracts, which the React Native preset does not
+      // transform on its own.
+      '@babel/plugin-transform-export-namespace-from',
       isAndroid
         ? './node_modules/r3-hack/node_modules/react-native-reanimated/plugin'
         : 'react-native-worklets/plugin'

From a22727ec522e1c6b5f271f88a71d4c5def2c40aa Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 02/24] Declare the hash.js dependency

src/util/hmacAuth.ts imports hashjs directly, but the package was only
ever resolved transitively. Declare it so a clean install and the Node
CLI bundle both get it.
---
 package-lock.json | 1 +
 package.json      | 1 +
 2 files changed, 2 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index acf16d4e315..bcd70a1f96d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -56,6 +56,7 @@
         "ethers": "^5.7.2",
         "expo": "^53.0.0",
         "expo-quick-actions": "^5.0.0",
+        "hash.js": "^1.1.7",
         "jsrsasign": "^11.1.0",
         "marked": "^15.0.9",
         "p-debounce": "^4.0.0",
diff --git a/package.json b/package.json
index f1c21af3bdd..2990de46f27 100644
--- a/package.json
+++ b/package.json
@@ -117,6 +117,7 @@
     "ethers": "^5.7.2",
     "expo": "^53.0.0",
     "expo-quick-actions": "^5.0.0",
+    "hash.js": "^1.1.7",
     "jsrsasign": "^11.1.0",
     "marked": "^15.0.9",
     "p-debounce": "^4.0.0",

From 259544171b5714c7d4f44d1129ccad1ab8000bd0 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 03/24] Make network and utils Node-safe

`network.ts`, `utils.ts` and the locale boot each pulled React Native in
through their module load paths, so nothing outside the app could fetch
from the info server, format an amount, or pick a language table.

Fiat constants and helpers move to `fiatConstants.ts`, and
`getOsVersion` to `rnUtils.ts` alongside the other React Native-only
helpers, with `keysStore.ts` following it there. `network.ts` takes its
server lists and device fields through `configureNetwork` and
`initInfoServer(params)` rather than reading `appConfig` and
`react-native-device-info` at module scope.

Locale boot splits the same way: `bootLocale.ts` applies a language
table and number format with no React Native imports, and
`initLocale.ts` stays GUI-only, feeding it what `react-native-localize`
reports.

Capturing those device fields is separate from starting the poll:
`configureInfoServer` records them synchronously, so `fetchPublicRollup`
works for whoever calls it first, while `initInfoServer` owns the
polling and the decision to skip the unsigned launch fetch.
`fetchWaterfall` refuses an empty server list rather than handing it to
`asyncWaterfall`, which awaits `Promise.race([])` and never settles.
---
 CHANGELOG.md                                 |   8 +
 eslint.config.mjs                            |   5 +-
 index.ts                                     |   4 +
 src/__tests__/util/network.test.ts           |  47 +++++
 src/actions/LogActions.tsx                   |   2 +-
 src/app.ts                                   |  86 ++++++++-
 src/components/cards/InfoCardCarousel.tsx    |   2 +-
 src/components/scenes/GuiPluginListScene.tsx |   3 +-
 src/components/scenes/WalletDetailsScene.tsx |   4 +-
 src/components/services/EdgeCoreManager.tsx  |   2 +-
 src/constants/WalletAndCurrencyConstants.ts  | 192 ++-----------------
 src/hooks/useRampPreferredProviders.ts       |   2 +-
 src/locales/bootLocale.ts                    |  73 +++++++
 src/locales/initLocale.ts                    |  16 ++
 src/locales/intl.ts                          |  35 ++--
 src/locales/strings.ts                       |   7 -
 src/util/WebUtils.ts                         |  21 +-
 src/util/attestation.ts                      |   7 +-
 src/util/fiatConstants.ts                    | 184 ++++++++++++++++++
 src/util/infoUtils.ts                        |   2 +-
 src/util/keysStore.ts                        |   2 +-
 src/util/network.ts                          | 146 +++++++++-----
 src/util/promoCardUtils.ts                   |   2 +-
 src/util/rnUtils.ts                          |  12 ++
 src/util/txDisplay/currencyCodes.ts          |  47 +++++
 src/util/utils.ts                            | 130 ++++++-------
 26 files changed, 691 insertions(+), 350 deletions(-)
 create mode 100644 src/__tests__/util/network.test.ts
 create mode 100644 src/locales/bootLocale.ts
 create mode 100644 src/locales/initLocale.ts
 create mode 100644 src/util/fiatConstants.ts
 create mode 100644 src/util/txDisplay/currencyCodes.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 597e7c137fb..68c1fba0f7f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased (develop)
 
+- changed: Moved transaction display metadata, denominations, spam-threshold resolution, local settings, the transaction export pipeline, transaction tagging, locale selection, exchange rates and the network helpers out of GUI-only modules so they load under plain Node, with no behaviour change to the app.
+- fixed: Historical rates no longer re-query a pair the server has answered but cannot price, which looped without delay and never settled the caller's promise.
+- fixed: Historical rate requests are capped below the rates server's 100-asset limit, where the previous check let a batch reach 101 and the rejection priced the whole page at zero.
+- fixed: An unusable OS number format no longer also falls the language back to English when resolving info-server localized strings.
+- fixed: `splitCategory` keeps an unrecognised category prefix as part of the subcategory rather than discarding it, so opening and saving such a transaction no longer writes the prefix away.
+- fixed: Transaction fiat amounts are fetched in one batch rather than in groups of ten, each of which paid a fresh one-second debounce.
+- fixed: QBO exports escape a non-ASCII payee or memo, so the `ENCODING:USASCII` header the file declares is true.
+- added: Edge CLI (`edge-cli`) and its engine daemon: a long-lived process owning an `EdgeContext`, a JSON REST API over a Unix socket with an optional loopback TCP listener, and a thin client that spawns the engine on demand. 117 routes, generated command table, help text and OpenAPI reference.
 - added: `YOLO_OTP_KEY` env setting, which lets auto-login reach a 2FA-protected account on a device that has no login stash for it yet.
 - added: Slow-sync explainer card on Bitcoin-family wallets with a long transaction history.
 - added: Logbox disable option to env.json
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 17295731ec9..7556c2a4425 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -491,8 +491,6 @@ export default [
       'src/util/CryptoAmount.ts',
       'src/util/cryptoTextUtils.ts',
 
-      'src/util/exchangeRates.ts',
-
       'src/util/FioAddressUtils.ts',
       'src/util/getAccountUsername.ts',
       'src/util/GuiPluginTools.ts',
@@ -508,7 +506,7 @@ export default [
 
       'src/util/ukComplianceUtils.ts',
       'src/util/utils.ts',
-      'src/util/WebUtils.ts',
+
       'src/util/withWatchableProps.ts'
     ],
     languageOptions: {
@@ -532,6 +530,7 @@ export default [
       'android/*',
       'artifacts/*',
       'ios/*',
+      'lib/*',
       'src/plugins/contracts/*',
       'src/controllers/edgeProvider/client/rolledUp.js',
       'src/controllers/edgeProvider/injectThisInWebView.js'
diff --git a/index.ts b/index.ts
index 3a27fe7aef1..1e8c5262e6d 100644
--- a/index.ts
+++ b/index.ts
@@ -5,6 +5,10 @@
 // no-ops and the home screen shortcuts never appear.
 import 'expo-modules-core'
 import 'react-native-gesture-handler'
+// Locale selection must precede ./src/app, whose import graph evaluates
+// locales/strings: anything capturing lstrings at module scope would otherwise
+// be frozen in English.
+import './src/locales/initLocale'
 import './src/app'
 import './src/perf'
 
diff --git a/src/__tests__/util/network.test.ts b/src/__tests__/util/network.test.ts
new file mode 100644
index 00000000000..1d3a3f90985
--- /dev/null
+++ b/src/__tests__/util/network.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it, jest } from '@jest/globals'
+import type { EdgeFetchFunction } from 'edge-core-js'
+
+import { configureNetwork, fetchInfo, fetchWaterfall } from '../../util/network'
+
+describe('fetchWaterfall', () => {
+  it('refuses an empty server list instead of hanging', async () => {
+    // `asyncWaterfall([])` awaits `Promise.race([])`, which never settles, so
+    // an unconfigured list used to hang the caller forever.
+    await expect(fetchWaterfall([], 'v1/infoRollup/edge')).rejects.toThrow(
+      /No servers configured for v1\/infoRollup\/edge/
+    )
+  })
+
+  it('fetches from a configured server', async () => {
+    const doFetch = jest.fn(async () => ({
+      ok: true
+    })) as unknown as EdgeFetchFunction
+    const result = await fetchWaterfall(
+      ['https://info1.example'],
+      'v1/thing',
+      undefined,
+      5000,
+      doFetch
+    )
+
+    expect(result).toEqual({ ok: true })
+    expect(doFetch).toHaveBeenCalledWith(
+      'https://info1.example/v1/thing',
+      undefined
+    )
+  })
+})
+
+describe('configureNetwork', () => {
+  it('keeps the production info servers when given an empty list', async () => {
+    configureNetwork({ infoServers: [] })
+    const doFetch = jest.fn(async () => ({
+      ok: true
+    })) as unknown as EdgeFetchFunction
+
+    await fetchInfo('v1/infoRollup/edge', undefined, 5000, doFetch)
+
+    const [uri] = (doFetch as unknown as jest.Mock).mock.calls[0] as [string]
+    expect(uri).toMatch(/^https:\/\/info[12]\.edge\.app\//)
+  })
+})
diff --git a/src/actions/LogActions.tsx b/src/actions/LogActions.tsx
index 00a5a4d6b2c..0cbc012aa3a 100644
--- a/src/actions/LogActions.tsx
+++ b/src/actions/LogActions.tsx
@@ -31,7 +31,7 @@ import type { ThunkAction } from '../types/reduxTypes'
 import { getCurrencyCode } from '../util/CurrencyInfoHelpers'
 import { base58 } from '../util/encoding'
 import { clearLogs, logWithType, readLogs } from '../util/logger'
-import { getOsVersion } from '../util/utils'
+import { getOsVersion } from '../util/rnUtils'
 import { getExchangeRateCacheDump } from './ExchangeRateActions'
 
 const logsUri = 'https://logs1.edge.app/v1/log/'
diff --git a/src/app.ts b/src/app.ts
index 83644f5c0e2..97ebd67d44d 100644
--- a/src/app.ts
+++ b/src/app.ts
@@ -5,11 +5,22 @@
  * rerenders
  */
 // import './wdyr'
+// First, and before anything that can read `lstrings`. ES module imports
+// evaluate in source order, so this makes the ordering `index.ts` describes
+// self-enforcing from *this* entry too: the extraction left it resting on a
+// comment plus one import line in one file, which nothing checks.
+import './locales/initLocale'
+// Then the app-boot wiring, beside its two siblings below. This one rode on
+// a binding-free side-effect import in `src/components/App.tsx`, where
+// Metro's default `inlineRequires` can defer the whole module — so the one
+// wiring that decides how rate-query failures are reported was the one whose
+// evaluation point depended on a bundler transform.
+
 import NetInfo from '@react-native-community/netinfo'
 import * as Sentry from '@sentry/react-native'
 import { Buffer } from 'buffer'
 import { asObject, asString } from 'cleaners'
-import { Appearance, InteractionManager, LogBox } from 'react-native'
+import { Appearance, InteractionManager, LogBox, Platform } from 'react-native'
 import { getVersion } from 'react-native-device-info'
 import RNFS from 'react-native-fs'
 
@@ -23,8 +34,56 @@ import { CONFIG } from './config'
 import { KEYS } from './keys'
 import { config } from './theme/appConfig'
 import type { NumberMap } from './types/types'
+import { initAttestation } from './util/attestation'
+import { willSignInfoRollup } from './util/edgeApiSigner'
 import { log, logToServer } from './util/logger'
-import { initCoinrankList, initInfoServer } from './util/network'
+import { INFO_TEST_SERVER, shouldUseTestServers } from './util/maestro'
+import {
+  configureInfoServer,
+  configureNetwork,
+  initCoinrankList,
+  initInfoServer
+} from './util/network'
+import { getOsVersion } from './util/rnUtils'
+import { runOnce } from './util/runOnce'
+import { checkAppVersion } from './util/versionCheck'
+
+// `CONFIG.INFO_SERVER` overrides the production info servers,
+// e.g. to point a debug build at a local info server. Absent in production
+// builds.
+configureNetwork({
+  infoServers:
+    CONFIG.INFO_SERVER != null && CONFIG.INFO_SERVER.length > 0
+      ? CONFIG.INFO_SERVER
+      : shouldUseTestServers()
+      ? [INFO_TEST_SERVER]
+      : undefined,
+  referralServers: config.referralServers ?? [],
+  notificationServers: config.notificationServers
+})
+
+// `keysStore` falls back to `fetchPublicRollup` on the cold-start path, which
+// runs from the first render — before the NetInfo listener below reaches
+// `initInfoServer`. Capturing the parameters here, synchronously, keeps that
+// fallback working whichever lands first.
+/**
+ * The device and app fields the info server is told about.
+ *
+ * One object, because `configureInfoServer` and `initInfoServer` take the
+ * same five and they were written out twice with an identical `onRollup`
+ * closure — the kind of pair that drifts in one place and not the other.
+ */
+const infoServerParams = {
+  osType: Platform.OS.toLowerCase(),
+  osVersion: getOsVersion(),
+  appVersion: getVersion(),
+  appId: config.appId ?? 'edge',
+  onRollup: async () => {
+    await runOnce('checkAppVersion', checkAppVersion)
+  }
+}
+
+configureInfoServer(infoServerParams)
 
 export type Environment = 'development' | 'testing' | 'production'
 
@@ -340,9 +399,26 @@ NetInfo.addEventListener(state => {
   const currentConnectionState = state.isConnected ?? false
   if (!previousConnectionState && currentConnectionState) {
     console.log('Network connected, refreshing info and coinrank...')
-    initInfoServer().catch((err: unknown) => {
-      console.log(err)
-    })
+    // Start attestation at reconnect (idempotent); previously lived in
+    // initInfoServer before network.ts was made Node-safe.
+    initAttestation()
+    // `willSignInfoRollup` reads the native signer, so it is awaited here
+    // rather than inside `network.ts`, which has to stay Node-safe. Its
+    // failure must not skip the refresh: a rejection used to be swallowed by
+    // the outer catch, so the reconnect rollup fetch never ran at all, where
+    // before this branch it always did. `false` means "do not skip the
+    // unsigned fetch", which is the safe reading of "we could not tell".
+    willSignInfoRollup()
+      .catch((error: unknown) => {
+        console.log(error)
+        return false
+      })
+      .then(async skipUnsignedLaunchFetch => {
+        await initInfoServer({ ...infoServerParams, skipUnsignedLaunchFetch })
+      })
+      .catch((error: unknown) => {
+        console.log(error)
+      })
     initCoinrankList().catch((err: unknown) => {
       console.log(err)
     })
diff --git a/src/components/cards/InfoCardCarousel.tsx b/src/components/cards/InfoCardCarousel.tsx
index 10fea2da109..f1cafbe4435 100644
--- a/src/components/cards/InfoCardCarousel.tsx
+++ b/src/components/cards/InfoCardCarousel.tsx
@@ -12,7 +12,7 @@ import { useDispatch, useSelector } from '../../types/reactRedux'
 import type { NavigationBase } from '../../types/routerTypes'
 import { type DisplayInfoCard, getDisplayInfoCards } from '../../util/infoUtils'
 import { addPromoCardToNotifications } from '../../util/promoCardUtils'
-import { getOsVersion } from '../../util/utils'
+import { getOsVersion } from '../../util/rnUtils'
 import { type Anim, EdgeAnim } from '../common/EdgeAnim'
 import { type CarouselRenderItem, EdgeCarousel } from '../common/EdgeCarousel'
 import { useTheme } from '../services/ThemeContext'
diff --git a/src/components/scenes/GuiPluginListScene.tsx b/src/components/scenes/GuiPluginListScene.tsx
index bde7b79d636..de6592ef365 100644
--- a/src/components/scenes/GuiPluginListScene.tsx
+++ b/src/components/scenes/GuiPluginListScene.tsx
@@ -56,8 +56,9 @@ import { filterGuiPluginJson } from '../../util/GuiPluginTools'
 import { getDisplayInfoCards } from '../../util/infoUtils'
 import { infoServerData } from '../../util/network'
 import { bestOfPlugins } from '../../util/ReferralHelpers'
+import { getOsVersion } from '../../util/rnUtils'
 import { logEvent, type OnLogEvent } from '../../util/tracking'
-import { base58ToUuid, getOsVersion } from '../../util/utils'
+import { base58ToUuid } from '../../util/utils'
 import { EdgeCard } from '../cards/EdgeCard'
 import { PaymentOptionCard } from '../cards/PaymentOptionCard'
 import {
diff --git a/src/components/scenes/WalletDetailsScene.tsx b/src/components/scenes/WalletDetailsScene.tsx
index a15947e4691..93f91e67cf3 100644
--- a/src/components/scenes/WalletDetailsScene.tsx
+++ b/src/components/scenes/WalletDetailsScene.tsx
@@ -41,11 +41,11 @@ import type {
 } from '../../types/routerTypes'
 import { getDisplayInfoCards } from '../../util/infoUtils'
 import { coinrankListData, infoServerData } from '../../util/network'
+import { getOsVersion } from '../../util/rnUtils'
 import {
   calculateSpamThreshold,
   convertNativeToDenomination,
-  darkenHexColor,
-  getOsVersion
+  darkenHexColor
 } from '../../util/utils'
 import { EdgeCard } from '../cards/EdgeCard'
 import { InfoCardCarousel } from '../cards/InfoCardCarousel'
diff --git a/src/components/services/EdgeCoreManager.tsx b/src/components/services/EdgeCoreManager.tsx
index c16adbd1d8a..61594b1af56 100644
--- a/src/components/services/EdgeCoreManager.tsx
+++ b/src/components/services/EdgeCoreManager.tsx
@@ -52,7 +52,7 @@ import {
   shouldUseTestServers,
   SYNC_TEST_SERVER
 } from '../../util/maestro'
-import { getOsVersion } from '../../util/utils'
+import { getOsVersion } from '../../util/rnUtils'
 import { LoadingSplashScreen } from '../progress-indicators/LoadingSplashScreen'
 import { showError } from './AirshipInstance'
 import { Providers } from './Providers'
diff --git a/src/constants/WalletAndCurrencyConstants.ts b/src/constants/WalletAndCurrencyConstants.ts
index d7934652e44..9df6dddc1f2 100644
--- a/src/constants/WalletAndCurrencyConstants.ts
+++ b/src/constants/WalletAndCurrencyConstants.ts
@@ -6,17 +6,28 @@ import { Platform } from 'react-native'
 import { lstrings } from '../locales/strings'
 import type { WalletConnectChainId } from '../types/types'
 import { utxoPlugins } from '../util/corePlugins'
+import {
+  FEE_ALERT_THRESHOLD,
+  FEE_COLOR_THRESHOLD,
+  FIAT_CODES_SYMBOLS,
+  FIAT_PRECISION,
+  getFiatSymbol
+} from '../util/fiatConstants'
 import { asMoneroUserSettings, isMoneroEdgeLws } from '../util/monero'
-import { removeIsoPrefix } from '../util/utils'
 
-export const MAX_TOKEN_CODE_CHARACTERS = 7
+// Re-export fiat helpers so existing importers stay unchanged
+export {
+  FEE_ALERT_THRESHOLD,
+  FEE_COLOR_THRESHOLD,
+  FIAT_CODES_SYMBOLS,
+  FIAT_PRECISION,
+  getFiatSymbol
+}
 
-export const FEE_COLOR_THRESHOLD = 2.0 // this is denominated in dollars
-export const FEE_ALERT_THRESHOLD = 5.0 // this is denominated in dollars
+export const MAX_TOKEN_CODE_CHARACTERS = 7
 
 export const MAX_ADDRESS_CHARACTERS = 17 // for displaying a truncated wallet address
 export const MAX_CRYPTO_AMOUNT_CHARACTERS = 10 // includes both whole and fractional characters
-export const FIAT_PRECISION = 2
 const UTXO_MAX_SPEND_TARGETS = 32
 
 // Sync status consts
@@ -1206,177 +1217,6 @@ export function isKeysOnlyModeDate(date: Date): boolean {
 }
 
 export const USD_FIAT = 'iso:USD'
-/**
- * Get the fiat symbol from an iso:[fiat] OR fiat currency code
- */
-export const getFiatSymbol = (isoOrFiatCurrencyCode: string): string => {
-  if (typeof isoOrFiatCurrencyCode !== 'string') return ''
-  const codeWithoutIso = removeIsoPrefix(isoOrFiatCurrencyCode)
-  const out = FIAT_CODES_SYMBOLS[codeWithoutIso.toUpperCase()]
-  return out ?? ''
-}
-export const FIAT_CODES_SYMBOLS: Record<string, string> = {
-  AED: 'د.إ',
-  AFN: '؋',
-  ALL: 'L',
-  AMD: '֏',
-  ANG: 'ƒ',
-  AOA: 'Kz',
-  ARS: '$',
-  AUD: '$',
-  AWG: 'ƒ',
-  AZN: '₼',
-  BAM: 'KM',
-  BBD: '$',
-  BDT: '৳',
-  BGN: 'лв',
-  BIF: 'Fr',
-  BMD: '$',
-  BND: '$',
-  BOB: 'Bs.',
-  BRL: 'R$',
-  BSD: '$',
-  BTN: 'Nu.',
-  BWP: 'P',
-  BYN: 'Br',
-  BZD: '$',
-  CAD: '$',
-  CDF: 'Fr',
-  CHF: 'Fr',
-  CLP: '$',
-  CNY: '¥',
-  COP: '$',
-  CRC: '₡',
-  CUC: '$',
-  CUP: '$',
-  CVE: '$',
-  CZK: 'Kč',
-  DJF: 'Fr',
-  DKK: 'kr',
-  DOP: '$',
-  DZD: 'د.ج',
-  EGP: 'ج.م',
-  ERN: 'Nfk',
-  ETB: 'Br',
-  EUR: '€',
-  FJD: '$',
-  FKP: '£',
-  GBP: '£',
-  GEL: '₾',
-  GGP: '£',
-  GHS: '₵',
-  GIP: '£',
-  GMD: 'D',
-  GNF: 'Fr',
-  GTQ: 'Q',
-  GYD: '$',
-  HKD: '$',
-  HNL: 'L',
-  HRK: 'kn',
-  HTG: 'G',
-  HUF: 'Ft',
-  IDR: 'Rp',
-  ILS: '₪',
-  IMP: '£',
-  INR: '₹',
-  IQD: 'ع.د',
-  IRR: '﷼',
-  ISK: 'kr',
-  JEP: '£',
-  JMD: '$',
-  JOD: 'د.ا',
-  JPY: '¥',
-  KES: 'Sh',
-  KGS: 'с',
-  KHR: '៛',
-  KMF: 'Fr',
-  KPW: '₩',
-  KRW: '₩',
-  KWD: 'د.ك',
-  KYD: '$',
-  KZT: '₸',
-  LAK: '₭',
-  LBP: 'ل.ل',
-  LKR: 'Rs',
-  LRD: '$',
-  LSL: 'L',
-  LYD: 'ل.د',
-  MAD: 'د. م.',
-  MDL: 'L',
-  MGA: 'Ar',
-  MKD: 'ден',
-  MMK: 'Ks',
-  MNT: '₮',
-  MOP: 'P',
-  MRO: 'UM',
-  MRU: 'UM',
-  MUR: '₨',
-  MWK: 'MK',
-  MXN: '$',
-  MYR: 'RM',
-  MZN: 'MT',
-  NAD: '$',
-  NGN: '₦',
-  NIO: 'C$',
-  NOK: 'kr',
-  NPR: '₨',
-  NZD: '$',
-  OMR: 'ر.ع.',
-  PAB: 'B/.',
-  PEN: 'S/.',
-  PGK: 'K',
-  PHP: '₱',
-  PKR: '₨',
-  PLN: 'zł',
-  PRB: 'р.',
-  PYG: '₲',
-  QAR: 'ر.ق',
-  RON: 'lei',
-  RSD: 'дин',
-  RUB: '₽',
-  RWF: 'Fr',
-  SAR: 'ر.س',
-  SBD: '$',
-  SCR: '₨',
-  SDG: 'ج.س.',
-  SEK: 'kr',
-  SGD: '$',
-  SHP: '£',
-  SLL: 'Le',
-  SOS: 'Sh',
-  SRD: '$',
-  SSP: '£',
-  STD: 'Db',
-  SYP: 'ل.س',
-  SZL: 'L',
-  THB: '฿',
-  TJS: 'ЅМ',
-  TMT: 'm',
-  TND: 'د.ت',
-  TOP: 'T$',
-  TRY: '₺',
-  TTD: '$',
-  TVD: '$',
-  TWD: '$',
-  TZS: 'Sh',
-  UAH: '₴',
-  UGX: 'Sh',
-  USD: '$',
-  UYU: '$',
-  UZS: '',
-  VEF: 'Bs',
-  VND: '₫',
-  VUV: 'Vt',
-  WST: 'T',
-  XAF: 'Fr',
-  XCD: '$',
-  XOF: 'Fr',
-  XPF: 'Fr',
-  YER: '﷼',
-  ZAR: 'R',
-  ZMW: 'ZK'
-}
-
 export const FIO_WALLET_TYPE = 'wallet:fio'
 export const FIO_STR = 'FIO'
 export const FIO_PLUGIN_ID = 'fio'
diff --git a/src/hooks/useRampPreferredProviders.ts b/src/hooks/useRampPreferredProviders.ts
index 33459927e12..aaafe80fb21 100644
--- a/src/hooks/useRampPreferredProviders.ts
+++ b/src/hooks/useRampPreferredProviders.ts
@@ -5,7 +5,7 @@ import { getBuildNumber, getVersion } from 'react-native-device-info'
 import { useSelector } from '../types/reactRedux'
 import { filterInfoCards } from '../util/infoUtils'
 import { infoServerData } from '../util/network'
-import { getOsVersion } from '../util/utils'
+import { getOsVersion } from '../util/rnUtils'
 
 /**
  * Ramp provider ids that the account's affiliation prefers for this direction,
diff --git a/src/locales/bootLocale.ts b/src/locales/bootLocale.ts
new file mode 100644
index 00000000000..79d3e03dae7
--- /dev/null
+++ b/src/locales/bootLocale.ts
@@ -0,0 +1,73 @@
+/**
+ * Node-safe locale boot. Mutates `lstrings` and `intl.locale`.
+ * GUI and CLI inject detection; this file must not import react-native.
+ */
+import { setIntlLocale } from './intl'
+import { selectLocale } from './strings'
+
+export interface LocaleSource {
+  languageTag: string
+  decimalSeparator: string
+  groupingSeparator: string
+}
+
+export interface AppliedLocale extends LocaleSource {
+  matched: boolean
+}
+
+const DEFAULT_LANGUAGE_TAG = 'en-US'
+
+let hasApplied = false
+let applied: AppliedLocale = {
+  languageTag: DEFAULT_LANGUAGE_TAG,
+  decimalSeparator: '.',
+  groupingSeparator: ',',
+  matched: true
+}
+
+function isDefaultEnglish(tag: string): boolean {
+  const compact = tag.replace(/[-_]/g, '').toLowerCase()
+  return compact === 'enus' || compact === 'en'
+}
+
+/**
+ * Apply language tables and number format. Call once at process start.
+ *
+ * Idempotent, because both `index.ts` and `src/app.ts` now import the GUI's
+ * boot module: the module cache makes that one evaluation, and a caller that
+ * does reach here twice with the same source gets the same answer rather
+ * than re-merging the tables.
+ */
+export function applyLocale(source: LocaleSource): AppliedLocale {
+  const languageTag =
+    source.languageTag === '' ? DEFAULT_LANGUAGE_TAG : source.languageTag
+  if (
+    hasApplied &&
+    applied.languageTag === languageTag &&
+    applied.decimalSeparator === source.decimalSeparator &&
+    applied.groupingSeparator === source.groupingSeparator
+  ) {
+    return applied
+  }
+  hasApplied = true
+  let matched = true
+  if (!isDefaultEnglish(languageTag)) {
+    matched = selectLocale(languageTag)
+  }
+  setIntlLocale({
+    localeIdentifier: languageTag,
+    decimalSeparator: source.decimalSeparator,
+    groupingSeparator: source.groupingSeparator
+  })
+  applied = {
+    languageTag,
+    decimalSeparator: source.decimalSeparator,
+    groupingSeparator: source.groupingSeparator,
+    matched
+  }
+  return applied
+}
+
+export function getAppliedLocale(): AppliedLocale {
+  return applied
+}
diff --git a/src/locales/initLocale.ts b/src/locales/initLocale.ts
new file mode 100644
index 00000000000..9c5d8c66392
--- /dev/null
+++ b/src/locales/initLocale.ts
@@ -0,0 +1,16 @@
+/**
+ * GUI-only locale boot. Call once at app startup so locales/strings and
+ * locales/intl stay free of react-native-localize module-load side effects.
+ */
+import { getLocales, getNumberFormatSettings } from 'react-native-localize'
+
+import { applyLocale } from './bootLocale'
+
+const [firstLocale = { languageTag: 'en-US' }] = getLocales()
+const { languageTag = 'en-US' } = firstLocale
+const numberFormat = getNumberFormatSettings()
+applyLocale({
+  languageTag,
+  decimalSeparator: numberFormat.decimalSeparator,
+  groupingSeparator: numberFormat.groupingSeparator
+})
diff --git a/src/locales/intl.ts b/src/locales/intl.ts
index 4056a1f3e19..5e37c8b5cda 100644
--- a/src/locales/intl.ts
+++ b/src/locales/intl.ts
@@ -1,7 +1,6 @@
 import { gt, mul, toBns, toFixed } from 'biggystring'
 import { asMaybe } from 'cleaners'
 import { format } from 'date-fns'
-import { getLocales, getNumberFormatSettings } from 'react-native-localize'
 import { sprintf } from 'sprintf-js'
 
 import { asBiggystring } from '../util/cleaners'
@@ -36,11 +35,6 @@ const NATIVE_DECIMAL_SEPARATOR = '.'
 const NUMBER_GROUP_SIZE = 3
 export const locale: IntlLocaleType = { ...EN_US_LOCALE }
 
-// Set the locale at boot:
-const [firstLocale = { languageTag: 'en_US' }] = getLocales()
-const numberFormat = getNumberFormatSettings()
-setIntlLocale({ localeIdentifier: firstLocale.languageTag, ...numberFormat })
-
 /**
  * Formats number input according to user locale
  * Allows decimalSeparator at the end of string
@@ -282,18 +276,30 @@ export function setIntlLocale(l: IntlLocaleType): void {
     throw new Error('Please select locale for internationalization')
   }
 
-  if (
-    l.decimalSeparator === '' ||
-    l.groupingSeparator === '' ||
-    l.localeIdentifier === ''
-  ) {
+  // The number format and the language are separate failures. An OS that
+  // reports an empty separator says nothing about the language, and
+  // discarding the whole locale meant `getLocaleOrDefaultString` — which now
+  // reads `locale.localeIdentifier` — resolved info-server localized strings
+  // in English on such a device, where only number formatting used to fall
+  // back.
+  if (l.localeIdentifier === '') {
     console.warn(
       'Cannot recognize user locale preferences. Default will be used.'
     )
     Object.assign(locale, EN_US_LOCALE)
-  } else {
-    Object.assign(locale, l)
+    return
+  }
+  if (l.decimalSeparator === '' || l.groupingSeparator === '') {
+    console.warn(
+      'Cannot recognize user number format preferences. Default will be used.'
+    )
+    Object.assign(locale, l, {
+      decimalSeparator: EN_US_LOCALE.decimalSeparator,
+      groupingSeparator: EN_US_LOCALE.groupingSeparator
+    })
+    return
   }
+  Object.assign(locale, l)
 }
 
 export function toLocaleDate(date: Date): string {
@@ -402,8 +408,7 @@ export const pickLanguage = (
 export const getLocaleOrDefaultString = (
   localizedStrings: Record<string, string>
 ): string | undefined => {
-  const [firstLocale = { languageTag: DEFAULT_LOCALE_ID }] = getLocales()
-  const { languageTag } = firstLocale
+  const languageTag = locale.localeIdentifier
   const localizedStringKeys = Object.keys(localizedStrings)
 
   let localeId = pickLanguage(languageTag, localizedStringKeys)
diff --git a/src/locales/strings.ts b/src/locales/strings.ts
index a743f741101..cdbe4cd1094 100644
--- a/src/locales/strings.ts
+++ b/src/locales/strings.ts
@@ -1,5 +1,3 @@
-import { getLocales } from 'react-native-localize'
-
 import en from './en_US'
 import de from './strings/de.json'
 import es from './strings/es.json'
@@ -20,11 +18,6 @@ export type LStrings = typeof lstrings
 export type LStringsKey = keyof LStrings
 export type LStringsValues = LStrings[LStringsKey]
 
-// Set the language at boot:
-const [firstLocale] = getLocales()
-const { languageTag = 'en-US' } = firstLocale ?? {}
-if (languageTag !== 'en-US') selectLocale(languageTag)
-
 function mergeStrings(
   primary: Record<string, string>,
   secondary: Record<string, string>
diff --git a/src/util/WebUtils.ts b/src/util/WebUtils.ts
index f7c7249a8e5..7ed47da8bb9 100644
--- a/src/util/WebUtils.ts
+++ b/src/util/WebUtils.ts
@@ -34,9 +34,24 @@ export const stringifyQuery = (query: UriQueryMap): string => {
 export const parseQuery = (query?: string): UriQueryMap => {
   if (query == null) return {}
   const dummyUrl = new URL('https://dummyurl.com?' + query, true)
-  const test = dummyUrl.query
-  // @ts-expect-error
-  return test
+  // `url-parse` types `query` as `string | Record<string, string>` depending
+  // on its `parseQuery` flag, which it cannot narrow from the `true` above.
+  // Narrowed rather than suppressed, which is the point of the change here.
+  //
+  // The `?? null` below is defensive, not a fix for an observed bug: the
+  // library's querystring parser yields `''` for a value-less flag, never
+  // `undefined` — `new URL('https://x?flag', true).query` is
+  // `{ flag: '' }`, which is why `cleanQueryFlags` above exists at all — but
+  // its types say `string | undefined`, and `UriQueryMap` promises
+  // `string | null`, so this keeps the two honest without claiming the
+  // `null` arm is reachable today.
+  const parsed = dummyUrl.query
+  if (typeof parsed === 'string') return {}
+  const out: UriQueryMap = {}
+  for (const [key, value] of Object.entries(parsed)) {
+    out[key] = value ?? null
+  }
+  return out
 }
 
 /**
diff --git a/src/util/attestation.ts b/src/util/attestation.ts
index d2cfdeb863a..3b4e5efe828 100644
--- a/src/util/attestation.ts
+++ b/src/util/attestation.ts
@@ -740,9 +740,10 @@ const runHandshake = (): void => {
  * (unless a live token is already cached) without blocking; the engine then
  * self-reschedules to refresh the token ahead of each expiry.
  *
- * Called from `initInfoServer`, which runs on every network reconnect and not
- * just at boot, so this has to be idempotent: it returns immediately while a
- * token is live, and `runHandshake` single-flights and rate-limits the rest.
+ * Called from the network-reconnect path in `app.ts` (alongside
+ * `initInfoServer`), so this has to be idempotent: it returns immediately
+ * while a token is live, and `runHandshake` single-flights and rate-limits
+ * the rest.
  */
 export const initAttestation = (): void => {
   if (canServeToken()) return
diff --git a/src/util/fiatConstants.ts b/src/util/fiatConstants.ts
new file mode 100644
index 00000000000..f3bf59a2db6
--- /dev/null
+++ b/src/util/fiatConstants.ts
@@ -0,0 +1,184 @@
+/**
+ * Node-safe fiat display constants. Split out of WalletAndCurrencyConstants
+ * so util/utils.ts can import them without pulling in react-native Platform.
+ */
+
+export const FEE_COLOR_THRESHOLD = 2.0 // this is denominated in dollars
+export const FEE_ALERT_THRESHOLD = 5.0 // this is denominated in dollars
+export const FIAT_PRECISION = 2
+
+export const removeIsoPrefix = (currencyCode: string): string => {
+  return currencyCode.replace('iso:', '')
+}
+
+export const FIAT_CODES_SYMBOLS: Record<string, string> = {
+  AED: 'د.إ',
+  AFN: '؋',
+  ALL: 'L',
+  AMD: '֏',
+  ANG: 'ƒ',
+  AOA: 'Kz',
+  ARS: '$',
+  AUD: '$',
+  AWG: 'ƒ',
+  AZN: '₼',
+  BAM: 'KM',
+  BBD: '$',
+  BDT: '৳',
+  BGN: 'лв',
+  BIF: 'Fr',
+  BMD: '$',
+  BND: '$',
+  BOB: 'Bs.',
+  BRL: 'R$',
+  BSD: '$',
+  BTN: 'Nu.',
+  BWP: 'P',
+  BYN: 'Br',
+  BZD: '$',
+  CAD: '$',
+  CDF: 'Fr',
+  CHF: 'Fr',
+  CLP: '$',
+  CNY: '¥',
+  COP: '$',
+  CRC: '₡',
+  CUC: '$',
+  CUP: '$',
+  CVE: '$',
+  CZK: 'Kč',
+  DJF: 'Fr',
+  DKK: 'kr',
+  DOP: '$',
+  DZD: 'د.ج',
+  EGP: 'ج.م',
+  ERN: 'Nfk',
+  ETB: 'Br',
+  EUR: '€',
+  FJD: '$',
+  FKP: '£',
+  GBP: '£',
+  GEL: '₾',
+  GGP: '£',
+  GHS: '₵',
+  GIP: '£',
+  GMD: 'D',
+  GNF: 'Fr',
+  GTQ: 'Q',
+  GYD: '$',
+  HKD: '$',
+  HNL: 'L',
+  HRK: 'kn',
+  HTG: 'G',
+  HUF: 'Ft',
+  IDR: 'Rp',
+  ILS: '₪',
+  IMP: '£',
+  INR: '₹',
+  IQD: 'ع.د',
+  IRR: '﷼',
+  ISK: 'kr',
+  JEP: '£',
+  JMD: '$',
+  JOD: 'د.ا',
+  JPY: '¥',
+  KES: 'Sh',
+  KGS: 'с',
+  KHR: '៛',
+  KMF: 'Fr',
+  KPW: '₩',
+  KRW: '₩',
+  KWD: 'د.ك',
+  KYD: '$',
+  KZT: '₸',
+  LAK: '₭',
+  LBP: 'ل.ل',
+  LKR: 'Rs',
+  LRD: '$',
+  LSL: 'L',
+  LYD: 'ل.د',
+  MAD: 'د. م.',
+  MDL: 'L',
+  MGA: 'Ar',
+  MKD: 'ден',
+  MMK: 'Ks',
+  MNT: '₮',
+  MOP: 'P',
+  MRO: 'UM',
+  MRU: 'UM',
+  MUR: '₨',
+  MWK: 'MK',
+  MXN: '$',
+  MYR: 'RM',
+  MZN: 'MT',
+  NAD: '$',
+  NGN: '₦',
+  NIO: 'C$',
+  NOK: 'kr',
+  NPR: '₨',
+  NZD: '$',
+  OMR: 'ر.ع.',
+  PAB: 'B/.',
+  PEN: 'S/.',
+  PGK: 'K',
+  PHP: '₱',
+  PKR: '₨',
+  PLN: 'zł',
+  PRB: 'р.',
+  PYG: '₲',
+  QAR: 'ر.ق',
+  RON: 'lei',
+  RSD: 'дин',
+  RUB: '₽',
+  RWF: 'Fr',
+  SAR: 'ر.س',
+  SBD: '$',
+  SCR: '₨',
+  SDG: 'ج.س.',
+  SEK: 'kr',
+  SGD: '$',
+  SHP: '£',
+  SLL: 'Le',
+  SOS: 'Sh',
+  SRD: '$',
+  SSP: '£',
+  STD: 'Db',
+  SYP: 'ل.س',
+  SZL: 'L',
+  THB: '฿',
+  TJS: 'ЅМ',
+  TMT: 'm',
+  TND: 'د.ت',
+  TOP: 'T$',
+  TRY: '₺',
+  TTD: '$',
+  TVD: '$',
+  TWD: '$',
+  TZS: 'Sh',
+  UAH: '₴',
+  UGX: 'Sh',
+  USD: '$',
+  UYU: '$',
+  UZS: '',
+  VEF: 'Bs',
+  VND: '₫',
+  VUV: 'Vt',
+  WST: 'T',
+  XAF: 'Fr',
+  XCD: '$',
+  XOF: 'Fr',
+  XPF: 'Fr',
+  YER: '﷼',
+  ZAR: 'R',
+  ZMW: 'ZK'
+}
+
+/**
+ * Get the fiat symbol from an iso:[fiat] OR fiat currency code
+ */
+export const getFiatSymbol = (isoOrFiatCurrencyCode: string): string => {
+  if (typeof isoOrFiatCurrencyCode !== 'string') return ''
+  const codeWithoutIso = removeIsoPrefix(isoOrFiatCurrencyCode)
+  const out = FIAT_CODES_SYMBOLS[codeWithoutIso.toUpperCase()]
+  return out ?? ''
+}
diff --git a/src/util/infoUtils.ts b/src/util/infoUtils.ts
index 42b40bcd445..6a1cd41693e 100644
--- a/src/util/infoUtils.ts
+++ b/src/util/infoUtils.ts
@@ -5,7 +5,7 @@ import { getBuildNumber, getVersion } from 'react-native-device-info'
 
 import { infoServerData } from './network'
 import { getPromoCardMessageId } from './promoCardUtils'
-import { getOsVersion } from './utils'
+import { getOsVersion } from './rnUtils'
 
 export interface DisplayInfoCard {
   background: InfoCard['background']
diff --git a/src/util/keysStore.ts b/src/util/keysStore.ts
index 32a9c95eb6c..a832b961969 100644
--- a/src/util/keysStore.ts
+++ b/src/util/keysStore.ts
@@ -26,8 +26,8 @@ import { type FetchCredentials, fetchRemoteKeys } from './keysServer'
 import { debugLog } from './logger'
 import { fetchPublicRollup, infoServerData } from './network'
 import { raceTimeout, TIMED_OUT } from './raceTimeout'
+import { getOsVersion } from './rnUtils'
 import { runOnce } from './runOnce'
-import { getOsVersion } from './utils'
 import { checkAppVersion } from './versionCheck'
 
 export type KeysTier = 'remote' | 'cache' | 'baked-in'
diff --git a/src/util/network.ts b/src/util/network.ts
index e647af95dec..44805a988da 100644
--- a/src/util/network.ts
+++ b/src/util/network.ts
@@ -5,31 +5,42 @@ import type {
   EdgeFetchResponse
 } from 'edge-core-js'
 import { asInfoRollup, type InfoRollup } from 'edge-info-server'
-import { Platform } from 'react-native'
-import { getVersion } from 'react-native-device-info'
-
-import { CONFIG } from '../config'
-import { config } from '../theme/appConfig'
-import { initAttestation } from './attestation'
-import { willSignInfoRollup } from './edgeApiSigner'
-import { INFO_TEST_SERVER, shouldUseTestServers } from './maestro'
-import { runOnce } from './runOnce'
-import { asyncWaterfall, getOsVersion, shuffleArray } from './utils'
-import { checkAppVersion } from './versionCheck'
-// `CONFIG.INFO_SERVER` (from config.json) overrides the production info servers,
-// e.g. to point a debug build at a local info server. Absent in production
-// builds.
-const INFO_SERVERS =
-  CONFIG.INFO_SERVER != null && CONFIG.INFO_SERVER.length > 0
-    ? CONFIG.INFO_SERVER
-    : shouldUseTestServers()
-    ? [INFO_TEST_SERVER]
-    : ['https://info1.edge.app', 'https://info2.edge.app']
+
+import { asyncWaterfall, shuffleArray } from './utils'
+
+export const DEFAULT_INFO_SERVERS = [
+  'https://info1.edge.app',
+  'https://info2.edge.app'
+]
 const RATES_SERVERS = ['https://rates3.edge.app', 'https://rates4.edge.app']
 const RATES_SERVER_V2 = ['https://rates1.edge.app', 'https://rates2.edge.app']
 
 const INFO_FETCH_INTERVAL = 5 * 60 * 1000 // 5 minutes
 
+let infoServers: string[] = DEFAULT_INFO_SERVERS
+let referralServers: string[] = []
+let notificationServers: string[] = []
+let infoServerPollStarted = false
+
+/**
+ * GUI wires referral/push/info server lists from appConfig/ENV at startup.
+ * Until configured, referral/push fetches use an empty list; info defaults
+ * to production hosts.
+ */
+export function configureNetwork(opts: {
+  infoServers?: string[]
+  referralServers?: string[]
+  notificationServers?: string[]
+}): void {
+  if (opts.infoServers != null && opts.infoServers.length > 0) {
+    infoServers = opts.infoServers
+  }
+  if (opts.referralServers != null) referralServers = opts.referralServers
+  if (opts.notificationServers != null) {
+    notificationServers = opts.notificationServers
+  }
+}
+
 export async function fetchWaterfall(
   servers: string[],
   path: string,
@@ -37,6 +48,13 @@ export async function fetchWaterfall(
   timeout: number = 5000,
   doFetch: EdgeFetchFunction = fetch
 ): Promise<EdgeFetchResponse> {
+  // `asyncWaterfall([])` awaits `Promise.race([])`, which never settles. The
+  // referral and push lists start empty until `configureNetwork` fills them,
+  // and the CLI configures only the info servers, so an unconfigured caller
+  // would hang forever rather than fail.
+  if (servers.length === 0) {
+    throw new Error(`No servers configured for ${path}`)
+  }
   const funcs = servers.map(server => async () => {
     const result = await doFetch(server + '/' + path, options)
     if (typeof result !== 'object') {
@@ -96,7 +114,7 @@ export const fetchInfo = async (
   timeout?: number,
   doFetch?: EdgeFetchFunction
 ): Promise<EdgeFetchResponse> => {
-  return await multiFetch(INFO_SERVERS, path, options, timeout, doFetch)
+  return await multiFetch(infoServers, path, options, timeout, doFetch)
 }
 export const fetchRates = async (
   path: string,
@@ -113,13 +131,7 @@ export const fetchReferral = async (
   timeout?: number,
   doFetch?: EdgeFetchFunction
 ): Promise<EdgeFetchResponse> => {
-  return await multiFetch(
-    config.referralServers ?? [],
-    path,
-    options,
-    timeout,
-    doFetch
-  )
+  return await multiFetch(referralServers, path, options, timeout, doFetch)
 }
 export const fetchPush = async (
   path: string,
@@ -127,13 +139,7 @@ export const fetchPush = async (
   timeout?: number,
   doFetch?: EdgeFetchFunction
 ): Promise<EdgeFetchResponse> => {
-  return await multiFetch(
-    config.notificationServers,
-    path,
-    options,
-    timeout,
-    doFetch
-  )
+  return await multiFetch(notificationServers, path, options, timeout, doFetch)
 }
 
 export const infoServerData: {
@@ -141,45 +147,79 @@ export const infoServerData: {
   rollupRaw?: unknown
 } = {}
 
-let infoServerPollStarted = false
+export interface InitInfoServerParams {
+  osType: string
+  osVersion: string
+  appVersion: string
+  appId: string
+  /** Called once after a successful rollup fetch (e.g. version check). */
+  onRollup?: () => Promise<void>
+  /**
+   * When true, skip the launch unsigned fetch (HMAC signed fetch will fill
+   * rollup + appKeys). Unsigned is enough when this build has no HMAC
+   * credentials.
+   */
+  skipUnsignedLaunchFetch?: boolean
+}
+
+let infoServerParams: InitInfoServerParams | undefined
 
 /**
  * Fetch the unsigned public info rollup. Exported so `keysStore` can fall back
  * to it when the signed infoRollup fetch fails to populate `infoServerData`:
  * that failure is only observable once the signed fetch settles, which is long
- * after `initInfoServer` has already run.
+ * after `initInfoServer` has already run. Uses the parameters captured by
+ * `initInfoServer`, so this module stays Node-safe.
  */
 export const fetchPublicRollup = async (): Promise<void> => {
-  const osType = Platform.OS.toLowerCase()
-  const osVersion = getOsVersion()
-  const version = getVersion()
+  const params = infoServerParams
+  if (params == null) {
+    console.warn(
+      'fetchPublicRollup: configureInfoServer has not run yet, so there are no device fields to send'
+    )
+    return
+  }
+  const { osType, osVersion, appVersion, appId, onRollup } = params
   try {
     const response = await fetchInfo(
-      `v1/infoRollup/${
-        config.appId ?? 'edge'
-      }?os=${osType}&osVersion=${osVersion}&appVersion=${version}`
+      `v1/infoRollup/${appId}?os=${osType}&osVersion=${osVersion}&appVersion=${appVersion}`
     )
     if (!response.ok) {
       console.warn(
-        `initInfoServer error ${response.status}: ${await response.text()}`
+        `fetchPublicRollup error ${response.status}: ${await response.text()}`
       )
     } else {
       const infoData = await response.json()
       infoServerData.rollupRaw = infoData
       infoServerData.rollup = asInfoRollup(infoData)
-      await runOnce('checkAppVersion', checkAppVersion)
+      if (onRollup != null) await onRollup()
     }
   } catch (e) {
-    console.warn('initInfoServer: Failed to ping info server')
+    console.warn('fetchPublicRollup: Failed to reach the info server')
   }
 }
 
-export const initInfoServer = async (): Promise<void> => {
-  // Start the background attestation engine at boot (best-effort, non-blocking)
-  // so a token is usually cached before any attestation-gated request is made.
-  // This is intentionally not inside fetchInfo: the fetch wrapper carries no
-  // attestation logic; gated plugins attach the token via getAttestationToken().
-  initAttestation()
+/**
+ * Record the fields `fetchPublicRollup` needs.
+ *
+ * Separate from `initInfoServer` because the GUI can supply all of these
+ * synchronously at startup, while the decision to skip the unsigned launch
+ * fetch depends on an async native read. `keysStore` calls
+ * `fetchPublicRollup` directly on the cold-start path, so it must not depend
+ * on that await having finished.
+ */
+export function configureInfoServer(params: InitInfoServerParams): void {
+  infoServerParams = params
+}
+
+export const initInfoServer = async (
+  params: InitInfoServerParams
+): Promise<void> => {
+  // Through `configureInfoServer` rather than assigning again: the whole
+  // body of that function is this one line, and two places writing the same
+  // module state is how the two drift.
+  configureInfoServer(params)
+  const { skipUnsignedLaunchFetch } = params
 
   const queryInfo = fetchPublicRollup
 
@@ -198,7 +238,7 @@ export const initInfoServer = async (): Promise<void> => {
   // populate the rollup, `keysStore` calls `fetchPublicRollup` directly: the
   // decision cannot be made here, because at this point the signed fetch is
   // usually still in flight rather than failed.
-  if (infoServerData.rollup == null && !(await willSignInfoRollup())) {
+  if (infoServerData.rollup == null && skipUnsignedLaunchFetch !== true) {
     await queryInfo()
   }
 
diff --git a/src/util/promoCardUtils.ts b/src/util/promoCardUtils.ts
index ff612b77960..aafaeb05c69 100644
--- a/src/util/promoCardUtils.ts
+++ b/src/util/promoCardUtils.ts
@@ -11,7 +11,7 @@ import {
 } from '../actions/LocalSettingsActions'
 import { getLocaleOrDefaultString } from '../locales/intl'
 import { type DisplayInfoCard, filterInfoCards } from './infoUtils'
-import { getOsVersion } from './utils'
+import { getOsVersion } from './rnUtils'
 
 /**
  * Generate a unique notification key for a promo card
diff --git a/src/util/rnUtils.ts b/src/util/rnUtils.ts
index 1b9b7e47e89..af56b73f053 100644
--- a/src/util/rnUtils.ts
+++ b/src/util/rnUtils.ts
@@ -1,3 +1,4 @@
+import DeviceInfo from 'react-native-device-info'
 import { generateSecureRandom } from 'react-native-securerandom'
 import { v4 } from 'uuid'
 
@@ -15,3 +16,14 @@ export const makeUuid = async (): Promise<string> => {
   const uuid = v4({ random: bytes })
   return uuid
 }
+
+/**
+ * Reads and normalizes the OS version.
+ */
+export function getOsVersion(): string {
+  const osVersionRaw = DeviceInfo.getSystemVersion()
+  return Array.from({ length: 3 }, (_, i) => {
+    const part = osVersionRaw.split('.')[i]
+    return part != null && part !== '' ? part : '0'
+  }).join('.')
+}
diff --git a/src/util/txDisplay/currencyCodes.ts b/src/util/txDisplay/currencyCodes.ts
new file mode 100644
index 00000000000..3fa784f7999
--- /dev/null
+++ b/src/util/txDisplay/currencyCodes.ts
@@ -0,0 +1,47 @@
+import type { EdgeAccount, EdgeTokenId } from 'edge-core-js'
+
+export const getCurrencyCodeWithAccount = (
+  account: EdgeAccount,
+  pluginId: string,
+  tokenId: EdgeTokenId
+): string | undefined => {
+  if (account.currencyConfig[pluginId] == null) {
+    return
+  }
+
+  if (tokenId == null) {
+    return account.currencyConfig[pluginId].currencyInfo.currencyCode
+  }
+  if (account.currencyConfig[pluginId].allTokens[tokenId] == null) {
+    console.warn(
+      `getCurrencyCodeWithAccount: tokenId: '${tokenId}' not found for pluginId: '${pluginId}'`
+    )
+    return ''
+  }
+  return account.currencyConfig[pluginId].allTokens[tokenId].currencyCode
+}
+
+/**
+ * The currency code a wallet reports for one of its own assets.
+ *
+ * The wallet-based sibling of `getCurrencyCodeWithAccount`, for a caller that
+ * has the wallet rather than the account. Structurally typed, so it needs
+ * neither `edge-core-js` nor the GUI's `SPECIAL_CURRENCY_INFO`.
+ */
+export const currencyCodeForToken = (
+  wallet: {
+    currencyInfo: { currencyCode: string; pluginId: string }
+    currencyConfig: { allTokens: Record<string, { currencyCode: string }> }
+  },
+  tokenId: string | null
+): string => {
+  if (tokenId == null) return wallet.currencyInfo.currencyCode
+  const token = wallet.currencyConfig.allTokens[tokenId]
+  if (token == null) {
+    console.warn(
+      `currencyCodeForToken: tokenId: '${tokenId}' not found for wallet pluginId: '${wallet.currencyInfo.pluginId}'`
+    )
+    return ''
+  }
+  return token.currencyCode
+}
diff --git a/src/util/utils.ts b/src/util/utils.ts
index ef2d80ac633..ec8f5c5ec19 100644
--- a/src/util/utils.ts
+++ b/src/util/utils.ts
@@ -9,20 +9,10 @@ import type {
   EdgeTokenMap,
   EdgeTransaction
 } from 'edge-core-js'
-import { Linking, Platform } from 'react-native'
-import DeviceInfo from 'react-native-device-info'
-import SafariView from 'react-native-safari-view'
 import { sprintf } from 'sprintf-js'
 import { v4 } from 'uuid'
 
 import type { GuiExchangeRates } from '../actions/ExchangeRateActions'
-import {
-  FEE_ALERT_THRESHOLD,
-  FEE_COLOR_THRESHOLD,
-  FIAT_CODES_SYMBOLS,
-  FIAT_PRECISION,
-  getFiatSymbol
-} from '../constants/WalletAndCurrencyConstants'
 import {
   toLocaleDate,
   toLocaleDateTime,
@@ -33,8 +23,19 @@ import { lstrings } from '../locales/strings'
 import { convertCurrency, getExchangeRate } from '../selectors/WalletSelectors'
 import type { RootState } from '../types/reduxTypes'
 import type { GuiFiatType } from '../types/types'
-import { getCurrencyCode } from './CurrencyInfoHelpers'
 import { base58 } from './encoding'
+import {
+  FEE_ALERT_THRESHOLD,
+  FEE_COLOR_THRESHOLD,
+  FIAT_CODES_SYMBOLS,
+  FIAT_PRECISION,
+  getFiatSymbol,
+  removeIsoPrefix
+} from './fiatConstants'
+import { currencyCodeForToken } from './txDisplay/currencyCodes'
+
+// Re-export so existing importers of removeIsoPrefix from utils stay unchanged
+export { removeIsoPrefix }
 
 export const DECIMAL_PRECISION = 18
 export const DEFAULT_TRUNCATE_PRECISION = 6
@@ -362,7 +363,7 @@ export const getTotalFiatAmountFromExchangeRates = (
     )
     for (const tokenId of wallet.balanceMap.keys()) {
       const nativeBalance = wallet.balanceMap.get(tokenId) ?? '0'
-      const currencyCode = getCurrencyCode(wallet, tokenId)
+      const currencyCode = currencyCodeForToken(wallet, tokenId)
       const rate = getExchangeRate(
         exchangeRates,
         wallet.currencyInfo.pluginId,
@@ -427,62 +428,56 @@ export async function asyncWaterfall(
 ): Promise<any> {
   let pending = asyncFuncs.length
   const promises: Array<Promise<any>> = []
-  for (const func of asyncFuncs) {
-    const index = promises.length
-    promises.push(
-      func().catch((e: unknown) => {
-        ;(e as any).index = index
-        throw e
-      })
-    )
-    if (pending > 1) {
+
+  // Each stagger timer outlives the race it loses: dropping the promise with
+  // `promises.pop()` leaves its `setTimeout` armed for the rest of
+  // `timeoutMs`, which keeps Node's event loop alive after the winning
+  // request has already answered. Behind a daemon that delays an exit, and in
+  // a jest worker it reads as a leaked handle that hides the next real one.
+  const staggerTimers: Array<ReturnType<typeof setTimeout>> = []
+  try {
+    for (const func of asyncFuncs) {
+      const index = promises.length
       promises.push(
-        new Promise(resolve => {
-          // eslint-disable-next-line @typescript-eslint/no-floating-promises
-          snooze(timeoutMs).then(() => {
-            resolve('async_waterfall_timed_out')
-          })
+        func().catch((e: unknown) => {
+          ;(e as any).index = index
+          throw e
         })
       )
-    }
-    try {
-      const result = await Promise.race(promises)
-      if (result === 'async_waterfall_timed_out') {
+      if (pending > 1) {
+        promises.push(
+          new Promise(resolve => {
+            staggerTimers.push(
+              setTimeout(() => {
+                resolve('async_waterfall_timed_out')
+              }, timeoutMs)
+            )
+          })
+        )
+      }
+      try {
+        const result = await Promise.race(promises)
+        if (result === 'async_waterfall_timed_out') {
+          // eslint-disable-next-line @typescript-eslint/no-floating-promises
+          promises.pop()
+          --pending
+        } else {
+          return result
+        }
+      } catch (e: any) {
+        const i = e.index
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        promises.splice(i, 1)
         // eslint-disable-next-line @typescript-eslint/no-floating-promises
         promises.pop()
         --pending
-      } else {
-        return result
-      }
-    } catch (e: any) {
-      const i = e.index
-      // eslint-disable-next-line @typescript-eslint/no-floating-promises
-      promises.splice(i, 1)
-      // eslint-disable-next-line @typescript-eslint/no-floating-promises
-      promises.pop()
-      --pending
-      if (pending === 0) {
-        throw e
+        if (pending === 0) {
+          throw e
+        }
       }
     }
-  }
-}
-
-export async function openLink(url: string): Promise<void> {
-  if (Platform.OS === 'ios') {
-    try {
-      await SafariView.isAvailable()
-      await SafariView.show({ url })
-      return
-    } catch (e: any) {
-      console.log(e)
-    }
-  }
-  const supported = await Linking.canOpenURL(url)
-  if (supported) {
-    await Linking.openURL(url)
-  } else {
-    throw new Error(`Don't know how to open URI: ${url}`)
+  } finally {
+    for (const timer of staggerTimers) clearTimeout(timer)
   }
 }
 
@@ -782,21 +777,6 @@ export const darkenHexColor = (
   return scaledHexColor
 }
 
-/**
- * Reads and normalizes the OS version.
- */
-export function getOsVersion(): string {
-  const osVersionRaw = DeviceInfo.getSystemVersion()
-  return Array.from({ length: 3 }, (_, i) => {
-    const part = osVersionRaw.split('.')[i]
-    return part != null && part !== '' ? part : '0'
-  }).join('.')
-}
-
-export const removeIsoPrefix = (currencyCode: string): string => {
-  return currencyCode.replace('iso:', '')
-}
-
 export const getDisplayUsername = (
   loginId: string,
   username?: string

From 934b7c7eec7b6c1337b6557bc694f74a6cfb1879 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 04/24] Split exchange rates for Node safety

Exchange rates could not be fetched outside the app: the module read its
server list and its error reporter at load time, both of which come from
React Native.

The query logic now takes what it needs through
`configureExchangeRates`, and `exchangeRatesGui` supplies the GUI's
Airship reporter at app start. A Node caller supplies its own, so the
same rate lookup answers the same way in both places.
---
 src/__tests__/exchangeRates.test.ts           |   4 +-
 src/__tests__/util/exchangeRatesCache.test.ts | 217 ++++++++++
 src/app.ts                                    |   1 +
 src/util/exchangeRates.ts                     | 373 ++++++++++++------
 src/util/exchangeRatesGui.ts                  |  17 +
 5 files changed, 495 insertions(+), 117 deletions(-)
 create mode 100644 src/__tests__/util/exchangeRatesCache.test.ts
 create mode 100644 src/util/exchangeRatesGui.ts

diff --git a/src/__tests__/exchangeRates.test.ts b/src/__tests__/exchangeRates.test.ts
index 8cd666a23b6..ed2645d85ee 100644
--- a/src/__tests__/exchangeRates.test.ts
+++ b/src/__tests__/exchangeRates.test.ts
@@ -1,7 +1,7 @@
 import { beforeAll, expect, it, jest } from '@jest/globals'
 import fetch from 'node-fetch'
 
-import { getHistoricalCryptoRate } from '../util/exchangeRates'
+import { getHistoricalCryptoRate, stopRateQueue } from '../util/exchangeRates'
 import { mswServer } from '../util/mswServer'
 import { snooze } from '../util/utils'
 
@@ -16,6 +16,8 @@ beforeAll(() => {
   mswServer.listen()
 })
 afterAll(() => {
+  // A debounce left armed in a shared jest worker hides the next real leak.
+  stopRateQueue()
   mswServer.close()
 })
 
diff --git a/src/__tests__/util/exchangeRatesCache.test.ts b/src/__tests__/util/exchangeRatesCache.test.ts
new file mode 100644
index 00000000000..8c4a9617484
--- /dev/null
+++ b/src/__tests__/util/exchangeRatesCache.test.ts
@@ -0,0 +1,217 @@
+import { afterAll, beforeAll, describe, expect, it, jest } from '@jest/globals'
+
+import {
+  clearRateCache,
+  getHistoricalCryptoRate,
+  rateCacheSize,
+  stopRateQueue
+} from '../../util/exchangeRates'
+
+// Real timers: the queue debounces by FETCH_FREQUENCY before it fetches.
+// The injected `doFetch` below is the only thing keeping this suite off
+// `rates.edge.app` — `fetchRates` falls back to the real fetch without it, so
+// a case added with no fake goes to the network.
+beforeAll(() => {
+  jest.useRealTimers()
+})
+afterAll(() => {
+  // The debounce is `unref`ed, but an armed timer in a shared worker still
+  // hides the next real leak.
+  stopRateQueue()
+  jest.useFakeTimers()
+})
+
+/** A rates server that prices everything it is asked for. */
+let posts = 0
+const fakeFetch: any = async (_uri: string, opts: any) => {
+  posts++
+  const body = JSON.parse(opts.body)
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({
+      targetFiat: body.targetFiat,
+      crypto: body.crypto.map((c: any) => ({ ...c, rate: 30000 })),
+      fiat: body.fiat.map((f: any) => ({ ...f, rate: 1 }))
+    }),
+    text: async () => ''
+  }
+}
+
+/** A rates server that answers, but prices nothing it was asked for. */
+const unpricedFetch: any = async (_uri: string, opts: any) => {
+  posts++
+  const body = JSON.parse(opts.body)
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({
+      targetFiat: body.targetFiat,
+      crypto: body.crypto.map((c: any) => ({ ...c, rate: undefined })),
+      fiat: body.fiat.map((f: any) => ({ ...f, rate: undefined }))
+    }),
+    text: async () => ''
+  }
+}
+
+/** A rates server that is down. */
+const failingFetch: any = async () => {
+  posts++
+  return {
+    ok: false,
+    status: 503,
+    json: async () => ({}),
+    text: async () => 'rates server unavailable'
+  }
+}
+
+const rateFor = async (
+  date: string,
+  doFetch: any = fakeFetch,
+  pluginId = 'bitcoin'
+): Promise<number> =>
+  await getHistoricalCryptoRate(pluginId, null, 'iso:USD', date, 100, doFetch)
+
+describe('the module-level rate cache', () => {
+  it('caches a rate, serves it without a second request, and clears', async () => {
+    clearRateCache()
+    expect(rateCacheSize()).toBe(0)
+
+    const date = '2022-06-01T04:00:00.000Z'
+    const first = await rateFor(date)
+    expect(first).toBe(30000)
+    expect(rateCacheSize()).toBe(1)
+
+    const before = posts
+    const second = await rateFor(date)
+    expect(second).toBe(30000)
+    // Served from the cache: behind a daemon this is what keeps a long
+    // listing from re-pricing the same dates.
+    expect(posts).toBe(before)
+
+    // And a long-lived process needs to be able to drop it: the engine calls
+    // this when the last session goes away and again on shutdown.
+    clearRateCache()
+    expect(rateCacheSize()).toBe(0)
+  })
+
+  it('does not cache a zero, so one unpriced response is not permanent', async () => {
+    clearRateCache()
+    const date = '2019-03-03T04:00:00.000Z'
+
+    // The route publishes `0` for a rate the server cannot supply.
+    expect(await rateFor(date, unpricedFetch)).toBe(0)
+    expect(rateCacheSize()).toBe(0)
+
+    // A later pass against a recovered server therefore prices it.
+    expect(await rateFor(date)).toBe(30000)
+    expect(rateCacheSize()).toBe(1)
+  })
+
+  it('resolves every caller with zero when the server fails, caching none', async () => {
+    clearRateCache()
+    const rates = await Promise.all([
+      rateFor('2019-04-01T04:00:00.000Z', failingFetch),
+      rateFor('2019-04-02T04:00:00.000Z', failingFetch)
+    ])
+    expect(rates).toStrictEqual([0, 0])
+    expect(rateCacheSize()).toBe(0)
+  })
+
+  it('prices a key queued while a request is already in flight', async () => {
+    clearRateCache()
+    posts = 0
+
+    // `addToQueue` deliberately arms no second timer while a pass is running,
+    // so this key joins the queue without a request of its own. Deciding "no
+    // progress" from the queue's size made the in-flight pass resolve it as
+    // `0` without ever asking the server — a $0 fiat amount in an export and
+    // in a transaction-list row.
+    let release: (value: unknown) => void = () => {}
+    const held = new Promise(resolve => {
+      release = resolve
+    })
+    const slowFetch: any = async (uri: string, opts: any) => {
+      await held
+      return await fakeFetch(uri, opts)
+    }
+
+    const first = rateFor('2020-01-01T04:00:00.000Z', slowFetch)
+    // Long enough for the debounce to fire and the fetch to be outstanding.
+    await new Promise(resolve => setTimeout(resolve, 1200))
+    const second = rateFor('2020-01-02T04:00:00.000Z', fakeFetch)
+    const third = rateFor('2020-01-03T04:00:00.000Z', fakeFetch)
+    release(undefined)
+
+    expect(await first).toBe(30000)
+    expect(await second).toBe(30000)
+    expect(await third).toBe(30000)
+    // Two passes: the one that was in flight, and one for the arrivals.
+    expect(posts).toBe(2)
+  })
+
+  it('gives up once on keys the server answered but could not price', async () => {
+    clearRateCache()
+    posts = 0
+    // Without settling an asked-for key the retry would re-send the identical
+    // request forever, with no delay.
+    expect(await rateFor('2018-07-07T04:00:00.000Z', unpricedFetch)).toBe(0)
+    expect(posts).toBe(1)
+  })
+
+  it('keeps the cache bounded', async () => {
+    clearRateCache()
+    // One date per entry, past the 20,000 bound. Dates are a day apart so
+    // every key is distinct. They are queued before anything is awaited, so
+    // the whole set costs one debounce and then one immediate pass per
+    // RATES_SERVER_MAX_QUERY_SIZE batch.
+    const start = Date.UTC(2000, 0, 1)
+    const day = 86_400_000
+    const pending: Array<Promise<number>> = []
+    for (let i = 0; i < 20_100; i++) {
+      pending.push(rateFor(new Date(start + i * day).toISOString()))
+    }
+    const rates = await Promise.all(pending)
+    expect(rates.every(rate => rate === 30000)).toBe(true)
+    expect(rateCacheSize()).toBeLessThanOrEqual(20_000)
+    expect(rateCacheSize()).toBeGreaterThan(0)
+  }, 120_000)
+})
+
+describe('query scheduling', () => {
+  it('fires immediately when the queue has been idle', async () => {
+    // A trailing-edge debounce spent a full FETCH_FREQUENCY before the first
+    // request, and every daemon request starts from an idle queue — so
+    // `get-transactions` paid it twice in series, a fixed ~2s floor
+    // independent of page size, and ~1s even when every rate was cached.
+    stopRateQueue()
+    clearRateCache()
+    posts = 0
+
+    const started = Date.now()
+    await rateFor('2024-01-01T00:00:00.000Z')
+    const elapsed = Date.now() - started
+
+    // Well under FETCH_FREQUENCY, which is what the old path could not do.
+    expect(elapsed).toBeLessThan(500)
+    expect(posts).toBe(1)
+  })
+
+  it('still collapses a burst into one request', async () => {
+    // The coalescing the GUI's per-row lookups need: the leading edge is
+    // deferred by a tick, so everything queued in the same pass goes in one
+    // batch rather than one request per caller.
+    stopRateQueue()
+    clearRateCache()
+    posts = 0
+
+    const dates = Array.from(
+      { length: 25 },
+      (_v, i) => `2024-02-${String(i + 1).padStart(2, '0')}T00:00:00.000Z`
+    )
+    await Promise.all(dates.map(async date => await rateFor(date)))
+
+    expect(rateCacheSize()).toBe(25)
+    expect(posts).toBe(1)
+  })
+})
diff --git a/src/app.ts b/src/app.ts
index 97ebd67d44d..d7c8ca32b81 100644
--- a/src/app.ts
+++ b/src/app.ts
@@ -15,6 +15,7 @@ import './locales/initLocale'
 // Metro's default `inlineRequires` can defer the whole module — so the one
 // wiring that decides how rate-query failures are reported was the one whose
 // evaluation point depended on a bundler transform.
+import './util/exchangeRatesGui'
 
 import NetInfo from '@react-native-community/netinfo'
 import * as Sentry from '@sentry/react-native'
diff --git a/src/util/exchangeRates.ts b/src/util/exchangeRates.ts
index 7a3fbe99bd1..44b0351a0e3 100644
--- a/src/util/exchangeRates.ts
+++ b/src/util/exchangeRates.ts
@@ -1,3 +1,9 @@
+/**
+ * Core historical / batched rates against rates3/4 `v3/rates`.
+ *
+ * Uses Node-safe `network.fetchRates` and `utils.removeIsoPrefix`.
+ * The GUI wires Airship `showError` via `exchangeRatesGui.ts`.
+ */
 import {
   asArray,
   asDate,
@@ -10,7 +16,6 @@ import {
 } from 'cleaners'
 import type { EdgeFetchFunction, EdgeTokenId } from 'edge-core-js'
 
-import { showError } from '../components/services/AirshipInstance'
 import { fetchRates } from './network'
 import { removeIsoPrefix } from './utils'
 
@@ -20,6 +25,17 @@ const SHOW_LOGS = false
 
 const clog = SHOW_LOGS ? console.log : (...args: any) => undefined
 
+let onQueryError: (error: unknown) => void = error => {
+  console.warn(error)
+}
+
+/** GUI calls this from `exchangeRatesGui.ts` to show Airship errors. */
+export function configureExchangeRates(opts: {
+  onError?: (error: unknown) => void
+}): void {
+  if (opts.onError != null) onQueryError = opts.onError
+}
+
 // From rates server:
 export const asCryptoAsset = asObject({
   pluginId: asString,
@@ -42,9 +58,39 @@ export const asRatesParams = asObject({
 })
 export type RatesParams = ReturnType<typeof asRatesParams>
 
-type RateMap = Record<string, number | null>
+/**
+ * The asset a crypto rate names, as one index key.
+ *
+ * Settling a queued entry against a response used to be
+ * `data.crypto.some(sameCrypto)` inside a walk of the entire queue, so a
+ * caller that queues a whole transaction history at once paid
+ * `O(queued x requested)` per pass. The response is indexed by these keys
+ * instead, which makes each settle a lookup.
+ */
+const cryptoIndexKey = (entry: {
+  isoDate?: Date
+  asset: { pluginId: string; tokenId?: EdgeTokenId }
+}): string =>
+  `${entry.asset.pluginId}|${entry.asset.tokenId ?? ''}|${
+    entry.isoDate?.getTime() ?? ''
+  }`
+
+const fiatIndexKey = (entry: { isoDate?: Date; fiatCode: string }): string =>
+  `${entry.fiatCode}|${entry.isoDate?.getTime() ?? ''}`
+
+/**
+ * How many rates the module-level cache keeps.
+ *
+ * In the GUI this was an app-session cache; behind a daemon it is a process
+ * cache, and `fillTxsFiat` adds one entry per transaction date of every
+ * wallet of every account the engine ever serves. An engine started with
+ * `--idle-timeout=0` never exits, so the map needs a bound as well as a
+ * clear function.
+ */
+const RATE_CACHE_MAX = 20_000
 
-const rateMap: RateMap = {}
+// A Map, for insertion-ordered eviction and a real `size`.
+const rateMap = new Map<string, number>()
 const resolverMap = new Map<
   string,
   {
@@ -53,149 +99,174 @@ const resolverMap = new Map<
   }
 >()
 let inQuery = false
+/**
+ * When the last query finished, for the leading-edge debounce.
+ *
+ * A trailing-edge debounce spends a full `FETCH_FREQUENCY` before the *first*
+ * request, which is the worst case for a daemon: every engine request starts
+ * from an idle queue, so `get-transactions` paid it twice in series — once
+ * for the spam threshold and once for the fiat fill — a fixed ~2s floor
+ * independent of page size, and ~1s even when every rate was already cached.
+ */
+let lastQueryEndedAt = 0
+let queryTimer: ReturnType<typeof setTimeout> | undefined
+
+/**
+ * Keep a pending debounce from holding a process open.
+ *
+ * Node's timer has `unref`; React Native's is a number and has none. A
+ * debounce should never be the reason a program stays alive — the engine
+ * holds a listening socket and the GUI a running app — and in a jest worker
+ * an armed timer is a leaked handle that outlives the test.
+ */
+function unrefTimer(timer: unknown): void {
+  if (
+    typeof timer === 'object' &&
+    timer != null &&
+    typeof (timer as { unref?: unknown }).unref === 'function'
+  ) {
+    ;(timer as { unref: () => void }).unref()
+  }
+}
+
+/** One upstream request: its parameters, and the queue keys it speaks for. */
+interface RateQueryGroup {
+  params: RatesParams
+  keys: string[]
+}
 
 let numDoQuery = 0
 const doQuery = async (doFetch?: EdgeFetchFunction): Promise<void> => {
   const n = numDoQuery++
   clog(`${n} doQuery enter`)
 
-  const groupedParams = new Map<string, RatesParams>()
+  const groups = new Map<string, RateQueryGroup>()
 
   // Fill the query up to RATES_SERVER_MAX_QUERY_SIZE entries
-  const values = resolverMap.values()
-  for (const value of values) {
-    const map = groupedParams.get(value.rateQueueEntry.targetFiat)
-    if (map == null) {
-      groupedParams.set(value.rateQueueEntry.targetFiat, value.rateQueueEntry)
-    } else {
-      const combinedMap: RatesParams = {
-        targetFiat: map.targetFiat,
-        crypto: [...map.crypto, ...value.rateQueueEntry.crypto],
-        fiat: [...map.fiat, ...value.rateQueueEntry.fiat]
-      }
-      groupedParams.set(value.rateQueueEntry.targetFiat, combinedMap)
+  for (const [key, value] of resolverMap.entries()) {
+    const group = groups.get(value.rateQueueEntry.targetFiat)
+    if (group == null) {
+      groups.set(value.rateQueueEntry.targetFiat, {
+        params: value.rateQueueEntry,
+        keys: [key]
+      })
+      continue
     }
 
-    if (map?.crypto.length === RATES_SERVER_MAX_QUERY_SIZE) break
+    // The server rejects a request whose `crypto` or `fiat` array reaches
+    // RATES_SERVER_MAX_QUERY_SIZE ("must be less than 100"), so this stops
+    // *before* adding an entry that would cross it. Testing the pre-insert
+    // length for equality instead let a batch reach 101 and let a batch that
+    // stepped over 100 never stop at all; whatever is left over is picked up
+    // by the retry at the end of this function.
+    if (
+      group.params.crypto.length + value.rateQueueEntry.crypto.length >=
+        RATES_SERVER_MAX_QUERY_SIZE ||
+      group.params.fiat.length + value.rateQueueEntry.fiat.length >=
+        RATES_SERVER_MAX_QUERY_SIZE
+    ) {
+      break
+    }
+
+    group.params = {
+      targetFiat: group.params.targetFiat,
+      crypto: [...group.params.crypto, ...value.rateQueueEntry.crypto],
+      fiat: [...group.params.fiat, ...value.rateQueueEntry.fiat]
+    }
+    group.keys.push(key)
   }
 
-  for (const data of groupedParams.values()) {
+  for (const group of groups.values()) {
     const options = {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(data)
+      body: JSON.stringify(group.params)
     }
     try {
       const response = await fetchRates('v3/rates', options, 5000, doFetch)
-      if (response.ok) {
-        const json = await response.json()
-        const cleanedRates = asRatesParams(json)
-
-        // Since the requests are USD only, we'll match up the original requests to what we've received
-        for (const [
-          key,
-          { rateQueueEntry, resolvers }
-        ] of resolverMap.entries()) {
-          // Match crypto/fiat requests
-          if (rateQueueEntry.crypto.length === 1) {
-            const cryptoToMatch = rateQueueEntry.crypto[0]
-            const fiatToMatch = rateQueueEntry.fiat[0]
-            const crypto = cleanedRates.crypto.find(cr => {
-              return (
-                cr.isoDate?.getTime() === cryptoToMatch.isoDate?.getTime() &&
-                cr.asset.pluginId === cryptoToMatch.asset.pluginId &&
-                (cr.asset.tokenId === cryptoToMatch.asset.tokenId ||
-                  (cr.asset.tokenId == null &&
-                    cryptoToMatch.asset.tokenId == null))
-              )
-            })
-
-            const fiat = cleanedRates.fiat.find(fr => {
-              return (
-                fr.isoDate?.getTime() === fiatToMatch.isoDate?.getTime() &&
-                fr.fiatCode === fiatToMatch.fiatCode
-              )
-            })
-
-            if (crypto?.rate != null && fiat?.rate != null) {
-              const rate = crypto.rate / fiat.rate
-              rateMap[key] = rate
-              if (resolverMap.get(key) == null) {
-                clog(`${n} oops`)
-                continue
-              }
-
-              clog(`${n} deleting ${key}`)
-              resolverMap.delete(key)
-              if (resolvers.length) {
-                resolvers.forEach((r, i) => {
-                  r(rate)
-                })
-              }
-            }
-          }
+      if (!response.ok) {
+        const text = await response.text()
+        throw new Error(text)
+      }
+      const cleanedRates = asRatesParams(await response.json())
 
-          // Match fiat/fiat requests
-          if (rateQueueEntry.fiat.length === 2) {
-            const fromFiatToMatch = rateQueueEntry.fiat[0]
-            const fiatToMatch = rateQueueEntry.fiat[1]
-            const fromFiat = cleanedRates.fiat.find(fr => {
-              return (
-                fr.isoDate?.getTime() === fromFiatToMatch.isoDate?.getTime() &&
-                fr.fiatCode === fromFiatToMatch.fiatCode
-              )
-            })
-
-            const toFiat = cleanedRates.fiat.find(fr => {
-              return (
-                fr.isoDate?.getTime() === fiatToMatch.isoDate?.getTime() &&
-                fr.fiatCode === fiatToMatch.fiatCode
-              )
-            })
-
-            if (fromFiat?.rate != null && toFiat?.rate != null) {
-              const rate = fromFiat.rate / toFiat.rate
-              rateMap[key] = rate
-              if (resolverMap.get(key) == null) {
-                clog(`${n} oops`)
-                continue
-              }
-
-              clog(`${n} deleting ${key}`)
-              resolverMap.delete(key)
-              if (resolvers.length) {
-                resolvers.forEach((r, i) => {
-                  r(rate)
-                })
-              }
-            }
+      // One index per response, so settling a key costs a lookup rather than
+      // a scan of both request arrays.
+      const cryptoRates = new Map<string, number | undefined>()
+      for (const rate of cleanedRates.crypto) {
+        cryptoRates.set(cryptoIndexKey(rate), rate.rate)
+      }
+      const fiatRates = new Map<string, number | undefined>()
+      for (const rate of cleanedRates.fiat) {
+        fiatRates.set(fiatIndexKey(rate), rate.rate)
+      }
+
+      // Only the keys this request carried. A key queued while the request
+      // was in flight was never asked about, so it is none of this response's
+      // business and gets a pass of its own below. Settling those here
+      // answered `0` for a rate the server could have priced.
+      for (const key of group.keys) {
+        const pending = resolverMap.get(key)
+        if (pending == null) continue
+        const { rateQueueEntry, resolvers } = pending
+
+        // The server answered, so this key settles either way: at `0` when it
+        // came back unpriced, because a key that survives its own response
+        // would make the retry below spin forever.
+        let rate = 0
+        if (rateQueueEntry.crypto.length === 1) {
+          const cryptoRate = cryptoRates.get(
+            cryptoIndexKey(rateQueueEntry.crypto[0])
+          )
+          const fiatRate = fiatRates.get(fiatIndexKey(rateQueueEntry.fiat[0]))
+          if (cryptoRate != null && fiatRate != null && fiatRate !== 0) {
+            rate = cryptoRate / fiatRate
+          }
+        } else if (rateQueueEntry.fiat.length === 2) {
+          const fromRate = fiatRates.get(fiatIndexKey(rateQueueEntry.fiat[0]))
+          const toRate = fiatRates.get(fiatIndexKey(rateQueueEntry.fiat[1]))
+          if (fromRate != null && toRate != null && toRate !== 0) {
+            rate = fromRate / toRate
           }
         }
-      } else {
-        const text = await response.text()
-        throw new Error(text)
+
+        // `0` means "the server could not price this", not a rate. Caching it
+        // would answer `0` for that key for the life of the process, long
+        // after the rates server recovered.
+        if (rate !== 0) cacheRate(key, rate)
+        clog(`${n} deleting ${key}`)
+        resolverMap.delete(key)
+        resolvers.forEach(r => r(rate))
       }
     } catch (e: unknown) {
       if (e instanceof Error) {
         console.warn(`Error querying rates server ${e.message}`)
       }
-      // Resolve all the promises with value 0
-      const resolversMapEntries = [...resolverMap.entries()]
-      resolversMapEntries.forEach(entry => {
-        const [pairDate, value] = entry
-        clog(`${n} throw deleting ${pairDate}`)
-        resolverMap.delete(pairDate)
-        value.resolvers.forEach(resolve => resolve(0))
-      })
+      // Give up on this request's own keys only. The queue may also hold keys
+      // another group owns and keys that arrived mid-flight, and neither was
+      // part of this failure.
+      for (const key of group.keys) {
+        const pending = resolverMap.get(key)
+        if (pending == null) continue
+        clog(`${n} throw deleting ${key}`)
+        resolverMap.delete(key)
+        pending.resolvers.forEach(resolve => resolve(0))
+      }
     }
   }
 
+  // Every key this pass asked about has settled, so whatever is left was
+  // never sent: the RATES_SERVER_MAX_QUERY_SIZE remainder, or an arrival from
+  // during the round trip, which `addToQueue` deliberately does not arm a
+  // second timer for. Each pass therefore removes at least the keys it asked
+  // about, so this terminates.
   if (resolverMap.size > 0) {
     clog(`${n} Calling doQuery again`)
     await doQuery(doFetch)
   } else {
     clog(`${n} doQuery complete`)
     inQuery = false
+    lastQueryEndedAt = Date.now()
   }
 }
 
@@ -205,7 +276,7 @@ const addToQueue = (
   resolve: Function,
   maxQuerySize: number,
   doFetch?: EdgeFetchFunction
-) => {
+): void => {
   const rateKeyResolver = resolverMap.get(rateKey)
   if (rateKeyResolver == null) {
     // Create a new entry in the map for this pair/date
@@ -221,14 +292,84 @@ const addToQueue = (
   }
   if (!inQuery) {
     inQuery = true
-    setTimeout(() => {
+    // Leading edge when the queue has been idle at least `FETCH_FREQUENCY`,
+    // and otherwise only far enough out to keep that as the minimum spacing
+    // between requests. Deferred by a tick rather than run synchronously, so
+    // a burst of per-row lookups still collapses into one batch, and anything
+    // arriving during the round trip is coalesced by `doQuery`'s own
+    // recursion — which is what keeps a burst to a bounded number of requests
+    // rather than one per caller.
+    const idleFor = Date.now() - lastQueryEndedAt
+    const delay = idleFor >= FETCH_FREQUENCY ? 0 : FETCH_FREQUENCY - idleFor
+    queryTimer = setTimeout(() => {
+      queryTimer = undefined
       doQuery(doFetch).catch((error: unknown) => {
-        showError(error)
+        onQueryError(error)
       })
-    }, FETCH_FREQUENCY)
+    }, delay)
+    unrefTimer(queryTimer)
+  }
+}
+
+/**
+ * Remember a rate, evicting the oldest entries once the map is full.
+ *
+ * A Map iterates in insertion order, so the oldest entries go first: a long
+ * listing pages through dates in order, and the earliest are the ones least
+ * likely to be asked for again.
+ */
+function cacheRate(key: string, rate: number): void {
+  if (!rateMap.has(key) && rateMap.size >= RATE_CACHE_MAX) {
+    // A quarter at a time rather than one per insert, so a long listing does
+    // not pay an eviction on every transaction.
+    const victims = [...rateMap.keys()].slice(0, RATE_CACHE_MAX >> 2)
+    for (const victim of victims) rateMap.delete(victim)
+  }
+  rateMap.set(key, rate)
+}
+
+/**
+ * Drop every cached rate.
+ *
+ * A module-level cache in a long-lived process needs an owner: the engine
+ * calls this when the last session goes away and again on shutdown, so a
+ * daemon does not accumulate one entry per transaction date for the life of
+ * the machine.
+ */
+export function clearRateCache(): void {
+  rateMap.clear()
+}
+
+/**
+ * Stop the pending query and settle whatever is still queued.
+ *
+ * `clearRateCache` empties the cache, which says nothing about work in
+ * flight: a debounce armed just before shutdown would otherwise fire against
+ * a closing context, and anything awaiting a rate would never settle. The
+ * engine calls this from `shutdown`, and a test calls it so no timer outlives
+ * the suite.
+ */
+export function stopRateQueue(): void {
+  if (queryTimer != null) {
+    clearTimeout(queryTimer)
+    queryTimer = undefined
+  }
+  inQuery = false
+  // So the next query after a stop is not throttled against a pass that
+  // never ran. A test that stops the queue between cases wants the same
+  // starting point each time.
+  lastQueryEndedAt = 0
+  for (const [key, { resolvers }] of [...resolverMap.entries()]) {
+    resolverMap.delete(key)
+    resolvers.forEach(resolve => resolve(0))
   }
 }
 
+/** How many rates are cached. `engine-status` reports it as `rateCachedCount`. */
+export function rateCacheSize(): number {
+  return rateMap.size
+}
+
 const createRateKey = (
   asset: { pluginId: string; tokenId?: EdgeTokenId } | string,
   targetFiat: string,
@@ -321,7 +462,7 @@ const getHistoricalRate = async (
   doFetch?: EdgeFetchFunction
 ): Promise<number> => {
   return await new Promise((resolve, reject) => {
-    const rate = rateMap[rateKey]
+    const rate = rateMap.get(rateKey)
     if (rate == null) {
       addToQueue(RatesParams, rateKey, resolve, maxQuerySize, doFetch)
       return
diff --git a/src/util/exchangeRatesGui.ts b/src/util/exchangeRatesGui.ts
new file mode 100644
index 00000000000..f19abd689a6
--- /dev/null
+++ b/src/util/exchangeRatesGui.ts
@@ -0,0 +1,17 @@
+/**
+ * GUI wiring for historical rates. Import once at app startup so
+ * `exchangeRates.ts` reports queue errors via Airship.
+ *
+ * Call sites keep importing helpers from `./exchangeRates`.
+ */
+import { showError } from '../components/services/AirshipInstance'
+import { configureExchangeRates } from './exchangeRates'
+
+configureExchangeRates({
+  // Wrapped, not passed bare: a bare reference makes `exchangeRates.ts`'s own
+  // `onQueryError(error)` the reporting frame for every caller, so this file
+  // — the one a reader would blame — appears nowhere in the stack.
+  onError: (error: unknown) => {
+    showError(error)
+  }
+})

From c23b2d8fda67a83816cb7344107640fed72aac1c Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 05/24] Extract Node-safe locale detection

`initLocale` reaches for `react-native-localize`, so nothing outside the
app could ask which locale to use. The decision itself is pure: read a
tag from argv, config or the environment, normalize it, and pick a
language table.

`nodeLocale.ts` holds that decision with no React Native imports, and
feeds the same `applyLocale` that the GUI's device lookup already calls,
so the GUI and any Node caller resolve a locale the same way rather than
approximately the same way.

Precedence is explicit and tested: an explicit tag, then config, then
`EDGE_CLI_LOCALE`, then `LC_ALL` / `LC_MESSAGES` / `LANG`, then `Intl`,
then `en-US`. `es_MX.UTF-8@euro` and `C` both resolve, which is what the
POSIX forms actually look like.

`env` is typed as the variables it reads rather than
`NodeJS.ProcessEnv`, which in this repo demands `NODE_ENV` and would
make every caller invent one.
---
 src/__tests__/nodeLocale.test.ts              | 100 +++++++++++++
 src/__tests__/util/intlLocaleFallback.test.ts |  44 ++++++
 src/locales/nodeLocale.ts                     | 132 ++++++++++++++++++
 3 files changed, 276 insertions(+)
 create mode 100644 src/__tests__/nodeLocale.test.ts
 create mode 100644 src/__tests__/util/intlLocaleFallback.test.ts
 create mode 100644 src/locales/nodeLocale.ts

diff --git a/src/__tests__/nodeLocale.test.ts b/src/__tests__/nodeLocale.test.ts
new file mode 100644
index 00000000000..dbf3067db36
--- /dev/null
+++ b/src/__tests__/nodeLocale.test.ts
@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, test } from '@jest/globals'
+
+import { applyLocale } from '../locales/bootLocale'
+import {
+  detectNodeLocale,
+  localeTagsMatch,
+  normalizePosixLocale,
+  numberSeparators,
+  parseLocaleFlag
+} from '../locales/nodeLocale'
+import { lstrings, selectLocale } from '../locales/strings'
+
+describe('normalizePosixLocale', () => {
+  test('strips encoding and modifier', () => {
+    expect(normalizePosixLocale('es_MX.UTF-8@euro')).toBe('es-MX')
+  })
+  test('C and POSIX become en-US', () => {
+    expect(normalizePosixLocale('C')).toBe('en-US')
+    expect(normalizePosixLocale('POSIX')).toBe('en-US')
+    expect(normalizePosixLocale('')).toBe('en-US')
+  })
+  test('keeps hyphenated tags', () => {
+    expect(normalizePosixLocale('de-DE')).toBe('de-DE')
+  })
+})
+
+describe('parseLocaleFlag', () => {
+  test('reads --locale value', () => {
+    expect(parseLocaleFlag(['--locale', 'fr'])).toBe('fr')
+  })
+  test('reads --locale=', () => {
+    expect(parseLocaleFlag(['--locale=ja'])).toBe('ja')
+  })
+})
+
+describe('detectNodeLocale', () => {
+  test('argv wins over env', () => {
+    const source = detectNodeLocale({
+      argv: ['--locale', 'de-DE'],
+      env: { LANG: 'fr_FR.UTF-8', EDGE_CLI_LOCALE: 'es' }
+    })
+    expect(source.languageTag).toBe('de-DE')
+  })
+  test('config wins over EDGE_CLI_LOCALE', () => {
+    const source = detectNodeLocale({
+      argv: [],
+      env: { EDGE_CLI_LOCALE: 'ja' },
+      configLocale: 'it'
+    })
+    expect(source.languageTag).toBe('it')
+  })
+  test('LANG es_MX.UTF-8', () => {
+    const source = detectNodeLocale({
+      argv: [],
+      env: { LANG: 'es_MX.UTF-8' }
+    })
+    expect(source.languageTag).toBe('es-MX')
+  })
+})
+
+describe('numberSeparators', () => {
+  test('de-DE uses comma decimal', () => {
+    const seps = numberSeparators('de-DE')
+    expect(seps.decimalSeparator).toBe(',')
+    expect(seps.groupingSeparator).toBe('.')
+  })
+})
+
+describe('selectLocale', () => {
+  afterEach(() => {
+    selectLocale('en')
+    applyLocale({
+      languageTag: 'en-US',
+      decimalSeparator: '.',
+      groupingSeparator: ','
+    })
+  })
+
+  test('de changes a known string', () => {
+    const english = lstrings.action_queue_display_unknown_message
+    const matched = selectLocale('de')
+    expect(matched).toBe(true)
+    expect(lstrings.action_queue_display_unknown_message).not.toBe(english)
+  })
+
+  test('zh_CN falls back to zh', () => {
+    expect(selectLocale('zh-CN')).toBe(true)
+  })
+
+  test('es-MX matches esMX table', () => {
+    expect(selectLocale('es-MX')).toBe(true)
+  })
+})
+
+describe('localeTagsMatch', () => {
+  test('hyphen vs underscore', () => {
+    expect(localeTagsMatch('en-US', 'en_US')).toBe(true)
+    expect(localeTagsMatch('de', 'fr')).toBe(false)
+  })
+})
diff --git a/src/__tests__/util/intlLocaleFallback.test.ts b/src/__tests__/util/intlLocaleFallback.test.ts
new file mode 100644
index 00000000000..26880b0425f
--- /dev/null
+++ b/src/__tests__/util/intlLocaleFallback.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from '@jest/globals'
+
+import {
+  getLocaleOrDefaultString,
+  setIntlLocale,
+  truncateDecimals
+} from '../../locales/intl'
+
+const localized = { de: 'Deutsch', en: 'English' }
+
+describe('setIntlLocale', () => {
+  it('keeps the language when only the number format is unusable', () => {
+    // An OS that reports an empty separator says nothing about the language.
+    // Discarding the whole locale made `getLocaleOrDefaultString` resolve
+    // info-server strings in English on such a device, where only number
+    // formatting used to fall back.
+    setIntlLocale({
+      localeIdentifier: 'de_DE',
+      decimalSeparator: '',
+      groupingSeparator: ''
+    })
+    expect(getLocaleOrDefaultString(localized)).toBe('Deutsch')
+    // And the number format really is the English one.
+    expect(truncateDecimals('1.23456', 2)).toBe('1.23')
+  })
+
+  it('falls back entirely when the language itself is unusable', () => {
+    setIntlLocale({
+      localeIdentifier: '',
+      decimalSeparator: ',',
+      groupingSeparator: '.'
+    })
+    expect(getLocaleOrDefaultString(localized)).toBe('English')
+  })
+
+  it('takes a complete locale as given', () => {
+    setIntlLocale({
+      localeIdentifier: 'de_DE',
+      decimalSeparator: ',',
+      groupingSeparator: '.'
+    })
+    expect(getLocaleOrDefaultString(localized)).toBe('Deutsch')
+  })
+})
diff --git a/src/locales/nodeLocale.ts b/src/locales/nodeLocale.ts
new file mode 100644
index 00000000000..176e334f859
--- /dev/null
+++ b/src/locales/nodeLocale.ts
@@ -0,0 +1,132 @@
+/**
+ * CLI locale detection. No react-native.
+ */
+import type { LocaleSource } from './bootLocale'
+
+/**
+ * The environment variables this reads, and nothing else.
+ *
+ * `process.env` satisfies it, but so does `{ LANG: 'es_MX.UTF-8' }`. Typing
+ * this as `NodeJS.ProcessEnv` demanded `NODE_ENV` from every caller, which no
+ * locale test has any reason to set.
+ */
+export type LocaleEnv = Readonly<Record<string, string | undefined>>
+
+export interface DetectNodeLocaleOpts {
+  argv?: string[]
+  env?: LocaleEnv
+  configLocale?: string
+}
+
+/**
+ * POSIX / BCP-47 tag → hyphenated language tag for Intl and selectLocale.
+ * `es_MX.UTF-8@euro` → `es-MX`; `C` / `POSIX` / empty → `en-US`.
+ */
+export function normalizePosixLocale(raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed === '' || trimmed === 'C' || trimmed === 'POSIX') return 'en-US'
+  const noModifier = trimmed.split('@')[0] ?? trimmed
+  const noEncoding = noModifier.split('.')[0] ?? noModifier
+  const hyphenated = noEncoding.replace(/_/g, '-')
+  return hyphenated === '' ? 'en-US' : hyphenated
+}
+
+/**
+ * The value of one flag in argv, in either spelling, or undefined.
+ *
+ * Deliberately lenient and deliberately separate from the real parsers in
+ * `src/cli/parseArgs.ts` and `src/cli/engine/index.ts`: this runs *before*
+ * either of them, from the locale boot, where a usage error has nowhere to
+ * go and the only sensible answer to an unreadable flag is the default. The
+ * real parser reports it a moment later.
+ *
+ * `parseLocaleFlag` and `parseConfigPathFlag` were byte-identical apart from
+ * the names they matched.
+ */
+function parseEarlyFlag(
+  argv: string[],
+  long: string,
+  short?: string
+): string | undefined {
+  const equals = `${long}=`
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === long || (short != null && a === short)) {
+      const next = argv[i + 1]
+      if (next == null || next.startsWith('-')) return undefined
+      return next
+    }
+    if (a.startsWith(equals)) {
+      const value = a.slice(equals.length)
+      return value === '' ? undefined : value
+    }
+  }
+  return undefined
+}
+
+export function parseLocaleFlag(argv: string[]): string | undefined {
+  return parseEarlyFlag(argv, '--locale')
+}
+
+export function parseConfigPathFlag(argv: string[]): string | undefined {
+  return parseEarlyFlag(argv, '--config', '-c')
+}
+
+function nonempty(value: string | undefined): string | undefined {
+  if (value == null) return undefined
+  const trimmed = value.trim()
+  return trimmed === '' ? undefined : trimmed
+}
+
+function posixLanguageTag(env: LocaleEnv): string | undefined {
+  return nonempty(env.LC_ALL) ?? nonempty(env.LC_MESSAGES) ?? nonempty(env.LANG)
+}
+
+export function numberSeparators(languageTag: string): {
+  decimalSeparator: string
+  groupingSeparator: string
+} {
+  try {
+    const parts = new Intl.NumberFormat(languageTag, {
+      useGrouping: true
+    }).formatToParts(1234567.89)
+    const decimal = parts.find(part => part.type === 'decimal')?.value ?? '.'
+    const grouping = parts.find(part => part.type === 'group')?.value ?? ','
+    if (decimal === '' || grouping === '') {
+      return { decimalSeparator: '.', groupingSeparator: ',' }
+    }
+    return { decimalSeparator: decimal, groupingSeparator: grouping }
+  } catch {
+    return { decimalSeparator: '.', groupingSeparator: ',' }
+  }
+}
+
+/**
+ * Precedence: --locale, config locale, EDGE_CLI_LOCALE, LC_ALL / LC_MESSAGES /
+ * LANG, Intl, en-US. One tag drives language and number format.
+ */
+export function detectNodeLocale(
+  opts: DetectNodeLocaleOpts = {}
+): LocaleSource {
+  const env = opts.env ?? process.env
+  const argv = opts.argv ?? []
+  const raw =
+    nonempty(parseLocaleFlag(argv)) ??
+    nonempty(opts.configLocale) ??
+    nonempty(env.EDGE_CLI_LOCALE) ??
+    posixLanguageTag(env) ??
+    nonempty(Intl.DateTimeFormat().resolvedOptions().locale) ??
+    'en-US'
+  const languageTag = normalizePosixLocale(raw)
+  return {
+    languageTag,
+    ...numberSeparators(languageTag)
+  }
+}
+
+export function localeTagsMatch(a: string, b: string): boolean {
+  return (
+    a.replace(/[-_]/g, '').toLowerCase() ===
+    b.replace(/[-_]/g, '').toLowerCase()
+  )
+}

From 6256aadedc840fda20b806b3304d98f1ccdfba59 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 06/24] Extract Node-safe transaction display metadata
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`CategoriesActions.ts` held five hundred lines deciding what a
transaction should be called: the category, the payee, the direction,
and the label for each action type. All of it is a pure function of the
transaction, the wallet and the account, but it sat behind Redux
imports, so nothing outside the app could ask the same question and get
the same answer.

`src/util/txDisplay/` holds that logic now — `displayInfo` for the
derivation, `category` for the category strings, `txActionLabels` for
the action names, and `currencyCodes` for the ticker lookups.
`CategoriesActions` re-exports what the GUI already imported, so no
scene changed.

The point is that two callers cannot drift. A transaction rendered in a
list, exported to CSV, or printed by a script now describes itself
identically, because it is the same code deciding.
---
 src/__tests__/util/txDisplay.test.ts          | 293 +++++++++++
 src/components/modals/CategoryModal.tsx       |  10 +-
 .../scenes/TransactionDetailsScene.tsx        |   8 +-
 src/components/themed/TransactionListRow.tsx  |   8 +-
 src/util/CurrencyWalletHelpers.ts             |  17 +-
 src/util/fiatCode.ts                          |  27 +
 src/util/txDisplay/category.ts                |  68 +++
 src/util/txDisplay/displayInfo.ts             | 470 ++++++++++++++++++
 src/util/txDisplay/index.ts                   |   6 +
 src/util/txDisplay/txActionLabels.ts          |  39 ++
 10 files changed, 916 insertions(+), 30 deletions(-)
 create mode 100644 src/__tests__/util/txDisplay.test.ts
 create mode 100644 src/util/fiatCode.ts
 create mode 100644 src/util/txDisplay/category.ts
 create mode 100644 src/util/txDisplay/displayInfo.ts
 create mode 100644 src/util/txDisplay/index.ts
 create mode 100644 src/util/txDisplay/txActionLabels.ts

diff --git a/src/__tests__/util/txDisplay.test.ts b/src/__tests__/util/txDisplay.test.ts
new file mode 100644
index 00000000000..09ba3c6430b
--- /dev/null
+++ b/src/__tests__/util/txDisplay.test.ts
@@ -0,0 +1,293 @@
+import { describe, expect, it } from '@jest/globals'
+import type {
+  EdgeAccount,
+  EdgeCurrencyWallet,
+  EdgeTransaction
+} from 'edge-core-js'
+
+import { joinCategory, splitCategory } from '../../util/txDisplay/category'
+import {
+  fillTxMetadataForDisplay,
+  getTxActionDisplayInfo
+} from '../../util/txDisplay/displayInfo'
+
+describe('splitCategory', () => {
+  it('reads each known prefix, case-insensitively', () => {
+    expect(splitCategory('Expense:Food')).toStrictEqual({
+      category: 'expense',
+      subcategory: 'Food'
+    })
+    expect(splitCategory('expense:Food')).toStrictEqual({
+      category: 'expense',
+      subcategory: 'Food'
+    })
+    expect(splitCategory('Transfer:')).toStrictEqual({
+      category: 'transfer',
+      subcategory: ''
+    })
+    expect(splitCategory('Income:Gift')).toStrictEqual({
+      category: 'income',
+      subcategory: 'Gift'
+    })
+    expect(splitCategory('Exchange:Swap')).toStrictEqual({
+      category: 'exchange',
+      subcategory: 'Swap'
+    })
+  })
+
+  it('matches a bare category name with no colon', () => {
+    expect(splitCategory('Expense')).toStrictEqual({
+      category: 'expense',
+      subcategory: ''
+    })
+  })
+
+  it('replaces an unrecognised prefix and keeps the user text whole', () => {
+    // Nothing of an unrecognised string is a category this code knows, and
+    // all of it is text a user, a dapp or `--metadata` put there. Slicing at
+    // the first colon destroyed it: `TransactionDetailsScene` round-trips
+    // this pair through `joinCategory`, so opening and saving such a
+    // transaction wrote the `Shopping` segment away.
+    expect(splitCategory('Shopping:Food')).toStrictEqual({
+      category: 'income',
+      subcategory: 'Shopping:Food'
+    })
+    expect(splitCategory('Foo:bar')).toStrictEqual({
+      category: 'income',
+      subcategory: 'Foo:bar'
+    })
+    // A bare word is the user's own text, not a category name, and used to
+    // come back with the internally appended colon still on it.
+    expect(splitCategory('plain')).toStrictEqual({
+      category: 'income',
+      subcategory: 'plain'
+    })
+  })
+
+  it('honours the default category for the fallback', () => {
+    expect(splitCategory('Foo:bar', 'expense')).toStrictEqual({
+      category: 'expense',
+      subcategory: 'Foo:bar'
+    })
+  })
+
+  it('takes an empty or absent category', () => {
+    expect(splitCategory('')).toStrictEqual({
+      category: 'income',
+      subcategory: ''
+    })
+    expect(splitCategory()).toStrictEqual({
+      category: 'income',
+      subcategory: ''
+    })
+  })
+})
+
+describe('joinCategory', () => {
+  it('round-trips every known prefix', () => {
+    for (const full of [
+      'Transfer:Move',
+      'Exchange:Swap',
+      'Expense:Food',
+      'Income:Gift'
+    ]) {
+      expect(joinCategory(splitCategory(full))).toBe(full)
+    }
+  })
+
+  it('capitalises the prefix the way the GUI writes it', () => {
+    expect(joinCategory(splitCategory('expense:food'))).toBe('Expense:food')
+  })
+})
+
+/**
+ * `getTxActionDisplayInfo` reads only `wallet.id`, `wallet.currencyInfo`,
+ * `wallet.currencyConfig.allTokens`, `account.currencyWallets` and
+ * `account.currencyConfig` — that last one through
+ * `getCurrencyCodeWithAccount`, which is why the stub below supplies it. So
+ * a stub is enough and no core is needed.
+ */
+const wallet: EdgeCurrencyWallet = {
+  id: 'w1',
+  currencyInfo: {
+    pluginId: 'bitcoin',
+    currencyCode: 'BTC',
+    assetDisplayName: 'Bitcoin',
+    denominations: [{ name: 'BTC', multiplier: '100000000' }]
+  },
+  currencyConfig: {
+    allTokens: {},
+    currencyInfo: {
+      pluginId: 'bitcoin',
+      currencyCode: 'BTC',
+      denominations: [{ name: 'BTC', multiplier: '100000000' }]
+    }
+  },
+  fiatCurrencyCode: 'iso:USD'
+} as unknown as EdgeCurrencyWallet
+
+const account = {
+  currencyWallets: { w1: wallet },
+  currencyConfig: { bitcoin: wallet.currencyConfig }
+} as unknown as EdgeAccount
+
+function tx(over: Partial<EdgeTransaction>): EdgeTransaction {
+  return {
+    txid: 'abc',
+    date: 1600000000,
+    currencyCode: 'BTC',
+    tokenId: null,
+    nativeAmount: '-10000',
+    networkFee: '100',
+    blockHeight: 1,
+    isSend: true,
+    memos: [],
+    ourReceiveAddresses: [],
+    signedTx: '',
+    walletId: 'w1',
+    ...over
+  } as unknown as EdgeTransaction
+}
+
+describe('getTxActionDisplayInfo', () => {
+  it('reads a plain send as an expense, and a receive as income', () => {
+    const sent = getTxActionDisplayInfo(tx({}), account, wallet)
+    expect(sent.direction).toBe('send')
+    expect(splitCategory(sent.mergedData.category ?? '').category).toBe(
+      'expense'
+    )
+
+    const received = getTxActionDisplayInfo(
+      tx({ nativeAmount: '10000', isSend: false }),
+      account,
+      wallet
+    )
+    expect(received.direction).toBe('receive')
+    expect(splitCategory(received.mergedData.category ?? '').category).toBe(
+      'income'
+    )
+  })
+
+  it('treats a zero-amount send as a send', () => {
+    const zero = getTxActionDisplayInfo(
+      tx({ nativeAmount: '0', isSend: true }),
+      account,
+      wallet
+    )
+    expect(zero.direction).toBe('send')
+  })
+
+  it('derives an exchange category from a swap action', () => {
+    const swap = getTxActionDisplayInfo(
+      tx({
+        savedAction: {
+          actionType: 'swap',
+          swapInfo: {
+            pluginId: 'fakeswap',
+            displayName: 'Fake Swap',
+            supportEmail: 'a@b.c'
+          },
+          fromAsset: { pluginId: 'bitcoin', tokenId: null },
+          toAsset: { pluginId: 'bitcoin', tokenId: null },
+          payoutAddress: 'addr',
+          payoutWalletId: 'w1'
+        },
+        assetAction: { assetActionType: 'swap' }
+      }),
+      account,
+      wallet
+    )
+    expect(splitCategory(swap.mergedData.category ?? '').category).toBe(
+      'exchange'
+    )
+    expect(swap.action?.actionType).toBe('swap')
+    expect(swap.assetAction?.assetActionType).toBe('swap')
+  })
+
+  it('names the stake plugin for a stake action', () => {
+    const stake = getTxActionDisplayInfo(
+      tx({
+        savedAction: {
+          actionType: 'stake',
+          pluginId: 'bitcoin',
+          stakeAssets: [{ pluginId: 'bitcoin', tokenId: null }]
+        },
+        assetAction: { assetActionType: 'stake' }
+      }),
+      account,
+      wallet
+    )
+    expect(stake.action?.actionType).toBe('stake')
+    expect(stake.mergedData.name).not.toBe('')
+  })
+
+  it('keeps what the user wrote over anything derived', () => {
+    const edited = getTxActionDisplayInfo(
+      tx({
+        metadata: {
+          name: 'My payee',
+          notes: 'My note',
+          category: 'Income:Pay'
+        },
+        savedAction: {
+          actionType: 'stake',
+          pluginId: 'bitcoin',
+          stakeAssets: [{ pluginId: 'bitcoin', tokenId: null }]
+        },
+        assetAction: { assetActionType: 'stake' }
+      }),
+      account,
+      wallet
+    )
+    expect(edited.mergedData.name).toBe('My payee')
+    expect(edited.mergedData.notes).toBe('My note')
+    expect(edited.mergedData.category).toBe('Income:Pay')
+    // The derived values are still reported separately, so a caller can show
+    // both.
+    expect(edited.userData.name).toBe('My payee')
+    expect(edited.savedData.name).not.toBe('My payee')
+  })
+
+  it('prefers savedAction over chainAction', () => {
+    const both = getTxActionDisplayInfo(
+      tx({
+        savedAction: {
+          actionType: 'stake',
+          pluginId: 'bitcoin',
+          stakeAssets: []
+        },
+        chainAction: {
+          actionType: 'tokenApproval',
+          tokenApproved: { pluginId: 'bitcoin', tokenId: null },
+          tokenContractAddress: 'a',
+          contractAddress: 'b'
+        }
+      }),
+      account,
+      wallet
+    )
+    expect(both.action?.actionType).toBe('stake')
+  })
+})
+
+describe('fillTxMetadataForDisplay', () => {
+  it('overlays the three display fields and keeps the rest', () => {
+    const original = tx({
+      metadata: { exchangeAmount: { 'iso:USD': 12 }, bizId: 7, name: 'old' }
+    })
+    const filled = fillTxMetadataForDisplay(original, {
+      name: 'new',
+      category: 'Expense:Food',
+      notes: 'why'
+    })
+    expect(filled.metadata).toStrictEqual({
+      exchangeAmount: { 'iso:USD': 12 },
+      bizId: 7,
+      name: 'new',
+      category: 'Expense:Food',
+      notes: 'why'
+    })
+    // Not persisted, and the original is untouched.
+    expect(original.metadata?.name).toBe('old')
+  })
+})
diff --git a/src/components/modals/CategoryModal.tsx b/src/components/modals/CategoryModal.tsx
index 08ae7180c93..6f01d48c7cd 100644
--- a/src/components/modals/CategoryModal.tsx
+++ b/src/components/modals/CategoryModal.tsx
@@ -4,13 +4,10 @@ import type { AirshipBridge } from 'react-native-airship'
 import { FlatList } from 'react-native-gesture-handler'
 
 import {
-  type Category,
   displayCategories,
   formatCategory,
   getSubcategories,
-  joinCategory,
-  setNewSubcategory,
-  splitCategory
+  setNewSubcategory
 } from '../../actions/CategoriesActions'
 import { SCROLL_INDICATOR_INSET_FIX } from '../../constants/constantSettings'
 import { useAsyncEffect } from '../../hooks/useAsyncEffect'
@@ -18,6 +15,11 @@ import { useHandler } from '../../hooks/useHandler'
 import { lstrings } from '../../locales/strings'
 import { useDispatch, useSelector } from '../../types/reactRedux'
 import { scale } from '../../util/scaling'
+import {
+  type Category,
+  joinCategory,
+  splitCategory
+} from '../../util/txDisplay'
 import { MinimalButton } from '../buttons/MinimalButton'
 import { EdgeTouchableOpacity } from '../common/EdgeTouchableOpacity'
 import { showError } from '../services/AirshipInstance'
diff --git a/src/components/scenes/TransactionDetailsScene.tsx b/src/components/scenes/TransactionDetailsScene.tsx
index 1d17b7a482c..475a1a88a02 100644
--- a/src/components/scenes/TransactionDetailsScene.tsx
+++ b/src/components/scenes/TransactionDetailsScene.tsx
@@ -13,12 +13,7 @@ import FastImage from 'react-native-fast-image'
 import IonIcon from 'react-native-vector-icons/Ionicons'
 import { sprintf } from 'sprintf-js'
 
-import {
-  formatCategory,
-  getTxActionDisplayInfo,
-  pluginIdIcons,
-  splitCategory
-} from '../../actions/CategoriesActions'
+import { formatCategory, pluginIdIcons } from '../../actions/CategoriesActions'
 import { playSendSound } from '../../actions/SoundActions'
 import { getFiatSymbol } from '../../constants/WalletAndCurrencyConstants'
 import { useContactThumbnail } from '../../hooks/redux/useContactThumbnail'
@@ -37,6 +32,7 @@ import type { EdgeAppSceneProps } from '../../types/routerTypes'
 import { getCurrencyCodeWithAccount } from '../../util/CurrencyInfoHelpers'
 import { matchJson } from '../../util/matchJson'
 import { getMemoTitle } from '../../util/memoUtils'
+import { getTxActionDisplayInfo, splitCategory } from '../../util/txDisplay'
 import {
   convertNativeToExchange,
   darkenHexColor,
diff --git a/src/components/themed/TransactionListRow.tsx b/src/components/themed/TransactionListRow.tsx
index 9b4a9ca7678..e2b6ab90aa5 100644
--- a/src/components/themed/TransactionListRow.tsx
+++ b/src/components/themed/TransactionListRow.tsx
@@ -12,12 +12,7 @@ import Share from 'react-native-share'
 import Ionicons from 'react-native-vector-icons/Ionicons'
 import { sprintf } from 'sprintf-js'
 
-import {
-  formatCategory,
-  getTxActionDisplayInfo,
-  pluginIdIcons,
-  splitCategory
-} from '../../actions/CategoriesActions'
+import { formatCategory, pluginIdIcons } from '../../actions/CategoriesActions'
 import { getFiatSymbol } from '../../constants/WalletAndCurrencyConstants'
 import { useContactThumbnail } from '../../hooks/redux/useContactThumbnail'
 import { useDisplayDenom } from '../../hooks/useDisplayDenom'
@@ -31,6 +26,7 @@ import { getExchangeDenom } from '../../selectors/DenominationSelectors'
 import { getExchangeRate } from '../../selectors/WalletSelectors'
 import { useSelector } from '../../types/reactRedux'
 import type { NavigationBase } from '../../types/routerTypes'
+import { getTxActionDisplayInfo, splitCategory } from '../../util/txDisplay'
 import {
   DECIMAL_PRECISION,
   decimalOrZero,
diff --git a/src/util/CurrencyWalletHelpers.ts b/src/util/CurrencyWalletHelpers.ts
index 93d755d5c99..29a9eb0dfbe 100644
--- a/src/util/CurrencyWalletHelpers.ts
+++ b/src/util/CurrencyWalletHelpers.ts
@@ -6,7 +6,9 @@ import { showFullScreenSpinner } from '../components/modals/AirshipFullScreenSpi
 import { SPECIAL_CURRENCY_INFO } from '../constants/WalletAndCurrencyConstants'
 import { lstrings } from '../locales/strings'
 import { getFioStakingBalances } from './stakeUtils'
-import { removeIsoPrefix } from './utils'
+// Re-exported, so the GUI's existing importers keep working while one
+// module owns the implementation.
+export { cleanFiatCurrencyCode } from './fiatCode'
 
 /**
  * Safely get a wallet name, returning a fallback when the name is null.
@@ -26,19 +28,6 @@ export function getWalletName(wallet: EdgeCurrencyWallet): string {
  * Takes any form of fiat currency code and returns a version with and without
  * the "iso:" prefix
  */
-export function cleanFiatCurrencyCode(fiatCurrencyCode: string): {
-  fiatCurrencyCode: string
-  isoFiatCurrencyCode: string
-} {
-  if (fiatCurrencyCode.startsWith('iso:')) {
-    return {
-      fiatCurrencyCode: removeIsoPrefix(fiatCurrencyCode),
-      isoFiatCurrencyCode: fiatCurrencyCode
-    }
-  } else {
-    return { fiatCurrencyCode, isoFiatCurrencyCode: `iso:${fiatCurrencyCode}` }
-  }
-}
 
 export const getAvailableBalance = (
   wallet: EdgeCurrencyWallet,
diff --git a/src/util/fiatCode.ts b/src/util/fiatCode.ts
new file mode 100644
index 00000000000..5c487152342
--- /dev/null
+++ b/src/util/fiatCode.ts
@@ -0,0 +1,27 @@
+/**
+ * Fiat code shapes, Node-safe.
+ *
+ * `CurrencyWalletHelpers.ts` holds the GUI's copy of this and imports
+ * Airship, so the CLI cannot reach it — which is why the extraction made a
+ * second copy. One module both can import instead: the value feeds a
+ * user-facing string (the fiat code inside an `Exchange:From %1$s`
+ * subcategory), so two implementations is two places for it to drift.
+ */
+import { removeIsoPrefix } from './utils'
+
+/**
+ * Take any form of fiat currency code and return it both with and without
+ * the `iso:` prefix.
+ */
+export function cleanFiatCurrencyCode(fiatCurrencyCode: string): {
+  fiatCurrencyCode: string
+  isoFiatCurrencyCode: string
+} {
+  if (fiatCurrencyCode.startsWith('iso:')) {
+    return {
+      fiatCurrencyCode: removeIsoPrefix(fiatCurrencyCode),
+      isoFiatCurrencyCode: fiatCurrencyCode
+    }
+  }
+  return { fiatCurrencyCode, isoFiatCurrencyCode: `iso:${fiatCurrencyCode}` }
+}
diff --git a/src/util/txDisplay/category.ts b/src/util/txDisplay/category.ts
new file mode 100644
index 00000000000..5f2429e1856
--- /dev/null
+++ b/src/util/txDisplay/category.ts
@@ -0,0 +1,68 @@
+export type Category = 'transfer' | 'exchange' | 'expense' | 'income'
+
+export interface EdgeCategory {
+  category: Category
+  subcategory: string
+}
+
+const prefixes: Record<Category, string> = {
+  transfer: 'Transfer:',
+  exchange: 'Exchange:',
+  expense: 'Expense:',
+  income: 'Income:'
+}
+
+const tests: Array<[Category, RegExp, number]> = [
+  ['transfer', /^Transfer:/i, 9],
+  ['exchange', /^Exchange:/i, 9],
+  ['expense', /^Expense:/i, 8],
+  ['income', /^Income:/i, 7]
+]
+
+/**
+ * Splits a string into its category and subcategory strings.
+ * The category must fit our enum type, or we will use a fallback.
+ * The subcategory can be localized and freely edited.
+ */
+export function splitCategory(
+  fullCategory: string = '',
+  defaultCategory: Category = 'income'
+): EdgeCategory {
+  // Every prefix test requires the colon, so a bare `Expense` still has to
+  // match the expense category. The original string is what the fallback
+  // below reads, so this added colon cannot leak into a result.
+  const probe =
+    fullCategory.length > 0 && !fullCategory.includes(':')
+      ? `${fullCategory}:`
+      : fullCategory
+  for (const [category, test, n] of tests) {
+    if (test.test(probe)) {
+      return {
+        category,
+        subcategory: probe.slice(n)
+      }
+    }
+  }
+
+  // We can't guarantee that data on disk is correct, but this should usually
+  // never happen. The whole stored string becomes the subcategory, because
+  // none of it is a category this code recognises and all of it is text a
+  // user — or a dapp through `edgeProvider`, or `--metadata` — put there.
+  //
+  // Slicing at the first colon looked tidier and silently destroyed data:
+  // `Shopping:Food` came back as `{ category: 'income', subcategory: 'Food' }`,
+  // and `TransactionDetailsScene` round-trips exactly that pair through
+  // `joinCategory`, so the first time a user opened and saved such a
+  // transaction the `Shopping` segment was written away. The appended-colon
+  // case the `probe` above exists for is already handled there, so nothing
+  // here needs to strip anything.
+  return { category: defaultCategory, subcategory: fullCategory }
+}
+
+/**
+ * Combine the category and subcategory into a single string,
+ * with the correct capitalization.
+ */
+export function joinCategory(split: EdgeCategory): string {
+  return prefixes[split.category] + split.subcategory
+}
diff --git a/src/util/txDisplay/displayInfo.ts b/src/util/txDisplay/displayInfo.ts
new file mode 100644
index 00000000000..5dae691b4ff
--- /dev/null
+++ b/src/util/txDisplay/displayInfo.ts
@@ -0,0 +1,470 @@
+/**
+ * What a transaction should be called.
+ *
+ * A pure function of the transaction, the wallet and the account: the
+ * category, the payee, the direction, and the label for each action type.
+ * Extracted from `CategoriesActions.ts` so the GUI and a Node caller derive
+ * the same answer rather than approximately the same answer.
+ */
+import { eq } from 'biggystring'
+import type {
+  EdgeAccount,
+  EdgeAssetAction,
+  EdgeAssetAmount,
+  EdgeCurrencyWallet,
+  EdgeMetadata,
+  EdgeTransaction,
+  EdgeTxAction
+} from 'edge-core-js'
+import { sprintf } from 'sprintf-js'
+
+import { lstrings } from '../../locales/strings'
+import { cleanFiatCurrencyCode } from '../fiatCode'
+import { type EdgeCategory, joinCategory } from './category'
+import { getCurrencyCodeWithAccount } from './currencyCodes'
+import { txActionLabel } from './txActionLabels'
+
+/**
+ * What `getTxActionDisplayInfo` works out about one transaction.
+ *
+ * `userData` is what the user wrote, `savedData` what the action implies, and
+ * `mergedData` the two combined with the user's values winning.
+ */
+export interface ActionDisplayInfo {
+  direction: 'send' | 'receive'
+  iconPluginId?: string
+  userData: EdgeMetadata
+  savedData: EdgeMetadata
+  mergedData: EdgeMetadata
+  action?: EdgeTxAction
+  assetAction?: EdgeAssetAction
+}
+
+/**
+ * Overlay GUI-computed display name/category/notes onto `tx.metadata` for
+ * API responses. Does not persist. Keeps existing exchangeAmount and other
+ * fields that `getTxActionDisplayInfo` does not own.
+ */
+export const fillTxMetadataForDisplay = (
+  tx: EdgeTransaction,
+  mergedData: EdgeMetadata
+): EdgeTransaction => ({
+  ...tx,
+  metadata: {
+    ...tx.metadata,
+    name: mergedData.name,
+    category: mergedData.category,
+    notes: mergedData.notes
+  }
+})
+
+/**
+ * Given a transaction's `EdgeTxAction`, derive the values that pre-fill the
+ * Category and Notes tiles — unless the user has already edited them, in which
+ * case `mergedData` keeps what they wrote.
+ */
+export const getTxActionDisplayInfo = (
+  tx: EdgeTransaction,
+  account: EdgeAccount,
+  wallet: EdgeCurrencyWallet
+): ActionDisplayInfo => {
+  const {
+    assetAction,
+    chainAction,
+    chainAssetAction,
+    metadata,
+    savedAction,
+    swapData,
+    tokenId
+  } = tx
+  const { currencyConfig, currencyInfo } = wallet
+
+  const displayName =
+    tokenId == null
+      ? currencyInfo.assetDisplayName
+      : currencyConfig.allTokens[tokenId]?.displayName ?? ''
+
+  const action = savedAction ?? chainAction
+  const assetAct = assetAction ?? chainAssetAction
+
+  const getCurrencyCodes = (assets: EdgeAssetAmount[]): string[] =>
+    assets
+      .map(asset =>
+        getCurrencyCodeWithAccount(account, asset.pluginId, asset.tokenId)
+      )
+      .filter((currencyCode): currencyCode is string => currencyCode != null)
+
+  const isSentTransaction =
+    tx.nativeAmount.startsWith('-') || (eq(tx.nativeAmount, '0') && tx.isSend)
+
+  let payeeText: string | undefined
+  let edgeCategory: EdgeCategory
+  let direction: 'send' | 'receive'
+  let notes: string | undefined
+  let iconPluginId: string | undefined
+
+  // Default text for send or receive
+  if (isSentTransaction) {
+    payeeText = sprintf(lstrings.transaction_sent_1s, displayName)
+    direction = 'send'
+    edgeCategory = {
+      category: 'expense',
+      subcategory: ''
+    }
+  } else {
+    payeeText = sprintf(lstrings.transaction_received_1s, displayName)
+    direction = 'receive'
+    edgeCategory = {
+      category: 'income',
+      subcategory: ''
+    }
+  }
+
+  // Override with swapData
+  if (swapData != null) {
+    const { payoutCurrencyCode } = swapData
+    payeeText = sprintf(
+      lstrings.transaction_details_swap_to_subcat_1s,
+      payoutCurrencyCode
+    )
+  }
+
+  if (action != null && assetAct != null) {
+    const { actionType } = action
+    const { assetActionType } = assetAct
+    payeeText = txActionLabel(assetActionType)
+
+    let unsupported = false
+
+    switch (actionType) {
+      case 'swap': {
+        iconPluginId = action.swapInfo.pluginId
+        switch (assetActionType) {
+          case 'transfer': {
+            const txSrc = action.payoutWalletId !== wallet.id
+            const toFromStr = txSrc
+              ? lstrings.transaction_details_swap_to_subcat_1s
+              : lstrings.transaction_details_swap_from_subcat_1s
+            const walletName =
+              account.currencyWallets[action.payoutWalletId]?.name ??
+              displayName
+            edgeCategory = {
+              category: 'transfer',
+              subcategory: sprintf(toFromStr, walletName)
+            }
+            break
+          }
+          case 'transferNetworkFee':
+          case 'swapNetworkFee': {
+            edgeCategory = {
+              category: 'expense',
+              subcategory: lstrings.wc_smartcontract_network_fee
+            }
+            break
+          }
+          case 'swap':
+          case 'swapOrderFill': {
+            // Determine if the swap destination was to a different asset or if the
+            // swap source was from a different asset.
+            const txSrcSameAsset =
+              action.fromAsset.tokenId === tokenId &&
+              action.fromAsset.pluginId === wallet.currencyInfo.pluginId
+            const toFromStr = txSrcSameAsset
+              ? lstrings.transaction_details_swap_to_subcat_1s
+              : lstrings.transaction_details_swap_from_subcat_1s
+            const otherAsset = txSrcSameAsset
+              ? action.toAsset
+              : action.fromAsset
+
+            edgeCategory = {
+              category: 'exchange',
+              subcategory: sprintf(
+                toFromStr,
+                getCurrencyCodeWithAccount(
+                  account,
+                  otherAsset.pluginId,
+                  otherAsset.tokenId
+                )
+              )
+            }
+            direction = txSrcSameAsset ? 'send' : 'receive'
+            break
+          }
+
+          case 'swapOrderPost': {
+            edgeCategory = {
+              category: 'expense',
+              subcategory: sprintf(lstrings.transaction_details_swap_order_post)
+            }
+            direction = 'send'
+            break
+          }
+          case 'swapOrderCancel': {
+            edgeCategory = {
+              category: 'expense',
+              subcategory: sprintf(
+                lstrings.transaction_details_swap_order_cancel
+              )
+            }
+            direction = 'send'
+            break
+          }
+          default:
+            unsupported = true
+        }
+        break
+      }
+      case 'stake': {
+        iconPluginId = action.pluginId
+        switch (assetActionType) {
+          case 'stake': {
+            let subcategory
+            if (action.stakeAssets.length === 1)
+              subcategory = sprintf(
+                lstrings.transaction_details_stake_subcat_1s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else if (action.stakeAssets.length === 2)
+              subcategory = sprintf(
+                lstrings.transaction_details_stake_subcat_2s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else {
+              console.warn(
+                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
+              )
+              break
+            }
+            edgeCategory = { category: 'transfer', subcategory }
+            direction = 'send'
+            break
+          }
+          case 'stakeOrder': {
+            if (action.stakeAssets.length === 1)
+              notes = sprintf(
+                lstrings.transaction_details_unstake_order_notes_1s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else if (action.stakeAssets.length === 2)
+              notes = sprintf(
+                lstrings.transaction_details_unstake_order_notes_2s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else {
+              console.error(
+                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
+              )
+              break
+            }
+
+            edgeCategory = {
+              category: 'expense',
+              subcategory: lstrings.transaction_details_stake_order_subcat
+            }
+            direction = 'send'
+            break
+          }
+          case 'claim': {
+            let subcategory
+            if (action.stakeAssets.length === 1)
+              subcategory = sprintf(
+                lstrings.transaction_details_unstake_subcat_1s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else if (action.stakeAssets.length === 2)
+              subcategory = sprintf(
+                lstrings.transaction_details_unstake_subcat_2s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else {
+              console.error(
+                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
+              )
+              break
+            }
+            edgeCategory = { category: 'transfer', subcategory }
+            if (
+              action.stakeAssets.every(
+                asset => asset.pluginId === currencyInfo.pluginId
+              )
+            ) {
+              direction = 'receive'
+            } else {
+              direction = 'send'
+            }
+            break
+          }
+          case 'unstake': {
+            let subcategory
+            if (action.stakeAssets.length === 1)
+              subcategory = sprintf(
+                lstrings.transaction_details_unstake_subcat_1s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else if (action.stakeAssets.length === 2)
+              subcategory = sprintf(
+                lstrings.transaction_details_unstake_subcat_2s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else {
+              console.error(
+                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
+              )
+              break
+            }
+            edgeCategory = { category: 'transfer', subcategory }
+            direction = 'receive'
+            break
+          }
+          case 'claimOrder':
+          case 'unstakeOrder': {
+            if (action.stakeAssets.length === 1)
+              notes = sprintf(
+                lstrings.transaction_details_unstake_order_notes_1s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else if (action.stakeAssets.length === 2)
+              notes = sprintf(
+                lstrings.transaction_details_unstake_order_notes_2s,
+                ...getCurrencyCodes(action.stakeAssets)
+              )
+            else {
+              console.error(
+                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
+              )
+              break
+            }
+
+            edgeCategory = {
+              category: 'expense',
+              subcategory: lstrings.transaction_details_unstake_order
+            }
+            direction = 'send'
+            break
+          }
+          case 'unstakeNetworkFee':
+          case 'stakeNetworkFee': {
+            edgeCategory = {
+              category: 'expense',
+              subcategory: lstrings.wc_smartcontract_network_fee
+            }
+            break
+          }
+
+          default:
+            unsupported = true
+        }
+        break
+      }
+      case 'fiat': {
+        iconPluginId = action.fiatPlugin.providerId
+        switch (assetActionType) {
+          case 'buy': {
+            payeeText = sprintf(payeeText, displayName)
+            const { fiatAsset } = action
+            const { fiatCurrencyCode } = cleanFiatCurrencyCode(
+              fiatAsset.fiatCurrencyCode
+            )
+            edgeCategory = {
+              category: 'exchange',
+              subcategory: sprintf(
+                lstrings.transaction_details_swap_from_subcat_1s,
+                fiatCurrencyCode
+              )
+            }
+            direction = 'receive'
+            break
+          }
+          case 'sell': {
+            payeeText = sprintf(payeeText, displayName)
+            const { fiatAsset } = action
+            const { fiatCurrencyCode } = cleanFiatCurrencyCode(
+              fiatAsset.fiatCurrencyCode
+            )
+            edgeCategory = {
+              category: 'exchange',
+              subcategory: sprintf(
+                lstrings.transaction_details_swap_to_subcat_1s,
+                fiatCurrencyCode
+              )
+            }
+            direction = 'send'
+            break
+          }
+          case 'sellNetworkFee': {
+            edgeCategory = {
+              category: 'expense',
+              subcategory: lstrings.wc_smartcontract_network_fee
+            }
+            direction = 'send'
+            break
+          }
+          default:
+            unsupported = true
+        }
+        break
+      }
+      case 'tokenApproval': {
+        switch (assetActionType) {
+          case 'tokenApproval': {
+            edgeCategory = {
+              category: 'expense',
+              subcategory: lstrings.wc_smartcontract_network_fee
+            }
+            break
+          }
+          default:
+            unsupported = true
+        }
+        break
+      }
+      case 'giftCard': {
+        iconPluginId = action.provider.providerId
+        payeeText = lstrings.gift_card_recipient_name
+        edgeCategory = {
+          category: 'expense',
+          subcategory: action.card.name
+        }
+        direction = 'send'
+        break
+      }
+      default:
+        unsupported = true
+    }
+
+    if (unsupported)
+      console.error(
+        `Unsupported EdgeTxAction assetAction:assetActionType '${assetActionType}'`
+      )
+  }
+  const savedData: EdgeMetadata = {
+    name: payeeText,
+    category: joinCategory(edgeCategory),
+    notes
+  }
+
+  const mergedData: EdgeMetadata = {
+    name:
+      metadata?.name != null && metadata.name.length > 0
+        ? metadata.name
+        : savedData.name,
+    category:
+      metadata?.category != null && metadata.category.length > 0
+        ? metadata.category
+        : savedData.category,
+    notes:
+      metadata?.notes != null && metadata.notes.length > 0
+        ? metadata.notes
+        : savedData.notes
+  }
+
+  return {
+    action,
+    assetAction,
+    direction,
+    iconPluginId,
+    savedData,
+    userData: metadata ?? {},
+    mergedData
+  }
+}
diff --git a/src/util/txDisplay/index.ts b/src/util/txDisplay/index.ts
new file mode 100644
index 00000000000..48e7ef3fd4e
--- /dev/null
+++ b/src/util/txDisplay/index.ts
@@ -0,0 +1,6 @@
+export type { Category, EdgeCategory } from './category'
+export { joinCategory, splitCategory } from './category'
+export { getCurrencyCodeWithAccount } from './currencyCodes'
+export type { ActionDisplayInfo } from './displayInfo'
+export { fillTxMetadataForDisplay, getTxActionDisplayInfo } from './displayInfo'
+export { txActionLabel } from './txActionLabels'
diff --git a/src/util/txDisplay/txActionLabels.ts b/src/util/txDisplay/txActionLabels.ts
new file mode 100644
index 00000000000..81160737950
--- /dev/null
+++ b/src/util/txDisplay/txActionLabels.ts
@@ -0,0 +1,39 @@
+import type { EdgeAssetActionType } from 'edge-core-js'
+
+import { lstrings } from '../../locales/strings'
+
+/**
+ * The label for one `assetActionType`, read at call time.
+ *
+ * A module-scope `Record` froze all twenty labels to whatever `lstrings` held
+ * when *this* module first evaluated. `applyLocale` mutates `lstrings` in
+ * place, so the values were correct only if the locale boot had already run —
+ * an invisible ordering dependency on a module nothing here imports. Reading
+ * them lazily removes it: there is no order in which this can be wrong.
+ */
+export function txActionLabel(actionType: EdgeAssetActionType): string {
+  return labelMap()[actionType]
+}
+
+const labelMap = (): Record<EdgeAssetActionType, string> => ({
+  buy: lstrings.transaction_details_bought_1s,
+  claim: lstrings.transaction_details_claim,
+  claimOrder: lstrings.transaction_details_claim_order,
+  giftCard: lstrings.transaction_details_gift_card,
+  sell: lstrings.transaction_details_sold_1s,
+  sellNetworkFee: lstrings.fiat_plugin_sell_network_fee,
+  swap: lstrings.transaction_details_swap,
+  swapNetworkFee: lstrings.transaction_details_swap_network_fee,
+  swapOrderPost: lstrings.transaction_details_swap_order_post,
+  swapOrderFill: lstrings.transaction_details_swap_order_fill,
+  swapOrderCancel: lstrings.transaction_details_swap_order_cancel,
+  stake: lstrings.transaction_details_stake,
+  stakeNetworkFee: lstrings.transaction_details_stake_network_fee,
+  stakeOrder: lstrings.transaction_details_stake_order,
+  tokenApproval: lstrings.transaction_details_token_approval,
+  transfer: lstrings.transaction_details_transfer_funds,
+  transferNetworkFee: lstrings.transaction_details_transfer_network_fee,
+  unstake: lstrings.transaction_details_unstake,
+  unstakeNetworkFee: lstrings.transaction_details_unstake_network_fee,
+  unstakeOrder: lstrings.transaction_details_unstake_order
+})

From 5d94d84bd78d8fe962cd2416d6e03f352c75e612 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 07/24] Extract Node-safe denominations and settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three small pieces of GUI state that any caller reading transactions
needs, and none of which had a reason to be Redux-only.

`exchangeDenom` picks the denomination a currency or token reports
amounts in. `DenominationSelectors` keeps its selector shape and calls
it, so the two cannot disagree about what a multiplier is.

`spamThreshold` decides which incoming transactions are dust worth
hiding. The GUI applies it to every list; a caller that reads the same
wallet and does not apply it sees a different set of transactions, which
is the sort of difference that looks like a bug in whichever one you did
not write.

`localAccountSettings` reads the device-local settings file that holds
the spam filter toggle, and `LocalSettingsActions` reads through it
rather than duplicating the format.

The threshold needs a rate, and asks for it at the current hour rather
than the current millisecond, so repeated listings share one cache entry
instead of missing on every call. It is a different source from the
GUI's, which reads live rates from Redux, and a lookup that fails yields
no filtering — stated in the module, because the two can legitimately
disagree.

`syncedSettingsFile` holds the one definition of the synced
`Settings.json` that Node-safe code reads. The GUI's own cleaner sits
behind an Airship import and cannot be loaded here, so this is a
two-field view of the same file with the same defaults, and a test
asserts those defaults still match the GUI's.
---
 .../util/localAccountSettings.test.ts         |  83 ++++++++
 src/__tests__/util/spamThreshold.test.ts      | 197 ++++++++++++++++++
 src/__tests__/util/syncedSettingsFile.test.ts |  45 ++++
 src/actions/LocalSettingsActions.ts           |  39 ++--
 src/configKeysMerge.ts                        |  15 +-
 src/selectors/DenominationSelectors.ts        |  24 +--
 src/util/exchangeDenom.ts                     |  36 ++++
 src/util/fake/fakeDisklet.ts                  |  90 ++++++++
 src/util/localAccountSettings.ts              |  96 +++++++++
 src/util/predicates.ts                        |  69 ++++++
 src/util/spamThreshold.ts                     |  91 ++++++++
 src/util/syncedSettingsFile.ts                |  67 ++++++
 12 files changed, 805 insertions(+), 47 deletions(-)
 create mode 100644 src/__tests__/util/localAccountSettings.test.ts
 create mode 100644 src/__tests__/util/spamThreshold.test.ts
 create mode 100644 src/__tests__/util/syncedSettingsFile.test.ts
 create mode 100644 src/util/exchangeDenom.ts
 create mode 100644 src/util/fake/fakeDisklet.ts
 create mode 100644 src/util/localAccountSettings.ts
 create mode 100644 src/util/predicates.ts
 create mode 100644 src/util/spamThreshold.ts
 create mode 100644 src/util/syncedSettingsFile.ts

diff --git a/src/__tests__/util/localAccountSettings.test.ts b/src/__tests__/util/localAccountSettings.test.ts
new file mode 100644
index 00000000000..18db54e59f1
--- /dev/null
+++ b/src/__tests__/util/localAccountSettings.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it, jest } from '@jest/globals'
+
+import { makeFakeDiskletAccount } from '../../util/fake/fakeDisklet'
+import {
+  readLocalAccountSettingsFromDisk,
+  readLocalAccountSettingsOrDefaults
+} from '../../util/localAccountSettings'
+
+/**
+ * A file that is there and cannot be read.
+ *
+ * `account.localDisklet` is core's `encryptDisklet`, whose `getText` runs
+ * `JSON.parse` then `asEdgeBox` then `decryptText` — so an interrupted write
+ * surfaces as a parse or cleaner error, which is not any of the three
+ * spellings `isMissingFile` knows.
+ */
+const corrupt = (): Error => new SyntaxError('Unexpected end of JSON input')
+
+describe('readLocalAccountSettingsFromDisk', () => {
+  it('yields defaults for an absent file', async () => {
+    const settings = await readLocalAccountSettingsFromDisk(
+      makeFakeDiskletAccount({})
+    )
+    expect(settings.spamFilterOn).toBe(true)
+  })
+
+  it('yields defaults for a file this version cannot read', async () => {
+    const settings = await readLocalAccountSettingsFromDisk(
+      makeFakeDiskletAccount({ local: '{"spamFilterOn":"not a boolean"}' })
+    )
+    expect(settings.spamFilterOn).toBe(true)
+  })
+
+  it('throws when a file that is there cannot be read', async () => {
+    // Deliberate, and the reason the lenient wrapper exists: a
+    // read-modify-write caller answering this with defaults and writing them
+    // back is how `spendingLimits` is destroyed.
+    await expect(
+      readLocalAccountSettingsFromDisk(
+        makeFakeDiskletAccount({ localError: corrupt() })
+      )
+    ).rejects.toThrow(/Unexpected end of JSON/)
+  })
+})
+
+describe('readLocalAccountSettingsOrDefaults', () => {
+  it('trusts a read that succeeded', async () => {
+    const account = makeFakeDiskletAccount({
+      local: '{"spamFilterOn":false}'
+    })
+    const { settings, trusted } = await readLocalAccountSettingsOrDefaults(
+      account
+    )
+    expect(settings.spamFilterOn).toBe(false)
+    expect(trusted).toBe(true)
+  })
+
+  it('trusts an absent file, which is a real answer', async () => {
+    const { settings, trusted } = await readLocalAccountSettingsOrDefaults(
+      makeFakeDiskletAccount({})
+    )
+    expect(settings.spamFilterOn).toBe(true)
+    expect(trusted).toBe(true)
+  })
+
+  it('answers defaults untrusted when the file cannot be read', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { settings, trusted } = await readLocalAccountSettingsOrDefaults(
+        makeFakeDiskletAccount({ localError: corrupt() })
+      )
+      // Untrusted, so the GUI's cached reader leaves `readSettingsFromDisk`
+      // false and a later write cannot persist these over the real file.
+      expect(settings.spamFilterOn).toBe(true)
+      expect(trusted).toBe(false)
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('using defaults')
+      )
+    } finally {
+      warn.mockRestore()
+    }
+  })
+})
diff --git a/src/__tests__/util/spamThreshold.test.ts b/src/__tests__/util/spamThreshold.test.ts
new file mode 100644
index 00000000000..1223b83f116
--- /dev/null
+++ b/src/__tests__/util/spamThreshold.test.ts
@@ -0,0 +1,197 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+import type { EdgeAccount, EdgeCurrencyWallet } from 'edge-core-js'
+
+import { getHistoricalCryptoRate } from '../../util/exchangeRates'
+import { makeFakeDiskletAccount } from '../../util/fake/fakeDisklet'
+import {
+  readDefaultIsoFiat,
+  resolveListSpamThreshold
+} from '../../util/spamThreshold'
+
+jest.mock('../../util/exchangeRates', () => ({
+  getHistoricalCryptoRate: jest.fn()
+}))
+
+const rateMock = getHistoricalCryptoRate as unknown as jest.Mock<
+  (
+    pluginId: string,
+    tokenId: unknown,
+    isoFiat: string,
+    date: string
+  ) => Promise<number>
+>
+
+/** An account whose two disklets return whatever text the test supplies. */
+const makeAccount = makeFakeDiskletAccount
+
+const wallet = {
+  currencyInfo: {
+    pluginId: 'bitcoin',
+    denominations: [{ name: 'BTC', multiplier: '100000000', symbol: '₿' }]
+  },
+  currencyConfig: {
+    currencyInfo: {
+      denominations: [{ name: 'BTC', multiplier: '100000000', symbol: '₿' }]
+    },
+    allTokens: {}
+  }
+} as unknown as EdgeCurrencyWallet
+
+describe('readDefaultIsoFiat', () => {
+  it('defaults to iso:USD when Settings.json is missing', async () => {
+    expect(await readDefaultIsoFiat(makeAccount({}))).toBe('iso:USD')
+  })
+
+  it('defaults to iso:USD when Settings.json is not JSON', async () => {
+    const account = makeAccount({ synced: '{not json' })
+    expect(await readDefaultIsoFiat(account)).toBe('iso:USD')
+  })
+
+  it('defaults to iso:USD when defaultIsoFiat is empty', async () => {
+    const account = makeAccount({ synced: '{"defaultIsoFiat":""}' })
+    expect(await readDefaultIsoFiat(account)).toBe('iso:USD')
+  })
+
+  it('returns the stored fiat', async () => {
+    const account = makeAccount({ synced: '{"defaultIsoFiat":"iso:EUR"}' })
+    expect(await readDefaultIsoFiat(account)).toBe('iso:EUR')
+  })
+})
+
+describe('resolveListSpamThreshold', () => {
+  beforeEach(() => {
+    rateMock.mockReset()
+    rateMock.mockResolvedValue(50000)
+  })
+
+  it('treats an empty override as "show everything"', async () => {
+    const threshold = await resolveListSpamThreshold({
+      account: makeAccount({}),
+      wallet,
+      tokenId: null,
+      queryOverride: ''
+    })
+    expect(threshold).toBe('0')
+    expect(rateMock).not.toHaveBeenCalled()
+  })
+
+  it('passes an explicit override straight through', async () => {
+    const threshold = await resolveListSpamThreshold({
+      account: makeAccount({}),
+      wallet,
+      tokenId: null,
+      queryOverride: '500'
+    })
+    expect(threshold).toBe('500')
+  })
+
+  it('returns undefined when the spam filter is off', async () => {
+    const account = makeAccount({ local: '{"spamFilterOn":false}' })
+    const threshold = await resolveListSpamThreshold({
+      account,
+      wallet,
+      tokenId: null
+    })
+    expect(threshold).toBeUndefined()
+    expect(rateMock).not.toHaveBeenCalled()
+  })
+
+  it('still answers when Settings.json cannot be read', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      // Present and unreadable, which `isMissingFile` cannot match. This used
+      // to propagate out of every `get-transactions` on the default path.
+      const account = makeAccount({
+        localError: new SyntaxError('Unexpected end of JSON input')
+      })
+      const threshold = await resolveListSpamThreshold({
+        account,
+        wallet,
+        tokenId: null
+      })
+      expect(threshold).not.toBeUndefined()
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  it('filters by default when no local settings exist', async () => {
+    const threshold = await resolveListSpamThreshold({
+      account: makeAccount({}),
+      wallet,
+      tokenId: null
+    })
+    expect(threshold).not.toBeUndefined()
+    expect(rateMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('quantises the rate lookup to the hour, so repeat calls hit the cache', async () => {
+    await resolveListSpamThreshold({
+      account: makeAccount({}),
+      wallet,
+      tokenId: null
+    })
+
+    const date = rateMock.mock.calls[0][3]
+    expect(date).toMatch(/T\d{2}:00:00\.000Z$/)
+    expect(new Date(date).getTime() % (60 * 60 * 1000)).toBe(0)
+  })
+
+  it('does not filter when the rate lookup fails', async () => {
+    rateMock.mockRejectedValue(new Error('rates server down'))
+    const threshold = await resolveListSpamThreshold({
+      account: makeAccount({}),
+      wallet,
+      tokenId: null
+    })
+    expect(threshold).toBe('0')
+  })
+
+  it('does not filter when the rate is not finite', async () => {
+    rateMock.mockResolvedValue(Number.NaN)
+    const threshold = await resolveListSpamThreshold({
+      account: makeAccount({}),
+      wallet,
+      tokenId: null
+    })
+    expect(threshold).toBe('0')
+  })
+
+  it('uses the account default fiat for the rate', async () => {
+    const account = makeAccount({ synced: '{"defaultIsoFiat":"iso:EUR"}' })
+    await resolveListSpamThreshold({ account, wallet, tokenId: null })
+    expect(rateMock.mock.calls[0][2]).toBe('iso:EUR')
+  })
+
+  it('uses the caller-supplied fiat instead of reading Settings.json again', async () => {
+    let syncedReads = 0
+    const account = {
+      disklet: {
+        getText: async () => {
+          syncedReads++
+          return '{"defaultIsoFiat":"iso:EUR"}'
+        }
+      },
+      localDisklet: { getText: async () => '{"spamFilterOn":true}' }
+    } as unknown as EdgeAccount
+    rateMock.mockResolvedValue(30000)
+
+    await resolveListSpamThreshold({
+      account,
+      wallet,
+      tokenId: null,
+      isoFiat: 'iso:USD'
+    })
+
+    // The handler has already resolved it, and `readSyncedSettings` — which
+    // is what reads the *synced* Settings.json this counter is counting —
+    // deliberately has no process-wide cache to absorb a repeat read.
+    expect(syncedReads).toBe(0)
+    expect(rateMock).toHaveBeenCalledWith(
+      'bitcoin',
+      null,
+      'iso:USD',
+      expect.any(String)
+    )
+  })
+})
diff --git a/src/__tests__/util/syncedSettingsFile.test.ts b/src/__tests__/util/syncedSettingsFile.test.ts
new file mode 100644
index 00000000000..7c92fd93bb8
--- /dev/null
+++ b/src/__tests__/util/syncedSettingsFile.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { asSyncedAccountSettings } from '../../actions/SettingsActions'
+import {
+  asSyncedSettingsSubset,
+  SYNCED_SETTINGS_FILENAME
+} from '../../util/syncedSettingsFile'
+
+describe('asSyncedSettingsSubset', () => {
+  it('agrees with the GUI cleaner on the fields it shares', () => {
+    // The GUI's cleaner cannot be imported by Node-safe code (it pulls in
+    // Airship), so this pins the subset's defaults to it instead.
+    const guiDefaults = asSyncedAccountSettings({})
+    const subsetDefaults = asSyncedSettingsSubset({})
+
+    expect(subsetDefaults.autoLogoutTimeInSeconds).toBe(
+      guiDefaults.autoLogoutTimeInSeconds
+    )
+    expect(subsetDefaults.defaultIsoFiat).toBe(guiDefaults.defaultIsoFiat)
+  })
+
+  it('reads the same file the GUI writes', () => {
+    expect(SYNCED_SETTINGS_FILENAME).toBe('Settings.json')
+  })
+
+  it('keeps unknown fields rather than stripping the GUI’s settings', () => {
+    const cleaned = asSyncedSettingsSubset({
+      autoLogoutTimeInSeconds: 60,
+      walletsSort: 'name'
+    })
+    expect(cleaned.autoLogoutTimeInSeconds).toBe(60)
+    expect((cleaned as unknown as { walletsSort: string }).walletsSort).toBe(
+      'name'
+    )
+  })
+
+  it('falls back to the defaults for a malformed value', () => {
+    const cleaned = asSyncedSettingsSubset({
+      autoLogoutTimeInSeconds: 'soon',
+      defaultIsoFiat: 42
+    })
+    expect(cleaned.autoLogoutTimeInSeconds).toBe(3600)
+    expect(cleaned.defaultIsoFiat).toBe('iso:USD')
+  })
+})
diff --git a/src/actions/LocalSettingsActions.ts b/src/actions/LocalSettingsActions.ts
index 0e18aa591c2..7d28d5ec2e5 100644
--- a/src/actions/LocalSettingsActions.ts
+++ b/src/actions/LocalSettingsActions.ts
@@ -15,9 +15,14 @@ import {
   type PasswordReminder,
   type SpendingLimits
 } from '../types/types'
+import {
+  LOCAL_SETTINGS_FILENAME,
+  readLocalAccountSettingsOrDefaults,
+  writeLocalAccountSettingsToDisk
+} from '../util/localAccountSettings'
 import { logActivity } from '../util/logger'
 
-export const LOCAL_SETTINGS_FILENAME = 'Settings.json'
+export { LOCAL_SETTINGS_FILENAME }
 
 // Long enough to read the instructions in the balance-hidden toast:
 const TOAST_HIDE_MS = 5000
@@ -316,21 +321,18 @@ export const readLocalAccountSettings = async (
     return localAccountSettings
   }
 
-  try {
-    const text = await account.localDisklet.getText(LOCAL_SETTINGS_FILENAME)
-    const json = JSON.parse(text)
-    const settings = asLocalAccountSettings(json)
-    emitAccountSettings(settings)
-    readSettingsFromDisk = true
-    return settings
-  } catch (error: unknown) {
-    // If Settings.json doesn't exist yet, return defaults without writing.
-    // Defaults can be derived from cleaners. Only write when values change.
-    const defaults = asLocalAccountSettings({})
-    emitAccountSettings(defaults)
-    readSettingsFromDisk = true
-    return defaults
-  }
+  // Lenient: this is the GUI's read-only cached reader, reached from
+  // `initializeAccount`, and before this branch it could not fail. A
+  // `Settings.json` that is present but unreadable must not stop the login.
+  // `readSettingsFromDisk` stays false in that case, so a later
+  // `writeLocalAccountSettings` cannot persist these defaults over the real
+  // file — the loss the strict reader exists to prevent.
+  const { settings, trusted } = await readLocalAccountSettingsOrDefaults(
+    account
+  )
+  emitAccountSettings(settings)
+  readSettingsFromDisk = trusted
+  return settings
 }
 
 export const writeLocalAccountSettings = async (
@@ -339,9 +341,6 @@ export const writeLocalAccountSettings = async (
 ): Promise<LocalAccountSettings> => {
   // Refresh cache, notify callers
   emitAccountSettings(settings)
-
-  const text = JSON.stringify(settings)
-  await account.localDisklet.setText(LOCAL_SETTINGS_FILENAME, text)
-
+  await writeLocalAccountSettingsToDisk(account, settings)
   return settings
 }
diff --git a/src/configKeysMerge.ts b/src/configKeysMerge.ts
index ea5c69f656d..f3129770a2e 100644
--- a/src/configKeysMerge.ts
+++ b/src/configKeysMerge.ts
@@ -9,15 +9,20 @@ import {
   type GlobalKeys,
   type RuntimeKeys
 } from './configKeysSchema'
+import { isPlainObject } from './util/predicates'
 
 /** Open string-keyed object; fails closed on non-objects (unlike a soft coerce). */
 const asUnknownMap = asObject(asUnknown)
 
-export function isPlainObject(
-  value: unknown
-): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
+/**
+ * Re-exported, not re-declared.
+ *
+ * This module exported a byte-equivalent second copy, and
+ * `src/util/keysStore.ts` imports it from here — so the repo had two
+ * exported `isPlainObject` functions and a hand-written third test inside
+ * `requireBodyObject`, which is what `predicates.ts` was created to end.
+ */
+export { isPlainObject }
 
 /** Maps inside a keys payload that must stay objects to merge safely. */
 const KEYS_PAYLOAD_MAP_FIELDS = [
diff --git a/src/selectors/DenominationSelectors.ts b/src/selectors/DenominationSelectors.ts
index 53fa7dd6ab0..1003c4ce71a 100644
--- a/src/selectors/DenominationSelectors.ts
+++ b/src/selectors/DenominationSelectors.ts
@@ -5,12 +5,9 @@ import type {
 } from 'edge-core-js'
 
 import type { RootState } from '../types/reduxTypes'
+import { emptyEdgeDenomination, getExchangeDenom } from '../util/exchangeDenom'
 
-export const emptyEdgeDenomination: EdgeDenomination = Object.freeze({
-  name: '',
-  multiplier: '1',
-  symbol: ''
-})
+export { emptyEdgeDenomination, getExchangeDenom } from '../util/exchangeDenom'
 
 export const selectDisplayDenom = (
   state: RootState,
@@ -33,20 +30,3 @@ export const selectDisplayDenom = (
   }
   return exchangeDenomination
 }
-
-/**
- * Looks up the denomination for a tokenId.
- * Pass either `account.currencyConfig[pluginId]` or `wallet.currencyConfig`,
- * whichever you have.
- */
-export function getExchangeDenom(
-  currencyConfig: EdgeCurrencyConfig,
-  tokenId: EdgeTokenId
-): EdgeDenomination {
-  if (tokenId == null) return currencyConfig.currencyInfo.denominations[0]
-
-  const token = currencyConfig.allTokens[tokenId]
-  if (token != null) return token.denominations[0]
-
-  return emptyEdgeDenomination
-}
diff --git a/src/util/exchangeDenom.ts b/src/util/exchangeDenom.ts
new file mode 100644
index 00000000000..3f87f49a13e
--- /dev/null
+++ b/src/util/exchangeDenom.ts
@@ -0,0 +1,36 @@
+import type {
+  EdgeCurrencyConfig,
+  EdgeDenomination,
+  EdgeTokenId
+} from 'edge-core-js'
+
+import { hasOwn } from './predicates'
+
+export const emptyEdgeDenomination: EdgeDenomination = Object.freeze({
+  name: '',
+  multiplier: '1',
+  symbol: ''
+})
+
+/**
+ * Looks up the denomination for a tokenId.
+ * Pass either `account.currencyConfig[pluginId]` or `wallet.currencyConfig`,
+ * whichever you have.
+ */
+export function getExchangeDenom(
+  currencyConfig: EdgeCurrencyConfig,
+  tokenId: EdgeTokenId
+): EdgeDenomination {
+  if (tokenId == null) return currencyConfig.currencyInfo.denominations[0]
+
+  // `hasOwn`, because `allTokens` is a plain object: `allTokens['__proto__']`
+  // is `Object.prototype`, which is not null, so this took the token branch
+  // and evaluated `Object.prototype.denominations[0]` — a `TypeError`, and
+  // `spamThreshold.ts` reaches here before any route-level token check runs.
+  if (hasOwn(currencyConfig.allTokens, tokenId)) {
+    const token = currencyConfig.allTokens[tokenId]
+    if (token != null) return token.denominations[0]
+  }
+
+  return emptyEdgeDenomination
+}
diff --git a/src/util/fake/fakeDisklet.ts b/src/util/fake/fakeDisklet.ts
new file mode 100644
index 00000000000..8a7f9842b72
--- /dev/null
+++ b/src/util/fake/fakeDisklet.ts
@@ -0,0 +1,90 @@
+/**
+ * Accounts and wallets whose disklets return whatever a test supplies.
+ *
+ * Several suites built the same two stubs by hand — "an account whose
+ * disklet returns this text", "a bitcoin wallet with one denomination" —
+ * under the same names, with the `File not found` sentinel repeated because
+ * that is what `isMissingFile` matches. Eleven ad-hoc
+ * `as unknown as EdgeAccount` literals across seven files, which is how a
+ * change to what counts as an absent file ends up fixed in some of them.
+ */
+import type { EdgeAccount, EdgeCurrencyWallet } from 'edge-core-js'
+
+/**
+ * The error disklet raises for a file that is not there.
+ *
+ * Three backends spell it three ways and `isMissingFile` knows all three;
+ * this is the memory backend's, which is what a stub should imitate.
+ */
+export function missingFileError(): Error {
+  return new Error('File not found')
+}
+
+export interface FakeDiskletAccountOpts {
+  /** Text the *synced* disklet returns, or absent for a missing file. */
+  synced?: string
+  /** Text the *local* disklet returns, or absent for a missing file. */
+  local?: string
+  /**
+   * An error the *local* disklet raises instead of answering.
+   *
+   * For a file that is present and unreadable, which is a different case
+   * from absent: `account.localDisklet` is core's `encryptDisklet`, so a
+   * truncated file fails inside `JSON.parse`/`decryptText` and does not
+   * match `isMissingFile`.
+   */
+  localError?: Error
+  /** Counts each synced read, for a test measuring repeat reads. */
+  onSyncedRead?: () => void
+  username?: string
+  rootLoginId?: string
+}
+
+/** An account that is nothing but two disklets. */
+export function makeFakeDiskletAccount(
+  opts: FakeDiskletAccountOpts = {}
+): EdgeAccount {
+  const read = async (text: string | undefined): Promise<string> => {
+    if (text == null) throw missingFileError()
+    return text
+  }
+  return {
+    username: opts.username ?? 'clitester',
+    rootLoginId: opts.rootLoginId ?? 'root123',
+    logout: async () => {},
+    waitForAllWallets: async () => {},
+    disklet: {
+      getText: async () => {
+        opts.onSyncedRead?.()
+        return await read(opts.synced)
+      }
+    },
+    localDisklet: {
+      getText: async () => {
+        if (opts.localError != null) throw opts.localError
+        return await read(opts.local)
+      }
+    }
+  } as unknown as EdgeAccount
+}
+
+const BTC_DENOM = { name: 'BTC', multiplier: '100000000', symbol: '₿' }
+
+/** A wallet with one denomination and no tokens. */
+export function makeFakeDenomWallet(
+  opts: { pluginId?: string; id?: string } = {}
+): EdgeCurrencyWallet {
+  const pluginId = opts.pluginId ?? 'bitcoin'
+  return {
+    id: opts.id ?? 'wallet-1',
+    currencyInfo: {
+      pluginId,
+      currencyCode: 'BTC',
+      denominations: [BTC_DENOM]
+    },
+    currencyConfig: {
+      currencyInfo: { pluginId, denominations: [BTC_DENOM] },
+      allTokens: {}
+    }
+  } as unknown as EdgeCurrencyWallet
+}
diff --git a/src/util/localAccountSettings.ts b/src/util/localAccountSettings.ts
new file mode 100644
index 00000000000..5f62db0cb44
--- /dev/null
+++ b/src/util/localAccountSettings.ts
@@ -0,0 +1,96 @@
+import { asJSON, asMaybe, uncleaner } from 'cleaners'
+import type { EdgeAccount } from 'edge-core-js'
+
+import {
+  asLocalAccountSettings,
+  type LocalAccountSettings
+} from '../types/types'
+import { isMissingFile } from './predicates'
+
+const uncleanLocalAccountSettings = uncleaner(asLocalAccountSettings)
+
+export const LOCAL_SETTINGS_FILENAME = 'Settings.json'
+
+/**
+ * Read account.localDisklet Settings.json.
+ *
+ * An **absent** file, or one whose contents this version cannot read, yields
+ * the cleaner's defaults (`spamFilterOn: true`). A failure to *read* a file
+ * that is there does not: it throws.
+ *
+ * The distinction is the whole point. `changeLocalSettings` is a
+ * read-modify-write over this one file, so answering any failure with the
+ * 13 defaults and then writing them back turned one unreadable file — an
+ * interrupted write, a bad sync — into the loss of `spendingLimits`,
+ * `passwordReminder`, `notifState`, `reviewTrigger`, `developerModeOn`,
+ * `isAccountBalanceVisible` and `tokenWarningsShown`. The user's spending
+ * limits among them.
+ *
+ * No process-wide cache — the GUI wrapper in LocalSettingsActions.ts keeps
+ * that.
+ */
+export async function readLocalAccountSettingsFromDisk(
+  account: EdgeAccount
+): Promise<LocalAccountSettings> {
+  let text: string
+  try {
+    text = await account.localDisklet.getText(LOCAL_SETTINGS_FILENAME)
+  } catch (error: unknown) {
+    if (!isMissingFile(error)) throw error
+    return asLocalAccountSettings({})
+  }
+  // `asJSON`, so one cleaner owns both the parse and the shape. A file this
+  // version cannot read is as good as absent: the cleaner's defaults are the
+  // only thing it could become either way.
+  return (
+    asMaybe(asJSON(asLocalAccountSettings))(text) ?? asLocalAccountSettings({})
+  )
+}
+
+/**
+ * As `readLocalAccountSettingsFromDisk`, for a caller that only reads.
+ *
+ * The strict reader exists so a read-modify-write cannot answer an
+ * unreadable file with the 13 defaults and then write them back over the
+ * user's `spendingLimits`. That argument is about the *write*, and applying
+ * it to read-only callers took something that could not fail before this
+ * branch and made it fatal: `account.localDisklet` is core's
+ * `encryptDisklet`, so a truncated `Settings.json` — the interrupted write
+ * the strict reader's own docstring cites — throws a parse or cleaner error
+ * that `isMissingFile` cannot match. That propagated out of
+ * `initializeAccount`, so the `LOGIN` action was never dispatched and the
+ * user sat on the login scene with a toast on every attempt; it also hard
+ * failed `GET /local-settings` and every `get-transactions`, through
+ * `resolveListSpamThreshold`.
+ *
+ * `trusted` is false when the file was there and could not be read. A caller
+ * that caches must not then mark itself authoritative, or a later write would
+ * persist these defaults over the real file — which is the destruction the
+ * strict reader is for, arriving by the other door.
+ */
+export async function readLocalAccountSettingsOrDefaults(
+  account: EdgeAccount
+): Promise<{ settings: LocalAccountSettings; trusted: boolean }> {
+  try {
+    return {
+      settings: await readLocalAccountSettingsFromDisk(account),
+      trusted: true
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.warn(
+      `Could not read ${LOCAL_SETTINGS_FILENAME}, using defaults: ${message}`
+    )
+    return { settings: asLocalAccountSettings({}), trusted: false }
+  }
+}
+
+export async function writeLocalAccountSettingsToDisk(
+  account: EdgeAccount,
+  settings: LocalAccountSettings
+): Promise<LocalAccountSettings> {
+  // Through the cleaner's uncleaner, so a shape change is a compile error.
+  const text = JSON.stringify(uncleanLocalAccountSettings(settings))
+  await account.localDisklet.setText(LOCAL_SETTINGS_FILENAME, text)
+  return settings
+}
diff --git a/src/util/predicates.ts b/src/util/predicates.ts
new file mode 100644
index 00000000000..1c480d0c948
--- /dev/null
+++ b/src/util/predicates.ts
@@ -0,0 +1,69 @@
+/**
+ * Small predicates the engine and the GUI share.
+ *
+ * Each of these existed in four or five places under two or three names:
+ * `isObject`, `isPlainObject` and the body-shape test inside
+ * `requireBodyObject` are the same check, and `isMissingFile` was
+ * byte-identical in three modules. One copy each, so a change to what counts
+ * as "an object" or "an absent file" happens once.
+ *
+ * In `src/util/` rather than `src/cli/engine/`, because
+ * `src/util/exportTxInfo.ts` uses it and that module is reached from
+ * `TransactionsExportScene`: the shipped React Native bundle must not import
+ * out of the daemon's directory, and it only worked because this file
+ * happens to have no imports. It still has none, so nothing is dragged in by
+ * using it.
+ */
+
+/** An object that is not an array — the shape a JSON body or record has. */
+export function isPlainObject(
+  value: unknown
+): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * A key the object really has, not one it inherits.
+ *
+ * `map[key] != null` is not that test. Core builds `account.currencyWallets`
+ * and `currencyConfig.allTokens` as plain object literals, so
+ * `wallets['__proto__']` is `Object.prototype` — truthy — and
+ * `allTokens['__proto__'] == null` is false. Every lookup whose key is
+ * caller input therefore let `__proto__`, `constructor`, `toString`,
+ * `valueOf`, `hasOwnProperty`, `isPrototypeOf`, `propertyIsEnumerable` and
+ * `toLocaleString` past the guard that exists to stop them, and the
+ * `TypeError` that followed surfaced as `500 INTERNAL_ERROR` with no field
+ * name.
+ *
+ * `Object.prototype.hasOwnProperty.call`, not `Object.hasOwn`: this module
+ * is reached from the React Native bundle as well as the daemon.
+ */
+export function hasOwn(object: object, key: string | number | symbol): boolean {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+/**
+ * An absent file, as opposed to a failure to read one that is there.
+ *
+ * Three spellings, because three backends produce it: `ENOENT` from
+ * disklet's node backend, `File not found` from its memory backend, and
+ * `Cannot load "<path>"` from core's encrypted repo disklet. That last one
+ * was missing, and it is the one the engine actually meets — a wallet that
+ * has never saved export preferences answered `500 INTERNAL_ERROR` instead
+ * of starting a fresh map, so `get-transactions --save-export-prefs` could
+ * not succeed on any wallet.
+ *
+ * The distinction matters in the other direction too: answering a real I/O
+ * failure the way an absent file is answered turns one unreadable file into
+ * a rewrite of whatever it held.
+ */
+export function isMissingFile(error: unknown): boolean {
+  if (error == null || typeof error !== 'object') return false
+  const code = (error as { code?: unknown }).code
+  if (code === 'ENOENT') return true
+  const message = (error as { message?: unknown }).message
+  return (
+    typeof message === 'string' &&
+    /not found|no such file|cannot load/i.test(message)
+  )
+}
diff --git a/src/util/spamThreshold.ts b/src/util/spamThreshold.ts
new file mode 100644
index 00000000000..9e759cc34ca
--- /dev/null
+++ b/src/util/spamThreshold.ts
@@ -0,0 +1,91 @@
+import type { EdgeAccount, EdgeCurrencyWallet, EdgeTokenId } from 'edge-core-js'
+
+import { getExchangeDenom } from './exchangeDenom'
+import { getHistoricalCryptoRate } from './exchangeRates'
+import { readLocalAccountSettingsOrDefaults } from './localAccountSettings'
+import {
+  asSyncedSettingsSubset,
+  readSyncedSettings
+} from './syncedSettingsFile'
+import { calculateSpamThreshold } from './utils'
+
+/**
+ * Synced account Settings.json on account.disklet (not localDisklet).
+ * defaultIsoFiat defaults to iso:USD, matching asSyncedAccountSettings.
+ */
+export async function readDefaultIsoFiat(
+  account: EdgeAccount
+): Promise<string> {
+  const { defaultIsoFiat } = await readSyncedSettings(account)
+  // The cleaner's fallback covers an absent field; an empty *string* in the
+  // file is a value it would keep, and no fiat code is the empty string.
+  return defaultIsoFiat === ''
+    ? asSyncedSettingsSubset({}).defaultIsoFiat
+    : defaultIsoFiat
+}
+
+/** An hour is finer than a dust threshold needs and coarse enough to cache. */
+const RATE_BUCKET_MS = 60 * 60 * 1000
+
+/**
+ * Same visibility rule as the GUI transaction list, with a different rate
+ * source: the GUI reads live rates from Redux, this asks for a historical
+ * rate at the current hour. An explicit query override wins. Otherwise honor
+ * spamFilterOn (default true) and calculateSpamThreshold from defaultIsoFiat
+ * and that rate. A missing or non-finite rate yields `'0'` — no filtering —
+ * where the GUI's live rate would have filtered.
+ */
+export async function resolveListSpamThreshold(opts: {
+  account: EdgeAccount
+  wallet: EdgeCurrencyWallet
+  tokenId: EdgeTokenId
+  /**
+   * The fiat to price in, resolved by the caller.
+   *
+   * Passed in rather than read again: the only caller has already resolved
+   * it, and reading the account's synced `Settings.json` a second time for
+   * the identical answer is the whole cost of this function's default path.
+   */
+  isoFiat?: string
+  queryOverride?: string
+}): Promise<string | undefined> {
+  // An empty override means "no threshold", which core spells `'0'`. The
+  // REST route cannot produce it — `queryToObject` reads `?spamThreshold=` as
+  // an absent parameter, and `?spamThreshold=0` is the spelling that route
+  // documents — but a direct caller can, and `''` must not reach core.
+  if (opts.queryOverride !== undefined) {
+    return opts.queryOverride === '' ? '0' : opts.queryOverride
+  }
+
+  // Lenient, and this is the one that matters most: a `Settings.json` that
+  // cannot be read used to fail *every* `get-transactions`, on the default
+  // path, with nothing here catching it.
+  const { settings } = await readLocalAccountSettingsOrDefaults(opts.account)
+  if (!settings.spamFilterOn) return undefined
+
+  const defaultIsoFiat =
+    opts.isoFiat ?? (await readDefaultIsoFiat(opts.account))
+  const denom = getExchangeDenom(opts.wallet.currencyConfig, opts.tokenId)
+  let rate = 0
+  try {
+    // Quantised to the hour. `getHistoricalCryptoRate` folds the date string
+    // into its cache key, so a millisecond-precision timestamp missed the
+    // cache on every call: each listing waited a full FETCH_FREQUENCY before
+    // the request even started, and left a permanent entry in the module-level
+    // rate map. In the GUI this value came from a Redux selector, so neither
+    // cost existed there.
+    const bucketedNow = new Date(
+      Math.floor(Date.now() / RATE_BUCKET_MS) * RATE_BUCKET_MS
+    ).toISOString()
+    rate = await getHistoricalCryptoRate(
+      opts.wallet.currencyInfo.pluginId,
+      opts.tokenId,
+      defaultIsoFiat,
+      bucketedNow
+    )
+  } catch {
+    rate = 0
+  }
+  if (!Number.isFinite(rate)) rate = 0
+  return calculateSpamThreshold(rate, denom)
+}
diff --git a/src/util/syncedSettingsFile.ts b/src/util/syncedSettingsFile.ts
new file mode 100644
index 00000000000..04e99560b08
--- /dev/null
+++ b/src/util/syncedSettingsFile.ts
@@ -0,0 +1,67 @@
+import { asJSON, asMaybe, asNumber, asObject, asString } from 'cleaners'
+
+/** The synced account settings file, on `account.disklet`. */
+export const SYNCED_SETTINGS_FILENAME = 'Settings.json'
+
+/**
+ * The fields of the synced settings that Node-safe code reads.
+ *
+ * The GUI's full `asSyncedAccountSettings` lives in `actions/SettingsActions`,
+ * which imports Airship, so neither the CLI engine nor the extracted modules
+ * can reach it. This is a narrow `.withRest` view of the same file with the
+ * same defaults — `syncedSettingsFile.test.ts` asserts the two agree, so the
+ * subset cannot drift from the file the GUI writes.
+ */
+export const asSyncedSettingsSubset = asObject({
+  autoLogoutTimeInSeconds: asMaybe(asNumber, 3600),
+  defaultIsoFiat: asMaybe(asString, 'iso:USD')
+}).withRest
+
+/**
+ * The account's synced settings, with the cleaner's defaults applied.
+ *
+ * One reader. `readAutoLogoutSeconds` and `readDefaultIsoFiat` were the same
+ * `getText` → `asMaybe(asJSON(…))` → field wrapper with an identical empty
+ * `catch`, and each restated a default the cleaner already supplies — so
+ * changing a default here left two call sites stale.
+ *
+ * An absent file, or one this version cannot read, yields the defaults —
+ * which is what every caller wanted from its own `catch`. A failure to read
+ * a file that *is* there throws, so a caller that must not change its mind
+ * on a transient failure can tell the two apart; `readSyncedSettingsOrThrow`
+ * below is that caller's entry point.
+ */
+export async function readSyncedSettings(account: {
+  disklet: { getText: (path: string) => Promise<string> }
+}): Promise<SyncedSettingsSubset> {
+  try {
+    return await readSyncedSettingsOrThrow(account)
+  } catch {
+    // Unreadable: the defaults are the answer for a caller with nothing
+    // better to fall back to.
+    return asSyncedSettingsSubset({})
+  }
+}
+
+/**
+ * The same read, letting an I/O or decryption failure out.
+ *
+ * The engine's auto-logout ticker re-reads this file every sweep and has a
+ * `catch` whose stated job is to keep the last known window. That `catch`
+ * was dead code, because `readSyncedSettings` swallows the failure itself —
+ * so one unreadable read silently replaced a live `autoLogoutTimeInSeconds`
+ * with the cleaner's 3600, and an account that had set `0` to disable
+ * auto-logout was logged out an hour later, mid-script.
+ */
+export async function readSyncedSettingsOrThrow(account: {
+  disklet: { getText: (path: string) => Promise<string> }
+}): Promise<SyncedSettingsSubset> {
+  const text = await account.disklet.getText(SYNCED_SETTINGS_FILENAME)
+  // A file this version cannot parse is as good as absent: the defaults are
+  // the only thing it could become. Only the read itself is allowed to fail.
+  return (
+    asMaybe(asJSON(asSyncedSettingsSubset))(text) ?? asSyncedSettingsSubset({})
+  )
+}
+
+export type SyncedSettingsSubset = ReturnType<typeof asSyncedSettingsSubset>

From 249c8da7ce1a03e66ff5419118f98a1f891e7a6c Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 08/24] Extract the Node-safe transaction export pipeline

`TransactionExportActions.tsx` was a five-hundred-line thunk that did
four separable jobs: fill in historical fiat values, render CSV, render
QBO, and render the Bitwave format. Only the last step needed React
Native, and only for writing the file.

`fillTxsFiat` asks the rates server what each transaction was worth on
the day it happened, which is the part that makes an export more than a
dump of native amounts. `txExport/format` renders the three formats.
`exportTxInfo` holds the Bitwave account mapping the exporter needs.

The thunk keeps the file-writing and the share sheet, and calls the same
renderers. `TransactionsExportScene` follows it. A test now covers
`fillTxsFiat` against a partial wallet, which is all it reads.

The formats matter here: an export that a person reconciles against
their books has to be byte-identical whichever tool produced it, and the
only way to be sure of that is for one renderer to produce both.
---
 .../actions/TransactionExportActions.test.ts  |  36 +-
 src/__tests__/fillTxsFiat.test.ts             | 149 +++++
 src/__tests__/util/serializeByKey.test.ts     |  77 +++
 src/actions/CategoriesActions.ts              | 501 +----------------
 src/actions/TransactionExportActions.tsx      | 525 +-----------------
 .../scenes/TransactionsExportScene.tsx        |  62 +--
 src/constants/txActionConstants.ts            |  26 -
 src/util/exportTxInfo.ts                      | 112 ++++
 src/util/fillTxsFiat.ts                       |  86 +++
 src/util/serializeByKey.ts                    |  38 ++
 src/util/txExport/format.ts                   | 490 ++++++++++++++++
 src/util/txExport/index.ts                    |  41 ++
 12 files changed, 1068 insertions(+), 1075 deletions(-)
 create mode 100644 src/__tests__/fillTxsFiat.test.ts
 create mode 100644 src/__tests__/util/serializeByKey.test.ts
 delete mode 100644 src/constants/txActionConstants.ts
 create mode 100644 src/util/exportTxInfo.ts
 create mode 100644 src/util/fillTxsFiat.ts
 create mode 100644 src/util/serializeByKey.ts
 create mode 100644 src/util/txExport/format.ts
 create mode 100644 src/util/txExport/index.ts

diff --git a/src/__tests__/actions/TransactionExportActions.test.ts b/src/__tests__/actions/TransactionExportActions.test.ts
index cb590dcfacf..e10325c10a8 100644
--- a/src/__tests__/actions/TransactionExportActions.test.ts
+++ b/src/__tests__/actions/TransactionExportActions.test.ts
@@ -6,7 +6,7 @@ import {
   exportTransactionsToBitwave,
   exportTransactionsToCSVInner,
   exportTransactionsToQBO
-} from '../../actions/TransactionExportActions'
+} from '../../util/txExport'
 
 const csvResult = fs.readFileSync('./src/__tests__/exportCsvResult.csv', {
   encoding: 'utf8'
@@ -196,6 +196,40 @@ test('export QBO matches reference data', function () {
   expect(out).toEqual(qboResult)
 })
 
+test('export QBO keeps its declared charset', function () {
+  // The header says `ENCODING:USASCII` / `CHARSET:1252`, which is what
+  // accounting importers expect, so the bytes have to match it. A payee or
+  // memo holds anything a dapp, `--metadata` or the engine's localized prose
+  // puts there, and those were previously emitted raw under an ASCII
+  // declaration. The alternative considered — declaring `ENCODING:UNICODE` —
+  // changed the format on 100% of exports and is not unambiguously UTF-8 in
+  // OFX 1.x.
+  const out = exportTransactionsToQBO(
+    [
+      {
+        ...edgeTxs[0],
+        metadata: {
+          name: 'Café Münster — naïve',
+          notes: 'Überweisung ✓',
+          category: 'Expense:Food'
+        }
+      }
+    ],
+    'iso:USD',
+    '100',
+    1524578071304
+  )
+  expect(out).toContain('ENCODING:USASCII')
+  expect(out).toContain('CHARSET:1252')
+  // Every byte inside the printable-ASCII range, so the declaration is true.
+  // eslint-disable-next-line no-control-regex
+  expect(/[^\x09\x0a\x0d\x20-\x7e]/.test(out)).toBe(false)
+  // And the original characters are recoverable, as numeric references.
+  expect(out).toContain('Caf&#233;')
+  expect(out).toContain('M&#252;nster')
+  expect(out).toContain('&#8212;')
+})
+
 test('export Bitwave matches reference data', async function () {
   const out = await exportTransactionsToBitwave(
     BITWAVE_ACCOUNT_ID,
diff --git a/src/__tests__/fillTxsFiat.test.ts b/src/__tests__/fillTxsFiat.test.ts
new file mode 100644
index 00000000000..4660f724f8c
--- /dev/null
+++ b/src/__tests__/fillTxsFiat.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it, jest } from '@jest/globals'
+import type { EdgeCurrencyWallet, EdgeTransaction } from 'edge-core-js'
+
+import { fillTxsFiat, toIsoFiatCode } from '../util/fillTxsFiat'
+
+/**
+ * Records how many lookups are outstanding at once.
+ *
+ * The point of the change this suite covers is that every rate is queued
+ * *before* anything is awaited, so one `doQuery` cycle drains a whole page
+ * instead of one cycle per ten transactions — roughly 1.1s against 120s for
+ * 1,200 transactions, which is past the client's own socket timeout. Without
+ * measuring concurrency, the old chunked loop and the new one produce
+ * byte-identical results under a mock, so the shape could regress silently.
+ */
+const concurrency = { current: 0, peak: 0 }
+
+jest.mock('../util/exchangeRates', () => ({
+  getHistoricalCryptoRate: jest.fn(
+    async (_pluginId: string, _tokenId: unknown, isoFiat: string) => {
+      concurrency.current++
+      if (concurrency.current > concurrency.peak) {
+        concurrency.peak = concurrency.current
+      }
+      // A microtask boundary, not a timer: `jestSetup` installs fake timers
+      // globally, so a `setTimeout` here would never fire. Every caller
+      // queued before the first await has incremented by the time this
+      // resumes.
+      await Promise.resolve()
+      concurrency.current--
+      if (isoFiat === 'iso:EUR') return 40000
+      return 50000
+    }
+  )
+}))
+
+function makeWallet(): EdgeCurrencyWallet {
+  // Incomplete core wallet — fillTxsFiat only reads currencyInfo and
+  // currencyConfig, so the cast says what the shape really is.
+  const wallet = {
+    currencyInfo: { pluginId: 'bitcoin' },
+    currencyConfig: {
+      currencyInfo: {
+        pluginId: 'bitcoin',
+        denominations: [{ name: 'BTC', multiplier: '100000000', symbol: '₿' }]
+      },
+      allTokens: {}
+    }
+  }
+  return wallet as unknown as EdgeCurrencyWallet
+}
+
+function makeTx(overrides: Partial<EdgeTransaction> = {}): EdgeTransaction {
+  const tx: EdgeTransaction = {
+    blockHeight: 1,
+    currencyCode: 'BTC',
+    date: 1700000000,
+    deviceDescription: 'test',
+    isSend: false,
+    memos: [],
+    nativeAmount: '100000000',
+    networkFee: '0',
+    networkFees: [],
+    ourReceiveAddresses: [],
+    parentNetworkFee: '0',
+    signedTx: '',
+    tokenId: null,
+    txid: 'txid',
+    walletId: '',
+    ...overrides
+  }
+  return tx
+}
+
+describe('fillTxsFiat', () => {
+  it('fills missing isoFiat from the historical rate', async () => {
+    const tx = makeTx({ metadata: { name: 'Keep me' } })
+    await fillTxsFiat({
+      wallet: makeWallet(),
+      tokenId: null,
+      isoFiat: 'iso:USD',
+      txs: [tx]
+    })
+    expect(tx.metadata?.name).toBe('Keep me')
+    expect(tx.metadata?.exchangeAmount?.['iso:USD']).toBe(50000)
+  })
+
+  it('skips txs that already have a non-zero amount for that fiat', async () => {
+    const tx = makeTx({
+      metadata: { exchangeAmount: { 'iso:USD': 12.5 } }
+    })
+    await fillTxsFiat({
+      wallet: makeWallet(),
+      tokenId: null,
+      isoFiat: 'iso:USD',
+      txs: [tx]
+    })
+    expect(tx.metadata?.exchangeAmount?.['iso:USD']).toBe(12.5)
+  })
+
+  it('fills an override fiat without dropping other stored amounts', async () => {
+    const tx = makeTx({
+      metadata: { exchangeAmount: { 'iso:USD': 12.5 } }
+    })
+    await fillTxsFiat({
+      wallet: makeWallet(),
+      tokenId: null,
+      isoFiat: 'iso:EUR',
+      txs: [tx]
+    })
+    expect(tx.metadata?.exchangeAmount?.['iso:USD']).toBe(12.5)
+    expect(tx.metadata?.exchangeAmount?.['iso:EUR']).toBe(40000)
+  })
+})
+
+describe('toIsoFiatCode', () => {
+  it('accepts a 3-letter code, optional iso: prefix, and any case', () => {
+    expect(toIsoFiatCode('USD')).toBe('iso:USD')
+    expect(toIsoFiatCode('eur')).toBe('iso:EUR')
+    expect(toIsoFiatCode('iso:GBP')).toBe('iso:GBP')
+    expect(toIsoFiatCode('  cad ')).toBe('iso:CAD')
+  })
+
+  it('rejects non-fiat codes', () => {
+    expect(toIsoFiatCode('')).toBeUndefined()
+    expect(toIsoFiatCode('US')).toBeUndefined()
+    expect(toIsoFiatCode('USDT')).toBeUndefined()
+    expect(toIsoFiatCode('123')).toBeUndefined()
+  })
+})
+
+describe('fillTxsFiat concurrency', () => {
+  it('queues every rate before awaiting any of them', async () => {
+    concurrency.current = 0
+    concurrency.peak = 0
+    const txs = Array.from({ length: 25 }, (_unused, i) =>
+      makeTx({ txid: `tx${i}`, date: 1700000000 + i * 86_400 })
+    )
+    await fillTxsFiat({
+      wallet: makeWallet(),
+      tokenId: null,
+      isoFiat: 'iso:USD',
+      txs
+    })
+    // 25, not 10: the chunked loop awaited ten at a time, and each chunk
+    // paid its own debounce.
+    expect(concurrency.peak).toBe(25)
+  })
+})
diff --git a/src/__tests__/util/serializeByKey.test.ts b/src/__tests__/util/serializeByKey.test.ts
new file mode 100644
index 00000000000..bbed71aef13
--- /dev/null
+++ b/src/__tests__/util/serializeByKey.test.ts
@@ -0,0 +1,77 @@
+import { afterAll, beforeAll, describe, expect, it, jest } from '@jest/globals'
+
+import { pendingKeyCount, serializeByKey } from '../../util/serializeByKey'
+
+// `jestSetup.js` installs fake timers for every suite. These cases are about
+// real interleaving, so they need the real clock.
+beforeAll(() => {
+  jest.useRealTimers()
+})
+afterAll(() => {
+  jest.useFakeTimers()
+})
+
+/** A read-modify-write over one shared value, with an await in the middle. */
+function makeStore(): {
+  bump: () => Promise<void>
+  value: () => number
+} {
+  let value = 0
+  return {
+    value: () => value,
+    bump: async () => {
+      const read = value
+      await new Promise(resolve => setTimeout(resolve, 5))
+      value = read + 1
+    }
+  }
+}
+
+describe('serializeByKey', () => {
+  it('a read-modify-write loses updates without it', async () => {
+    const store = makeStore()
+    await Promise.all([store.bump(), store.bump(), store.bump()])
+    // Each call read 0 before any of them wrote, so two increments vanished —
+    // the same way two `mergeExportTxInfo` calls discarded each other's keys.
+    expect(store.value()).toBe(1)
+  })
+
+  it('serializes operations sharing a key', async () => {
+    const store = makeStore()
+    await Promise.all([
+      serializeByKey('k', store.bump),
+      serializeByKey('k', store.bump),
+      serializeByKey('k', store.bump)
+    ])
+    expect(store.value()).toBe(3)
+  })
+
+  it('does not serialize across different keys', async () => {
+    const order: string[] = []
+    const slow = async (): Promise<void> => {
+      await new Promise(resolve => setTimeout(resolve, 20))
+      order.push('slow')
+    }
+    const quick = async (): Promise<void> => {
+      order.push('quick')
+    }
+    await Promise.all([serializeByKey('a', slow), serializeByKey('b', quick)])
+    expect(order).toStrictEqual(['quick', 'slow'])
+  })
+
+  it('a failure does not poison the queue behind it', async () => {
+    const store = makeStore()
+    const failed = serializeByKey('k', async () => {
+      throw new Error('boom')
+    })
+    const after = serializeByKey('k', store.bump)
+    await expect(failed).rejects.toThrow('boom')
+    await after
+    expect(store.value()).toBe(1)
+  })
+
+  it('returns the operation value and drops the key when idle', async () => {
+    await expect(serializeByKey('k', async () => 42)).resolves.toBe(42)
+    expect(pendingKeyCount()).toBe(0)
+  })
+})
diff --git a/src/actions/CategoriesActions.ts b/src/actions/CategoriesActions.ts
index 0ece8f2055e..f83bbe23dd9 100644
--- a/src/actions/CategoriesActions.ts
+++ b/src/actions/CategoriesActions.ts
@@ -1,29 +1,15 @@
-import { eq } from 'biggystring'
-import type {
-  EdgeAccount,
-  EdgeAssetAction,
-  EdgeAssetAmount,
-  EdgeCurrencyWallet,
-  EdgeMetadata,
-  EdgeTransaction,
-  EdgeTxAction
-} from 'edge-core-js'
-import { sprintf } from 'sprintf-js'
+import type { EdgeAccount } from 'edge-core-js'
 
 import { showError } from '../components/services/AirshipInstance'
 import { EDGE_CONTENT_SERVER_URI } from '../constants/CdnConstants'
-import { TX_ACTION_LABEL_MAP } from '../constants/txActionConstants'
 import { lstrings } from '../locales/strings'
 import type { ThunkAction } from '../types/reduxTypes'
-import { getCurrencyCodeWithAccount } from '../util/CurrencyInfoHelpers'
-import { cleanFiatCurrencyCode } from '../util/CurrencyWalletHelpers'
+import type { EdgeCategory } from '../util/txDisplay'
 
-export type Category = 'transfer' | 'exchange' | 'expense' | 'income'
-
-export interface EdgeCategory {
-  category: Category
-  subcategory: string
-}
+// No re-exports of the Node-safe helpers. This module imports `showError`
+// from Airship, so re-exporting them made it the public door to code that
+// exists precisely so it can load without react-native. Callers import from
+// `util/txDisplay` directly.
 
 /**
  * Use these strings to show categories in a user's language.
@@ -71,43 +57,6 @@ export function setNewSubcategory(
   }
 }
 
-/**
- * Splits a string into its category and subcategory strings.
- * The category must fit our enum type, or we will use a fallback.
- * The subcategory can be localized and freely edited.
- */
-export function splitCategory(
-  fullCategory: string = '',
-  defaultCategory: Category = 'income'
-): EdgeCategory {
-  if (fullCategory.length > 0 && !fullCategory.includes(':')) {
-    fullCategory += ':'
-  }
-  for (const [category, test, n] of tests) {
-    if (test.test(fullCategory)) {
-      return {
-        category,
-        subcategory: fullCategory.slice(n)
-      }
-    }
-  }
-
-  // We can't guarantee that data on disk is correct,
-  // but this should usually never happen:
-  return {
-    category: defaultCategory,
-    subcategory: fullCategory.replace(/^[^:]:/, '')
-  }
-}
-
-/**
- * Combine the category and subcategory into a single string,
- * with the correct capitalization.
- */
-export function joinCategory(split: EdgeCategory): string {
-  return prefixes[split.category] + split.subcategory
-}
-
 /**
  * Localizes a category string for display.
  */
@@ -116,23 +65,6 @@ export function formatCategory(split: EdgeCategory): string {
   return `${displayCategories[split.category]}:${split.subcategory}`
 }
 
-/**
- * Internal prefixes used on disk.
- */
-const prefixes = {
-  transfer: 'Transfer:',
-  exchange: 'Exchange:',
-  expense: 'Expense:',
-  income: 'Income:'
-}
-
-const tests: Array<[Category, RegExp, number]> = [
-  ['transfer', /^Transfer:/i, 9],
-  ['exchange', /^Exchange:/i, 9],
-  ['expense', /^Expense:/i, 8],
-  ['income', /^Income:/i, 7]
-]
-
 export interface CategoriesFile {
   categories: string[]
 }
@@ -284,427 +216,6 @@ export const defaultCategories = [
   'Transfer:Dark Wallet'
 ]
 
-/**
- * Given an EdgeTxAction, returns the display value for pre-filling the
- * 'Category' and 'Notes' tiles, if they are not already user-modified.
- */
-
-export interface ActionDisplayInfo {
-  direction: 'send' | 'receive'
-  iconPluginId?: string
-  userData: EdgeMetadata
-  savedData: EdgeMetadata
-  mergedData: EdgeMetadata
-  action?: EdgeTxAction
-  assetAction?: EdgeAssetAction
-}
-
-export const getTxActionDisplayInfo = (
-  tx: EdgeTransaction,
-  account: EdgeAccount,
-  wallet: EdgeCurrencyWallet
-): ActionDisplayInfo => {
-  const {
-    assetAction,
-    chainAction,
-    chainAssetAction,
-    metadata,
-    savedAction,
-    swapData,
-    tokenId
-  } = tx
-  const { currencyConfig, currencyInfo } = wallet
-
-  const displayName =
-    tokenId == null
-      ? currencyInfo.assetDisplayName
-      : currencyConfig.allTokens[tokenId]?.displayName ?? ''
-
-  const action = savedAction ?? chainAction
-  const assetAct = assetAction ?? chainAssetAction
-
-  const getCurrencyCodes = (assets: EdgeAssetAmount[]): string[] =>
-    assets
-      .map(asset =>
-        getCurrencyCodeWithAccount(account, asset.pluginId, asset.tokenId)
-      )
-      .filter((currencyCode): currencyCode is string => currencyCode != null)
-
-  const isSentTransaction =
-    tx.nativeAmount.startsWith('-') || (eq(tx.nativeAmount, '0') && tx.isSend)
-
-  let payeeText: string | undefined
-  let edgeCategory: EdgeCategory
-  let direction: 'send' | 'receive'
-  let notes: string | undefined
-  let iconPluginId: string | undefined
-
-  // Default text for send or receive
-  if (isSentTransaction) {
-    payeeText = sprintf(lstrings.transaction_sent_1s, displayName)
-    direction = 'send'
-    edgeCategory = {
-      category: 'expense',
-      subcategory: ''
-    }
-  } else {
-    payeeText = sprintf(lstrings.transaction_received_1s, displayName)
-    direction = 'receive'
-    edgeCategory = {
-      category: 'income',
-      subcategory: ''
-    }
-  }
-
-  // Override with swapData
-  if (swapData != null) {
-    const { payoutCurrencyCode } = swapData
-    payeeText = sprintf(
-      lstrings.transaction_details_swap_to_subcat_1s,
-      payoutCurrencyCode
-    )
-  }
-
-  if (action != null && assetAct != null) {
-    const { actionType } = action
-    const { assetActionType } = assetAct
-    payeeText = TX_ACTION_LABEL_MAP[assetActionType]
-
-    let unsupported = false
-
-    switch (actionType) {
-      case 'swap': {
-        iconPluginId = action.swapInfo.pluginId
-        switch (assetActionType) {
-          case 'transfer': {
-            const txSrc = action.payoutWalletId !== wallet.id
-            const toFromStr = txSrc
-              ? lstrings.transaction_details_swap_to_subcat_1s
-              : lstrings.transaction_details_swap_from_subcat_1s
-            const walletName =
-              account.currencyWallets[action.payoutWalletId]?.name ??
-              displayName
-            edgeCategory = {
-              category: 'transfer',
-              subcategory: sprintf(toFromStr, walletName)
-            }
-            break
-          }
-          case 'transferNetworkFee':
-          case 'swapNetworkFee': {
-            edgeCategory = {
-              category: 'expense',
-              subcategory: lstrings.wc_smartcontract_network_fee
-            }
-            break
-          }
-          case 'swap':
-          case 'swapOrderFill': {
-            // Determine if the swap destination was to a different asset or if the
-            // swap source was from a different asset.
-            const txSrcSameAsset =
-              action.fromAsset.tokenId === tokenId &&
-              action.fromAsset.pluginId === wallet.currencyInfo.pluginId
-            const toFromStr = txSrcSameAsset
-              ? lstrings.transaction_details_swap_to_subcat_1s
-              : lstrings.transaction_details_swap_from_subcat_1s
-            const otherAsset = txSrcSameAsset
-              ? action.toAsset
-              : action.fromAsset
-
-            edgeCategory = {
-              category: 'exchange',
-              subcategory: sprintf(
-                toFromStr,
-                getCurrencyCodeWithAccount(
-                  account,
-                  otherAsset.pluginId,
-                  otherAsset.tokenId
-                )
-              )
-            }
-            direction = txSrcSameAsset ? 'send' : 'receive'
-            break
-          }
-
-          case 'swapOrderPost': {
-            edgeCategory = {
-              category: 'expense',
-              subcategory: sprintf(lstrings.transaction_details_swap_order_post)
-            }
-            direction = 'send'
-            break
-          }
-          case 'swapOrderCancel': {
-            edgeCategory = {
-              category: 'expense',
-              subcategory: sprintf(
-                lstrings.transaction_details_swap_order_cancel
-              )
-            }
-            direction = 'send'
-            break
-          }
-          default:
-            unsupported = true
-        }
-        break
-      }
-      case 'stake': {
-        iconPluginId = action.pluginId
-        switch (assetActionType) {
-          case 'stake': {
-            let subcategory
-            if (action.stakeAssets.length === 1)
-              subcategory = sprintf(
-                lstrings.transaction_details_stake_subcat_1s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else if (action.stakeAssets.length === 2)
-              subcategory = sprintf(
-                lstrings.transaction_details_stake_subcat_2s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else {
-              console.warn(
-                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
-              )
-              break
-            }
-            edgeCategory = { category: 'transfer', subcategory }
-            direction = 'send'
-            break
-          }
-          case 'stakeOrder': {
-            if (action.stakeAssets.length === 1)
-              notes = sprintf(
-                lstrings.transaction_details_unstake_order_notes_1s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else if (action.stakeAssets.length === 2)
-              notes = sprintf(
-                lstrings.transaction_details_unstake_order_notes_2s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else {
-              console.error(
-                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
-              )
-              break
-            }
-
-            edgeCategory = {
-              category: 'expense',
-              subcategory: lstrings.transaction_details_stake_order_subcat
-            }
-            direction = 'send'
-            break
-          }
-          case 'claim': {
-            let subcategory
-            if (action.stakeAssets.length === 1)
-              subcategory = sprintf(
-                lstrings.transaction_details_unstake_subcat_1s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else if (action.stakeAssets.length === 2)
-              subcategory = sprintf(
-                lstrings.transaction_details_unstake_subcat_2s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else {
-              console.error(
-                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
-              )
-              break
-            }
-            edgeCategory = { category: 'transfer', subcategory }
-            if (
-              action.stakeAssets.every(
-                asset => asset.pluginId === currencyInfo.pluginId
-              )
-            ) {
-              direction = 'receive'
-            } else {
-              direction = 'send'
-            }
-            break
-          }
-          case 'unstake': {
-            let subcategory
-            if (action.stakeAssets.length === 1)
-              subcategory = sprintf(
-                lstrings.transaction_details_unstake_subcat_1s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else if (action.stakeAssets.length === 2)
-              subcategory = sprintf(
-                lstrings.transaction_details_unstake_subcat_2s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else {
-              console.error(
-                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
-              )
-              break
-            }
-            edgeCategory = { category: 'transfer', subcategory }
-            direction = 'receive'
-            break
-          }
-          case 'claimOrder':
-          case 'unstakeOrder': {
-            if (action.stakeAssets.length === 1)
-              notes = sprintf(
-                lstrings.transaction_details_unstake_order_notes_1s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else if (action.stakeAssets.length === 2)
-              notes = sprintf(
-                lstrings.transaction_details_unstake_order_notes_2s,
-                ...getCurrencyCodes(action.stakeAssets)
-              )
-            else {
-              console.error(
-                `Unsupported number of assets for '${assetActionType}' EdgeTxActionSwapType`
-              )
-              break
-            }
-
-            edgeCategory = {
-              category: 'expense',
-              subcategory: lstrings.transaction_details_unstake_order
-            }
-            direction = 'send'
-            break
-          }
-          case 'unstakeNetworkFee':
-          case 'stakeNetworkFee': {
-            edgeCategory = {
-              category: 'expense',
-              subcategory: lstrings.wc_smartcontract_network_fee
-            }
-            break
-          }
-
-          default:
-            unsupported = true
-        }
-        break
-      }
-      case 'fiat': {
-        iconPluginId = action.fiatPlugin.providerId
-        switch (assetActionType) {
-          case 'buy': {
-            payeeText = sprintf(payeeText, displayName)
-            const { fiatAsset } = action
-            const { fiatCurrencyCode } = cleanFiatCurrencyCode(
-              fiatAsset.fiatCurrencyCode
-            )
-            edgeCategory = {
-              category: 'exchange',
-              subcategory: sprintf(
-                lstrings.transaction_details_swap_from_subcat_1s,
-                fiatCurrencyCode
-              )
-            }
-            direction = 'receive'
-            break
-          }
-          case 'sell': {
-            payeeText = sprintf(payeeText, displayName)
-            const { fiatAsset } = action
-            const { fiatCurrencyCode } = cleanFiatCurrencyCode(
-              fiatAsset.fiatCurrencyCode
-            )
-            edgeCategory = {
-              category: 'exchange',
-              subcategory: sprintf(
-                lstrings.transaction_details_swap_to_subcat_1s,
-                fiatCurrencyCode
-              )
-            }
-            direction = 'send'
-            break
-          }
-          case 'sellNetworkFee': {
-            edgeCategory = {
-              category: 'expense',
-              subcategory: lstrings.wc_smartcontract_network_fee
-            }
-            direction = 'send'
-            break
-          }
-          default:
-            unsupported = true
-        }
-        break
-      }
-      case 'tokenApproval': {
-        switch (assetActionType) {
-          case 'tokenApproval': {
-            edgeCategory = {
-              category: 'expense',
-              subcategory: lstrings.wc_smartcontract_network_fee
-            }
-            break
-          }
-          default:
-            unsupported = true
-        }
-        break
-      }
-      case 'giftCard': {
-        iconPluginId = action.provider.providerId
-        payeeText = lstrings.gift_card_recipient_name
-        edgeCategory = {
-          category: 'expense',
-          subcategory: action.card.name
-        }
-        direction = 'send'
-        break
-      }
-      default:
-        unsupported = true
-    }
-
-    if (unsupported)
-      console.error(
-        `Unsupported EdgeTxAction assetAction:assetActionType '${assetActionType}'`
-      )
-  }
-  const savedData: EdgeMetadata = {
-    name: payeeText,
-    category: joinCategory(edgeCategory),
-    notes
-  }
-
-  const mergedData: EdgeMetadata = {
-    name:
-      metadata?.name != null && metadata.name.length > 0
-        ? metadata.name
-        : savedData.name,
-    category:
-      metadata?.category != null && metadata.category.length > 0
-        ? metadata.category
-        : savedData.category,
-    notes:
-      metadata?.notes != null && metadata.notes.length > 0
-        ? metadata.notes
-        : savedData.notes
-  }
-
-  return {
-    action,
-    assetAction,
-    direction,
-    iconPluginId,
-    savedData,
-    userData: metadata ?? {},
-    mergedData
-  }
-}
-
 export const pluginIdIcons: Record<string, string> = {
   '0xgasless': EDGE_CONTENT_SERVER_URI + '/0xgasless.png',
   bitrefill: EDGE_CONTENT_SERVER_URI + '/bitrefill.png',
diff --git a/src/actions/TransactionExportActions.tsx b/src/actions/TransactionExportActions.tsx
index 5ebace768a9..e0c3f87f4df 100644
--- a/src/actions/TransactionExportActions.tsx
+++ b/src/actions/TransactionExportActions.tsx
@@ -1,529 +1,32 @@
-import { abs, add, div, gt, lt, mul } from 'biggystring'
-import csvStringify from 'csv-stringify/lib/browser/sync'
 import type {
   EdgeCurrencyWallet,
   EdgeTokenId,
   EdgeTransaction
 } from 'edge-core-js'
-import shajs from 'sha.js'
 
-import { getExchangeDenom } from '../selectors/DenominationSelectors'
 import type { ThunkAction } from '../types/reduxTypes'
-import { getHistoricalCryptoRate } from '../util/exchangeRates'
-import { DECIMAL_PRECISION } from '../util/utils'
+import { fillTxsFiat } from '../util/fillTxsFiat'
 
-const UPDATE_TXS_MAX_PROMISES = 10
-
-export async function exportTransactionsToCSV(
-  wallet: EdgeCurrencyWallet,
-  defaultIsoFiat: string,
-  txs: EdgeTransaction[],
-  currencyCode: string,
-  denomination?: string
-): Promise<string> {
-  let denomName = ''
-  if (denomination != null) {
-    const denomObj = wallet.currencyInfo.denominations.find(
-      edgeDenom => edgeDenom.multiplier === denomination
-    )
-    if (denomObj != null) denomName = denomObj.name
-  }
-  return exportTransactionsToCSVInner(
-    txs,
-    currencyCode,
-    defaultIsoFiat,
-    denomination,
-    denomName
-  )
-}
+export {
+  exportTransactionsToBitwave,
+  exportTransactionsToCSV,
+  exportTransactionsToCSVInner,
+  exportTransactionsToQBO,
+  getTransferTx
+} from '../util/txExport'
 
 export function updateTxsFiat(
   wallet: EdgeCurrencyWallet,
   tokenId: EdgeTokenId,
-  currencyCode: string,
   txs: EdgeTransaction[]
 ): ThunkAction<Promise<void>> {
   return async (dispatch, getState) => {
-    const state = getState()
-    const defaultIsoFiat = state.ui.settings.defaultIsoFiat
-
-    const exchangeDenom = getExchangeDenom(wallet.currencyConfig, tokenId)
-
-    let promises: Array<Promise<void>> = []
-    for (const tx of txs) {
-      const amountFiat = tx.metadata?.exchangeAmount?.[defaultIsoFiat] ?? 0
-
-      if (amountFiat === 0) {
-        const date = new Date(tx.date * 1000).toISOString()
-        promises.push(
-          getHistoricalCryptoRate(
-            wallet.currencyInfo.pluginId,
-            tokenId,
-            defaultIsoFiat,
-            date
-          )
-            .then(rate => {
-              tx.metadata = {
-                ...tx.metadata,
-                exchangeAmount: {
-                  ...tx.metadata?.exchangeAmount,
-                  [defaultIsoFiat]:
-                    rate *
-                    Number(
-                      div(
-                        tx.nativeAmount,
-                        exchangeDenom.multiplier,
-                        DECIMAL_PRECISION
-                      )
-                    )
-                }
-              }
-            })
-            .catch((e: unknown) => {
-              console.warn(e instanceof Error ? e.message : String(e))
-            })
-        )
-        if (promises.length >= UPDATE_TXS_MAX_PROMISES) {
-          await Promise.all(promises)
-          promises = []
-        }
-      }
-    }
-    if (promises.length > 0) {
-      await Promise.all(promises)
-    }
-  }
-}
-
-function padZero(val: string): string {
-  if (val.length === 1) {
-    return '0' + val
-  }
-  return val
-}
-
-function escapeOFXString(str: string): string {
-  str = str.replace(/&/g, '&amp;')
-  str = str.replace(/>/g, '&gt;')
-  return str.replace(/</g, '&lt;')
-}
-
-function exportOfxHeader(inputObj: any): string {
-  let out = ''
-  for (const key of Object.keys(inputObj)) {
-    let element = inputObj[key]
-    if (typeof element === 'string') {
-      element = escapeOFXString(element)
-      out += `${key}:${element}\n`
-    } else {
-      throw new Error('Invalid OFX header')
-    }
-  }
-  return out
-}
-
-function exportOfxBody(inputObj: any): string {
-  let out = ''
-  for (const key of Object.keys(inputObj)) {
-    let element = inputObj[key]
-    if (typeof element === 'string') {
-      element = escapeOFXString(element)
-      out += `<${key}>${element}\n`
-    } else if (element instanceof Array) {
-      for (const a of element) {
-        out += `<${key}>\n`
-        out += exportOfxBody(a)
-        out += `</${key}>\n`
-      }
-    } else if (typeof element === 'object') {
-      out += `<${key}>\n`
-      out += exportOfxBody(element)
-      out += `</${key}>\n`
-    } else {
-      throw new Error('Invalid OFX body')
-    }
-  }
-  return out
-}
-
-function exportOfx(header: any, body: any): string {
-  let out = exportOfxHeader(header) + '\n'
-  out += '<OFX>\n'
-  out += exportOfxBody(body)
-  out += '</OFX>\n'
-  return out
-}
-
-function makeOfxDate(date: number): string {
-  const d = new Date(date * 1000)
-  const yyyy = d.getUTCFullYear().toString()
-  const mm = padZero((d.getUTCMonth() + 1).toString())
-  const dd = padZero(d.getUTCDate().toString())
-  const hh = padZero(d.getUTCHours().toString())
-  const min = padZero(d.getUTCMinutes().toString())
-  const ss = padZero(d.getUTCSeconds().toString())
-  return `${yyyy}${mm}${dd}${hh}${min}${ss}.000`
-}
-
-function makeCsvDateTime(date: number): { date: string; time: string } {
-  const d = new Date(date * 1000)
-  const yyyy = d.getUTCFullYear().toString()
-  const mm = padZero((d.getUTCMonth() + 1).toString())
-  const dd = padZero(d.getUTCDate().toString())
-  const hh = padZero(d.getUTCHours().toString())
-  const min = padZero(d.getUTCMinutes().toString())
-
-  return {
-    date: `${yyyy}-${mm}-${dd}`,
-    time: `${hh}:${min}`
-  }
-}
-
-/** ISO 8601 UTC, the timestamp format Bitwave requires for imports. */
-function makeBitwaveDateTime(date: number): string {
-  const d = new Date(date * 1000)
-  const yyyy = d.getUTCFullYear().toString()
-  const mm = padZero((d.getUTCMonth() + 1).toString())
-  const dd = padZero(d.getUTCDate().toString())
-  const hh = padZero(d.getUTCHours().toString())
-  const min = padZero(d.getUTCMinutes().toString())
-  const ss = padZero(d.getUTCSeconds().toString())
-
-  return `${yyyy}-${mm}-${dd}T${hh}:${min}:${ss}Z`
-}
-
-//
-// Check if tx is
-// 1. A transfer
-// 2. Outgoing spend
-// 3. Has a network fee
-// If so:
-//  1. Modify transaction to reduce the nativeAmount by the networkFee
-//  2. Set networkFee to 0
-//  3. Return a new transaction that has:
-//      1. nativeAmount and networkFee set to original tx fee
-//      2. category set to 'Expense:Network Fee'
-//      3. txid set to old txid + '-TRANSFER_TX'
-
-export function getTransferTx(
-  oldEdgeTransaction: EdgeTransaction,
-  fiatCurrencyCode: string
-): EdgeTransaction[] | null {
-  const edgeTransaction = { ...oldEdgeTransaction }
-  edgeTransaction.metadata = { ...oldEdgeTransaction.metadata }
-
-  const category = edgeTransaction.metadata?.category ?? ''
-  if (!category.toLowerCase().startsWith('transfer:')) return null
-  if (!lt(edgeTransaction.nativeAmount, '0')) return null
-  if (!gt(edgeTransaction.networkFee, '0')) return null
-
-  const nativeAmountNoFee = add(
-    edgeTransaction.nativeAmount,
-    edgeTransaction.networkFee
-  )
-  let newTxFiatFee = 0
-  let amountFiat =
-    edgeTransaction.metadata?.exchangeAmount?.[fiatCurrencyCode] ?? 0
-
-  if (amountFiat > 0) {
-    const exchangeRate: string = div(
-      amountFiat.toString(),
-      edgeTransaction.nativeAmount,
-      16
-    )
-    const newTxFiatFeeString: string = mul(
-      exchangeRate,
-      edgeTransaction.networkFee
-    )
-    newTxFiatFee = Math.abs(Number(newTxFiatFeeString))
-    amountFiat = Number(mul(exchangeRate, nativeAmountNoFee))
-  }
-
-  const newEdgeTransaction: EdgeTransaction = { ...edgeTransaction }
-  newEdgeTransaction.nativeAmount = `-${edgeTransaction.networkFee}`
-  newEdgeTransaction.metadata = {
-    ...edgeTransaction.metadata,
-    category: `Expense:Network Fee`,
-    exchangeAmount: {
-      ...edgeTransaction.metadata?.exchangeAmount,
-      [fiatCurrencyCode]: newTxFiatFee
-    }
-  }
-  newEdgeTransaction.txid += '-TRANSFER_TX'
-  edgeTransaction.nativeAmount = nativeAmountNoFee
-  edgeTransaction.networkFee = '0'
-  edgeTransaction.metadata = {
-    ...edgeTransaction.metadata,
-    exchangeAmount: {
-      ...edgeTransaction.metadata?.exchangeAmount,
-      [fiatCurrencyCode]: amountFiat
-    }
-  }
-  return [edgeTransaction, newEdgeTransaction]
-}
-
-export function exportTransactionsToQBO(
-  edgeTransactions: EdgeTransaction[],
-  fiatCurrencyCode: string,
-  denom: string | undefined,
-  /** For unit testing */
-  testDateNow?: number
-): string {
-  const STMTTRN: any[] = []
-  const now = makeOfxDate((testDateNow ?? Date.now()) / 1000)
-  const hasDenom = denom != null
-
-  for (const tx of edgeTransactions) {
-    const newTxs = getTransferTx(tx, fiatCurrencyCode)
-    if (newTxs != null) {
-      edgeTxToQbo(newTxs[0])
-      edgeTxToQbo(newTxs[1])
-    } else {
-      edgeTxToQbo(tx)
-    }
-  }
-
-  function edgeTxToQbo(edgeTx: EdgeTransaction): void {
-    const TRNAMT: string = hasDenom
-      ? div(edgeTx.nativeAmount, denom, DECIMAL_PRECISION)
-      : edgeTx.nativeAmount
-    const TRNTYPE = lt(edgeTx.nativeAmount, '0') ? 'DEBIT' : 'CREDIT'
-    const DTPOSTED = makeOfxDate(edgeTx.date)
-    const NAME: string = edgeTx.metadata?.name ?? ''
-    const amountFiat: number =
-      edgeTx.metadata?.exchangeAmount?.[fiatCurrencyCode] ?? 0
-    const category: string = edgeTx.metadata?.category ?? ''
-    const notes: string = edgeTx.metadata?.notes ?? ''
-
-    const absFiat = abs(amountFiat.toString())
-    const absAmount = abs(TRNAMT)
-    const CURRATE = absAmount !== '0' ? div(absFiat, absAmount, 8) : '0'
-    let memo = `// Rate=${CURRATE} ${fiatCurrencyCode}=${amountFiat} category="${category}" memo="${notes}"`
-    if (memo.length > 250) {
-      memo = memo.substring(0, 250) + '...'
-    }
-    const qboTxNamed = {
-      TRNTYPE,
-      DTPOSTED,
-      TRNAMT,
-      FITID: edgeTx.txid,
-      NAME,
-      MEMO: memo,
-      CURRENCY: {
-        CURRATE,
-        CURSYM: fiatCurrencyCode
-      }
-    }
-    const qboTx = {
-      TRNTYPE,
-      DTPOSTED,
-      TRNAMT,
-      FITID: edgeTx.txid,
-      MEMO: memo,
-      CURRENCY: {
-        CURRATE,
-        CURSYM: fiatCurrencyCode
-      }
-    }
-    const use = NAME === '' ? qboTx : qboTxNamed
-    STMTTRN.push(use)
-  }
-
-  const header = {
-    OFXHEADER: '100',
-    DATA: 'OFXSGML',
-    VERSION: '102',
-    SECURITY: 'NONE',
-    ENCODING: 'USASCII',
-    CHARSET: '1252',
-    COMPRESSION: 'NONE',
-    OLDFILEUID: 'NONE',
-    NEWFILEUID: 'NONE'
-  }
-
-  const body = {
-    SIGNONMSGSRSV1: {
-      SONRS: {
-        STATUS: {
-          CODE: '0',
-          SEVERITY: 'INFO'
-        },
-        DTSERVER: now,
-        LANGUAGE: 'ENG',
-        'INTU.BID': '3000'
-      }
-    },
-    BANKMSGSRSV1: {
-      STMTTRNRS: {
-        TRNUID: now,
-        STATUS: {
-          CODE: '0',
-          SEVERITY: 'INFO',
-          MESSAGE: 'OK'
-        },
-        STMTRS: {
-          CURDEF: 'USD',
-          BANKACCTFROM: {
-            BANKID: '999999999',
-            ACCTID: '999999999999',
-            ACCTTYPE: 'CHECKING'
-          },
-          BANKTRANLIST: {
-            DTSTART: now,
-            DTEND: now,
-            STMTTRN
-          },
-          LEDGERBAL: {
-            BALAMT: '0.00',
-            DTASOF: now
-          },
-          AVAILBAL: {
-            BALAMT: '0.00',
-            DTASOF: now
-          }
-        }
-      }
-    }
-  }
-
-  return exportOfx(header, body)
-}
-
-export function exportTransactionsToCSVInner(
-  edgeTransactions: EdgeTransaction[],
-  currencyCode: string,
-  fiatCurrencyCode: string,
-  denom?: string,
-  denomName: string = ''
-): string {
-  const items: any[] = []
-  const hasDenom = denom != null
-
-  for (const tx of edgeTransactions) {
-    const newTxs = getTransferTx(tx, fiatCurrencyCode)
-    if (newTxs != null) {
-      edgeTxToCsv(newTxs[0])
-      edgeTxToCsv(newTxs[1])
-    } else {
-      edgeTxToCsv(tx)
-    }
-  }
-
-  function edgeTxToCsv(edgeTx: EdgeTransaction): void {
-    const amount: string = hasDenom
-      ? div(edgeTx.nativeAmount, denom, DECIMAL_PRECISION)
-      : edgeTx.nativeAmount
-    const networkFeeField: string = hasDenom
-      ? div(edgeTx.networkFee, denom, DECIMAL_PRECISION)
-      : edgeTx.networkFee
-    const { date, time } = makeCsvDateTime(edgeTx.date)
-    const name: string = edgeTx.metadata?.name ?? ''
-    const amountFiat: number =
-      edgeTx.metadata?.exchangeAmount?.[fiatCurrencyCode] ?? 0
-    const category: string = edgeTx.metadata?.category ?? ''
-    const notes: string = edgeTx.metadata?.notes ?? ''
-
-    items.push({
-      CURRENCY_CODE: currencyCode,
-      DATE: date,
-      TIME: time,
-      PAYEE_PAYER_NAME: name,
-      AMT_ASSET: amount,
-      DENOMINATION: denomName,
-      [fiatCurrencyCode]: String(amountFiat),
-      CATEGORY: category,
-      NOTES: notes,
-      AMT_NETWORK_FEES_ASSET: networkFeeField,
-      TXID: edgeTx.txid,
-      OUR_RECEIVE_ADDRESSES: edgeTx.ourReceiveAddresses.join(','),
-      VER: 1,
-      DEVICE_DESCRIPTION: edgeTx.deviceDescription ?? ''
+    const defaultIsoFiat = getState().ui.settings.defaultIsoFiat
+    await fillTxsFiat({
+      wallet,
+      tokenId,
+      isoFiat: defaultIsoFiat,
+      txs
     })
   }
-
-  return csvStringify(items, {
-    header: true,
-    quoted_string: true,
-    record_delimiter: '\n'
-  })
-}
-
-export async function exportTransactionsToBitwave(
-  accountId: string,
-  edgeTransactions: EdgeTransaction[],
-  currencyCode: string,
-  multiplier: string
-): Promise<string> {
-  const items: any[] = []
-
-  for (const tx of edgeTransactions) {
-    edgeTxToCsv(tx)
-  }
-
-  function edgeTxToCsv(edgeTx: EdgeTransaction): void {
-    const {
-      date,
-      isSend,
-      metadata,
-      nativeAmount,
-      networkFee,
-      ourReceiveAddresses,
-      spendTargets,
-      txid
-    } = edgeTx
-    const amount: string = abs(div(nativeAmount, multiplier, DECIMAL_PRECISION))
-    const time = makeBitwaveDateTime(date)
-    const { name = '', category = '', notes = '' } = metadata ?? {}
-
-    let toAddress = ''
-    if (isSend) {
-      if (spendTargets != null && spendTargets.length > 0) {
-        // We can only choose 1 `toAddress` so pick the first spendTarget
-        toAddress = spendTargets[0].publicAddress
-      }
-    } else {
-      // We can only choose 1 `toAddress` so pick the first receive address
-      toAddress = ourReceiveAddresses != null ? ourReceiveAddresses[0] : ''
-    }
-
-    const id = shajs('sha256')
-      .update(`${txid}_${nativeAmount}_${networkFee}_${toAddress}`)
-      .digest('hex')
-      .slice(0, 16)
-
-    items.push({
-      id,
-      remoteContactId: '',
-      amount,
-      amountTicker: currencyCode,
-      cost: '',
-      costTicker: '',
-      // Bitwave calculates transaction fees on its own side. Exporting them
-      // here duplicates the fees after import, so both columns stay blank:
-      fee: '',
-      feeTicker: '',
-      time,
-      blockchainId: txid,
-      memo: notes,
-      transactionType: isSend ? 'withdrawal' : 'deposit',
-      accountId,
-      contactId: '',
-      categoryId: '',
-      taxExempt: 'FALSE',
-      tradeId: '',
-      description: name,
-      fromAddress: '',
-      toAddress,
-      groupId: '',
-      'metadata:myCustomMetadata1': category,
-      // Bitwave expects this to mirror the description column:
-      'metadata:myCustomMetadata2': name
-    })
-  }
-
-  return csvStringify(items, {
-    header: true,
-    quoted_string: true,
-    record_delimiter: '\n'
-  })
 }
diff --git a/src/components/scenes/TransactionsExportScene.tsx b/src/components/scenes/TransactionsExportScene.tsx
index 3ea018673e3..fc0d2a70381 100644
--- a/src/components/scenes/TransactionsExportScene.tsx
+++ b/src/components/scenes/TransactionsExportScene.tsx
@@ -1,4 +1,3 @@
-import { asBoolean, asObject, asString } from 'cleaners'
 import type {
   EdgeAccount,
   EdgeCurrencyWallet,
@@ -11,7 +10,6 @@ import RNFS from 'react-native-fs'
 import Share from 'react-native-share'
 import EntypoIcon from 'react-native-vector-icons/Entypo'
 
-import { getTxActionDisplayInfo } from '../../actions/CategoriesActions'
 import {
   exportTransactionsToBitwave,
   exportTransactionsToCSV,
@@ -28,6 +26,14 @@ import { connect } from '../../types/reactRedux'
 import type { EdgeAppSceneProps } from '../../types/routerTypes'
 import { getCurrencyCode } from '../../util/CurrencyInfoHelpers'
 import { getWalletName } from '../../util/CurrencyWalletHelpers'
+import {
+  EXPORT_TX_INFO_FILE,
+  type ExportTxInfo,
+  exportTxInfoKey,
+  mergeExportTxInfo,
+  readExportTxInfoMap
+} from '../../util/exportTxInfo'
+import { getTxActionDisplayInfo } from '../../util/txDisplay'
 import { SceneWrapper } from '../common/SceneWrapper'
 import { DateModal } from '../modals/DateModal'
 import { TextInputModal } from '../modals/TextInputModal'
@@ -64,7 +70,6 @@ interface DispatchProps {
   updateTxsFiatDispatch: (
     wallet: EdgeCurrencyWallet,
     tokenId: EdgeTokenId,
-    currencyCode: string,
     txs: EdgeTransaction[]
   ) => Promise<void>
 }
@@ -79,20 +84,6 @@ interface State {
   isExportBitwave: boolean
 }
 
-const EXPORT_TX_INFO_FILE = 'exportTxInfo.json'
-
-const asExportTxInfo = asObject({
-  bitwaveAccountId: asString,
-  isExportQbo: asBoolean,
-  isExportCsv: asBoolean,
-  isExportBitwave: asBoolean
-})
-
-const asExportTxInfoMap = asObject(asExportTxInfo)
-
-type ExportTxInfoMap = ReturnType<typeof asExportTxInfoMap>
-type ExportTxInfo = ReturnType<typeof asExportTxInfo>
-
 class TransactionsExportSceneComponent extends React.PureComponent<
   Props,
   State
@@ -165,13 +156,12 @@ class TransactionsExportSceneComponent extends React.PureComponent<
 
   loadInfoFile = async (): Promise<void> => {
     const { sourceWallet, tokenId } = this.props.route.params
-    const { disklet } = sourceWallet
-    const result = await disklet.getText(EXPORT_TX_INFO_FILE)
-    const exportTxInfoMap = asExportTxInfoMap(JSON.parse(result))
-    const tokenCurrencyCode = tokenId ?? sourceWallet.currencyInfo.currencyCode
+    const exportTxInfoMap = await readExportTxInfoMap(sourceWallet)
+    const tokenCurrencyCode = exportTxInfoKey(sourceWallet, tokenId)
+    const info = exportTxInfoMap[tokenCurrencyCode]
+    if (info == null) return
 
-    const { isExportBitwave, isExportCsv, isExportQbo } =
-      exportTxInfoMap[tokenCurrencyCode]
+    const { isExportBitwave, isExportCsv, isExportQbo } = info
 
     this.setState({
       isExportBitwave,
@@ -307,13 +297,11 @@ class TransactionsExportSceneComponent extends React.PureComponent<
     const { sourceWallet, tokenId } = route.params
     const { isExportBitwave, isExportQbo, isExportCsv, startDate, endDate } =
       this.state
-    const tokenCurrencyCode = tokenId ?? sourceWallet.currencyInfo.currencyCode
+    const tokenCurrencyCode = exportTxInfoKey(sourceWallet, tokenId)
 
     let exportTxInfo: ExportTxInfo | undefined
-    let exportTxInfoMap: ExportTxInfoMap | undefined
     try {
-      const result = await sourceWallet.disklet.getText(EXPORT_TX_INFO_FILE)
-      exportTxInfoMap = asExportTxInfoMap(JSON.parse(result))
+      const exportTxInfoMap = await readExportTxInfoMap(sourceWallet)
       exportTxInfo = exportTxInfoMap[tokenCurrencyCode]
     } catch (e) {
       console.log(
@@ -357,17 +345,12 @@ class TransactionsExportSceneComponent extends React.PureComponent<
       exportTxInfo?.isExportCsv !== isExportCsv ||
       exportTxInfo?.isExportQbo !== isExportQbo
     ) {
-      exportTxInfoMap ??= {}
-      exportTxInfoMap[tokenCurrencyCode] = {
+      await mergeExportTxInfo(sourceWallet, tokenId, {
         bitwaveAccountId: accountId,
         isExportBitwave,
         isExportQbo,
         isExportCsv
-      }
-      await sourceWallet.disklet.setText(
-        EXPORT_TX_INFO_FILE,
-        JSON.stringify(exportTxInfoMap)
-      )
+      })
     }
 
     if (startDate.getTime() > endDate.getTime()) {
@@ -413,12 +396,7 @@ class TransactionsExportSceneComponent extends React.PureComponent<
     const formats: string[] = []
 
     // Update the transactions that are missing fiat amounts
-    await this.props.updateTxsFiatDispatch(
-      sourceWallet,
-      tokenId,
-      currencyCode,
-      txs
-    )
+    await this.props.updateTxsFiatDispatch(sourceWallet, tokenId, txs)
 
     // The non-string result appears to be a bug in the core,
     // which we are relying on to determine if the date range is empty:
@@ -549,8 +527,8 @@ export const TransactionsExportScene = connect<
     ).multiplier
   }),
   dispatch => ({
-    updateTxsFiatDispatch: async (wallet, tokenId, currencyCode, txs) => {
-      await dispatch(updateTxsFiat(wallet, tokenId, currencyCode, txs))
+    updateTxsFiatDispatch: async (wallet, tokenId, txs) => {
+      await dispatch(updateTxsFiat(wallet, tokenId, txs))
     }
   })
 )(withTheme(TransactionsExportSceneComponent))
diff --git a/src/constants/txActionConstants.ts b/src/constants/txActionConstants.ts
deleted file mode 100644
index 13d811cb8ec..00000000000
--- a/src/constants/txActionConstants.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import type { EdgeAssetActionType } from 'edge-core-js'
-
-import { lstrings } from '../locales/strings'
-
-export const TX_ACTION_LABEL_MAP: Record<EdgeAssetActionType, string> = {
-  buy: lstrings.transaction_details_bought_1s,
-  claim: lstrings.transaction_details_claim,
-  claimOrder: lstrings.transaction_details_claim_order,
-  giftCard: lstrings.transaction_details_gift_card,
-  sell: lstrings.transaction_details_sold_1s,
-  sellNetworkFee: lstrings.fiat_plugin_sell_network_fee,
-  swap: lstrings.transaction_details_swap,
-  swapNetworkFee: lstrings.transaction_details_swap_network_fee,
-  swapOrderPost: lstrings.transaction_details_swap_order_post,
-  swapOrderFill: lstrings.transaction_details_swap_order_fill,
-  swapOrderCancel: lstrings.transaction_details_swap_order_cancel,
-  stake: lstrings.transaction_details_stake,
-  stakeNetworkFee: lstrings.transaction_details_stake_network_fee,
-  stakeOrder: lstrings.transaction_details_stake_order,
-  tokenApproval: lstrings.transaction_details_token_approval,
-  transfer: lstrings.transaction_details_transfer_funds,
-  transferNetworkFee: lstrings.transaction_details_transfer_network_fee,
-  unstake: lstrings.transaction_details_unstake,
-  unstakeNetworkFee: lstrings.transaction_details_unstake_network_fee,
-  unstakeOrder: lstrings.transaction_details_unstake_order
-}
diff --git a/src/util/exportTxInfo.ts b/src/util/exportTxInfo.ts
new file mode 100644
index 00000000000..d0c2be4a64c
--- /dev/null
+++ b/src/util/exportTxInfo.ts
@@ -0,0 +1,112 @@
+import {
+  asBoolean,
+  asJSON,
+  asMaybe,
+  asObject,
+  asString,
+  uncleaner
+} from 'cleaners'
+import type { EdgeCurrencyWallet, EdgeTokenId } from 'edge-core-js'
+
+import { isMissingFile } from './predicates'
+import { serializeByKey } from './serializeByKey'
+
+/** Per-wallet, per-asset export prefs on `wallet.disklet`. */
+export const EXPORT_TX_INFO_FILE = 'exportTxInfo.json'
+
+export const asExportTxInfo = asObject({
+  bitwaveAccountId: asString,
+  isExportQbo: asBoolean,
+  isExportCsv: asBoolean,
+  isExportBitwave: asBoolean
+})
+
+export const asExportTxInfoMap = asObject(asExportTxInfo)
+
+const uncleanExportTxInfoMap = uncleaner(asExportTxInfoMap)
+
+export type ExportTxInfo = ReturnType<typeof asExportTxInfo>
+export type ExportTxInfoMap = ReturnType<typeof asExportTxInfoMap>
+
+/**
+ * Map key is `tokenId ?? currencyCode` (native = currency code; token =
+ * contract tokenId). Matches the GUI export scene.
+ */
+export function exportTxInfoKey(
+  wallet: Pick<EdgeCurrencyWallet, 'currencyInfo'>,
+  tokenId: EdgeTokenId
+): string {
+  return tokenId ?? wallet.currencyInfo.currencyCode
+}
+
+/** Tolerant of a record this version cannot read; strict about the rest. */
+const asStoredExportTxInfoMap = asJSON(asObject(asMaybe(asExportTxInfo)))
+
+export async function readExportTxInfoMap(
+  wallet: Pick<EdgeCurrencyWallet, 'disklet'>
+): Promise<ExportTxInfoMap> {
+  const text = await wallet.disklet.getText(EXPORT_TX_INFO_FILE)
+  // `asJSON`, so one cleaner owns both the parse and the shape — and
+  // `asMaybe` per record, so one unreadable asset entry costs that entry
+  // rather than the Export button. A whole file that will not parse is also
+  // tolerated, because nothing can be recovered from it and the GUI scene
+  // recovered by writing a fresh map; a genuine read or decryption failure
+  // still throws, out of `getText`, and the caller decides.
+  const map = asMaybe(asStoredExportTxInfoMap)(text) ?? {}
+  const out: ExportTxInfoMap = {}
+  for (const [key, value] of Object.entries(map)) {
+    if (value != null) out[key] = value
+  }
+  return out
+}
+
+export async function writeExportTxInfoMap(
+  wallet: Pick<EdgeCurrencyWallet, 'disklet'>,
+  map: ExportTxInfoMap
+): Promise<void> {
+  // Through the cleaner's uncleaner: a shape change is then a compile
+  // error rather than a file `readExportTxInfoMap` later rejects.
+  await wallet.disklet.setText(
+    EXPORT_TX_INFO_FILE,
+    JSON.stringify(uncleanExportTxInfoMap(map))
+  )
+}
+
+/**
+ * Merge one asset key. Omitted patch fields keep the previous value, or
+ * `false` / `''` when creating the key.
+ */
+export async function mergeExportTxInfo(
+  wallet: EdgeCurrencyWallet,
+  tokenId: EdgeTokenId,
+  patch: Partial<ExportTxInfo>
+): Promise<ExportTxInfo> {
+  // Read-modify-write over the whole file, so two calls for different tokens
+  // on the same wallet must not interleave: the engine serves requests
+  // concurrently and the second write would discard the first.
+  return await serializeByKey(`exportTxInfo:${wallet.id}`, async () => {
+    let map: ExportTxInfoMap
+    try {
+      map = await readExportTxInfoMap(wallet)
+    } catch (error: unknown) {
+      // Only an absent file may be answered with an empty map. A bad shape
+      // never reaches here — `readExportTxInfoMap` drops the records it
+      // cannot read — so anything caught here is a real I/O or decryption
+      // failure, and answering *that* with a rewrite would turn one
+      // unreadable file into the loss of every asset's saved preferences.
+      if (!isMissingFile(error)) throw error
+      map = {}
+    }
+    const key = exportTxInfoKey(wallet, tokenId)
+    const prev = map[key]
+    const next: ExportTxInfo = {
+      bitwaveAccountId: patch.bitwaveAccountId ?? prev?.bitwaveAccountId ?? '',
+      isExportBitwave: patch.isExportBitwave ?? prev?.isExportBitwave ?? false,
+      isExportCsv: patch.isExportCsv ?? prev?.isExportCsv ?? false,
+      isExportQbo: patch.isExportQbo ?? prev?.isExportQbo ?? false
+    }
+    map[key] = next
+    await writeExportTxInfoMap(wallet, map)
+    return next
+  })
+}
diff --git a/src/util/fillTxsFiat.ts b/src/util/fillTxsFiat.ts
new file mode 100644
index 00000000000..69fdf2b4aa4
--- /dev/null
+++ b/src/util/fillTxsFiat.ts
@@ -0,0 +1,86 @@
+import { div } from 'biggystring'
+import type {
+  EdgeCurrencyWallet,
+  EdgeTokenId,
+  EdgeTransaction
+} from 'edge-core-js'
+
+import { getExchangeDenom } from './exchangeDenom'
+import { getHistoricalCryptoRate } from './exchangeRates'
+import { DECIMAL_PRECISION } from './utils'
+
+/**
+ * Accept a 3-letter ISO 4217 code (`USD`, `eur`) or `iso:USD`.
+ * Returns `iso:USD` or undefined when the input is not a fiat code.
+ */
+export function toIsoFiatCode(raw: string): string | undefined {
+  let code = raw.trim().toUpperCase()
+  if (code.startsWith('ISO:')) code = code.slice(4)
+  if (!/^[A-Z]{3}$/.test(code)) return undefined
+  return `iso:${code}`
+}
+
+/**
+ * Fill missing `metadata.exchangeAmount[isoFiat]` from the rates server,
+ * using each transaction's date. Skips a transaction whose fiat amount is
+ * already non-zero, and persists nothing.
+ *
+ * This is the loop `updateTxsFiat` used to run inline;
+ * `TransactionExportActions` is now a short thunk that reads `defaultIsoFiat`
+ * out of Redux and calls this, so there is no parallel implementation to keep
+ * in step.
+ *
+ * Every rate is queued before anything is awaited. `getHistoricalCryptoRate`
+ * batches into one request of up to RATES_SERVER_MAX_QUERY_SIZE assets and
+ * debounces by FETCH_FREQUENCY per batch, so awaiting in fixed-size groups
+ * instead bought a fresh debounce every group: 1,200 unpriced transactions
+ * cost ~120s of pure waiting in groups of ten, past the CLI client's own
+ * socket timeout, against ~1.1s queued all at once.
+ */
+export async function fillTxsFiat(opts: {
+  wallet: EdgeCurrencyWallet
+  tokenId: EdgeTokenId
+  isoFiat: string
+  txs: EdgeTransaction[]
+}): Promise<void> {
+  const { wallet, tokenId, isoFiat, txs } = opts
+  const exchangeDenom = getExchangeDenom(wallet.currencyConfig, tokenId)
+
+  const promises: Array<Promise<void>> = []
+  for (const tx of txs) {
+    const amountFiat = tx.metadata?.exchangeAmount?.[isoFiat] ?? 0
+
+    if (amountFiat === 0) {
+      const date = new Date(tx.date * 1000).toISOString()
+      promises.push(
+        getHistoricalCryptoRate(
+          wallet.currencyInfo.pluginId,
+          tokenId,
+          isoFiat,
+          date
+        )
+          .then(rate => {
+            tx.metadata = {
+              ...tx.metadata,
+              exchangeAmount: {
+                ...tx.metadata?.exchangeAmount,
+                [isoFiat]:
+                  rate *
+                  Number(
+                    div(
+                      tx.nativeAmount,
+                      exchangeDenom.multiplier,
+                      DECIMAL_PRECISION
+                    )
+                  )
+              }
+            }
+          })
+          .catch((error: unknown) => {
+            console.warn(error instanceof Error ? error.message : String(error))
+          })
+      )
+    }
+  }
+  await Promise.all(promises)
+}
diff --git a/src/util/serializeByKey.ts b/src/util/serializeByKey.ts
new file mode 100644
index 00000000000..276b1d8d667
--- /dev/null
+++ b/src/util/serializeByKey.ts
@@ -0,0 +1,38 @@
+/**
+ * Run async operations one at a time per key.
+ *
+ * The engine serves requests concurrently, so a read-modify-write over a
+ * whole shared file — a wallet's `exportTxInfo.json`, an account's
+ * `Settings.json` — can interleave with another and the second write
+ * silently discards the first. Disklet has no compare-and-swap, so the
+ * serialization has to live here.
+ *
+ * A failed operation does not poison the queue behind it, and a key is
+ * dropped once nothing is waiting on it, so the map stays bounded.
+ */
+const chains = new Map<string, Promise<void>>()
+
+export async function serializeByKey<T>(
+  key: string,
+  operation: () => Promise<T>
+): Promise<T> {
+  const previous = chains.get(key) ?? Promise.resolve()
+  const run = previous.then(operation)
+  const tail = run.then(
+    () => {},
+    () => {}
+  )
+  chains.set(key, tail)
+  try {
+    return await run
+  } finally {
+    // Only the last operation in the chain clears the key; an earlier one
+    // finishing must not drop a queue that is still being appended to.
+    if (chains.get(key) === tail) chains.delete(key)
+  }
+}
+
+/** How many keys currently have work queued. Tests read this. */
+export function pendingKeyCount(): number {
+  return chains.size
+}
diff --git a/src/util/txExport/format.ts b/src/util/txExport/format.ts
new file mode 100644
index 00000000000..d87f7e7f014
--- /dev/null
+++ b/src/util/txExport/format.ts
@@ -0,0 +1,490 @@
+import { abs, add, div, gt, lt, mul } from 'biggystring'
+import csvStringify from 'csv-stringify/lib/browser/sync'
+import type { EdgeCurrencyWallet, EdgeTransaction } from 'edge-core-js'
+import shajs from 'sha.js'
+
+import { DECIMAL_PRECISION } from '../utils'
+
+export async function exportTransactionsToCSV(
+  wallet: EdgeCurrencyWallet,
+  defaultIsoFiat: string,
+  txs: EdgeTransaction[],
+  currencyCode: string,
+  denomination?: string
+): Promise<string> {
+  let denomName = ''
+  if (denomination != null) {
+    const denomObj = wallet.currencyInfo.denominations.find(
+      edgeDenom => edgeDenom.multiplier === denomination
+    )
+    if (denomObj != null) denomName = denomObj.name
+  }
+  return exportTransactionsToCSVInner(
+    txs,
+    currencyCode,
+    defaultIsoFiat,
+    denomination,
+    denomName
+  )
+}
+
+function padZero(val: string): string {
+  if (val.length === 1) {
+    return '0' + val
+  }
+  return val
+}
+
+/**
+ * Escape a string for OFX 1.x, and keep it inside the declared charset.
+ *
+ * The header declares `ENCODING:USASCII` / `CHARSET:1252`, which is what
+ * every accounting importer this file has ever been fed expects. A payee or
+ * memo can hold anything — a dapp sets it through `edgeProvider`, the CLI's
+ * `--metadata` accepts any string, and the engine's own localized prose is
+ * not ASCII in most languages — so the non-ASCII characters are turned into
+ * SGML numeric character references rather than emitted raw. The declaration
+ * is then true, and an importer that reads the references shows the original
+ * character.
+ */
+function escapeOFXString(str: string): string {
+  str = str.replace(/&/g, '&amp;')
+  str = str.replace(/>/g, '&gt;')
+  str = str.replace(/</g, '&lt;')
+  return str.replace(
+    /[^\x20-\x7e\t\r\n]/g,
+    char => `&#${char.codePointAt(0) ?? 0};`
+  )
+}
+
+function exportOfxHeader(inputObj: any): string {
+  let out = ''
+  for (const key of Object.keys(inputObj)) {
+    let element = inputObj[key]
+    if (typeof element === 'string') {
+      element = escapeOFXString(element)
+      out += `${key}:${element}\n`
+    } else {
+      throw new Error('Invalid OFX header')
+    }
+  }
+  return out
+}
+
+function exportOfxBody(inputObj: any): string {
+  let out = ''
+  for (const key of Object.keys(inputObj)) {
+    let element = inputObj[key]
+    if (typeof element === 'string') {
+      element = escapeOFXString(element)
+      out += `<${key}>${element}\n`
+    } else if (element instanceof Array) {
+      for (const a of element) {
+        out += `<${key}>\n`
+        out += exportOfxBody(a)
+        out += `</${key}>\n`
+      }
+    } else if (typeof element === 'object') {
+      out += `<${key}>\n`
+      out += exportOfxBody(element)
+      out += `</${key}>\n`
+    } else {
+      throw new Error('Invalid OFX body')
+    }
+  }
+  return out
+}
+
+function exportOfx(header: any, body: any): string {
+  let out = exportOfxHeader(header) + '\n'
+  out += '<OFX>\n'
+  out += exportOfxBody(body)
+  out += '</OFX>\n'
+  return out
+}
+
+function makeOfxDate(date: number): string {
+  const d = new Date(date * 1000)
+  const yyyy = d.getUTCFullYear().toString()
+  const mm = padZero((d.getUTCMonth() + 1).toString())
+  const dd = padZero(d.getUTCDate().toString())
+  const hh = padZero(d.getUTCHours().toString())
+  const min = padZero(d.getUTCMinutes().toString())
+  const ss = padZero(d.getUTCSeconds().toString())
+  return `${yyyy}${mm}${dd}${hh}${min}${ss}.000`
+}
+
+function makeCsvDateTime(date: number): { date: string; time: string } {
+  const d = new Date(date * 1000)
+  const yyyy = d.getUTCFullYear().toString()
+  const mm = padZero((d.getUTCMonth() + 1).toString())
+  const dd = padZero(d.getUTCDate().toString())
+  const hh = padZero(d.getUTCHours().toString())
+  const min = padZero(d.getUTCMinutes().toString())
+
+  return {
+    date: `${yyyy}-${mm}-${dd}`,
+    time: `${hh}:${min}`
+  }
+}
+
+/** ISO 8601 UTC, the timestamp format Bitwave requires for imports. */
+function makeBitwaveDateTime(date: number): string {
+  const d = new Date(date * 1000)
+  const yyyy = d.getUTCFullYear().toString()
+  const mm = padZero((d.getUTCMonth() + 1).toString())
+  const dd = padZero(d.getUTCDate().toString())
+  const hh = padZero(d.getUTCHours().toString())
+  const min = padZero(d.getUTCMinutes().toString())
+  const ss = padZero(d.getUTCSeconds().toString())
+
+  return `${yyyy}-${mm}-${dd}T${hh}:${min}:${ss}Z`
+}
+
+//
+// Check if tx is
+// 1. A transfer
+// 2. Outgoing spend
+// 3. Has a network fee
+// If so:
+//  1. Modify transaction to reduce the nativeAmount by the networkFee
+//  2. Set networkFee to 0
+//  3. Return a new transaction that has:
+//      1. nativeAmount and networkFee set to original tx fee
+//      2. category set to 'Expense:Network Fee'
+//      3. txid set to old txid + '-TRANSFER_TX'
+
+export function getTransferTx(
+  oldEdgeTransaction: EdgeTransaction,
+  fiatCurrencyCode: string
+): EdgeTransaction[] | null {
+  const edgeTransaction = { ...oldEdgeTransaction }
+  edgeTransaction.metadata = { ...oldEdgeTransaction.metadata }
+
+  const category = edgeTransaction.metadata?.category ?? ''
+  if (!category.toLowerCase().startsWith('transfer:')) return null
+  if (!lt(edgeTransaction.nativeAmount, '0')) return null
+  if (!gt(edgeTransaction.networkFee, '0')) return null
+
+  const nativeAmountNoFee = add(
+    edgeTransaction.nativeAmount,
+    edgeTransaction.networkFee
+  )
+  let newTxFiatFee = 0
+  let amountFiat =
+    edgeTransaction.metadata?.exchangeAmount?.[fiatCurrencyCode] ?? 0
+
+  if (amountFiat > 0) {
+    const exchangeRate: string = div(
+      amountFiat.toString(),
+      edgeTransaction.nativeAmount,
+      16
+    )
+    const newTxFiatFeeString: string = mul(
+      exchangeRate,
+      edgeTransaction.networkFee
+    )
+    newTxFiatFee = Math.abs(Number(newTxFiatFeeString))
+    amountFiat = Number(mul(exchangeRate, nativeAmountNoFee))
+  }
+
+  const newEdgeTransaction: EdgeTransaction = { ...edgeTransaction }
+  newEdgeTransaction.nativeAmount = `-${edgeTransaction.networkFee}`
+  newEdgeTransaction.metadata = {
+    ...edgeTransaction.metadata,
+    category: `Expense:Network Fee`,
+    exchangeAmount: {
+      ...edgeTransaction.metadata?.exchangeAmount,
+      [fiatCurrencyCode]: newTxFiatFee
+    }
+  }
+  newEdgeTransaction.txid += '-TRANSFER_TX'
+  edgeTransaction.nativeAmount = nativeAmountNoFee
+  edgeTransaction.networkFee = '0'
+  edgeTransaction.metadata = {
+    ...edgeTransaction.metadata,
+    exchangeAmount: {
+      ...edgeTransaction.metadata?.exchangeAmount,
+      [fiatCurrencyCode]: amountFiat
+    }
+  }
+  return [edgeTransaction, newEdgeTransaction]
+}
+
+export function exportTransactionsToQBO(
+  edgeTransactions: EdgeTransaction[],
+  fiatCurrencyCode: string,
+  denom: string | undefined,
+  /** For unit testing */
+  testDateNow?: number
+): string {
+  const STMTTRN: any[] = []
+  const now = makeOfxDate((testDateNow ?? Date.now()) / 1000)
+  const hasDenom = denom != null
+
+  for (const tx of edgeTransactions) {
+    const newTxs = getTransferTx(tx, fiatCurrencyCode)
+    if (newTxs != null) {
+      edgeTxToQbo(newTxs[0])
+      edgeTxToQbo(newTxs[1])
+    } else {
+      edgeTxToQbo(tx)
+    }
+  }
+
+  function edgeTxToQbo(edgeTx: EdgeTransaction): void {
+    const TRNAMT: string = hasDenom
+      ? div(edgeTx.nativeAmount, denom, DECIMAL_PRECISION)
+      : edgeTx.nativeAmount
+    const TRNTYPE = lt(edgeTx.nativeAmount, '0') ? 'DEBIT' : 'CREDIT'
+    const DTPOSTED = makeOfxDate(edgeTx.date)
+    const NAME: string = edgeTx.metadata?.name ?? ''
+    const amountFiat: number =
+      edgeTx.metadata?.exchangeAmount?.[fiatCurrencyCode] ?? 0
+    const category: string = edgeTx.metadata?.category ?? ''
+    const notes: string = edgeTx.metadata?.notes ?? ''
+
+    const absFiat = abs(amountFiat.toString())
+    const absAmount = abs(TRNAMT)
+    const CURRATE = absAmount !== '0' ? div(absFiat, absAmount, 8) : '0'
+    let memo = `// Rate=${CURRATE} ${fiatCurrencyCode}=${amountFiat} category="${category}" memo="${notes}"`
+    if (memo.length > 250) {
+      memo = memo.substring(0, 250) + '...'
+    }
+    const qboTxNamed = {
+      TRNTYPE,
+      DTPOSTED,
+      TRNAMT,
+      FITID: edgeTx.txid,
+      NAME,
+      MEMO: memo,
+      CURRENCY: {
+        CURRATE,
+        CURSYM: fiatCurrencyCode
+      }
+    }
+    const qboTx = {
+      TRNTYPE,
+      DTPOSTED,
+      TRNAMT,
+      FITID: edgeTx.txid,
+      MEMO: memo,
+      CURRENCY: {
+        CURRATE,
+        CURSYM: fiatCurrencyCode
+      }
+    }
+    const use = NAME === '' ? qboTx : qboTxNamed
+    STMTTRN.push(use)
+  }
+
+  // `USASCII`/`1252`, as the app has always written, and `escapeOFXString`
+  // now makes the declaration true instead of the header being changed to
+  // match the bytes.
+  //
+  // The defect was narrow: only a file carrying a non-ASCII payee or memo
+  // was ever mis-described, and the engine's localized prose made that
+  // reachable. Moving to `ENCODING:UNICODE` changed the format on 100% of
+  // exports, including the ASCII-only majority, inside a commit whose stated
+  // scope is a Node-safety extraction with no behaviour change — and OFX 1.x
+  // `UNICODE` is not unambiguously UTF-8 (readers have taken it as UCS-2),
+  // so an importer that honours the declaration could mis-decode the whole
+  // file where before it garbled only the non-ASCII characters.
+  const header = {
+    OFXHEADER: '100',
+    DATA: 'OFXSGML',
+    VERSION: '102',
+    SECURITY: 'NONE',
+    ENCODING: 'USASCII',
+    CHARSET: '1252',
+    COMPRESSION: 'NONE',
+    OLDFILEUID: 'NONE',
+    NEWFILEUID: 'NONE'
+  }
+
+  const body = {
+    SIGNONMSGSRSV1: {
+      SONRS: {
+        STATUS: {
+          CODE: '0',
+          SEVERITY: 'INFO'
+        },
+        DTSERVER: now,
+        LANGUAGE: 'ENG',
+        'INTU.BID': '3000'
+      }
+    },
+    BANKMSGSRSV1: {
+      STMTTRNRS: {
+        TRNUID: now,
+        STATUS: {
+          CODE: '0',
+          SEVERITY: 'INFO',
+          MESSAGE: 'OK'
+        },
+        STMTRS: {
+          CURDEF: 'USD',
+          BANKACCTFROM: {
+            BANKID: '999999999',
+            ACCTID: '999999999999',
+            ACCTTYPE: 'CHECKING'
+          },
+          BANKTRANLIST: {
+            DTSTART: now,
+            DTEND: now,
+            STMTTRN
+          },
+          LEDGERBAL: {
+            BALAMT: '0.00',
+            DTASOF: now
+          },
+          AVAILBAL: {
+            BALAMT: '0.00',
+            DTASOF: now
+          }
+        }
+      }
+    }
+  }
+
+  return exportOfx(header, body)
+}
+
+export function exportTransactionsToCSVInner(
+  edgeTransactions: EdgeTransaction[],
+  currencyCode: string,
+  fiatCurrencyCode: string,
+  denom?: string,
+  denomName: string = ''
+): string {
+  const items: any[] = []
+  const hasDenom = denom != null
+
+  for (const tx of edgeTransactions) {
+    const newTxs = getTransferTx(tx, fiatCurrencyCode)
+    if (newTxs != null) {
+      edgeTxToCsv(newTxs[0])
+      edgeTxToCsv(newTxs[1])
+    } else {
+      edgeTxToCsv(tx)
+    }
+  }
+
+  function edgeTxToCsv(edgeTx: EdgeTransaction): void {
+    const amount: string = hasDenom
+      ? div(edgeTx.nativeAmount, denom, DECIMAL_PRECISION)
+      : edgeTx.nativeAmount
+    const networkFeeField: string = hasDenom
+      ? div(edgeTx.networkFee, denom, DECIMAL_PRECISION)
+      : edgeTx.networkFee
+    const { date, time } = makeCsvDateTime(edgeTx.date)
+    const name: string = edgeTx.metadata?.name ?? ''
+    const amountFiat: number =
+      edgeTx.metadata?.exchangeAmount?.[fiatCurrencyCode] ?? 0
+    const category: string = edgeTx.metadata?.category ?? ''
+    const notes: string = edgeTx.metadata?.notes ?? ''
+
+    items.push({
+      CURRENCY_CODE: currencyCode,
+      DATE: date,
+      TIME: time,
+      PAYEE_PAYER_NAME: name,
+      AMT_ASSET: amount,
+      DENOMINATION: denomName,
+      [fiatCurrencyCode]: String(amountFiat),
+      CATEGORY: category,
+      NOTES: notes,
+      AMT_NETWORK_FEES_ASSET: networkFeeField,
+      TXID: edgeTx.txid,
+      OUR_RECEIVE_ADDRESSES: edgeTx.ourReceiveAddresses.join(','),
+      VER: 1,
+      DEVICE_DESCRIPTION: edgeTx.deviceDescription ?? ''
+    })
+  }
+
+  return csvStringify(items, {
+    header: true,
+    quoted_string: true,
+    record_delimiter: '\n'
+  })
+}
+
+export async function exportTransactionsToBitwave(
+  accountId: string,
+  edgeTransactions: EdgeTransaction[],
+  currencyCode: string,
+  multiplier: string
+): Promise<string> {
+  const items: any[] = []
+
+  for (const tx of edgeTransactions) {
+    edgeTxToCsv(tx)
+  }
+
+  function edgeTxToCsv(edgeTx: EdgeTransaction): void {
+    const {
+      date,
+      isSend,
+      metadata,
+      nativeAmount,
+      networkFee,
+      ourReceiveAddresses,
+      spendTargets,
+      txid
+    } = edgeTx
+    const amount: string = abs(div(nativeAmount, multiplier, DECIMAL_PRECISION))
+    const time = makeBitwaveDateTime(date)
+    const { name = '', category = '', notes = '' } = metadata ?? {}
+
+    let toAddress = ''
+    if (isSend) {
+      if (spendTargets != null && spendTargets.length > 0) {
+        // We can only choose 1 `toAddress` so pick the first spendTarget
+        toAddress = spendTargets[0].publicAddress
+      }
+    } else {
+      // We can only choose 1 `toAddress` so pick the first receive address
+      toAddress = ourReceiveAddresses != null ? ourReceiveAddresses[0] : ''
+    }
+
+    const id = shajs('sha256')
+      .update(`${txid}_${nativeAmount}_${networkFee}_${toAddress}`)
+      .digest('hex')
+      .slice(0, 16)
+
+    items.push({
+      id,
+      remoteContactId: '',
+      amount,
+      amountTicker: currencyCode,
+      cost: '',
+      costTicker: '',
+      // Bitwave calculates transaction fees on its own side. Exporting them
+      // here duplicates the fees after import, so both columns stay blank:
+      fee: '',
+      feeTicker: '',
+      time,
+      blockchainId: txid,
+      memo: notes,
+      transactionType: isSend ? 'withdrawal' : 'deposit',
+      accountId,
+      contactId: '',
+      categoryId: '',
+      taxExempt: 'FALSE',
+      tradeId: '',
+      description: name,
+      fromAddress: '',
+      toAddress,
+      groupId: '',
+      'metadata:myCustomMetadata1': category,
+      // Bitwave expects this to mirror the description column:
+      'metadata:myCustomMetadata2': name
+    })
+  }
+
+  return csvStringify(items, {
+    header: true,
+    quoted_string: true,
+    record_delimiter: '\n'
+  })
+}
diff --git a/src/util/txExport/index.ts b/src/util/txExport/index.ts
new file mode 100644
index 00000000000..7e27ee7c3fd
--- /dev/null
+++ b/src/util/txExport/index.ts
@@ -0,0 +1,41 @@
+import { asValue } from 'cleaners'
+
+export {
+  exportTransactionsToBitwave,
+  exportTransactionsToCSV,
+  exportTransactionsToCSVInner,
+  exportTransactionsToQBO,
+  getTransferTx
+} from './format'
+
+const TX_EXPORT_FORMATS = ['csv', 'qbo', 'bitwave'] as const
+export type TxExportFormat = (typeof TX_EXPORT_FORMATS)[number]
+
+/**
+ * One export format.
+ *
+ * A cleaner rather than `includes(part as TxExportFormat)`: the cast was
+ * what made that check load-bearing, so a new format added to
+ * `TX_EXPORT_FORMATS` and forgotten here would have been accepted silently.
+ */
+export const asTxExportFormat = asValue<TxExportFormat[]>(...TX_EXPORT_FORMATS)
+
+/**
+ * Parse a comma-separated exportFormat query/flag.
+ * Empty / omitted → `[]`. Unknown tokens throw.
+ */
+export function parseExportFormats(raw: string | undefined): TxExportFormat[] {
+  if (raw == null) return []
+  const parts = raw
+    .split(',')
+    .map(part => part.trim().toLowerCase())
+    .filter(part => part !== '')
+  const formats: TxExportFormat[] = []
+  for (const part of parts) {
+    // Reports the field and the legal values, where the hand-rolled check
+    // said only `Unknown exportFormat "x"`.
+    const format = asTxExportFormat(part)
+    if (!formats.includes(format)) formats.push(format)
+  }
+  return formats
+}

From a5219cc71f3da07d0ca4af4914313bd3c7145005 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:08 -0700
Subject: [PATCH 09/24] Extract Node-safe transaction tagging

`SendScene2` saved a sent transaction and then attached its metadata,
its category, its notes and any swap details in a sequence that had to
happen in a particular order and had grown inline in the scene. A second
caller that saved a transaction and got the order wrong would produce a
transaction that looks right until someone exports it.

`txTagging/apply` holds that sequence. `SendScene2` calls it and loses
two dozen lines. The scene was the only definition of what a correctly
tagged transaction is, and now it is not the only caller that can
produce one.

It re-applies only the fields the caller actually supplied. Under
`EdgeMetadataChange` an empty string is a value rather than "leave
unchanged", so passing all three through would let a caller who set one
field erase the other two that core derived. The trigger is any
non-empty name, notes or category, which is wider than the scene's old
`payeeName != null` check and preserves a category that would otherwise
be lost; callers pass the metadata they were given, never computed
display metadata.
---
 src/__tests__/util/txTagging.test.ts | 119 +++++++++++++++++++++++++++
 src/components/scenes/SendScene2.tsx |  28 ++-----
 src/util/txTagging/apply.ts          |  85 +++++++++++++++++++
 src/util/txTagging/index.ts          |   1 +
 4 files changed, 211 insertions(+), 22 deletions(-)
 create mode 100644 src/__tests__/util/txTagging.test.ts
 create mode 100644 src/util/txTagging/apply.ts
 create mode 100644 src/util/txTagging/index.ts

diff --git a/src/__tests__/util/txTagging.test.ts b/src/__tests__/util/txTagging.test.ts
new file mode 100644
index 00000000000..a7a93eace07
--- /dev/null
+++ b/src/__tests__/util/txTagging.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it, jest } from '@jest/globals'
+import type {
+  EdgeCurrencyWallet,
+  EdgeSaveTxMetadataOptions,
+  EdgeTransaction
+} from 'edge-core-js'
+
+import {
+  hasPersistableTxMetadata,
+  saveTxAndMetadata
+} from '../../util/txTagging'
+
+function makeWallet(opts?: { saveTxMetadataError?: Error }): {
+  wallet: EdgeCurrencyWallet
+  saveTx: jest.Mock<() => Promise<void>>
+  saveTxMetadata: jest.Mock<(opts: EdgeSaveTxMetadataOptions) => Promise<void>>
+} {
+  const saveTx = jest.fn<() => Promise<void>>(async () => {})
+  const saveTxMetadata = jest.fn<
+    (opts: EdgeSaveTxMetadataOptions) => Promise<void>
+  >(async () => {
+    if (opts?.saveTxMetadataError != null) throw opts.saveTxMetadataError
+  })
+  return {
+    wallet: { saveTx, saveTxMetadata } as unknown as EdgeCurrencyWallet,
+    saveTx,
+    saveTxMetadata
+  }
+}
+
+const tx = (metadata?: EdgeTransaction['metadata']): EdgeTransaction =>
+  ({ txid: 'abc', tokenId: null, metadata } as unknown as EdgeTransaction)
+
+describe('hasPersistableTxMetadata', () => {
+  it('is false for nothing worth re-applying', () => {
+    expect(hasPersistableTxMetadata(undefined)).toBe(false)
+    expect(hasPersistableTxMetadata({})).toBe(false)
+    expect(
+      hasPersistableTxMetadata({ name: '', notes: '', category: '' })
+    ).toBe(false)
+  })
+
+  it('is true for any one supplied field, including a category', () => {
+    expect(hasPersistableTxMetadata({ name: 'Alice' })).toBe(true)
+    expect(hasPersistableTxMetadata({ notes: 'rent' })).toBe(true)
+    expect(hasPersistableTxMetadata({ category: 'Expense:Food' })).toBe(true)
+  })
+})
+
+describe('saveTxAndMetadata', () => {
+  it('saves the transaction and nothing else when there is no metadata', async () => {
+    const { wallet, saveTx, saveTxMetadata } = makeWallet()
+    await saveTxAndMetadata(wallet, tx())
+    expect(saveTx).toHaveBeenCalledTimes(1)
+    expect(saveTxMetadata).not.toHaveBeenCalled()
+  })
+
+  it('re-applies only the fields the caller supplied', async () => {
+    const { wallet, saveTxMetadata } = makeWallet()
+    await saveTxAndMetadata(wallet, tx({ notes: 'rent' }))
+
+    // An empty string would *clear* the field core derived, so absent fields
+    // must be absent from the change object rather than ''.
+    expect(saveTxMetadata).toHaveBeenCalledWith({
+      txid: 'abc',
+      tokenId: null,
+      metadata: { notes: 'rent' }
+    })
+  })
+
+  it('does not clear a sibling field that was passed empty', async () => {
+    const { wallet, saveTxMetadata } = makeWallet()
+    await saveTxAndMetadata(wallet, tx({ notes: 'rent', name: '' }))
+
+    const [{ metadata }] = saveTxMetadata.mock.calls[0]
+    expect(metadata).toEqual({ notes: 'rent' })
+    expect('name' in metadata).toBe(false)
+  })
+
+  it('carries all three when all three are supplied', async () => {
+    const { wallet, saveTxMetadata } = makeWallet()
+    await saveTxAndMetadata(
+      wallet,
+      tx({ name: 'Alice', notes: 'rent', category: 'Expense:Rent' })
+    )
+    const [{ metadata }] = saveTxMetadata.mock.calls[0]
+    expect(metadata).toEqual({
+      name: 'Alice',
+      notes: 'rent',
+      category: 'Expense:Rent'
+    })
+  })
+
+  it('routes a metadata failure to onMetadataError instead of throwing', async () => {
+    const failure = new Error('sync failed')
+    const { wallet } = makeWallet({ saveTxMetadataError: failure })
+    const onMetadataError = jest.fn<(error: unknown) => void>()
+
+    await saveTxAndMetadata(wallet, tx({ name: 'Alice' }), { onMetadataError })
+    expect(onMetadataError).toHaveBeenCalledWith(failure)
+  })
+
+  it('throws a metadata failure when no handler is given', async () => {
+    const failure = new Error('sync failed')
+    const { wallet } = makeWallet({ saveTxMetadataError: failure })
+    await expect(saveTxAndMetadata(wallet, tx({ name: 'Alice' }))).rejects.toBe(
+      failure
+    )
+  })
+
+  it('never reports a failed broadcast as success', async () => {
+    const { wallet, saveTx, saveTxMetadata } = makeWallet()
+    saveTx.mockRejectedValue(new Error('disk full') as never)
+    await expect(
+      saveTxAndMetadata(wallet, tx({ name: 'Alice' }))
+    ).rejects.toThrow('disk full')
+    expect(saveTxMetadata).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/components/scenes/SendScene2.tsx b/src/components/scenes/SendScene2.tsx
index b94fb33b123..7003bea1a3a 100644
--- a/src/components/scenes/SendScene2.tsx
+++ b/src/components/scenes/SendScene2.tsx
@@ -68,6 +68,7 @@ import {
   getMemoLabel,
   getMemoTitle
 } from '../../util/memoUtils'
+import { saveTxAndMetadata } from '../../util/txTagging'
 import {
   convertTransactionFeeToDisplayFee,
   darkenHexColor,
@@ -1516,28 +1517,11 @@ const SendComponent: React.FC<Props> = props => {
   spendTargets: ${JSON.stringify(spendInfo.spendTargets)}
   ourReceiveAddresses: ${JSON.stringify(ourReceiveAddresses)}`)
 
-        await coreWallet.saveTx(broadcastedTx)
-
-        // edge-core-js's saveTx silently drops tx.metadata when the engine
-        // has already registered the txid in walletState before we get here
-        // (race against the engine's onTransactionsChanged callback, which
-        // calls setupNewTxMetadata with no metadata for the engine's view of
-        // the tx). Re-apply via saveTxMetadata so payeeName and fio notes
-        // survive a reload from disk.
-        if (payeeName != null) {
-          await coreWallet
-            .saveTxMetadata({
-              txid: broadcastedTx.txid,
-              tokenId: broadcastedTx.tokenId,
-              metadata: {
-                name: broadcastedTx.metadata.name,
-                notes: broadcastedTx.metadata.notes
-              }
-            })
-            .catch((error: unknown) => {
-              showError(error)
-            })
-        }
+        await saveTxAndMetadata(coreWallet, broadcastedTx, {
+          onMetadataError: (error: unknown) => {
+            showError(error)
+          }
+        })
 
         for (const target of spendInfo.spendTargets) {
           // Write FIO OBT per spendTarget
diff --git a/src/util/txTagging/apply.ts b/src/util/txTagging/apply.ts
new file mode 100644
index 00000000000..795f7e75e2a
--- /dev/null
+++ b/src/util/txTagging/apply.ts
@@ -0,0 +1,85 @@
+import type {
+  EdgeCurrencyWallet,
+  EdgeMetadata,
+  EdgeMetadataChange,
+  EdgeTransaction
+} from 'edge-core-js'
+
+/** A field the caller actually supplied, rather than an empty placeholder. */
+function nonEmpty(value: string | undefined): boolean {
+  return value != null && value !== ''
+}
+
+/**
+ * True when the caller supplied metadata worth re-applying — a payee name
+ * from BIP21 or a resolved address, notes, or an explicit category.
+ *
+ * A category counts. Callers must therefore pass the metadata they were given,
+ * not the display metadata computed for a transaction, whose `Expense:` /
+ * `Income:` category would make every send look like it carried one.
+ */
+export function hasPersistableTxMetadata(
+  metadata: EdgeMetadata | undefined
+): boolean {
+  if (metadata == null) return false
+  return (
+    nonEmpty(metadata.name) ||
+    nonEmpty(metadata.notes) ||
+    nonEmpty(metadata.category)
+  )
+}
+
+/**
+ * saveTx plus the saveTxMetadata re-apply used by SendScene2 and the CLI.
+ *
+ * Core derives its own metadata for a sent transaction, and a concurrent
+ * engine callback can land after ours and drop what the caller asked for. So
+ * the fields the caller actually supplied are written again afterwards.
+ *
+ * Only non-empty fields are sent. Under `EdgeMetadataChange` an empty string
+ * is a value, not "leave unchanged" — only `undefined` means that, and `null`
+ * deletes — so sending all three verbatim let a caller who supplied one field
+ * erase the other two.
+ *
+ * saveTx errors always throw. saveTxMetadata errors throw unless
+ * `onMetadataError` is provided (the GUI uses that so a tagging failure
+ * cannot look like a failed send after broadcast).
+ *
+ * This fires for a category or a note, not only for a payee name. The GUI
+ * used to re-apply `if (payeeName != null)`, and the race its own comment
+ * describes — core's `saveTx` dropping `tx.metadata` when the engine has
+ * already registered the txid — drops *every* field, not just the name. So a
+ * category arriving from a payment URI was silently losable before. The cost
+ * is one extra round trip on a send that carries a category but no payee,
+ * which buys back a field that could otherwise vanish on reload.
+ */
+export async function saveTxAndMetadata(
+  wallet: EdgeCurrencyWallet,
+  tx: EdgeTransaction,
+  opts?: {
+    onMetadataError?: (error: unknown) => void
+  }
+): Promise<void> {
+  await wallet.saveTx(tx)
+  const metadata = tx.metadata
+  if (!hasPersistableTxMetadata(metadata)) return
+
+  const change: EdgeMetadataChange = {}
+  if (nonEmpty(metadata?.name)) change.name = metadata?.name
+  if (nonEmpty(metadata?.notes)) change.notes = metadata?.notes
+  if (nonEmpty(metadata?.category)) change.category = metadata?.category
+
+  try {
+    await wallet.saveTxMetadata({
+      txid: tx.txid,
+      tokenId: tx.tokenId,
+      metadata: change
+    })
+  } catch (error: unknown) {
+    if (opts?.onMetadataError != null) {
+      opts.onMetadataError(error)
+      return
+    }
+    throw error
+  }
+}
diff --git a/src/util/txTagging/index.ts b/src/util/txTagging/index.ts
new file mode 100644
index 00000000000..8899a7e6a5e
--- /dev/null
+++ b/src/util/txTagging/index.ts
@@ -0,0 +1 @@
+export { hasPersistableTxMetadata, saveTxAndMetadata } from './apply'

From 05f24feb413ef342dcc984f686d312253c8647f8 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:09 -0700
Subject: [PATCH 10/24] Add the Edge CLI engine and its REST API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A long-lived engine daemon owns the `EdgeContext` and answers a JSON
REST API over a Unix socket; the `edge-cli` binary is a thin one-shot
client that spawns the engine on demand and keeps a session id in
`session.json` so commands chain. `docs/EDGE_CLI.md` describes that
architecture and deliberately documents no endpoints — the reference is
generated.

The point of this commit is the declaration format, so it carries
thirteen calls. Each is one `route({…})`: the core call it fronts, the
HTTP method and path, how it appears on the command line, cleaners for
the query, body and response, and its error codes. The prose lives
inside the declaration, beside the field it describes, and the JSDoc
above carries what belongs to the call as a whole.

Nothing is written twice. The command line, the help text, the OpenAPI
document and the HTML reference are all derived from these declarations,
and the derived artifacts are committed so a fresh clone needs no build
step. Five gates run in the pre-commit hook and reject the ways they
could drift apart: a route with no command, a handler reading a field
its cleaner would strip, a request parameter the core call does not
have, a generated file that is stale, and a command no test exercises.

The thirteen cover the shapes worth reviewing:

- no arguments, engine-local — `engine-status`, `engine-config`
- no arguments, reaching core — `local-users`, `fetch-login-messages`
- one named argument — `username-available`
- a body, and the session it establishes — `create-account`,
  `login-with-password`, `logout`
- a positional path parameter — `object-get`, `object-delete`
- a held-open stream — `subscribe`

Path parameters are base58 identifiers and nothing else, because base64
wallet ids and free-text usernames contain `/` and cannot survive a URL
unescaped. Everything else is a named argument. A positional is declared
once as an ordinary field and the path is derived from it, so the two
cannot disagree.

`--fake` serves an in-process `makeFakeEdgeWorld`, which is what lets
the CLI tests run in a hook with no network, no server and no API key.

Core values with methods on them cannot cross JSON, so the engine keeps
them and hands back a handle: a staged transaction, a pending login, a
swap quote, a lobby. A handle carries its own TTL and is released when
the caller finishes with it, and a call that consumes one — approving a
swap — marks it in flight first, so a client that retries after its own
socket timeout is refused with `OBJECT_IN_USE` rather than spending
twice. A call that keeps its handle holds it the same way, so a
broadcast that outlives the TTL still returns its txid instead of
expiring between the send and the reply. Reading a handle returns a
projection, never the live object: serializing an `EdgeAccount` would
walk its `otpKey` and `recoveryKey` getters, and a swap quote reaches
both wallets and every token they know.

Responses are validated against the same cleaners that document them.
`checkResponse` runs each one and discards the cleaned value, since a
cleaner strips unknown keys and returning it would delete fields the
engine means to send; `EDGE_CLI_CHECK_RESPONSES` decides whether a
mismatch warns, fails the request, or is skipped. Drift shows up in the
log rather than reaching a caller unnoticed.

One engine serves one profile, and it claims the profile by creating its
run file exclusively before opening the data directory, so two cold
invocations cannot hold two `EdgeContext`s on one set of repos or unlink
each other's socket. The idle timer counts in-flight requests as well as
sessions and subscribers, so a cold login cannot be shut down underneath
itself. Everything the engine reads from disk — its run file, the
client's session file, the account's synced settings — goes through a
cleaner, and the bearer tokens in an OTP challenge are masked on their
way to a terminal while staying in the REST body the commands read them
from.
---
 .gitattributes                                |     6 +
 .gitignore                                    |     9 +
 .travis.yml                                   |     7 +
 AGENTS.md                                     |    21 +-
 docs/EDGE_CLI.md                              |   499 +
 docs/api/README.md                            |   169 +
 docs/api/dist/index.html                      |  8499 +++++++++++++
 docs/api/dist/openapi.json                    | 10227 ++++++++++++++++
 docs/api/groups.ts                            |   217 +
 docs/api/shared.ts                            |   365 +
 native/edge-api-signer/node/binding.gyp       |    18 +
 .../node/edge_api_signer_napi.c               |   176 +
 package-lock.json                             |   336 +-
 package.json                                  |    41 +-
 rollup.config.cli.mjs                         |    87 +
 scripts/apiDocs.css                           |   147 +
 scripts/buildApiDocs.ts                       |   800 ++
 scripts/buildCliCommands.ts                   |   136 +
 scripts/buildCliHelp.ts                       |   134 +
 scripts/buildNodeApiSigner.sh                 |    26 +
 scripts/checkCliCoverage.ts                   |   113 +
 scripts/checkCoreAlignment.ts                 |   155 +
 scripts/checkRouteContracts.ts                |   181 +
 scripts/cliNodeSafeSmoke.js                   |   116 +
 scripts/cliUsage.ts                           |   120 +
 scripts/engineRequest.ts                      |    59 +
 scripts/extractRoutes.ts                      |   862 ++
 scripts/makeApiSigner.ts                      |   102 +-
 scripts/prepare.sh                            |     6 +
 scripts/testCliFake.ts                        |   998 ++
 scripts/testCliSubscribe.ts                   |   543 +
 scripts/util/cliHarness.ts                    |    64 +
 scripts/util/solveCaptcha.ts                  |     1 +
 scripts/verifyApiDocs.ts                      |   470 +
 scripts/writeIfChanged.ts                     |    40 +
 src/__tests__/cli/apiClient.test.ts           |   140 +
 src/__tests__/cli/configSubsets.test.ts       |    82 +
 src/__tests__/cli/discovery.test.ts           |   330 +
 src/__tests__/cli/engineCodecs.test.ts        |   138 +
 src/__tests__/cli/errors.test.ts              |   223 +
 src/__tests__/cli/events.test.ts              |   185 +
 src/__tests__/cli/exitCodes.test.ts           |    69 +
 src/__tests__/cli/fetchPluginKeys.test.ts     |    21 +
 src/__tests__/cli/idleShutdown.test.ts        |   176 +
 src/__tests__/cli/jsonBody.test.ts            |    67 +
 src/__tests__/cli/keysConfig.test.ts          |    17 +
 src/__tests__/cli/logger.test.ts              |   125 +
 src/__tests__/cli/objectHandles.test.ts       |   193 +
 src/__tests__/cli/parseArgs.test.ts           |   229 +
 src/__tests__/cli/persistedSchemas.test.ts    |   183 +
 src/__tests__/cli/redaction.test.ts           |   134 +
 src/__tests__/cli/routeHelpers.test.ts        |   135 +
 src/__tests__/cli/router.test.ts              |    71 +
 src/__tests__/cli/sessions.test.ts            |   354 +
 src/__tests__/cli/solveCaptcha.test.ts        |   129 +
 src/__tests__/util/exchangeDenom.test.ts      |    44 +
 src/cli/bootEngineLocale.ts                   |    22 +
 src/cli/bootNodeLocale.ts                     |    50 +
 src/cli/client/apiClient.ts                   |   493 +
 src/cli/client/exitCodes.ts                   |    71 +
 src/cli/client/output.ts                      |    93 +
 src/cli/client/sessionFile.ts                 |    71 +
 src/cli/client/solveCaptcha.ts                |   197 +
 src/cli/client/spawnEngine.ts                 |   304 +
 src/cli/clientResponses.ts                    |    58 +
 src/cli/command.ts                            |    92 +
 src/cli/commandArgs.ts                        |   129 +
 src/cli/commands/all.ts                       |     8 +
 src/cli/commands/generated.ts                 |   158 +
 src/cli/commands/help.ts                      |    46 +
 src/cli/commands/login.ts                     |   198 +
 src/cli/commands/paths.ts                     |    17 +
 src/cli/commands/subscribe.ts                 |   117 +
 src/cli/declare-modules.d.ts                  |     1 +
 src/cli/engine/apiVersion.ts                  |    14 +
 src/cli/engine/appConfig.ts                   |    50 +
 src/cli/engine/cliConfig.ts                   |    59 +
 src/cli/engine/cliHome.ts                     |    37 +
 src/cli/engine/discovery.ts                   |   467 +
 src/cli/engine/doc.ts                         |    37 +
 src/cli/engine/errorGroups.ts                 |    27 +
 src/cli/engine/errors.ts                      |   343 +
 src/cli/engine/events.ts                      |   256 +
 src/cli/engine/fetchPluginKeys.ts             |   110 +
 src/cli/engine/fieldDocs.ts                   |    38 +
 src/cli/engine/idleShutdown.ts                |   172 +
 src/cli/engine/index.ts                       |   700 ++
 src/cli/engine/internal.ts                    |    45 +
 src/cli/engine/json.ts                        |    72 +
 src/cli/engine/keysConfig.ts                  |    97 +
 src/cli/engine/logger.ts                      |   225 +
 src/cli/engine/makeCoreContext.ts             |   400 +
 src/cli/engine/nodeApiSigner.ts               |    97 +
 src/cli/engine/objectHandles.ts               |   381 +
 src/cli/engine/readJsonConfig.ts              |    58 +
 src/cli/engine/resolve.ts                     |    88 +
 src/cli/engine/route.ts                       |   282 +
 src/cli/engine/router.ts                      |   121 +
 src/cli/engine/routes/account.ts              |   401 +
 src/cli/engine/routes/context.ts              |   307 +
 src/cli/engine/routes/events.ts               |    88 +
 src/cli/engine/routes/helpers.ts              |    92 +
 src/cli/engine/routes/index.ts                |    19 +
 src/cli/engine/routes/login.ts                |   546 +
 src/cli/engine/routes/objects.ts              |   128 +
 src/cli/engine/routes/status.ts               |   176 +
 src/cli/engine/schemas.ts                     |   890 ++
 src/cli/engine/server.ts                      |   342 +
 src/cli/engine/sessions.ts                    |   513 +
 src/cli/engine/sweepTicker.ts                 |    31 +
 src/cli/engine/tcpPort.ts                     |    41 +
 src/cli/engine/testerServers.ts               |    33 +
 src/cli/engine/transportAuth.ts               |   138 +
 src/cli/flagTable.ts                          |   151 +
 src/cli/generated/commands.json               |  2123 ++++
 src/cli/generated/helpDocs.json               |  3427 ++++++
 src/cli/generatedSchemas.ts                   |   127 +
 src/cli/index.ts                              |   442 +
 src/cli/parseArgs.ts                          |   210 +
 src/util/CurrencyInfoHelpers.ts               |    30 +-
 120 files changed, 45270 insertions(+), 81 deletions(-)
 create mode 100644 .gitattributes
 create mode 100644 docs/EDGE_CLI.md
 create mode 100644 docs/api/README.md
 create mode 100644 docs/api/dist/index.html
 create mode 100644 docs/api/dist/openapi.json
 create mode 100644 docs/api/groups.ts
 create mode 100644 docs/api/shared.ts
 create mode 100644 native/edge-api-signer/node/binding.gyp
 create mode 100644 native/edge-api-signer/node/edge_api_signer_napi.c
 create mode 100644 rollup.config.cli.mjs
 create mode 100644 scripts/apiDocs.css
 create mode 100644 scripts/buildApiDocs.ts
 create mode 100644 scripts/buildCliCommands.ts
 create mode 100644 scripts/buildCliHelp.ts
 create mode 100755 scripts/buildNodeApiSigner.sh
 create mode 100644 scripts/checkCliCoverage.ts
 create mode 100644 scripts/checkCoreAlignment.ts
 create mode 100644 scripts/checkRouteContracts.ts
 create mode 100644 scripts/cliNodeSafeSmoke.js
 create mode 100644 scripts/cliUsage.ts
 create mode 100644 scripts/engineRequest.ts
 create mode 100644 scripts/extractRoutes.ts
 create mode 100644 scripts/testCliFake.ts
 create mode 100644 scripts/testCliSubscribe.ts
 create mode 100644 scripts/util/cliHarness.ts
 create mode 100644 scripts/util/solveCaptcha.ts
 create mode 100644 scripts/verifyApiDocs.ts
 create mode 100644 scripts/writeIfChanged.ts
 create mode 100644 src/__tests__/cli/apiClient.test.ts
 create mode 100644 src/__tests__/cli/configSubsets.test.ts
 create mode 100644 src/__tests__/cli/discovery.test.ts
 create mode 100644 src/__tests__/cli/engineCodecs.test.ts
 create mode 100644 src/__tests__/cli/errors.test.ts
 create mode 100644 src/__tests__/cli/events.test.ts
 create mode 100644 src/__tests__/cli/exitCodes.test.ts
 create mode 100644 src/__tests__/cli/fetchPluginKeys.test.ts
 create mode 100644 src/__tests__/cli/idleShutdown.test.ts
 create mode 100644 src/__tests__/cli/jsonBody.test.ts
 create mode 100644 src/__tests__/cli/keysConfig.test.ts
 create mode 100644 src/__tests__/cli/logger.test.ts
 create mode 100644 src/__tests__/cli/objectHandles.test.ts
 create mode 100644 src/__tests__/cli/parseArgs.test.ts
 create mode 100644 src/__tests__/cli/persistedSchemas.test.ts
 create mode 100644 src/__tests__/cli/redaction.test.ts
 create mode 100644 src/__tests__/cli/routeHelpers.test.ts
 create mode 100644 src/__tests__/cli/router.test.ts
 create mode 100644 src/__tests__/cli/sessions.test.ts
 create mode 100644 src/__tests__/cli/solveCaptcha.test.ts
 create mode 100644 src/__tests__/util/exchangeDenom.test.ts
 create mode 100644 src/cli/bootEngineLocale.ts
 create mode 100644 src/cli/bootNodeLocale.ts
 create mode 100644 src/cli/client/apiClient.ts
 create mode 100644 src/cli/client/exitCodes.ts
 create mode 100644 src/cli/client/output.ts
 create mode 100644 src/cli/client/sessionFile.ts
 create mode 100644 src/cli/client/solveCaptcha.ts
 create mode 100644 src/cli/client/spawnEngine.ts
 create mode 100644 src/cli/clientResponses.ts
 create mode 100644 src/cli/command.ts
 create mode 100644 src/cli/commandArgs.ts
 create mode 100644 src/cli/commands/all.ts
 create mode 100644 src/cli/commands/generated.ts
 create mode 100644 src/cli/commands/help.ts
 create mode 100644 src/cli/commands/login.ts
 create mode 100644 src/cli/commands/paths.ts
 create mode 100644 src/cli/commands/subscribe.ts
 create mode 100644 src/cli/declare-modules.d.ts
 create mode 100644 src/cli/engine/apiVersion.ts
 create mode 100644 src/cli/engine/appConfig.ts
 create mode 100644 src/cli/engine/cliConfig.ts
 create mode 100644 src/cli/engine/cliHome.ts
 create mode 100644 src/cli/engine/discovery.ts
 create mode 100644 src/cli/engine/doc.ts
 create mode 100644 src/cli/engine/errorGroups.ts
 create mode 100644 src/cli/engine/errors.ts
 create mode 100644 src/cli/engine/events.ts
 create mode 100644 src/cli/engine/fetchPluginKeys.ts
 create mode 100644 src/cli/engine/fieldDocs.ts
 create mode 100644 src/cli/engine/idleShutdown.ts
 create mode 100644 src/cli/engine/index.ts
 create mode 100644 src/cli/engine/internal.ts
 create mode 100644 src/cli/engine/json.ts
 create mode 100644 src/cli/engine/keysConfig.ts
 create mode 100644 src/cli/engine/logger.ts
 create mode 100644 src/cli/engine/makeCoreContext.ts
 create mode 100644 src/cli/engine/nodeApiSigner.ts
 create mode 100644 src/cli/engine/objectHandles.ts
 create mode 100644 src/cli/engine/readJsonConfig.ts
 create mode 100644 src/cli/engine/resolve.ts
 create mode 100644 src/cli/engine/route.ts
 create mode 100644 src/cli/engine/router.ts
 create mode 100644 src/cli/engine/routes/account.ts
 create mode 100644 src/cli/engine/routes/context.ts
 create mode 100644 src/cli/engine/routes/events.ts
 create mode 100644 src/cli/engine/routes/helpers.ts
 create mode 100644 src/cli/engine/routes/index.ts
 create mode 100644 src/cli/engine/routes/login.ts
 create mode 100644 src/cli/engine/routes/objects.ts
 create mode 100644 src/cli/engine/routes/status.ts
 create mode 100644 src/cli/engine/schemas.ts
 create mode 100644 src/cli/engine/server.ts
 create mode 100644 src/cli/engine/sessions.ts
 create mode 100644 src/cli/engine/sweepTicker.ts
 create mode 100644 src/cli/engine/tcpPort.ts
 create mode 100644 src/cli/engine/testerServers.ts
 create mode 100644 src/cli/engine/transportAuth.ts
 create mode 100644 src/cli/flagTable.ts
 create mode 100644 src/cli/generated/commands.json
 create mode 100644 src/cli/generated/helpDocs.json
 create mode 100644 src/cli/generatedSchemas.ts
 create mode 100644 src/cli/index.ts
 create mode 100644 src/cli/parseArgs.ts

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 00000000000..ec2b9b8298f
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,6 @@
+# The committed generated artifacts. They belong in the tree — a fresh clone
+# needs no build step to run the CLI or read its reference — but they are
+# output, so a review should not have to scroll them and the language
+# statistics should not count them.
+docs/api/dist/** linguist-generated=true
+src/cli/generated/** linguist-generated=true
diff --git a/.gitignore b/.gitignore
index da3f7fb27fa..ba6bee559e0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,9 @@ coverage/
 /ios/EdgeApiSecret.h
 /android/app/src/main/cpp/edge_api_secret.c
 /android/app/src/main/cpp/edge_api_secret.h
+/native/edge-api-signer/node/edge_api_secret.c
+/native/edge-api-signer/node/edge_api_secret.h
+/native/edge-api-signer/node/build/
 /vendor/*.tgz
 /vendor/edge-core-js-*.tgz
 /*.tgz
@@ -140,3 +143,9 @@ yarn-error.log
 !.yarn/sdks
 !.yarn/versions
 /.husky/_
+
+# Edge CLI runtime
+.edge-cli/
+
+# Built CLI
+/lib/
diff --git a/.travis.yml b/.travis.yml
index f8edca4305e..bdd0ffb8816 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -15,4 +15,11 @@ install:
 script:
   - npm run lint
   - npx tsc
+  # The five documentation gates, which are read-only and take seconds
+  # between them. `npm run prepare` above regenerates the committed
+  # artifacts, so without this nothing anywhere notices a stale
+  # `commands.json` — and that file is the table the CLI parses argv against.
+  - npm run docs:api:gates
+  - npm run test:cli:node-safe
   - npm test
+  - npm run test:cli:offline
diff --git a/AGENTS.md b/AGENTS.md
index 24184a3af69..2d808ef765a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,10 +14,27 @@
 - `npm test` - Run Jest tests (single run)
 - `npm run watch` - Run Jest tests in watch mode
 - `npm test -- --testNamePattern="test name"` - Run specific test by name
-- `npm run verify` - Run lint, typechain, tsc, and test (full verification)
-- `npm run precommit` - Full pre-commit check (localize, lint-staged, tsc, test)
+- `npm run verify` - Full verification: lint, typechain, tsc, the five
+  documentation gates, the Node-safety smoke test, Jest, and the CLI's offline
+  suites against both the sources and the built bundle
+- `npm run precommit` - Pre-commit check: localize, update-eslint-warnings,
+  lint-staged, the documentation gates, the Node-safety smoke test, tsc, Jest
+  and the CLI's offline suites
 - `tsc` - TypeScript type checking (via package.json script)
 
+### Edge CLI
+
+The repository also builds `edge-cli` and `edge-engine` from `src/cli/`.
+[`docs/EDGE_CLI.md`](docs/EDGE_CLI.md) is the guide; `docs/api/README.md`
+covers the route declarations the reference is generated from.
+
+- `npm run cli -- <command>` / `npm run engine` - run either half from source
+- `npm run build:cli` - the single-file bundles in `lib/`
+- `npm run docs:api` - regenerate the committed reference and command table
+- `npm run docs:api:gates` - the five read-only checks that it is in step
+- `npm run test:cli:offline` - the fake-world suites, no network
+- `npm run test:cli:network` - the suites that need the tester servers
+
 ## Swap Provider Integration
 
 The plugin itself lives in `edge-exchange-plugins`; this repo only wires it up, and every wiring point below fails SILENTLY when missed (no error, just a blank icon or a provider that never initializes). Registering a new swap `pluginId` means all of:
diff --git a/docs/EDGE_CLI.md b/docs/EDGE_CLI.md
new file mode 100644
index 00000000000..de427311d75
--- /dev/null
+++ b/docs/EDGE_CLI.md
@@ -0,0 +1,499 @@
+# Edge CLI
+
+A command-line interface for the Edge platform. Useful for account management,
+wallet operations, debugging, and scripting against edge-core-js.
+
+The CLI is a **thin one-shot client**. A long-lived **engine daemon** owns the
+`EdgeContext`, keeps logged-in accounts alive across invocations, and exposes a
+JSON REST API over a Unix domain socket (TCP is optional).
+
+For the full surface — every command, its REST call, and the `edge-core-js`
+call behind it — see the generated reference at
+[docs/api/dist/index.html](./api/dist/index.html), built from `docs/api/`.
+
+## Overview
+
+| Piece | Role |
+|-------|------|
+| `edge-engine` | Long-lived daemon. Owns one `EdgeContext` and N `EdgeAccount`s keyed by `sessionId`. Serves HTTP. |
+| `edge-cli` | One-shot client. Parses argv, auto-spawns the engine if needed, talks over the Unix socket, prints results. |
+
+By default the client uses only the Unix socket at
+`~/.edge-cli/run/<profile>/engine.sock`. Enable loopback TCP with
+`--tcp=9008` on the engine (useful for `curl` / scripts). That port is
+authenticated with a token from the run file — see
+[Sessions](#sessions).
+
+The CLI keeps state under two roots:
+
+| Path | Holds |
+|------|-------|
+| `~/.config/edge-cli/` | `edge-cli.conf`, and the account data directory `--directory` defaults to. The data directory is created `0700`: it holds the login stashes |
+| `~/.edge-cli/run/<profile>/` | `engine.sock`, `engine.json`, `session.json` — per profile; directory `0700`, files `0600` |
+| `~/.edge-cli/logs/` | `engine-<profile>.log` |
+| `~/.edge-cli/keys.json` | API keys, after `./keys.json` |
+
+Account repos therefore live under `~/.config/edge-cli`, not `~/.edge-cli`.
+Pass `--directory` to put them somewhere else; it is part of the profile hash,
+so a different directory is a different engine.
+
+## Running
+
+**Development (from source):**
+
+```bash
+npm run cli -- help                              # One-shot via client (auto-spawns engine)
+npm run cli -- login-with-password --username=u --password=p  # sessionId is persisted
+npm run cli -- balance-map --wallet-id=<id>           # Reuses the engine + session
+
+npm run engine                      # Start the engine alone
+npm run engine -- -t                # Engine against tester servers
+npm run engine -- --tcp=9008        # Also listen on 127.0.0.1:9008
+```
+
+**Built artifact:**
+
+```bash
+npm run build:cli                   # → lib/edgeCli.js + lib/edgeEngine.js
+node lib/edgeCli.js help
+node lib/edgeEngine.js -t --tcp=9008
+```
+
+**Published (npm):** not yet. `edge-react-gui` is `private` with no `bin`
+entry, so there is nothing for `npx` to fetch and no `edge-cli` on a `PATH`.
+Until a package is published, run the built artifact directly as above. The
+`edge-cli` name used throughout this document is the command the built
+`lib/edgeCli.js` presents as; it is not an npm package name.
+
+**Interactive prompt:** run `edge-cli` with no command and it reads commands
+from stdin instead of exiting, with tab completion over the command list. The
+engine, session and flags are the same as one-shot mode — `edge-cli -t` with no
+command opens a prompt already pointed at the tester servers. `help` lists the
+commands, and EOF (Ctrl-D) leaves.
+
+### Engine / client flags
+
+| Flag | Who | Description |
+|------|-----|-------------|
+| `-t, --test` | both | Use the six `-tester` servers — see below |
+| `--fake` | both | Emulate the login, info and sync servers in-process — no network, no API key. Its own engine profile, so it never shares a socket with a real one |
+| `-d, --directory` | both | Working directory for local Edge data |
+| `-a, --app-id` | both | Application ID |
+| `-k, --api-key` | both | Override API key from `keys.json` — also turns off the keys.json secret and the native HMAC signer. The client forwards it to the engine in the environment, not on the command line. An `apiKey` in the config file supplies the key *without* that override |
+| `--locale <tag>` | both | Language tag (BCP 47 or POSIX). Also `EDGE_CLI_LOCALE` or `locale` in the config file |
+| `--tcp=<port>` | both | Bind TCP on `127.0.0.1`, token-authenticated — off by default; bare `--tcp` and `--tcp=` are both errors, and `--tcp=0` picks an ephemeral port. On the client it is forwarded to the engine it spawns |
+| `--idle-timeout=<seconds>` | engine | Self-shutdown once nothing holds the engine open — default `300`, `0` means never, and a blank value is an error |
+| `--no-spawn` | client | Do not auto-start the engine; fail if none is running |
+| `--timeout=<seconds>` | client | Per-request deadline (default `120`) — on expiry the client gives up while the engine runs the request to completion, so raise it for a whole-wallet `get-transactions`, `wait-for-all-wallets` or `resync-blockchain` |
+| `--session <id>` | client | Override the persisted `sessionId` |
+| `--solve-captcha` | client | On `CHALLENGE_REQUIRED`, auto-solve ALTCHA PoW and retry |
+| `-c, --config <path>` | both | Configuration file. Forwarded to the engine the client spawns, so one file decides both halves |
+| `--tcp-host=<host>` | engine | TCP bind host, loopback only (default `127.0.0.1`) — a non-loopback address is a usage error, because the port would expose `spend` and `get-raw-private-key` to the network |
+| `-u, --username` | client | Legacy one-shot login helper |
+| `-p, --password` | client | Legacy one-shot login helper |
+| `-h, --help` | both | Show options |
+
+API keys load from `./keys.json`, then `~/.edge-cli/keys.json`
+(`edgeApiKey`, `edgeApiSecret`, `pluginApiKeys`).
+
+When the native Edge API HMAC signer is available, the engine prefers it over
+`keys.json` secrets for **both** `edge-core-js` and `GET /v1/getKeys` on the
+info server. Plugin secrets (including Monero LWS `edgeApiKey`) come from that
+fetch and overlay local `pluginApiKeys`. Set `EDGE_CLI_FORCE_KEYS_JSON=1`
+(or pass `-k`) to force the JSON key/secret pair instead — useful for tester
+embeds and debugging. `-t` signs getKeys against `info-tester.edge.app`.
+
+Locale: `--locale`, then `locale` in `edge-cli.conf`, then `EDGE_CLI_LOCALE`,
+then `LC_ALL` / `LC_MESSAGES` / `LANG`, then `Intl`, then `en-US`. The tag
+selects the language tables the engine's responses are built from. It also
+sets `decimalSeparator` and `groupingSeparator`, which `GET /engine/status`
+reports — but nothing on either CLI entry's import graph formats a number
+through them, so today they are reported for a caller's benefit rather than
+applied to anything the CLI prints. An already-running engine keeps its
+locale; the client warns on mismatch and continues.
+
+## Tester servers
+
+**Always use `-t` / `--test` for testing. Never hit production in tests.**
+
+`-t` points the engine at these six hosts (the only `*-tester.edge.app`
+names that resolve):
+
+| Host | `EdgeContextOptions` field |
+|------|----------------------------|
+| `https://login-tester.edge.app` | `loginServer` |
+| `https://info-tester.edge.app` | `infoServer` |
+| `https://sync-tester-us1.edge.app` | `syncServer` (array) |
+| `https://sync-tester-us2.edge.app` | `syncServer` |
+| `https://sync-tester-us3.edge.app` | `syncServer` |
+| `https://change-tester.edge.app` | `changeServer` |
+
+```bash
+npm run cli -- -t --solve-captcha create-account --username=alice --password='pass' --pin=1234
+npm run cli -- -t login-with-password --username=alice --password='pass'
+```
+
+Confirm with `edge-cli engine-config` — every server URL should be a
+`*-tester.edge.app` host. `testMode` being true is necessary but not
+sufficient: it means "not production", and `--fake` reports true while pointed
+at `fake://login`, so read the server list to tell the two apart.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  cli["edge-cli (one-shot)"] -->|"HTTP / unix socket"| engine
+  script["scripts / curl"] -->|"HTTP / TCP (opt-in --tcp=9008)"| engine
+  subgraph engine [edge-engine daemon]
+    router[Router] --> sessions[SessionStore]
+    sessions --> account1["EdgeAccount (sess_A)"]
+    sessions --> account2["EdgeAccount (sess_B)"]
+    router --> context["EdgeContext (single)"]
+  end
+  context --> core[edge-core-js + currency plugins]
+```
+
+ASCII equivalent:
+
+```
+edge-cli  ──HTTP──►  engine.sock  ──►  edge-engine
+                                         │
+                                         ├─ EdgeContext (one)
+                                         └─ accounts by sessionId
+                                            (sess_… → EdgeAccount)
+```
+
+A *profile* is a hash of `{ appId, directory, testMode, loginServer }`.
+Distinct profiles get distinct run directories, so a tester engine and a
+production engine can coexist. `directory` is canonicalised first — resolved
+to an absolute path and through any symlink — so one data directory is one
+profile however the path is spelled, and a trailing slash or a relative `-d`
+cannot give it a second engine.
+
+## Discovery
+
+Under `~/.edge-cli/run/<profile>/` (files mode `0600`):
+
+| File | Purpose |
+|------|---------|
+| `engine.json` | Discovery / lock: pid, apiVersion, socketPath, tcpPort, appId, testMode, startedAt |
+| `engine.sock` | Unix domain socket (always on) |
+| `session.json` | Last `sessionId` written by the client. Removed when the engine stops, since a session cannot outlive it |
+| `engine-startup.log` | The spawned engine's stdout and stderr, so a startup that dies before the socket exists (bad `keys.json`, a plugin that will not load) leaves a record rather than a spawn timeout. Kept when a stale lock is cleared, because the replacement engine is already writing to it |
+
+A clean shutdown removes all four and the profile directory with them.
+
+Example `engine.json`:
+
+```json
+{
+  "pid": 40123,
+  "apiVersion": "1.0.0",
+  "socketPath": "/Users/you/.edge-cli/run/8f3a.../engine.sock",
+  "tcpPort": null,
+  "appId": "",
+  "testMode": true,
+  "startedAt": "2026-08-06T04:55:00.000Z"
+}
+```
+
+Client flow: the profile is a pure hash of four argv-derived values, so the
+client needs nothing on disk to know which socket to use. It sends the request
+straight at that socket; only on ENOENT or ECONNREFUSED does it spawn the
+engine (unless `--no-spawn`), and `ensureEngine` pings `/engine/status` first
+in case one is already up, then polls readiness for up to 30 s and retries the
+request once.
+
+```bash
+# Manual status check over the socket
+curl --unix-socket ~/.edge-cli/run/<profile>/engine.sock \
+  http://localhost/engine/status
+```
+
+## Sessions
+
+Successful login returns an opaque `sessionId` (`sess_` + base58 of 16 random
+bytes). Account-scoped REST paths look like:
+
+```
+/account/{sessionId}/wallet/balance-map?walletId=<id>
+```
+
+A `sessionId` **is** the credential: every account-scoped route checks it and
+nothing else, so holding one means `get-pin`, `get-raw-private-key`,
+`get-login-key` and `spend`. Core authenticates the login itself via password
+/ PIN / key / recovery; `sessionId` scopes everything after that.
+
+The Unix socket therefore needs no transport auth of its own — it is `0600`
+inside a `0700` directory, so the operating system is the check. **The
+loopback TCP listener does**, because any process on the host can reach
+`127.0.0.1` whatever user it runs as, and so can a web page the user happens
+to be looking at. With `--tcp` the engine:
+
+- mints a bearer token at startup and writes it to the `0600` run file as
+  `tcpToken`, and requires it in an `X-Edge-Token` header;
+- refuses any request carrying an `Origin` header, and any request whose
+  `Host` is not the address it bound — which is what stops a page reaching it
+  by rebinding a name onto the port;
+- refuses to bind anything but a loopback address.
+
+```bash
+edge-cli engine-status                    # starts an engine
+TOKEN=$(jq -r .tcpToken ~/.edge-cli/run/<profile>/engine.json)
+curl -sH "X-Edge-Token: $TOKEN" http://127.0.0.1:9008/engine/status
+```
+
+A missing or wrong token is `401 UNAUTHORIZED`; a bad `Origin` or `Host` is
+`403 FORBIDDEN`. `engine-sessions` truncates every `sessionId` it reports, so
+the listing is a diagnostic rather than a way to collect credentials.
+
+The client persists the latest id in `session.json` so commands chain without
+re-typing. Override with `--session <id>` or `EDGE_CLI_SESSION`.
+
+**Auto-logout** mirrors the GUI: the engine reads `autoLogoutTimeInSeconds`
+from the account’s synced `Settings.json` (default `3600`, `0` = disabled) and
+logs the account out after that much idle time since the last REST call that
+touched the session. `edge-cli touch` is an explicit keepalive.
+
+**Engine idle shutdown:** after ~5 minutes with nothing holding it open, the
+engine closes the context, unlinks the socket / run file, and exits. Four
+things hold it: a logged-in session, a live subscription, a request being
+served, and a pending edge login, whose handle belongs to no session and whose
+TTL is the same 5 minutes. Configure with `--idle-timeout` (`0` = never). A live `subscribe` holds
+it open — see [Subscribing to events](#subscribing-to-events).
+
+```bash
+edge-cli -t login-with-password --username=alice --password='pass'  # stores sessionId
+edge-cli currency-wallets                 # uses persisted session
+edge-cli engine-sessions
+edge-cli touch
+edge-cli logout
+```
+
+## CAPTCHA
+
+`usernameAvailable`, `createAccount`, and `loginWithPassword` can raise a
+login-server CAPTCHA. The engine does **not** solve it. It returns:
+
+```json
+{
+  "error": {
+    "code": "CHALLENGE_REQUIRED",
+    "status": 403,
+    "message": "Login requires a CAPTCHA challenge challengeId=YUXCPENDRSDHMMA7 challengeUri=https://login-tester.edge.app/captcha/YUXCPENDRSDHMMA7 Retry the same request with body/query challengeId after solving, or use CLI --solve-captcha.",
+    "details": {
+      "challengeId": "YUXCPENDRSDHMMA7",
+      "challengeUri": "https://login-tester.edge.app/captcha/YUXCPENDRSDHMMA7"
+    }
+  }
+}
+```
+
+Options:
+
+1. **CLI helper** — `--solve-captcha` on any login command headlessly
+   solves ALTCHA PoW at `challengeUri` and retries with `challengeId`.
+2. **Manual** — open the URI in a browser, then re-run the command with
+   `--challenge-id <id>` (or pass `challengeId` in the REST body).
+3. **Prefetch** — `edge-cli fetch-challenge` → `POST /fetch-challenge`.
+
+Automated tests use the same ALTCHA solver (see `src/cli/client/solveCaptcha.ts`).
+
+## Edge login (QR / barcode)
+
+`edge-cli request-edge-login` requests a pending Edge login and prints JSON the
+approving device can use. By default it then **blocks**, polling every 2 seconds
+for up to 5 minutes, and stores the session as soon as the login is approved.
+Pass `--no-wait` to print the JSON and exit immediately, which is what a script
+that drives its own polling wants:
+
+```json
+{
+  "pendingId": "pending_7Qk3mVJ2xR4t",
+  "lobbyId": "HbC9mVJ2xR4tN8pL",
+  "uri": "edge://edge/HbC9mVJ2xR4tN8pL",
+  "state": "pending"
+}
+```
+
+Approve from another logged-in Edge device (Scan QR), or paste `uri` /
+`lobbyId` via **Scan QR → Enter** (useful with Maestro on the iOS simulator).
+
+After `--no-wait`, poll it yourself with `poll-edge-login <pendingId>` (or
+`GET /pending-edge-login/{pendingId}`) until `state` is `done` — it then carries
+the session — or `error`. `fetch-lobby <lobbyId>` reads the lobby without
+waiting, and `cancel-request <pendingId>` abandons it.
+
+## Command shape
+
+Commands are not listed here. The full reference — every command paired with
+the REST call it makes and the `edge-core-js` call behind it, with request and
+response types and an example — is generated from the route declarations:
+
+**[docs/api/dist/index.html](./api/dist/index.html)**
+
+```bash
+npm run docs:api          # rebuild it
+npm run docs:api:gates    # check it still matches src/cli
+```
+
+Every command follows one shape:
+
+```
+edge-cli [global flags] <command> [--flag=value ...]
+```
+
+| Form | Example |
+|------|---------|
+| Preferred | `--wallet-id=7o7i6` |
+| Also accepted | `--wallet-id 7o7i6` |
+| Boolean | `--paused` means true; `--paused=false` turns it off. A required one must be written out: `--paused=true` |
+| Repeatable | `--answer=rex --answer=oak` |
+| Lists | comma-separated, no spaces: `--export-format=csv,qbo` |
+| JSON | single-quoted: `--spend-info='{"tokenId":null}'` |
+
+Arguments are named. A command takes a bare positional only where the value is
+a base58 identifier the engine issued — an object handle, a pending login —
+because only those are safe as a URL path segment. A wallet id is base64 and a
+username is free text, so both are flags. `edge-cli help <command>` prints the
+exact usage for any of them, and that text is generated from the same source
+as the reference.
+
+For the native asset, omit `--token-id` rather than passing the literal
+`null`. An empty `--name=` is a usage error, as are unknown flags and extra
+positionals.
+
+### Subscribing to events
+
+`edge-cli subscribe` holds a Server-Sent Events stream open and prints one JSON
+object per line until you interrupt it. It runs concurrently with ordinary
+one-shot commands, so a subscriber in one terminal watches what another
+terminal does:
+
+```bash
+# terminal 1
+edge-cli subscribe --type=session.created --type=session.expired
+
+# terminal 2
+edge-cli -t login-with-password --username=alice --password='pass'
+edge-cli logout
+```
+
+A live subscription keeps the **engine** alive past its idle timeout — the
+stream would otherwise die under the subscriber. It does **not** keep an
+**account** logged in: the auto-logout timer still fires on schedule.
+
+Scope comes from the query string. `subscribe` opens an **unscoped** stream,
+which carries context-level events and survives for as long as the engine
+does — so a subscriber that logged in, was auto-logged-out and logged in again
+keeps the same stream, and `subscription.closed` arrives only when the engine
+stops. A stream opened with `?sessionId=` is account-scoped and that session's
+logout closes it, with `?walletId=` narrowing it further; `?type=` repeated
+filters it in the engine, so an unwanted event never crosses the socket.
+
+`subscribe` exits `0` on Ctrl-C and `7` when the engine ends the stream, or
+for any close reason it does not recognise. A Ctrl-C during a cold start has
+to wait for the engine to finish spawning before the stream can be closed
+cleanly; a second Ctrl-C in that window exits `130` immediately instead.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Generic failure |
+| `2` | Usage / bad argv |
+| `3` | Auth / session |
+| `4` | Not found |
+| `5` | Validation / funds |
+| `6` | Network |
+| `7` | Engine unavailable |
+
+Codes `3` to `6` are assigned from an explicit list of error codes, published
+per code in the generated reference. An error code with no entry in that list
+— and any non-`ApiClientError` failure — exits `1`, so `1` means "failed, with
+no more specific mapping" rather than "unknown error".
+
+## Source layout
+
+```
+src/cli/
+  engine/
+    index.ts           # Daemon entry, argv, signals
+    makeCoreContext.ts # Plugin registration + makeEdgeContext
+    server.ts          # HTTP handler; unix (+ optional TCP) listeners
+    router.ts          # Method + path dispatch
+    route.ts           # route() — the declaration every doc and command is built from
+    doc.ts             # doc() — prose attached to a cleaner
+    schemas.ts         # Query coercions and shared response shapes
+    objectHandles.ts   # Handles for core values that cannot cross JSON
+    sessions.ts        # SessionStore + auto-logout ticker
+    idleShutdown.ts    # Idle self-shutdown
+    discovery.ts       # Profile hash, run-file, socket paths
+    errors.ts          # EngineError + core → HTTP mapping
+    errorGroups.ts     # Error codes that recur across routes
+    apiVersion.ts      # The protocol version, for every surface that shows it
+    transportAuth.ts   # Token, Host and Origin checks for the TCP listener
+    tcpPort.ts         # --tcp parsing, shared by both entries
+    cliHome.ts         # ~/.edge-cli and the paths under it
+    readJsonConfig.ts  # One read-parse-clean for the config files
+    sweepTicker.ts     # The periodic sweep both stores run
+    json.ts            # Body parse / Uint8Array·Map codec
+    internal.ts        # `$internalStuff` access for the admin routes
+    resolve.ts         # walletId prefix, tokenId parsing
+    events.ts          # SSE hub
+    logger.ts          # Engine log file
+    cliConfig.ts       # edge-cli.conf + default directory
+    keysConfig.ts      # keys.json search path
+    appConfig.ts       # appId / app config
+    fetchPluginKeys.ts # Remote plugin keys over the signed infoRollup
+    nodeApiSigner.ts   # Node HMAC signer for the Edge API
+    testerServers.ts   # The six -tester hosts
+    routes/            # status, login, account, wallets, …
+  client/
+    apiClient.ts       # HTTP over socketPath or TCP
+    spawnEngine.ts     # Auto-spawn + readiness poll
+    sessionFile.ts     # Persisted sessionId
+    solveCaptcha.ts    # Headless ALTCHA solver for --solve-captcha
+    output.ts          # JSON / NDJSON output + exit codes
+    exitCodes.ts       # Error code → exit code, shared with the reference
+  commands/            # Argv → apiClient → output (no core imports)
+  command.ts           # command() registry
+  commandArgs.ts       # Per-command flag parsing
+  parseArgs.ts         # Client/engine argv before the command name
+  flagTable.ts         # Every global flag, once; both help texts render it
+  bootNodeLocale.ts    # Locale detection, before anything reads a string
+  bootEngineLocale.ts  # Applies it; engine only, so the client ships no tables
+  generatedSchemas.ts  # Cleaners for the files scripts/build* generate
+  index.ts             # One-shot and interactive front-end
+```
+
+Shared, outside `src/cli/`: `src/util/predicates.ts` holds the small
+predicates both halves use, because `src/util/exportTxInfo.ts` needs one and
+that module is reached from the app — the React Native bundle must not import
+out of the daemon's directory.
+
+Every module in `src/cli/engine/` is listed above; `scripts/cliNodeSafeSmoke.js`
+is what keeps the list honest about what loads under plain Node.
+
+## Tests
+
+| Script | What it runs |
+|--------|--------------|
+| `npm run test:cli:offline` | `testCliFake` + `testCliSubscribe` against the sources, through `sucrase/register`. No network, no Edge API key. |
+| `npm run test:cli:offline:built` | The same suites against `lib/edgeCli.js`, the bundle `build:cli` produces — which is how the CLI is run until a package is published. Part of `verify`. |
+| `npm run test:cli:node-safe` | Loads every CLI module under plain Node, so a `react-native` import at module scope fails here. |
+| `npm run test:cli:network` | One-shot, CAPTCHA and Edge-login suites. Needs the network and an Edge API key. |
+| `npm run docs:api:gates` | The five documentation gates. |
+
+Three different transforms produce a working CLI — `sucrase` for the suites,
+`@react-native/babel-preset` for jest, `@babel/preset-env` for the bundle — so
+a defect can exist in only one of them. `EDGE_CLI_BIN=<path>` points either
+offline suite at any built CLI.
+
+## REST API
+
+Full method/path/body/error documentation is generated:
+**[docs/api/dist/index.html](./api/dist/index.html)**, with an OpenAPI 3.1
+document beside it at `docs/api/dist/openapi.json`. The source of truth is
+`docs/api/`; see [docs/api/README.md](./api/README.md).
diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100644
index 00000000000..74faee60adf
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,169 @@
+# Edge CLI API docs
+
+The `edge-cli` command line and the `edge-engine` REST API, declared once and
+rendered together. Each call is a single `route({…})` in
+`src/cli/engine/routes/`, holding both forms, so the CLI usage and the HTTP
+request cannot drift apart — from each other or from the code.
+
+```bash
+npm run docs:api          # rebuild the command table, help text and dist/
+npm run docs:api:gates    # the five checks Travis and precommit run
+```
+
+Open `docs/api/dist/index.html` in a browser. The command line comes first in
+every entry, the REST call second, and each states the `edge-core-js` call it
+fronts.
+
+**`dist/` is committed on purpose** so the reference can be read on GitHub and
+linked to without a build step. `npm run docs:api` is idempotent: it rewrites
+the generated files only when they change, and `docs:api:check` fails if a
+route edit landed without them being rebuilt.
+
+## Naming
+
+Routes are named after the core call they front, kebab-cased, and the command
+matches: `context.forgetAccount` becomes `POST /forget-account` and
+`forget-account`. Parameters keep core's names.
+
+A path parameter is a base58 identifier, and nothing else — `sessionId`,
+`objectId`, `pendingId`, `lobbyId`, `syncKey`. Base58 has no `/`, `?` or `#`,
+so it survives a URL as written. A base64 wallet id or a free-text username
+does not, so those are named arguments: the query for `GET`, the body for
+`POST`. That is why `balance-map` is
+`GET /account/{sessionId}/wallet/balance-map?walletId=…` rather than putting
+the wallet id in the path. Where a path parameter is allowed it comes last, in
+the order the command reads. Collection segments are singular, since each call
+acts on one. Only `GET` and `POST` are used, since core has no HTTP verbs, and
+a core method returning `void` answers `204`.
+
+A call with no core equivalent sets `core: null` and explains itself in a
+`@coreNote`; the verifier enforces that.
+
+## Why generated, not hand-written
+
+A hand-maintained reference drifted badly: response shapes no route returned,
+status codes off by a category, body fields under the wrong name, and a
+documented `confirm=true` guard on account deletion the engine never
+implemented. None of that is visible by reading either the doc or the code
+alone — only by diffing them.
+
+So the declaration is the documentation. `scripts/extractRoutes.ts` reads every
+`route(…)` with the TypeScript checker: the JSDoc above it is the prose, and
+its `query`, `body` and `returns` cleaners are the shapes, resolved to the
+validator's own types. Everything downstream — the CLI's command table, its
+`help` text, the HTML reference and the OpenAPI document — is generated from
+that one source.
+
+## The five gates
+
+`npm run docs:api:gates`, also run by `precommit`:
+
+| Gate | Checks |
+| --- | --- |
+| `docs:api:check` | the generated files are current — rebuild them and nothing changes |
+| `docs:api:verify` | the surface matches: no route without the command it claims, no command nobody declares, no flag on one side missing from the other, no `core` naming a member `edge-core-js` does not have |
+| `docs:api:contracts` | the contract holds: every field a caller can send is described, nothing described has gone away, and no handler reads a field its cleaner would strip |
+| `docs:api:core` | each route's request matches the real signature of the core call it fronts, or records why it differs in `coreExtra` |
+| `docs:api:coverage` | every command is exercised by an automated test, or is listed with a reason |
+
+`docs:api:core` exists because checking the core member by name is not enough:
+that is how `currency-wallets` came to carry a `waitForAll` parameter
+`account.currencyWallets` does not have — it is a property, and waiting is a
+separate method.
+
+## Layout
+
+```
+docs/api/
+  README.md             this file
+  groups.ts             section titles and order, keyed by route-file basename
+  shared.ts             the error catalogue; re-exports the shared error
+                        groups and the exit-code table from runtime code
+  dist/                 generated — do not edit
+scripts/
+  extractRoutes.ts      reads the route declarations
+  cliUsage.ts           renders a usage line, and decides which fields
+                        need a JSON argument
+  writeIfChanged.ts     writes an output only when its bytes differ
+  buildCliCommands.ts   -> src/cli/generated/commands.json
+  buildCliHelp.ts       -> src/cli/generated/helpDocs.json
+  buildApiDocs.ts       -> dist/index.html and dist/openapi.json
+  verifyApiDocs.ts      surface drift
+  checkRouteContracts.ts  contract drift
+  checkCoreAlignment.ts   core signature drift
+  checkCliCoverage.ts     untested commands
+```
+
+There is no separate doc file per route: the route file *is* the doc file.
+`groups.ts` only decides section titles and render order.
+
+## Adding an endpoint
+
+Declare the route, and it documents itself:
+
+```ts
+/**
+ * Balances for every asset in the wallet.
+ *
+ * @note On the CLI, omit `--token-id` for the native asset rather than passing
+ *   the literal `null`.
+ * @coreNote Rendered as an array, with currencyCode and displayAmount added
+ *   from the wallet's denominations.
+ */
+export const balanceMap = route({
+  core: 'wallet.balanceMap', // or null, with a @coreNote saying why
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/balance-map',
+  cli: { command: 'balance-map' },
+  query: asObject({ walletId: asWalletId }).withRest,
+  returns: asObject({
+    balances: doc(
+      asArray(asBalance),
+      'One entry per asset the wallet holds, native coin first.'
+    )
+  }),
+  errors: WALLET_ERRORS,
+
+  handler(ctx) {
+    /* … */
+  }
+})
+```
+
+Then `npm run docs:api && npm run docs:api:gates`.
+
+Conventions worth keeping:
+
+- Wrap a cleaner in `doc(…)` to describe a field. `checkRouteContracts` fails a
+  response field with no prose, so the reference cannot ship a bare type.
+- Reuse the shared error lists from `src/cli/engine/errorGroups.ts`
+  (`SESSION_ERRORS`, `WALLET_ERRORS`, `HANDLE_ERRORS`) rather than restating
+  them. They live in runtime code so routes can import them and `shared.ts`
+  can re-export them for the reference; a route importing from `docs/` would
+  have the dependency backwards. Take error codes from the catalogue in
+  `shared.ts` — a code not in it fails `verify`.
+- Put anything a caller would get wrong from the type alone in a `@note`:
+  surprising defaults, fields that look symmetric but are not, calls that write
+  when they look like reads.
+- Two commands may share a route (`spend` / `spend-max`, via `preset`), and a
+  route may declare `cli: { custom: true }` when its command needs code of its
+  own. Both are fine; declare every binding on the route it calls.
+
+## Runtime validation
+
+The engine validates its own responses. `checkResponse` in
+`src/cli/engine/route.ts` runs each response through the route's `returns`
+cleaner on every request and **discards the cleaned value** — response cleaners
+strip unknown keys, so returning it would quietly delete fields the engine
+means to send. The check reports drift; it never reshapes anything.
+
+`EDGE_CLI_CHECK_RESPONSES` picks what a mismatch costs:
+
+| Value | Behaviour |
+| --- | --- |
+| unset, or `warn` | log `Response type mismatch` and answer normally (the default) |
+| `strict`, or `1` | fail the request with `500 INTERNAL_ERROR` |
+| `off`, or `0` | skip the check |
+
+So the documented shape is the validated shape, and a drifting response shows
+up in the engine log rather than silently reaching a caller.
diff --git a/docs/api/dist/index.html b/docs/api/dist/index.html
new file mode 100644
index 00000000000..135ddf76e8c
--- /dev/null
+++ b/docs/api/dist/index.html
@@ -0,0 +1,8499 @@
+<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Edge CLI API</title>
+<style>
+:root {
+  --bg: #fff; --fg: #16181d; --dim: #6b7280; --line: #e5e7eb; --card: #fafafa;
+  --accent: #2563eb; --code: #f3f4f6; --warn: #b45309; --ok: #047857;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0d1117; --fg: #e6edf3; --dim: #8b949e; --line: #262c36; --card: #131920;
+    --accent: #6ea8ff; --code: #1a212b; --warn: #d29922; --ok: #3fb950;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; background: var(--bg); color: var(--fg);
+  font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+}
+code, pre { font-family: var(--mono); font-size: 13px; }
+code { background: var(--code); padding: 1px 5px; border-radius: 4px; }
+pre { background: var(--code); padding: 12px 14px; border-radius: 8px; overflow-x: auto; margin: 8px 0; }
+pre code { background: none; padding: 0; }
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+.layout { display: flex; align-items: flex-start; }
+nav {
+  position: sticky; top: 0; height: 100vh; overflow-y: auto; flex: 0 0 270px;
+  border-right: 1px solid var(--line); padding: 20px 12px 60px;
+}
+nav h1 { font-size: 15px; margin: 0 8px 4px; }
+nav .ver { font-size: 12px; color: var(--dim); margin: 0 8px 14px; }
+nav input {
+  width: 100%; padding: 7px 10px; margin-bottom: 14px; font: inherit; font-size: 13px;
+  border: 1px solid var(--line); border-radius: 7px; background: var(--bg); color: var(--fg);
+}
+nav .s { font: 700 12px/1.5 var(--sans); text-transform: uppercase; letter-spacing: .08em;
+  color: var(--fg); margin: 18px 0 4px; padding-top: 10px; border-top: 1px solid var(--line); }
+nav .s:first-child { margin-top: 0; padding-top: 0; border-top: none; }
+nav .g { font-size: 11px; text-transform: uppercase; letter-spacing: .07em; color: var(--dim);
+  margin: 16px 8px 5px; font-weight: 600; }
+nav a.e { display: block; padding: 3px 8px; border-radius: 5px; font-size: 13px; color: var(--fg); }
+nav a.e:hover { background: var(--card); text-decoration: none; }
+nav a.e code { background: none; padding: 0; color: var(--accent); }
+nav a.e .restonly { color: var(--dim); font-style: italic; font-size: 12px; }
+
+main { flex: 1 1 auto; min-width: 0; padding: 32px 40px 120px; max-width: 1000px; }
+h2 { font-size: 22px; margin: 48px 0 6px; padding-top: 14px; border-top: 1px solid var(--line); }
+h3.sub { font-size: 16px; margin: 30px 0 4px; color: var(--fg); }
+h2:first-of-type { border-top: none; margin-top: 8px; }
+.groupdoc { color: var(--dim); margin: 0 0 8px; }
+
+.endpoint { border: 1px solid var(--line); border-radius: 12px; padding: 18px 20px;
+  margin: 18px 0; background: var(--card); }
+.endpoint header { display: flex; flex-wrap: wrap; align-items: baseline;
+  justify-content: space-between; gap: 8px; }
+.endpoint h3 { font-size: 17px; margin: 0; }
+.endpoint h3 a { color: var(--fg); }
+.ids { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.cmdname { background: var(--accent); color: #fff; font-weight: 600; }
+.restonly { color: var(--dim); font-style: italic; font-size: 12px; }
+.src { color: var(--dim); font-size: 11px; font-family: var(--mono); }
+.shape { margin: 6px 0; }
+.shape-h { font: 600 10px var(--mono); text-transform: uppercase; letter-spacing: .06em;
+  color: var(--dim); margin-bottom: 4px; }
+pre.ts { background: var(--code); border-left: 3px solid var(--accent); }
+pre.json { background: transparent; border: 1px dashed var(--line); }
+.shape details { margin: 6px 0; }
+.shape summary { cursor: pointer; font-size: 12px; color: var(--dim); user-select: none; }
+.shape summary:hover { color: var(--accent); }
+.core { margin: 8px 0 2px; font-size: 13px; display: flex; align-items: baseline;
+  gap: 8px; flex-wrap: wrap; }
+.core .lbl { font: 600 10px var(--mono); text-transform: uppercase; letter-spacing: .06em;
+  color: var(--dim); border: 1px solid var(--line); border-radius: 3px; padding: 1px 5px; }
+.core code { color: var(--ok); }
+.core.none em { color: var(--dim); font-style: italic; }
+.desc { margin: 8px 0 4px; }
+.desc p { margin: 6px 0; }
+
+.panes { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-top: 14px; }
+@media (max-width: 900px) { .panes { grid-template-columns: 1fr; } }
+.pane { background: var(--bg); border: 1px solid var(--line); border-radius: 9px; padding: 12px 14px;
+  /* A grid item defaults to min-width:auto, so a long unbreakable line makes
+     the column wider than its 1fr share and shoves the next pane sideways.
+     `overflow-x` on the <pre> never gets a chance until this is 0. */
+  min-width: 0; }
+.pane h4 { margin: 0 0 8px; font-size: 12px; text-transform: uppercase;
+  letter-spacing: .07em; color: var(--dim); }
+.pane h5 { margin: 12px 0 4px; font-size: 12px; color: var(--dim); font-weight: 600; }
+.pane.resp, .pane.notes { margin-top: 16px; }
+.pane.cli.none p { margin: 0; }
+.cmd + .cmd { margin-top: 14px; padding-top: 14px; border-top: 1px dashed var(--line); }
+/* A command line is a sentence, not a table: wrap it at the spaces rather
+   than making the reader scroll a pane sideways. `get-transactions` is 322
+   characters. */
+.usage, .ex { white-space: pre-wrap; overflow-wrap: break-word; }
+.usage { background: var(--code); }
+.ex { background: transparent; border: 1px dashed var(--line); }
+.lead { margin: 4px 0; color: var(--dim); font-size: 13px; }
+.note { font-size: 13px; }
+.note p { margin: 4px 0; }
+.pane.notes ul { margin: 0; padding-left: 20px; }
+.pane.notes li { margin: 5px 0; }
+
+.route { margin: 0 0 4px; display: flex; align-items: center; gap: 8px; }
+.m { font: 600 11px var(--mono); padding: 2px 7px; border-radius: 4px; color: #fff; }
+.m-GET { background: #2563eb; } .m-POST { background: #047857; }
+.m-PUT { background: #b45309; } .m-PATCH { background: #7c3aed; }
+.m-DELETE { background: #b91c1c; }
+
+table { border-collapse: collapse; width: 100%; margin: 4px 0; }
+table.fields td, table.flags td, table.flags th { padding: 4px 8px 4px 0;
+  vertical-align: top; font-size: 13px; border-bottom: 1px solid var(--line); }
+table.flags th { text-align: left; font-size: 11px; color: var(--dim); text-transform: uppercase; }
+td.k { white-space: nowrap; width: 1%; }
+td.ty { white-space: nowrap; width: 1%; }
+td.doc { color: var(--dim); }
+tr.d1 td.k { padding-left: 18px; } tr.d2 td.k { padding-left: 36px; }
+.t { color: var(--dim); font-family: var(--mono); font-size: 12px; }
+.t.core { color: var(--warn); border-bottom: 1px dotted var(--warn); cursor: help; }
+.dim { color: var(--dim); }
+.ref { font-family: var(--mono); font-size: 12px; }
+.flag { font-size: 10px; padding: 1px 5px; border-radius: 3px; border: 1px solid var(--line);
+  color: var(--dim); text-transform: uppercase; letter-spacing: .04em; }
+.flag.req { color: var(--warn); border-color: var(--warn); }
+.st { font: 600 11px var(--mono); padding: 1px 6px; border-radius: 4px;
+  background: var(--code); margin-right: 5px; }
+.st.ok { color: var(--ok); }
+.errs { display: flex; flex-wrap: wrap; gap: 6px; margin: 4px 0; }
+a.err { font: 12px var(--mono); border: 1px solid var(--line); border-radius: 5px;
+  padding: 2px 7px; color: var(--fg); }
+a.err:hover { border-color: var(--accent); text-decoration: none; }
+
+.schema { border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; margin: 14px 0;
+  background: var(--card); }
+.schema h3 { margin: 0 0 2px; font-size: 15px; font-family: var(--mono); }
+.schema .src { display: block; margin-bottom: 6px; }
+.hidden { display: none; }
+
+/* An alternate CLI binding's heading, e.g. `spend-max` under `spend`. */
+h5.alt {
+  margin: 1.1rem 0 0.35rem;
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+h5.alt code {
+  font-size: 0.95rem;
+}
+</style>
+</head><body>
+<div class="layout">
+<nav>
+  <h1>Edge CLI API</h1>
+  <p class="ver">v1.0.0 · 117 calls</p>
+  <input id="q" type="search" placeholder="Filter…" autocomplete="off">
+  <a class="e" href="#overview"><strong>Overview</strong></a>
+  <div class="s">Engine</div><div class="g">Lifecycle</div><a class="e" href="#engineStatus" data-s="engine liveness and summary. /engine/status engine-status "><code>engine-status</code></a><a class="e" href="#engineConfig" data-s="configured context options. /engine/config engine-config "><code>engine-config</code></a><a class="e" href="#engineStop" data-s="stop the engine. /engine/stop engine-stop "><code>engine-stop</code></a><div class="g">Event stream</div><a class="e" href="#engineEvents" data-s="subscribe to engine events. /engine/events subscribe "><code>subscribe</code></a><div class="s">Context</div><div class="g">Device and usernames</div><a class="e" href="#localUsers" data-s="list local users on this device. /local-users local-users "><code>local-users</code></a><a class="e" href="#forgetAccount" data-s="forget an account on this device. /forget-account forget-account "><code>forget-account</code></a><a class="e" href="#usernameAvailable" data-s="check whether a username is free. /username-available username-available "><code>username-available</code></a><a class="e" href="#fixUsername" data-s="normalize a username. /fix-username fix-username "><code>fix-username</code></a><a class="e" href="#checkPasswordRules" data-s="score a candidate password. /check-password-rules check-password-rules "><code>check-password-rules</code></a><a class="e" href="#fetchLoginMessages" data-s="fetch login-server messages for every local user. /fetch-login-messages fetch-login-messages "><code>fetch-login-messages</code></a><a class="e" href="#requestOtpReset" data-s="request a 2fa reset. /request-otp-reset request-otp-reset "><code>request-otp-reset</code></a><a class="e" href="#fetchRecoveryQuestions" data-s="fetch a user’s recovery questions. /fetch-recovery-questions fetch-recovery-questions "><code>fetch-recovery-questions</code></a><a class="e" href="#fetchChallenge" data-s="pre-fetch a captcha challenge. /fetch-challenge fetch-challenge "><code>fetch-challenge</code></a><a class="e" href="#currencyConfigs" data-s="list plugin ids usable for wallet creation. /currency-configs currency-configs "><code>currency-configs</code></a><div class="g">Login methods</div><a class="e" href="#loginWithPassword" data-s="log in with a password. /login-with-password login-with-password "><code>login-with-password</code></a><a class="e" href="#loginWithPin" data-s="log in with a device pin. /login-with-pin login-with-pin "><code>login-with-pin</code></a><a class="e" href="#loginWithKey" data-s="log in with an account login key. /login-with-key login-with-key "><code>login-with-key</code></a><a class="e" href="#loginWithRecovery" data-s="log in with recovery answers. /login-with-recovery login-with-recovery "><code>login-with-recovery</code></a><a class="e" href="#createAccount" data-s="create an account. /create-account create-account "><code>create-account</code></a><a class="e" href="#requestEdgeLogin" data-s="start a qr login. /request-edge-login request-edge-login "><code>request-edge-login</code></a><a class="e" href="#pollEdgeLogin" data-s="poll a pending qr login. /pending-edge-login/{pendingid} poll-edge-login "><code>poll-edge-login</code></a><a class="e" href="#cancelEdgeLogin" data-s="cancel a pending qr login. /pending-edge-login/cancel-request/{pendingid} cancel-request "><code>cancel-request</code></a><a class="e" href="#engineSessions" data-s="list active sessions. /engine/sessions engine-sessions "><code>engine-sessions</code></a><div class="s">Account</div><div class="g">Session</div><a class="e" href="#accountInfo" data-s="account and session summary. /account/{sessionid} account-info "><code>account-info</code></a><a class="e" href="#logout" data-s="log out. /account/{sessionid}/logout logout "><code>logout</code></a><a class="e" href="#touchSession" data-s="keepalive. /account/{sessionid}/touch touch "><code>touch</code></a><a class="e" href="#getLoginKey" data-s="read the account login key. /account/{sessionid}/get-login-key get-login-key "><code>get-login-key</code></a><a class="e" href="#accountSync" data-s="force an account data sync. /account/{sessionid}/sync sync "><code>sync</code></a><a class="e" href="#deleteRemoteAccount" data-s="permanently delete the remote account. /account/{sessionid}/delete-remote-account delete-remote-account "><code>delete-remote-account</code></a><a class="e" href="#waitForAllWallets" data-s="wait for every wallet to finish loading. /account/{sessionid}/wait-for-all-wallets wait-for-all-wallets "><code>wait-for-all-wallets</code></a><a class="e" href="#currencyWallets" data-s="list the account's wallets. /account/{sessionid}/currency-wallets currency-wallets "><code>currency-wallets</code></a><a class="e" href="#createCurrencyWallet" data-s="create a currency wallet. /account/{sessionid}/create-currency-wallet create-currency-wallet "><code>create-currency-wallet</code></a><a class="e" href="#createCurrencyWallets" data-s="create several wallets at once. /account/{sessionid}/create-currency-wallets create-currency-wallets "><code>create-currency-wallets</code></a><div class="g">Credentials</div><a class="e" href="#changePassword" data-s="set or change the password. /account/{sessionid}/change-password change-password "><code>change-password</code></a><a class="e" href="#deletePassword" data-s="remove password login. /account/{sessionid}/delete-password delete-password "><code>delete-password</code></a><a class="e" href="#checkPassword" data-s="verify a password. /account/{sessionid}/check-password check-password "><code>check-password</code></a><a class="e" href="#getPin" data-s="read the account pin. /account/{sessionid}/get-pin get-pin "><code>get-pin</code></a><a class="e" href="#changePin" data-s="set or change the pin. /account/{sessionid}/change-pin change-pin "><code>change-pin</code></a><a class="e" href="#deletePin" data-s="remove the pin. /account/{sessionid}/delete-pin delete-pin "><code>delete-pin</code></a><a class="e" href="#checkPin" data-s="verify a pin. /account/{sessionid}/check-pin check-pin "><code>check-pin</code></a><a class="e" href="#changeUsername" data-s="change the username. /account/{sessionid}/change-username change-username "><code>change-username</code></a><a class="e" href="#changeRecovery" data-s="set recovery questions and answers. /account/{sessionid}/change-recovery change-recovery "><code>change-recovery</code></a><a class="e" href="#deleteRecovery" data-s="disable recovery login. /account/{sessionid}/delete-recovery delete-recovery "><code>delete-recovery</code></a><div class="g">Two-factor authentication</div><a class="e" href="#otpKey" data-s="read the 2fa secret and reset state. /account/{sessionid}/otp-key otp-key "><code>otp-key</code></a><a class="e" href="#enableOtp" data-s="enable 2fa. /account/{sessionid}/enable-otp enable-otp "><code>enable-otp</code></a><a class="e" href="#disableOtp" data-s="disable 2fa. /account/{sessionid}/disable-otp disable-otp "><code>disable-otp</code></a><a class="e" href="#cancelOtpReset" data-s="cancel a pending 2fa reset. /account/{sessionid}/cancel-otp-reset cancel-otp-reset "><code>cancel-otp-reset</code></a><a class="e" href="#repairOtp" data-s="re-point the account at a known 2fa secret. /account/{sessionid}/repair-otp repair-otp "><code>repair-otp</code></a><div class="g">Vouchers</div><a class="e" href="#pendingVouchers" data-s="list pending 2fa vouchers. /account/{sessionid}/pending-vouchers pending-vouchers "><code>pending-vouchers</code></a><a class="e" href="#approveVoucher" data-s="approve a voucher. /account/{sessionid}/approve-voucher approve-voucher "><code>approve-voucher</code></a><a class="e" href="#rejectVoucher" data-s="reject a voucher. /account/{sessionid}/reject-voucher reject-voucher "><code>reject-voucher</code></a><div class="g">Approving a login</div><a class="e" href="#fetchLobby" data-s="inspect a login request. /account/{sessionid}/fetch-lobby/{lobbyid} fetch-lobby "><code>fetch-lobby</code></a><a class="e" href="#approveLoginRequest" data-s="approve a login request. /account/{sessionid}/approve-login-request/{lobbyid} approve-login-request "><code>approve-login-request</code></a><div class="g">Keys</div><a class="e" href="#allKeys" data-s="list every key in the account. /account/{sessionid}/all-keys all-keys "><code>all-keys</code></a><a class="e" href="#createWallet" data-s="create a wallet from raw key json. /account/{sessionid}/create-wallet create-wallet "><code>create-wallet</code></a><a class="e" href="#getWalletInfo" data-s="read one wallet's key info. /account/{sessionid}/get-wallet-info get-wallet-info "><code>get-wallet-info</code></a><a class="e" href="#getRawPrivateKey" data-s="read raw private key material. /account/{sessionid}/get-raw-private-key get-raw-private-key "><code>get-raw-private-key</code></a><a class="e" href="#getRawPublicKey" data-s="read raw public key material. /account/{sessionid}/get-raw-public-key get-raw-public-key "><code>get-raw-public-key</code></a><a class="e" href="#getDisplayPrivateKey" data-s="export the private key for display. /account/{sessionid}/get-display-private-key get-display-private-key "><code>get-display-private-key</code></a><a class="e" href="#getDisplayPublicKey" data-s="export the public key for display. /account/{sessionid}/get-display-public-key get-display-public-key "><code>get-display-public-key</code></a><a class="e" href="#listSplittableWalletTypes" data-s="list chains a wallet can split into. /account/{sessionid}/list-splittable-wallet-types list-splittable-wallet-types "><code>list-splittable-wallet-types</code></a><a class="e" href="#changeWalletStates" data-s="archive, delete, hide, or reorder wallets. /account/{sessionid}/change-wallet-states change-wallet-states "><code>change-wallet-states</code></a><div class="g">Swap quotes</div><a class="e" href="#fetchSwapQuotes" data-s="fetch swap quotes. /account/{sessionid}/fetch-swap-quotes fetch-swap-quotes "><code>fetch-swap-quotes</code></a><a class="e" href="#getSwapQuote" data-s="re-read a quote. /account/{sessionid}/swap-quote/{objectid} swap-quote-get "><code>swap-quote-get</code></a><a class="e" href="#approveSwapQuote" data-s="execute a quote. /account/{sessionid}/swap-quote/approve/{objectid} approve-swap-quote "><code>approve-swap-quote</code></a><a class="e" href="#closeSwapQuote" data-s="discard a quote. /account/{sessionid}/swap-quote/close/{objectid} close-swap-quote "><code>close-swap-quote</code></a><div class="g">Data store</div><a class="e" href="#listStoreIds" data-s="list data-store ids. /account/{sessionid}/list-store-ids list-store-ids "><code>list-store-ids</code></a><a class="e" href="#listItemIds" data-s="list item ids in a store. /account/{sessionid}/list-item-ids list-item-ids "><code>list-item-ids</code></a><a class="e" href="#getItem" data-s="read an item. /account/{sessionid}/get-item get-item "><code>get-item</code></a><a class="e" href="#setItem" data-s="write an item. /account/{sessionid}/set-item set-item "><code>set-item</code></a><a class="e" href="#deleteItem" data-s="delete an item. /account/{sessionid}/delete-item delete-item "><code>delete-item</code></a><a class="e" href="#deleteStore" data-s="delete an entire store. /account/{sessionid}/delete-store delete-store "><code>delete-store</code></a><div class="s">Wallet</div><div class="g">Wallet state</div><a class="e" href="#walletInfo" data-s="wallet detail. /account/{sessionid}/wallet wallet-info "><code>wallet-info</code></a><a class="e" href="#renameWallet" data-s="rename a wallet. /account/{sessionid}/wallet/rename-wallet rename-wallet "><code>rename-wallet</code></a><a class="e" href="#setFiatCurrencyCode" data-s="change a wallet's fiat currency. /account/{sessionid}/wallet/set-fiat-currency-code set-fiat-currency-code "><code>set-fiat-currency-code</code></a><a class="e" href="#changePaused" data-s="pause or resume a wallet engine. /account/{sessionid}/wallet/change-paused change-paused "><code>change-paused</code></a><a class="e" href="#walletSync" data-s="nudge one wallet to sync. /account/{sessionid}/wallet/sync wallet-sync "><code>wallet-sync</code></a><a class="e" href="#resyncBlockchain" data-s="rescan the blockchain from scratch. /account/{sessionid}/wallet/resync-blockchain resync-blockchain "><code>resync-blockchain</code></a><a class="e" href="#splitWallet" data-s="split a wallet into another chain. /account/{sessionid}/wallet/split split "><code>split</code></a><a class="e" href="#dumpData" data-s="dump wallet engine state. /account/{sessionid}/wallet/dump-data dump-data "><code>dump-data</code></a><a class="e" href="#balanceMap" data-s="balances for every asset in the wallet. /account/{sessionid}/wallet/balance-map balance-map "><code>balance-map</code></a><a class="e" href="#getAddresses" data-s="receive addresses. /account/{sessionid}/wallet/get-addresses get-addresses "><code>get-addresses</code></a><div class="g">Tokens</div><a class="e" href="#walletTokens" data-s="list a wallet's tokens. /account/{sessionid}/wallet/tokens wallet-tokens "><code>wallet-tokens</code></a><a class="e" href="#changeEnabledTokenIds" data-s="set the enabled token set. /account/{sessionid}/wallet/change-enabled-token-ids change-enabled-token-ids "><code>change-enabled-token-ids</code></a><div class="g">Transactions</div><a class="e" href="#getTransactions" data-s="list or export a wallet's transactions. /account/{sessionid}/wallet/get-transactions get-transactions "><code>get-transactions</code></a><a class="e" href="#getNumTransactions" data-s="count transactions in a wallet. /account/{sessionid}/wallet/get-num-transactions get-num-transactions "><code>get-num-transactions</code></a><a class="e" href="#saveTxMetadata" data-s="save transaction metadata. /account/{sessionid}/wallet/save-tx-metadata save-tx-metadata "><code>save-tx-metadata</code></a><a class="e" href="#saveTxAction" data-s="save a transaction action. /account/{sessionid}/wallet/save-tx-action save-tx-action "><code>save-tx-action</code></a><div class="g">Spending</div><a class="e" href="#getMaxSpendable" data-s="largest sendable amount. /account/{sessionid}/wallet/get-max-spendable get-max-spendable "><code>get-max-spendable</code></a><a class="e" href="#spend" data-s="send funds. /account/{sessionid}/wallet/spend spend spend-max send a wallet’s entire spendable balance."><code>spend</code></a><a class="e" href="#makeSpend" data-s="build an unsigned transaction. /account/{sessionid}/wallet/make-spend make-spend "><code>make-spend</code></a><a class="e" href="#signTx" data-s="sign a staged transaction. /account/{sessionid}/sign-tx/{objectid} sign-tx "><code>sign-tx</code></a><a class="e" href="#broadcastTx" data-s="broadcast a signed transaction. /account/{sessionid}/broadcast-tx/{objectid} broadcast-tx "><code>broadcast-tx</code></a><a class="e" href="#saveTx" data-s="record a transaction and release its handle. /account/{sessionid}/save-tx/{objectid} save-tx "><code>save-tx</code></a><a class="e" href="#accelerate" data-s="fee-bump a pending transaction. /account/{sessionid}/wallet/accelerate accelerate "><code>accelerate</code></a><a class="e" href="#sweepPrivateKeys" data-s="sweep private keys into this wallet. /account/{sessionid}/wallet/sweep-private-keys sweep-private-keys "><code>sweep-private-keys</code></a><a class="e" href="#signBytes" data-s="sign arbitrary bytes. /account/{sessionid}/wallet/sign-bytes sign-bytes "><code>sign-bytes</code></a><a class="e" href="#getPaymentProtocolInfo" data-s="fetch a bip70 payment request. /account/{sessionid}/wallet/get-payment-protocol-info get-payment-protocol-info "><code>get-payment-protocol-info</code></a><div class="g">URIs</div><a class="e" href="#parseUri" data-s="parse a payment uri or address. /account/{sessionid}/wallet/parse-uri parse-uri "><code>parse-uri</code></a><a class="e" href="#encodeUri" data-s="build a payment uri. /account/{sessionid}/wallet/encode-uri encode-uri "><code>encode-uri</code></a><div class="s">Local settings</div><div class="g">Local settings</div><a class="e" href="#localSettings" data-s="local settings. /account/{sessionid}/local-settings local-settings "><code>local-settings</code></a><a class="e" href="#changeLocalSettings" data-s="change local settings. /account/{sessionid}/change-local-settings local-settings "><code>local-settings</code></a><div class="s">Exchange rates</div><div class="g">Exchange rates</div><a class="e" href="#ratesQuery" data-s="batch crypto and fiat rate lookups. /rates/query rates-query "><code>rates-query</code></a><a class="e" href="#ratesUsdToNative" data-s="convert a usd amount into native units. /rates/usd-to-native rates-usd-to-native "><code>rates-usd-to-native</code></a><div class="s">Object handles</div><div class="g">Object handles</div><a class="e" href="#getObject" data-s="inspect an object handle. /account/{sessionid}/object/{objectid} object-get "><code>object-get</code></a><a class="e" href="#deleteObject" data-s="release an object handle. /account/{sessionid}/object/delete/{objectid} object-delete "><code>object-delete</code></a><div class="s">Admin</div><div class="g">Admin</div><a class="e" href="#adminAuthRequest" data-s="raw login-server request. /admin/auth-request admin-auth-request "><code>admin-auth-request</code></a><a class="e" href="#adminHashUsername" data-s="hash a username. /admin/hash-username admin-hash-username "><code>admin-hash-username</code></a><a class="e" href="#adminMakeLobby" data-s="create a lobby. /admin/make-lobby admin-make-lobby "><code>admin-make-lobby</code></a><a class="e" href="#adminDeleteLobbyHandle" data-s="close a parked lobby. /admin/lobby-handle/delete/{objectid} admin-lobby-handle-delete "><code>admin-lobby-handle-delete</code></a><a class="e" href="#adminFetchLobbyRequest" data-s="read a lobby's contents. /admin/fetch-lobby-request/{lobbyid} admin-fetch-lobby-request "><code>admin-fetch-lobby-request</code></a><a class="e" href="#adminSendLobbyReply" data-s="reply to a lobby. /admin/send-lobby-reply/{lobbyid} admin-send-lobby-reply "><code>admin-send-lobby-reply</code></a><a class="e" href="#adminSyncRepo" data-s="sync a repo. /admin/sync-repo/{synckey} admin-sync-repo "><code>admin-sync-repo</code></a><a class="e" href="#adminRepoList" data-s="list repo contents. /admin/repo-list/{synckey} admin-repo-list "><code>admin-repo-list</code></a><a class="e" href="#adminRepoGet" data-s="read a repo file. /admin/repo-get/{synckey} admin-repo-get "><code>admin-repo-get</code></a><a class="e" href="#adminRepoSet" data-s="write a repo file. /admin/repo-set/{synckey} admin-repo-set "><code>admin-repo-set</code></a><a class="e" href="#adminRepoDelete" data-s="delete a repo file. /admin/repo-delete/{synckey} admin-repo-delete "><code>admin-repo-delete</code></a>
+  <div class="g">Reference</div>
+  <a class="e" href="#errors">Error codes</a>
+  <a class="e" href="#exit-codes">Exit codes</a>
+</nav>
+<main>
+<h2 id="overview">Overview</h2>
+<div class="groupdoc"><p>Every entry is one API call shown twice: as an <code>edge-cli</code> command, then as the JSON REST request that command sends. Both are generated from a single declaration in <code>src/cli/engine/routes/</code>, so the two forms cannot drift apart.</p>
+<p>Routes are named after the <code>edge-core-js</code> call they front, kebab-cased: <code>context.forgetAccount</code> becomes <code>POST /forget-account</code>, and the command is <code>forget-account</code>. Parameters carry core&#39;s own names. Every entry states its core call, or says why there is none. Only <code>GET</code> and <code>POST</code> appear — core has no HTTP verbs, so reads are GET and everything else is POST.</p>
+<p>The <code>edge-cli</code> client is a thin one-shot process. A long-lived <code>edge-engine</code> daemon owns the <code>EdgeContext</code> and every logged-in account, serving this API over a Unix socket at <code>~/.edge-cli/run/&lt;profile&gt;/engine.sock</code>, plus loopback TCP when started with <code>--tcp=9008</code>.</p>
+<p><strong>There is no transport authentication.</strong> The socket is owner-only (<code>0600</code>) and TCP is loopback, so anything that can reach the engine can act as every logged-in account.</p>
+<p><a id="object-handles"></a>
+<strong>Ephemeral object handles.</strong> In <code>edge-core-js</code> a method-bearing value is identified by object reference — you call <code>wallet.signTx(tx)</code> on the very <code>tx</code> that <code>makeSpend</code> returned. That does not survive HTTP, so the engine parks such values under an <code>objectId</code> with a 5 minute TTL and later steps name the id. Reads do not extend the TTL; only a step that updates the value does. Finishing a workflow, or <code>POST …/objects/{objectId}/delete</code>, releases the handle early. Expired handles return <code>410 OBJECT_EXPIRED</code>.</p>
+<p><strong>Serialization.</strong> <code>Uint8Array</code> becomes base64, <code>Date</code> becomes an ISO-8601 string, <code>Map</code> becomes an object, amounts are always decimal strings, and <code>EdgeTokenId</code> is JSON <code>null</code> for a native asset.</p>
+<p><strong>Testing.</strong> Always pass <code>-t</code> / <code>--test</code> to point at the <code>*-tester.edge.app</code> servers.</p>
+</div>
+<h2 id="engine">Engine</h2>
+      <div class="groupdoc"><p>The <code>edge-engine</code> daemon itself. None of these have an <code>edge-core-js</code> equivalent — they describe the process — and none need a session.</p>
+</div>
+      <h3 class="sub" id="status">Lifecycle</h3>
+          <div class="groupdoc"><p>Lifecycle and configuration of the <code>edge-engine</code> daemon. None of these have an <code>edge-core-js</code> equivalent — they describe the daemon itself — and none need a session.</p>
+</div>
+          <section class="endpoint" id="engineStatus">
+    <header>
+      <h3><a href="#engineStatus">Engine liveness and summary.</a></h3>
+      <div class="ids"><code class="cmdname">engine-status</code><span class="src" title="Declared in">src/cli/engine/routes/status.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine lifecycle; the daemon is not part of the core API.</em></p>
+    <div class="desc"><p>The readiness probe the client polls after auto-spawning the engine.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>engine-status</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/engine/status</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/engine/status'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>idleShutdownAt</code> is null while a session or a subscription holds the engine open, and <code>tcpPort</code> is null unless started with <code>--tcp</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  pid: number
+  apiVersion: string
+  uptimeSeconds: number
+  sessionCount: number
+  testMode: boolean
+  idleShutdownAt: string | null
+  tcpPort: number | null
+  socketPath: string
+  rateCachedCount: number
+  locale: string
+  localeMatched: boolean
+  decimalSeparator: string
+  groupingSeparator: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pid&quot;: 0,
+  &quot;apiVersion&quot;: &quot;string&quot;,
+  &quot;uptimeSeconds&quot;: 1,
+  &quot;sessionCount&quot;: 1,
+  &quot;testMode&quot;: true,
+  &quot;idleShutdownAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;tcpPort&quot;: 0,
+  &quot;socketPath&quot;: &quot;string&quot;,
+  &quot;rateCachedCount&quot;: 1,
+  &quot;locale&quot;: &quot;string&quot;,
+  &quot;localeMatched&quot;: true,
+  &quot;decimalSeparator&quot;: &quot;string&quot;,
+  &quot;groupingSeparator&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pid</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">The daemon process, for <code>kill</code> when it will not stop.</td>
+</tr>
+<tr>
+  <td class="k"><code>apiVersion</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The API this engine speaks. A client refusing to talk to an older engine checks this.</td>
+</tr>
+<tr>
+  <td class="k"><code>uptimeSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">How long the daemon has been running.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionCount</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Logged-in accounts held open right now.</td>
+</tr>
+<tr>
+  <td class="k"><code>testMode</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True when the engine is not pointed at production: the tester fleet, or the in-process fake world under <code>--fake</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>idleShutdownAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When the engine will exit for want of work. Null while anything is holding it open — a logged-in session, a live subscription, a request being served, or a pending edge login, whose handle belongs to no session — and null when the timeout is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>tcpPort</code></td>
+  <td class="ty"><span class="t">number | null</span></td>
+  <td class="doc">The loopback port, null unless started with <code>--tcp</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>socketPath</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Unix socket the CLI connects to.</td>
+</tr>
+<tr>
+  <td class="k"><code>rateCachedCount</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Exchange rates held in the engine’s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it.</td>
+</tr>
+<tr>
+  <td class="k"><code>locale</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Language tag the engine resolved at boot.</td>
+</tr>
+<tr>
+  <td class="k"><code>localeMatched</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Whether a translation table for that tag was actually found. False means the tag was accepted but the engine is answering in English, which is otherwise indistinguishable from a build that has the language.</td>
+</tr>
+<tr>
+  <td class="k"><code>decimalSeparator</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Decimal mark for that locale.</td>
+</tr>
+<tr>
+  <td class="k"><code>groupingSeparator</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Thousands mark for that locale.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-ENGINE_SHUTTING_DOWN" class="err" title="Idle or explicit shutdown already in progress."><span class="st">503</span>ENGINE_SHUTTING_DOWN</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="engineConfig">
+    <header>
+      <h3><a href="#engineConfig">Configured context options.</a></h3>
+      <div class="ids"><code class="cmdname">engine-config</code><span class="src" title="Declared in">src/cli/engine/routes/status.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Reflects the EdgeContextOptions the engine supplied at startup.</em></p>
+    <div class="desc"><p>What the engine passed to <code>makeEdgeContext</code>. Contains no secrets. Use it to assert tester hosts before a test run.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>engine-config</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/engine/config</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/engine/config'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  appId: string
+  testMode: boolean
+  directory: string
+  servers: {
+    [keys: string]: string | string[]
+  }
+  plugins: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;appId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;testMode&quot;: true,
+  &quot;directory&quot;: &quot;string&quot;,
+  &quot;servers&quot;: {},
+  &quot;plugins&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>appId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Application ID the engine was started with.</td>
+</tr>
+<tr>
+  <td class="k"><code>testMode</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True when the engine is not pointed at production: the tester fleet, or the in-process fake world under <code>--fake</code>. Read <code>servers</code> to tell those apart.</td>
+</tr>
+<tr>
+  <td class="k"><code>directory</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Working directory holding the core data.</td>
+</tr>
+<tr>
+  <td class="k"><code>servers</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: string | string[]; }</span></td>
+  <td class="doc">The URLs this engine talks to, keyed by role. <code>syncServer</code> is a list, since core rotates across the sync fleet.</td>
+</tr>
+<tr>
+  <td class="k"><code>plugins</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Plugin IDs the engine loaded, sorted.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Outside <code>-t</code> / <code>--test</code>, <code>servers</code> is an empty object — core is using its built-in production defaults, so there is nothing to echo back.</li></ul></div>
+  </section><section class="endpoint" id="engineStop">
+    <header>
+      <h3><a href="#engineStop">Stop the engine.</a></h3>
+      <div class="ids"><code class="cmdname">engine-stop</code><span class="src" title="Declared in">src/cli/engine/routes/status.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine lifecycle. Internally calls <code>context.close()</code>.</em></p>
+    <div class="desc"><p>Logs out every session, closes the context, unlinks the socket and run-file, then exits. The engine answers before it starts tearing down, so a response is not proof the process is gone.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>engine-stop</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/engine/stop</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/engine/stop'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Always true; a failure arrives as an error envelope.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li><code>503 ENGINE_SHUTTING_DOWN</code> reaches requests that arrive <em>after</em> teardown starts, not ones already in flight: <code>handleRequest</code> tests the flag at the top only. A request already past that point is waited for — shutdown drains in-flight work before logging out — so it gets its real response. This route is exempt: a second stop is answered <code>ok</code>, because stopping an engine that is already stopping has succeeded.</li></ul></div>
+  </section><h3 class="sub" id="events">Event stream</h3>
+          <div class="groupdoc"><p>A Server-Sent Events feed of engine activity, served outside the router because the response never ends.</p>
+</div>
+          <section class="endpoint" id="engineEvents">
+    <header>
+      <h3><a href="#engineEvents">Subscribe to engine events.</a></h3>
+      <div class="ids"><code class="cmdname">subscribe</code><span class="src" title="Declared in">src/cli/engine/routes/events.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine-side fan-out; <code>core.log</code> frames carry core&#39;s onLog output.</em></p>
+    <div class="desc"><p>Holds a Server-Sent Events stream open until the caller disconnects or the engine closes it. Runs concurrently with one-shot calls, so a subscriber in one terminal watches what another terminal does.</p>
+<p>A live subscription holds the engine open past its idle timeout. It does not hold an account logged in: the auto-logout timer still fires, and closes any subscription scoped to that account or one of its wallets. Context-scoped subscriptions survive, because the context outlives every account.</p>
+<p>Scope comes from the query string. With no <code>sessionId</code> the stream is context-scoped and nothing but the engine stopping ends it, which is what the <code>subscribe</code> command asks for. With <code>sessionId</code> it is account-scoped: a logout closes it, and the session events of <em>other</em> accounts are filtered out. <code>walletId</code> narrows it further, for whenever a wallet-scoped event exists — no event carries a wallet scope today, so on its own it changes only which events close the stream.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>subscribe [--session-id=&lt;sessionId&gt;] [--wallet-id=&lt;walletId&gt;] [--type=&lt;value&gt;]</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--type</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Only these event types. Applied by the engine, so an unwanted type never crosses the socket; the client filters again for the types the engine sends regardless, like <code>subscription.closed</code>.</td></tr></tbody></table>
+    <div class="note"><p>Prints newline-delimited JSON and runs until interrupted. Exits 0 on SIGINT and 7 when the engine ends the stream. <code>subscribe</code> opens an unscoped stream, which only the engine stopping ends; a stream opened with <code>sessionId</code> is closed by that session logging out.</p>
+</div>
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/engine/events</code></p>
+    
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  sessionId?: string
+  walletId?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Scope the stream to one account, so a logout closes it. Omitted, the stream is context-scoped and only the engine stopping ends it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">With <code>sessionId</code>, narrow the stream to one wallet. No event carries a wallet scope yet, so today this only narrows which events can close the stream. Ignored on its own.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/engine/events'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>One frame per event, as <code>event:</code> then <code>data:</code> lines.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  type: string
+  data: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;type&quot;: &quot;string&quot;,
+  &quot;data&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>type</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The event name.</td>
+</tr>
+<tr>
+  <td class="k"><code>data</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc">Payload, shaped by the event type.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Frame types: <code>core.log</code>, <code>session.created</code>, <code>session.expired</code>, <code>engine.shutdown</code>, and <code>subscription.closed</code> when the engine ends it.</li><li>The <code>subscribe</code> command prints one further frame of its own once the stream is over, <code>subscription.ended</code>, carrying the close reason. It comes from the client, so <code>--type</code> does not filter it.</li><li><code>sessionId</code> in event payloads is truncated to its first 10 characters.</li><li>A client more than 1 MiB behind is disconnected rather than buffered.</li><li>Served directly by the HTTP handler rather than through the router, because the response never ends.</li></ul></div>
+  </section><h2 id="context">Context</h2>
+      <div class="groupdoc"><p>Calls on the shared <code>EdgeContext</code>: device state, username queries, and every way of logging in. None of them need a session, because a session is what they produce.</p>
+</div>
+      <h3 class="sub" id="context">Device and usernames</h3>
+          <div class="groupdoc"><p>Calls on the shared <code>EdgeContext</code>: local device state and login-server queries that do not need a session.</p>
+</div>
+          <section class="endpoint" id="localUsers">
+    <header>
+      <h3><a href="#localUsers">List local users on this device.</a></h3>
+      <div class="ids"><code class="cmdname">local-users</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.localUsers</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>local-users</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/local-users</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/local-users'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>Everything <code>context.localUsers</code> reports, including which login methods each user has enabled on this device.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  localUsers: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;localUsers&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>localUsers</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc"><code>EdgeUserInfo[]</code>: one entry per account cached on this device.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    
+  </section><section class="endpoint" id="forgetAccount">
+    <header>
+      <h3><a href="#forgetAccount">Forget an account on this device.</a></h3>
+      <div class="ids"><code class="cmdname">forget-account</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.forgetAccount</code></p>
+    <div class="desc"><p>Removes locally cached credentials. The remote account is untouched.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>forget-account --root-login-id=&lt;rootLoginId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/forget-account</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  rootLoginId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Core takes a <code>rootLoginId</code>. A username is also accepted and resolved against <code>localUsers</code> first, so callers need not hash it.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;rootLoginId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/forget-account'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-USER_NOT_FOUND" class="err" title="No local user matches that username or login id."><span class="st">404</span>USER_NOT_FOUND</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="usernameAvailable">
+    <header>
+      <h3><a href="#usernameAvailable">Check whether a username is free.</a></h3>
+      <div class="ids"><code class="cmdname">username-available</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.usernameAvailable</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>username-available --username=&lt;username&gt; [--challenge-id=&lt;challengeId&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/username-available</code></p>
+    
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  username: string
+  challengeId?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The name to check.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Supply after solving a CAPTCHA to retry the same check.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/username-available?username=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  username: string
+  available: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;available&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The name that was checked, echoed back.</td>
+</tr>
+<tr>
+  <td class="k"><code>available</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True when nobody holds this name. It is not reserved by asking.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-CHALLENGE_REQUIRED" class="err" title="The login server wants a CAPTCHA. Retry with `challengeId`."><span class="st">403</span>CHALLENGE_REQUIRED</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="fixUsername">
+    <header>
+      <h3><a href="#fixUsername">Normalize a username.</a></h3>
+      <div class="ids"><code class="cmdname">fix-username</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.fixUsername</code></p>
+    <div class="desc"><p>Applies the same rules the login server does, so a caller can show the user what their name will actually be before creating an account.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>fix-username --username=&lt;username&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/fix-username</code></p>
+    
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  username: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The name to normalize.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/fix-username?username=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  username: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The normalized value. The input is not echoed.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    
+  </section><section class="endpoint" id="checkPasswordRules">
+    <header>
+      <h3><a href="#checkPasswordRules">Score a candidate password.</a></h3>
+      <div class="ids"><code class="cmdname">check-password-rules</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.checkPasswordRules</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>check-password-rules --password=&lt;password&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/check-password-rules</code></p>
+    
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  password: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;password&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>password</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The candidate password to score.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/check-password-rules?password=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>EdgePasswordRules</code> from core: passed, tooShort, noNumber, noLowerCase, noUpperCase, secondsToCrack.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Send it with <code>curl --get --data-urlencode</code> rather than putting it in a shell-visible URL.</li></ul></div>
+  </section><section class="endpoint" id="fetchLoginMessages">
+    <header>
+      <h3><a href="#fetchLoginMessages">Fetch login-server messages for every local user.</a></h3>
+      <div class="ids"><code class="cmdname">fetch-login-messages</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.fetchLoginMessages</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>fetch-login-messages</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/fetch-login-messages</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/fetch-login-messages'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>EdgeLoginMessages</code> from core, keyed by loginId; each value carries otpResetPending and pendingVouchers.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="requestOtpReset">
+    <header>
+      <h3><a href="#requestOtpReset">Request a 2FA reset.</a></h3>
+      <div class="ids"><code class="cmdname">request-otp-reset</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.requestOtpReset</code></p>
+    <div class="desc"><p>Starts the timed reset a user falls back on after losing their authenticator.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>request-otp-reset --username=&lt;username&gt; --otp-reset-token=&lt;otpResetToken&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/request-otp-reset</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  username: string
+  otpResetToken: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;otpResetToken&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Whose 2FA to reset.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpResetToken</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>details.resetToken</code> on an <code>OTP_REQUIRED</code> error.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;username&quot;:&quot;string&quot;,&quot;otpResetToken&quot;:&quot;string&quot;}' \
+  'http://localhost/request-otp-reset'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>When the reset completes if nobody cancels it.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  resetDate: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;resetDate&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>resetDate</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When 2FA will actually come off. The login server enforces a waiting period so the real owner has time to cancel.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="fetchRecoveryQuestions">
+    <header>
+      <h3><a href="#fetchRecoveryQuestions">Fetch a user’s recovery questions.</a></h3>
+      <div class="ids"><code class="cmdname">fetch-recovery-questions</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.fetchRecovery2Questions</code> <span class="dim">Our surface drops the <code>2</code> from the path, command and <code>recoveryKey</code> parameter; a future Recovery1 would be suffixed <code>V1</code>.</span></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>recoveryKey</code> — Core calls it recovery2Key. The <code>2</code> is dropped throughout.</li></ul></div>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>fetch-recovery-questions --recovery-key=&lt;recoveryKey&gt; --username=&lt;username&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/fetch-recovery-questions</code></p>
+    
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  recoveryKey: string
+  username: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;recoveryKey&quot;: &quot;string&quot;,
+  &quot;username&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>recoveryKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>change-recovery</code>, stored by the user out of band.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Whose questions to fetch.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/fetch-recovery-questions?recoveryKey=…&amp;username=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  questions: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;questions&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>questions</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">The questions in the order <code>login-with-recovery</code> expects the answers.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="fetchChallenge">
+    <header>
+      <h3><a href="#fetchChallenge">Pre-fetch a CAPTCHA challenge.</a></h3>
+      <div class="ids"><code class="cmdname">fetch-challenge</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.fetchChallenge</code></p>
+    <div class="desc"><p>Lets a client solve a challenge before it hits <code>403 CHALLENGE_REQUIRED</code> mid-flow.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>fetch-challenge</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/fetch-challenge</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/fetch-challenge'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>challengeUri</code> is absent when the server considers the challenge already satisfied.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  challengeId: string
+  challengeUri?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;challengeUri&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Pass to the call that demanded a challenge once the user has solved it.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeUri</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Where to send the user to solve the CAPTCHA. Absent when the server issued a challenge that needs no interaction.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="currencyConfigs">
+    <header>
+      <h3><a href="#currencyConfigs">List plugin ids usable for wallet creation.</a></h3>
+      <div class="ids"><code class="cmdname">currency-configs</code><span class="src" title="Declared in">src/cli/engine/routes/context.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine view of the enabled plugin set; core exposes <code>account.currencyConfig</code> per plugin instead.</em></p>
+    <div class="desc"><p>Currency and accountbased plugins only — swap plugins are excluded.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>currency-configs</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/currency-configs</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/currency-configs'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  pluginIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pluginIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pluginIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Currency plugins this engine loaded.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    
+  </section><h3 class="sub" id="login">Login methods</h3>
+          <div class="groupdoc"><p>Every successful login returns a <a href="#schema-Session">Session</a> and registers it in the engine, so later calls need only the <code>sessionId</code>. The CLI writes that id to <code>session.json</code> automatically.</p>
+</div>
+          <section class="endpoint" id="loginWithPassword">
+    <header>
+      <h3><a href="#loginWithPassword">Log in with a password.</a></h3>
+      <div class="ids"><code class="cmdname">login-with-password</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.loginWithPassword</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>login-with-password [--otp=&lt;otp&gt;] [--otp-key=&lt;otpKey&gt;] [--challenge-id=&lt;challengeId&gt;] --username=&lt;username&gt; --password=&lt;password&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/login-with-password</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  otp?: string
+  otpKey?: string
+  challengeId?: string
+  username: string
+  password: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otp&quot;: &quot;string&quot;,
+  &quot;otpKey&quot;: &quot;string&quot;,
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;password&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otp</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A current 2FA code.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The 2FA secret itself, instead of a code.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Supply after solving a CAPTCHA to retry the same request.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account name.</td>
+</tr>
+<tr>
+  <td class="k"><code>password</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account password.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;otp&quot;:&quot;string&quot;,&quot;otpKey&quot;:&quot;string&quot;,&quot;challengeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;username&quot;:&quot;string&quot;,&quot;password&quot;:&quot;string&quot;}' \
+  'http://localhost/login-with-password'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>A session with <code>loginMethod: &quot;password&quot;</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  sessionId: string
+  username?: string
+  rootLoginId: string
+  loginMethod: &quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginMethod&quot;: &quot;&lt;\&quot;create\&quot;&gt;&quot;,
+  &quot;autoLogoutSeconds&quot;: 1,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lastActivityAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Absent for a light account, which has no username.</td>
+</tr>
+<tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account root, stable across appIds. Two sessions sharing it are the same account.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginMethod</code></td>
+  <td class="ty"><span class="t">&quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;</span></td>
+  <td class="doc">How this session was established.</td>
+</tr>
+<tr>
+  <td class="k"><code>autoLogoutSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Idle time before the engine logs the account out. 0 disables it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When auto-logout will fire, or null when it is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastActivityAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Last call on this session, which is what auto-logout measures from.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the login completed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-PASSWORD_ERROR" class="err" title="Wrong password, PIN, or recovery answers."><span class="st">401</span>PASSWORD_ERROR</a> <a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-OTP_REQUIRED" class="err" title="Missing or wrong 2FA token."><span class="st">401</span>OTP_REQUIRED</a> <a href="#err-CHALLENGE_REQUIRED" class="err" title="The login server wants a CAPTCHA. Retry with `challengeId`."><span class="st">403</span>CHALLENGE_REQUIRED</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>With <code>--solve-captcha</code> the client solves a <code>CHALLENGE_REQUIRED</code> response headlessly (ALTCHA proof-of-work) and retries once.</li></ul></div>
+  </section><section class="endpoint" id="loginWithPin">
+    <header>
+      <h3><a href="#loginWithPin">Log in with a device PIN.</a></h3>
+      <div class="ids"><code class="cmdname">login-with-pin</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.loginWithPIN</code></p>
+    <div class="desc"><p>Only works on a device that has already saved a PIN for the account.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>login-with-pin [--otp=&lt;otp&gt;] [--otp-key=&lt;otpKey&gt;] [--challenge-id=&lt;challengeId&gt;] --username-or-login-id=&lt;usernameOrLoginId&gt; --pin=&lt;pin&gt; [--use-login-id[=false]]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/login-with-pin</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  otp?: string
+  otpKey?: string
+  challengeId?: string
+  usernameOrLoginId: string
+  pin: string
+  useLoginId?: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otp&quot;: &quot;string&quot;,
+  &quot;otpKey&quot;: &quot;string&quot;,
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;usernameOrLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;pin&quot;: &quot;string&quot;,
+  &quot;useLoginId&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otp</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A current 2FA code.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The 2FA secret itself, instead of a code.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Supply after solving a CAPTCHA to retry the same request.</td>
+</tr>
+<tr>
+  <td class="k"><code>usernameOrLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">A username, or a login id.</td>
+</tr>
+<tr>
+  <td class="k"><code>pin</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The device PIN.</td>
+</tr>
+<tr>
+  <td class="k"><code>useLoginId</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Treat the value as a login id.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;otp&quot;:&quot;string&quot;,&quot;otpKey&quot;:&quot;string&quot;,&quot;challengeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;usernameOrLoginId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;pin&quot;:&quot;string&quot;,&quot;useLoginId&quot;:true}' \
+  'http://localhost/login-with-pin'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>A session with <code>loginMethod: &quot;pin&quot;</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  sessionId: string
+  username?: string
+  rootLoginId: string
+  loginMethod: &quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginMethod&quot;: &quot;&lt;\&quot;create\&quot;&gt;&quot;,
+  &quot;autoLogoutSeconds&quot;: 1,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lastActivityAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Absent for a light account, which has no username.</td>
+</tr>
+<tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account root, stable across appIds. Two sessions sharing it are the same account.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginMethod</code></td>
+  <td class="ty"><span class="t">&quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;</span></td>
+  <td class="doc">How this session was established.</td>
+</tr>
+<tr>
+  <td class="k"><code>autoLogoutSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Idle time before the engine logs the account out. 0 disables it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When auto-logout will fire, or null when it is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastActivityAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Last call on this session, which is what auto-logout measures from.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the login completed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-PASSWORD_ERROR" class="err" title="Wrong password, PIN, or recovery answers."><span class="st">401</span>PASSWORD_ERROR</a> <a href="#err-PIN_DISABLED" class="err" title="PIN login is not enabled on this device."><span class="st">403</span>PIN_DISABLED</a> <a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="loginWithKey">
+    <header>
+      <h3><a href="#loginWithKey">Log in with an account login key.</a></h3>
+      <div class="ids"><code class="cmdname">login-with-key</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.loginWithKey</code></p>
+    <div class="desc"><p>The key comes from <code>get-login-key</code> on an already-authenticated session.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>login-with-key [--otp=&lt;otp&gt;] [--otp-key=&lt;otpKey&gt;] [--challenge-id=&lt;challengeId&gt;] --username-or-login-id=&lt;usernameOrLoginId&gt; --login-key=&lt;loginKey&gt; [--use-login-id[=false]]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/login-with-key</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  otp?: string
+  otpKey?: string
+  challengeId?: string
+  usernameOrLoginId: string
+  loginKey: string
+  useLoginId?: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otp&quot;: &quot;string&quot;,
+  &quot;otpKey&quot;: &quot;string&quot;,
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;usernameOrLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginKey&quot;: &quot;string&quot;,
+  &quot;useLoginId&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otp</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A current 2FA code.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The 2FA secret itself, instead of a code.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Supply after solving a CAPTCHA to retry the same request.</td>
+</tr>
+<tr>
+  <td class="k"><code>usernameOrLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">A username, or a login id.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>get-login-key</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>useLoginId</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Treat the value as a login id.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;otp&quot;:&quot;string&quot;,&quot;otpKey&quot;:&quot;string&quot;,&quot;challengeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;usernameOrLoginId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;loginKey&quot;:&quot;string&quot;,&quot;useLoginId&quot;:true}' \
+  'http://localhost/login-with-key'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>A session with <code>loginMethod: &quot;key&quot;</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  sessionId: string
+  username?: string
+  rootLoginId: string
+  loginMethod: &quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginMethod&quot;: &quot;&lt;\&quot;create\&quot;&gt;&quot;,
+  &quot;autoLogoutSeconds&quot;: 1,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lastActivityAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Absent for a light account, which has no username.</td>
+</tr>
+<tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account root, stable across appIds. Two sessions sharing it are the same account.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginMethod</code></td>
+  <td class="ty"><span class="t">&quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;</span></td>
+  <td class="doc">How this session was established.</td>
+</tr>
+<tr>
+  <td class="k"><code>autoLogoutSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Idle time before the engine logs the account out. 0 disables it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When auto-logout will fire, or null when it is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastActivityAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Last call on this session, which is what auto-logout measures from.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the login completed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-PASSWORD_ERROR" class="err" title="Wrong password, PIN, or recovery answers."><span class="st">401</span>PASSWORD_ERROR</a> <a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="loginWithRecovery">
+    <header>
+      <h3><a href="#loginWithRecovery">Log in with recovery answers.</a></h3>
+      <div class="ids"><code class="cmdname">login-with-recovery</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.loginWithRecovery2</code> <span class="dim">Our surface drops the <code>2</code> from core&#39;s recovery2 naming, and calls the key <code>recoveryKey</code> to match what <code>change-recovery</code> returns.</span></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>recoveryKey</code> — Core calls it recovery2Key. The <code>2</code> is dropped throughout.</li></ul></div>
+    <div class="desc"><p>Needs both the recovery key and the answers; neither works alone.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>login-with-recovery [--otp=&lt;otp&gt;] [--otp-key=&lt;otpKey&gt;] [--challenge-id=&lt;challengeId&gt;] --recovery-key=&lt;recoveryKey&gt; --username=&lt;username&gt; --answer=&lt;answers&gt; …</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/login-with-recovery</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  otp?: string
+  otpKey?: string
+  challengeId?: string
+  recoveryKey: string
+  username: string
+  answers: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otp&quot;: &quot;string&quot;,
+  &quot;otpKey&quot;: &quot;string&quot;,
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;recoveryKey&quot;: &quot;string&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;answers&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otp</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A current 2FA code.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The 2FA secret itself, instead of a code.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Supply after solving a CAPTCHA to retry the same request.</td>
+</tr>
+<tr>
+  <td class="k"><code>recoveryKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>change-recovery</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account name.</td>
+</tr>
+<tr>
+  <td class="k"><code>answers</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">In the same order as the questions.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;otp&quot;:&quot;string&quot;,&quot;otpKey&quot;:&quot;string&quot;,&quot;challengeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;recoveryKey&quot;:&quot;string&quot;,&quot;username&quot;:&quot;string&quot;,&quot;answers&quot;:[&quot;string&quot;]}' \
+  'http://localhost/login-with-recovery'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>A session with <code>loginMethod: &quot;recovery&quot;</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  sessionId: string
+  username?: string
+  rootLoginId: string
+  loginMethod: &quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginMethod&quot;: &quot;&lt;\&quot;create\&quot;&gt;&quot;,
+  &quot;autoLogoutSeconds&quot;: 1,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lastActivityAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Absent for a light account, which has no username.</td>
+</tr>
+<tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account root, stable across appIds. Two sessions sharing it are the same account.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginMethod</code></td>
+  <td class="ty"><span class="t">&quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;</span></td>
+  <td class="doc">How this session was established.</td>
+</tr>
+<tr>
+  <td class="k"><code>autoLogoutSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Idle time before the engine logs the account out. 0 disables it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When auto-logout will fire, or null when it is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastActivityAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Last call on this session, which is what auto-logout measures from.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the login completed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-PASSWORD_ERROR" class="err" title="Wrong password, PIN, or recovery answers."><span class="st">401</span>PASSWORD_ERROR</a> <a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="createAccount">
+    <header>
+      <h3><a href="#createAccount">Create an account.</a></h3>
+      <div class="ids"><code class="cmdname">create-account</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.createAccount</code></p>
+    <div class="desc"><p>Every credential is optional over REST: omitting all three creates a light account with no username.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>create-account [--otp=&lt;otp&gt;] [--otp-key=&lt;otpKey&gt;] [--challenge-id=&lt;challengeId&gt;] [--username=&lt;username&gt;] [--password=&lt;password&gt;] [--pin=&lt;pin&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/create-account</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  otp?: string
+  otpKey?: string
+  challengeId?: string
+  username?: string
+  password?: string
+  pin?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otp&quot;: &quot;string&quot;,
+  &quot;otpKey&quot;: &quot;string&quot;,
+  &quot;challengeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;password&quot;: &quot;string&quot;,
+  &quot;pin&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otp</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A current 2FA code.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The 2FA secret itself, instead of a code.</td>
+</tr>
+<tr>
+  <td class="k"><code>challengeId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Supply after solving a CAPTCHA to retry the same request.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The name to claim.</td>
+</tr>
+<tr>
+  <td class="k"><code>password</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">The account password.</td>
+</tr>
+<tr>
+  <td class="k"><code>pin</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A device PIN to save.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;otp&quot;:&quot;string&quot;,&quot;otpKey&quot;:&quot;string&quot;,&quot;challengeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;username&quot;:&quot;string&quot;,&quot;password&quot;:&quot;string&quot;,&quot;pin&quot;:&quot;string&quot;}' \
+  'http://localhost/create-account'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>A session with <code>loginMethod: &quot;create&quot;</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  sessionId: string
+  username?: string
+  rootLoginId: string
+  loginMethod: &quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginMethod&quot;: &quot;&lt;\&quot;create\&quot;&gt;&quot;,
+  &quot;autoLogoutSeconds&quot;: 1,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lastActivityAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Absent for a light account, which has no username.</td>
+</tr>
+<tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account root, stable across appIds. Two sessions sharing it are the same account.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginMethod</code></td>
+  <td class="ty"><span class="t">&quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;</span></td>
+  <td class="doc">How this session was established.</td>
+</tr>
+<tr>
+  <td class="k"><code>autoLogoutSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Idle time before the engine logs the account out. 0 disables it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When auto-logout will fire, or null when it is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastActivityAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Last call on this session, which is what auto-logout measures from.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the login completed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-CHALLENGE_REQUIRED" class="err" title="The login server wants a CAPTCHA. Retry with `challengeId`."><span class="st">403</span>CHALLENGE_REQUIRED</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The command requires a username, password and PIN. Creating a light account is REST-only.</li></ul></div>
+  </section><section class="endpoint" id="requestEdgeLogin">
+    <header>
+      <h3><a href="#requestEdgeLogin">Start a QR login.</a></h3>
+      <div class="ids"><code class="cmdname">request-edge-login</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.requestEdgeLogin</code></p>
+    <div class="desc"><p>Asks the login server for a lobby another logged-in Edge device can approve. The returned <code>lobbyId</code> is what goes in the QR code.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>request-edge-login [--no-wait]</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--no-wait</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Print the lobby and exit instead of polling, so the QR can be displayed while <code>poll-edge-login</code> watches the same handle from another process.</td></tr></tbody></table>
+    <div class="note"><p>Prints the pending login, then polls every 2s for up to 5 minutes. On <code>done</code> it stores the session. With <code>--no-wait</code> it returns immediately and <code>poll-edge-login</code> takes over.</p>
+</div>
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/request-edge-login</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/request-edge-login'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  pendingId: string
+  kind: string
+  expiresAt: string | null
+  lobbyId: string
+  uri: string
+  state: string
+  username: string | null
+  session: {
+    sessionId: string;
+    username: string | undefined;
+    rootLoginId: string;
+    loginMethod: &quot;password&quot; | &quot;pin&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;create&quot; | &quot;recovery&quot;;
+    autoLogoutSeconds: number;
+    expiresAt: string | null;
+    lastActivityAt: string;
+    createdAt: string
+  } | null
+  error: string | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;pendingId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lobbyId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;uri&quot;: &quot;string&quot;,
+  &quot;state&quot;: &quot;string&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;session&quot;: {},
+  &quot;error&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>pendingId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Same value as <code>objectId</code>, under the name the poll command takes.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When the lobby closes and the QR code stops working.</td>
+</tr>
+<tr>
+  <td class="k"><code>lobbyId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Lobby the phone connects to.</td>
+</tr>
+<tr>
+  <td class="k"><code>uri</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The <code>edge://</code> URI to render as a QR code for the phone to scan.</td>
+</tr>
+<tr>
+  <td class="k"><code>state</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">How far the login has got: <code>pending</code> before the phone scans, <code>started</code> once it has, and <code>done</code> when <code>session</code> is filled in.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Account that approved the login, known once the phone has scanned.</td>
+</tr>
+<tr>
+  <td class="k"><code>session</code></td>
+  <td class="ty"><span class="t">{ sessionId: string; username: string | undefined; rootLoginId: string; loginMethod: &quot;password&quot; | &quot;pin&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;create&quot; | &quot;recovery&quot;; autoLogoutSeconds: number; expiresAt: string | null; lastActivityAt: string; createdAt: string; } | null</span></td>
+  <td class="doc">The session, null until <code>state</code> is <code>done</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>error</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Why the login failed, set only when <code>state</code> is <code>error</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The pending login is an object handle with a 5 minute TTL. On expiry the engine cancels the request on the login server for you.</li></ul></div>
+  </section><section class="endpoint" id="pollEdgeLogin">
+    <header>
+      <h3><a href="#pollEdgeLogin">Poll a pending QR login.</a></h3>
+      <div class="ids"><code class="cmdname">poll-edge-login</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine state for an in-flight requestEdgeLogin; core exposes it as EdgePendingEdgeLogin properties.</em></p>
+    <div class="desc"><p>Once <code>state</code> reaches <code>done</code> the engine has already created the session, so the response carries one ready to use.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>poll-edge-login &lt;pendingId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/pending-edge-login/{pendingId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>pendingId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">The <code>pendingId</code> returned when the QR login was requested.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/pending-edge-login/$PENDINGID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  pendingId: string
+  kind: string
+  expiresAt: string | null
+  lobbyId: string
+  uri: string
+  state: string
+  username: string | null
+  session: {
+    sessionId: string;
+    username: string | undefined;
+    rootLoginId: string;
+    loginMethod: &quot;password&quot; | &quot;pin&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;create&quot; | &quot;recovery&quot;;
+    autoLogoutSeconds: number;
+    expiresAt: string | null;
+    lastActivityAt: string;
+    createdAt: string
+  } | null
+  error: string | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;pendingId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lobbyId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;uri&quot;: &quot;string&quot;,
+  &quot;state&quot;: &quot;string&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;session&quot;: {},
+  &quot;error&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>pendingId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Same value as <code>objectId</code>, under the name the poll command takes.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When the lobby closes and the QR code stops working.</td>
+</tr>
+<tr>
+  <td class="k"><code>lobbyId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Lobby the phone connects to.</td>
+</tr>
+<tr>
+  <td class="k"><code>uri</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The <code>edge://</code> URI to render as a QR code for the phone to scan.</td>
+</tr>
+<tr>
+  <td class="k"><code>state</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">How far the login has got: <code>pending</code> before the phone scans, <code>started</code> once it has, and <code>done</code> when <code>session</code> is filled in.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Account that approved the login, known once the phone has scanned.</td>
+</tr>
+<tr>
+  <td class="k"><code>session</code></td>
+  <td class="ty"><span class="t">{ sessionId: string; username: string | undefined; rootLoginId: string; loginMethod: &quot;password&quot; | &quot;pin&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;create&quot; | &quot;recovery&quot;; autoLogoutSeconds: number; expiresAt: string | null; lastActivityAt: string; createdAt: string; } | null</span></td>
+  <td class="doc">The session, null until <code>state</code> is <code>done</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>error</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Why the login failed, set only when <code>state</code> is <code>error</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-PENDING_LOGIN_NOT_FOUND" class="err" title="No pending Edge login with that `pendingId`."><span class="st">404</span>PENDING_LOGIN_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Session creation is attempted once. A failure is sticky, so later polls report the same <code>error</code> rather than retrying.</li><li>Polling does not extend the handle TTL; only the original 5 minute window applies.</li></ul></div>
+  </section><section class="endpoint" id="cancelEdgeLogin">
+    <header>
+      <h3><a href="#cancelEdgeLogin">Cancel a pending QR login.</a></h3>
+      <div class="ids"><code class="cmdname">cancel-request</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>EdgePendingEdgeLogin.cancelRequest</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>cancel-request &lt;pendingId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/pending-edge-login/cancel-request/{pendingId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>pendingId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">The <code>pendingId</code> returned when the QR login was requested.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/pending-edge-login/cancel-request/$PENDINGID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-PENDING_LOGIN_NOT_FOUND" class="err" title="No pending Edge login with that `pendingId`."><span class="st">404</span>PENDING_LOGIN_NOT_FOUND</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>If the login already completed and a session exists, that session is force-logged-out too, so cancelling cannot leave an orphan visible in <code>engine-sessions</code>.</li></ul></div>
+  </section><section class="endpoint" id="engineSessions">
+    <header>
+      <h3><a href="#engineSessions">List active sessions.</a></h3>
+      <div class="ids"><code class="cmdname">engine-sessions</code><span class="src" title="Declared in">src/cli/engine/routes/login.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>The session registry is an engine construct; core has no multi-account session concept.</em></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>engine-sessions</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/engine/sessions</code></p>
+    
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/engine/sessions'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>A bare array, not wrapped in a key. Each <code>sessionId</code> is truncated: this route needs no session, so a usable id here would be a credential anyone who can reach the engine could collect.</p>
+</div><pre class="ts"><code>{
+  sessionId: string;
+  username: string | undefined;
+  rootLoginId: string;
+  loginMethod: &quot;password&quot; | &quot;pin&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;create&quot; | &quot;recovery&quot;;
+  autoLogoutSeconds: number;
+  expiresAt: string | null;
+  lastActivityAt: string;
+  createdAt: string
+}[]</code></pre>
+    
+  </div>
+    
+  </section><h2 id="account">Account</h2>
+      <div class="groupdoc"><p>Calls on a logged-in <code>EdgeAccount</code>, addressed by <code>sessionId</code>. All of these can also return <code>401 INVALID_SESSION</code> or <code>401 SESSION_EXPIRED</code>.</p>
+</div>
+      <h3 class="sub" id="account">Session</h3>
+          <div class="groupdoc"><p>Calls on a logged-in <code>EdgeAccount</code>, addressed by <code>sessionId</code>. All of these can also return <code>401 INVALID_SESSION</code> or <code>401 SESSION_EXPIRED</code>.</p>
+</div>
+          <section class="endpoint" id="accountInfo">
+    <header>
+      <h3><a href="#accountInfo">Account and session summary.</a></h3>
+      <div class="ids"><code class="cmdname">account-info</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine composite of the session record plus EdgeAccount properties.</em></p>
+    <div class="desc"><p>Session fields are spread at the top level alongside the account&#39;s own properties — there is no nested <code>session</code> object.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>account-info</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  appId: string
+  created: string | null
+  lastLogin: string
+  loggedIn: boolean
+  recoveryKey: string | null
+  otpEnabled: boolean
+  otpResetPending: boolean
+  canDuressLogin: boolean
+  isDuressAccount: boolean
+  edgeLogin: boolean
+  keyLogin: boolean
+  newAccount: boolean
+  passwordLogin: boolean
+  pinLogin: boolean
+  recoveryLogin: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;appId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;created&quot;: &quot;string&quot;,
+  &quot;lastLogin&quot;: &quot;string&quot;,
+  &quot;loggedIn&quot;: true,
+  &quot;recoveryKey&quot;: &quot;string&quot;,
+  &quot;otpEnabled&quot;: true,
+  &quot;otpResetPending&quot;: true,
+  &quot;canDuressLogin&quot;: true,
+  &quot;isDuressAccount&quot;: true,
+  &quot;edgeLogin&quot;: true,
+  &quot;keyLogin&quot;: true,
+  &quot;newAccount&quot;: true,
+  &quot;passwordLogin&quot;: true,
+  &quot;pinLogin&quot;: true,
+  &quot;recoveryLogin&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>appId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Application this session logged into.</td>
+</tr>
+<tr>
+  <td class="k"><code>created</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When the account was created, null for accounts predating the field.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastLogin</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The previous login, not this one.</td>
+</tr>
+<tr>
+  <td class="k"><code>loggedIn</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">False once the account has been logged out; the session object outlives it briefly.</td>
+</tr>
+<tr>
+  <td class="k"><code>recoveryKey</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Present only while recovery is configured.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpEnabled</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">2FA is on for this account.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpResetPending</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True while somebody has a reset pending against this account.</td>
+</tr>
+<tr>
+  <td class="k"><code>canDuressLogin</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">A duress PIN is configured, so this account can be opened in duress mode.</td>
+</tr>
+<tr>
+  <td class="k"><code>isDuressAccount</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True when this very session is the duress account rather than the real one.</td>
+</tr>
+<tr>
+  <td class="k"><code>edgeLogin</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">This account was reached by QR login.</td>
+</tr>
+<tr>
+  <td class="k"><code>keyLogin</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">This session was reached with a login key.</td>
+</tr>
+<tr>
+  <td class="k"><code>newAccount</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">This session created the account rather than logging into an existing one.</td>
+</tr>
+<tr>
+  <td class="k"><code>passwordLogin</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">This session was reached with a password.</td>
+</tr>
+<tr>
+  <td class="k"><code>pinLogin</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">This session was reached with a PIN.</td>
+</tr>
+<tr>
+  <td class="k"><code>recoveryLogin</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">This session was reached by answering recovery questions.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The <code>otpEnabled</code> and <code>otpResetPending</code> flags here are derived. For the secret itself use <code>otp-key</code>.</li></ul></div>
+  </section><section class="endpoint" id="logout">
+    <header>
+      <h3><a href="#logout">Log out.</a></h3>
+      <div class="ids"><code class="cmdname">logout</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.logout</code></p>
+    <div class="desc"><p>Ends the session and drops it from the engine. Any subscription scoped to this account or its wallets is closed with it.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>logout</code></pre>
+    
+    
+    <div class="note"><p>Also clears the stored id from <code>session.json</code>.</p>
+</div>
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/logout</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/logout'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="touchSession">
+    <header>
+      <h3><a href="#touchSession">Keepalive.</a></h3>
+      <div class="ids"><code class="cmdname">touch</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine auto-logout timer; core has no idle concept.</em></p>
+    <div class="desc"><p>Resets the idle auto-logout timer without doing any other work.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>touch</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/touch</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/touch'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The session, with a refreshed <code>expiresAt</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  sessionId: string
+  username?: string
+  rootLoginId: string
+  loginMethod: &quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;rootLoginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginMethod&quot;: &quot;&lt;\&quot;create\&quot;&gt;&quot;,
+  &quot;autoLogoutSeconds&quot;: 1,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lastActivityAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.</td>
+</tr>
+<tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Absent for a light account, which has no username.</td>
+</tr>
+<tr>
+  <td class="k"><code>rootLoginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account root, stable across appIds. Two sessions sharing it are the same account.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginMethod</code></td>
+  <td class="ty"><span class="t">&quot;create&quot; | &quot;edge&quot; | &quot;key&quot; | &quot;password&quot; | &quot;pin&quot; | &quot;recovery&quot;</span></td>
+  <td class="doc">How this session was established.</td>
+</tr>
+<tr>
+  <td class="k"><code>autoLogoutSeconds</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Idle time before the engine logs the account out. 0 disables it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When auto-logout will fire, or null when it is disabled.</td>
+</tr>
+<tr>
+  <td class="k"><code>lastActivityAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Last call on this session, which is what auto-logout measures from.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the login completed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getLoginKey">
+    <header>
+      <h3><a href="#getLoginKey">Read the account login key.</a></h3>
+      <div class="ids"><code class="cmdname">get-login-key</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getLoginKey</code></p>
+    <div class="desc"><p>The key <code>login-with-key</code> takes. It grants full account access, so treat the output as secret.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-login-key</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-login-key</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-login-key'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  loginKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;loginKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>loginKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">base58. Full account access — keep it safe.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="accountSync">
+    <header>
+      <h3><a href="#accountSync">Force an account data sync.</a></h3>
+      <div class="ids"><code class="cmdname">sync</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.sync</code></p>
+    <div class="desc"><p>Pushes and pulls the account repos immediately rather than waiting for the next scheduled sync.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>sync</code></pre>
+    
+    
+    <div class="note"><p>Named <code>sync</code> for the account; the wallet one is <code>wallet-sync</code>.</p>
+</div>
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/sync</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/sync'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="deleteRemoteAccount">
+    <header>
+      <h3><a href="#deleteRemoteAccount">Permanently delete the remote account.</a></h3>
+      <div class="ids"><code class="cmdname">delete-remote-account</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.deleteRemoteAccount</code></p>
+    <div class="desc"><p>Irreversible. The account is removed from the login server, and funds in its wallets are unrecoverable without the keys. The session is logged out afterwards.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>delete-remote-account --yes</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--yes</code></td><td class="ty"><span class="flag req">required</span></td><td class="doc">Confirms intent. Without it the command refuses to run.</td></tr></tbody></table>
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/delete-remote-account</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/delete-remote-account'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The engine performs no confirmation check — the call runs as soon as it arrives, so any guard has to live in the caller. The command requires <code>--yes</code> for exactly this reason.</li></ul></div>
+  </section><section class="endpoint" id="waitForAllWallets">
+    <header>
+      <h3><a href="#waitForAllWallets">Wait for every wallet to finish loading.</a></h3>
+      <div class="ids"><code class="cmdname">wait-for-all-wallets</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.waitForAllWallets</code></p>
+    <div class="desc"><p>Wallets load in the background after login, so a list taken straight afterwards can be short. This resolves once each active wallet has either loaded or failed — balances may still be syncing afterwards.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>wait-for-all-wallets</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wait-for-all-wallets</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/wait-for-all-wallets'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>There is no timeout: a wallet that never resolves holds this open. The engine&#39;s own idle shutdown does not fire while a request is in flight, so give the client one.</li><li>Nothing is returned. Call <code>currency-wallets</code> afterwards to see the result, including any wallet that failed to load.</li></ul></div>
+  </section><section class="endpoint" id="currencyWallets">
+    <header>
+      <h3><a href="#currencyWallets">List the account's wallets.</a></h3>
+      <div class="ids"><code class="cmdname">currency-wallets</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.currencyWallets</code> <span class="dim">Filtered by account.activeWalletIds / archivedWalletIds / hiddenWalletIds.</span></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>filter</code> — Core has no filter: it exposes activeWalletIds, archivedWalletIds and hiddenWalletIds as separate lists. This picks between them.</li></ul></div>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>currency-wallets [--filter=active|all|archived|hidden]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/currency-wallets</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  filter?: &quot;active&quot; | &quot;all&quot; | &quot;archived&quot; | &quot;hidden&quot;
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;filter&quot;: &quot;&lt;\&quot;active\&quot;&gt;&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>filter</code></td>
+  <td class="ty"><span class="t">&quot;active&quot; | &quot;all&quot; | &quot;archived&quot; | &quot;hidden&quot;</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Which of the account’s wallet lists to read. Defaults to <code>active</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/currency-wallets'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  currencyWallets: {
+    walletId: string;
+    id: string;
+    type: string;
+    name: string | null;
+    pluginId: string;
+    currencyCode: string;
+    fiatCurrencyCode: string;
+    blockHeight: number;
+    syncStatus: unknown;
+    syncRatio: string | undefined;
+    paused: boolean;
+    imported: boolean | undefined;
+    created: string | null;
+    enabledTokenIds: string[];
+    detectedTokenIds: string[];
+    unactivatedTokenIds: string[]
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;currencyWallets&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>currencyWallets</code></td>
+  <td class="ty"><span class="t">{ walletId: string; id: string; type: string; name: string | null; pluginId: string; currencyCode: string; fiatCurrencyCode: string; blockHeight: number; syncStatus: unknown; syncRatio: string | undefined; paused: boolean; imported: boolean | undefined; created: string | null; enabledTokenIds: string[]; detectedTokenIds: string[]; unactivatedTokenIds: string[]; }[]</span></td>
+  <td class="doc">Every wallet in the account, including paused ones.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Wallets load in the background after login, so a list taken straight afterwards can be short. Call <code>wait-for-all-wallets</code> first to be sure the account has finished loading.</li></ul></div>
+  </section><section class="endpoint" id="createCurrencyWallet">
+    <header>
+      <h3><a href="#createCurrencyWallet">Create a currency wallet.</a></h3>
+      <div class="ids"><code class="cmdname">create-currency-wallet</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.createCurrencyWallet</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>create-currency-wallet --wallet-type=&lt;walletType&gt; [--name=&lt;name&gt;] [--import-text=&lt;importText&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/create-currency-wallet</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletType: string
+  name?: string
+  importText?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletType&quot;: &quot;string&quot;,
+  &quot;name&quot;: &quot;string&quot;,
+  &quot;importText&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletType</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>currency-configs</code>, e.g. <code>wallet:bitcoin</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>name</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Display name.</td>
+</tr>
+<tr>
+  <td class="k"><code>importText</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Seed or key text to import instead of generating.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletType&quot;:&quot;string&quot;,&quot;name&quot;:&quot;string&quot;,&quot;importText&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/create-currency-wallet'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  id: string
+  type: string
+  name: string | null
+  pluginId: string
+  currencyCode: string
+  fiatCurrencyCode: string
+  blockHeight: number
+  syncStatus: unknown
+  syncRatio?: string
+  paused: boolean
+  imported?: boolean
+  created: string | null
+  enabledTokenIds: string[]
+  detectedTokenIds: string[]
+  unactivatedTokenIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;id&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;type&quot;: &quot;string&quot;,
+  &quot;name&quot;: &quot;string&quot;,
+  &quot;pluginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;currencyCode&quot;: &quot;string&quot;,
+  &quot;fiatCurrencyCode&quot;: &quot;string&quot;,
+  &quot;blockHeight&quot;: 1,
+  &quot;syncStatus&quot;: {},
+  &quot;syncRatio&quot;: &quot;string&quot;,
+  &quot;paused&quot;: true,
+  &quot;imported&quot;: true,
+  &quot;created&quot;: &quot;string&quot;,
+  &quot;enabledTokenIds&quot;: [
+    &quot;string&quot;
+  ],
+  &quot;detectedTokenIds&quot;: [
+    &quot;string&quot;
+  ],
+  &quot;unactivatedTokenIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The full wallet id. Commands taking a wallet accept any unique prefix.</td>
+</tr>
+<tr>
+  <td class="k"><code>id</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Same value as <code>walletId</code>; core exposes both names.</td>
+</tr>
+<tr>
+  <td class="k"><code>type</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Key type, such as <code>wallet:bitcoin</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>name</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">User-assigned name, null until one is set.</td>
+</tr>
+<tr>
+  <td class="k"><code>pluginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Currency plugin backing this wallet.</td>
+</tr>
+<tr>
+  <td class="k"><code>currencyCode</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Ticker for the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>fiatCurrencyCode</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Fiat the wallet reports value in, as <code>iso:USD</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>blockHeight</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Chain height this wallet has seen.</td>
+</tr>
+<tr>
+  <td class="k"><code>syncStatus</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc"><code>EdgeWalletSyncStatus</code> from core.</td>
+</tr>
+<tr>
+  <td class="k"><code>syncRatio</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Sync progress as a percentage, for display.</td>
+</tr>
+<tr>
+  <td class="k"><code>paused</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True while the engine is not syncing this wallet.</td>
+</tr>
+<tr>
+  <td class="k"><code>imported</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">True when the keys came from an import rather than being generated here.</td>
+</tr>
+<tr>
+  <td class="k"><code>created</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When the wallet was created, null for wallets predating the field.</td>
+</tr>
+<tr>
+  <td class="k"><code>enabledTokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Tokens the user turned on.</td>
+</tr>
+<tr>
+  <td class="k"><code>detectedTokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Tokens found on-chain that are not enabled yet.</td>
+</tr>
+<tr>
+  <td class="k"><code>unactivatedTokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Enabled tokens still awaiting on-chain activation.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The fiat currency is not set here. Core still accepts it on create, but that path is deprecated — use <code>set-fiat-currency-code</code> afterwards, so there is one way to do it.</li></ul></div>
+  </section><section class="endpoint" id="createCurrencyWallets">
+    <header>
+      <h3><a href="#createCurrencyWallets">Create several wallets at once.</a></h3>
+      <div class="ids"><code class="cmdname">create-currency-wallets</code><span class="src" title="Declared in">src/cli/engine/routes/account.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.createCurrencyWallets</code></p>
+    <div class="desc"><p>Partial success is normal: each entry reports its own outcome, and one failure does not roll back the others.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>create-currency-wallets --create-wallets='&lt;json&gt;'</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/create-currency-wallets</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  createWallets: {
+    walletType: string;
+    name: string | undefined;
+    fiatCurrencyCode: string | undefined
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;createWallets&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>createWallets</code></td>
+  <td class="ty"><span class="t">{ walletType: string; name: string | undefined; fiatCurrencyCode: string | undefined; }[]</span></td>
+  <td class="doc"><code>EdgeCreateCurrencyWallet[]</code>: walletType, plus optional name and fiatCurrencyCode.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;createWallets&quot;:[{}]}' \
+  'http://localhost/account/$SESS/create-currency-wallets'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  results: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;results&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>results</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc">Mirrors core’s EdgeResult[]: <code>{ ok, wallet }</code> or <code>{ ok: false, error }</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="credentials">Credentials</h3>
+          <div class="groupdoc"><p>Password, PIN, username and recovery changes on a logged-in account.</p>
+</div>
+          <section class="endpoint" id="changePassword">
+    <header>
+      <h3><a href="#changePassword">Set or change the password.</a></h3>
+      <div class="ids"><code class="cmdname">change-password</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.changePassword</code></p>
+    <div class="desc"><p>The login server enforces its own rules; <code>check-password-rules</code> scores a candidate first.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-password --password=&lt;password&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/change-password</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  password: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;password&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>password</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The new password.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;password&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/change-password'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="deletePassword">
+    <header>
+      <h3><a href="#deletePassword">Remove password login.</a></h3>
+      <div class="ids"><code class="cmdname">delete-password</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.deletePassword</code></p>
+    <div class="desc"><p>The account keeps its other login methods; only the password stops working.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>delete-password</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/delete-password</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/delete-password'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="checkPassword">
+    <header>
+      <h3><a href="#checkPassword">Verify a password.</a></h3>
+      <div class="ids"><code class="cmdname">check-password</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.checkPassword</code></p>
+    <div class="desc"><p>Checks without changing anything, which is how a caller gates a destructive action behind a re-entry prompt.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>check-password --password=&lt;password&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/check-password</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  password: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;password&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>password</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The account password.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;password&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/check-password'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">False for a wrong password — not an error response.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getPin">
+    <header>
+      <h3><a href="#getPin">Read the account PIN.</a></h3>
+      <div class="ids"><code class="cmdname">get-pin</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getPin</code></p>
+    <div class="desc"><p>Returns the PIN itself, not a status flag, so treat the output as secret.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-pin</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-pin</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-pin'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  pin: string | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pin&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pin</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Null when no PIN is set.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changePin">
+    <header>
+      <h3><a href="#changePin">Set or change the PIN.</a></h3>
+      <div class="ids"><code class="cmdname">change-pin</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.changePin</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-pin --pin=&lt;pin&gt; [--enable-login[=false]] [--for-duress-account[=false]]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/change-pin</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  pin: string
+  enableLogin?: boolean
+  forDuressAccount?: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pin&quot;: &quot;string&quot;,
+  &quot;enableLogin&quot;: true,
+  &quot;forDuressAccount&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pin</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The new PIN.</td>
+</tr>
+<tr>
+  <td class="k"><code>enableLogin</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Allow logging in with this PIN on this device.</td>
+</tr>
+<tr>
+  <td class="k"><code>forDuressAccount</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Act on the duress account rather than the real one.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;pin&quot;:&quot;string&quot;,&quot;enableLogin&quot;:true,&quot;forDuressAccount&quot;:true}' \
+  'http://localhost/account/$SESS/change-pin'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  pin2Key: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pin2Key&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pin2Key</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The new PIN login key core returns.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="deletePin">
+    <header>
+      <h3><a href="#deletePin">Remove the PIN.</a></h3>
+      <div class="ids"><code class="cmdname">delete-pin</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.deletePin</code></p>
+    <div class="desc"><p>PIN login stops working on this device; other methods are untouched.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>delete-pin</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/delete-pin</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/delete-pin'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="checkPin">
+    <header>
+      <h3><a href="#checkPin">Verify a PIN.</a></h3>
+      <div class="ids"><code class="cmdname">check-pin</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.checkPin</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>check-pin --pin=&lt;pin&gt; [--for-duress-account[=false]]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/check-pin</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  pin: string
+  forDuressAccount?: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pin&quot;: &quot;string&quot;,
+  &quot;forDuressAccount&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pin</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The device PIN, usually four digits.</td>
+</tr>
+<tr>
+  <td class="k"><code>forDuressAccount</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Act on the duress account rather than the real one.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;pin&quot;:&quot;string&quot;,&quot;forDuressAccount&quot;:true}' \
+  'http://localhost/account/$SESS/check-pin'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">False for a wrong PIN — not an error response.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changeUsername">
+    <header>
+      <h3><a href="#changeUsername">Change the username.</a></h3>
+      <div class="ids"><code class="cmdname">change-username</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.changeUsername</code></p>
+    <div class="desc"><p>The old name is released, so it becomes available to anyone else.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-username --username=&lt;username&gt; [--password=&lt;password&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/change-username</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  username: string
+  password?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;,
+  &quot;password&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The new username.</td>
+</tr>
+<tr>
+  <td class="k"><code>password</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Required by core when the account has a password.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;username&quot;:&quot;string&quot;,&quot;password&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/change-username'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-USERNAME_ERROR" class="err" title="Unknown username, or an invalid recovery key."><span class="st">400</span>USERNAME_ERROR</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changeRecovery">
+    <header>
+      <h3><a href="#changeRecovery">Set recovery questions and answers.</a></h3>
+      <div class="ids"><code class="cmdname">change-recovery</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.changeRecovery</code> <span class="dim">Our surface drops the <code>2</code> from core&#39;s recovery2 naming; a future Recovery1 would be suffixed <code>V1</code>.</span></p>
+    <div class="desc"><p>The returned key is half of the credential: without it the answers alone cannot recover the account, so it has to be stored somewhere else.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-recovery --question=&lt;questions&gt; … --answer=&lt;answers&gt; …</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/change-recovery</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  questions: string[]
+  answers: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;questions&quot;: [
+    &quot;string&quot;
+  ],
+  &quot;answers&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>questions</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">The questions to ask.</td>
+</tr>
+<tr>
+  <td class="k"><code>answers</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Same length and order as <code>questions</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;questions&quot;:[&quot;string&quot;],&quot;answers&quot;:[&quot;string&quot;]}' \
+  'http://localhost/account/$SESS/change-recovery'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  recoveryKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;recoveryKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>recoveryKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Store this out of band. <code>login-with-recovery</code> needs it alongside the answers.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="deleteRecovery">
+    <header>
+      <h3><a href="#deleteRecovery">Disable recovery login.</a></h3>
+      <div class="ids"><code class="cmdname">delete-recovery</code><span class="src" title="Declared in">src/cli/engine/routes/credentials.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.deleteRecovery</code></p>
+    <div class="desc"><p>The existing recovery key stops working.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>delete-recovery</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/delete-recovery</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/delete-recovery'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="otp">Two-factor authentication</h3>
+          <div class="groupdoc"><p>OTP state and the reset flow a user falls back on after losing their authenticator.</p>
+</div>
+          <section class="endpoint" id="otpKey">
+    <header>
+      <h3><a href="#otpKey">Read the 2FA secret and reset state.</a></h3>
+      <div class="ids"><code class="cmdname">otp-key</code><span class="src" title="Declared in">src/cli/engine/routes/otp.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.otpKey</code> <span class="dim">Also carries account.otpResetDate.</span></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>otp-key</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/otp-key</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/otp-key'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  otpKey: string | null
+  otpResetDate: string | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otpKey&quot;: &quot;string&quot;,
+  &quot;otpResetDate&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Null when 2FA is off. The 2FA secret itself. Secret material — record it safely.</td>
+</tr>
+<tr>
+  <td class="k"><code>otpResetDate</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Set once somebody has requested a reset; cancel it with <code>cancel-otp-reset</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="enableOtp">
+    <header>
+      <h3><a href="#enableOtp">Enable 2FA.</a></h3>
+      <div class="ids"><code class="cmdname">enable-otp</code><span class="src" title="Declared in">src/cli/engine/routes/otp.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.enableOtp</code></p>
+    <div class="desc"><p>Record the returned key before leaving the terminal: it is the only copy.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>enable-otp [--timeout=&lt;timeout&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/enable-otp</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  timeout?: number
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;timeout&quot;: 0
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>timeout</code></td>
+  <td class="ty"><span class="t">number</span> <span class="flag opt">optional</span></td>
+  <td class="doc">How long a reset request must wait before it completes, in seconds. Core supplies the default when omitted.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;timeout&quot;:0}' \
+  'http://localhost/account/$SESS/enable-otp'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  otpKey: string | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otpKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">The new secret. The 2FA secret itself. Secret material — record it safely.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="disableOtp">
+    <header>
+      <h3><a href="#disableOtp">Disable 2FA.</a></h3>
+      <div class="ids"><code class="cmdname">disable-otp</code><span class="src" title="Declared in">src/cli/engine/routes/otp.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.disableOtp</code></p>
+    <div class="desc"><p>Logins stop requiring a code immediately.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>disable-otp</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/disable-otp</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/disable-otp'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="cancelOtpReset">
+    <header>
+      <h3><a href="#cancelOtpReset">Cancel a pending 2FA reset.</a></h3>
+      <div class="ids"><code class="cmdname">cancel-otp-reset</code><span class="src" title="Declared in">src/cli/engine/routes/otp.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.cancelOtpReset</code></p>
+    <div class="desc"><p>The defence against somebody else requesting a reset on your account: as long as you cancel before the timer runs out, their reset never lands.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>cancel-otp-reset</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/cancel-otp-reset</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/cancel-otp-reset'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="repairOtp">
+    <header>
+      <h3><a href="#repairOtp">Re-point the account at a known 2FA secret.</a></h3>
+      <div class="ids"><code class="cmdname">repair-otp</code><span class="src" title="Declared in">src/cli/engine/routes/otp.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.repairOtp</code></p>
+    <div class="desc"><p>For a device whose stored secret has drifted from the server&#39;s.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>repair-otp --otp-key=&lt;otpKey&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/repair-otp</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  otpKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;otpKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>otpKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The secret the account should use.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;otpKey&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/repair-otp'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-OTP_REQUIRED" class="err" title="Missing or wrong 2FA token."><span class="st">401</span>OTP_REQUIRED</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="vouchers">Vouchers</h3>
+          <div class="groupdoc"><p>When 2FA blocks a login, the login server issues a voucher an already-trusted device can approve or reject.</p>
+</div>
+          <section class="endpoint" id="pendingVouchers">
+    <header>
+      <h3><a href="#pendingVouchers">List pending 2FA vouchers.</a></h3>
+      <div class="ids"><code class="cmdname">pending-vouchers</code><span class="src" title="Declared in">src/cli/engine/routes/vouchers.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.pendingVouchers</code></p>
+    <div class="desc"><p>When 2FA blocks a login, the login server issues a voucher that an already-trusted device can approve or reject.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>pending-vouchers</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/pending-vouchers</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/pending-vouchers'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  pendingVouchers: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;pendingVouchers&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>pendingVouchers</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc"><code>EdgePendingVoucher[]</code>: voucherId, activates, created, deviceDescription, ipDescription.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="approveVoucher">
+    <header>
+      <h3><a href="#approveVoucher">Approve a voucher.</a></h3>
+      <div class="ids"><code class="cmdname">approve-voucher</code><span class="src" title="Declared in">src/cli/engine/routes/vouchers.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.approveVoucher</code></p>
+    <div class="desc"><p>Lets the waiting device finish logging in.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>approve-voucher --voucher-id=&lt;voucherId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/approve-voucher</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  voucherId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;voucherId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>voucherId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>pending-vouchers</code>, or an <code>OTP_REQUIRED</code> error’s <code>details.voucherId</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;voucherId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/approve-voucher'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="rejectVoucher">
+    <header>
+      <h3><a href="#rejectVoucher">Reject a voucher.</a></h3>
+      <div class="ids"><code class="cmdname">reject-voucher</code><span class="src" title="Declared in">src/cli/engine/routes/vouchers.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.rejectVoucher</code></p>
+    <div class="desc"><p>Denies the waiting device. The login it was issued for cannot complete.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>reject-voucher --voucher-id=&lt;voucherId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/reject-voucher</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  voucherId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;voucherId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>voucherId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">From <code>pending-vouchers</code>, or an <code>OTP_REQUIRED</code> error’s <code>details.voucherId</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;voucherId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/reject-voucher'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="lobby">Approving a login</h3>
+          <div class="groupdoc"><p>The other side of <code>request-edge-login</code>: a logged-in account inspecting and approving a login somebody scanned.</p>
+</div>
+          <section class="endpoint" id="fetchLobby">
+    <header>
+      <h3><a href="#fetchLobby">Inspect a login request.</a></h3>
+      <div class="ids"><code class="cmdname">fetch-lobby</code><span class="src" title="Declared in">src/cli/engine/routes/lobby.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.fetchLobby</code></p>
+    <div class="desc"><p>The other side of <code>request-edge-login</code>: shows who is asking, so a human can decide before approving.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>fetch-lobby &lt;lobbyId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/fetch-lobby/{lobbyId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>lobbyId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From the QR code, or an <code>edge://edge/&lt;lobbyId&gt;</code> link.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/fetch-lobby/$LOBBYID?lobbyId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  lobbyId: string
+  loginRequest: {
+    appId: string;
+    displayName: string;
+    displayImageDarkUrl: string | null;
+    displayImageLightUrl: string | null
+  } | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;lobbyId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;loginRequest&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>lobbyId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The lobby that was fetched, echoed back.</td>
+</tr>
+<tr>
+  <td class="k"><code>loginRequest</code></td>
+  <td class="ty"><span class="t">{ appId: string; displayName: string; displayImageDarkUrl: string | null; displayImageLightUrl: string | null; } | null</span></td>
+  <td class="doc">Null when the lobby carries no pending login request.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="approveLoginRequest">
+    <header>
+      <h3><a href="#approveLoginRequest">Approve a login request.</a></h3>
+      <div class="ids"><code class="cmdname">approve-login-request</code><span class="src" title="Declared in">src/cli/engine/routes/lobby.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>EdgeLoginRequest.approve</code> <span class="dim">Reached through account.fetchLobby(lobbyId).loginRequest.</span></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>lobbyId</code> — Core calls approve() on a request object. Over HTTP there is no object to hold, so the lobby names which one to approve.</li></ul></div>
+    <div class="desc"><p>Grants the requesting device access to this account.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>approve-login-request &lt;lobbyId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/approve-login-request/{lobbyId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>lobbyId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From the QR code, or an <code>edge://edge/&lt;lobbyId&gt;</code> link.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;lobbyId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/approve-login-request/$LOBBYID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Always true; a failure arrives as an error envelope.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-NO_LOGIN_REQUEST" class="err" title="The lobby exists but carries no pending login request."><span class="st">404</span>NO_LOGIN_REQUEST</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The lobby is re-fetched on approve, so a request that expired between inspecting and approving fails with <code>404 NO_LOGIN_REQUEST</code>.</li></ul></div>
+  </section><h3 class="sub" id="keys">Keys</h3>
+          <div class="groupdoc"><p>Raw key infrastructure beneath the wallet API. Several of these return private key material, and the engine has no transport auth — treat any process that can reach the socket as fully trusted.</p>
+</div>
+          <section class="endpoint" id="allKeys">
+    <header>
+      <h3><a href="#allKeys">List every key in the account.</a></h3>
+      <div class="ids"><code class="cmdname">all-keys</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.allKeys</code></p>
+    <div class="desc"><p>Includes archived and deleted keys, unlike <code>currency-wallets</code>.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>all-keys</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/all-keys</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/all-keys'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  allKeys: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;allKeys&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>allKeys</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc"><code>EdgeWalletInfoFull[]</code>: id, type, keys, archived, deleted, hidden, sortIndex.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="createWallet">
+    <header>
+      <h3><a href="#createWallet">Create a wallet from raw key JSON.</a></h3>
+      <div class="ids"><code class="cmdname">create-wallet</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.createWallet</code></p>
+    <div class="desc"><p>The import path. Use <code>create-currency-wallet</code> to make a fresh wallet with generated keys.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>create-wallet --type=&lt;type&gt; [--keys='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/create-wallet</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  type: string
+  keys?: {
+    [keys: string]: unknown
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;type&quot;: &quot;string&quot;,
+  &quot;keys&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>type</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Wallet type, e.g. <code>wallet:bitcoin</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>keys</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Plugin key material. Omit to let core generate it.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;type&quot;:&quot;string&quot;,&quot;keys&quot;:{}}' \
+  'http://localhost/account/$SESS/create-wallet'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The new wallet. Its keys are already saved.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getWalletInfo">
+    <header>
+      <h3><a href="#getWalletInfo">Read one wallet's key info.</a></h3>
+      <div class="ids"><code class="cmdname">get-wallet-info</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getWalletInfo</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-wallet-info --id=&lt;id&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-wallet-info</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  id: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;id&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>id</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The key id, from <code>all-keys</code>. Base64, like a wallet id.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-wallet-info?id=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>EdgeWalletInfoFull</code>, verbatim from core — including the <code>keys</code> object.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>An exact lookup: unlike the wallet-scoped routes this does not accept an id prefix.</li></ul></div>
+  </section><section class="endpoint" id="getRawPrivateKey">
+    <header>
+      <h3><a href="#getRawPrivateKey">Read raw private key material.</a></h3>
+      <div class="ids"><code class="cmdname">get-raw-private-key</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getRawPrivateKey</code></p>
+    <div class="desc"><p>Secret. Whatever the plugin stores — seed, mnemonic, xpriv.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-raw-private-key --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-raw-private-key</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-raw-private-key?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The plugin’s key object, at the top level.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getRawPublicKey">
+    <header>
+      <h3><a href="#getRawPublicKey">Read raw public key material.</a></h3>
+      <div class="ids"><code class="cmdname">get-raw-public-key</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getRawPublicKey</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-raw-public-key --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-raw-public-key</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-raw-public-key?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The plugin’s public key object.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getDisplayPrivateKey">
+    <header>
+      <h3><a href="#getDisplayPrivateKey">Export the private key for display.</a></h3>
+      <div class="ids"><code class="cmdname">get-display-private-key</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getDisplayPrivateKey</code></p>
+    <div class="desc"><p>Secret. The human-facing form — WIF, seed phrase, whatever the plugin shows on its export screen.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-display-private-key --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-display-private-key</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-display-private-key?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  key: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;key&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>key</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The displayable private key.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getDisplayPublicKey">
+    <header>
+      <h3><a href="#getDisplayPublicKey">Export the public key for display.</a></h3>
+      <div class="ids"><code class="cmdname">get-display-public-key</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.getDisplayPublicKey</code></p>
+    <div class="desc"><p>The xpub or equivalent — safe to share for watch-only use.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-display-public-key --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-display-public-key</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-display-public-key?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  key: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;key&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>key</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The displayable public key.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="listSplittableWalletTypes">
+    <header>
+      <h3><a href="#listSplittableWalletTypes">List chains a wallet can split into.</a></h3>
+      <div class="ids"><code class="cmdname">list-splittable-wallet-types</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.listSplittableWalletTypes</code></p>
+    <div class="desc"><p>Forked-chain support: which wallet types can be derived from these keys.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>list-splittable-wallet-types --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/list-splittable-wallet-types</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/list-splittable-wallet-types?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  walletTypes: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletTypes&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletTypes</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Types valid for <code>split</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changeWalletStates">
+    <header>
+      <h3><a href="#changeWalletStates">Archive, delete, hide, or reorder wallets.</a></h3>
+      <div class="ids"><code class="cmdname">change-wallet-states</code><span class="src" title="Declared in">src/cli/engine/routes/keys.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.changeWalletStates</code></p>
+    <div class="desc"><p>The canonical backend for every wallet flag; there are no separate archive, unarchive or undelete verbs.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-wallet-states [--wallet-states='&lt;json&gt;'] --wallet-id=&lt;value&gt; [--archived=&lt;value&gt;] [--deleted=&lt;value&gt;] [--hidden=&lt;value&gt;] [--sort-index=&lt;value&gt;]</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--wallet-id</code></td><td class="ty"><span class="flag req">required</span></td><td class="doc">The wallet to change. The command makes it the key of a single-entry <code>walletStates</code> map.</td></tr><tr><td class="k"><code>--archived</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Hide from the active list.</td></tr><tr><td class="k"><code>--deleted</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Mark deleted.</td></tr><tr><td class="k"><code>--hidden</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Hide from the wallet picker.</td></tr><tr><td class="k"><code>--sort-index</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Position in the wallet list.</td></tr></tbody></table>
+    <div class="note"><p>The command builds a single-wallet <code>walletStates</code> map from these flags, and needs at least one.</p>
+</div>
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/change-wallet-states</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletStates?: {
+    [keys: string]: {
+      archived: boolean | undefined;
+      deleted: boolean | undefined;
+      hidden: boolean | undefined;
+      sortIndex: number | undefined
+    }
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletStates&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletStates</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: { archived: boolean | undefined; deleted: boolean | undefined; hidden: boolean | undefined; sortIndex: number | undefined; }; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc"><code>EdgeWalletStates</code>: wallet ids to the flags being changed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletStates&quot;:{}}' \
+  'http://localhost/account/$SESS/change-wallet-states'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="swap">Swap quotes</h3>
+          <div class="groupdoc"><p>Cross-asset exchange. Quotes are live objects held server-side under a <code>swap_</code> handle, so approving one means naming its <code>objectId</code> rather than re-uploading the quote.</p>
+</div>
+          <section class="endpoint" id="fetchSwapQuotes">
+    <header>
+      <h3><a href="#fetchSwapQuotes">Fetch swap quotes.</a></h3>
+      <div class="ids"><code class="cmdname">fetch-swap-quotes</code><span class="src" title="Declared in">src/cli/engine/routes/swap.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.fetchSwapQuotes</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>fromWalletId</code> — Core takes the wallet object; over HTTP it is an id.</li><li><code>toWalletId</code> — Core takes the wallet object; over HTTP it is an id.</li></ul></div>
+    <div class="desc"><p>Polls every enabled swap plugin and parks each result under its own <code>swap_</code> handle with a 5 minute TTL.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>fetch-swap-quotes --from-wallet-id=&lt;fromWalletId&gt; --to-wallet-id=&lt;toWalletId&gt; --native-amount=&lt;nativeAmount&gt; [--from-token-id=&lt;fromTokenId&gt;] [--to-token-id=&lt;toTokenId&gt;] [--quote-for=from|max|to] [--plugin-id=&lt;preferPluginId&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/fetch-swap-quotes</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  fromWalletId: string
+  toWalletId: string
+  nativeAmount: string
+  fromTokenId?: string | null
+  toTokenId?: string | null
+  quoteFor?: &quot;from&quot; | &quot;max&quot; | &quot;to&quot;
+  preferPluginId?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;fromWalletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;toWalletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;nativeAmount&quot;: &quot;12345&quot;,
+  &quot;fromTokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;toTokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;quoteFor&quot;: &quot;&lt;\&quot;from\&quot;&gt;&quot;,
+  &quot;preferPluginId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>fromWalletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Source wallet. Accepts a unique prefix.</td>
+</tr>
+<tr>
+  <td class="k"><code>toWalletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Destination wallet.</td>
+</tr>
+<tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">How much, in native units.</td>
+</tr>
+<tr>
+  <td class="k"><code>fromTokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>toTokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>quoteFor</code></td>
+  <td class="ty"><span class="t">&quot;from&quot; | &quot;max&quot; | &quot;to&quot;</span> <span class="flag opt">optional</span></td>
+  <td class="doc"><code>from</code> spends this much of the source, <code>to</code> receives this much at the destination, <code>max</code> sends everything. Defaults to <code>from</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>preferPluginId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Restrict to one exchange.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;fromWalletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;toWalletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;nativeAmount&quot;:&quot;12345&quot;,&quot;fromTokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;toTokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;quoteFor&quot;:&quot;&lt;\&quot;from\&quot;&gt;&quot;,&quot;preferPluginId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/fetch-swap-quotes'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  quoteCount: number
+  quotes: {
+    objectId: string;
+    kind: string;
+    expiresAt: string;
+    pluginId: string;
+    isEstimate: boolean;
+    canBePartial: boolean | null;
+    maxFulfillmentSeconds: number | null;
+    minReceiveAmount: string | null;
+    fromNativeAmount: string;
+    toNativeAmount: string;
+    networkFee: {
+      nativeAmount: string;
+      tokenId: string | null
+    };
+    quoteExpirationDate: string | null;
+    swapInfo: {
+      pluginId: string;
+      displayName: string;
+      supportEmail: string;
+      isDex: boolean | null
+    };
+    request: {
+      fromTokenId: string | null;
+      toTokenId: string | null;
+      nativeAmount: string;
+      quoteFor: &quot;from&quot; | &quot;to&quot; | &quot;max&quot;;
+      fromWalletId: string;
+      toWalletId: string
+    }
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;quoteCount&quot;: 1,
+  &quot;quotes&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>quoteCount</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">How many plugins answered.</td>
+</tr>
+<tr>
+  <td class="k"><code>quotes</code></td>
+  <td class="ty"><span class="t">{ objectId: string; kind: string; expiresAt: string; pluginId: string; isEstimate: boolean; canBePartial: boolean | null; maxFulfillmentSeconds: number | null; minReceiveAmount: string | null; fromNativeAmount: string; toNativeAmount: string; networkFee: { nativeAmount: string; tokenId: string | null; }; quoteExpirationDate: string | null; swapInfo: { pluginId: string; displayName: string; supportEmail: string; isDex: boolean | null; }; request: { fromTokenId: string | null; toTokenId: string | null; nativeAmount: string; quoteFor: &quot;from&quot; | &quot;to&quot; | &quot;max&quot;; fromWalletId: string; toWalletId: string; }; }[]</span></td>
+  <td class="doc">One quote per plugin that answered, each already parked under its own handle. Plugins that failed or had nothing to offer are simply absent.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-SWAP_BELOW_LIMIT" class="err" title="Amount below the plugin minimum."><span class="st">422</span>SWAP_BELOW_LIMIT</a> <a href="#err-SWAP_ABOVE_LIMIT" class="err" title="Amount exceeds the plugin maximum."><span class="st">422</span>SWAP_ABOVE_LIMIT</a> <a href="#err-SWAP_CURRENCY" class="err" title="The plugin does not support that pair."><span class="st">422</span>SWAP_CURRENCY</a> <a href="#err-SWAP_PERMISSION" class="err" title="The swap plugin refused the request."><span class="st">403</span>SWAP_PERMISSION</a> <a href="#err-SWAP_ADDRESS" class="err" title="Address unusable for this swap."><span class="st">422</span>SWAP_ADDRESS</a> <a href="#err-SAME_CURRENCY" class="err" title="Swap between identical currencies."><span class="st">400</span>SAME_CURRENCY</a> <a href="#err-INSUFFICIENT_FUNDS" class="err" title="Not enough balance to cover amount plus fee."><span class="st">422</span>INSUFFICIENT_FUNDS</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Every returned quote holds an open plugin object. Approving one releases only that handle; close the rest, or let them expire.</li><li>An empty <code>quotes</code> array with <code>quoteCount: 0</code> is a success, not an error — no plugin could serve the pair.</li></ul></div>
+  </section><section class="endpoint" id="getSwapQuote">
+    <header>
+      <h3><a href="#getSwapQuote">Re-read a quote.</a></h3>
+      <div class="ids"><code class="cmdname">swap-quote-get</code><span class="src" title="Declared in">src/cli/engine/routes/swap.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine handle store; the quote is a live EdgeSwapQuote held server-side.</em></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>swap-quote-get &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/swap-quote/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">An ephemeral object handle id.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/swap-quote/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  expiresAt: string
+  pluginId: string
+  isEstimate: boolean
+  canBePartial: boolean | null
+  maxFulfillmentSeconds: number | null
+  minReceiveAmount: string | null
+  fromNativeAmount: string
+  toNativeAmount: string
+  networkFee: {
+    nativeAmount: string;
+    tokenId: string | null
+  }
+  quoteExpirationDate: string | null
+  swapInfo: {
+    pluginId: string;
+    displayName: string;
+    supportEmail: string;
+    isDex: boolean | null
+  }
+  request: {
+    fromTokenId: string | null;
+    toTokenId: string | null;
+    nativeAmount: string;
+    quoteFor: &quot;from&quot; | &quot;to&quot; | &quot;max&quot;;
+    fromWalletId: string;
+    toWalletId: string
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;pluginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;isEstimate&quot;: true,
+  &quot;canBePartial&quot;: true,
+  &quot;maxFulfillmentSeconds&quot;: 1,
+  &quot;minReceiveAmount&quot;: &quot;12345&quot;,
+  &quot;fromNativeAmount&quot;: &quot;12345&quot;,
+  &quot;toNativeAmount&quot;: &quot;12345&quot;,
+  &quot;networkFee&quot;: {},
+  &quot;quoteExpirationDate&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;swapInfo&quot;: {},
+  &quot;request&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>pluginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Swap provider that produced this quote.</td>
+</tr>
+<tr>
+  <td class="k"><code>isEstimate</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True when the provider may settle at a different rate than quoted.</td>
+</tr>
+<tr>
+  <td class="k"><code>canBePartial</code></td>
+  <td class="ty"><span class="t">boolean | null</span></td>
+  <td class="doc">True when the provider may fill only part of the order. Null when it does not say.</td>
+</tr>
+<tr>
+  <td class="k"><code>maxFulfillmentSeconds</code></td>
+  <td class="ty"><span class="t">number | null</span></td>
+  <td class="doc">Longest the provider expects a partial fill to take.</td>
+</tr>
+<tr>
+  <td class="k"><code>minReceiveAmount</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">Least the provider guarantees to deliver, in the destination’s native units.</td>
+</tr>
+<tr>
+  <td class="k"><code>fromNativeAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Amount leaving the source wallet.</td>
+</tr>
+<tr>
+  <td class="k"><code>toNativeAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Amount arriving in the destination wallet.</td>
+</tr>
+<tr>
+  <td class="k"><code>networkFee</code></td>
+  <td class="ty"><span class="t">{ nativeAmount: string; tokenId: string | null; }</span></td>
+  <td class="doc">On-chain fee for the sending transaction. It is not the provider’s own spread, which is already in the rate.</td>
+</tr>
+<tr>
+  <td class="k"><code>quoteExpirationDate</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">When the provider stops honouring the rate. Null when it does not expire.</td>
+</tr>
+<tr>
+  <td class="k"><code>swapInfo</code></td>
+  <td class="ty"><span class="t">{ pluginId: string; displayName: string; supportEmail: string; isDex: boolean | null; }</span></td>
+  <td class="doc"><code>EdgeSwapInfo</code>: how to name the provider and where to send complaints.</td>
+</tr>
+<tr>
+  <td class="k"><code>request</code></td>
+  <td class="ty"><span class="t">{ fromTokenId: string | null; toTokenId: string | null; nativeAmount: string; quoteFor: &quot;from&quot; | &quot;to&quot; | &quot;max&quot;; fromWalletId: string; toWalletId: string; }</span></td>
+  <td class="doc">The <code>EdgeSwapRequest</code> this quote answers, echoed back so quotes from different plugins can be compared without tracking what was asked.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Check <code>quoteExpirationDate</code> as well as <code>expiresAt</code>: the plugin&#39;s price can go stale before the handle does.</li></ul></div>
+  </section><section class="endpoint" id="approveSwapQuote">
+    <header>
+      <h3><a href="#approveSwapQuote">Execute a quote.</a></h3>
+      <div class="ids"><code class="cmdname">approve-swap-quote</code><span class="src" title="Declared in">src/cli/engine/routes/swap.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>EdgeSwapQuote.approve</code></p>
+    <div class="desc"><p>Moves funds. The handle is released afterwards whether or not the response is read, so record <code>orderId</code> from it.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>approve-swap-quote &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/swap-quote/approve/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">An ephemeral object handle id.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/swap-quote/approve/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: unknown
+  objectId: string
+  orderId: unknown
+  destinationAddress: unknown
+  transaction: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: {},
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;orderId&quot;: {},
+  &quot;destinationAddress&quot;: {},
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc">True once the swap is submitted and the send broadcast.</td>
+</tr>
+<tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The handle that was consumed.</td>
+</tr>
+<tr>
+  <td class="k"><code>orderId</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc">The exchange’s order reference, when it gives one.</td>
+</tr>
+<tr>
+  <td class="k"><code>destinationAddress</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc">Address the funds were sent to, when the exchange reports one.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc">The on-chain send to the exchange.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-OBJECT_IN_USE" class="err" title="A consuming call on this handle is already in flight. Fund-moving calls outlive the client socket timeout, so a retry is refused rather than sending twice."><span class="st">409</span>OBJECT_IN_USE</a> <a href="#err-INSUFFICIENT_FUNDS" class="err" title="Not enough balance to cover amount plus fee."><span class="st">422</span>INSUFFICIENT_FUNDS</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>A failure releases the handle too, and a retry answers <code>OBJECT_NOT_FOUND</code>. <code>approve()</code> signs, broadcasts and then does its own bookkeeping, and from outside the plugin an error after the money moved cannot be told from one before it — so a retry has to start from a fresh quote rather than risk a second broadcast.</li><li>The plugin attaches its own savedAction and assetAction metadata; the engine adds none.</li></ul></div>
+  </section><section class="endpoint" id="closeSwapQuote">
+    <header>
+      <h3><a href="#closeSwapQuote">Discard a quote.</a></h3>
+      <div class="ids"><code class="cmdname">close-swap-quote</code><span class="src" title="Declared in">src/cli/engine/routes/swap.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>EdgeSwapQuote.close</code></p>
+    <div class="desc"><p>Closes the plugin object without executing, freeing whatever the exchange was holding.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>close-swap-quote &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/swap-quote/close/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">An ephemeral object handle id.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/swap-quote/close/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+  objectId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true,
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Always true; a failure arrives as an error envelope.</td>
+</tr>
+<tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The handle this call consumed. It is now expired.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="dataStore">Data store</h3>
+          <div class="groupdoc"><p>The account’s synced key-value store, where plugins keep their own state. One route per <code>EdgeDataStore</code> method.</p>
+</div>
+          <section class="endpoint" id="listStoreIds">
+    <header>
+      <h3><a href="#listStoreIds">List data-store ids.</a></h3>
+      <div class="ids"><code class="cmdname">list-store-ids</code><span class="src" title="Declared in">src/cli/engine/routes/dataStore.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.dataStore.listStoreIds</code></p>
+    <div class="desc"><p>The account&#39;s synced key-value store, where plugins keep their own state.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>list-store-ids</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/list-store-ids</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/list-store-ids'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  storeIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;storeIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>storeIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Every store holding at least one item.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="listItemIds">
+    <header>
+      <h3><a href="#listItemIds">List item ids in a store.</a></h3>
+      <div class="ids"><code class="cmdname">list-item-ids</code><span class="src" title="Declared in">src/cli/engine/routes/dataStore.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.dataStore.listItemIds</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>list-item-ids --store-id=&lt;storeId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/list-item-ids</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  storeId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;storeId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>storeId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Plugin or app namespace within the account data store.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/list-item-ids?storeId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  itemIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;itemIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>itemIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Keys in this store. Empty if it has none.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="getItem">
+    <header>
+      <h3><a href="#getItem">Read an item.</a></h3>
+      <div class="ids"><code class="cmdname">get-item</code><span class="src" title="Declared in">src/cli/engine/routes/dataStore.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.dataStore.getItem</code></p>
+    <div class="desc"><p>Values are opaque strings; encoding is the caller&#39;s business.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-item --store-id=&lt;storeId&gt; --item-id=&lt;itemId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/get-item</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  storeId: string
+  itemId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;storeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;itemId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>storeId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Plugin or app namespace within the account data store.</td>
+</tr>
+<tr>
+  <td class="k"><code>itemId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Key within the store.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/get-item?storeId=…&amp;itemId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  value: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;value&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>value</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The stored string.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-NOT_FOUND" class="err" title="No route matched, or a generic missing resource."><span class="st">404</span>NOT_FOUND</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="setItem">
+    <header>
+      <h3><a href="#setItem">Write an item.</a></h3>
+      <div class="ids"><code class="cmdname">set-item</code><span class="src" title="Declared in">src/cli/engine/routes/dataStore.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.dataStore.setItem</code></p>
+    <div class="desc"><p>Creates the store if it does not exist.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>set-item --store-id=&lt;storeId&gt; --item-id=&lt;itemId&gt; --value=&lt;value&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/set-item</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  storeId: string
+  itemId: string
+  value: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;storeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;itemId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;value&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>storeId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Plugin or app namespace within the account data store.</td>
+</tr>
+<tr>
+  <td class="k"><code>itemId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Key within the store.</td>
+</tr>
+<tr>
+  <td class="k"><code>value</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The string to store.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;storeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;itemId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;value&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/set-item'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="deleteItem">
+    <header>
+      <h3><a href="#deleteItem">Delete an item.</a></h3>
+      <div class="ids"><code class="cmdname">delete-item</code><span class="src" title="Declared in">src/cli/engine/routes/dataStore.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.dataStore.deleteItem</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>delete-item --store-id=&lt;storeId&gt; --item-id=&lt;itemId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/delete-item</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  storeId: string
+  itemId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;storeId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;itemId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>storeId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Plugin or app namespace within the account data store.</td>
+</tr>
+<tr>
+  <td class="k"><code>itemId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Key within the store.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;storeId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;itemId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/delete-item'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="deleteStore">
+    <header>
+      <h3><a href="#deleteStore">Delete an entire store.</a></h3>
+      <div class="ids"><code class="cmdname">delete-store</code><span class="src" title="Declared in">src/cli/engine/routes/dataStore.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>account.dataStore.deleteStore</code></p>
+    <div class="desc"><p>Removes every item in it, which cannot be undone from this API.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>delete-store --store-id=&lt;storeId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/delete-store</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  storeId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;storeId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>storeId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Plugin or app namespace within the account data store.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;storeId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/delete-store'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h2 id="wallet">Wallet</h2>
+      <div class="groupdoc"><p>Calls on a single <code>EdgeCurrencyWallet</code>. Each names its wallet with <code>--wallet-id</code>, which accepts a full id or any unique prefix.</p>
+</div>
+      <h3 class="sub" id="wallets">Wallet state</h3>
+          <div class="groupdoc"><p>Account-level wallet listing and creation, then per-wallet calls. A <code>{walletId}</code> segment accepts a unique prefix, so those routes can also return <code>404 WALLET_NOT_FOUND</code> or <code>409 AMBIGUOUS_WALLET_ID</code>.</p>
+</div>
+          <section class="endpoint" id="walletInfo">
+    <header>
+      <h3><a href="#walletInfo">Wallet detail.</a></h3>
+      <div class="ids"><code class="cmdname">wallet-info</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine composite of EdgeCurrencyWallet properties plus its EdgeCurrencyConfig token map.</em></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>wallet-info --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>Every WalletSummary field, plus denominations and walletSettings. <code>allTokens</code> is not here — <code>wallet-tokens</code> exists to carry it, and returning it from both sent the same map twice in a session that calls both.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="renameWallet">
+    <header>
+      <h3><a href="#renameWallet">Rename a wallet.</a></h3>
+      <div class="ids"><code class="cmdname">rename-wallet</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.renameWallet</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>rename-wallet --wallet-id=&lt;walletId&gt; --name=&lt;name&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/rename-wallet</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  name: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;name&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>name</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The new display name.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;name&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/wallet/rename-wallet'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="setFiatCurrencyCode">
+    <header>
+      <h3><a href="#setFiatCurrencyCode">Change a wallet's fiat currency.</a></h3>
+      <div class="ids"><code class="cmdname">set-fiat-currency-code</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.setFiatCurrencyCode</code></p>
+    <div class="desc"><p>Affects how balances and history are priced, not the asset itself.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>set-fiat-currency-code --wallet-id=&lt;walletId&gt; --fiat-currency-code=&lt;fiatCurrencyCode&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/set-fiat-currency-code</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  fiatCurrencyCode: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;fiatCurrencyCode&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>fiatCurrencyCode</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">e.g. <code>iso:EUR</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;fiatCurrencyCode&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/wallet/set-fiat-currency-code'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changePaused">
+    <header>
+      <h3><a href="#changePaused">Pause or resume a wallet engine.</a></h3>
+      <div class="ids"><code class="cmdname">change-paused</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.changePaused</code></p>
+    <div class="desc"><p>A paused wallet stops syncing, which is how a caller quiets a chain it does not currently care about.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-paused --wallet-id=&lt;walletId&gt; --paused=true|false</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/change-paused</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  paused: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;paused&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>paused</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">True to stop syncing.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;paused&quot;:true}' \
+  'http://localhost/account/$SESS/wallet/change-paused'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="walletSync">
+    <header>
+      <h3><a href="#walletSync">Nudge one wallet to sync.</a></h3>
+      <div class="ids"><code class="cmdname">wallet-sync</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.sync</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>wallet-sync --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/sync</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/wallet/sync'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Named <code>wallet-sync</code> on the CLI because <code>sync</code> is <code>account.sync</code>.</li></ul></div>
+  </section><section class="endpoint" id="resyncBlockchain">
+    <header>
+      <h3><a href="#resyncBlockchain">Rescan the blockchain from scratch.</a></h3>
+      <div class="ids"><code class="cmdname">resync-blockchain</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.resyncBlockchain</code></p>
+    <div class="desc"><p>Drops cached chain state and re-scans. Expensive, and the wallet reports an incomplete balance until it finishes.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>resync-blockchain --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/resync-blockchain</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/wallet/resync-blockchain'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Returns when the resync is requested, not when it completes. Watch <code>syncRatio</code> for progress.</li></ul></div>
+  </section><section class="endpoint" id="splitWallet">
+    <header>
+      <h3><a href="#splitWallet">Split a wallet into another chain.</a></h3>
+      <div class="ids"><code class="cmdname">split</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.split</code></p>
+    <div class="desc"><p>Forked-chain support: derive a wallet of a different type from the same keys. <code>list-splittable-wallet-types</code> says which are valid.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>split --wallet-id=&lt;walletId&gt; --split-wallets='&lt;json&gt;'</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/split</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  splitWallets: {
+    walletType: string;
+    name: string | undefined;
+    fiatCurrencyCode: string | undefined
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;splitWallets&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>splitWallets</code></td>
+  <td class="ty"><span class="t">{ walletType: string; name: string | undefined; fiatCurrencyCode: string | undefined; }[]</span></td>
+  <td class="doc"><code>EdgeSplitCurrencyWallet[]</code>: walletType, plus optional name and fiatCurrencyCode.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;splitWallets&quot;:[{}]}' \
+  'http://localhost/account/$SESS/wallet/split'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  results: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;results&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>results</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc">Per-entry outcomes, like batch create.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="dumpData">
+    <header>
+      <h3><a href="#dumpData">Dump wallet engine state.</a></h3>
+      <div class="ids"><code class="cmdname">dump-data</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.dumpData</code></p>
+    <div class="desc"><p>Plugin-defined debug output. Shape varies by plugin and can be very large.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>dump-data --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/dump-data</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/dump-data?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>EdgeDataDump</code>, straight from the plugin.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="balanceMap">
+    <header>
+      <h3><a href="#balanceMap">Balances for every asset in the wallet.</a></h3>
+      <div class="ids"><code class="cmdname">balance-map</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.balanceMap</code> <span class="dim">Rendered as an array, with currencyCode and displayAmount added from the wallet&#39;s denominations.</span></p>
+    <div class="desc"><p>The native currency plus every enabled token.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>balance-map --wallet-id=&lt;walletId&gt; [--token-id=&lt;value&gt;]</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--token-id</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Client-side filter; core has no single-balance accessor.</td></tr></tbody></table>
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/balance-map</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/balance-map?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  balances: {
+    tokenId: string | null;
+    currencyCode: string;
+    nativeAmount: string;
+    displayAmount: string | null;
+    unknownToken: boolean
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;balances&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>balances</code></td>
+  <td class="ty"><span class="t">{ tokenId: string | null; currencyCode: string; nativeAmount: string; displayAmount: string | null; unknownToken: boolean; }[]</span></td>
+  <td class="doc">One entry per asset the wallet holds, native coin first: <code>tokenId</code>, <code>currencyCode</code>, <code>nativeAmount</code>, <code>displayAmount</code> and <code>unknownToken</code>. A token the plugin reports a balance for but whose config it no longer carries is listed with <code>unknownToken: true</code> and a null <code>displayAmount</code>, rather than failing the whole wallet.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>On the CLI, omit <code>--token-id</code> for the native asset rather than passing the literal <code>null</code>.</li></ul></div>
+  </section><section class="endpoint" id="getAddresses">
+    <header>
+      <h3><a href="#getAddresses">Receive addresses.</a></h3>
+      <div class="ids"><code class="cmdname">get-addresses</code><span class="src" title="Declared in">src/cli/engine/routes/wallets.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.getAddresses</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-addresses --wallet-id=&lt;walletId&gt; [--token-id=&lt;tokenId&gt;] [--force-index=&lt;forceIndex&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/get-addresses</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+  tokenId?: string | null
+  forceIndex?: number
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;forceIndex&quot;: 0
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>forceIndex</code></td>
+  <td class="ty"><span class="t">number</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Derive at a specific index.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/get-addresses?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  addresses: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;addresses&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>addresses</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc"><code>EdgeAddress[]</code>: addressType, publicAddress, nativeBalance.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="tokens">Tokens</h3>
+          <div class="groupdoc"><p>Which tokens a wallet tracks. Enabled tokens are the ones it syncs balances for; detected ones were seen on-chain but are not yet enabled.</p>
+</div>
+          <section class="endpoint" id="walletTokens">
+    <header>
+      <h3><a href="#walletTokens">List a wallet's tokens.</a></h3>
+      <div class="ids"><code class="cmdname">wallet-tokens</code><span class="src" title="Declared in">src/cli/engine/routes/tokens.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine composite of the EdgeCurrencyConfig token maps plus wallet.enabledTokenIds and wallet.detectedTokenIds.</em></p>
+    <div class="desc"><p>&quot;Enabled&quot; tokens are the ones the wallet syncs balances for; &quot;detected&quot; ones were seen on-chain but are not yet enabled.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>wallet-tokens --wallet-id=&lt;walletId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/tokens</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/tokens?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  allTokens: {
+    [keys: string]: unknown
+  }
+  customTokens: {
+    [keys: string]: unknown
+  }
+  enabledTokenIds: string[]
+  detectedTokenIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;allTokens&quot;: {},
+  &quot;customTokens&quot;: {},
+  &quot;enabledTokenIds&quot;: [
+    &quot;string&quot;
+  ],
+  &quot;detectedTokenIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>allTokens</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span></td>
+  <td class="doc"><code>EdgeToken</code> by tokenId: everything the plugin ships with, plus this account’s own. <code>builtinTokens</code> is not returned separately — it is this map minus <code>customTokens</code>, and sending both wrote the whole built-in list down the socket twice.</td>
+</tr>
+<tr>
+  <td class="k"><code>customTokens</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span></td>
+  <td class="doc"><code>EdgeToken</code> by tokenId: tokens this account added by hand.</td>
+</tr>
+<tr>
+  <td class="k"><code>enabledTokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Which of the above the wallet is actually tracking.</td>
+</tr>
+<tr>
+  <td class="k"><code>detectedTokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">Seen on-chain but not enabled, so their balances are not synced.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changeEnabledTokenIds">
+    <header>
+      <h3><a href="#changeEnabledTokenIds">Set the enabled token set.</a></h3>
+      <div class="ids"><code class="cmdname">change-enabled-token-ids</code><span class="src" title="Declared in">src/cli/engine/routes/tokens.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.changeEnabledTokenIds</code></p>
+    <div class="desc"><p>Absolute: anything missing from <code>tokenIds</code> is disabled. Core has only this setter, so there is no add or remove call.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>change-enabled-token-ids --wallet-id=&lt;walletId&gt; --token-ids='&lt;json&gt;' [--add=&lt;value&gt;] [--remove=&lt;value&gt;]</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--add</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Read the current set, add this id, write it back.</td></tr><tr><td class="k"><code>--remove</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Read the current set, drop this id, write it back.</td></tr></tbody></table>
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/change-enabled-token-ids</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  tokenIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">The complete desired set.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;tokenIds&quot;:[&quot;string&quot;]}' \
+  'http://localhost/account/$SESS/wallet/change-enabled-token-ids'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  enabledTokenIds: string[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;enabledTokenIds&quot;: [
+    &quot;string&quot;
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>enabledTokenIds</code></td>
+  <td class="ty"><span class="t">string[]</span></td>
+  <td class="doc">The wallet’s enabled tokens after the change, not just what changed.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The command&#39;s <code>--add</code> and <code>--remove</code> are client-side sugar over this one route, and cost an extra read first.</li></ul></div>
+  </section><h3 class="sub" id="transactions">Transactions</h3>
+          <div class="groupdoc"><p>Reading transaction history, exporting it, and editing its metadata.</p>
+</div>
+          <section class="endpoint" id="getTransactions">
+    <header>
+      <h3><a href="#getTransactions">List or export a wallet's transactions.</a></h3>
+      <div class="ids"><code class="cmdname">get-transactions</code><span class="src" title="Declared in">src/cli/engine/routes/transactions.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.getTransactions</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>limit</code> — Engine-side paging; core returns every match.</li><li><code>offset</code> — Engine-side paging; core returns every match.</li><li><code>fiat</code> — Selects the currency the engine values each transaction in.</li><li><code>exportFormat</code> — Engine-side rendering to CSV, QBO or Bitwave.</li><li><code>bitwaveAccountId</code> — Required by the Bitwave export format.</li><li><code>saveExportPrefs</code> — Opt-in write of the wallet’s synced exportTxInfo.json, the record the GUI export scene reads back.</li></ul></div>
+    <div class="desc"><p>Reads history, overlays the display metadata the GUI shows, fills historical fiat, and optionally formats the result — all on this one call.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-transactions --wallet-id=&lt;walletId&gt; [--token-id=&lt;tokenId&gt;] [--limit=&lt;limit&gt;] [--offset=&lt;offset&gt;] [--save-export-prefs[=false]] [--start-date=&lt;startDate&gt;] [--end-date=&lt;endDate&gt;] [--search-string=&lt;searchString&gt;] [--spam-threshold=&lt;spamThreshold&gt;] [--fiat=&lt;fiat&gt;] [--export-format=&lt;exportFormat&gt;] [--bitwave-account=&lt;bitwaveAccountId&gt;] [--out=&lt;value&gt;]</code></pre>
+    
+    <h5>Client-only flags</h5><table class="fields"><tbody><tr><td class="k"><code>--out</code></td><td class="ty"><span class="flag opt">optional</span></td><td class="doc">Where to write the returned files. One format: the path. Several: a stem, plus .csv / .qbo / .bitwave.csv.</td></tr></tbody></table>
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/get-transactions</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+  tokenId?: string | null
+  limit?: number
+  offset?: number
+  saveExportPrefs?: boolean
+  startDate?: Date
+  endDate?: Date
+  searchString?: string
+  spamThreshold?: string
+  fiat?: string
+  exportFormat?: string
+  bitwaveAccountId?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;limit&quot;: 0,
+  &quot;offset&quot;: 0,
+  &quot;saveExportPrefs&quot;: true,
+  &quot;startDate&quot;: &quot;&lt;Date&gt;&quot;,
+  &quot;endDate&quot;: &quot;&lt;Date&gt;&quot;,
+  &quot;searchString&quot;: &quot;string&quot;,
+  &quot;spamThreshold&quot;: &quot;string&quot;,
+  &quot;fiat&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;exportFormat&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;bitwaveAccountId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>limit</code></td>
+  <td class="ty"><span class="t">number</span> <span class="flag opt">optional</span></td>
+  <td class="doc">How many to return. Defaults to 100; pass <code>0</code> for every transaction from <code>offset</code> on. <code>total</code> in the response says how many matched, so a caller can page with <code>offset</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>offset</code></td>
+  <td class="ty"><span class="t">number</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Where to start. Defaults to 0.</td>
+</tr>
+<tr>
+  <td class="k"><code>saveExportPrefs</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Save <code>bitwaveAccountId</code> and the chosen formats into the wallet’s synced <code>exportTxInfo.json</code>, which the GUI export scene reads back. Off by default: a read does not change saved preferences.</td>
+</tr>
+<tr>
+  <td class="k"><code>startDate</code></td>
+  <td class="ty"><span class="t">Date</span> <span class="flag opt">optional</span></td>
+  <td class="doc">ISO-8601, or epoch milliseconds.</td>
+</tr>
+<tr>
+  <td class="k"><code>endDate</code></td>
+  <td class="ty"><span class="t">Date</span> <span class="flag opt">optional</span></td>
+  <td class="doc">ISO-8601, or epoch milliseconds.</td>
+</tr>
+<tr>
+  <td class="k"><code>searchString</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Matches payee, category, notes and txid.</td>
+</tr>
+<tr>
+  <td class="k"><code>spamThreshold</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Native-amount floor. Omitted, the account spam-filter setting applies; a value always overrides it, and <code>0</code> shows everything. An empty value reads as omitted, like every other query parameter.</td>
+</tr>
+<tr>
+  <td class="k"><code>fiat</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Three-letter ISO 4217 code. Defaults to the account defaultIsoFiat.</td>
+</tr>
+<tr>
+  <td class="k"><code>exportFormat</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Comma list of <code>csv</code>, <code>qbo</code>, <code>bitwave</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>bitwaveAccountId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A 400 unless <code>exportFormat</code> includes <code>bitwave</code>.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/get-transactions?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>{ transactions, total, isoFiat }</code>, or <code>{ ok, isoFiat, total, files }</code> when exportFormat is set. Each transaction carries <code>metadata.name</code>, <code>metadata.category</code> and <code>metadata.notes</code> as <strong>localized prose</strong> in the engine’s boot locale — the engine has no per-request locale, so a second shell with a different <code>LANG</code> reuses the first engine and gets its language. <code>displayInfo</code> beside them carries the machine values the prose was derived from (<code>direction</code>, <code>assetActionType</code>, <code>actionType</code>, and the <code>category</code> split whose <code>category</code> member is one of <code>transfer</code>, <code>exchange</code>, <code>expense</code>, <code>income</code>), so a caller can render its own text.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-MISSING_BITWAVE_ACCOUNT_ID" class="err" title="Bitwave export requested with no account id in the query and none saved in the wallet’s `exportTxInfo.json`."><span class="st">400</span>MISSING_BITWAVE_ACCOUNT_ID</a> <a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>The metadata overlay and the fiat fill are response-only. Neither writes to disk.</li><li><code>limit</code> and <code>offset</code> apply before the fiat fill, so a large page asks the rates server about more dates. Unpriced dates are batched into one request per 100, and every rate is cached for the life of the engine, so a second listing of the same range needs none.</li><li>This is the one GET that can write: passing <code>bitwaveAccountId</code> persists it to <code>exportTxInfo.json</code> on the wallet disklet.</li></ul></div>
+  </section><section class="endpoint" id="getNumTransactions">
+    <header>
+      <h3><a href="#getNumTransactions">Count transactions in a wallet.</a></h3>
+      <div class="ids"><code class="cmdname">get-num-transactions</code><span class="src" title="Declared in">src/cli/engine/routes/transactions.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.getNumTransactions</code></p>
+    <div class="desc"><p>Cheaper than listing when only the total matters.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-num-transactions --wallet-id=&lt;walletId&gt; [--token-id=&lt;tokenId&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/get-num-transactions</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+  tokenId?: string | null
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/get-num-transactions?walletId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  numTransactions: number
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;numTransactions&quot;: 0
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>numTransactions</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Every transaction the wallet knows of.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Unfiltered: <code>spamThreshold</code>, dates and <code>searchString</code> do not apply, so this can exceed <code>total</code> from <code>get-transactions</code>.</li></ul></div>
+  </section><section class="endpoint" id="saveTxMetadata">
+    <header>
+      <h3><a href="#saveTxMetadata">Save transaction metadata.</a></h3>
+      <div class="ids"><code class="cmdname">save-tx-metadata</code><span class="src" title="Declared in">src/cli/engine/routes/transactions.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.saveTxMetadata</code></p>
+    <div class="desc"><p>One of the paths that write transaction metadata to disk. The others are <code>save-tx-action</code>, which writes <code>savedAction</code> and <code>assetAction</code> to the same file, and <code>save-tx</code> and <code>spend</code>, both of which re-apply the caller&#39;s metadata through <code>saveTxAndMetadata</code> after the transaction is saved.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>save-tx-metadata --wallet-id=&lt;walletId&gt; --txid=&lt;txid&gt; [--token-id=&lt;tokenId&gt;] --metadata='&lt;json&gt;'</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/save-tx-metadata</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  txid: string
+  tokenId?: string | null
+  metadata: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeMetadataChange
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;txid&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;metadata&quot;: &quot;&lt;import(\&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\&quot;).EdgeMetadataChange&gt;&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>txid</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Which transaction to tag.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>metadata</code></td>
+  <td class="ty"><span class="t">import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeMetadataChange</span></td>
+  <td class="doc"><code>EdgeMetadataChange</code>: name, category, notes, exchangeAmount, bizId. <code>null</code> on a field deletes it; omitting the field leaves it unchanged.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;txid&quot;:&quot;FS8xJ2kQ…&quot;,&quot;tokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;metadata&quot;:&quot;&lt;import(\&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\&quot;).EdgeMetadataChange&gt;&quot;}' \
+  'http://localhost/account/$SESS/wallet/save-tx-metadata'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li><code>metadata</code> is an <code>EdgeMetadataChange</code>, so an explicit null clears a field while an omitted one is left alone.</li></ul></div>
+  </section><section class="endpoint" id="saveTxAction">
+    <header>
+      <h3><a href="#saveTxAction">Save a transaction action.</a></h3>
+      <div class="ids"><code class="cmdname">save-tx-action</code><span class="src" title="Declared in">src/cli/engine/routes/transactions.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.saveTxAction</code></p>
+    <div class="desc"><p>Records what a transaction <em>was</em> — a swap, a stake — beyond its metadata.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>save-tx-action --wallet-id=&lt;walletId&gt; --txid=&lt;txid&gt; [--token-id=&lt;tokenId&gt;] --saved-action='&lt;json&gt;' [--asset-action='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/save-tx-action</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  txid: string
+  tokenId?: string | null
+  savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionSwap | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionStake | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionFiat | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionTokenApproval | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionGiftCard
+  assetAction?: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;txid&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;savedAction&quot;: &quot;&lt;import(\&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\&quot;).EdgeTxActionSwap&gt;&quot;,
+  &quot;assetAction&quot;: &quot;&lt;import(\&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\&quot;).EdgeAssetAction&gt;&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>txid</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Which transaction to annotate.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>savedAction</code></td>
+  <td class="ty"><span class="t">import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionSwap | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionStake | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionFiat | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionTokenApproval | import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxActionGiftCard</span></td>
+  <td class="doc"><code>EdgeTxAction</code> describing what happened, discriminated on <code>actionType</code>: swap, stake, fiat, tokenApproval or giftCard.</td>
+</tr>
+<tr>
+  <td class="k"><code>assetAction</code></td>
+  <td class="ty"><span class="t">import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction</span> <span class="flag opt">optional</span></td>
+  <td class="doc"><code>EdgeAssetAction</code>: one <code>assetActionType</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;txid&quot;:&quot;FS8xJ2kQ…&quot;,&quot;tokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;savedAction&quot;:&quot;&lt;import(\&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\&quot;).EdgeTxActionSwap&gt;&quot;,&quot;assetAction&quot;:&quot;&lt;import(\&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\&quot;).EdgeAssetAction&gt;&quot;}' \
+  'http://localhost/account/$SESS/wallet/save-tx-action'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>When <code>assetAction</code> is omitted it defaults to <code>{ assetActionType: &#39;transfer&#39; }</code>.</li></ul></div>
+  </section><h3 class="sub" id="spend">Spending</h3>
+          <div class="groupdoc"><p>Two ways to send funds. <code>spend</code> does the whole thing in one call; the staged workflow — <code>make-spend</code>, <code>sign-tx</code>, <code>broadcast-tx</code>, <code>save-tx</code> — hands back an object handle at each step so fees can be inspected before committing.</p>
+</div>
+          <section class="endpoint" id="getMaxSpendable">
+    <header>
+      <h3><a href="#getMaxSpendable">Largest sendable amount.</a></h3>
+      <div class="ids"><code class="cmdname">get-max-spendable</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.getMaxSpendable</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>to</code> — Shorthand the engine expands into <code>spendTargets</code>, so a one-output send needs no nested JSON.</li><li><code>nativeAmount</code> — Amount for the <code>to</code> shorthand, in the smallest unit.</li><li><code>amount</code> — Alias of <code>nativeAmount</code> for the <code>to</code> shorthand: the chain’s smallest unit, not whole coins.</li></ul></div>
+    <div class="desc"><p>What empties the wallet after fees. A destination is still required, since fees depend on it.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-max-spendable --wallet-id=&lt;walletId&gt; [--spend-info='&lt;json&gt;'] [--to=&lt;to&gt;] [--native-amount=&lt;nativeAmount&gt;] [--amount=&lt;amount&gt;] [--token-id=&lt;tokenId&gt;] [--metadata='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/get-max-spendable</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  spendInfo?: {
+    spendTargets: {
+      publicAddress: string | undefined;
+      nativeAmount: string | undefined;
+      uniqueIdentifier: string | undefined;
+      memo: string | undefined;
+      otherParams: {
+        [keys: string]: unknown
+      } | undefined
+    }[];
+    tokenId: string | null;
+    metadata: EdgeMetadata | undefined;
+    networkFeeOption: string | undefined;
+    customNetworkFee: {
+      [keys: string]: unknown
+    } | undefined;
+    rbfTxid: string | undefined;
+    memos: {
+      [keys: string]: unknown
+    }[] | undefined;
+    assetAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction | undefined;
+    savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxAction | undefined;
+    otherParams: {
+      [keys: string]: unknown
+    } | undefined
+  }
+  to?: string
+  nativeAmount?: string
+  amount?: string
+  tokenId?: string | null
+  metadata?: EdgeMetadata
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;spendInfo&quot;: {},
+  &quot;to&quot;: &quot;string&quot;,
+  &quot;nativeAmount&quot;: &quot;12345&quot;,
+  &quot;amount&quot;: &quot;12345&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;metadata&quot;: &quot;&lt;EdgeMetadata&gt;&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>spendInfo</code></td>
+  <td class="ty"><span class="t">{ spendTargets: { publicAddress: string | undefined; nativeAmount: string | undefined; uniqueIdentifier: string | undefined; memo: string | undefined; otherParams: { [keys: string]: unknown; } | undefined; }[]; tokenId: string | null; metadata: EdgeMetadata | undefined; networkFeeOption: string | undefined; customNetworkFee: { [keys: string]: unknown; } | undefined; rbfTxid: string | undefined; memos: { [keys: string]: unknown; }[] | undefined; assetAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction | undefined; savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxAction | undefined; otherParams: { [keys: string]: unknown; } | undefined; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A full <code>EdgeSpendInfo</code>, used as-is when present. <code>spendTargets</code> is required.</td>
+</tr>
+<tr>
+  <td class="k"><code>to</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Address or BIP21 URI, run through <code>wallet.parseUri</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">How much, in native units.</td>
+</tr>
+<tr>
+  <td class="k"><code>amount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Alias of <code>nativeAmount</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>metadata</code></td>
+  <td class="ty"><span class="t">EdgeMetadata</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wins over anything parsed out of the URI.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;spendInfo&quot;:{},&quot;to&quot;:&quot;string&quot;,&quot;nativeAmount&quot;:&quot;12345&quot;,&quot;amount&quot;:&quot;12345&quot;,&quot;tokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;metadata&quot;:&quot;&lt;EdgeMetadata&gt;&quot;}' \
+  'http://localhost/account/$SESS/wallet/get-max-spendable'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  nativeAmount: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;nativeAmount&quot;: &quot;12345&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The most this wallet can send.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-INSUFFICIENT_FUNDS" class="err" title="Not enough balance to cover amount plus fee."><span class="st">422</span>INSUFFICIENT_FUNDS</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="spend">
+    <header>
+      <h3><a href="#spend">Send funds.</a></h3>
+      <div class="ids"><code class="cmdname">spend</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>GUI composite: makeSpend, signTx, broadcastTx and saveTx together.</em></p>
+    <div class="desc"><p><code>makeSpend</code>, then <code>signTx</code>, then optionally <code>broadcastTx</code> and <code>saveTx</code>, in one request. <code>broadcast</code> and <code>save</code> both default to true, so a bare body with a destination and an amount moves real money. A completed spend leaves no handle behind.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>spend [--use-max[=false]] [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=&lt;walletId&gt; [--spend-info='&lt;json&gt;'] [--to=&lt;to&gt;] [--native-amount=&lt;nativeAmount&gt;] [--amount=&lt;amount&gt;] [--token-id=&lt;tokenId&gt;] [--metadata='&lt;json&gt;']</code></pre>
+    <h5 class="alt"><code>spend-max</code> — Send a wallet’s entire spendable balance.</h5><pre class="usage"><code>spend-max [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=&lt;walletId&gt; [--spend-info='&lt;json&gt;'] [--to=&lt;to&gt;] [--native-amount=&lt;nativeAmount&gt;] [--amount=&lt;amount&gt;] [--token-id=&lt;tokenId&gt;] [--metadata='&lt;json&gt;']</code></pre><div class="note"><p>The same route with <code>useMax</code> preset, so it sends everything.</p>
+</div>
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/spend</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  useMax?: boolean
+  dryRun?: boolean
+  broadcast?: boolean
+  save?: boolean
+  walletId: string
+  spendInfo?: {
+    spendTargets: {
+      publicAddress: string | undefined;
+      nativeAmount: string | undefined;
+      uniqueIdentifier: string | undefined;
+      memo: string | undefined;
+      otherParams: {
+        [keys: string]: unknown
+      } | undefined
+    }[];
+    tokenId: string | null;
+    metadata: EdgeMetadata | undefined;
+    networkFeeOption: string | undefined;
+    customNetworkFee: {
+      [keys: string]: unknown
+    } | undefined;
+    rbfTxid: string | undefined;
+    memos: {
+      [keys: string]: unknown
+    }[] | undefined;
+    assetAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction | undefined;
+    savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxAction | undefined;
+    otherParams: {
+      [keys: string]: unknown
+    } | undefined
+  }
+  to?: string
+  nativeAmount?: string
+  amount?: string
+  tokenId?: string | null
+  metadata?: EdgeMetadata
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;useMax&quot;: true,
+  &quot;dryRun&quot;: true,
+  &quot;broadcast&quot;: true,
+  &quot;save&quot;: true,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;spendInfo&quot;: {},
+  &quot;to&quot;: &quot;string&quot;,
+  &quot;nativeAmount&quot;: &quot;12345&quot;,
+  &quot;amount&quot;: &quot;12345&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;metadata&quot;: &quot;&lt;EdgeMetadata&gt;&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>useMax</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Replace the first target’s amount with the maximum.</td>
+</tr>
+<tr>
+  <td class="k"><code>dryRun</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Build only. Never signs or broadcasts.</td>
+</tr>
+<tr>
+  <td class="k"><code>broadcast</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to <strong>true</strong>. With <code>false</code> the transaction is signed and not sent, so <code>save</code> then defaults to false as well — recording an unsent transaction marks its inputs spent locally for something the network will never confirm.</td>
+</tr>
+<tr>
+  <td class="k"><code>save</code></td>
+  <td class="ty"><span class="t">boolean</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Record the transaction in the wallet. Defaults to whatever <code>broadcast</code> is. Setting it true alongside <code>broadcast: false</code> is refused: use <code>--dry-run</code>, or the staged <code>make-spend</code> → <code>sign-tx</code> → <code>broadcast-tx</code> → <code>save-tx</code> flow.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>spendInfo</code></td>
+  <td class="ty"><span class="t">{ spendTargets: { publicAddress: string | undefined; nativeAmount: string | undefined; uniqueIdentifier: string | undefined; memo: string | undefined; otherParams: { [keys: string]: unknown; } | undefined; }[]; tokenId: string | null; metadata: EdgeMetadata | undefined; networkFeeOption: string | undefined; customNetworkFee: { [keys: string]: unknown; } | undefined; rbfTxid: string | undefined; memos: { [keys: string]: unknown; }[] | undefined; assetAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction | undefined; savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxAction | undefined; otherParams: { [keys: string]: unknown; } | undefined; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A full <code>EdgeSpendInfo</code>, used as-is when present. <code>spendTargets</code> is required.</td>
+</tr>
+<tr>
+  <td class="k"><code>to</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Address or BIP21 URI, run through <code>wallet.parseUri</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">How much, in native units.</td>
+</tr>
+<tr>
+  <td class="k"><code>amount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Alias of <code>nativeAmount</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>metadata</code></td>
+  <td class="ty"><span class="t">EdgeMetadata</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wins over anything parsed out of the URI.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;useMax&quot;:true,&quot;dryRun&quot;:true,&quot;broadcast&quot;:true,&quot;save&quot;:true,&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;spendInfo&quot;:{},&quot;to&quot;:&quot;string&quot;,&quot;nativeAmount&quot;:&quot;12345&quot;,&quot;amount&quot;:&quot;12345&quot;,&quot;tokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;metadata&quot;:&quot;&lt;EdgeMetadata&gt;&quot;}' \
+  'http://localhost/account/$SESS/wallet/spend'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>{ transaction }</code>, plus <code>saveError</code> when the broadcast succeeded but saving failed. With dryRun, a TransactionHandle instead.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-INSUFFICIENT_FUNDS" class="err" title="Not enough balance to cover amount plus fee."><span class="st">422</span>INSUFFICIENT_FUNDS</a> <a href="#err-DUST_SPEND" class="err" title="Amount below the network dust threshold."><span class="st">422</span>DUST_SPEND</a> <a href="#err-PENDING_FUNDS" class="err" title="Balance exists but is unconfirmed."><span class="st">422</span>PENDING_FUNDS</a> <a href="#err-SPEND_TO_SELF" class="err" title="Destination address belongs to the source wallet."><span class="st">422</span>SPEND_TO_SELF</a> <a href="#err-NO_AMOUNT_SPECIFIED" class="err" title="Zero-amount spend."><span class="st">400</span>NO_AMOUNT_SPECIFIED</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>BIP21 <code>label</code> and <code>message</code> from <code>to</code> become metadata name and notes. An explicit <code>metadata</code> object wins.</li><li><code>saveError</code> is the case to handle. Once broadcast, the money is gone, so a failure inside saveTx cannot throw — it would hide the txid of a real payment. The response is 200 with the transaction plus <code>saveError</code>.</li><li>With <code>dryRun</code>, only makeSpend runs and the response is a transaction handle that expires in 5 minutes.</li></ul></div>
+  </section><section class="endpoint" id="makeSpend">
+    <header>
+      <h3><a href="#makeSpend">Build an unsigned transaction.</a></h3>
+      <div class="ids"><code class="cmdname">make-spend</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.makeSpend</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>to</code> — Shorthand the engine expands into <code>spendTargets</code>, so a one-output send needs no nested JSON.</li><li><code>nativeAmount</code> — Amount for the <code>to</code> shorthand, in the smallest unit.</li><li><code>amount</code> — Alias of <code>nativeAmount</code> for the <code>to</code> shorthand: the chain’s smallest unit, not whole coins.</li></ul></div>
+    <div class="desc"><p>First step of the staged workflow: nothing is signed and no funds move. Inspect <code>transaction.networkFee</code> on the result before signing.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>make-spend --wallet-id=&lt;walletId&gt; [--spend-info='&lt;json&gt;'] [--to=&lt;to&gt;] [--native-amount=&lt;nativeAmount&gt;] [--amount=&lt;amount&gt;] [--token-id=&lt;tokenId&gt;] [--metadata='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/make-spend</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  spendInfo?: {
+    spendTargets: {
+      publicAddress: string | undefined;
+      nativeAmount: string | undefined;
+      uniqueIdentifier: string | undefined;
+      memo: string | undefined;
+      otherParams: {
+        [keys: string]: unknown
+      } | undefined
+    }[];
+    tokenId: string | null;
+    metadata: EdgeMetadata | undefined;
+    networkFeeOption: string | undefined;
+    customNetworkFee: {
+      [keys: string]: unknown
+    } | undefined;
+    rbfTxid: string | undefined;
+    memos: {
+      [keys: string]: unknown
+    }[] | undefined;
+    assetAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction | undefined;
+    savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxAction | undefined;
+    otherParams: {
+      [keys: string]: unknown
+    } | undefined
+  }
+  to?: string
+  nativeAmount?: string
+  amount?: string
+  tokenId?: string | null
+  metadata?: EdgeMetadata
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;spendInfo&quot;: {},
+  &quot;to&quot;: &quot;string&quot;,
+  &quot;nativeAmount&quot;: &quot;12345&quot;,
+  &quot;amount&quot;: &quot;12345&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;metadata&quot;: &quot;&lt;EdgeMetadata&gt;&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>spendInfo</code></td>
+  <td class="ty"><span class="t">{ spendTargets: { publicAddress: string | undefined; nativeAmount: string | undefined; uniqueIdentifier: string | undefined; memo: string | undefined; otherParams: { [keys: string]: unknown; } | undefined; }[]; tokenId: string | null; metadata: EdgeMetadata | undefined; networkFeeOption: string | undefined; customNetworkFee: { [keys: string]: unknown; } | undefined; rbfTxid: string | undefined; memos: { [keys: string]: unknown; }[] | undefined; assetAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeAssetAction | undefined; savedAction: import(&quot;/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types&quot;).EdgeTxAction | undefined; otherParams: { [keys: string]: unknown; } | undefined; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">A full <code>EdgeSpendInfo</code>, used as-is when present. <code>spendTargets</code> is required.</td>
+</tr>
+<tr>
+  <td class="k"><code>to</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Address or BIP21 URI, run through <code>wallet.parseUri</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">How much, in native units.</td>
+</tr>
+<tr>
+  <td class="k"><code>amount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Alias of <code>nativeAmount</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>metadata</code></td>
+  <td class="ty"><span class="t">EdgeMetadata</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wins over anything parsed out of the URI.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;spendInfo&quot;:{},&quot;to&quot;:&quot;string&quot;,&quot;nativeAmount&quot;:&quot;12345&quot;,&quot;amount&quot;:&quot;12345&quot;,&quot;tokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;metadata&quot;:&quot;&lt;EdgeMetadata&gt;&quot;}' \
+  'http://localhost/account/$SESS/wallet/make-spend'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+  transaction: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Session that created the handle; only that session may use it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wallet the handle is bound to, when it belongs to one.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc"><code>EdgeTransaction</code> as it stands after this step. Unsigned after <code>make-spend</code>, signed after <code>sign-tx</code>, and carrying a txid once broadcast.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-INSUFFICIENT_FUNDS" class="err" title="Not enough balance to cover amount plus fee."><span class="st">422</span>INSUFFICIENT_FUNDS</a> <a href="#err-DUST_SPEND" class="err" title="Amount below the network dust threshold."><span class="st">422</span>DUST_SPEND</a> <a href="#err-NO_AMOUNT_SPECIFIED" class="err" title="Zero-amount spend."><span class="st">400</span>NO_AMOUNT_SPECIFIED</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="signTx">
+    <header>
+      <h3><a href="#signTx">Sign a staged transaction.</a></h3>
+      <div class="ids"><code class="cmdname">sign-tx</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.signTx</code></p>
+    <div class="desc"><p>Keeps the same handle and pushes its expiry out another five minutes.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>sign-tx &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/sign-tx/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From <code>make-spend</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;objectId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/sign-tx/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+  transaction: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Session that created the handle; only that session may use it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wallet the handle is bound to, when it belongs to one.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc"><code>EdgeTransaction</code> as it stands after this step. Unsigned after <code>make-spend</code>, signed after <code>sign-tx</code>, and carrying a txid once broadcast.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_WALLET_MISMATCH" class="err" title="The transaction handle belongs to a different wallet."><span class="st">400</span>OBJECT_WALLET_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="broadcastTx">
+    <header>
+      <h3><a href="#broadcastTx">Broadcast a signed transaction.</a></h3>
+      <div class="ids"><code class="cmdname">broadcast-tx</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.broadcastTx</code></p>
+    <div class="desc"><p>The irreversible step: once this returns, the funds have left the wallet.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>broadcast-tx &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/broadcast-tx/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From <code>sign-tx</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;objectId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/broadcast-tx/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The handle survives, so <code>save-tx</code> can still run.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+  transaction: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Session that created the handle; only that session may use it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wallet the handle is bound to, when it belongs to one.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc"><code>EdgeTransaction</code> as it stands after this step. Unsigned after <code>make-spend</code>, signed after <code>sign-tx</code>, and carrying a txid once broadcast.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_WALLET_MISMATCH" class="err" title="The transaction handle belongs to a different wallet."><span class="st">400</span>OBJECT_WALLET_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Broadcasting does not record the transaction locally. Follow with <code>save-tx</code>, or it stays missing from history until a sync finds it.</li></ul></div>
+  </section><section class="endpoint" id="saveTx">
+    <header>
+      <h3><a href="#saveTx">Record a transaction and release its handle.</a></h3>
+      <div class="ids"><code class="cmdname">save-tx</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.saveTx</code></p>
+    <div class="desc"><p>Final step. The handle is gone afterwards, so a second call is a 404.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>save-tx &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/save-tx/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">The handle to persist and release.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;objectId&quot;:&quot;FS8xJ2kQ…&quot;}' \
+  'http://localhost/account/$SESS/save-tx/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+  objectId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true,
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Always true; a failure arrives as an error envelope.</td>
+</tr>
+<tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The handle this call consumed. It is now expired.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_WALLET_MISMATCH" class="err" title="The transaction handle belongs to a different wallet."><span class="st">400</span>OBJECT_WALLET_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="accelerate">
+    <header>
+      <h3><a href="#accelerate">Fee-bump a pending transaction.</a></h3>
+      <div class="ids"><code class="cmdname">accelerate</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.accelerate</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>transaction</code> — Core names the parameter <code>tx</code>. Spelled out here to match the <code>transaction</code> field every staged-transaction response returns.</li></ul></div>
+    <div class="desc"><p>Replace-by-fee, where the plugin supports it. Returns a new unsigned transaction to sign and broadcast.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>accelerate --wallet-id=&lt;walletId&gt; [--object-id=&lt;objectId&gt;] [--transaction='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/accelerate</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  objectId?: string
+  transaction?: {
+    txid: string;
+    currencyCode: string | undefined;
+    nativeAmount: string | undefined;
+    networkFee: string | undefined;
+    walletId: string | undefined
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Handle of the transaction to bump.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">{ txid: string; currencyCode: string | undefined; nativeAmount: string | undefined; networkFee: string | undefined; walletId: string | undefined; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Or the transaction itself.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;objectId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;transaction&quot;:{}}' \
+  'http://localhost/account/$SESS/wallet/accelerate'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>Given objectId the same handle is updated; given a transaction a new one is created.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+  transaction: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Session that created the handle; only that session may use it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wallet the handle is bound to, when it belongs to one.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc"><code>EdgeTransaction</code> as it stands after this step. Unsigned after <code>make-spend</code>, signed after <code>sign-tx</code>, and carrying a txid once broadcast.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_WALLET_MISMATCH" class="err" title="The transaction handle belongs to a different wallet."><span class="st">400</span>OBJECT_WALLET_MISMATCH</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>A plugin that cannot accelerate returns 400 rather than a null transaction.</li></ul></div>
+  </section><section class="endpoint" id="sweepPrivateKeys">
+    <header>
+      <h3><a href="#sweepPrivateKeys">Sweep private keys into this wallet.</a></h3>
+      <div class="ids"><code class="cmdname">sweep-private-keys</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.sweepPrivateKeys</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>spendInfo</code> — Core names this one <code>edgeSpendInfo</code> while <code>makeSpend</code> names the same type <code>spendInfo</code>. Both are <code>spendInfo</code> here.</li></ul></div>
+    <div class="desc"><p>Builds a transaction moving everything from an external key. Returns an unsigned handle: sign, broadcast and save it like any staged spend.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>sweep-private-keys --wallet-id=&lt;walletId&gt; --spend-info='&lt;json&gt;'</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/sweep-private-keys</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  spendInfo: {
+    privateKeys: string[];
+    tokenId: string | null;
+    spendTargets: {
+      publicAddress: string | undefined;
+      nativeAmount: string | undefined;
+      uniqueIdentifier: string | undefined;
+      memo: string | undefined;
+      otherParams: {
+        [keys: string]: unknown
+      } | undefined
+    }[];
+    metadata: EdgeMetadata | undefined;
+    memos: {
+      [keys: string]: unknown
+    }[] | undefined
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;spendInfo&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>spendInfo</code></td>
+  <td class="ty"><span class="t">{ privateKeys: string[]; tokenId: string | null; spendTargets: { publicAddress: string | undefined; nativeAmount: string | undefined; uniqueIdentifier: string | undefined; memo: string | undefined; otherParams: { [keys: string]: unknown; } | undefined; }[]; metadata: EdgeMetadata | undefined; memos: { [keys: string]: unknown; }[] | undefined; }</span></td>
+  <td class="doc">The keys to sweep in <code>privateKeys</code>, plus the optional <code>spendTargets</code>, <code>tokenId</code>, <code>metadata</code> and <code>memos</code> of a spend.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;spendInfo&quot;:{}}' \
+  'http://localhost/account/$SESS/wallet/sweep-private-keys'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+  transaction: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;transaction&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Session that created the handle; only that session may use it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wallet the handle is bound to, when it belongs to one.</td>
+</tr>
+<tr>
+  <td class="k"><code>transaction</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc"><code>EdgeTransaction</code> as it stands after this step. Unsigned after <code>make-spend</code>, signed after <code>sign-tx</code>, and carrying a txid once broadcast.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-INSUFFICIENT_FUNDS" class="err" title="Not enough balance to cover amount plus fee."><span class="st">422</span>INSUFFICIENT_FUNDS</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-TOKEN_NOT_FOUND" class="err" title="Unknown token id for this wallet."><span class="st">404</span>TOKEN_NOT_FOUND</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="signBytes">
+    <header>
+      <h3><a href="#signBytes">Sign arbitrary bytes.</a></h3>
+      <div class="ids"><code class="cmdname">sign-bytes</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.signBytes</code></p><div class="note"><p><strong>Differs from core:</strong></p><ul><li><code>bytes</code> — Core takes a Uint8Array named <code>buf</code>. JSON cannot carry bytes, so this is base64 text.</li></ul></div>
+    <div class="desc"><p>Message signing and proof-of-ownership, for plugins that support it.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>sign-bytes --wallet-id=&lt;walletId&gt; [--bytes=&lt;bytes&gt;] [--other-params='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/sign-bytes</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  bytes?: string
+  otherParams?: {
+    [keys: string]: unknown
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;bytes&quot;: &quot;string&quot;,
+  &quot;otherParams&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>bytes</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Base64. Defaults to empty when absent.</td>
+</tr>
+<tr>
+  <td class="k"><code>otherParams</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Plugin-specific options. Bitcoin needs <code>{ publicAddress }</code>; other plugins take nothing, or refuse the call entirely.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;bytes&quot;:&quot;string&quot;,&quot;otherParams&quot;:{}}' \
+  'http://localhost/account/$SESS/wallet/sign-bytes'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  signature: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;signature&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>signature</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Base64.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Invalid base64 is refused with <code>BAD_REQUEST</code> rather than signed.</li><li>Support is per plugin, and failures surface as <code>500 INTERNAL_ERROR</code> from the plugin rather than as a typed error: litecoin answers &quot;litecoin doesn&#39;t support signBytes&quot;, and bitcoin requires <code>otherParams.publicAddress</code> naming which address to sign with.</li></ul></div>
+  </section><section class="endpoint" id="getPaymentProtocolInfo">
+    <header>
+      <h3><a href="#getPaymentProtocolInfo">Fetch a BIP70 payment request.</a></h3>
+      <div class="ids"><code class="cmdname">get-payment-protocol-info</code><span class="src" title="Declared in">src/cli/engine/routes/spend.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.getPaymentProtocolInfo</code></p>
+    <div class="desc"><p>Feed <code>spendTargets</code> from the result into <code>make-spend</code> to pay it.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>get-payment-protocol-info --wallet-id=&lt;walletId&gt; --payment-protocol-url=&lt;paymentProtocolUrl&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/wallet/get-payment-protocol-info</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  walletId: string
+  paymentProtocolUrl: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;paymentProtocolUrl&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>paymentProtocolUrl</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The payment-request URL.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/wallet/get-payment-protocol-info?walletId=…&amp;paymentProtocolUrl=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>EdgePaymentProtocolInfo</code>: domain, memo, merchant, nativeAmount, spendTargets.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h3 class="sub" id="uri">URIs</h3>
+          <div class="groupdoc"><p>Parsing and building BIP21-style payment URIs through the wallet’s own plugin, so chain-specific quirks are handled for you.</p>
+</div>
+          <section class="endpoint" id="parseUri">
+    <header>
+      <h3><a href="#parseUri">Parse a payment URI or address.</a></h3>
+      <div class="ids"><code class="cmdname">parse-uri</code><span class="src" title="Declared in">src/cli/engine/routes/uri.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.parseUri</code></p>
+    <div class="desc"><p>What the GUI address tile does when you paste or scan something.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>parse-uri --wallet-id=&lt;walletId&gt; --uri=&lt;uri&gt; [--currency-code=&lt;currencyCode&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/parse-uri</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  uri: string
+  currencyCode?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;uri&quot;: &quot;string&quot;,
+  &quot;currencyCode&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>uri</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">A payment URI or a bare address.</td>
+</tr>
+<tr>
+  <td class="k"><code>currencyCode</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Disambiguates on chains that carry several assets.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;uri&quot;:&quot;string&quot;,&quot;currencyCode&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/wallet/parse-uri'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p><code>EdgeParsedUri</code>: publicAddress, nativeAmount, currencyCode, metadata, paymentProtocolUrl, …</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li><code>spend</code> and <code>make-spend</code> run their <code>to</code> field through this same call, so parsing separately is only needed to inspect or confirm first.</li></ul></div>
+  </section><section class="endpoint" id="encodeUri">
+    <header>
+      <h3><a href="#encodeUri">Build a payment URI.</a></h3>
+      <div class="ids"><code class="cmdname">encode-uri</code><span class="src" title="Declared in">src/cli/engine/routes/uri.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>wallet.encodeUri</code></p>
+    <div class="desc"><p>For a receive screen or a QR code.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>encode-uri --wallet-id=&lt;walletId&gt; --public-address=&lt;publicAddress&gt; [--native-amount=&lt;nativeAmount&gt;] [--label=&lt;label&gt;] [--message=&lt;message&gt;] [--currency-code=&lt;currencyCode&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/wallet/encode-uri</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  walletId: string
+  publicAddress: string
+  nativeAmount?: string
+  label?: string
+  message?: string
+  currencyCode?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;publicAddress&quot;: &quot;string&quot;,
+  &quot;nativeAmount&quot;: &quot;12345&quot;,
+  &quot;label&quot;: &quot;string&quot;,
+  &quot;message&quot;: &quot;string&quot;,
+  &quot;currencyCode&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns <code>409 AMBIGUOUS_WALLET_ID</code> with <code>details.candidates</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>publicAddress</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Where the payment should go.</td>
+</tr>
+<tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Amount, in the native unit.</td>
+</tr>
+<tr>
+  <td class="k"><code>label</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">BIP21 <code>label</code>; becomes <code>metadata.name</code> when parsed back.</td>
+</tr>
+<tr>
+  <td class="k"><code>message</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">BIP21 <code>message</code>; becomes <code>metadata.notes</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>currencyCode</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Disambiguates on chains that carry several assets.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;walletId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;publicAddress&quot;:&quot;string&quot;,&quot;nativeAmount&quot;:&quot;12345&quot;,&quot;label&quot;:&quot;string&quot;,&quot;message&quot;:&quot;string&quot;,&quot;currencyCode&quot;:&quot;string&quot;}' \
+  'http://localhost/account/$SESS/wallet/encode-uri'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  uri: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;uri&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>uri</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The encoded URI, ready for a QR code.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-WALLET_NOT_FOUND" class="err" title="No wallet matches that id or prefix."><span class="st">404</span>WALLET_NOT_FOUND</a> <a href="#err-AMBIGUOUS_WALLET_ID" class="err" title="A wallet id prefix matched more than one wallet."><span class="st">409</span>AMBIGUOUS_WALLET_ID</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Only these five fields are read; a fuller <code>EdgeEncodeUri</code> has its extras ignored.</li></ul></div>
+  </section><h2 id="local-settings">Local settings</h2>
+      <div class="groupdoc"><p>Device-local account settings, stored outside the synced repos. They follow the account but never leave the machine.</p>
+</div>
+      <h3 class="sub" id="localSettings">Local settings</h3>
+          <div class="groupdoc"><p>Device-local account settings, stored outside the synced repos.</p>
+</div>
+          <section class="endpoint" id="localSettings">
+    <header>
+      <h3><a href="#localSettings">Local settings.</a></h3>
+      <div class="ids"><code class="cmdname">local-settings</code><span class="src" title="Declared in">src/cli/engine/routes/localSettings.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>GUI code (src/util/localAccountSettings), reached through account.localDisklet.</em></p>
+    <div class="desc"><p>Device-local account settings, stored in <code>Settings.json</code> on <code>account.localDisklet</code>. They are not synced — a phone and a CLI keep separate copies unless they share an Edge data directory.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>local-settings</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/local-settings</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/local-settings'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  spamFilterOn: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;spamFilterOn&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>spamFilterOn</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Hide spam transactions in <code>get-transactions</code> results. Defaults to <code>true</code>, matching the GUI. The filter hides rows; it never changes stored metadata.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="changeLocalSettings">
+    <header>
+      <h3><a href="#changeLocalSettings">Change local settings.</a></h3>
+      <div class="ids"><code class="cmdname">local-settings</code><span class="src" title="Declared in">src/cli/engine/routes/localSettings.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>GUI code (src/util/localAccountSettings).</em></p>
+    <div class="desc"><p>Writes device-local account settings. Every option is a field on the body; <code>spamFilterOn</code> is the only one today, and new options are added alongside it.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>local-settings --spam-filter-on=true|false</code></pre>
+    
+    
+    <div class="note"><p>With no flag the command reads; with one it writes.</p>
+</div>
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/change-local-settings</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  spamFilterOn: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;spamFilterOn&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>spamFilterOn</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Hide spam transactions in <code>get-transactions</code> results. Defaults to <code>true</code>, matching the GUI. The filter hides rows; it never changes stored metadata.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;spamFilterOn&quot;:true}' \
+  'http://localhost/account/$SESS/change-local-settings'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  spamFilterOn: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;spamFilterOn&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>spamFilterOn</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Hide spam transactions in <code>get-transactions</code> results. Defaults to <code>true</code>, matching the GUI. The filter hides rows; it never changes stored metadata.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Omitting a field is a <code>400</code>, not a no-op, so a caller cannot clear a setting by accident.</li></ul></div>
+  </section><h2 id="rates">Exchange rates</h2>
+      <div class="groupdoc"><p>Fiat and crypto pricing, current and historical.</p>
+</div>
+      <h3 class="sub" id="rates">Exchange rates</h3>
+          <div class="groupdoc"><p>Historical and current rates through the same batching queue the GUI uses. No session required.</p>
+</div>
+          <section class="endpoint" id="ratesQuery">
+    <header>
+      <h3><a href="#ratesQuery">Batch crypto and fiat rate lookups.</a></h3>
+      <div class="ids"><code class="cmdname">rates-query</code><span class="src" title="Declared in">src/cli/engine/routes/rates.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>GUI code (src/util/exchangeRates): getHistoricalCryptoRate and getHistoricalFiatRate.</em></p>
+    <div class="desc"><p>Concurrent lookups share one rates-server queue, so asking for many rates at once costs a single upstream request.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>rates-query [--crypto='&lt;json&gt;'] [--fiat='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/rates/query</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  crypto?: {
+    pluginId: string;
+    tokenId: string | null;
+    targetFiat: string | undefined;
+    date: string | undefined
+  }[]
+  fiat?: {
+    fiatCode: string;
+    targetFiat: string | undefined;
+    date: string | undefined
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;crypto&quot;: [
+    {}
+  ],
+  &quot;fiat&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>crypto</code></td>
+  <td class="ty"><span class="t">{ pluginId: string; tokenId: string | null; targetFiat: string | undefined; date: string | undefined; }[]</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Crypto rates to fetch.</td>
+</tr>
+<tr>
+  <td class="k"><code>fiat</code></td>
+  <td class="ty"><span class="t">{ fiatCode: string; targetFiat: string | undefined; date: string | undefined; }[]</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Fiat rates to fetch.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;crypto&quot;:[{}],&quot;fiat&quot;:[{}]}' \
+  'http://localhost/rates/query'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  crypto: {
+    pluginId: string;
+    tokenId: string | null;
+    targetFiat: string;
+    date: string;
+    rate: number
+  }[]
+  fiat: {
+    fiatCode: string;
+    targetFiat: string;
+    date: string;
+    rate: number
+  }[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;crypto&quot;: [
+    {}
+  ],
+  &quot;fiat&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>crypto</code></td>
+  <td class="ty"><span class="t">{ pluginId: string; tokenId: string | null; targetFiat: string; date: string; rate: number; }[]</span></td>
+  <td class="doc">Always present; empty when no crypto rates were requested.</td>
+</tr>
+<tr>
+  <td class="k"><code>fiat</code></td>
+  <td class="ty"><span class="t">{ fiatCode: string; targetFiat: string; date: string; rate: number; }[]</span></td>
+  <td class="doc">Always present; empty when no fiat rates were requested.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>A rate the server cannot supply comes back as <code>0</code> rather than an error, so check for zero before dividing.</li></ul></div>
+  </section><section class="endpoint" id="ratesUsdToNative">
+    <header>
+      <h3><a href="#ratesUsdToNative">Convert a USD amount into native units.</a></h3>
+      <div class="ids"><code class="cmdname">rates-usd-to-native</code><span class="src" title="Declared in">src/cli/engine/routes/rates.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>GUI code (src/util/exchangeRates): getHistoricalCryptoRate.</em></p>
+    <div class="desc"><p>Turns a fiat notional into the native amount a spend needs.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>rates-usd-to-native --usd-amount=&lt;usdAmount&gt; --plugin-id=&lt;pluginId&gt; [--token-id=&lt;tokenId&gt;] --multiplier=&lt;multiplier&gt; [--date=&lt;date&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/rates/usd-to-native</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  usdAmount: string
+  pluginId: string
+  tokenId?: string | null
+  multiplier: string
+  date?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;usdAmount&quot;: &quot;12345&quot;,
+  &quot;pluginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;multiplier&quot;: &quot;string&quot;,
+  &quot;date&quot;: &quot;2026-09-02T16:35:00.000Z&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>usdAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">A positive decimal string.</td>
+</tr>
+<tr>
+  <td class="k"><code>pluginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Which chain to price.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to the native asset.</td>
+</tr>
+<tr>
+  <td class="k"><code>multiplier</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Native units per whole coin, as a positive decimal string. This route is not session-scoped, so the engine cannot read the asset’s denomination from core and will not guess one.</td>
+</tr>
+<tr>
+  <td class="k"><code>date</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">ISO-8601. Omitted, the current time is sent to the rates server.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;usdAmount&quot;:&quot;12345&quot;,&quot;pluginId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;tokenId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;multiplier&quot;:&quot;string&quot;,&quot;date&quot;:&quot;2026-09-02T16:35:00.000Z&quot;}' \
+  'http://localhost/rates/usd-to-native'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  usdAmount: number
+  pluginId: string
+  tokenId: string | null
+  multiplier: string
+  date: string
+  rate: number
+  displayAmount: string
+  nativeAmount: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;usdAmount&quot;: 0,
+  &quot;pluginId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;tokenId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;multiplier&quot;: &quot;string&quot;,
+  &quot;date&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;rate&quot;: 1,
+  &quot;displayAmount&quot;: &quot;12345&quot;,
+  &quot;nativeAmount&quot;: &quot;12345&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>usdAmount</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Echoed as a number, though it is sent as a string.</td>
+</tr>
+<tr>
+  <td class="k"><code>pluginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Currency plugin the amount was converted for.</td>
+</tr>
+<tr>
+  <td class="k"><code>tokenId</code></td>
+  <td class="ty"><span class="t">string | null</span></td>
+  <td class="doc">The asset, or null for the chain’s own coin.</td>
+</tr>
+<tr>
+  <td class="k"><code>multiplier</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Native units per whole coin, which is what <code>displayAmount</code> was multiplied by to reach <code>nativeAmount</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>date</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The timestamp actually used for the rate.</td>
+</tr>
+<tr>
+  <td class="k"><code>rate</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">USD per whole coin at that date.</td>
+</tr>
+<tr>
+  <td class="k"><code>displayAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Whole coins, to 8 decimal places.</td>
+</tr>
+<tr>
+  <td class="k"><code>nativeAmount</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What a spend actually takes.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NOT_FOUND" class="err" title="No route matched, or a generic missing resource."><span class="st">404</span>NOT_FOUND</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li><code>displayAmount</code> is rounded to 8 decimals before conversion, so assets with finer precision lose the tail. For an exact figure use <code>rates-query</code> and do the arithmetic yourself.</li><li><code>multiplier</code> is required. The engine has no logged-in account here, so it cannot read the asset&#39;s denomination from core, and a guessed multiplier would return a <code>nativeAmount</code> wrong by orders of magnitude under a field documented as what a spend takes.</li></ul></div>
+  </section><h2 id="objects">Object handles</h2>
+      <div class="groupdoc"><p>A core value with methods on it cannot cross JSON, so the engine keeps it and hands back an id. These read and release any of them.</p>
+</div>
+      <h3 class="sub" id="objects">Object handles</h3>
+          <div class="groupdoc"><p>A core value with methods on it — a staged transaction, a swap quote, a pending login — cannot cross JSON, so the engine keeps it and hands back an id. These read and release any of them.</p>
+</div>
+          <section class="endpoint" id="getObject">
+    <header>
+      <h3><a href="#getObject">Inspect an object handle.</a></h3>
+      <div class="ids"><code class="cmdname">object-get</code><span class="src" title="Declared in">src/cli/engine/routes/objects.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine handle store; core identifies these values by object reference.</em></p>
+    <div class="desc"><p>Works for every kind: transactions, pending logins, swap quotes and lobbies.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>object-get &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/account/{sessionId}/object/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">An ephemeral object handle id.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/account/$SESS/object/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The handle fields, plus a <code>value</code> holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports <code>value: null</code>.</p>
+</div><div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  kind: string
+  createdAt: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;kind&quot;: &quot;string&quot;,
+  &quot;createdAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;sessionId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;walletId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Handle for the value the engine is holding. Pass it to the calls that consume it.</td>
+</tr>
+<tr>
+  <td class="k"><code>kind</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">What the handle refers to, which decides the calls that accept it.</td>
+</tr>
+<tr>
+  <td class="k"><code>createdAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine took the handle.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine drops the handle. Handles live 5 minutes.</td>
+</tr>
+<tr>
+  <td class="k"><code>sessionId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Session that created the handle; only that session may use it.</td>
+</tr>
+<tr>
+  <td class="k"><code>walletId</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Wallet the handle is bound to, when it belongs to one.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_IN_USE" class="err" title="A consuming call on this handle is already in flight. Fund-moving calls outlive the client socket timeout, so a retry is refused rather than sending twice."><span class="st">409</span>OBJECT_IN_USE</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Reading does not extend the TTL. Only a step that updates the value does.</li></ul></div>
+  </section><section class="endpoint" id="deleteObject">
+    <header>
+      <h3><a href="#deleteObject">Release an object handle.</a></h3>
+      <div class="ids"><code class="cmdname">object-delete</code><span class="src" title="Declared in">src/cli/engine/routes/objects.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine handle store.</em></p>
+    <div class="desc"><p>Runs the handle&#39;s cleanup — closing a swap quote, cancelling a pending login — instead of waiting out the TTL.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>object-delete &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/account/{sessionId}/object/delete/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">From a successful login. The CLI supplies this from <code>session.json</code>, <code>--session</code>, or <code>EDGE_CLI_SESSION</code>.</td></tr><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">An ephemeral object handle id.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/account/$SESS/object/delete/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+  objectId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true,
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Always true; a failure arrives as an error envelope.</td>
+</tr>
+<tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The handle this call consumed. It is now expired.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_EXPIRED" class="err" title="The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead."><span class="st">410</span>OBJECT_EXPIRED</a> <a href="#err-OBJECT_IN_USE" class="err" title="A consuming call on this handle is already in flight. Fund-moving calls outlive the client socket timeout, so a retry is refused rather than sending twice."><span class="st">409</span>OBJECT_IN_USE</a> <a href="#err-OBJECT_SESSION_MISMATCH" class="err" title="The handle belongs to a different session."><span class="st">400</span>OBJECT_SESSION_MISMATCH</a> <a href="#err-INVALID_SESSION" class="err" title="Unknown `sessionId`."><span class="st">401</span>INVALID_SESSION</a> <a href="#err-SESSION_EXPIRED" class="err" title="Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`."><span class="st">401</span>SESSION_EXPIRED</a></p>
+  </div>
+    
+  </section><h2 id="admin">Admin</h2>
+      <div class="groupdoc"><p>The <code>$internalStuff</code> escape hatch: login-server and sync-repo access that no ordinary caller needs.</p>
+</div>
+      <h3 class="sub" id="admin">Admin</h3>
+          <div class="groupdoc"><p><strong>Debugging only — not for production apps.</strong> These reach into <code>context.$internalStuff</code>, the private surface of <code>edge-core-js</code>, and can corrupt an account’s synced repos. They take no <code>sessionId</code>: they act on the context, not on a logged-in account.</p>
+</div>
+          <section class="endpoint" id="adminAuthRequest">
+    <header>
+      <h3><a href="#adminAuthRequest">Raw login-server request.</a></h3>
+      <div class="ids"><code class="cmdname">admin-auth-request</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.authRequest</code></p>
+    <div class="desc"><p>Sends an arbitrary request with the context&#39;s credentials attached. Debugging only — this is core&#39;s private surface.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-auth-request --method=&lt;method&gt; --path=&lt;path&gt; [--body='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/auth-request</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  method: string
+  path: string
+  body?: {
+    [keys: string]: unknown
+  }
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;method&quot;: &quot;string&quot;,
+  &quot;path&quot;: &quot;string&quot;,
+  &quot;body&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>method</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">HTTP method, e.g. <code>GET</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>path</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Login-server path, not an engine path.</td>
+</tr>
+<tr>
+  <td class="k"><code>body</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Request body, when the method takes one.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;method&quot;:&quot;string&quot;,&quot;path&quot;:&quot;string&quot;,&quot;body&quot;:{}}' \
+  'http://localhost/admin/auth-request'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>Whatever the login server returned.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminHashUsername">
+    <header>
+      <h3><a href="#adminHashUsername">Hash a username.</a></h3>
+      <div class="ids"><code class="cmdname">admin-hash-username</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.hashUsername</code></p>
+    <div class="desc"><p>Reproduces the login server&#39;s hashing, to derive a login id offline.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-hash-username --username=&lt;username&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/admin/hash-username</code></p>
+    
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  username: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;username&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>username</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The name to hash.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/admin/hash-username?username=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  loginId: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;loginId&quot;: &quot;FS8xJ2kQ…&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>loginId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Base58.</td>
+</tr></tbody></table>
+  </div>
+    
+  </div>
+    
+  </section><section class="endpoint" id="adminMakeLobby">
+    <header>
+      <h3><a href="#adminMakeLobby">Create a lobby.</a></h3>
+      <div class="ids"><code class="cmdname">admin-make-lobby</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.makeLobby</code></p>
+    <div class="desc"><p>A lobby polls the login server until closed, so the engine parks it under a <code>lobby_</code> handle and closes it on expiry rather than leaking the poll.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-make-lobby [--lobby-request='&lt;json&gt;'] [--period-seconds=&lt;period&gt;]</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/make-lobby</code></p>
+    
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  lobbyRequest?: {
+    [keys: string]: unknown
+  }
+  period?: number
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;lobbyRequest&quot;: {},
+  &quot;period&quot;: 0
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>lobbyRequest</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Defaults to <code>{}</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>period</code></td>
+  <td class="ty"><span class="t">number</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Poll interval in seconds. At least 0.25; the engine converts to the milliseconds core takes.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;lobbyRequest&quot;:{},&quot;period&quot;:0}' \
+  'http://localhost/admin/make-lobby'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  objectId: string
+  expiresAt: string
+  lobbyId: string
+  replies: unknown[]
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;objectId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;expiresAt&quot;: &quot;2026-09-02T16:35:00.000Z&quot;,
+  &quot;lobbyId&quot;: &quot;FS8xJ2kQ…&quot;,
+  &quot;replies&quot;: [
+    {}
+  ]
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>objectId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The parked handle.</td>
+</tr>
+<tr>
+  <td class="k"><code>expiresAt</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">When the engine closes the lobby and stops polling.</td>
+</tr>
+<tr>
+  <td class="k"><code>lobbyId</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Identifies the lobby to the party joining it.</td>
+</tr>
+<tr>
+  <td class="k"><code>replies</code></td>
+  <td class="ty"><span class="t">unknown[]</span></td>
+  <td class="doc">Empty at creation; re-read to see replies.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Release it with <code>admin-lobby-handle-delete</code>, or the poll runs for the full five minutes.</li></ul></div>
+  </section><section class="endpoint" id="adminDeleteLobbyHandle">
+    <header>
+      <h3><a href="#adminDeleteLobbyHandle">Close a parked lobby.</a></h3>
+      <div class="ids"><code class="cmdname">admin-lobby-handle-delete</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core none"><span class="lbl">core</span><em>Engine handle store for a lobby created via makeLobby.</em></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-lobby-handle-delete &lt;objectId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/lobby-handle/delete/{objectId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>objectId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">An ephemeral object handle id.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  'http://localhost/admin/lobby-handle/delete/$OBJECTID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  ok: boolean
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;ok&quot;: true
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>ok</code></td>
+  <td class="ty"><span class="t">boolean</span></td>
+  <td class="doc">Always true; a failure arrives as an error envelope.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-OBJECT_NOT_FOUND" class="err" title="No handle with that `objectId`."><span class="st">404</span>OBJECT_NOT_FOUND</a> <a href="#err-OBJECT_KIND_MISMATCH" class="err" title="The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`)."><span class="st">400</span>OBJECT_KIND_MISMATCH</a> <a href="#err-OBJECT_IN_USE" class="err" title="A consuming call on this handle is already in flight. Fund-moving calls outlive the client socket timeout, so a retry is refused rather than sending twice."><span class="st">409</span>OBJECT_IN_USE</a></p>
+  </div>
+    <div class="pane notes"><h4>Notes</h4><ul><li>Not under <code>/account/{sessionId}/objects/</code>, because admin lobbies belong to no session.</li></ul></div>
+  </section><section class="endpoint" id="adminFetchLobbyRequest">
+    <header>
+      <h3><a href="#adminFetchLobbyRequest">Read a lobby's contents.</a></h3>
+      <div class="ids"><code class="cmdname">admin-fetch-lobby-request</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.fetchLobbyRequest</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-fetch-lobby-request &lt;lobbyId&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/admin/fetch-lobby-request/{lobbyId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>lobbyId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Which lobby to read.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/admin/fetch-lobby-request/$LOBBYID?lobbyId=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The raw lobby request.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminSendLobbyReply">
+    <header>
+      <h3><a href="#adminSendLobbyReply">Reply to a lobby.</a></h3>
+      <div class="ids"><code class="cmdname">admin-send-lobby-reply</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.sendLobbyReply</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-send-lobby-reply &lt;lobbyId&gt; --lobby-request='&lt;json&gt;' [--reply-data='&lt;json&gt;']</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/send-lobby-reply/{lobbyId}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>lobbyId</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Which lobby to answer.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  lobbyRequest: {
+    [keys: string]: unknown
+  }
+  replyData?: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;lobbyRequest&quot;: {},
+  &quot;replyData&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>lobbyRequest</code></td>
+  <td class="ty"><span class="t">{ [keys: string]: unknown; }</span></td>
+  <td class="doc">Normally the object from <code>admin-fetch-lobby-request</code>.</td>
+</tr>
+<tr>
+  <td class="k"><code>replyData</code></td>
+  <td class="ty"><span class="t">unknown</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Payload for the requester.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;lobbyId&quot;:&quot;FS8xJ2kQ…&quot;,&quot;lobbyRequest&quot;:{},&quot;replyData&quot;:{}}' \
+  'http://localhost/admin/send-lobby-reply/$LOBBYID'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminSyncRepo">
+    <header>
+      <h3><a href="#adminSyncRepo">Sync a repo.</a></h3>
+      <div class="ids"><code class="cmdname">admin-sync-repo</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.syncRepo</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-sync-repo &lt;syncKey&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/sync-repo/{syncKey}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>syncKey</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Base58 repo sync key.</td></tr></tbody></table>
+    
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;syncKey&quot;:&quot;string&quot;}' \
+  'http://localhost/admin/sync-repo/$SYNCKEY'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="note"><p>The changeset summary.</p>
+</div><pre class="ts"><code>unknown</code></pre>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a> <a href="#err-NETWORK_ERROR" class="err" title="Could not reach an Edge server."><span class="st">503</span>NETWORK_ERROR</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminRepoList">
+    <header>
+      <h3><a href="#adminRepoList">List repo contents.</a></h3>
+      <div class="ids"><code class="cmdname">admin-repo-list</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.getRepoDisklet</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-repo-list &lt;syncKey&gt; [--path=&lt;path&gt;] --data-key=&lt;dataKey&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/admin/repo-list/{syncKey}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>syncKey</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Base58 repo sync key.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  path?: string
+  dataKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;path&quot;: &quot;string&quot;,
+  &quot;dataKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>path</code></td>
+  <td class="ty"><span class="t">string</span> <span class="flag opt">optional</span></td>
+  <td class="doc">Subdirectory. Defaults to the repo root.</td>
+</tr>
+<tr>
+  <td class="k"><code>dataKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Base58 repo data key.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/admin/repo-list/$SYNCKEY?syncKey=…&amp;dataKey=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  listing: unknown
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;listing&quot;: {}
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>listing</code></td>
+  <td class="ty"><span class="t">unknown</span></td>
+  <td class="doc">Path to entry type: <code>file</code> or <code>folder</code>.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminRepoGet">
+    <header>
+      <h3><a href="#adminRepoGet">Read a repo file.</a></h3>
+      <div class="ids"><code class="cmdname">admin-repo-get</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.getRepoDisklet</code></p>
+    
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-repo-get &lt;syncKey&gt; --path=&lt;path&gt; --data-key=&lt;dataKey&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-GET">GET</span><code>/admin/repo-get/{syncKey}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>syncKey</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Base58 repo sync key.</td></tr></tbody></table>
+    <div class="shape">
+    <div class="shape-h">Query</div>
+    <pre class="ts"><code>{
+  path: string
+  dataKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;path&quot;: &quot;string&quot;,
+  &quot;dataKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>path</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Path within the repo.</td>
+</tr>
+<tr>
+  <td class="k"><code>dataKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Base58 repo data key.</td>
+</tr></tbody></table>
+  </div>
+    
+    
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  'http://localhost/admin/repo-get/$SYNCKEY?path=…&amp;syncKey=…&amp;dataKey=…'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">200</span></h4>
+    <div class="shape">
+    <div class="shape-h">Response body</div>
+    <pre class="ts"><code>{
+  text: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;text&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>text</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The file contents.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Errors</h5><p class="errs"><a href="#err-NOT_FOUND" class="err" title="No route matched, or a generic missing resource."><span class="st">404</span>NOT_FOUND</a> <a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminRepoSet">
+    <header>
+      <h3><a href="#adminRepoSet">Write a repo file.</a></h3>
+      <div class="ids"><code class="cmdname">admin-repo-set</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.getRepoDisklet</code></p>
+    <div class="desc"><p>Writes directly into a synced repo, bypassing every core-level invariant. A malformed write can break the account for real clients.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-repo-set &lt;syncKey&gt; --path=&lt;path&gt; --text=&lt;text&gt; --data-key=&lt;dataKey&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/repo-set/{syncKey}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>syncKey</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Base58 repo sync key.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  path: string
+  text: string
+  dataKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;path&quot;: &quot;string&quot;,
+  &quot;text&quot;: &quot;string&quot;,
+  &quot;dataKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>path</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Path within the repo.</td>
+</tr>
+<tr>
+  <td class="k"><code>text</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">The contents to write.</td>
+</tr>
+<tr>
+  <td class="k"><code>dataKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Base58 repo data key.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;path&quot;:&quot;string&quot;,&quot;text&quot;:&quot;string&quot;,&quot;syncKey&quot;:&quot;string&quot;,&quot;dataKey&quot;:&quot;string&quot;}' \
+  'http://localhost/admin/repo-set/$SYNCKEY'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a></p>
+  </div>
+    
+  </section><section class="endpoint" id="adminRepoDelete">
+    <header>
+      <h3><a href="#adminRepoDelete">Delete a repo file.</a></h3>
+      <div class="ids"><code class="cmdname">admin-repo-delete</code><span class="src" title="Declared in">src/cli/engine/routes/admin.ts</span></div>
+    </header>
+    <p class="core"><span class="lbl">core</span><code>context.$internalStuff.getRepoDisklet</code></p>
+    <div class="desc"><p>Destructive, and not undoable from this API.</p>
+</div>
+    <div class="panes"><div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>admin-repo-delete &lt;syncKey&gt; --path=&lt;path&gt; --data-key=&lt;dataKey&gt;</code></pre>
+    
+    
+    
+  </div><div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-POST">POST</span><code>/admin/repo-delete/{syncKey}</code></p>
+    <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>syncKey</code></td><td class="ty"><span class="t">string</span></td><td class="doc">Base58 repo sync key.</td></tr></tbody></table>
+    
+    
+    <div class="shape">
+    <div class="shape-h">Request body</div>
+    <pre class="ts"><code>{
+  path: string
+  dataKey: string
+}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>{
+  &quot;path&quot;: &quot;string&quot;,
+  &quot;dataKey&quot;: &quot;string&quot;
+}</code></pre></details>
+    <table class="fields"><tbody><tr>
+  <td class="k"><code>path</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Path within the repo.</td>
+</tr>
+<tr>
+  <td class="k"><code>dataKey</code></td>
+  <td class="ty"><span class="t">string</span></td>
+  <td class="doc">Base58 repo data key.</td>
+</tr></tbody></table>
+  </div>
+    <h5>Example</h5>
+    <pre class="ex"><code>curl --unix-socket &quot;$SOCK&quot; \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{&quot;path&quot;:&quot;string&quot;,&quot;syncKey&quot;:&quot;string&quot;,&quot;dataKey&quot;:&quot;string&quot;}' \
+  'http://localhost/admin/repo-delete/$SYNCKEY'</code></pre>
+  </div></div>
+    <div class="pane resp">
+    <h4>Response <span class="st ok">204</span></h4>
+    <p class="lead dim">No body.</p>
+    <h5>Errors</h5><p class="errs"><a href="#err-BAD_REQUEST" class="err" title="Malformed JSON, or a missing / wrongly typed field."><span class="st">400</span>BAD_REQUEST</a></p>
+  </div>
+    
+  </section>
+<h2 id="errors">Error codes</h2>
+<table class="fields"><tbody><tr id="err-BAD_REQUEST"><td class="k"><code>BAD_REQUEST</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">engine</span></td>
+        <td class="doc">Malformed JSON, or a missing / wrongly typed field.</td></tr><tr id="err-MISSING_BITWAVE_ACCOUNT_ID"><td class="k"><code>MISSING_BITWAVE_ACCOUNT_ID</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">engine</span></td>
+        <td class="doc">Bitwave export requested with no account id in the query and none saved in the wallet’s <code>exportTxInfo.json</code>.</td></tr><tr id="err-OBJECT_KIND_MISMATCH"><td class="k"><code>OBJECT_KIND_MISMATCH</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">engine</span></td>
+        <td class="doc">The handle exists but is a different kind (e.g. a swap quote passed to <code>sign-tx</code>).</td></tr><tr id="err-OBJECT_SESSION_MISMATCH"><td class="k"><code>OBJECT_SESSION_MISMATCH</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">engine</span></td>
+        <td class="doc">The handle belongs to a different session.</td></tr><tr id="err-OBJECT_WALLET_MISMATCH"><td class="k"><code>OBJECT_WALLET_MISMATCH</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">engine</span></td>
+        <td class="doc">The transaction handle belongs to a different wallet.</td></tr><tr id="err-INVALID_SESSION"><td class="k"><code>INVALID_SESSION</code></td>
+        <td class="ty"><span class="st">401</span><span class="dim">engine</span></td>
+        <td class="doc">Unknown <code>sessionId</code>.</td></tr><tr id="err-SESSION_EXPIRED"><td class="k"><code>SESSION_EXPIRED</code></td>
+        <td class="ty"><span class="st">401</span><span class="dim">engine</span></td>
+        <td class="doc">Auto-logged-out after the account’s idle timeout. An explicitly logged-out session is gone rather than expired, and answers <code>INVALID_SESSION</code>.</td></tr><tr id="err-NOT_FOUND"><td class="k"><code>NOT_FOUND</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">No route matched, or a generic missing resource.</td></tr><tr id="err-NO_LOGIN_REQUEST"><td class="k"><code>NO_LOGIN_REQUEST</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">The lobby exists but carries no pending login request.</td></tr><tr id="err-OBJECT_NOT_FOUND"><td class="k"><code>OBJECT_NOT_FOUND</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">No handle with that <code>objectId</code>.</td></tr><tr id="err-PENDING_LOGIN_NOT_FOUND"><td class="k"><code>PENDING_LOGIN_NOT_FOUND</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">No pending Edge login with that <code>pendingId</code>.</td></tr><tr id="err-TOKEN_NOT_FOUND"><td class="k"><code>TOKEN_NOT_FOUND</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">Unknown token id for this wallet.</td></tr><tr id="err-UNAUTHORIZED"><td class="k"><code>UNAUTHORIZED</code></td>
+        <td class="ty"><span class="st">401</span><span class="dim">engine</span></td>
+        <td class="doc">The TCP transport requires the bearer token from the engine run file in an <code>X-Edge-Token</code> header. The unix socket needs none: its <code>0600</code> mode is the check.</td></tr><tr id="err-FORBIDDEN"><td class="k"><code>FORBIDDEN</code></td>
+        <td class="ty"><span class="st">403</span><span class="dim">engine</span></td>
+        <td class="doc">A TCP request carried an <code>Origin</code> header, or a <code>Host</code> that is not the address the listener is bound to. Both are refused so a web page cannot reach the engine, directly or by rebinding a name onto its port.</td></tr><tr id="err-USER_NOT_FOUND"><td class="k"><code>USER_NOT_FOUND</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">No local user matches that username or login id.</td></tr><tr id="err-WALLET_NOT_FOUND"><td class="k"><code>WALLET_NOT_FOUND</code></td>
+        <td class="ty"><span class="st">404</span><span class="dim">engine</span></td>
+        <td class="doc">No wallet matches that id or prefix.</td></tr><tr id="err-ENGINE_UNAVAILABLE"><td class="k"><code>ENGINE_UNAVAILABLE</code></td>
+        <td class="ty"><span class="st">503</span><span class="dim">client</span></td>
+        <td class="doc">The client could not reach or start an engine. Written by the client, so it never arrives over the wire; exit code 7.</td></tr><tr id="err-USAGE"><td class="k"><code>USAGE</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">client</span></td>
+        <td class="doc">Bad argv: an unknown command or flag, a missing flag value, or an unparseable structured flag. Written by the client; exit code 2.</td></tr><tr id="err-METHOD_NOT_ALLOWED"><td class="k"><code>METHOD_NOT_ALLOWED</code></td>
+        <td class="ty"><span class="st">405</span><span class="dim">engine</span></td>
+        <td class="doc">The path exists but not for this HTTP method.</td></tr><tr id="err-AMBIGUOUS_WALLET_ID"><td class="k"><code>AMBIGUOUS_WALLET_ID</code></td>
+        <td class="ty"><span class="st">409</span><span class="dim">engine</span></td>
+        <td class="doc">A wallet id prefix matched more than one wallet. <span class="dim">details: <code>details.candidates</code></span></td></tr><tr id="err-OBJECT_EXPIRED"><td class="k"><code>OBJECT_EXPIRED</code></td>
+        <td class="ty"><span class="st">410</span><span class="dim">engine</span></td>
+        <td class="doc">The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers <code>OBJECT_NOT_FOUND</code> instead.</td></tr><tr id="err-OBJECT_IN_USE"><td class="k"><code>OBJECT_IN_USE</code></td>
+        <td class="ty"><span class="st">409</span><span class="dim">engine</span></td>
+        <td class="doc">A consuming call on this handle is already in flight. Fund-moving calls outlive the client socket timeout, so a retry is refused rather than sending twice.</td></tr><tr id="err-PAYLOAD_TOO_LARGE"><td class="k"><code>PAYLOAD_TOO_LARGE</code></td>
+        <td class="ty"><span class="st">413</span><span class="dim">engine</span></td>
+        <td class="doc">Request body over 4 MiB.</td></tr><tr id="err-UNSUPPORTED_MEDIA_TYPE"><td class="k"><code>UNSUPPORTED_MEDIA_TYPE</code></td>
+        <td class="ty"><span class="st">415</span><span class="dim">engine</span></td>
+        <td class="doc">Body present but not <code>application/json</code>.</td></tr><tr id="err-INTERNAL_ERROR"><td class="k"><code>INTERNAL_ERROR</code></td>
+        <td class="ty"><span class="st">500</span><span class="dim">engine</span></td>
+        <td class="doc">Unmapped engine or plugin failure.</td></tr><tr id="err-ENGINE_SHUTTING_DOWN"><td class="k"><code>ENGINE_SHUTTING_DOWN</code></td>
+        <td class="ty"><span class="st">503</span><span class="dim">engine</span></td>
+        <td class="doc">Idle or explicit shutdown already in progress.</td></tr><tr id="err-USERNAME_ERROR"><td class="k"><code>USERNAME_ERROR</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">core</span></td>
+        <td class="doc">Unknown username, or an invalid recovery key.</td></tr><tr id="err-NO_AMOUNT_SPECIFIED"><td class="k"><code>NO_AMOUNT_SPECIFIED</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">core</span></td>
+        <td class="doc">Zero-amount spend.</td></tr><tr id="err-SAME_CURRENCY"><td class="k"><code>SAME_CURRENCY</code></td>
+        <td class="ty"><span class="st">400</span><span class="dim">core</span></td>
+        <td class="doc">Swap between identical currencies.</td></tr><tr id="err-PASSWORD_ERROR"><td class="k"><code>PASSWORD_ERROR</code></td>
+        <td class="ty"><span class="st">401</span><span class="dim">core</span></td>
+        <td class="doc">Wrong password, PIN, or recovery answers. <span class="dim">details: <code>details.wait</code> (seconds) when rate-limited</span></td></tr><tr id="err-OTP_REQUIRED"><td class="k"><code>OTP_REQUIRED</code></td>
+        <td class="ty"><span class="st">401</span><span class="dim">core</span></td>
+        <td class="doc">Missing or wrong 2FA token. <span class="dim">details: <code>reason</code> (<code>ip</code>|<code>otp</code>), <code>loginId</code>, <code>resetToken</code>, <code>resetDate</code>, <code>voucherId</code>, <code>voucherAuth</code>, <code>voucherActivates</code></span></td></tr><tr id="err-CHALLENGE_REQUIRED"><td class="k"><code>CHALLENGE_REQUIRED</code></td>
+        <td class="ty"><span class="st">403</span><span class="dim">core</span></td>
+        <td class="doc">The login server wants a CAPTCHA. Retry with <code>challengeId</code>. <span class="dim">details: <code>challengeId</code>, <code>challengeUri</code></span></td></tr><tr id="err-PIN_DISABLED"><td class="k"><code>PIN_DISABLED</code></td>
+        <td class="ty"><span class="st">403</span><span class="dim">core</span></td>
+        <td class="doc">PIN login is not enabled on this device.</td></tr><tr id="err-SWAP_PERMISSION"><td class="k"><code>SWAP_PERMISSION</code></td>
+        <td class="ty"><span class="st">403</span><span class="dim">core</span></td>
+        <td class="doc">The swap plugin refused the request. <span class="dim">details: <code>pluginId</code>, <code>reason</code>: <code>geoRestriction</code> | <code>noVerification</code> | <code>needsActivation</code></span></td></tr><tr id="err-INSUFFICIENT_FUNDS"><td class="k"><code>INSUFFICIENT_FUNDS</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Not enough balance to cover amount plus fee. <span class="dim">details: <code>tokenId</code>, <code>networkFee</code></span></td></tr><tr id="err-DUST_SPEND"><td class="k"><code>DUST_SPEND</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Amount below the network dust threshold.</td></tr><tr id="err-PENDING_FUNDS"><td class="k"><code>PENDING_FUNDS</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Balance exists but is unconfirmed.</td></tr><tr id="err-SPEND_TO_SELF"><td class="k"><code>SPEND_TO_SELF</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Destination address belongs to the source wallet.</td></tr><tr id="err-SWAP_ABOVE_LIMIT"><td class="k"><code>SWAP_ABOVE_LIMIT</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Amount exceeds the plugin maximum. <span class="dim">details: <code>swapPluginId</code>, <code>nativeMax</code>, <code>direction</code></span></td></tr><tr id="err-SWAP_BELOW_LIMIT"><td class="k"><code>SWAP_BELOW_LIMIT</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Amount below the plugin minimum. <span class="dim">details: <code>swapPluginId</code>, <code>nativeMin</code>, <code>direction</code>. <code>nativeMin</code> is an empty string when the plugin refused the amount without reporting a limit — core defaults it, and the engine passes it through rather than inventing one.</span></td></tr><tr id="err-SWAP_CURRENCY"><td class="k"><code>SWAP_CURRENCY</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">The plugin does not support that pair. <span class="dim">details: <code>pluginId</code>, <code>fromTokenId</code>, <code>toTokenId</code></span></td></tr><tr id="err-SWAP_ADDRESS"><td class="k"><code>SWAP_ADDRESS</code></td>
+        <td class="ty"><span class="st">422</span><span class="dim">core</span></td>
+        <td class="doc">Address unusable for this swap. <span class="dim">details: <code>swapPluginId</code>, <code>reason</code>: <code>mustMatch</code> | <code>mustBeActivated</code></span></td></tr><tr id="err-OBSOLETE_API"><td class="k"><code>OBSOLETE_API</code></td>
+        <td class="ty"><span class="st">426</span><span class="dim">core</span></td>
+        <td class="doc">The login server rejected this client version.</td></tr><tr id="err-NETWORK_ERROR"><td class="k"><code>NETWORK_ERROR</code></td>
+        <td class="ty"><span class="st">503</span><span class="dim">core</span></td>
+        <td class="doc">Could not reach an Edge server.</td></tr></tbody></table>
+<h2 id="exit-codes">CLI exit codes</h2>
+<table class="fields"><tbody><tr><td class="k"><code>0</code></td><td class="ty"><span class="dim">OK</span></td><td class="doc">Success.</td></tr><tr><td class="k"><code>1</code></td><td class="ty"><span class="dim">GENERIC</span></td><td class="doc">Any failure with no more specific mapping.</td></tr><tr><td class="k"><code>2</code></td><td class="ty"><span class="dim">USAGE</span></td><td class="doc">Bad argv: unknown flag, missing value, extra positional.</td></tr><tr><td class="k"><code>3</code></td><td class="ty"><span class="dim">AUTH</span></td><td class="doc"><code>INVALID_SESSION</code>, <code>SESSION_EXPIRED</code>, <code>UNAUTHORIZED</code>, <code>FORBIDDEN</code>, <code>PASSWORD_ERROR</code>, <code>OTP_REQUIRED</code>, <code>CHALLENGE_REQUIRED</code>, <code>PIN_DISABLED</code>.</td></tr><tr><td class="k"><code>4</code></td><td class="ty"><span class="dim">NOT_FOUND</span></td><td class="doc"><code>NOT_FOUND</code>, <code>WALLET_NOT_FOUND</code>, <code>TOKEN_NOT_FOUND</code>.</td></tr><tr><td class="k"><code>5</code></td><td class="ty"><span class="dim">VALIDATION</span></td><td class="doc"><code>BAD_REQUEST</code>, <code>INSUFFICIENT_FUNDS</code>, <code>DUST_SPEND</code>, <code>PENDING_FUNDS</code>, <code>SPEND_TO_SELF</code>, <code>NO_AMOUNT_SPECIFIED</code>, <code>AMBIGUOUS_WALLET_ID</code>, <code>USERNAME_ERROR</code>.</td></tr><tr><td class="k"><code>6</code></td><td class="ty"><span class="dim">NETWORK</span></td><td class="doc"><code>NETWORK_ERROR</code>, or any response with HTTP status <code>503</code>.</td></tr><tr><td class="k"><code>7</code></td><td class="ty"><span class="dim">ENGINE</span></td><td class="doc"><code>ENGINE_SHUTTING_DOWN</code>, or the client could not connect to or spawn the engine.</td></tr></tbody></table>
+</main>
+</div>
+<script>
+const q = document.getElementById('q')
+const links = [...document.querySelectorAll('nav a.e[data-s]')]
+q.addEventListener('input', () => {
+  const v = q.value.trim().toLowerCase()
+  for (const a of links) a.classList.toggle('hidden', v !== '' && !a.dataset.s.includes(v))
+  for (const g of document.querySelectorAll('nav .g')) {
+    let el = g.nextElementSibling, any = false
+    while (el != null && el.classList.contains('e')) {
+      if (!el.classList.contains('hidden')) any = true
+      el = el.nextElementSibling
+    }
+    g.classList.toggle('hidden', !any)
+  }
+  // A section heading outlives its groups unless it is hidden too.
+  for (const sec of document.querySelectorAll('nav .s')) {
+    let el = sec.nextElementSibling, any = false
+    while (el != null && !el.classList.contains('s')) {
+      if (el.classList.contains('e') && !el.classList.contains('hidden')) any = true
+      el = el.nextElementSibling
+    }
+    sec.classList.toggle('hidden', !any)
+  }
+})
+</script>
+</body></html>
\ No newline at end of file
diff --git a/docs/api/dist/openapi.json b/docs/api/dist/openapi.json
new file mode 100644
index 00000000000..8ceaceeb8e9
--- /dev/null
+++ b/docs/api/dist/openapi.json
@@ -0,0 +1,10227 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Edge CLI",
+    "version": "1.0.0",
+    "description": "The `edge-cli` command line and the `edge-engine` JSON REST API, generated from the route declarations in `src/cli/engine/routes/`."
+  },
+  "servers": [
+    {
+      "url": "http://localhost",
+      "description": "Unix socket at ~/.edge-cli/run/<profile>/engine.sock"
+    },
+    {
+      "url": "http://127.0.0.1:9008",
+      "description": "Loopback TCP, when started with --tcp=9008. Requires the X-Edge-Token header; see securitySchemes."
+    }
+  ],
+  "security": [
+    {},
+    {
+      "edgeTcpToken": []
+    }
+  ],
+  "tags": [
+    {
+      "name": "Lifecycle",
+      "description": "Lifecycle and configuration of the `edge-engine` daemon. None of these have an `edge-core-js` equivalent — they describe the daemon itself — and none need a session."
+    },
+    {
+      "name": "Device and usernames",
+      "description": "Calls on the shared `EdgeContext`: local device state and login-server queries that do not need a session."
+    },
+    {
+      "name": "Login methods",
+      "description": "Every successful login returns a [Session](#schema-Session) and registers it in the engine, so later calls need only the `sessionId`. The CLI writes that id to `session.json` automatically."
+    },
+    {
+      "name": "Session",
+      "description": "Calls on a logged-in `EdgeAccount`, addressed by `sessionId`. All of these can also return `401 INVALID_SESSION` or `401 SESSION_EXPIRED`."
+    },
+    {
+      "name": "Local settings",
+      "description": "Device-local account settings, stored outside the synced repos."
+    },
+    {
+      "name": "Credentials",
+      "description": "Password, PIN, username and recovery changes on a logged-in account."
+    },
+    {
+      "name": "Two-factor authentication",
+      "description": "OTP state and the reset flow a user falls back on after losing their authenticator."
+    },
+    {
+      "name": "Vouchers",
+      "description": "When 2FA blocks a login, the login server issues a voucher an already-trusted device can approve or reject."
+    },
+    {
+      "name": "Approving a login",
+      "description": "The other side of `request-edge-login`: a logged-in account inspecting and approving a login somebody scanned."
+    },
+    {
+      "name": "Keys",
+      "description": "Raw key infrastructure beneath the wallet API. Several of these return private key material, and the engine has no transport auth — treat any process that can reach the socket as fully trusted."
+    },
+    {
+      "name": "Wallet state",
+      "description": "Account-level wallet listing and creation, then per-wallet calls. A `{walletId}` segment accepts a unique prefix, so those routes can also return `404 WALLET_NOT_FOUND` or `409 AMBIGUOUS_WALLET_ID`."
+    },
+    {
+      "name": "Tokens",
+      "description": "Which tokens a wallet tracks. Enabled tokens are the ones it syncs balances for; detected ones were seen on-chain but are not yet enabled."
+    },
+    {
+      "name": "Transactions",
+      "description": "Reading transaction history, exporting it, and editing its metadata."
+    },
+    {
+      "name": "Object handles",
+      "description": "A core value with methods on it — a staged transaction, a swap quote, a pending login — cannot cross JSON, so the engine keeps it and hands back an id. These read and release any of them."
+    },
+    {
+      "name": "Spending",
+      "description": "Two ways to send funds. `spend` does the whole thing in one call; the staged workflow — `make-spend`, `sign-tx`, `broadcast-tx`, `save-tx` — hands back an object handle at each step so fees can be inspected before committing."
+    },
+    {
+      "name": "Swap quotes",
+      "description": "Cross-asset exchange. Quotes are live objects held server-side under a `swap_` handle, so approving one means naming its `objectId` rather than re-uploading the quote."
+    },
+    {
+      "name": "URIs",
+      "description": "Parsing and building BIP21-style payment URIs through the wallet’s own plugin, so chain-specific quirks are handled for you."
+    },
+    {
+      "name": "Exchange rates",
+      "description": "Historical and current rates through the same batching queue the GUI uses. No session required."
+    },
+    {
+      "name": "Data store",
+      "description": "The account’s synced key-value store, where plugins keep their own state. One route per `EdgeDataStore` method."
+    },
+    {
+      "name": "Admin",
+      "description": "**Debugging only — not for production apps.** These reach into `context.$internalStuff`, the private surface of `edge-core-js`, and can corrupt an account’s synced repos. They take no `sessionId`: they act on the context, not on a logged-in account."
+    },
+    {
+      "name": "Event stream",
+      "description": "A Server-Sent Events feed of engine activity, served outside the router because the response never ends."
+    }
+  ],
+  "paths": {
+    "/engine/status": {
+      "get": {
+        "operationId": "engineStatus",
+        "summary": "Engine liveness and summary.",
+        "description": "**Core call:** _none — Engine lifecycle; the daemon is not part of the core API._\n\n**Command line**\n\n```\nengine-status\n```\n\nThe readiness probe the client polls after auto-spawning the engine.",
+        "tags": [
+          "Lifecycle"
+        ],
+        "x-cli": {
+          "command": "engine-status",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine lifecycle; the daemon is not part of the core API.",
+        "x-source": "src/cli/engine/routes/status.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "`idleShutdownAt` is null while a session or a subscription holds the engine open, and `tcpPort` is null unless started with `--tcp`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "pid": {
+                      "type": "number",
+                      "description": "The daemon process, for `kill` when it will not stop."
+                    },
+                    "apiVersion": {
+                      "type": "string",
+                      "description": "The API this engine speaks. A client refusing to talk to an older engine checks this."
+                    },
+                    "uptimeSeconds": {
+                      "type": "number",
+                      "description": "How long the daemon has been running."
+                    },
+                    "sessionCount": {
+                      "type": "number",
+                      "description": "Logged-in accounts held open right now."
+                    },
+                    "testMode": {
+                      "type": "boolean",
+                      "description": "True when the engine is not pointed at production: the tester fleet, or the in-process fake world under `--fake`."
+                    },
+                    "idleShutdownAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When the engine will exit for want of work. Null while anything is holding it open — a logged-in session, a live subscription, a request being served, or a pending edge login, whose handle belongs to no session — and null when the timeout is disabled."
+                    },
+                    "tcpPort": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The loopback port, null unless started with `--tcp`."
+                    },
+                    "socketPath": {
+                      "type": "string",
+                      "description": "Unix socket the CLI connects to."
+                    },
+                    "rateCachedCount": {
+                      "type": "number",
+                      "description": "Exchange rates held in the engine’s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it."
+                    },
+                    "locale": {
+                      "type": "string",
+                      "description": "Language tag the engine resolved at boot."
+                    },
+                    "localeMatched": {
+                      "type": "boolean",
+                      "description": "Whether a translation table for that tag was actually found. False means the tag was accepted but the engine is answering in English, which is otherwise indistinguishable from a build that has the language."
+                    },
+                    "decimalSeparator": {
+                      "type": "string",
+                      "description": "Decimal mark for that locale."
+                    },
+                    "groupingSeparator": {
+                      "type": "string",
+                      "description": "Thousands mark for that locale."
+                    }
+                  },
+                  "required": [
+                    "pid",
+                    "apiVersion",
+                    "uptimeSeconds",
+                    "sessionCount",
+                    "testMode",
+                    "idleShutdownAt",
+                    "tcpPort",
+                    "socketPath",
+                    "rateCachedCount",
+                    "locale",
+                    "localeMatched",
+                    "decimalSeparator",
+                    "groupingSeparator"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "ENGINE_SHUTTING_DOWN",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/engine/config": {
+      "get": {
+        "operationId": "engineConfig",
+        "summary": "Configured context options.",
+        "description": "**Core call:** _none — Reflects the EdgeContextOptions the engine supplied at startup._\n\n**Command line**\n\n```\nengine-config\n```\n\nWhat the engine passed to `makeEdgeContext`. Contains no secrets. Use it to assert tester hosts before a test run.",
+        "tags": [
+          "Lifecycle"
+        ],
+        "x-cli": {
+          "command": "engine-config",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Reflects the EdgeContextOptions the engine supplied at startup.",
+        "x-source": "src/cli/engine/routes/status.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "appId": {
+                      "type": "string",
+                      "description": "Application ID the engine was started with."
+                    },
+                    "testMode": {
+                      "type": "boolean",
+                      "description": "True when the engine is not pointed at production: the tester fleet, or the in-process fake world under `--fake`. Read `servers` to tell those apart."
+                    },
+                    "directory": {
+                      "type": "string",
+                      "description": "Working directory holding the core data."
+                    },
+                    "servers": {
+                      "anyOf": [
+                        {
+                          "description": "{ [keys: string]: string"
+                        },
+                        {
+                          "description": "string[]; }"
+                        }
+                      ],
+                      "description": "The URLs this engine talks to, keyed by role. `syncServer` is a list, since core rotates across the sync fleet."
+                    },
+                    "plugins": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Plugin IDs the engine loaded, sorted."
+                    }
+                  },
+                  "required": [
+                    "appId",
+                    "testMode",
+                    "directory",
+                    "servers",
+                    "plugins"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/engine/stop": {
+      "post": {
+        "operationId": "engineStop",
+        "summary": "Stop the engine.",
+        "description": "**Core call:** _none — Engine lifecycle. Internally calls `context.close()`._\n\n**Command line**\n\n```\nengine-stop\n```\n\nLogs out every session, closes the context, unlinks the socket and run-file, then exits. The engine answers before it starts tearing down, so a response is not proof the process is gone.",
+        "tags": [
+          "Lifecycle"
+        ],
+        "x-cli": {
+          "command": "engine-stop",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine lifecycle. Internally calls `context.close()`.",
+        "x-source": "src/cli/engine/routes/status.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "Always true; a failure arrives as an error envelope."
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/local-users": {
+      "get": {
+        "operationId": "localUsers",
+        "summary": "List local users on this device.",
+        "description": "**Core call:** `context.localUsers`\n\n**Command line**\n\n```\nlocal-users\n```\n\n",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "local-users",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.localUsers",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Everything `context.localUsers` reports, including which login methods each user has enabled on this device.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "localUsers": {
+                      "type": "array",
+                      "items": {},
+                      "description": "`EdgeUserInfo[]`: one entry per account cached on this device."
+                    }
+                  },
+                  "required": [
+                    "localUsers"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/forget-account": {
+      "post": {
+        "operationId": "forgetAccount",
+        "summary": "Forget an account on this device.",
+        "description": "**Core call:** `context.forgetAccount`\n\n**Command line**\n\n```\nforget-account --root-login-id=<rootLoginId>\n```\n\nRemoves locally cached credentials. The remote account is untouched.",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "forget-account",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.forgetAccount",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "USER_NOT_FOUND, BAD_REQUEST",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "rootLoginId": {
+                    "type": "string",
+                    "description": "Core takes a `rootLoginId`. A username is also accepted and resolved against `localUsers` first, so callers need not hash it."
+                  }
+                },
+                "required": [
+                  "rootLoginId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/username-available": {
+      "get": {
+        "operationId": "usernameAvailable",
+        "summary": "Check whether a username is free.",
+        "description": "**Core call:** `context.usernameAvailable`\n\n**Command line**\n\n```\nusername-available --username=<username> [--challenge-id=<challengeId>]\n```\n\n",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "username-available",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.usernameAvailable",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [
+          {
+            "name": "username",
+            "in": "query",
+            "required": true,
+            "description": "The name to check.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "challengeId",
+            "in": "query",
+            "required": false,
+            "description": "Supply after solving a CAPTCHA to retry the same check.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "username": {
+                      "type": "string",
+                      "description": "The name that was checked, echoed back."
+                    },
+                    "available": {
+                      "type": "boolean",
+                      "description": "True when nobody holds this name. It is not reserved by asking."
+                    }
+                  },
+                  "required": [
+                    "username",
+                    "available"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "USERNAME_ERROR, CHALLENGE_REQUIRED, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/fix-username": {
+      "get": {
+        "operationId": "fixUsername",
+        "summary": "Normalize a username.",
+        "description": "**Core call:** `context.fixUsername`\n\n**Command line**\n\n```\nfix-username --username=<username>\n```\n\nApplies the same rules the login server does, so a caller can show the user what their name will actually be before creating an account.",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "fix-username",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.fixUsername",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [
+          {
+            "name": "username",
+            "in": "query",
+            "required": true,
+            "description": "The name to normalize.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "username": {
+                      "type": "string",
+                      "description": "The normalized value. The input is not echoed."
+                    }
+                  },
+                  "required": [
+                    "username"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/check-password-rules": {
+      "get": {
+        "operationId": "checkPasswordRules",
+        "summary": "Score a candidate password.",
+        "description": "**Core call:** `context.checkPasswordRules`\n\n**Command line**\n\n```\ncheck-password-rules --password=<password>\n```\n\n",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "check-password-rules",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.checkPasswordRules",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [
+          {
+            "name": "password",
+            "in": "query",
+            "required": true,
+            "description": "The candidate password to score.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`EdgePasswordRules` from core: passed, tooShort, noNumber, noLowerCase, noUpperCase, secondsToCrack.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/fetch-login-messages": {
+      "get": {
+        "operationId": "fetchLoginMessages",
+        "summary": "Fetch login-server messages for every local user.",
+        "description": "**Core call:** `context.fetchLoginMessages`\n\n**Command line**\n\n```\nfetch-login-messages\n```\n\n",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "fetch-login-messages",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.fetchLoginMessages",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "`EdgeLoginMessages` from core, keyed by loginId; each value carries otpResetPending and pendingVouchers.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/request-otp-reset": {
+      "post": {
+        "operationId": "requestOtpReset",
+        "summary": "Request a 2FA reset.",
+        "description": "**Core call:** `context.requestOtpReset`\n\n**Command line**\n\n```\nrequest-otp-reset --username=<username> --otp-reset-token=<otpResetToken>\n```\n\nStarts the timed reset a user falls back on after losing their authenticator.",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "request-otp-reset",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.requestOtpReset",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "When the reset completes if nobody cancels it.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "resetDate": {
+                      "type": "string",
+                      "description": "When 2FA will actually come off. The login server enforces a waiting period so the real owner has time to cancel."
+                    }
+                  },
+                  "required": [
+                    "resetDate"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "USERNAME_ERROR, BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "username": {
+                    "type": "string",
+                    "description": "Whose 2FA to reset."
+                  },
+                  "otpResetToken": {
+                    "type": "string",
+                    "description": "From `details.resetToken` on an `OTP_REQUIRED` error."
+                  }
+                },
+                "required": [
+                  "username",
+                  "otpResetToken"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/fetch-recovery-questions": {
+      "get": {
+        "operationId": "fetchRecoveryQuestions",
+        "summary": "Fetch a user’s recovery questions.",
+        "description": "**Core call:** `context.fetchRecovery2Questions`\n\n**Command line**\n\n```\nfetch-recovery-questions --recovery-key=<recoveryKey> --username=<username>\n```\n\n",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "fetch-recovery-questions",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.fetchRecovery2Questions",
+        "x-core-note": "Our surface drops the `2` from the path, command and `recoveryKey` parameter; a future Recovery1 would be suffixed `V1`.",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [
+          {
+            "name": "recoveryKey",
+            "in": "query",
+            "required": true,
+            "description": "From `change-recovery`, stored by the user out of band.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "username",
+            "in": "query",
+            "required": true,
+            "description": "Whose questions to fetch.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "questions": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "The questions in the order `login-with-recovery` expects the answers."
+                    }
+                  },
+                  "required": [
+                    "questions"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "USERNAME_ERROR, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/fetch-challenge": {
+      "post": {
+        "operationId": "fetchChallenge",
+        "summary": "Pre-fetch a CAPTCHA challenge.",
+        "description": "**Core call:** `context.fetchChallenge`\n\n**Command line**\n\n```\nfetch-challenge\n```\n\nLets a client solve a challenge before it hits `403 CHALLENGE_REQUIRED` mid-flow.",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "fetch-challenge",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.fetchChallenge",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "`challengeUri` is absent when the server considers the challenge already satisfied.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "challengeId": {
+                      "type": "string",
+                      "description": "Pass to the call that demanded a challenge once the user has solved it."
+                    },
+                    "challengeUri": {
+                      "type": "string",
+                      "description": "Where to send the user to solve the CAPTCHA. Absent when the server issued a challenge that needs no interaction."
+                    }
+                  },
+                  "required": [
+                    "challengeId"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/currency-configs": {
+      "get": {
+        "operationId": "currencyConfigs",
+        "summary": "List plugin ids usable for wallet creation.",
+        "description": "**Core call:** _none — Engine view of the enabled plugin set; core exposes `account.currencyConfig` per plugin instead._\n\n**Command line**\n\n```\ncurrency-configs\n```\n\nCurrency and accountbased plugins only — swap plugins are excluded.",
+        "tags": [
+          "Device and usernames"
+        ],
+        "x-cli": {
+          "command": "currency-configs",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine view of the enabled plugin set; core exposes `account.currencyConfig` per plugin instead.",
+        "x-source": "src/cli/engine/routes/context.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "pluginIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Currency plugins this engine loaded."
+                    }
+                  },
+                  "required": [
+                    "pluginIds"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/login-with-password": {
+      "post": {
+        "operationId": "loginWithPassword",
+        "summary": "Log in with a password.",
+        "description": "**Core call:** `context.loginWithPassword`\n\n**Command line**\n\n```\nlogin-with-password [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --username=<username> --password=<password>\n```\n\n",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "login-with-password",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "context.loginWithPassword",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A session with `loginMethod: \"password\"`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Absent for a light account, which has no username."
+                    },
+                    "rootLoginId": {
+                      "type": "string",
+                      "description": "The account root, stable across appIds. Two sessions sharing it are the same account."
+                    },
+                    "loginMethod": {
+                      "anyOf": [
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"recovery\""
+                        }
+                      ],
+                      "description": "How this session was established."
+                    },
+                    "autoLogoutSeconds": {
+                      "type": "number",
+                      "description": "Idle time before the engine logs the account out. 0 disables it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When auto-logout will fire, or null when it is disabled."
+                    },
+                    "lastActivityAt": {
+                      "type": "string",
+                      "description": "Last call on this session, which is what auto-logout measures from."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the login completed."
+                    }
+                  },
+                  "required": [
+                    "sessionId",
+                    "rootLoginId",
+                    "loginMethod",
+                    "autoLogoutSeconds",
+                    "expiresAt",
+                    "lastActivityAt",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "PASSWORD_ERROR, USERNAME_ERROR, OTP_REQUIRED, CHALLENGE_REQUIRED, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "otp": {
+                    "type": "string",
+                    "description": "A current 2FA code."
+                  },
+                  "otpKey": {
+                    "type": "string",
+                    "description": "The 2FA secret itself, instead of a code."
+                  },
+                  "challengeId": {
+                    "type": "string",
+                    "description": "Supply after solving a CAPTCHA to retry the same request."
+                  },
+                  "username": {
+                    "type": "string",
+                    "description": "The account name."
+                  },
+                  "password": {
+                    "type": "string",
+                    "description": "The account password."
+                  }
+                },
+                "required": [
+                  "username",
+                  "password"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/login-with-pin": {
+      "post": {
+        "operationId": "loginWithPin",
+        "summary": "Log in with a device PIN.",
+        "description": "**Core call:** `context.loginWithPIN`\n\n**Command line**\n\n```\nlogin-with-pin [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --username-or-login-id=<usernameOrLoginId> --pin=<pin> [--use-login-id[=false]]\n```\n\nOnly works on a device that has already saved a PIN for the account.",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "login-with-pin",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "context.loginWithPIN",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A session with `loginMethod: \"pin\"`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Absent for a light account, which has no username."
+                    },
+                    "rootLoginId": {
+                      "type": "string",
+                      "description": "The account root, stable across appIds. Two sessions sharing it are the same account."
+                    },
+                    "loginMethod": {
+                      "anyOf": [
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"recovery\""
+                        }
+                      ],
+                      "description": "How this session was established."
+                    },
+                    "autoLogoutSeconds": {
+                      "type": "number",
+                      "description": "Idle time before the engine logs the account out. 0 disables it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When auto-logout will fire, or null when it is disabled."
+                    },
+                    "lastActivityAt": {
+                      "type": "string",
+                      "description": "Last call on this session, which is what auto-logout measures from."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the login completed."
+                    }
+                  },
+                  "required": [
+                    "sessionId",
+                    "rootLoginId",
+                    "loginMethod",
+                    "autoLogoutSeconds",
+                    "expiresAt",
+                    "lastActivityAt",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "PASSWORD_ERROR, PIN_DISABLED, USERNAME_ERROR, BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "otp": {
+                    "type": "string",
+                    "description": "A current 2FA code."
+                  },
+                  "otpKey": {
+                    "type": "string",
+                    "description": "The 2FA secret itself, instead of a code."
+                  },
+                  "challengeId": {
+                    "type": "string",
+                    "description": "Supply after solving a CAPTCHA to retry the same request."
+                  },
+                  "usernameOrLoginId": {
+                    "type": "string",
+                    "description": "A username, or a login id."
+                  },
+                  "pin": {
+                    "type": "string",
+                    "description": "The device PIN."
+                  },
+                  "useLoginId": {
+                    "type": "boolean",
+                    "description": "Treat the value as a login id."
+                  }
+                },
+                "required": [
+                  "usernameOrLoginId",
+                  "pin"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/login-with-key": {
+      "post": {
+        "operationId": "loginWithKey",
+        "summary": "Log in with an account login key.",
+        "description": "**Core call:** `context.loginWithKey`\n\n**Command line**\n\n```\nlogin-with-key [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --username-or-login-id=<usernameOrLoginId> --login-key=<loginKey> [--use-login-id[=false]]\n```\n\nThe key comes from `get-login-key` on an already-authenticated session.",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "login-with-key",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "context.loginWithKey",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A session with `loginMethod: \"key\"`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Absent for a light account, which has no username."
+                    },
+                    "rootLoginId": {
+                      "type": "string",
+                      "description": "The account root, stable across appIds. Two sessions sharing it are the same account."
+                    },
+                    "loginMethod": {
+                      "anyOf": [
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"recovery\""
+                        }
+                      ],
+                      "description": "How this session was established."
+                    },
+                    "autoLogoutSeconds": {
+                      "type": "number",
+                      "description": "Idle time before the engine logs the account out. 0 disables it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When auto-logout will fire, or null when it is disabled."
+                    },
+                    "lastActivityAt": {
+                      "type": "string",
+                      "description": "Last call on this session, which is what auto-logout measures from."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the login completed."
+                    }
+                  },
+                  "required": [
+                    "sessionId",
+                    "rootLoginId",
+                    "loginMethod",
+                    "autoLogoutSeconds",
+                    "expiresAt",
+                    "lastActivityAt",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "PASSWORD_ERROR, USERNAME_ERROR, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "otp": {
+                    "type": "string",
+                    "description": "A current 2FA code."
+                  },
+                  "otpKey": {
+                    "type": "string",
+                    "description": "The 2FA secret itself, instead of a code."
+                  },
+                  "challengeId": {
+                    "type": "string",
+                    "description": "Supply after solving a CAPTCHA to retry the same request."
+                  },
+                  "usernameOrLoginId": {
+                    "type": "string",
+                    "description": "A username, or a login id."
+                  },
+                  "loginKey": {
+                    "type": "string",
+                    "description": "From `get-login-key`."
+                  },
+                  "useLoginId": {
+                    "type": "boolean",
+                    "description": "Treat the value as a login id."
+                  }
+                },
+                "required": [
+                  "usernameOrLoginId",
+                  "loginKey"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/login-with-recovery": {
+      "post": {
+        "operationId": "loginWithRecovery",
+        "summary": "Log in with recovery answers.",
+        "description": "**Core call:** `context.loginWithRecovery2`\n\n**Command line**\n\n```\nlogin-with-recovery [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --recovery-key=<recoveryKey> --username=<username> --answer=<answers> …\n```\n\nNeeds both the recovery key and the answers; neither works alone.",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "login-with-recovery",
+          "flags": [
+            {
+              "name": "answer",
+              "maps": "answers",
+              "repeat": true
+            }
+          ],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "context.loginWithRecovery2",
+        "x-core-note": "Our surface drops the `2` from core's recovery2 naming, and calls the key `recoveryKey` to match what `change-recovery` returns.",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A session with `loginMethod: \"recovery\"`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Absent for a light account, which has no username."
+                    },
+                    "rootLoginId": {
+                      "type": "string",
+                      "description": "The account root, stable across appIds. Two sessions sharing it are the same account."
+                    },
+                    "loginMethod": {
+                      "anyOf": [
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"recovery\""
+                        }
+                      ],
+                      "description": "How this session was established."
+                    },
+                    "autoLogoutSeconds": {
+                      "type": "number",
+                      "description": "Idle time before the engine logs the account out. 0 disables it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When auto-logout will fire, or null when it is disabled."
+                    },
+                    "lastActivityAt": {
+                      "type": "string",
+                      "description": "Last call on this session, which is what auto-logout measures from."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the login completed."
+                    }
+                  },
+                  "required": [
+                    "sessionId",
+                    "rootLoginId",
+                    "loginMethod",
+                    "autoLogoutSeconds",
+                    "expiresAt",
+                    "lastActivityAt",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "PASSWORD_ERROR, USERNAME_ERROR, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "otp": {
+                    "type": "string",
+                    "description": "A current 2FA code."
+                  },
+                  "otpKey": {
+                    "type": "string",
+                    "description": "The 2FA secret itself, instead of a code."
+                  },
+                  "challengeId": {
+                    "type": "string",
+                    "description": "Supply after solving a CAPTCHA to retry the same request."
+                  },
+                  "recoveryKey": {
+                    "type": "string",
+                    "description": "From `change-recovery`."
+                  },
+                  "username": {
+                    "type": "string",
+                    "description": "The account name."
+                  },
+                  "answers": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "In the same order as the questions."
+                  }
+                },
+                "required": [
+                  "recoveryKey",
+                  "username",
+                  "answers"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/create-account": {
+      "post": {
+        "operationId": "createAccount",
+        "summary": "Create an account.",
+        "description": "**Core call:** `context.createAccount`\n\n**Command line**\n\n```\ncreate-account [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] [--username=<username>] [--password=<password>] [--pin=<pin>]\n```\n\nEvery credential is optional over REST: omitting all three creates a light account with no username.",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "create-account",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "context.createAccount",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A session with `loginMethod: \"create\"`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Absent for a light account, which has no username."
+                    },
+                    "rootLoginId": {
+                      "type": "string",
+                      "description": "The account root, stable across appIds. Two sessions sharing it are the same account."
+                    },
+                    "loginMethod": {
+                      "anyOf": [
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"recovery\""
+                        }
+                      ],
+                      "description": "How this session was established."
+                    },
+                    "autoLogoutSeconds": {
+                      "type": "number",
+                      "description": "Idle time before the engine logs the account out. 0 disables it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When auto-logout will fire, or null when it is disabled."
+                    },
+                    "lastActivityAt": {
+                      "type": "string",
+                      "description": "Last call on this session, which is what auto-logout measures from."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the login completed."
+                    }
+                  },
+                  "required": [
+                    "sessionId",
+                    "rootLoginId",
+                    "loginMethod",
+                    "autoLogoutSeconds",
+                    "expiresAt",
+                    "lastActivityAt",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "USERNAME_ERROR, CHALLENGE_REQUIRED, BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "otp": {
+                    "type": "string",
+                    "description": "A current 2FA code."
+                  },
+                  "otpKey": {
+                    "type": "string",
+                    "description": "The 2FA secret itself, instead of a code."
+                  },
+                  "challengeId": {
+                    "type": "string",
+                    "description": "Supply after solving a CAPTCHA to retry the same request."
+                  },
+                  "username": {
+                    "type": "string",
+                    "description": "The name to claim."
+                  },
+                  "password": {
+                    "type": "string",
+                    "description": "The account password."
+                  },
+                  "pin": {
+                    "type": "string",
+                    "description": "A device PIN to save."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/request-edge-login": {
+      "post": {
+        "operationId": "requestEdgeLogin",
+        "summary": "Start a QR login.",
+        "description": "**Core call:** `context.requestEdgeLogin`\n\n**Command line**\n\n```\nrequest-edge-login [--no-wait]\n```\n\nAsks the login server for a lobby another logged-in Edge device can approve. The returned `lobbyId` is what goes in the QR code.",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "request-edge-login",
+          "flags": [],
+          "extra": [
+            {
+              "name": "no-wait",
+              "kind": "boolean",
+              "required": false,
+              "doc": "Print the lobby and exit instead of polling, so the QR can be displayed while `poll-edge-login` watches the same handle from another process."
+            }
+          ],
+          "custom": true,
+          "preset": {},
+          "notes": "Prints the pending login, then polls every 2s for up to 5 minutes. On `done` it stores the session. With `--no-wait` it returns immediately and `poll-edge-login` takes over."
+        },
+        "x-core-call": "context.requestEdgeLogin",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "pendingId": {
+                      "type": "string",
+                      "description": "Same value as `objectId`, under the name the poll command takes."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When the lobby closes and the QR code stops working."
+                    },
+                    "lobbyId": {
+                      "type": "string",
+                      "description": "Lobby the phone connects to."
+                    },
+                    "uri": {
+                      "type": "string",
+                      "description": "The `edge://` URI to render as a QR code for the phone to scan."
+                    },
+                    "state": {
+                      "type": "string",
+                      "description": "How far the login has got: `pending` before the phone scans, `started` once it has, and `done` when `session` is filled in."
+                    },
+                    "username": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Account that approved the login, known once the phone has scanned."
+                    },
+                    "session": {
+                      "anyOf": [
+                        {
+                          "description": "{ sessionId: string; username: string"
+                        },
+                        {
+                          "description": "undefined; rootLoginId: string; loginMethod: \"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"recovery\"; autoLogoutSeconds: number; expiresAt: string"
+                        },
+                        {
+                          "description": "null; lastActivityAt: string; createdAt: string; }"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The session, null until `state` is `done`."
+                    },
+                    "error": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Why the login failed, set only when `state` is `error`."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "pendingId",
+                    "kind",
+                    "expiresAt",
+                    "lobbyId",
+                    "uri",
+                    "state",
+                    "username",
+                    "session",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pending-edge-login/{pendingId}": {
+      "get": {
+        "operationId": "pollEdgeLogin",
+        "summary": "Poll a pending QR login.",
+        "description": "**Core call:** _none — Engine state for an in-flight requestEdgeLogin; core exposes it as EdgePendingEdgeLogin properties._\n\n**Command line**\n\n```\npoll-edge-login <pendingId>\n```\n\nOnce `state` reaches `done` the engine has already created the session, so the response carries one ready to use.",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "poll-edge-login",
+          "positional": "pendingId",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine state for an in-flight requestEdgeLogin; core exposes it as EdgePendingEdgeLogin properties.",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [
+          {
+            "name": "pendingId",
+            "in": "path",
+            "required": true,
+            "description": "The `pendingId` returned when the QR login was requested.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "pendingId": {
+                      "type": "string",
+                      "description": "Same value as `objectId`, under the name the poll command takes."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When the lobby closes and the QR code stops working."
+                    },
+                    "lobbyId": {
+                      "type": "string",
+                      "description": "Lobby the phone connects to."
+                    },
+                    "uri": {
+                      "type": "string",
+                      "description": "The `edge://` URI to render as a QR code for the phone to scan."
+                    },
+                    "state": {
+                      "type": "string",
+                      "description": "How far the login has got: `pending` before the phone scans, `started` once it has, and `done` when `session` is filled in."
+                    },
+                    "username": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Account that approved the login, known once the phone has scanned."
+                    },
+                    "session": {
+                      "anyOf": [
+                        {
+                          "description": "{ sessionId: string; username: string"
+                        },
+                        {
+                          "description": "undefined; rootLoginId: string; loginMethod: \"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"recovery\"; autoLogoutSeconds: number; expiresAt: string"
+                        },
+                        {
+                          "description": "null; lastActivityAt: string; createdAt: string; }"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The session, null until `state` is `done`."
+                    },
+                    "error": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Why the login failed, set only when `state` is `error`."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "pendingId",
+                    "kind",
+                    "expiresAt",
+                    "lobbyId",
+                    "uri",
+                    "state",
+                    "username",
+                    "session",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "PENDING_LOGIN_NOT_FOUND, OBJECT_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pending-edge-login/cancel-request/{pendingId}": {
+      "post": {
+        "operationId": "cancelEdgeLogin",
+        "summary": "Cancel a pending QR login.",
+        "description": "**Core call:** `EdgePendingEdgeLogin.cancelRequest`\n\n**Command line**\n\n```\ncancel-request <pendingId>\n```\n\n",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "cancel-request",
+          "positional": "pendingId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "EdgePendingEdgeLogin.cancelRequest",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [
+          {
+            "name": "pendingId",
+            "in": "path",
+            "required": true,
+            "description": "The `pendingId` returned when the QR login was requested.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "PENDING_LOGIN_NOT_FOUND",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/engine/sessions": {
+      "get": {
+        "operationId": "engineSessions",
+        "summary": "List active sessions.",
+        "description": "**Core call:** _none — The session registry is an engine construct; core has no multi-account session concept._\n\n**Command line**\n\n```\nengine-sessions\n```\n\n",
+        "tags": [
+          "Login methods"
+        ],
+        "x-cli": {
+          "command": "engine-sessions",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "The session registry is an engine construct; core has no multi-account session concept.",
+        "x-source": "src/cli/engine/routes/login.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A bare array, not wrapped in a key. Each `sessionId` is truncated: this route needs no session, so a usable id here would be a credential anyone who can reach the engine could collect.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "description": "{ sessionId: string; username: string"
+                      },
+                      {
+                        "description": "undefined; rootLoginId: string; loginMethod: \"password\""
+                      },
+                      {
+                        "description": "\"pin\""
+                      },
+                      {
+                        "description": "\"edge\""
+                      },
+                      {
+                        "description": "\"key\""
+                      },
+                      {
+                        "description": "\"create\""
+                      },
+                      {
+                        "description": "\"recovery\"; autoLogoutSeconds: number; expiresAt: string"
+                      },
+                      {
+                        "description": "null; lastActivityAt: string; createdAt: string; }"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}": {
+      "get": {
+        "operationId": "accountInfo",
+        "summary": "Account and session summary.",
+        "description": "**Core call:** _none — Engine composite of the session record plus EdgeAccount properties._\n\n**Command line**\n\n```\naccount-info\n```\n\nSession fields are spread at the top level alongside the account's own properties — there is no nested `session` object.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "account-info",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine composite of the session record plus EdgeAccount properties.",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "appId": {
+                      "type": "string",
+                      "description": "Application this session logged into."
+                    },
+                    "created": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When the account was created, null for accounts predating the field."
+                    },
+                    "lastLogin": {
+                      "type": "string",
+                      "description": "The previous login, not this one."
+                    },
+                    "loggedIn": {
+                      "type": "boolean",
+                      "description": "False once the account has been logged out; the session object outlives it briefly."
+                    },
+                    "recoveryKey": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Present only while recovery is configured."
+                    },
+                    "otpEnabled": {
+                      "type": "boolean",
+                      "description": "2FA is on for this account."
+                    },
+                    "otpResetPending": {
+                      "type": "boolean",
+                      "description": "True while somebody has a reset pending against this account."
+                    },
+                    "canDuressLogin": {
+                      "type": "boolean",
+                      "description": "A duress PIN is configured, so this account can be opened in duress mode."
+                    },
+                    "isDuressAccount": {
+                      "type": "boolean",
+                      "description": "True when this very session is the duress account rather than the real one."
+                    },
+                    "edgeLogin": {
+                      "type": "boolean",
+                      "description": "This account was reached by QR login."
+                    },
+                    "keyLogin": {
+                      "type": "boolean",
+                      "description": "This session was reached with a login key."
+                    },
+                    "newAccount": {
+                      "type": "boolean",
+                      "description": "This session created the account rather than logging into an existing one."
+                    },
+                    "passwordLogin": {
+                      "type": "boolean",
+                      "description": "This session was reached with a password."
+                    },
+                    "pinLogin": {
+                      "type": "boolean",
+                      "description": "This session was reached with a PIN."
+                    },
+                    "recoveryLogin": {
+                      "type": "boolean",
+                      "description": "This session was reached by answering recovery questions."
+                    }
+                  },
+                  "required": [
+                    "appId",
+                    "created",
+                    "lastLogin",
+                    "loggedIn",
+                    "recoveryKey",
+                    "otpEnabled",
+                    "otpResetPending",
+                    "canDuressLogin",
+                    "isDuressAccount",
+                    "edgeLogin",
+                    "keyLogin",
+                    "newAccount",
+                    "passwordLogin",
+                    "pinLogin",
+                    "recoveryLogin"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/logout": {
+      "post": {
+        "operationId": "logout",
+        "summary": "Log out.",
+        "description": "**Core call:** `account.logout`\n\n**Command line**\n\n```\nlogout\n```\n\nEnds the session and drops it from the engine. Any subscription scoped to this account or its wallets is closed with it.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "logout",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {},
+          "notes": "Also clears the stored id from `session.json`."
+        },
+        "x-core-call": "account.logout",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/touch": {
+      "post": {
+        "operationId": "touchSession",
+        "summary": "Keepalive.",
+        "description": "**Core call:** _none — Engine auto-logout timer; core has no idle concept._\n\n**Command line**\n\n```\ntouch\n```\n\nResets the idle auto-logout timer without doing any other work.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "touch",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine auto-logout timer; core has no idle concept.",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The session, with a refreshed `expiresAt`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Absent for a light account, which has no username."
+                    },
+                    "rootLoginId": {
+                      "type": "string",
+                      "description": "The account root, stable across appIds. Two sessions sharing it are the same account."
+                    },
+                    "loginMethod": {
+                      "anyOf": [
+                        {
+                          "description": "\"create\""
+                        },
+                        {
+                          "description": "\"edge\""
+                        },
+                        {
+                          "description": "\"key\""
+                        },
+                        {
+                          "description": "\"password\""
+                        },
+                        {
+                          "description": "\"pin\""
+                        },
+                        {
+                          "description": "\"recovery\""
+                        }
+                      ],
+                      "description": "How this session was established."
+                    },
+                    "autoLogoutSeconds": {
+                      "type": "number",
+                      "description": "Idle time before the engine logs the account out. 0 disables it."
+                    },
+                    "expiresAt": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When auto-logout will fire, or null when it is disabled."
+                    },
+                    "lastActivityAt": {
+                      "type": "string",
+                      "description": "Last call on this session, which is what auto-logout measures from."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the login completed."
+                    }
+                  },
+                  "required": [
+                    "sessionId",
+                    "rootLoginId",
+                    "loginMethod",
+                    "autoLogoutSeconds",
+                    "expiresAt",
+                    "lastActivityAt",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-login-key": {
+      "get": {
+        "operationId": "getLoginKey",
+        "summary": "Read the account login key.",
+        "description": "**Core call:** `account.getLoginKey`\n\n**Command line**\n\n```\nget-login-key\n```\n\nThe key `login-with-key` takes. It grants full account access, so treat the output as secret.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "get-login-key",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getLoginKey",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "loginKey": {
+                      "type": "string",
+                      "description": "base58. Full account access — keep it safe."
+                    }
+                  },
+                  "required": [
+                    "loginKey"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/sync": {
+      "post": {
+        "operationId": "accountSync",
+        "summary": "Force an account data sync.",
+        "description": "**Core call:** `account.sync`\n\n**Command line**\n\n```\nsync\n```\n\nPushes and pulls the account repos immediately rather than waiting for the next scheduled sync.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "sync",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {},
+          "notes": "Named `sync` for the account; the wallet one is `wallet-sync`."
+        },
+        "x-core-call": "account.sync",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/delete-remote-account": {
+      "post": {
+        "operationId": "deleteRemoteAccount",
+        "summary": "Permanently delete the remote account.",
+        "description": "**Core call:** `account.deleteRemoteAccount`\n\n**Command line**\n\n```\ndelete-remote-account --yes\n```\n\nIrreversible. The account is removed from the login server, and funds in its wallets are unrecoverable without the keys. The session is logged out afterwards.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "delete-remote-account",
+          "flags": [],
+          "extra": [
+            {
+              "name": "yes",
+              "kind": "boolean",
+              "required": true,
+              "doc": "Confirms intent. Without it the command refuses to run."
+            }
+          ],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "account.deleteRemoteAccount",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wait-for-all-wallets": {
+      "post": {
+        "operationId": "waitForAllWallets",
+        "summary": "Wait for every wallet to finish loading.",
+        "description": "**Core call:** `account.waitForAllWallets`\n\n**Command line**\n\n```\nwait-for-all-wallets\n```\n\nWallets load in the background after login, so a list taken straight afterwards can be short. This resolves once each active wallet has either loaded or failed — balances may still be syncing afterwards.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "wait-for-all-wallets",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.waitForAllWallets",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/currency-wallets": {
+      "get": {
+        "operationId": "currencyWallets",
+        "summary": "List the account's wallets.",
+        "description": "**Core call:** `account.currencyWallets`\n\n**Command line**\n\n```\ncurrency-wallets [--filter=active|all|archived|hidden]\n```\n\n",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "currency-wallets",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.currencyWallets",
+        "x-core-note": "Filtered by account.activeWalletIds / archivedWalletIds / hiddenWalletIds.",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "filter",
+            "in": "query",
+            "required": false,
+            "description": "Which of the account’s wallet lists to read. Defaults to `active`.",
+            "schema": {
+              "anyOf": [
+                {
+                  "description": "\"active\""
+                },
+                {
+                  "description": "\"all\""
+                },
+                {
+                  "description": "\"archived\""
+                },
+                {
+                  "description": "\"hidden\""
+                }
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "currencyWallets": {
+                      "type": "array",
+                      "items": {
+                        "anyOf": [
+                          {
+                            "description": "{ walletId: string; id: string; type: string; name: string"
+                          },
+                          {
+                            "description": "null; pluginId: string; currencyCode: string; fiatCurrencyCode: string; blockHeight: number; syncStatus: unknown; syncRatio: string"
+                          },
+                          {
+                            "description": "undefined; paused: boolean; imported: boolean"
+                          },
+                          {
+                            "description": "undefined; created: string"
+                          },
+                          {
+                            "description": "null; enabledTokenIds: string[]; detectedTokenIds: string[]; unactivatedTokenIds: string[]; }"
+                          }
+                        ]
+                      },
+                      "description": "Every wallet in the account, including paused ones."
+                    }
+                  },
+                  "required": [
+                    "currencyWallets"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/create-currency-wallet": {
+      "post": {
+        "operationId": "createCurrencyWallet",
+        "summary": "Create a currency wallet.",
+        "description": "**Core call:** `account.createCurrencyWallet`\n\n**Command line**\n\n```\ncreate-currency-wallet --wallet-type=<walletType> [--name=<name>] [--import-text=<importText>]\n```\n\n",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "create-currency-wallet",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.createCurrencyWallet",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "walletId": {
+                      "type": "string",
+                      "description": "The full wallet id. Commands taking a wallet accept any unique prefix."
+                    },
+                    "id": {
+                      "type": "string",
+                      "description": "Same value as `walletId`; core exposes both names."
+                    },
+                    "type": {
+                      "type": "string",
+                      "description": "Key type, such as `wallet:bitcoin`."
+                    },
+                    "name": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "User-assigned name, null until one is set."
+                    },
+                    "pluginId": {
+                      "type": "string",
+                      "description": "Currency plugin backing this wallet."
+                    },
+                    "currencyCode": {
+                      "type": "string",
+                      "description": "Ticker for the native asset."
+                    },
+                    "fiatCurrencyCode": {
+                      "type": "string",
+                      "description": "Fiat the wallet reports value in, as `iso:USD`."
+                    },
+                    "blockHeight": {
+                      "type": "number",
+                      "description": "Chain height this wallet has seen."
+                    },
+                    "syncStatus": {
+                      "description": "`EdgeWalletSyncStatus` from core."
+                    },
+                    "syncRatio": {
+                      "type": "string",
+                      "description": "Sync progress as a percentage, for display."
+                    },
+                    "paused": {
+                      "type": "boolean",
+                      "description": "True while the engine is not syncing this wallet."
+                    },
+                    "imported": {
+                      "type": "boolean",
+                      "description": "True when the keys came from an import rather than being generated here."
+                    },
+                    "created": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When the wallet was created, null for wallets predating the field."
+                    },
+                    "enabledTokenIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Tokens the user turned on."
+                    },
+                    "detectedTokenIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Tokens found on-chain that are not enabled yet."
+                    },
+                    "unactivatedTokenIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Enabled tokens still awaiting on-chain activation."
+                    }
+                  },
+                  "required": [
+                    "walletId",
+                    "id",
+                    "type",
+                    "name",
+                    "pluginId",
+                    "currencyCode",
+                    "fiatCurrencyCode",
+                    "blockHeight",
+                    "syncStatus",
+                    "paused",
+                    "created",
+                    "enabledTokenIds",
+                    "detectedTokenIds",
+                    "unactivatedTokenIds"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletType": {
+                    "type": "string",
+                    "description": "From `currency-configs`, e.g. `wallet:bitcoin`."
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "Display name."
+                  },
+                  "importText": {
+                    "type": "string",
+                    "description": "Seed or key text to import instead of generating."
+                  }
+                },
+                "required": [
+                  "walletType"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/create-currency-wallets": {
+      "post": {
+        "operationId": "createCurrencyWallets",
+        "summary": "Create several wallets at once.",
+        "description": "**Core call:** `account.createCurrencyWallets`\n\n**Command line**\n\n```\ncreate-currency-wallets --create-wallets='<json>'\n```\n\nPartial success is normal: each entry reports its own outcome, and one failure does not roll back the others.",
+        "tags": [
+          "Session"
+        ],
+        "x-cli": {
+          "command": "create-currency-wallets",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.createCurrencyWallets",
+        "x-source": "src/cli/engine/routes/account.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {},
+                      "description": "Mirrors core’s EdgeResult[]: `{ ok, wallet }` or `{ ok: false, error }`."
+                    }
+                  },
+                  "required": [
+                    "results"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "createWallets": {
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "description": "{ walletType: string; name: string"
+                        },
+                        {
+                          "description": "undefined; fiatCurrencyCode: string"
+                        },
+                        {
+                          "description": "undefined; }"
+                        }
+                      ]
+                    },
+                    "description": "`EdgeCreateCurrencyWallet[]`: walletType, plus optional name and fiatCurrencyCode."
+                  }
+                },
+                "required": [
+                  "createWallets"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/local-settings": {
+      "get": {
+        "operationId": "localSettings",
+        "summary": "Local settings.",
+        "description": "**Core call:** _none — GUI code (src/util/localAccountSettings), reached through account.localDisklet._\n\n**Command line**\n\n```\nlocal-settings\n```\n\nDevice-local account settings, stored in `Settings.json` on `account.localDisklet`. They are not synced — a phone and a CLI keep separate copies unless they share an Edge data directory.",
+        "tags": [
+          "Local settings"
+        ],
+        "x-cli": {
+          "command": "local-settings",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "GUI code (src/util/localAccountSettings), reached through account.localDisklet.",
+        "x-source": "src/cli/engine/routes/localSettings.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "spamFilterOn": {
+                      "type": "boolean",
+                      "description": "Hide spam transactions in `get-transactions` results. Defaults to `true`, matching the GUI. The filter hides rows; it never changes stored metadata."
+                    }
+                  },
+                  "required": [
+                    "spamFilterOn"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/change-local-settings": {
+      "post": {
+        "operationId": "changeLocalSettings",
+        "summary": "Change local settings.",
+        "description": "**Core call:** _none — GUI code (src/util/localAccountSettings)._\n\n**Command line**\n\n```\nlocal-settings --spam-filter-on=true|false\n```\n\nWrites device-local account settings. Every option is a field on the body; `spamFilterOn` is the only one today, and new options are added alongside it.",
+        "tags": [
+          "Local settings"
+        ],
+        "x-cli": {
+          "command": "local-settings",
+          "flags": [],
+          "extra": [],
+          "custom": true,
+          "preset": {},
+          "notes": "With no flag the command reads; with one it writes."
+        },
+        "x-core-call": null,
+        "x-core-note": "GUI code (src/util/localAccountSettings).",
+        "x-source": "src/cli/engine/routes/localSettings.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "spamFilterOn": {
+                      "type": "boolean",
+                      "description": "Hide spam transactions in `get-transactions` results. Defaults to `true`, matching the GUI. The filter hides rows; it never changes stored metadata."
+                    }
+                  },
+                  "required": [
+                    "spamFilterOn"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "spamFilterOn": {
+                    "type": "boolean",
+                    "description": "Hide spam transactions in `get-transactions` results. Defaults to `true`, matching the GUI. The filter hides rows; it never changes stored metadata."
+                  }
+                },
+                "required": [
+                  "spamFilterOn"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/change-password": {
+      "post": {
+        "operationId": "changePassword",
+        "summary": "Set or change the password.",
+        "description": "**Core call:** `account.changePassword`\n\n**Command line**\n\n```\nchange-password --password=<password>\n```\n\nThe login server enforces its own rules; `check-password-rules` scores a candidate first.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "change-password",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.changePassword",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "password": {
+                    "type": "string",
+                    "description": "The new password."
+                  }
+                },
+                "required": [
+                  "password"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/delete-password": {
+      "post": {
+        "operationId": "deletePassword",
+        "summary": "Remove password login.",
+        "description": "**Core call:** `account.deletePassword`\n\n**Command line**\n\n```\ndelete-password\n```\n\nThe account keeps its other login methods; only the password stops working.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "delete-password",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.deletePassword",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/check-password": {
+      "post": {
+        "operationId": "checkPassword",
+        "summary": "Verify a password.",
+        "description": "**Core call:** `account.checkPassword`\n\n**Command line**\n\n```\ncheck-password --password=<password>\n```\n\nChecks without changing anything, which is how a caller gates a destructive action behind a re-entry prompt.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "check-password",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.checkPassword",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "False for a wrong password — not an error response."
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "password": {
+                    "type": "string",
+                    "description": "The account password."
+                  }
+                },
+                "required": [
+                  "password"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-pin": {
+      "get": {
+        "operationId": "getPin",
+        "summary": "Read the account PIN.",
+        "description": "**Core call:** `account.getPin`\n\n**Command line**\n\n```\nget-pin\n```\n\nReturns the PIN itself, not a status flag, so treat the output as secret.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "get-pin",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getPin",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "pin": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Null when no PIN is set."
+                    }
+                  },
+                  "required": [
+                    "pin"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/change-pin": {
+      "post": {
+        "operationId": "changePin",
+        "summary": "Set or change the PIN.",
+        "description": "**Core call:** `account.changePin`\n\n**Command line**\n\n```\nchange-pin --pin=<pin> [--enable-login[=false]] [--for-duress-account[=false]]\n```\n\n",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "change-pin",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.changePin",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "pin2Key": {
+                      "type": "string",
+                      "description": "The new PIN login key core returns."
+                    }
+                  },
+                  "required": [
+                    "pin2Key"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "pin": {
+                    "type": "string",
+                    "description": "The new PIN."
+                  },
+                  "enableLogin": {
+                    "type": "boolean",
+                    "description": "Allow logging in with this PIN on this device."
+                  },
+                  "forDuressAccount": {
+                    "type": "boolean",
+                    "description": "Act on the duress account rather than the real one."
+                  }
+                },
+                "required": [
+                  "pin"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/delete-pin": {
+      "post": {
+        "operationId": "deletePin",
+        "summary": "Remove the PIN.",
+        "description": "**Core call:** `account.deletePin`\n\n**Command line**\n\n```\ndelete-pin\n```\n\nPIN login stops working on this device; other methods are untouched.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "delete-pin",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.deletePin",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/check-pin": {
+      "post": {
+        "operationId": "checkPin",
+        "summary": "Verify a PIN.",
+        "description": "**Core call:** `account.checkPin`\n\n**Command line**\n\n```\ncheck-pin --pin=<pin> [--for-duress-account[=false]]\n```\n\n",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "check-pin",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.checkPin",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "False for a wrong PIN — not an error response."
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "pin": {
+                    "type": "string",
+                    "description": "The device PIN, usually four digits."
+                  },
+                  "forDuressAccount": {
+                    "type": "boolean",
+                    "description": "Act on the duress account rather than the real one."
+                  }
+                },
+                "required": [
+                  "pin"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/change-username": {
+      "post": {
+        "operationId": "changeUsername",
+        "summary": "Change the username.",
+        "description": "**Core call:** `account.changeUsername`\n\n**Command line**\n\n```\nchange-username --username=<username> [--password=<password>]\n```\n\nThe old name is released, so it becomes available to anyone else.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "change-username",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.changeUsername",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "USERNAME_ERROR, BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "username": {
+                    "type": "string",
+                    "description": "The new username."
+                  },
+                  "password": {
+                    "type": "string",
+                    "description": "Required by core when the account has a password."
+                  }
+                },
+                "required": [
+                  "username"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/change-recovery": {
+      "post": {
+        "operationId": "changeRecovery",
+        "summary": "Set recovery questions and answers.",
+        "description": "**Core call:** `account.changeRecovery`\n\n**Command line**\n\n```\nchange-recovery --question=<questions> … --answer=<answers> …\n```\n\nThe returned key is half of the credential: without it the answers alone cannot recover the account, so it has to be stored somewhere else.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "change-recovery",
+          "flags": [
+            {
+              "name": "question",
+              "maps": "questions",
+              "repeat": true
+            },
+            {
+              "name": "answer",
+              "maps": "answers",
+              "repeat": true
+            }
+          ],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.changeRecovery",
+        "x-core-note": "Our surface drops the `2` from core's recovery2 naming; a future Recovery1 would be suffixed `V1`.",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "recoveryKey": {
+                      "type": "string",
+                      "description": "Store this out of band. `login-with-recovery` needs it alongside the answers."
+                    }
+                  },
+                  "required": [
+                    "recoveryKey"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "questions": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "The questions to ask."
+                  },
+                  "answers": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Same length and order as `questions`."
+                  }
+                },
+                "required": [
+                  "questions",
+                  "answers"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/delete-recovery": {
+      "post": {
+        "operationId": "deleteRecovery",
+        "summary": "Disable recovery login.",
+        "description": "**Core call:** `account.deleteRecovery`\n\n**Command line**\n\n```\ndelete-recovery\n```\n\nThe existing recovery key stops working.",
+        "tags": [
+          "Credentials"
+        ],
+        "x-cli": {
+          "command": "delete-recovery",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.deleteRecovery",
+        "x-source": "src/cli/engine/routes/credentials.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/otp-key": {
+      "get": {
+        "operationId": "otpKey",
+        "summary": "Read the 2FA secret and reset state.",
+        "description": "**Core call:** `account.otpKey`\n\n**Command line**\n\n```\notp-key\n```\n\n",
+        "tags": [
+          "Two-factor authentication"
+        ],
+        "x-cli": {
+          "command": "otp-key",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.otpKey",
+        "x-core-note": "Also carries account.otpResetDate.",
+        "x-source": "src/cli/engine/routes/otp.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "otpKey": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Null when 2FA is off. The 2FA secret itself. Secret material — record it safely."
+                    },
+                    "otpResetDate": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Set once somebody has requested a reset; cancel it with `cancel-otp-reset`."
+                    }
+                  },
+                  "required": [
+                    "otpKey",
+                    "otpResetDate"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/enable-otp": {
+      "post": {
+        "operationId": "enableOtp",
+        "summary": "Enable 2FA.",
+        "description": "**Core call:** `account.enableOtp`\n\n**Command line**\n\n```\nenable-otp [--timeout=<timeout>]\n```\n\nRecord the returned key before leaving the terminal: it is the only copy.",
+        "tags": [
+          "Two-factor authentication"
+        ],
+        "x-cli": {
+          "command": "enable-otp",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.enableOtp",
+        "x-source": "src/cli/engine/routes/otp.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "otpKey": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The new secret. The 2FA secret itself. Secret material — record it safely."
+                    }
+                  },
+                  "required": [
+                    "otpKey"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "timeout": {
+                    "type": "number",
+                    "description": "How long a reset request must wait before it completes, in seconds. Core supplies the default when omitted."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/disable-otp": {
+      "post": {
+        "operationId": "disableOtp",
+        "summary": "Disable 2FA.",
+        "description": "**Core call:** `account.disableOtp`\n\n**Command line**\n\n```\ndisable-otp\n```\n\nLogins stop requiring a code immediately.",
+        "tags": [
+          "Two-factor authentication"
+        ],
+        "x-cli": {
+          "command": "disable-otp",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.disableOtp",
+        "x-source": "src/cli/engine/routes/otp.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/cancel-otp-reset": {
+      "post": {
+        "operationId": "cancelOtpReset",
+        "summary": "Cancel a pending 2FA reset.",
+        "description": "**Core call:** `account.cancelOtpReset`\n\n**Command line**\n\n```\ncancel-otp-reset\n```\n\nThe defence against somebody else requesting a reset on your account: as long as you cancel before the timer runs out, their reset never lands.",
+        "tags": [
+          "Two-factor authentication"
+        ],
+        "x-cli": {
+          "command": "cancel-otp-reset",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.cancelOtpReset",
+        "x-source": "src/cli/engine/routes/otp.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/repair-otp": {
+      "post": {
+        "operationId": "repairOtp",
+        "summary": "Re-point the account at a known 2FA secret.",
+        "description": "**Core call:** `account.repairOtp`\n\n**Command line**\n\n```\nrepair-otp --otp-key=<otpKey>\n```\n\nFor a device whose stored secret has drifted from the server's.",
+        "tags": [
+          "Two-factor authentication"
+        ],
+        "x-cli": {
+          "command": "repair-otp",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.repairOtp",
+        "x-source": "src/cli/engine/routes/otp.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "OTP_REQUIRED, BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "otpKey": {
+                    "type": "string",
+                    "description": "The secret the account should use."
+                  }
+                },
+                "required": [
+                  "otpKey"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/pending-vouchers": {
+      "get": {
+        "operationId": "pendingVouchers",
+        "summary": "List pending 2FA vouchers.",
+        "description": "**Core call:** `account.pendingVouchers`\n\n**Command line**\n\n```\npending-vouchers\n```\n\nWhen 2FA blocks a login, the login server issues a voucher that an already-trusted device can approve or reject.",
+        "tags": [
+          "Vouchers"
+        ],
+        "x-cli": {
+          "command": "pending-vouchers",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.pendingVouchers",
+        "x-source": "src/cli/engine/routes/vouchers.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "pendingVouchers": {
+                      "type": "array",
+                      "items": {},
+                      "description": "`EdgePendingVoucher[]`: voucherId, activates, created, deviceDescription, ipDescription."
+                    }
+                  },
+                  "required": [
+                    "pendingVouchers"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/approve-voucher": {
+      "post": {
+        "operationId": "approveVoucher",
+        "summary": "Approve a voucher.",
+        "description": "**Core call:** `account.approveVoucher`\n\n**Command line**\n\n```\napprove-voucher --voucher-id=<voucherId>\n```\n\nLets the waiting device finish logging in.",
+        "tags": [
+          "Vouchers"
+        ],
+        "x-cli": {
+          "command": "approve-voucher",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.approveVoucher",
+        "x-source": "src/cli/engine/routes/vouchers.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "voucherId": {
+                    "type": "string",
+                    "description": "From `pending-vouchers`, or an `OTP_REQUIRED` error’s `details.voucherId`."
+                  }
+                },
+                "required": [
+                  "voucherId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/reject-voucher": {
+      "post": {
+        "operationId": "rejectVoucher",
+        "summary": "Reject a voucher.",
+        "description": "**Core call:** `account.rejectVoucher`\n\n**Command line**\n\n```\nreject-voucher --voucher-id=<voucherId>\n```\n\nDenies the waiting device. The login it was issued for cannot complete.",
+        "tags": [
+          "Vouchers"
+        ],
+        "x-cli": {
+          "command": "reject-voucher",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.rejectVoucher",
+        "x-source": "src/cli/engine/routes/vouchers.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "voucherId": {
+                    "type": "string",
+                    "description": "From `pending-vouchers`, or an `OTP_REQUIRED` error’s `details.voucherId`."
+                  }
+                },
+                "required": [
+                  "voucherId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/fetch-lobby/{lobbyId}": {
+      "get": {
+        "operationId": "fetchLobby",
+        "summary": "Inspect a login request.",
+        "description": "**Core call:** `account.fetchLobby`\n\n**Command line**\n\n```\nfetch-lobby <lobbyId>\n```\n\nThe other side of `request-edge-login`: shows who is asking, so a human can decide before approving.",
+        "tags": [
+          "Approving a login"
+        ],
+        "x-cli": {
+          "command": "fetch-lobby",
+          "positional": "lobbyId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.fetchLobby",
+        "x-source": "src/cli/engine/routes/lobby.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "lobbyId",
+            "in": "path",
+            "required": true,
+            "description": "From the QR code, or an `edge://edge/<lobbyId>` link.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "lobbyId": {
+                      "type": "string",
+                      "description": "The lobby that was fetched, echoed back."
+                    },
+                    "loginRequest": {
+                      "anyOf": [
+                        {
+                          "description": "{ appId: string; displayName: string; displayImageDarkUrl: string"
+                        },
+                        {
+                          "description": "null; displayImageLightUrl: string"
+                        },
+                        {
+                          "description": "null; }"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Null when the lobby carries no pending login request."
+                    }
+                  },
+                  "required": [
+                    "lobbyId",
+                    "loginRequest"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/approve-login-request/{lobbyId}": {
+      "post": {
+        "operationId": "approveLoginRequest",
+        "summary": "Approve a login request.",
+        "description": "**Core call:** `EdgeLoginRequest.approve`\n\n**Command line**\n\n```\napprove-login-request <lobbyId>\n```\n\nGrants the requesting device access to this account.",
+        "tags": [
+          "Approving a login"
+        ],
+        "x-cli": {
+          "command": "approve-login-request",
+          "positional": "lobbyId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "EdgeLoginRequest.approve",
+        "x-core-note": "Reached through account.fetchLobby(lobbyId).loginRequest.",
+        "x-source": "src/cli/engine/routes/lobby.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "lobbyId",
+            "in": "path",
+            "required": true,
+            "description": "From the QR code, or an `edge://edge/<lobbyId>` link.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "Always true; a failure arrives as an error envelope."
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "NO_LOGIN_REQUEST, BAD_REQUEST, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/all-keys": {
+      "get": {
+        "operationId": "allKeys",
+        "summary": "List every key in the account.",
+        "description": "**Core call:** `account.allKeys`\n\n**Command line**\n\n```\nall-keys\n```\n\nIncludes archived and deleted keys, unlike `currency-wallets`.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "all-keys",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.allKeys",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "allKeys": {
+                      "type": "array",
+                      "items": {},
+                      "description": "`EdgeWalletInfoFull[]`: id, type, keys, archived, deleted, hidden, sortIndex."
+                    }
+                  },
+                  "required": [
+                    "allKeys"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/create-wallet": {
+      "post": {
+        "operationId": "createWallet",
+        "summary": "Create a wallet from raw key JSON.",
+        "description": "**Core call:** `account.createWallet`\n\n**Command line**\n\n```\ncreate-wallet --type=<type> [--keys='<json>']\n```\n\nThe import path. Use `create-currency-wallet` to make a fresh wallet with generated keys.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "create-wallet",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.createWallet",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "walletId": {
+                      "type": "string",
+                      "description": "The new wallet. Its keys are already saved."
+                    }
+                  },
+                  "required": [
+                    "walletId"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "description": "Wallet type, e.g. `wallet:bitcoin`."
+                  },
+                  "keys": {
+                    "description": "Plugin key material. Omit to let core generate it."
+                  }
+                },
+                "required": [
+                  "type"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-wallet-info": {
+      "get": {
+        "operationId": "getWalletInfo",
+        "summary": "Read one wallet's key info.",
+        "description": "**Core call:** `account.getWalletInfo`\n\n**Command line**\n\n```\nget-wallet-info --id=<id>\n```\n\n",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "get-wallet-info",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getWalletInfo",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "query",
+            "required": true,
+            "description": "The key id, from `all-keys`. Base64, like a wallet id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`EdgeWalletInfoFull`, verbatim from core — including the `keys` object.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-raw-private-key": {
+      "get": {
+        "operationId": "getRawPrivateKey",
+        "summary": "Read raw private key material.",
+        "description": "**Core call:** `account.getRawPrivateKey`\n\n**Command line**\n\n```\nget-raw-private-key --wallet-id=<walletId>\n```\n\nSecret. Whatever the plugin stores — seed, mnemonic, xpriv.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "get-raw-private-key",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getRawPrivateKey",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The plugin’s key object, at the top level.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-raw-public-key": {
+      "get": {
+        "operationId": "getRawPublicKey",
+        "summary": "Read raw public key material.",
+        "description": "**Core call:** `account.getRawPublicKey`\n\n**Command line**\n\n```\nget-raw-public-key --wallet-id=<walletId>\n```\n\n",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "get-raw-public-key",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getRawPublicKey",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The plugin’s public key object.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-display-private-key": {
+      "get": {
+        "operationId": "getDisplayPrivateKey",
+        "summary": "Export the private key for display.",
+        "description": "**Core call:** `account.getDisplayPrivateKey`\n\n**Command line**\n\n```\nget-display-private-key --wallet-id=<walletId>\n```\n\nSecret. The human-facing form — WIF, seed phrase, whatever the plugin shows on its export screen.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "get-display-private-key",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getDisplayPrivateKey",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "description": "The displayable private key."
+                    }
+                  },
+                  "required": [
+                    "key"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-display-public-key": {
+      "get": {
+        "operationId": "getDisplayPublicKey",
+        "summary": "Export the public key for display.",
+        "description": "**Core call:** `account.getDisplayPublicKey`\n\n**Command line**\n\n```\nget-display-public-key --wallet-id=<walletId>\n```\n\nThe xpub or equivalent — safe to share for watch-only use.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "get-display-public-key",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.getDisplayPublicKey",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "description": "The displayable public key."
+                    }
+                  },
+                  "required": [
+                    "key"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/list-splittable-wallet-types": {
+      "get": {
+        "operationId": "listSplittableWalletTypes",
+        "summary": "List chains a wallet can split into.",
+        "description": "**Core call:** `account.listSplittableWalletTypes`\n\n**Command line**\n\n```\nlist-splittable-wallet-types --wallet-id=<walletId>\n```\n\nForked-chain support: which wallet types can be derived from these keys.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "list-splittable-wallet-types",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.listSplittableWalletTypes",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "walletTypes": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Types valid for `split`."
+                    }
+                  },
+                  "required": [
+                    "walletTypes"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/change-wallet-states": {
+      "post": {
+        "operationId": "changeWalletStates",
+        "summary": "Archive, delete, hide, or reorder wallets.",
+        "description": "**Core call:** `account.changeWalletStates`\n\n**Command line**\n\n```\nchange-wallet-states [--wallet-states='<json>'] --wallet-id=<value> [--archived=<value>] [--deleted=<value>] [--hidden=<value>] [--sort-index=<value>]\n```\n\nThe canonical backend for every wallet flag; there are no separate archive, unarchive or undelete verbs.",
+        "tags": [
+          "Keys"
+        ],
+        "x-cli": {
+          "command": "change-wallet-states",
+          "flags": [],
+          "extra": [
+            {
+              "name": "wallet-id",
+              "kind": "string",
+              "required": true,
+              "doc": "The wallet to change. The command makes it the key of a single-entry `walletStates` map."
+            },
+            {
+              "name": "archived",
+              "kind": "boolstr",
+              "required": false,
+              "doc": "Hide from the active list."
+            },
+            {
+              "name": "deleted",
+              "kind": "boolstr",
+              "required": false,
+              "doc": "Mark deleted."
+            },
+            {
+              "name": "hidden",
+              "kind": "boolstr",
+              "required": false,
+              "doc": "Hide from the wallet picker."
+            },
+            {
+              "name": "sort-index",
+              "kind": "string",
+              "required": false,
+              "doc": "Position in the wallet list."
+            }
+          ],
+          "custom": true,
+          "preset": {},
+          "notes": "The command builds a single-wallet `walletStates` map from these flags, and needs at least one."
+        },
+        "x-core-call": "account.changeWalletStates",
+        "x-source": "src/cli/engine/routes/keys.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletStates": {
+                    "anyOf": [
+                      {
+                        "description": "{ [keys: string]: { archived: boolean"
+                      },
+                      {
+                        "description": "undefined; deleted: boolean"
+                      },
+                      {
+                        "description": "undefined; hidden: boolean"
+                      },
+                      {
+                        "description": "undefined; sortIndex: number"
+                      },
+                      {
+                        "description": "undefined; }; }"
+                      }
+                    ],
+                    "description": "`EdgeWalletStates`: wallet ids to the flags being changed."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet": {
+      "get": {
+        "operationId": "walletInfo",
+        "summary": "Wallet detail.",
+        "description": "**Core call:** _none — Engine composite of EdgeCurrencyWallet properties plus its EdgeCurrencyConfig token map._\n\n**Command line**\n\n```\nwallet-info --wallet-id=<walletId>\n```\n\n",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "wallet-info",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine composite of EdgeCurrencyWallet properties plus its EdgeCurrencyConfig token map.",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Every WalletSummary field, plus denominations and walletSettings. `allTokens` is not here — `wallet-tokens` exists to carry it, and returning it from both sent the same map twice in a session that calls both.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/rename-wallet": {
+      "post": {
+        "operationId": "renameWallet",
+        "summary": "Rename a wallet.",
+        "description": "**Core call:** `wallet.renameWallet`\n\n**Command line**\n\n```\nrename-wallet --wallet-id=<walletId> --name=<name>\n```\n\n",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "rename-wallet",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.renameWallet",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "The new display name."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "name"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/set-fiat-currency-code": {
+      "post": {
+        "operationId": "setFiatCurrencyCode",
+        "summary": "Change a wallet's fiat currency.",
+        "description": "**Core call:** `wallet.setFiatCurrencyCode`\n\n**Command line**\n\n```\nset-fiat-currency-code --wallet-id=<walletId> --fiat-currency-code=<fiatCurrencyCode>\n```\n\nAffects how balances and history are priced, not the asset itself.",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "set-fiat-currency-code",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.setFiatCurrencyCode",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "fiatCurrencyCode": {
+                    "type": "string",
+                    "description": "e.g. `iso:EUR`."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "fiatCurrencyCode"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/change-paused": {
+      "post": {
+        "operationId": "changePaused",
+        "summary": "Pause or resume a wallet engine.",
+        "description": "**Core call:** `wallet.changePaused`\n\n**Command line**\n\n```\nchange-paused --wallet-id=<walletId> --paused=true|false\n```\n\nA paused wallet stops syncing, which is how a caller quiets a chain it does not currently care about.",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "change-paused",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.changePaused",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "paused": {
+                    "type": "boolean",
+                    "description": "True to stop syncing."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "paused"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/sync": {
+      "post": {
+        "operationId": "walletSync",
+        "summary": "Nudge one wallet to sync.",
+        "description": "**Core call:** `wallet.sync`\n\n**Command line**\n\n```\nwallet-sync --wallet-id=<walletId>\n```\n\n",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "wallet-sync",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.sync",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/resync-blockchain": {
+      "post": {
+        "operationId": "resyncBlockchain",
+        "summary": "Rescan the blockchain from scratch.",
+        "description": "**Core call:** `wallet.resyncBlockchain`\n\n**Command line**\n\n```\nresync-blockchain --wallet-id=<walletId>\n```\n\nDrops cached chain state and re-scans. Expensive, and the wallet reports an incomplete balance until it finishes.",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "resync-blockchain",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.resyncBlockchain",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/split": {
+      "post": {
+        "operationId": "splitWallet",
+        "summary": "Split a wallet into another chain.",
+        "description": "**Core call:** `wallet.split`\n\n**Command line**\n\n```\nsplit --wallet-id=<walletId> --split-wallets='<json>'\n```\n\nForked-chain support: derive a wallet of a different type from the same keys. `list-splittable-wallet-types` says which are valid.",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "split",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.split",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {},
+                      "description": "Per-entry outcomes, like batch create."
+                    }
+                  },
+                  "required": [
+                    "results"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "splitWallets": {
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "description": "{ walletType: string; name: string"
+                        },
+                        {
+                          "description": "undefined; fiatCurrencyCode: string"
+                        },
+                        {
+                          "description": "undefined; }"
+                        }
+                      ]
+                    },
+                    "description": "`EdgeSplitCurrencyWallet[]`: walletType, plus optional name and fiatCurrencyCode."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "splitWallets"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/dump-data": {
+      "get": {
+        "operationId": "dumpData",
+        "summary": "Dump wallet engine state.",
+        "description": "**Core call:** `wallet.dumpData`\n\n**Command line**\n\n```\ndump-data --wallet-id=<walletId>\n```\n\nPlugin-defined debug output. Shape varies by plugin and can be very large.",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "dump-data",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.dumpData",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`EdgeDataDump`, straight from the plugin.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/balance-map": {
+      "get": {
+        "operationId": "balanceMap",
+        "summary": "Balances for every asset in the wallet.",
+        "description": "**Core call:** `wallet.balanceMap`\n\n**Command line**\n\n```\nbalance-map --wallet-id=<walletId> [--token-id=<value>]\n```\n\nThe native currency plus every enabled token.",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "balance-map",
+          "flags": [],
+          "extra": [
+            {
+              "name": "token-id",
+              "kind": "string",
+              "required": false,
+              "doc": "Client-side filter; core has no single-balance accessor."
+            }
+          ],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "wallet.balanceMap",
+        "x-core-note": "Rendered as an array, with currencyCode and displayAmount added from the wallet's denominations.",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "balances": {
+                      "type": "array",
+                      "items": {
+                        "anyOf": [
+                          {
+                            "description": "{ tokenId: string"
+                          },
+                          {
+                            "description": "null; currencyCode: string; nativeAmount: string; displayAmount: string"
+                          },
+                          {
+                            "description": "null; unknownToken: boolean; }"
+                          }
+                        ]
+                      },
+                      "description": "One entry per asset the wallet holds, native coin first: `tokenId`, `currencyCode`, `nativeAmount`, `displayAmount` and `unknownToken`. A token the plugin reports a balance for but whose config it no longer carries is listed with `unknownToken: true` and a null `displayAmount`, rather than failing the whole wallet."
+                    }
+                  },
+                  "required": [
+                    "balances"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/get-addresses": {
+      "get": {
+        "operationId": "getAddresses",
+        "summary": "Receive addresses.",
+        "description": "**Core call:** `wallet.getAddresses`\n\n**Command line**\n\n```\nget-addresses --wallet-id=<walletId> [--token-id=<tokenId>] [--force-index=<forceIndex>]\n```\n\n",
+        "tags": [
+          "Wallet state"
+        ],
+        "x-cli": {
+          "command": "get-addresses",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.getAddresses",
+        "x-source": "src/cli/engine/routes/wallets.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tokenId",
+            "in": "query",
+            "required": false,
+            "description": "Defaults to the native asset.",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          {
+            "name": "forceIndex",
+            "in": "query",
+            "required": false,
+            "description": "Derive at a specific index.",
+            "schema": {
+              "type": "number"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "addresses": {
+                      "type": "array",
+                      "items": {},
+                      "description": "`EdgeAddress[]`: addressType, publicAddress, nativeBalance."
+                    }
+                  },
+                  "required": [
+                    "addresses"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "TOKEN_NOT_FOUND, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/tokens": {
+      "get": {
+        "operationId": "walletTokens",
+        "summary": "List a wallet's tokens.",
+        "description": "**Core call:** _none — Engine composite of the EdgeCurrencyConfig token maps plus wallet.enabledTokenIds and wallet.detectedTokenIds._\n\n**Command line**\n\n```\nwallet-tokens --wallet-id=<walletId>\n```\n\n\"Enabled\" tokens are the ones the wallet syncs balances for; \"detected\" ones were seen on-chain but are not yet enabled.",
+        "tags": [
+          "Tokens"
+        ],
+        "x-cli": {
+          "command": "wallet-tokens",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine composite of the EdgeCurrencyConfig token maps plus wallet.enabledTokenIds and wallet.detectedTokenIds.",
+        "x-source": "src/cli/engine/routes/tokens.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "allTokens": {
+                      "description": "`EdgeToken` by tokenId: everything the plugin ships with, plus this account’s own. `builtinTokens` is not returned separately — it is this map minus `customTokens`, and sending both wrote the whole built-in list down the socket twice."
+                    },
+                    "customTokens": {
+                      "description": "`EdgeToken` by tokenId: tokens this account added by hand."
+                    },
+                    "enabledTokenIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Which of the above the wallet is actually tracking."
+                    },
+                    "detectedTokenIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Seen on-chain but not enabled, so their balances are not synced."
+                    }
+                  },
+                  "required": [
+                    "allTokens",
+                    "customTokens",
+                    "enabledTokenIds",
+                    "detectedTokenIds"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/change-enabled-token-ids": {
+      "post": {
+        "operationId": "changeEnabledTokenIds",
+        "summary": "Set the enabled token set.",
+        "description": "**Core call:** `wallet.changeEnabledTokenIds`\n\n**Command line**\n\n```\nchange-enabled-token-ids --wallet-id=<walletId> --token-ids='<json>' [--add=<value>] [--remove=<value>]\n```\n\nAbsolute: anything missing from `tokenIds` is disabled. Core has only this setter, so there is no add or remove call.",
+        "tags": [
+          "Tokens"
+        ],
+        "x-cli": {
+          "command": "change-enabled-token-ids",
+          "flags": [],
+          "extra": [
+            {
+              "name": "add",
+              "kind": "repeat",
+              "required": false,
+              "doc": "Read the current set, add this id, write it back."
+            },
+            {
+              "name": "remove",
+              "kind": "repeat",
+              "required": false,
+              "doc": "Read the current set, drop this id, write it back."
+            }
+          ],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "wallet.changeEnabledTokenIds",
+        "x-source": "src/cli/engine/routes/tokens.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "enabledTokenIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "The wallet’s enabled tokens after the change, not just what changed."
+                    }
+                  },
+                  "required": [
+                    "enabledTokenIds"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "tokenIds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "The complete desired set."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "tokenIds"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/get-transactions": {
+      "get": {
+        "operationId": "getTransactions",
+        "summary": "List or export a wallet's transactions.",
+        "description": "**Core call:** `wallet.getTransactions`\n\n**Command line**\n\n```\nget-transactions --wallet-id=<walletId> [--token-id=<tokenId>] [--limit=<limit>] [--offset=<offset>] [--save-export-prefs[=false]] [--start-date=<startDate>] [--end-date=<endDate>] [--search-string=<searchString>] [--spam-threshold=<spamThreshold>] [--fiat=<fiat>] [--export-format=<exportFormat>] [--bitwave-account=<bitwaveAccountId>] [--out=<value>]\n```\n\nReads history, overlays the display metadata the GUI shows, fills historical fiat, and optionally formats the result — all on this one call.",
+        "tags": [
+          "Transactions"
+        ],
+        "x-cli": {
+          "command": "get-transactions",
+          "flags": [
+            {
+              "name": "bitwave-account",
+              "maps": "bitwaveAccountId",
+              "repeat": false
+            }
+          ],
+          "extra": [
+            {
+              "name": "out",
+              "kind": "string",
+              "required": false,
+              "requiredWith": "exportFormat",
+              "doc": "Where to write the returned files. One format: the path. Several: a stem, plus .csv / .qbo / .bitwave.csv."
+            }
+          ],
+          "custom": true,
+          "preset": {}
+        },
+        "x-core-call": "wallet.getTransactions",
+        "x-source": "src/cli/engine/routes/transactions.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tokenId",
+            "in": "query",
+            "required": false,
+            "description": "Defaults to the native asset.",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "How many to return. Defaults to 100; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.",
+            "schema": {
+              "type": "number"
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "description": "Where to start. Defaults to 0.",
+            "schema": {
+              "type": "number"
+            }
+          },
+          {
+            "name": "saveExportPrefs",
+            "in": "query",
+            "required": false,
+            "description": "Save `bitwaveAccountId` and the chosen formats into the wallet’s synced `exportTxInfo.json`, which the GUI export scene reads back. Off by default: a read does not change saved preferences.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "startDate",
+            "in": "query",
+            "required": false,
+            "description": "ISO-8601, or epoch milliseconds.",
+            "schema": {
+              "description": "Date"
+            }
+          },
+          {
+            "name": "endDate",
+            "in": "query",
+            "required": false,
+            "description": "ISO-8601, or epoch milliseconds.",
+            "schema": {
+              "description": "Date"
+            }
+          },
+          {
+            "name": "searchString",
+            "in": "query",
+            "required": false,
+            "description": "Matches payee, category, notes and txid.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "spamThreshold",
+            "in": "query",
+            "required": false,
+            "description": "Native-amount floor. Omitted, the account spam-filter setting applies; a value always overrides it, and `0` shows everything. An empty value reads as omitted, like every other query parameter.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "fiat",
+            "in": "query",
+            "required": false,
+            "description": "Three-letter ISO 4217 code. Defaults to the account defaultIsoFiat.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "exportFormat",
+            "in": "query",
+            "required": false,
+            "description": "Comma list of `csv`, `qbo`, `bitwave`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "bitwaveAccountId",
+            "in": "query",
+            "required": false,
+            "description": "A 400 unless `exportFormat` includes `bitwave`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`{ transactions, total, isoFiat }`, or `{ ok, isoFiat, total, files }` when exportFormat is set. Each transaction carries `metadata.name`, `metadata.category` and `metadata.notes` as **localized prose** in the engine’s boot locale — the engine has no per-request locale, so a second shell with a different `LANG` reuses the first engine and gets its language. `displayInfo` beside them carries the machine values the prose was derived from (`direction`, `assetActionType`, `actionType`, and the `category` split whose `category` member is one of `transfer`, `exchange`, `expense`, `income`), so a caller can render its own text.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, MISSING_BITWAVE_ACCOUNT_ID, TOKEN_NOT_FOUND, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/get-num-transactions": {
+      "get": {
+        "operationId": "getNumTransactions",
+        "summary": "Count transactions in a wallet.",
+        "description": "**Core call:** `wallet.getNumTransactions`\n\n**Command line**\n\n```\nget-num-transactions --wallet-id=<walletId> [--token-id=<tokenId>]\n```\n\nCheaper than listing when only the total matters.",
+        "tags": [
+          "Transactions"
+        ],
+        "x-cli": {
+          "command": "get-num-transactions",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.getNumTransactions",
+        "x-source": "src/cli/engine/routes/transactions.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tokenId",
+            "in": "query",
+            "required": false,
+            "description": "Defaults to the native asset.",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "numTransactions": {
+                      "type": "number",
+                      "description": "Every transaction the wallet knows of."
+                    }
+                  },
+                  "required": [
+                    "numTransactions"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "TOKEN_NOT_FOUND, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/save-tx-metadata": {
+      "post": {
+        "operationId": "saveTxMetadata",
+        "summary": "Save transaction metadata.",
+        "description": "**Core call:** `wallet.saveTxMetadata`\n\n**Command line**\n\n```\nsave-tx-metadata --wallet-id=<walletId> --txid=<txid> [--token-id=<tokenId>] --metadata='<json>'\n```\n\nOne of the paths that write transaction metadata to disk. The others are `save-tx-action`, which writes `savedAction` and `assetAction` to the same file, and `save-tx` and `spend`, both of which re-apply the caller's metadata through `saveTxAndMetadata` after the transaction is saved.",
+        "tags": [
+          "Transactions"
+        ],
+        "x-cli": {
+          "command": "save-tx-metadata",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.saveTxMetadata",
+        "x-source": "src/cli/engine/routes/transactions.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, TOKEN_NOT_FOUND, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "txid": {
+                    "type": "string",
+                    "description": "Which transaction to tag."
+                  },
+                  "tokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "metadata": {
+                    "description": "`EdgeMetadataChange`: name, category, notes, exchangeAmount, bizId. `null` on a field deletes it; omitting the field leaves it unchanged."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "txid",
+                  "metadata"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/save-tx-action": {
+      "post": {
+        "operationId": "saveTxAction",
+        "summary": "Save a transaction action.",
+        "description": "**Core call:** `wallet.saveTxAction`\n\n**Command line**\n\n```\nsave-tx-action --wallet-id=<walletId> --txid=<txid> [--token-id=<tokenId>] --saved-action='<json>' [--asset-action='<json>']\n```\n\nRecords what a transaction *was* — a swap, a stake — beyond its metadata.",
+        "tags": [
+          "Transactions"
+        ],
+        "x-cli": {
+          "command": "save-tx-action",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.saveTxAction",
+        "x-source": "src/cli/engine/routes/transactions.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, TOKEN_NOT_FOUND, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "txid": {
+                    "type": "string",
+                    "description": "Which transaction to annotate."
+                  },
+                  "tokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "savedAction": {
+                    "anyOf": [
+                      {
+                        "description": "import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxActionSwap"
+                      },
+                      {
+                        "description": "import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxActionStake"
+                      },
+                      {
+                        "description": "import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxActionFiat"
+                      },
+                      {
+                        "description": "import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxActionTokenApproval"
+                      },
+                      {
+                        "description": "import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxActionGiftCard"
+                      }
+                    ],
+                    "description": "`EdgeTxAction` describing what happened, discriminated on `actionType`: swap, stake, fiat, tokenApproval or giftCard."
+                  },
+                  "assetAction": {
+                    "description": "`EdgeAssetAction`: one `assetActionType`."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "txid",
+                  "savedAction"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/object/{objectId}": {
+      "get": {
+        "operationId": "getObject",
+        "summary": "Inspect an object handle.",
+        "description": "**Core call:** _none — Engine handle store; core identifies these values by object reference._\n\n**Command line**\n\n```\nobject-get <objectId>\n```\n\nWorks for every kind: transactions, pending logins, swap quotes and lobbies.",
+        "tags": [
+          "Object handles"
+        ],
+        "x-cli": {
+          "command": "object-get",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine handle store; core identifies these values by object reference.",
+        "x-source": "src/cli/engine/routes/objects.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "An ephemeral object handle id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports `value: null`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "When the engine took the handle."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Session that created the handle; only that session may use it."
+                    },
+                    "walletId": {
+                      "type": "string",
+                      "description": "Wallet the handle is bound to, when it belongs to one."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "createdAt",
+                    "expiresAt"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_IN_USE, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/object/delete/{objectId}": {
+      "post": {
+        "operationId": "deleteObject",
+        "summary": "Release an object handle.",
+        "description": "**Core call:** _none — Engine handle store._\n\n**Command line**\n\n```\nobject-delete <objectId>\n```\n\nRuns the handle's cleanup — closing a swap quote, cancelling a pending login — instead of waiting out the TTL.",
+        "tags": [
+          "Object handles"
+        ],
+        "x-cli": {
+          "command": "object-delete",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine handle store.",
+        "x-source": "src/cli/engine/routes/objects.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "An ephemeral object handle id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "Always true; a failure arrives as an error envelope."
+                    },
+                    "objectId": {
+                      "type": "string",
+                      "description": "The handle this call consumed. It is now expired."
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "objectId"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_IN_USE, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/get-max-spendable": {
+      "post": {
+        "operationId": "getMaxSpendable",
+        "summary": "Largest sendable amount.",
+        "description": "**Core call:** `wallet.getMaxSpendable`\n\n**Command line**\n\n```\nget-max-spendable --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']\n```\n\nWhat empties the wallet after fees. A destination is still required, since fees depend on it.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "get-max-spendable",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.getMaxSpendable",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "nativeAmount": {
+                      "type": "string",
+                      "description": "The most this wallet can send."
+                    }
+                  },
+                  "required": [
+                    "nativeAmount"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "TOKEN_NOT_FOUND, INSUFFICIENT_FUNDS, BAD_REQUEST, NETWORK_ERROR, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "spendInfo": {
+                    "anyOf": [
+                      {
+                        "description": "{ spendTargets: { publicAddress: string"
+                      },
+                      {
+                        "description": "undefined; nativeAmount: string"
+                      },
+                      {
+                        "description": "undefined; uniqueIdentifier: string"
+                      },
+                      {
+                        "description": "undefined; memo: string"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }[]; tokenId: string"
+                      },
+                      {
+                        "description": "null; metadata: EdgeMetadata"
+                      },
+                      {
+                        "description": "undefined; networkFeeOption: string"
+                      },
+                      {
+                        "description": "undefined; customNetworkFee: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; rbfTxid: string"
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "description": "undefined; memos: { [keys: string]: unknown; }"
+                        }
+                      },
+                      {
+                        "description": "undefined; assetAction: import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeAssetAction"
+                      },
+                      {
+                        "description": "undefined; savedAction: import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxAction"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }"
+                      }
+                    ],
+                    "description": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required."
+                  },
+                  "to": {
+                    "type": "string",
+                    "description": "Address or BIP21 URI, run through `wallet.parseUri`."
+                  },
+                  "nativeAmount": {
+                    "type": "string",
+                    "description": "How much, in native units."
+                  },
+                  "amount": {
+                    "type": "string",
+                    "description": "Alias of `nativeAmount`."
+                  },
+                  "tokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "metadata": {
+                    "description": "Wins over anything parsed out of the URI."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/spend": {
+      "post": {
+        "operationId": "spend",
+        "summary": "Send funds.",
+        "description": "**Core call:** _none — GUI composite: makeSpend, signTx, broadcastTx and saveTx together._\n\n**Command line**\n\n```\nspend [--use-max[=false]] [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']\n```\n\n`makeSpend`, then `signTx`, then optionally `broadcastTx` and `saveTx`, in one request. `broadcast` and `save` both default to true, so a bare body with a destination and an amount moves real money. A completed spend leaves no handle behind.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "spend",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-cli-alternates": [
+          {
+            "command": "spend-max",
+            "flags": [],
+            "extra": [],
+            "custom": false,
+            "preset": {
+              "useMax": true
+            },
+            "notes": "The same route with `useMax` preset, so it sends everything.",
+            "summary": "Send a wallet’s entire spendable balance."
+          }
+        ],
+        "x-core-call": null,
+        "x-core-note": "GUI composite: makeSpend, signTx, broadcastTx and saveTx together.",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`{ transaction }`, plus `saveError` when the broadcast succeeded but saving failed. With dryRun, a TransactionHandle instead.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "TOKEN_NOT_FOUND, INSUFFICIENT_FUNDS, DUST_SPEND, PENDING_FUNDS, SPEND_TO_SELF, NO_AMOUNT_SPECIFIED, BAD_REQUEST, NETWORK_ERROR, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "useMax": {
+                    "type": "boolean",
+                    "description": "Replace the first target’s amount with the maximum."
+                  },
+                  "dryRun": {
+                    "type": "boolean",
+                    "description": "Build only. Never signs or broadcasts."
+                  },
+                  "broadcast": {
+                    "type": "boolean",
+                    "description": "Defaults to **true**. With `false` the transaction is signed and not sent, so `save` then defaults to false as well — recording an unsent transaction marks its inputs spent locally for something the network will never confirm."
+                  },
+                  "save": {
+                    "type": "boolean",
+                    "description": "Record the transaction in the wallet. Defaults to whatever `broadcast` is. Setting it true alongside `broadcast: false` is refused: use `--dry-run`, or the staged `make-spend` → `sign-tx` → `broadcast-tx` → `save-tx` flow."
+                  },
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "spendInfo": {
+                    "anyOf": [
+                      {
+                        "description": "{ spendTargets: { publicAddress: string"
+                      },
+                      {
+                        "description": "undefined; nativeAmount: string"
+                      },
+                      {
+                        "description": "undefined; uniqueIdentifier: string"
+                      },
+                      {
+                        "description": "undefined; memo: string"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }[]; tokenId: string"
+                      },
+                      {
+                        "description": "null; metadata: EdgeMetadata"
+                      },
+                      {
+                        "description": "undefined; networkFeeOption: string"
+                      },
+                      {
+                        "description": "undefined; customNetworkFee: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; rbfTxid: string"
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "description": "undefined; memos: { [keys: string]: unknown; }"
+                        }
+                      },
+                      {
+                        "description": "undefined; assetAction: import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeAssetAction"
+                      },
+                      {
+                        "description": "undefined; savedAction: import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxAction"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }"
+                      }
+                    ],
+                    "description": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required."
+                  },
+                  "to": {
+                    "type": "string",
+                    "description": "Address or BIP21 URI, run through `wallet.parseUri`."
+                  },
+                  "nativeAmount": {
+                    "type": "string",
+                    "description": "How much, in native units."
+                  },
+                  "amount": {
+                    "type": "string",
+                    "description": "Alias of `nativeAmount`."
+                  },
+                  "tokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "metadata": {
+                    "description": "Wins over anything parsed out of the URI."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/make-spend": {
+      "post": {
+        "operationId": "makeSpend",
+        "summary": "Build an unsigned transaction.",
+        "description": "**Core call:** `wallet.makeSpend`\n\n**Command line**\n\n```\nmake-spend --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']\n```\n\nFirst step of the staged workflow: nothing is signed and no funds move. Inspect `transaction.networkFee` on the result before signing.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "make-spend",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.makeSpend",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Session that created the handle; only that session may use it."
+                    },
+                    "walletId": {
+                      "type": "string",
+                      "description": "Wallet the handle is bound to, when it belongs to one."
+                    },
+                    "transaction": {
+                      "description": "`EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "expiresAt",
+                    "transaction"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "TOKEN_NOT_FOUND, INSUFFICIENT_FUNDS, DUST_SPEND, NO_AMOUNT_SPECIFIED, BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "spendInfo": {
+                    "anyOf": [
+                      {
+                        "description": "{ spendTargets: { publicAddress: string"
+                      },
+                      {
+                        "description": "undefined; nativeAmount: string"
+                      },
+                      {
+                        "description": "undefined; uniqueIdentifier: string"
+                      },
+                      {
+                        "description": "undefined; memo: string"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }[]; tokenId: string"
+                      },
+                      {
+                        "description": "null; metadata: EdgeMetadata"
+                      },
+                      {
+                        "description": "undefined; networkFeeOption: string"
+                      },
+                      {
+                        "description": "undefined; customNetworkFee: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; rbfTxid: string"
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "description": "undefined; memos: { [keys: string]: unknown; }"
+                        }
+                      },
+                      {
+                        "description": "undefined; assetAction: import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeAssetAction"
+                      },
+                      {
+                        "description": "undefined; savedAction: import(\"/Users/paul/git-worktrees/edge-react-gui-cli/node_modules/edge-core-js/src/types/types\").EdgeTxAction"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }"
+                      }
+                    ],
+                    "description": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required."
+                  },
+                  "to": {
+                    "type": "string",
+                    "description": "Address or BIP21 URI, run through `wallet.parseUri`."
+                  },
+                  "nativeAmount": {
+                    "type": "string",
+                    "description": "How much, in native units."
+                  },
+                  "amount": {
+                    "type": "string",
+                    "description": "Alias of `nativeAmount`."
+                  },
+                  "tokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "metadata": {
+                    "description": "Wins over anything parsed out of the URI."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/sign-tx/{objectId}": {
+      "post": {
+        "operationId": "signTx",
+        "summary": "Sign a staged transaction.",
+        "description": "**Core call:** `wallet.signTx`\n\n**Command line**\n\n```\nsign-tx <objectId>\n```\n\nKeeps the same handle and pushes its expiry out another five minutes.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "sign-tx",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.signTx",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "From `make-spend`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Session that created the handle; only that session may use it."
+                    },
+                    "walletId": {
+                      "type": "string",
+                      "description": "Wallet the handle is bound to, when it belongs to one."
+                    },
+                    "transaction": {
+                      "description": "`EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "expiresAt",
+                    "transaction"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_WALLET_MISMATCH, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/broadcast-tx/{objectId}": {
+      "post": {
+        "operationId": "broadcastTx",
+        "summary": "Broadcast a signed transaction.",
+        "description": "**Core call:** `wallet.broadcastTx`\n\n**Command line**\n\n```\nbroadcast-tx <objectId>\n```\n\nThe irreversible step: once this returns, the funds have left the wallet.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "broadcast-tx",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.broadcastTx",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "From `sign-tx`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The handle survives, so `save-tx` can still run.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Session that created the handle; only that session may use it."
+                    },
+                    "walletId": {
+                      "type": "string",
+                      "description": "Wallet the handle is bound to, when it belongs to one."
+                    },
+                    "transaction": {
+                      "description": "`EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "expiresAt",
+                    "transaction"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_WALLET_MISMATCH, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/save-tx/{objectId}": {
+      "post": {
+        "operationId": "saveTx",
+        "summary": "Record a transaction and release its handle.",
+        "description": "**Core call:** `wallet.saveTx`\n\n**Command line**\n\n```\nsave-tx <objectId>\n```\n\nFinal step. The handle is gone afterwards, so a second call is a 404.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "save-tx",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.saveTx",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "The handle to persist and release.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "Always true; a failure arrives as an error envelope."
+                    },
+                    "objectId": {
+                      "type": "string",
+                      "description": "The handle this call consumed. It is now expired."
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "objectId"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_WALLET_MISMATCH, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/accelerate": {
+      "post": {
+        "operationId": "accelerate",
+        "summary": "Fee-bump a pending transaction.",
+        "description": "**Core call:** `wallet.accelerate`\n\n**Command line**\n\n```\naccelerate --wallet-id=<walletId> [--object-id=<objectId>] [--transaction='<json>']\n```\n\nReplace-by-fee, where the plugin supports it. Returns a new unsigned transaction to sign and broadcast.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "accelerate",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.accelerate",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Given objectId the same handle is updated; given a transaction a new one is created.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Session that created the handle; only that session may use it."
+                    },
+                    "walletId": {
+                      "type": "string",
+                      "description": "Wallet the handle is bound to, when it belongs to one."
+                    },
+                    "transaction": {
+                      "description": "`EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "expiresAt",
+                    "transaction"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_WALLET_MISMATCH, OBJECT_SESSION_MISMATCH, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "objectId": {
+                    "type": "string",
+                    "description": "Handle of the transaction to bump."
+                  },
+                  "transaction": {
+                    "anyOf": [
+                      {
+                        "description": "{ txid: string; currencyCode: string"
+                      },
+                      {
+                        "description": "undefined; nativeAmount: string"
+                      },
+                      {
+                        "description": "undefined; networkFee: string"
+                      },
+                      {
+                        "description": "undefined; walletId: string"
+                      },
+                      {
+                        "description": "undefined; }"
+                      }
+                    ],
+                    "description": "Or the transaction itself."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/sweep-private-keys": {
+      "post": {
+        "operationId": "sweepPrivateKeys",
+        "summary": "Sweep private keys into this wallet.",
+        "description": "**Core call:** `wallet.sweepPrivateKeys`\n\n**Command line**\n\n```\nsweep-private-keys --wallet-id=<walletId> --spend-info='<json>'\n```\n\nBuilds a transaction moving everything from an external key. Returns an unsigned handle: sign, broadcast and save it like any staged spend.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "sweep-private-keys",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.sweepPrivateKeys",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "sessionId": {
+                      "type": "string",
+                      "description": "Session that created the handle; only that session may use it."
+                    },
+                    "walletId": {
+                      "type": "string",
+                      "description": "Wallet the handle is bound to, when it belongs to one."
+                    },
+                    "transaction": {
+                      "description": "`EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "expiresAt",
+                    "transaction"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, INSUFFICIENT_FUNDS, NETWORK_ERROR, TOKEN_NOT_FOUND, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "spendInfo": {
+                    "anyOf": [
+                      {
+                        "description": "{ privateKeys: string[]; tokenId: string"
+                      },
+                      {
+                        "description": "null; spendTargets: { publicAddress: string"
+                      },
+                      {
+                        "description": "undefined; nativeAmount: string"
+                      },
+                      {
+                        "description": "undefined; uniqueIdentifier: string"
+                      },
+                      {
+                        "description": "undefined; memo: string"
+                      },
+                      {
+                        "description": "undefined; otherParams: { [keys: string]: unknown; }"
+                      },
+                      {
+                        "description": "undefined; }[]; metadata: EdgeMetadata"
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "description": "undefined; memos: { [keys: string]: unknown; }"
+                        }
+                      },
+                      {
+                        "description": "undefined; }"
+                      }
+                    ],
+                    "description": "The keys to sweep in `privateKeys`, plus the optional `spendTargets`, `tokenId`, `metadata` and `memos` of a spend."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "spendInfo"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/sign-bytes": {
+      "post": {
+        "operationId": "signBytes",
+        "summary": "Sign arbitrary bytes.",
+        "description": "**Core call:** `wallet.signBytes`\n\n**Command line**\n\n```\nsign-bytes --wallet-id=<walletId> [--bytes=<bytes>] [--other-params='<json>']\n```\n\nMessage signing and proof-of-ownership, for plugins that support it.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "sign-bytes",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.signBytes",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "signature": {
+                      "type": "string",
+                      "description": "Base64."
+                    }
+                  },
+                  "required": [
+                    "signature"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "bytes": {
+                    "type": "string",
+                    "description": "Base64. Defaults to empty when absent."
+                  },
+                  "otherParams": {
+                    "description": "Plugin-specific options. Bitcoin needs `{ publicAddress }`; other plugins take nothing, or refuse the call entirely."
+                  }
+                },
+                "required": [
+                  "walletId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/get-payment-protocol-info": {
+      "get": {
+        "operationId": "getPaymentProtocolInfo",
+        "summary": "Fetch a BIP70 payment request.",
+        "description": "**Core call:** `wallet.getPaymentProtocolInfo`\n\n**Command line**\n\n```\nget-payment-protocol-info --wallet-id=<walletId> --payment-protocol-url=<paymentProtocolUrl>\n```\n\nFeed `spendTargets` from the result into `make-spend` to pay it.",
+        "tags": [
+          "Spending"
+        ],
+        "x-cli": {
+          "command": "get-payment-protocol-info",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.getPaymentProtocolInfo",
+        "x-source": "src/cli/engine/routes/spend.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": true,
+            "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "paymentProtocolUrl",
+            "in": "query",
+            "required": true,
+            "description": "The payment-request URL.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`EdgePaymentProtocolInfo`: domain, memo, merchant, nativeAmount, spendTargets.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/fetch-swap-quotes": {
+      "post": {
+        "operationId": "fetchSwapQuotes",
+        "summary": "Fetch swap quotes.",
+        "description": "**Core call:** `account.fetchSwapQuotes`\n\n**Command line**\n\n```\nfetch-swap-quotes --from-wallet-id=<fromWalletId> --to-wallet-id=<toWalletId> --native-amount=<nativeAmount> [--from-token-id=<fromTokenId>] [--to-token-id=<toTokenId>] [--quote-for=from|max|to] [--plugin-id=<preferPluginId>]\n```\n\nPolls every enabled swap plugin and parks each result under its own `swap_` handle with a 5 minute TTL.",
+        "tags": [
+          "Swap quotes"
+        ],
+        "x-cli": {
+          "command": "fetch-swap-quotes",
+          "flags": [
+            {
+              "name": "plugin-id",
+              "maps": "preferPluginId",
+              "repeat": false
+            }
+          ],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.fetchSwapQuotes",
+        "x-source": "src/cli/engine/routes/swap.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "quoteCount": {
+                      "type": "number",
+                      "description": "How many plugins answered."
+                    },
+                    "quotes": {
+                      "type": "array",
+                      "items": {
+                        "anyOf": [
+                          {
+                            "description": "{ objectId: string; kind: string; expiresAt: string; pluginId: string; isEstimate: boolean; canBePartial: boolean"
+                          },
+                          {
+                            "description": "null; maxFulfillmentSeconds: number"
+                          },
+                          {
+                            "description": "null; minReceiveAmount: string"
+                          },
+                          {
+                            "description": "null; fromNativeAmount: string; toNativeAmount: string; networkFee: { nativeAmount: string; tokenId: string"
+                          },
+                          {
+                            "description": "null; }; quoteExpirationDate: string"
+                          },
+                          {
+                            "description": "null; swapInfo: { pluginId: string; displayName: string; supportEmail: string; isDex: boolean"
+                          },
+                          {
+                            "description": "null; }; request: { fromTokenId: string"
+                          },
+                          {
+                            "description": "null; toTokenId: string"
+                          },
+                          {
+                            "description": "null; nativeAmount: string; quoteFor: \"from\""
+                          },
+                          {
+                            "description": "\"to\""
+                          },
+                          {
+                            "description": "\"max\"; fromWalletId: string; toWalletId: string; }; }"
+                          }
+                        ]
+                      },
+                      "description": "One quote per plugin that answered, each already parked under its own handle. Plugins that failed or had nothing to offer are simply absent."
+                    }
+                  },
+                  "required": [
+                    "quoteCount",
+                    "quotes"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, SWAP_BELOW_LIMIT, SWAP_ABOVE_LIMIT, SWAP_CURRENCY, SWAP_PERMISSION, SWAP_ADDRESS, SAME_CURRENCY, INSUFFICIENT_FUNDS, WALLET_NOT_FOUND, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "fromWalletId": {
+                    "type": "string",
+                    "description": "Source wallet. Accepts a unique prefix."
+                  },
+                  "toWalletId": {
+                    "type": "string",
+                    "description": "Destination wallet."
+                  },
+                  "nativeAmount": {
+                    "type": "string",
+                    "description": "How much, in native units."
+                  },
+                  "fromTokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "toTokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "quoteFor": {
+                    "anyOf": [
+                      {
+                        "description": "\"from\""
+                      },
+                      {
+                        "description": "\"max\""
+                      },
+                      {
+                        "description": "\"to\""
+                      }
+                    ],
+                    "description": "`from` spends this much of the source, `to` receives this much at the destination, `max` sends everything. Defaults to `from`."
+                  },
+                  "preferPluginId": {
+                    "type": "string",
+                    "description": "Restrict to one exchange."
+                  }
+                },
+                "required": [
+                  "fromWalletId",
+                  "toWalletId",
+                  "nativeAmount"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/swap-quote/{objectId}": {
+      "get": {
+        "operationId": "getSwapQuote",
+        "summary": "Re-read a quote.",
+        "description": "**Core call:** _none — Engine handle store; the quote is a live EdgeSwapQuote held server-side._\n\n**Command line**\n\n```\nswap-quote-get <objectId>\n```\n\n",
+        "tags": [
+          "Swap quotes"
+        ],
+        "x-cli": {
+          "command": "swap-quote-get",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine handle store; the quote is a live EdgeSwapQuote held server-side.",
+        "x-source": "src/cli/engine/routes/swap.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "An ephemeral object handle id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "Handle for the value the engine is holding. Pass it to the calls that consume it."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "description": "What the handle refers to, which decides the calls that accept it."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine drops the handle. Handles live 5 minutes."
+                    },
+                    "pluginId": {
+                      "type": "string",
+                      "description": "Swap provider that produced this quote."
+                    },
+                    "isEstimate": {
+                      "type": "boolean",
+                      "description": "True when the provider may settle at a different rate than quoted."
+                    },
+                    "canBePartial": {
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "True when the provider may fill only part of the order. Null when it does not say."
+                    },
+                    "maxFulfillmentSeconds": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Longest the provider expects a partial fill to take."
+                    },
+                    "minReceiveAmount": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Least the provider guarantees to deliver, in the destination’s native units."
+                    },
+                    "fromNativeAmount": {
+                      "type": "string",
+                      "description": "Amount leaving the source wallet."
+                    },
+                    "toNativeAmount": {
+                      "type": "string",
+                      "description": "Amount arriving in the destination wallet."
+                    },
+                    "networkFee": {
+                      "anyOf": [
+                        {
+                          "description": "{ nativeAmount: string; tokenId: string"
+                        },
+                        {
+                          "description": "null; }"
+                        }
+                      ],
+                      "description": "On-chain fee for the sending transaction. It is not the provider’s own spread, which is already in the rate."
+                    },
+                    "quoteExpirationDate": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "When the provider stops honouring the rate. Null when it does not expire."
+                    },
+                    "swapInfo": {
+                      "anyOf": [
+                        {
+                          "description": "{ pluginId: string; displayName: string; supportEmail: string; isDex: boolean"
+                        },
+                        {
+                          "description": "null; }"
+                        }
+                      ],
+                      "description": "`EdgeSwapInfo`: how to name the provider and where to send complaints."
+                    },
+                    "request": {
+                      "anyOf": [
+                        {
+                          "description": "{ fromTokenId: string"
+                        },
+                        {
+                          "description": "null; toTokenId: string"
+                        },
+                        {
+                          "description": "null; nativeAmount: string; quoteFor: \"from\""
+                        },
+                        {
+                          "description": "\"to\""
+                        },
+                        {
+                          "description": "\"max\"; fromWalletId: string; toWalletId: string; }"
+                        }
+                      ],
+                      "description": "The `EdgeSwapRequest` this quote answers, echoed back so quotes from different plugins can be compared without tracking what was asked."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "kind",
+                    "expiresAt",
+                    "pluginId",
+                    "isEstimate",
+                    "canBePartial",
+                    "maxFulfillmentSeconds",
+                    "minReceiveAmount",
+                    "fromNativeAmount",
+                    "toNativeAmount",
+                    "networkFee",
+                    "quoteExpirationDate",
+                    "swapInfo",
+                    "request"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/swap-quote/approve/{objectId}": {
+      "post": {
+        "operationId": "approveSwapQuote",
+        "summary": "Execute a quote.",
+        "description": "**Core call:** `EdgeSwapQuote.approve`\n\n**Command line**\n\n```\napprove-swap-quote <objectId>\n```\n\nMoves funds. The handle is released afterwards whether or not the response is read, so record `orderId` from it.",
+        "tags": [
+          "Swap quotes"
+        ],
+        "x-cli": {
+          "command": "approve-swap-quote",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "EdgeSwapQuote.approve",
+        "x-source": "src/cli/engine/routes/swap.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "An ephemeral object handle id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "description": "True once the swap is submitted and the send broadcast."
+                    },
+                    "objectId": {
+                      "type": "string",
+                      "description": "The handle that was consumed."
+                    },
+                    "orderId": {
+                      "description": "The exchange’s order reference, when it gives one."
+                    },
+                    "destinationAddress": {
+                      "description": "Address the funds were sent to, when the exchange reports one."
+                    },
+                    "transaction": {
+                      "description": "The on-chain send to the exchange."
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "objectId",
+                    "orderId",
+                    "destinationAddress",
+                    "transaction"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_SESSION_MISMATCH, OBJECT_IN_USE, INSUFFICIENT_FUNDS, NETWORK_ERROR, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/swap-quote/close/{objectId}": {
+      "post": {
+        "operationId": "closeSwapQuote",
+        "summary": "Discard a quote.",
+        "description": "**Core call:** `EdgeSwapQuote.close`\n\n**Command line**\n\n```\nclose-swap-quote <objectId>\n```\n\nCloses the plugin object without executing, freeing whatever the exchange was holding.",
+        "tags": [
+          "Swap quotes"
+        ],
+        "x-cli": {
+          "command": "close-swap-quote",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "EdgeSwapQuote.close",
+        "x-source": "src/cli/engine/routes/swap.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "An ephemeral object handle id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "Always true; a failure arrives as an error envelope."
+                    },
+                    "objectId": {
+                      "type": "string",
+                      "description": "The handle this call consumed. It is now expired."
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "objectId"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "OBJECT_NOT_FOUND, OBJECT_EXPIRED, OBJECT_KIND_MISMATCH, OBJECT_SESSION_MISMATCH, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/parse-uri": {
+      "post": {
+        "operationId": "parseUri",
+        "summary": "Parse a payment URI or address.",
+        "description": "**Core call:** `wallet.parseUri`\n\n**Command line**\n\n```\nparse-uri --wallet-id=<walletId> --uri=<uri> [--currency-code=<currencyCode>]\n```\n\nWhat the GUI address tile does when you paste or scan something.",
+        "tags": [
+          "URIs"
+        ],
+        "x-cli": {
+          "command": "parse-uri",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.parseUri",
+        "x-source": "src/cli/engine/routes/uri.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "`EdgeParsedUri`: publicAddress, nativeAmount, currencyCode, metadata, paymentProtocolUrl, …",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "uri": {
+                    "type": "string",
+                    "description": "A payment URI or a bare address."
+                  },
+                  "currencyCode": {
+                    "type": "string",
+                    "description": "Disambiguates on chains that carry several assets."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "uri"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/wallet/encode-uri": {
+      "post": {
+        "operationId": "encodeUri",
+        "summary": "Build a payment URI.",
+        "description": "**Core call:** `wallet.encodeUri`\n\n**Command line**\n\n```\nencode-uri --wallet-id=<walletId> --public-address=<publicAddress> [--native-amount=<nativeAmount>] [--label=<label>] [--message=<message>] [--currency-code=<currencyCode>]\n```\n\nFor a receive screen or a QR code.",
+        "tags": [
+          "URIs"
+        ],
+        "x-cli": {
+          "command": "encode-uri",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "wallet.encodeUri",
+        "x-source": "src/cli/engine/routes/uri.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "uri": {
+                      "type": "string",
+                      "description": "The encoded URI, ready for a QR code."
+                    }
+                  },
+                  "required": [
+                    "uri"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, WALLET_NOT_FOUND, AMBIGUOUS_WALLET_ID, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "walletId": {
+                    "type": "string",
+                    "description": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`."
+                  },
+                  "publicAddress": {
+                    "type": "string",
+                    "description": "Where the payment should go."
+                  },
+                  "nativeAmount": {
+                    "type": "string",
+                    "description": "Amount, in the native unit."
+                  },
+                  "label": {
+                    "type": "string",
+                    "description": "BIP21 `label`; becomes `metadata.name` when parsed back."
+                  },
+                  "message": {
+                    "type": "string",
+                    "description": "BIP21 `message`; becomes `metadata.notes`."
+                  },
+                  "currencyCode": {
+                    "type": "string",
+                    "description": "Disambiguates on chains that carry several assets."
+                  }
+                },
+                "required": [
+                  "walletId",
+                  "publicAddress"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/rates/query": {
+      "post": {
+        "operationId": "ratesQuery",
+        "summary": "Batch crypto and fiat rate lookups.",
+        "description": "**Core call:** _none — GUI code (src/util/exchangeRates): getHistoricalCryptoRate and getHistoricalFiatRate._\n\n**Command line**\n\n```\nrates-query [--crypto='<json>'] [--fiat='<json>']\n```\n\nConcurrent lookups share one rates-server queue, so asking for many rates at once costs a single upstream request.",
+        "tags": [
+          "Exchange rates"
+        ],
+        "x-cli": {
+          "command": "rates-query",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "GUI code (src/util/exchangeRates): getHistoricalCryptoRate and getHistoricalFiatRate.",
+        "x-source": "src/cli/engine/routes/rates.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "crypto": {
+                      "type": "array",
+                      "items": {
+                        "anyOf": [
+                          {
+                            "description": "{ pluginId: string; tokenId: string"
+                          },
+                          {
+                            "description": "null; targetFiat: string; date: string; rate: number; }"
+                          }
+                        ]
+                      },
+                      "description": "Always present; empty when no crypto rates were requested."
+                    },
+                    "fiat": {
+                      "type": "array",
+                      "items": {
+                        "description": "{ fiatCode: string; targetFiat: string; date: string; rate: number; }"
+                      },
+                      "description": "Always present; empty when no fiat rates were requested."
+                    }
+                  },
+                  "required": [
+                    "crypto",
+                    "fiat"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "crypto": {
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "description": "{ pluginId: string; tokenId: string"
+                        },
+                        {
+                          "description": "null; targetFiat: string"
+                        },
+                        {
+                          "description": "undefined; date: string"
+                        },
+                        {
+                          "description": "undefined; }"
+                        }
+                      ]
+                    },
+                    "description": "Crypto rates to fetch."
+                  },
+                  "fiat": {
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "description": "{ fiatCode: string; targetFiat: string"
+                        },
+                        {
+                          "description": "undefined; date: string"
+                        },
+                        {
+                          "description": "undefined; }"
+                        }
+                      ]
+                    },
+                    "description": "Fiat rates to fetch."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/rates/usd-to-native": {
+      "post": {
+        "operationId": "ratesUsdToNative",
+        "summary": "Convert a USD amount into native units.",
+        "description": "**Core call:** _none — GUI code (src/util/exchangeRates): getHistoricalCryptoRate._\n\n**Command line**\n\n```\nrates-usd-to-native --usd-amount=<usdAmount> --plugin-id=<pluginId> [--token-id=<tokenId>] --multiplier=<multiplier> [--date=<date>]\n```\n\nTurns a fiat notional into the native amount a spend needs.",
+        "tags": [
+          "Exchange rates"
+        ],
+        "x-cli": {
+          "command": "rates-usd-to-native",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "GUI code (src/util/exchangeRates): getHistoricalCryptoRate.",
+        "x-source": "src/cli/engine/routes/rates.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "usdAmount": {
+                      "type": "number",
+                      "description": "Echoed as a number, though it is sent as a string."
+                    },
+                    "pluginId": {
+                      "type": "string",
+                      "description": "Currency plugin the amount was converted for."
+                    },
+                    "tokenId": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The asset, or null for the chain’s own coin."
+                    },
+                    "multiplier": {
+                      "type": "string",
+                      "description": "Native units per whole coin, which is what `displayAmount` was multiplied by to reach `nativeAmount`."
+                    },
+                    "date": {
+                      "type": "string",
+                      "description": "The timestamp actually used for the rate."
+                    },
+                    "rate": {
+                      "type": "number",
+                      "description": "USD per whole coin at that date."
+                    },
+                    "displayAmount": {
+                      "type": "string",
+                      "description": "Whole coins, to 8 decimal places."
+                    },
+                    "nativeAmount": {
+                      "type": "string",
+                      "description": "What a spend actually takes."
+                    }
+                  },
+                  "required": [
+                    "usdAmount",
+                    "pluginId",
+                    "tokenId",
+                    "multiplier",
+                    "date",
+                    "rate",
+                    "displayAmount",
+                    "nativeAmount"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NOT_FOUND, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "usdAmount": {
+                    "type": "string",
+                    "description": "A positive decimal string."
+                  },
+                  "pluginId": {
+                    "type": "string",
+                    "description": "Which chain to price."
+                  },
+                  "tokenId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Defaults to the native asset."
+                  },
+                  "multiplier": {
+                    "type": "string",
+                    "description": "Native units per whole coin, as a positive decimal string. This route is not session-scoped, so the engine cannot read the asset’s denomination from core and will not guess one."
+                  },
+                  "date": {
+                    "type": "string",
+                    "description": "ISO-8601. Omitted, the current time is sent to the rates server."
+                  }
+                },
+                "required": [
+                  "usdAmount",
+                  "pluginId",
+                  "multiplier"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/list-store-ids": {
+      "get": {
+        "operationId": "listStoreIds",
+        "summary": "List data-store ids.",
+        "description": "**Core call:** `account.dataStore.listStoreIds`\n\n**Command line**\n\n```\nlist-store-ids\n```\n\nThe account's synced key-value store, where plugins keep their own state.",
+        "tags": [
+          "Data store"
+        ],
+        "x-cli": {
+          "command": "list-store-ids",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.dataStore.listStoreIds",
+        "x-source": "src/cli/engine/routes/dataStore.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "storeIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Every store holding at least one item."
+                    }
+                  },
+                  "required": [
+                    "storeIds"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/list-item-ids": {
+      "get": {
+        "operationId": "listItemIds",
+        "summary": "List item ids in a store.",
+        "description": "**Core call:** `account.dataStore.listItemIds`\n\n**Command line**\n\n```\nlist-item-ids --store-id=<storeId>\n```\n\n",
+        "tags": [
+          "Data store"
+        ],
+        "x-cli": {
+          "command": "list-item-ids",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.dataStore.listItemIds",
+        "x-source": "src/cli/engine/routes/dataStore.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "storeId",
+            "in": "query",
+            "required": true,
+            "description": "Plugin or app namespace within the account data store.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "itemIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Keys in this store. Empty if it has none."
+                    }
+                  },
+                  "required": [
+                    "itemIds"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/get-item": {
+      "get": {
+        "operationId": "getItem",
+        "summary": "Read an item.",
+        "description": "**Core call:** `account.dataStore.getItem`\n\n**Command line**\n\n```\nget-item --store-id=<storeId> --item-id=<itemId>\n```\n\nValues are opaque strings; encoding is the caller's business.",
+        "tags": [
+          "Data store"
+        ],
+        "x-cli": {
+          "command": "get-item",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.dataStore.getItem",
+        "x-source": "src/cli/engine/routes/dataStore.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "storeId",
+            "in": "query",
+            "required": true,
+            "description": "Plugin or app namespace within the account data store.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "itemId",
+            "in": "query",
+            "required": true,
+            "description": "Key within the store.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "value": {
+                      "type": "string",
+                      "description": "The stored string."
+                    }
+                  },
+                  "required": [
+                    "value"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "NOT_FOUND, BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/set-item": {
+      "post": {
+        "operationId": "setItem",
+        "summary": "Write an item.",
+        "description": "**Core call:** `account.dataStore.setItem`\n\n**Command line**\n\n```\nset-item --store-id=<storeId> --item-id=<itemId> --value=<value>\n```\n\nCreates the store if it does not exist.",
+        "tags": [
+          "Data store"
+        ],
+        "x-cli": {
+          "command": "set-item",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.dataStore.setItem",
+        "x-source": "src/cli/engine/routes/dataStore.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "storeId": {
+                    "type": "string",
+                    "description": "Plugin or app namespace within the account data store."
+                  },
+                  "itemId": {
+                    "type": "string",
+                    "description": "Key within the store."
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "The string to store."
+                  }
+                },
+                "required": [
+                  "storeId",
+                  "itemId",
+                  "value"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/delete-item": {
+      "post": {
+        "operationId": "deleteItem",
+        "summary": "Delete an item.",
+        "description": "**Core call:** `account.dataStore.deleteItem`\n\n**Command line**\n\n```\ndelete-item --store-id=<storeId> --item-id=<itemId>\n```\n\n",
+        "tags": [
+          "Data store"
+        ],
+        "x-cli": {
+          "command": "delete-item",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.dataStore.deleteItem",
+        "x-source": "src/cli/engine/routes/dataStore.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "storeId": {
+                    "type": "string",
+                    "description": "Plugin or app namespace within the account data store."
+                  },
+                  "itemId": {
+                    "type": "string",
+                    "description": "Key within the store."
+                  }
+                },
+                "required": [
+                  "storeId",
+                  "itemId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/account/{sessionId}/delete-store": {
+      "post": {
+        "operationId": "deleteStore",
+        "summary": "Delete an entire store.",
+        "description": "**Core call:** `account.dataStore.deleteStore`\n\n**Command line**\n\n```\ndelete-store --store-id=<storeId>\n```\n\nRemoves every item in it, which cannot be undone from this API.",
+        "tags": [
+          "Data store"
+        ],
+        "x-cli": {
+          "command": "delete-store",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "account.dataStore.deleteStore",
+        "x-source": "src/cli/engine/routes/dataStore.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "description": "From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, INVALID_SESSION, SESSION_EXPIRED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "storeId": {
+                    "type": "string",
+                    "description": "Plugin or app namespace within the account data store."
+                  }
+                },
+                "required": [
+                  "storeId"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/auth-request": {
+      "post": {
+        "operationId": "adminAuthRequest",
+        "summary": "Raw login-server request.",
+        "description": "**Core call:** `context.$internalStuff.authRequest`\n\n**Command line**\n\n```\nadmin-auth-request --method=<method> --path=<path> [--body='<json>']\n```\n\nSends an arbitrary request with the context's credentials attached. Debugging only — this is core's private surface.",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-auth-request",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.authRequest",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Whatever the login server returned.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "method": {
+                    "type": "string",
+                    "description": "HTTP method, e.g. `GET`."
+                  },
+                  "path": {
+                    "type": "string",
+                    "description": "Login-server path, not an engine path."
+                  },
+                  "body": {
+                    "description": "Request body, when the method takes one."
+                  }
+                },
+                "required": [
+                  "method",
+                  "path"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/hash-username": {
+      "get": {
+        "operationId": "adminHashUsername",
+        "summary": "Hash a username.",
+        "description": "**Core call:** `context.$internalStuff.hashUsername`\n\n**Command line**\n\n```\nadmin-hash-username --username=<username>\n```\n\nReproduces the login server's hashing, to derive a login id offline.",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-hash-username",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.hashUsername",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "username",
+            "in": "query",
+            "required": true,
+            "description": "The name to hash.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "loginId": {
+                      "type": "string",
+                      "description": "Base58."
+                    }
+                  },
+                  "required": [
+                    "loginId"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/make-lobby": {
+      "post": {
+        "operationId": "adminMakeLobby",
+        "summary": "Create a lobby.",
+        "description": "**Core call:** `context.$internalStuff.makeLobby`\n\n**Command line**\n\n```\nadmin-make-lobby [--lobby-request='<json>'] [--period-seconds=<period>]\n```\n\nA lobby polls the login server until closed, so the engine parks it under a `lobby_` handle and closes it on expiry rather than leaking the poll.",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-make-lobby",
+          "flags": [
+            {
+              "name": "period-seconds",
+              "maps": "period",
+              "repeat": false
+            }
+          ],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.makeLobby",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "objectId": {
+                      "type": "string",
+                      "description": "The parked handle."
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "description": "When the engine closes the lobby and stops polling."
+                    },
+                    "lobbyId": {
+                      "type": "string",
+                      "description": "Identifies the lobby to the party joining it."
+                    },
+                    "replies": {
+                      "type": "array",
+                      "items": {},
+                      "description": "Empty at creation; re-read to see replies."
+                    }
+                  },
+                  "required": [
+                    "objectId",
+                    "expiresAt",
+                    "lobbyId",
+                    "replies"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "lobbyRequest": {
+                    "description": "Defaults to `{}`."
+                  },
+                  "period": {
+                    "type": "number",
+                    "description": "Poll interval in seconds. At least 0.25; the engine converts to the milliseconds core takes."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/lobby-handle/delete/{objectId}": {
+      "post": {
+        "operationId": "adminDeleteLobbyHandle",
+        "summary": "Close a parked lobby.",
+        "description": "**Core call:** _none — Engine handle store for a lobby created via makeLobby._\n\n**Command line**\n\n```\nadmin-lobby-handle-delete <objectId>\n```\n\n",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-lobby-handle-delete",
+          "positional": "objectId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine handle store for a lobby created via makeLobby.",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "objectId",
+            "in": "path",
+            "required": true,
+            "description": "An ephemeral object handle id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "description": "Always true; a failure arrives as an error envelope."
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "OBJECT_NOT_FOUND, OBJECT_KIND_MISMATCH, OBJECT_IN_USE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/fetch-lobby-request/{lobbyId}": {
+      "get": {
+        "operationId": "adminFetchLobbyRequest",
+        "summary": "Read a lobby's contents.",
+        "description": "**Core call:** `context.$internalStuff.fetchLobbyRequest`\n\n**Command line**\n\n```\nadmin-fetch-lobby-request <lobbyId>\n```\n\n",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-fetch-lobby-request",
+          "positional": "lobbyId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.fetchLobbyRequest",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "lobbyId",
+            "in": "path",
+            "required": true,
+            "description": "Which lobby to read.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The raw lobby request.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/send-lobby-reply/{lobbyId}": {
+      "post": {
+        "operationId": "adminSendLobbyReply",
+        "summary": "Reply to a lobby.",
+        "description": "**Core call:** `context.$internalStuff.sendLobbyReply`\n\n**Command line**\n\n```\nadmin-send-lobby-reply <lobbyId> --lobby-request='<json>' [--reply-data='<json>']\n```\n\n",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-send-lobby-reply",
+          "positional": "lobbyId",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.sendLobbyReply",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "lobbyId",
+            "in": "path",
+            "required": true,
+            "description": "Which lobby to answer.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "lobbyRequest": {
+                    "description": "Normally the object from `admin-fetch-lobby-request`."
+                  },
+                  "replyData": {
+                    "description": "Payload for the requester."
+                  }
+                },
+                "required": [
+                  "lobbyRequest"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/sync-repo/{syncKey}": {
+      "post": {
+        "operationId": "adminSyncRepo",
+        "summary": "Sync a repo.",
+        "description": "**Core call:** `context.$internalStuff.syncRepo`\n\n**Command line**\n\n```\nadmin-sync-repo <syncKey>\n```\n\n",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-sync-repo",
+          "positional": "syncKey",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.syncRepo",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "syncKey",
+            "in": "path",
+            "required": true,
+            "description": "Base58 repo sync key.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The changeset summary.",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST, NETWORK_ERROR",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/repo-list/{syncKey}": {
+      "get": {
+        "operationId": "adminRepoList",
+        "summary": "List repo contents.",
+        "description": "**Core call:** `context.$internalStuff.getRepoDisklet`\n\n**Command line**\n\n```\nadmin-repo-list <syncKey> [--path=<path>] --data-key=<dataKey>\n```\n\n",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-repo-list",
+          "positional": "syncKey",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.getRepoDisklet",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "syncKey",
+            "in": "path",
+            "required": true,
+            "description": "Base58 repo sync key.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "path",
+            "in": "query",
+            "required": false,
+            "description": "Subdirectory. Defaults to the repo root.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "dataKey",
+            "in": "query",
+            "required": true,
+            "description": "Base58 repo data key.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "listing": {
+                      "description": "Path to entry type: `file` or `folder`."
+                    }
+                  },
+                  "required": [
+                    "listing"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "BAD_REQUEST",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/repo-get/{syncKey}": {
+      "get": {
+        "operationId": "adminRepoGet",
+        "summary": "Read a repo file.",
+        "description": "**Core call:** `context.$internalStuff.getRepoDisklet`\n\n**Command line**\n\n```\nadmin-repo-get <syncKey> --path=<path> --data-key=<dataKey>\n```\n\n",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-repo-get",
+          "positional": "syncKey",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.getRepoDisklet",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "syncKey",
+            "in": "path",
+            "required": true,
+            "description": "Base58 repo sync key.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "path",
+            "in": "query",
+            "required": true,
+            "description": "Path within the repo.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "dataKey",
+            "in": "query",
+            "required": true,
+            "description": "Base58 repo data key.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "text": {
+                      "type": "string",
+                      "description": "The file contents."
+                    }
+                  },
+                  "required": [
+                    "text"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "NOT_FOUND, BAD_REQUEST",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/repo-set/{syncKey}": {
+      "post": {
+        "operationId": "adminRepoSet",
+        "summary": "Write a repo file.",
+        "description": "**Core call:** `context.$internalStuff.getRepoDisklet`\n\n**Command line**\n\n```\nadmin-repo-set <syncKey> --path=<path> --text=<text> --data-key=<dataKey>\n```\n\nWrites directly into a synced repo, bypassing every core-level invariant. A malformed write can break the account for real clients.",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-repo-set",
+          "positional": "syncKey",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.getRepoDisklet",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "syncKey",
+            "in": "path",
+            "required": true,
+            "description": "Base58 repo sync key.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "description": "Path within the repo."
+                  },
+                  "text": {
+                    "type": "string",
+                    "description": "The contents to write."
+                  },
+                  "dataKey": {
+                    "type": "string",
+                    "description": "Base58 repo data key."
+                  }
+                },
+                "required": [
+                  "path",
+                  "text",
+                  "dataKey"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/admin/repo-delete/{syncKey}": {
+      "post": {
+        "operationId": "adminRepoDelete",
+        "summary": "Delete a repo file.",
+        "description": "**Core call:** `context.$internalStuff.getRepoDisklet`\n\n**Command line**\n\n```\nadmin-repo-delete <syncKey> --path=<path> --data-key=<dataKey>\n```\n\nDestructive, and not undoable from this API.",
+        "tags": [
+          "Admin"
+        ],
+        "x-cli": {
+          "command": "admin-repo-delete",
+          "positional": "syncKey",
+          "flags": [],
+          "extra": [],
+          "custom": false,
+          "preset": {}
+        },
+        "x-core-call": "context.$internalStuff.getRepoDisklet",
+        "x-source": "src/cli/engine/routes/admin.ts",
+        "parameters": [
+          {
+            "name": "syncKey",
+            "in": "path",
+            "required": true,
+            "description": "Base58 repo sync key.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content."
+          },
+          "default": {
+            "description": "BAD_REQUEST",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "description": "Path within the repo."
+                  },
+                  "dataKey": {
+                    "type": "string",
+                    "description": "Base58 repo data key."
+                  }
+                },
+                "required": [
+                  "path",
+                  "dataKey"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/engine/events": {
+      "get": {
+        "operationId": "engineEvents",
+        "summary": "Subscribe to engine events.",
+        "description": "**Core call:** _none — Engine-side fan-out; `core.log` frames carry core's onLog output._\n\n**Command line**\n\n```\nsubscribe [--session-id=<sessionId>] [--wallet-id=<walletId>] [--type=<value>]\n```\n\nHolds a Server-Sent Events stream open until the caller disconnects or the engine closes it. Runs concurrently with one-shot calls, so a subscriber in one terminal watches what another terminal does.\n\nA live subscription holds the engine open past its idle timeout. It does not hold an account logged in: the auto-logout timer still fires, and closes any subscription scoped to that account or one of its wallets. Context-scoped subscriptions survive, because the context outlives every account.\n\nScope comes from the query string. With no `sessionId` the stream is context-scoped and nothing but the engine stopping ends it, which is what the `subscribe` command asks for. With `sessionId` it is account-scoped: a logout closes it, and the session events of *other* accounts are filtered out. `walletId` narrows it further, for whenever a wallet-scoped event exists — no event carries a wallet scope today, so on its own it changes only which events close the stream.",
+        "tags": [
+          "Event stream"
+        ],
+        "x-cli": {
+          "command": "subscribe",
+          "flags": [],
+          "extra": [
+            {
+              "name": "type",
+              "kind": "repeat",
+              "required": false,
+              "doc": "Only these event types. Applied by the engine, so an unwanted type never crosses the socket; the client filters again for the types the engine sends regardless, like `subscription.closed`."
+            }
+          ],
+          "custom": true,
+          "preset": {},
+          "notes": "Prints newline-delimited JSON and runs until interrupted. Exits 0 on SIGINT and 7 when the engine ends the stream. `subscribe` opens an unscoped stream, which only the engine stopping ends; a stream opened with `sessionId` is closed by that session logging out."
+        },
+        "x-core-call": null,
+        "x-core-note": "Engine-side fan-out; `core.log` frames carry core's onLog output.",
+        "x-source": "src/cli/engine/routes/events.ts",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "query",
+            "required": false,
+            "description": "Scope the stream to one account, so a logout closes it. Omitted, the stream is context-scoped and only the engine stopping ends it.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "walletId",
+            "in": "query",
+            "required": false,
+            "description": "With `sessionId`, narrow the stream to one wallet. No event carries a wallet scope yet, so today this only narrows which events can close the stream. Ignored on its own.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "One frame per event, as `event:` then `data:` lines.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "description": "The event name."
+                    },
+                    "data": {
+                      "description": "Payload, shaped by the event type."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "data"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "edgeTcpToken": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-Edge-Token",
+        "description": "The bearer token the engine mints for its loopback TCP listener, written to the `0600` run file at ~/.edge-cli/run/<profile>/engine.json as `tcpToken`. Required on the TCP transport and ignored on the unix socket. A TCP request that also carries `Origin`, or a `Host` other than the bound address, is refused with 403 whatever token it presents."
+      }
+    },
+    "schemas": {
+      "ErrorEnvelope": {
+        "type": "object",
+        "description": "Every failure, on both transports.",
+        "properties": {
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "status": {
+                "type": "number"
+              },
+              "details": {}
+            },
+            "required": [
+              "code",
+              "message",
+              "status"
+            ]
+          }
+        },
+        "required": [
+          "error"
+        ]
+      }
+    }
+  }
+}
diff --git a/docs/api/groups.ts b/docs/api/groups.ts
new file mode 100644
index 00000000000..84228befe8a
--- /dev/null
+++ b/docs/api/groups.ts
@@ -0,0 +1,217 @@
+import { SESSION_ERRORS } from '../../src/cli/engine/errorGroups'
+
+/**
+ * Section titles and order for the generated reference.
+ *
+ * Keyed by route-file basename, which is also the group each `route()` in that
+ * file belongs to. Everything else about an endpoint comes from its
+ * declaration in `src/cli/engine/routes/`.
+ */
+export interface GroupInfo {
+  id: string
+  title: string
+  doc: string
+  /** Section this group sits under, from `sectionOrder`. */
+  section: string
+}
+
+/**
+ * The top level of the reference: the core object a call acts on.
+ *
+ * `EdgeContext`, `EdgeAccount` and `EdgeCurrencyWallet` are the three objects
+ * the API is built on, so they are the three main sections; the engine daemon
+ * is its own, having no core object at all. Everything else that does not
+ * belong to one of them stands alone rather than being filed under a section
+ * it only half fits.
+ */
+export interface SectionInfo {
+  id: string
+  title: string
+  doc: string
+}
+
+/**
+ * The session errors every account-scoped route can return, from the list the
+ * routes themselves import. Written out here, two copies of the sentence had
+ * to be kept in step with the list by hand.
+ */
+function sessionErrorList(): string {
+  return SESSION_ERRORS.map(code => `\`401 ${code}\``).join(' or ')
+}
+
+export const sectionOrder: SectionInfo[] = [
+  {
+    id: 'engine',
+    title: 'Engine',
+    doc: 'The `edge-engine` daemon itself. None of these have an `edge-core-js` equivalent — they describe the process — and none need a session.'
+  },
+  {
+    id: 'context',
+    title: 'Context',
+    doc: 'Calls on the shared `EdgeContext`: device state, username queries, and every way of logging in. None of them need a session, because a session is what they produce.'
+  },
+  {
+    id: 'account',
+    title: 'Account',
+    doc: `Calls on a logged-in \`EdgeAccount\`, addressed by \`sessionId\`. All of these can also return ${sessionErrorList()}.`
+  },
+  {
+    id: 'wallet',
+    title: 'Wallet',
+    doc: 'Calls on a single `EdgeCurrencyWallet`. Each names its wallet with `--wallet-id`, which accepts a full id or any unique prefix.'
+  },
+  {
+    id: 'local-settings',
+    title: 'Local settings',
+    doc: 'Device-local account settings, stored outside the synced repos. They follow the account but never leave the machine.'
+  },
+  {
+    id: 'swap',
+    title: 'Swap',
+    doc: 'Exchanging one asset for another through the swap plugins.'
+  },
+  {
+    id: 'rates',
+    title: 'Exchange rates',
+    doc: 'Fiat and crypto pricing, current and historical.'
+  },
+  {
+    id: 'objects',
+    title: 'Object handles',
+    doc: 'A core value with methods on it cannot cross JSON, so the engine keeps it and hands back an id. These read and release any of them.'
+  },
+  {
+    id: 'admin',
+    title: 'Admin',
+    doc: 'The `$internalStuff` escape hatch: login-server and sync-repo access that no ordinary caller needs.'
+  }
+]
+
+export const groupOrder: GroupInfo[] = [
+  {
+    id: 'status',
+    title: 'Lifecycle',
+    section: 'engine',
+    doc: 'Lifecycle and configuration of the `edge-engine` daemon. None of these have an `edge-core-js` equivalent — they describe the daemon itself — and none need a session.'
+  },
+  {
+    id: 'context',
+    title: 'Device and usernames',
+    section: 'context',
+    doc: 'Calls on the shared `EdgeContext`: local device state and login-server queries that do not need a session.'
+  },
+  {
+    id: 'login',
+    title: 'Login methods',
+    section: 'context',
+    doc: 'Every successful login returns a [Session](#schema-Session) and registers it in the engine, so later calls need only the `sessionId`. The CLI writes that id to `session.json` automatically.'
+  },
+  {
+    id: 'account',
+    title: 'Session',
+    section: 'account',
+    doc: `Calls on a logged-in \`EdgeAccount\`, addressed by \`sessionId\`. All of these can also return ${sessionErrorList()}.`
+  },
+  {
+    id: 'localSettings',
+    title: 'Local settings',
+    section: 'local-settings',
+    doc: 'Device-local account settings, stored outside the synced repos.'
+  },
+  {
+    id: 'credentials',
+    title: 'Credentials',
+    section: 'account',
+    doc: 'Password, PIN, username and recovery changes on a logged-in account.'
+  },
+  {
+    id: 'otp',
+    title: 'Two-factor authentication',
+    section: 'account',
+    doc: 'OTP state and the reset flow a user falls back on after losing their authenticator.'
+  },
+  {
+    id: 'vouchers',
+    title: 'Vouchers',
+    section: 'account',
+    doc: 'When 2FA blocks a login, the login server issues a voucher an already-trusted device can approve or reject.'
+  },
+  {
+    id: 'lobby',
+    title: 'Approving a login',
+    section: 'account',
+    doc: 'The other side of `request-edge-login`: a logged-in account inspecting and approving a login somebody scanned.'
+  },
+  {
+    id: 'keys',
+    title: 'Keys',
+    section: 'account',
+    doc: 'Raw key infrastructure beneath the wallet API. Several of these return private key material, and the engine has no transport auth — treat any process that can reach the socket as fully trusted.'
+  },
+  {
+    id: 'wallets',
+    title: 'Wallet state',
+    section: 'wallet',
+    doc: 'Account-level wallet listing and creation, then per-wallet calls. A `{walletId}` segment accepts a unique prefix, so those routes can also return `404 WALLET_NOT_FOUND` or `409 AMBIGUOUS_WALLET_ID`.'
+  },
+  {
+    id: 'tokens',
+    title: 'Tokens',
+    section: 'wallet',
+    doc: 'Which tokens a wallet tracks. Enabled tokens are the ones it syncs balances for; detected ones were seen on-chain but are not yet enabled.'
+  },
+  {
+    id: 'transactions',
+    title: 'Transactions',
+    section: 'wallet',
+    doc: 'Reading transaction history, exporting it, and editing its metadata.'
+  },
+  {
+    id: 'objects',
+    title: 'Object handles',
+    section: 'objects',
+    doc: 'A core value with methods on it — a staged transaction, a swap quote, a pending login — cannot cross JSON, so the engine keeps it and hands back an id. These read and release any of them.'
+  },
+  {
+    id: 'spend',
+    title: 'Spending',
+    section: 'wallet',
+    doc: 'Two ways to send funds. `spend` does the whole thing in one call; the staged workflow — `make-spend`, `sign-tx`, `broadcast-tx`, `save-tx` — hands back an object handle at each step so fees can be inspected before committing.'
+  },
+  {
+    id: 'swap',
+    title: 'Swap quotes',
+    section: 'account',
+    doc: 'Cross-asset exchange. Quotes are live objects held server-side under a `swap_` handle, so approving one means naming its `objectId` rather than re-uploading the quote.'
+  },
+  {
+    id: 'uri',
+    title: 'URIs',
+    section: 'wallet',
+    doc: 'Parsing and building BIP21-style payment URIs through the wallet’s own plugin, so chain-specific quirks are handled for you.'
+  },
+  {
+    id: 'rates',
+    title: 'Exchange rates',
+    section: 'rates',
+    doc: 'Historical and current rates through the same batching queue the GUI uses. No session required.'
+  },
+  {
+    id: 'dataStore',
+    title: 'Data store',
+    section: 'account',
+    doc: 'The account’s synced key-value store, where plugins keep their own state. One route per `EdgeDataStore` method.'
+  },
+  {
+    id: 'admin',
+    title: 'Admin',
+    section: 'admin',
+    doc: '**Debugging only — not for production apps.** These reach into `context.$internalStuff`, the private surface of `edge-core-js`, and can corrupt an account’s synced repos. They take no `sessionId`: they act on the context, not on a logged-in account.'
+  },
+  {
+    id: 'events',
+    title: 'Event stream',
+    section: 'engine',
+    doc: 'A Server-Sent Events feed of engine activity, served outside the router because the response never ends.'
+  }
+]
diff --git a/docs/api/shared.ts b/docs/api/shared.ts
new file mode 100644
index 00000000000..3d3d531ebad
--- /dev/null
+++ b/docs/api/shared.ts
@@ -0,0 +1,365 @@
+import { errorCodesFor, EXIT } from '../../src/cli/client/exitCodes'
+
+/**
+ * The error catalogue and the CLI exit-code table.
+ *
+ * Response shapes used to live here too; they are now cleaners in
+ * `src/cli/engine/schemas.ts`, where they both validate and describe.
+ */
+
+export interface ErrorCode {
+  code: string
+  status: number
+  origin: 'engine' | 'core' | 'client'
+  doc: string
+  details?: string
+}
+
+/**
+ * Every code the CLI can emit. Engine codes are thrown by `engineError`;
+ * core codes are mapped from `edge-core-js` error types by `mapCoreError`;
+ * client codes are written by `src/cli/client/output.ts` and never cross the
+ * wire, but a script matching on `error.code` sees them all the same, so
+ * leaving them out published a program whose failures the catalogue could
+ * not describe.
+ */
+export const errorCodes: ErrorCode[] = [
+  {
+    code: 'BAD_REQUEST',
+    status: 400,
+    origin: 'engine',
+    doc: 'Malformed JSON, or a missing / wrongly typed field.'
+  },
+  {
+    code: 'MISSING_BITWAVE_ACCOUNT_ID',
+    status: 400,
+    origin: 'engine',
+    doc: 'Bitwave export requested with no account id in the query and none saved in the wallet’s `exportTxInfo.json`.'
+  },
+  {
+    code: 'OBJECT_KIND_MISMATCH',
+    status: 400,
+    origin: 'engine',
+    doc: 'The handle exists but is a different kind (e.g. a swap quote passed to `sign-tx`).'
+  },
+  {
+    code: 'OBJECT_SESSION_MISMATCH',
+    status: 400,
+    origin: 'engine',
+    doc: 'The handle belongs to a different session.'
+  },
+  {
+    code: 'OBJECT_WALLET_MISMATCH',
+    status: 400,
+    origin: 'engine',
+    doc: 'The transaction handle belongs to a different wallet.'
+  },
+  {
+    code: 'INVALID_SESSION',
+    status: 401,
+    origin: 'engine',
+    doc: 'Unknown `sessionId`.'
+  },
+  {
+    code: 'SESSION_EXPIRED',
+    status: 401,
+    origin: 'engine',
+    doc: 'Auto-logged-out after the account\u2019s idle timeout. An explicitly logged-out session is gone rather than expired, and answers `INVALID_SESSION`.'
+  },
+  {
+    code: 'NOT_FOUND',
+    status: 404,
+    origin: 'engine',
+    doc: 'No route matched, or a generic missing resource.'
+  },
+  {
+    code: 'NO_LOGIN_REQUEST',
+    status: 404,
+    origin: 'engine',
+    doc: 'The lobby exists but carries no pending login request.'
+  },
+  {
+    code: 'OBJECT_NOT_FOUND',
+    status: 404,
+    origin: 'engine',
+    doc: 'No handle with that `objectId`.'
+  },
+  {
+    code: 'PENDING_LOGIN_NOT_FOUND',
+    status: 404,
+    origin: 'engine',
+    doc: 'No pending Edge login with that `pendingId`.'
+  },
+  {
+    code: 'TOKEN_NOT_FOUND',
+    status: 404,
+    origin: 'engine',
+    doc: 'Unknown token id for this wallet.'
+  },
+  {
+    code: 'UNAUTHORIZED',
+    status: 401,
+    origin: 'engine',
+    doc: 'The TCP transport requires the bearer token from the engine run file in an `X-Edge-Token` header. The unix socket needs none: its `0600` mode is the check.'
+  },
+  {
+    code: 'FORBIDDEN',
+    status: 403,
+    origin: 'engine',
+    doc: 'A TCP request carried an `Origin` header, or a `Host` that is not the address the listener is bound to. Both are refused so a web page cannot reach the engine, directly or by rebinding a name onto its port.'
+  },
+  {
+    code: 'USER_NOT_FOUND',
+    status: 404,
+    origin: 'engine',
+    doc: 'No local user matches that username or login id.'
+  },
+  {
+    code: 'WALLET_NOT_FOUND',
+    status: 404,
+    origin: 'engine',
+    doc: 'No wallet matches that id or prefix.'
+  },
+  {
+    code: 'ENGINE_UNAVAILABLE',
+    status: 503,
+    origin: 'client',
+    doc: 'The client could not reach or start an engine. Written by the client, so it never arrives over the wire; exit code 7.'
+  },
+  {
+    code: 'USAGE',
+    status: 400,
+    origin: 'client',
+    doc: 'Bad argv: an unknown command or flag, a missing flag value, or an unparseable structured flag. Written by the client; exit code 2.'
+  },
+  {
+    code: 'METHOD_NOT_ALLOWED',
+    status: 405,
+    origin: 'engine',
+    doc: 'The path exists but not for this HTTP method.'
+  },
+  {
+    code: 'AMBIGUOUS_WALLET_ID',
+    status: 409,
+    origin: 'engine',
+    doc: 'A wallet id prefix matched more than one wallet.',
+    details: '`details.candidates`'
+  },
+  {
+    code: 'OBJECT_EXPIRED',
+    status: 410,
+    origin: 'engine',
+    doc: 'The handle was read after its TTL but before the 15-second sweeper released it. Once swept it is gone, so a handle past its TTL usually answers `OBJECT_NOT_FOUND` instead.'
+  },
+  {
+    code: 'OBJECT_IN_USE',
+    status: 409,
+    origin: 'engine',
+    doc: 'A consuming call on this handle is already in flight. Fund-moving calls outlive the client socket timeout, so a retry is refused rather than sending twice.'
+  },
+  {
+    code: 'PAYLOAD_TOO_LARGE',
+    status: 413,
+    origin: 'engine',
+    doc: 'Request body over 4 MiB.'
+  },
+  {
+    code: 'UNSUPPORTED_MEDIA_TYPE',
+    status: 415,
+    origin: 'engine',
+    doc: 'Body present but not `application/json`.'
+  },
+  {
+    code: 'INTERNAL_ERROR',
+    status: 500,
+    origin: 'engine',
+    doc: 'Unmapped engine or plugin failure.'
+  },
+  {
+    code: 'ENGINE_SHUTTING_DOWN',
+    status: 503,
+    origin: 'engine',
+    doc: 'Idle or explicit shutdown already in progress.'
+  },
+
+  {
+    code: 'USERNAME_ERROR',
+    status: 400,
+    origin: 'core',
+    doc: 'Unknown username, or an invalid recovery key.'
+  },
+  {
+    code: 'NO_AMOUNT_SPECIFIED',
+    status: 400,
+    origin: 'core',
+    doc: 'Zero-amount spend.'
+  },
+  {
+    code: 'SAME_CURRENCY',
+    status: 400,
+    origin: 'core',
+    doc: 'Swap between identical currencies.'
+  },
+  {
+    code: 'PASSWORD_ERROR',
+    status: 401,
+    origin: 'core',
+    doc: 'Wrong password, PIN, or recovery answers.',
+    details: '`details.wait` (seconds) when rate-limited'
+  },
+  {
+    code: 'OTP_REQUIRED',
+    status: 401,
+    origin: 'core',
+    doc: 'Missing or wrong 2FA token.',
+    details:
+      '`reason` (`ip`\\|`otp`), `loginId`, `resetToken`, `resetDate`, `voucherId`, `voucherAuth`, `voucherActivates`'
+  },
+  {
+    code: 'CHALLENGE_REQUIRED',
+    status: 403,
+    origin: 'core',
+    doc: 'The login server wants a CAPTCHA. Retry with `challengeId`.',
+    details: '`challengeId`, `challengeUri`'
+  },
+  {
+    code: 'PIN_DISABLED',
+    status: 403,
+    origin: 'core',
+    doc: 'PIN login is not enabled on this device.'
+  },
+  {
+    code: 'SWAP_PERMISSION',
+    status: 403,
+    origin: 'core',
+    doc: 'The swap plugin refused the request.',
+    details:
+      '`pluginId`, `reason`: `geoRestriction` \\| `noVerification` \\| `needsActivation`'
+  },
+  {
+    code: 'INSUFFICIENT_FUNDS',
+    status: 422,
+    origin: 'core',
+    doc: 'Not enough balance to cover amount plus fee.',
+    details: '`tokenId`, `networkFee`'
+  },
+  {
+    code: 'DUST_SPEND',
+    status: 422,
+    origin: 'core',
+    doc: 'Amount below the network dust threshold.'
+  },
+  {
+    code: 'PENDING_FUNDS',
+    status: 422,
+    origin: 'core',
+    doc: 'Balance exists but is unconfirmed.'
+  },
+  {
+    code: 'SPEND_TO_SELF',
+    status: 422,
+    origin: 'core',
+    doc: 'Destination address belongs to the source wallet.'
+  },
+  {
+    code: 'SWAP_ABOVE_LIMIT',
+    status: 422,
+    origin: 'core',
+    doc: 'Amount exceeds the plugin maximum.',
+    details: '`swapPluginId`, `nativeMax`, `direction`'
+  },
+  {
+    code: 'SWAP_BELOW_LIMIT',
+    status: 422,
+    origin: 'core',
+    doc: 'Amount below the plugin minimum.',
+    details:
+      '`swapPluginId`, `nativeMin`, `direction`. `nativeMin` is an empty string when the plugin refused the amount without reporting a limit — core defaults it, and the engine passes it through rather than inventing one.'
+  },
+  {
+    code: 'SWAP_CURRENCY',
+    status: 422,
+    origin: 'core',
+    doc: 'The plugin does not support that pair.',
+    details: '`pluginId`, `fromTokenId`, `toTokenId`'
+  },
+  {
+    code: 'SWAP_ADDRESS',
+    status: 422,
+    origin: 'core',
+    doc: 'Address unusable for this swap.',
+    details: '`swapPluginId`, `reason`: `mustMatch` \\| `mustBeActivated`'
+  },
+  {
+    code: 'OBSOLETE_API',
+    status: 426,
+    origin: 'core',
+    doc: 'The login server rejected this client version.'
+  },
+  {
+    code: 'NETWORK_ERROR',
+    status: 503,
+    origin: 'core',
+    doc: 'Could not reach an Edge server.'
+  }
+]
+
+// Re-exported from the runtime module the routes import, so the reference and
+// the declarations cannot disagree about what is in each group.
+export {
+  HANDLE_ERRORS,
+  SESSION_ERRORS,
+  WALLET_ERRORS
+} from '../../src/cli/engine/errorGroups'
+
+/** The error codes that map to one exit code, as the reference renders them. */
+function codeList(exitCode: number): string {
+  return errorCodesFor(exitCode)
+    .map(code => `\`${code}\``)
+    .join(', ')
+}
+
+/**
+ * The published exit-code table.
+ *
+ * The membership of codes 3 to 6 comes from `EXIT_CODE_BY_ERROR`, the same
+ * table `output.ts` chooses the code from, so the reference cannot drift from
+ * the implementation. Only the prose that is *not* a membership list is
+ * written here.
+ */
+export const CLI_EXIT_CODES = [
+  { code: EXIT.OK, name: 'OK', doc: 'Success.' },
+  {
+    code: EXIT.GENERIC,
+    name: 'GENERIC',
+    doc: 'Any failure with no more specific mapping.'
+  },
+  {
+    code: EXIT.USAGE,
+    name: 'USAGE',
+    doc: 'Bad argv: unknown flag, missing value, extra positional.'
+  },
+  { code: EXIT.AUTH, name: 'AUTH', doc: `${codeList(EXIT.AUTH)}.` },
+  {
+    code: EXIT.NOT_FOUND,
+    name: 'NOT_FOUND',
+    doc: `${codeList(EXIT.NOT_FOUND)}.`
+  },
+  {
+    code: EXIT.VALIDATION,
+    name: 'VALIDATION',
+    doc: `${codeList(EXIT.VALIDATION)}.`
+  },
+  {
+    code: EXIT.NETWORK,
+    name: 'NETWORK',
+    doc: `${codeList(EXIT.NETWORK)}, or any response with HTTP status \`503\`.`
+  },
+  {
+    code: EXIT.ENGINE,
+    name: 'ENGINE',
+    doc: `${codeList(
+      EXIT.ENGINE
+    )}, or the client could not connect to or spawn the engine.`
+  }
+]
diff --git a/native/edge-api-signer/node/binding.gyp b/native/edge-api-signer/node/binding.gyp
new file mode 100644
index 00000000000..1b6040dbf75
--- /dev/null
+++ b/native/edge-api-signer/node/binding.gyp
@@ -0,0 +1,18 @@
+{
+  "targets": [
+    {
+      "target_name": "edge_api_signer",
+      "sources": [
+        "edge_api_signer_napi.c",
+        "edge_api_secret.c",
+        "../edge_hmac.c"
+      ],
+      "include_dirs": ["..", "."],
+      "cflags": ["-Wall", "-Wextra", "-Wno-unused-parameter"],
+      "xcode_settings": {
+        "OTHER_CFLAGS": ["-Wall", "-Wextra", "-Wno-unused-parameter"],
+        "MACOSX_DEPLOYMENT_TARGET": "11.0"
+      }
+    }
+  ]
+}
diff --git a/native/edge-api-signer/node/edge_api_signer_napi.c b/native/edge-api-signer/node/edge_api_signer_napi.c
new file mode 100644
index 00000000000..31821b9fb29
--- /dev/null
+++ b/native/edge-api-signer/node/edge_api_signer_napi.c
@@ -0,0 +1,176 @@
+/**
+ * Node N-API bindings for the shared Edge API HMAC C core.
+ *
+ * The runtime pad comes from the generated edge_api_secret.h rather than a
+ * literal here, so it is always the id scripts/makeApiSigner.ts baked into the
+ * shards. A stale or hand-edited header fails the build instead of silently
+ * producing signatures the login server rejects.
+ */
+
+#include <node_api.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "edge_api_secret.h"
+#include "edge_api_sign.h"
+
+#ifndef EDGE_NODE_BUNDLE_ID
+#error "EDGE_NODE_BUNDLE_ID missing - regenerate with scripts/makeApiSigner.ts"
+#endif
+
+static const char kBase64Table[] =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+static char *edge_base64_encode(const uint8_t *data, size_t len) {
+  size_t out_len = 4 * ((len + 2) / 3);
+  char *out = (char *)malloc(out_len + 1);
+  size_t i;
+  size_t j = 0;
+  if (out == NULL) return NULL;
+
+  for (i = 0; i + 2 < len; i += 3) {
+    uint32_t n = ((uint32_t)data[i] << 16) | ((uint32_t)data[i + 1] << 8) |
+                 (uint32_t)data[i + 2];
+    out[j++] = kBase64Table[(n >> 18) & 63];
+    out[j++] = kBase64Table[(n >> 12) & 63];
+    out[j++] = kBase64Table[(n >> 6) & 63];
+    out[j++] = kBase64Table[n & 63];
+  }
+  if (i < len) {
+    uint32_t n = ((uint32_t)data[i] << 16);
+    out[j++] = kBase64Table[(n >> 18) & 63];
+    if (i + 1 < len) {
+      n |= ((uint32_t)data[i + 1] << 8);
+      out[j++] = kBase64Table[(n >> 12) & 63];
+      out[j++] = kBase64Table[(n >> 6) & 63];
+      out[j++] = '=';
+    } else {
+      out[j++] = kBase64Table[(n >> 12) & 63];
+      out[j++] = '=';
+      out[j++] = '=';
+    }
+  }
+  out[j] = '\0';
+  return out;
+}
+
+static napi_value edge_throw(napi_env env, const char *message) {
+  napi_throw_error(env, NULL, message);
+  return NULL;
+}
+
+static napi_value SignMessage(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_status status;
+  napi_valuetype value_type;
+  size_t msg_len = 0;
+  char *msg = NULL;
+  uint8_t signature[32];
+  char *signature_b64 = NULL;
+  napi_value result;
+  napi_value api_key_val;
+  napi_value signature_val;
+  int rc;
+
+  status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
+  if (status != napi_ok || argc < 1) {
+    return edge_throw(env, "signMessage(message) requires a string");
+  }
+
+  status = napi_typeof(env, argv[0], &value_type);
+  if (status != napi_ok || value_type != napi_string) {
+    return edge_throw(env, "message must be a string");
+  }
+
+  status = napi_get_value_string_utf8(env, argv[0], NULL, 0, &msg_len);
+  if (status != napi_ok) {
+    return edge_throw(env, "failed to read message length");
+  }
+
+  msg = (char *)malloc(msg_len + 1);
+  if (msg == NULL) {
+    return edge_throw(env, "out of memory");
+  }
+
+  status = napi_get_value_string_utf8(env, argv[0], msg, msg_len + 1, &msg_len);
+  if (status != napi_ok) {
+    free(msg);
+    return edge_throw(env, "failed to read message");
+  }
+
+  rc = edge_api_hmac_sign(
+    (const uint8_t *)msg, msg_len, EDGE_NODE_BUNDLE_ID, signature
+  );
+  free(msg);
+  if (rc != 0) {
+    return edge_throw(env, "edge_api_hmac_sign failed");
+  }
+
+  signature_b64 = edge_base64_encode(signature, 32);
+  if (signature_b64 == NULL) {
+    return edge_throw(env, "out of memory");
+  }
+
+  status = napi_create_object(env, &result);
+  if (status != napi_ok) {
+    free(signature_b64);
+    return edge_throw(env, "failed to create result object");
+  }
+
+  status = napi_create_string_utf8(env, edge_api_key(), NAPI_AUTO_LENGTH, &api_key_val);
+  if (status != napi_ok) {
+    free(signature_b64);
+    return edge_throw(env, "failed to create apiKey");
+  }
+
+  status = napi_create_string_utf8(
+    env, signature_b64, NAPI_AUTO_LENGTH, &signature_val
+  );
+  free(signature_b64);
+  if (status != napi_ok) {
+    return edge_throw(env, "failed to create signature");
+  }
+
+  status = napi_set_named_property(env, result, "apiKey", api_key_val);
+  if (status != napi_ok) {
+    return edge_throw(env, "failed to set apiKey");
+  }
+  status = napi_set_named_property(env, result, "signature", signature_val);
+  if (status != napi_ok) {
+    return edge_throw(env, "failed to set signature");
+  }
+
+  return result;
+}
+
+static napi_value GetApiKey(napi_env env, napi_callback_info info) {
+  napi_value result;
+  napi_status status =
+    napi_create_string_utf8(env, edge_api_key(), NAPI_AUTO_LENGTH, &result);
+  if (status != napi_ok) {
+    return edge_throw(env, "failed to create apiKey");
+  }
+  return result;
+}
+
+static napi_value Init(napi_env env, napi_value exports) {
+  napi_value sign_fn;
+  napi_value get_key_fn;
+  napi_status status;
+
+  status = napi_create_function(env, "signMessage", NAPI_AUTO_LENGTH, SignMessage, NULL, &sign_fn);
+  if (status != napi_ok) return NULL;
+  status = napi_set_named_property(env, exports, "signMessage", sign_fn);
+  if (status != napi_ok) return NULL;
+
+  status = napi_create_function(env, "getApiKey", NAPI_AUTO_LENGTH, GetApiKey, NULL, &get_key_fn);
+  if (status != napi_ok) return NULL;
+  status = napi_set_named_property(env, exports, "getApiKey", get_key_fn);
+  if (status != napi_ok) return NULL;
+
+  return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
diff --git a/package-lock.json b/package-lock.json
index bcd70a1f96d..b96efa68342 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -58,6 +58,7 @@
         "expo-quick-actions": "^5.0.0",
         "hash.js": "^1.1.7",
         "jsrsasign": "^11.1.0",
+        "lib-cmdparse": "^0.1.0",
         "marked": "^15.0.9",
         "p-debounce": "^4.0.0",
         "posthog-js": "^1.88.1",
@@ -143,7 +144,9 @@
         "@react-native/babel-preset": "0.79.2",
         "@react-native/metro-config": "0.79.2",
         "@react-native/typescript-config": "0.79.2",
-        "@rollup/plugin-babel": "^6.0.3",
+        "@rollup/plugin-babel": "^6.1.0",
+        "@rollup/plugin-json": "^6.1.0",
+        "@rollup/plugin-node-resolve": "^16.0.3",
         "@stakekit/api-hooks": "^0.0.93",
         "@testing-library/react-native": "^13.2.0",
         "@typechain/ethers-v5": "^11.1.2",
@@ -186,7 +189,9 @@
         "lint-staged": "^10.5.3",
         "msw": "^2.8.4",
         "msw-snapshot": "^5.3.0",
+        "nanocolors": "^0.1.2",
         "node-fetch": "2.x",
+        "node-gyp": "^13.0.1",
         "os-browserify": "^0.3.0",
         "patch-package": "^8.0.0",
         "path-browserify": "^1.0.1",
@@ -3803,6 +3808,16 @@
       "version": "2.0.0",
       "license": "MIT"
     },
+    "node_modules/@expo/cli/node_modules/source-map-support": {
+      "version": "0.5.21",
+      "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz",
+      "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==",
+      "license": "MIT",
+      "dependencies": {
+        "buffer-from": "^1.0.0",
+        "source-map": "^0.6.0"
+      }
+    },
     "node_modules/@expo/cli/node_modules/undici": {
       "version": "6.21.3",
       "license": "MIT",
@@ -8509,7 +8524,9 @@
       }
     },
     "node_modules/@rollup/plugin-babel": {
-      "version": "6.0.3",
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-babel/-/plugin-babel-6.1.0.tgz",
+      "integrity": "sha512-dFZNuFD2YRcoomP4oYf+DvQNSUA9ih+A3vUqopQx5EdtPGo3WBnQcI/S8pwpz91UsGfL0HsMSOlaMld8HrbubA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -8522,7 +8539,7 @@
       "peerDependencies": {
         "@babel/core": "^7.0.0",
         "@types/babel__core": "^7.1.9",
-        "rollup": "^1.20.0||^2.0.0||^3.0.0"
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
       },
       "peerDependenciesMeta": {
         "@types/babel__core": {
@@ -8533,20 +8550,68 @@
         }
       }
     },
+    "node_modules/@rollup/plugin-json": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-json/-/plugin-json-6.1.0.tgz",
+      "integrity": "sha512-EGI2te5ENk1coGeADSIwZ7G2Q8CJS2sF120T7jLw4xFw9n7wIOXHo+kIYRAoVpJAN+kmqZSoO3Fp4JtoNF4ReA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.1.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/plugin-node-resolve": {
+      "version": "16.0.3",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-node-resolve/-/plugin-node-resolve-16.0.3.tgz",
+      "integrity": "sha512-lUYM3UBGuM93CnMPG1YocWu7X802BrNF3jW2zny5gQyLQgRFJhV1Sq0Zi74+dh/6NBx1DxFC4b4GXg9wUCG5Qg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.0.1",
+        "@types/resolve": "1.20.2",
+        "deepmerge": "^4.2.2",
+        "is-module": "^1.0.0",
+        "resolve": "^1.22.1"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^2.78.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@rollup/pluginutils": {
-      "version": "5.0.2",
+      "version": "5.4.0",
+      "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.4.0.tgz",
+      "integrity": "sha512-MfPp06CjRLfXQ3wY0R8vJDYBy/MvVcc9OulEfR0B8Iv9ko+GCNaRZ+EpJYFl27LhKsZK0o420sYCRHCjfCgeUg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/estree": "^1.0.0",
         "estree-walker": "^2.0.2",
-        "picomatch": "^2.3.1"
+        "picomatch": "^4.0.2"
       },
       "engines": {
         "node": ">=14.0.0"
       },
       "peerDependencies": {
-        "rollup": "^1.20.0||^2.0.0||^3.0.0"
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
       },
       "peerDependenciesMeta": {
         "rollup": {
@@ -8554,6 +8619,19 @@
         }
       }
     },
+    "node_modules/@rollup/pluginutils/node_modules/picomatch": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
     "node_modules/@rtsao/scc": {
       "version": "1.1.0",
       "dev": true,
@@ -10549,6 +10627,13 @@
         "redux": "^4.0.0"
       }
     },
+    "node_modules/@types/resolve": {
+      "version": "1.20.2",
+      "resolved": "https://registry.npmjs.org/@types/resolve/-/resolve-1.20.2.tgz",
+      "integrity": "sha512-60BCwRFOZCQhDncwQdxxeOEEkbc5dIMccYLwbxsS4TUNeVECQ/pBJ0j09mrHOl/JJvpRPGwO9SvE4nR2Nb/a4Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/secp256k1": {
       "version": "4.0.3",
       "license": "MIT",
@@ -11645,6 +11730,16 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/abbrev": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-5.0.0.tgz",
+      "integrity": "sha512-/XrFJgzQQQHpti1raDJC6m4ws6aNktmjBlhk8Fdlk7LwCEuDoieEJJY9OFHjfiFJFFRM2tK+Ky/IsfbbmlMu1w==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
     "node_modules/abort-controller": {
       "version": "3.0.0",
       "license": "MIT",
@@ -12044,6 +12139,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/array-filter": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/array-filter/-/array-filter-0.0.1.tgz",
+      "integrity": "sha512-VW0FpCIhjZdarWjIz8Vpva7U95fl2Jn+b+mmFFMLn8PIVscOQcAgEznwUzTEuUHuqZqIxwzRlcaN/urTFFQoiw==",
+      "license": "MIT"
+    },
     "node_modules/array-flatten": {
       "version": "1.1.1",
       "dev": true,
@@ -12070,6 +12171,21 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/array-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/array-map/-/array-map-0.0.1.tgz",
+      "integrity": "sha512-sxHIeJTGEsRC8/hYkZzdJNNPZ41EXHVys7pqMw1iwE/Kx8/hto0UbDuGQsSJ0ujPovj9qUZl6EOY/EiZ2g3d9Q==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/array-reduce": {
+      "version": "0.0.0",
+      "resolved": "https://registry.npmjs.org/array-reduce/-/array-reduce-0.0.0.tgz",
+      "integrity": "sha512-8jR+StqaC636u7h3ye1co3lQRefgVVUQUhuAmRbDqIMeR2yuXzRvkCNQiQ5J/wbREmoBLNtp13dhaaVpZQDRUw==",
+      "license": "MIT"
+    },
     "node_modules/array.prototype.findlast": {
       "version": "1.2.5",
       "dev": true,
@@ -17421,6 +17537,24 @@
         "bser": "2.1.1"
       }
     },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/feaxios": {
       "version": "0.0.23",
       "resolved": "https://registry.npmjs.org/feaxios/-/feaxios-0.0.23.tgz",
@@ -20281,7 +20415,6 @@
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/jsonify/-/jsonify-0.0.1.tgz",
       "integrity": "sha512-2/Ki0GcmuqSrgFyelQq9M05y7PS0mEwuIzrf3f1fPqkVDVRvZrPZtVSMHxdgo8Aq0sxAOb/cr2aqqA3LeWHVPg==",
-      "dev": true,
       "license": "Public Domain",
       "funding": {
         "url": "https://github.com/sponsors/ljharb"
@@ -20410,6 +20543,27 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/lib-cmdparse": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/lib-cmdparse/-/lib-cmdparse-0.1.0.tgz",
+      "integrity": "sha512-D4sP6p4h5/lbxkvnwFRvr/uBe0l73yRJOxVBeB9uRMdZK/e6s3FhCw6y2+eUCiJBBSYNFPPWP8h35ejHq6X/mQ==",
+      "license": "MIT",
+      "dependencies": {
+        "shell-quote": "~1.4.0"
+      }
+    },
+    "node_modules/lib-cmdparse/node_modules/shell-quote": {
+      "version": "1.4.3",
+      "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.4.3.tgz",
+      "integrity": "sha512-0Y4SH6mnoNZNW29pNEC0E1F//X7AmbpOj/j5oTssXFUvg2J9MbKIVH3S5ca8Je1Hr36utXJqlzCbYxEYsPAR4A==",
+      "license": "MIT",
+      "dependencies": {
+        "array-filter": "~0.0.0",
+        "array-map": "~0.0.0",
+        "array-reduce": "~0.0.0",
+        "jsonify": "~0.0.0"
+      }
+    },
     "node_modules/libsodium-sumo": {
       "version": "0.7.16",
       "resolved": "https://registry.npmjs.org/libsodium-sumo/-/libsodium-sumo-0.7.16.tgz",
@@ -21799,7 +21953,9 @@
       }
     },
     "node_modules/minizlib": {
-      "version": "3.0.2",
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
+      "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
       "license": "MIT",
       "dependencies": {
         "minipass": "^7.1.2"
@@ -22039,6 +22195,13 @@
       "version": "1.0.1",
       "license": "MIT"
     },
+    "node_modules/nanocolors": {
+      "version": "0.1.12",
+      "resolved": "https://registry.npmjs.org/nanocolors/-/nanocolors-0.1.12.tgz",
+      "integrity": "sha512-2nMHqg1x5PU+unxX7PGY7AuYxl2qDx7PSrTRjizr8sxdd3l/3hBuWWaki62qmtYm2U5i4Z5E7GbjlyDFhs9/EQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/nanoid": {
       "version": "3.3.11",
       "funding": [
@@ -22178,6 +22341,31 @@
         "node": ">= 6.13.0"
       }
     },
+    "node_modules/node-gyp": {
+      "version": "13.0.1",
+      "resolved": "https://registry.npmjs.org/node-gyp/-/node-gyp-13.0.1.tgz",
+      "integrity": "sha512-piOr0S10qy5THB+q5BdqkoOx65XL/tjTMUAit3vciPNp+snTOBnGunWH1Rz7XZUxf2T9uFrfT/Ty4+aC3yPeyg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "env-paths": "^2.2.0",
+        "exponential-backoff": "^3.1.1",
+        "graceful-fs": "^4.2.6",
+        "nopt": "^10.0.0",
+        "proc-log": "^7.0.0",
+        "semver": "^7.3.5",
+        "tar": "^7.5.4",
+        "tinyglobby": "^0.2.12",
+        "undici": "^8.4.1",
+        "which": "^7.0.0"
+      },
+      "bin": {
+        "node-gyp": "bin/node-gyp.js"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
     "node_modules/node-gyp-build": {
       "version": "4.5.0",
       "license": "MIT",
@@ -22187,6 +22375,52 @@
         "node-gyp-build-test": "build-test.js"
       }
     },
+    "node_modules/node-gyp/node_modules/isexe": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-4.0.0.tgz",
+      "integrity": "sha512-FFUtZMpoZ8RqHS3XeXEmHWLA4thH+ZxCv2lOiPIn1Xc7CxrqhWzNSDzD+/chS/zbYezmiwWLdQC09JdQKmthOw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/node-gyp/node_modules/proc-log": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/proc-log/-/proc-log-7.0.0.tgz",
+      "integrity": "sha512-FYgfaA69XZ93zaXLoMNQ+ViDXGGBgR8aLh03txzcFhV+9xOXx7+8DLCULrKKpR9+GsH9ZfHm82aSUPpozX0Ztg==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
+    "node_modules/node-gyp/node_modules/undici": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-8.9.0.tgz",
+      "integrity": "sha512-aWZpUj7XoGonMClx4gdDRfgBjqeA+F473aDmROQQbM9n6PRfK/u1q/a0X4wMTgcHfT8H6fpbt98PFuDUwFg2YA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=22.19.0"
+      }
+    },
+    "node_modules/node-gyp/node_modules/which": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/which/-/which-7.0.0.tgz",
+      "integrity": "sha512-RancgH2dmbLdHl6LRhEqvklWMgl/Hdnun0Y90KhBOLkMefg8Qa7/Zel8Sm+8HEcP6DEjzsWzpkuBQEZok58isA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^4.0.0"
+      },
+      "bin": {
+        "node-which": "bin/which.js"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
     "node_modules/node-html-parser": {
       "version": "7.0.1",
       "license": "MIT",
@@ -22232,6 +22466,22 @@
       "version": "10.17.60",
       "license": "MIT"
     },
+    "node_modules/nopt": {
+      "version": "10.0.1",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-10.0.1.tgz",
+      "integrity": "sha512-df3sBr/6ax9hSGuC3CspvLlbnX8cP5L5nZwXF8cGN8l0zSWR6BvzmQ6jPUKjvo6+/xdpkNvEcucBNUdBeeV13g==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "abbrev": "^5.0.0"
+      },
+      "bin": {
+        "nopt": "bin/nopt.js"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
     "node_modules/normalize-path": {
       "version": "3.0.0",
       "license": "MIT",
@@ -26073,14 +26323,6 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/source-map-support": {
-      "version": "0.5.21",
-      "license": "MIT",
-      "dependencies": {
-        "buffer-from": "^1.0.0",
-        "source-map": "^0.6.0"
-      }
-    },
     "node_modules/spark-md5": {
       "version": "3.0.2",
       "license": "(WTFPL OR MIT)"
@@ -26707,14 +26949,15 @@
       }
     },
     "node_modules/tar": {
-      "version": "7.4.3",
-      "license": "ISC",
+      "version": "7.5.22",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz",
+      "integrity": "sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==",
+      "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/fs-minipass": "^4.0.0",
         "chownr": "^3.0.0",
         "minipass": "^7.1.2",
-        "minizlib": "^3.0.1",
-        "mkdirp": "^3.0.1",
+        "minizlib": "^3.1.0",
         "yallist": "^5.0.0"
       },
       "engines": {
@@ -26742,19 +26985,6 @@
         "streamx": "^2.15.0"
       }
     },
-    "node_modules/tar/node_modules/mkdirp": {
-      "version": "3.0.1",
-      "license": "MIT",
-      "bin": {
-        "mkdirp": "dist/cjs/src/bin.js"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/tar/node_modules/yallist": {
       "version": "5.0.0",
       "license": "BlueOak-1.0.0",
@@ -26803,6 +27033,16 @@
       "version": "2.20.3",
       "license": "MIT"
     },
+    "node_modules/terser/node_modules/source-map-support": {
+      "version": "0.5.21",
+      "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz",
+      "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==",
+      "license": "MIT",
+      "dependencies": {
+        "buffer-from": "^1.0.0",
+        "source-map": "^0.6.0"
+      }
+    },
     "node_modules/teslabot": {
       "version": "1.5.0",
       "license": "MIT"
@@ -26919,6 +27159,36 @@
       "version": "1.6.0",
       "license": "MIT"
     },
+    "node_modules/tinyglobby": {
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tinyglobby/node_modules/picomatch": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
     "node_modules/tmp": {
       "version": "0.2.7",
       "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.7.tgz",
diff --git a/package.json b/package.json
index 2990de46f27..d5adb1c1c4b 100644
--- a/package.json
+++ b/package.json
@@ -46,7 +46,7 @@
     "maestro": "node -r sucrase/register ./scripts/runMaestro.ts",
     "maestro:ios": "node -r sucrase/register ./scripts/runMaestro.ts test --include-tags all,ios maestro",
     "maestro:android": "node -r sucrase/register ./scripts/runMaestro.ts test --include-tags all,android maestro",
-    "precommit": "npm run localize && npm run update-eslint-warnings && lint-staged && tsc && npm test",
+    "precommit": "npm run localize && npm run update-eslint-warnings && lint-staged && npm run docs:api:gates && npm run test:cli:node-safe && tsc && npm test && npm run test:cli:offline",
     "prepare.ios": "(cd ios; pod repo update; pod install)",
     "prepare": "husky install && ./scripts/prepare.sh",
     "rates-cache-replay": "node -r sucrase/register scripts/ratesCacheReplay.ts",
@@ -55,13 +55,41 @@
     "split-baked-and-server-keys": "node -r sucrase/register scripts/splitBakedAndServerKeys.js",
     "start": "react-native start",
     "test": "NODE_ENV=test TZ=America/Los_Angeles jest",
+    "test:all": "npm test && npm run test:cli:offline && npm run test:cli:offline:built",
     "typechain": "rm -rf './src/plugins/contracts/' && typechain --target ethers-v5 --out-dir ./src/plugins/contracts/ './src/plugins/abis/*.json'",
     "theme": "node -r sucrase/register ./scripts/themeServer.ts",
     "updateVersion": "node -r sucrase/register scripts/updateVersion.ts",
     "updot": "EDGE_MODE=development updot",
-    "verify": "npm run lint && npm run typechain && tsc && npm run test",
+    "verify": "npm run lint && npm run typechain && tsc && npm run docs:api:gates && npm run test:cli:node-safe && npm run test:all",
     "watch": "npm test -- --watch",
-    "update-eslint-warnings": "node -r sucrase/register ./scripts/updateEslintWarnings.ts"
+    "update-eslint-warnings": "node -r sucrase/register ./scripts/updateEslintWarnings.ts",
+    "cli": "node -r sucrase/register src/cli/index.ts",
+    "engine": "node -r sucrase/register src/cli/engine/index.ts",
+    "build": "npm run build:cli",
+    "build:cli": "rollup -c rollup.config.cli.mjs",
+    "build:cli:all": "npm run build:cli:native && npm run build:cli && npm run build:cli:copy-native",
+    "build:cli:native": "bash ./scripts/buildNodeApiSigner.sh",
+    "build:cli:copy-native": "mkdir -p lib && cp -f native/edge-api-signer/node/build/Release/edge_api_signer.node lib/edge_api_signer.node",
+    "docs:api": "npm run docs:api:cli && node -r sucrase/register scripts/buildApiDocs.ts",
+    "docs:api:cli": "node -r sucrase/register scripts/buildCliCommands.ts && node -r sucrase/register scripts/buildCliHelp.ts",
+    "docs:api:check": "node -r sucrase/register scripts/buildCliCommands.ts --check && node -r sucrase/register scripts/buildCliHelp.ts --check && node -r sucrase/register scripts/buildApiDocs.ts --check",
+    "docs:api:verify": "node -r sucrase/register scripts/verifyApiDocs.ts",
+    "docs:api:contracts": "node -r sucrase/register scripts/checkRouteContracts.ts",
+    "docs:api:core": "node -r sucrase/register scripts/checkCoreAlignment.ts",
+    "docs:api:coverage": "node -r sucrase/register scripts/checkCliCoverage.ts",
+    "docs:api:gates": "npm run docs:api:check && npm run docs:api:verify && npm run docs:api:contracts && npm run docs:api:core && npm run docs:api:coverage",
+    "test:cli:offline": "node -r sucrase/register scripts/testCliFake.ts && node -r sucrase/register scripts/testCliSubscribe.ts",
+    "test:cli:offline:built": "npm run build:cli && EDGE_CLI_BIN=lib/edgeCli.js npm run test:cli:offline",
+    "test:cli:fake": "node -r sucrase/register scripts/testCliFake.ts",
+    "test:cli:subscribe": "node -r sucrase/register scripts/testCliSubscribe.ts",
+    "test:cli:interactive": "node -r sucrase/register scripts/testCliInteractive.ts",
+    "test:cli:oneshot": "node -r sucrase/register scripts/testCli.ts",
+    "test:cli:captcha": "node -r sucrase/register scripts/testCliCaptcha.ts",
+    "test:cli:edge-login": "node -r sucrase/register scripts/testEdgeLogin.ts",
+    "test:cli:node-safe": "node scripts/cliNodeSafeSmoke.js",
+    "test:cli:node-hmac": "node -r sucrase/register scripts/testNodeApiSigner.ts",
+    "test:cli": "node -r sucrase/register scripts/testCli.ts && node -r sucrase/register scripts/testCliCaptcha.ts",
+    "test:cli:network": "npm run test:cli:oneshot && npm run test:cli:captcha && npm run test:cli:edge-login"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": "eslint"
@@ -119,6 +147,7 @@
     "expo-quick-actions": "^5.0.0",
     "hash.js": "^1.1.7",
     "jsrsasign": "^11.1.0",
+    "lib-cmdparse": "^0.1.0",
     "marked": "^15.0.9",
     "p-debounce": "^4.0.0",
     "posthog-js": "^1.88.1",
@@ -204,7 +233,9 @@
     "@react-native/babel-preset": "0.79.2",
     "@react-native/metro-config": "0.79.2",
     "@react-native/typescript-config": "0.79.2",
-    "@rollup/plugin-babel": "^6.0.3",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@stakekit/api-hooks": "^0.0.93",
     "@testing-library/react-native": "^13.2.0",
     "@typechain/ethers-v5": "^11.1.2",
@@ -247,7 +278,9 @@
     "lint-staged": "^10.5.3",
     "msw": "^2.8.4",
     "msw-snapshot": "^5.3.0",
+    "nanocolors": "^0.1.2",
     "node-fetch": "2.x",
+    "node-gyp": "^13.0.1",
     "os-browserify": "^0.3.0",
     "patch-package": "^8.0.0",
     "path-browserify": "^1.0.1",
diff --git a/rollup.config.cli.mjs b/rollup.config.cli.mjs
new file mode 100644
index 00000000000..2d130fa6a5e
--- /dev/null
+++ b/rollup.config.cli.mjs
@@ -0,0 +1,87 @@
+import babel from '@rollup/plugin-babel'
+import json from '@rollup/plugin-json'
+import resolve from '@rollup/plugin-node-resolve'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const packageJson = require('./package.json')
+
+const extensions = ['.ts']
+const babelOpts = {
+  babelHelpers: 'bundled',
+  babelrc: false,
+  configFile: false,
+  extensions,
+  include: ['src/**/*'],
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        // The CLI bundle runs on Node, so target Node rather than downlevelling
+        // for browsers. `loose: true` compiled `[...aSet]` to
+        // `[].concat(aSet)`, which wraps the Set instead of spreading it — the
+        // built engine then iterated the Set object itself and died on the
+        // first event. Targeting Node 18 leaves spread native.
+        targets: { node: '18' },
+        exclude: ['transform-regenerator']
+      }
+    ],
+    '@babel/typescript'
+  ],
+  // No Babel plugins. In particular not `transform-fake-error-class`, which
+  // rewrites `class X extends Error` into a function returning a plain Error
+  // — its own README notes that makes `instanceof X` always false, and the
+  // engine and client both dispatch on `instanceof EngineError`,
+  // `ApiClientError` and `UsageError`. This bundle targets Node 18, where
+  // native subclasses work and give good stack traces. (The repo does not
+  // depend on that plugin at all; it was declared and never used.)
+  plugins: []
+}
+const resolveOpts = { extensions }
+
+// Node builtins, plus whatever `package.json` calls a runtime dependency.
+//
+// That second part is why a CLI-only package belongs in `devDependencies`:
+// listed as a dependency it is left out of the bundle and has to be installed
+// alongside it, which also puts it in the React Native app's runtime graph for
+// nothing. `nanocolors` is therefore a dev dependency and is bundled.
+// `lib-cmdparse` cannot be: it is CommonJS with no default export, so
+// bundling it needs `@rollup/plugin-commonjs`, and until then it stays a
+// runtime dependency on purpose. If the CLI is ever published as its own
+// package with its own `dependencies`, this is the line to revisit.
+const external = [
+  'buffer',
+  'child_process',
+  'crypto',
+  'fs',
+  'http',
+  'https',
+  'net',
+  'os',
+  'path',
+  'readline',
+  ...Object.keys(packageJson.dependencies)
+]
+
+export default [
+  {
+    external,
+    input: 'src/cli/index.ts',
+    output: {
+      banner: '#!/usr/bin/env node',
+      file: 'lib/edgeCli.js',
+      format: 'cjs'
+    },
+    plugins: [json(), babel(babelOpts), resolve(resolveOpts)]
+  },
+  {
+    external,
+    input: 'src/cli/engine/index.ts',
+    output: {
+      banner: '#!/usr/bin/env node',
+      file: 'lib/edgeEngine.js',
+      format: 'cjs'
+    },
+    plugins: [json(), babel(babelOpts), resolve(resolveOpts)]
+  }
+]
diff --git a/scripts/apiDocs.css b/scripts/apiDocs.css
new file mode 100644
index 00000000000..45a4ab69da8
--- /dev/null
+++ b/scripts/apiDocs.css
@@ -0,0 +1,147 @@
+
+:root {
+  --bg: #fff; --fg: #16181d; --dim: #6b7280; --line: #e5e7eb; --card: #fafafa;
+  --accent: #2563eb; --code: #f3f4f6; --warn: #b45309; --ok: #047857;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0d1117; --fg: #e6edf3; --dim: #8b949e; --line: #262c36; --card: #131920;
+    --accent: #6ea8ff; --code: #1a212b; --warn: #d29922; --ok: #3fb950;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; background: var(--bg); color: var(--fg);
+  font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+}
+code, pre { font-family: var(--mono); font-size: 13px; }
+code { background: var(--code); padding: 1px 5px; border-radius: 4px; }
+pre { background: var(--code); padding: 12px 14px; border-radius: 8px; overflow-x: auto; margin: 8px 0; }
+pre code { background: none; padding: 0; }
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+.layout { display: flex; align-items: flex-start; }
+nav {
+  position: sticky; top: 0; height: 100vh; overflow-y: auto; flex: 0 0 270px;
+  border-right: 1px solid var(--line); padding: 20px 12px 60px;
+}
+nav h1 { font-size: 15px; margin: 0 8px 4px; }
+nav .ver { font-size: 12px; color: var(--dim); margin: 0 8px 14px; }
+nav input {
+  width: 100%; padding: 7px 10px; margin-bottom: 14px; font: inherit; font-size: 13px;
+  border: 1px solid var(--line); border-radius: 7px; background: var(--bg); color: var(--fg);
+}
+nav .s { font: 700 12px/1.5 var(--sans); text-transform: uppercase; letter-spacing: .08em;
+  color: var(--fg); margin: 18px 0 4px; padding-top: 10px; border-top: 1px solid var(--line); }
+nav .s:first-child { margin-top: 0; padding-top: 0; border-top: none; }
+nav .g { font-size: 11px; text-transform: uppercase; letter-spacing: .07em; color: var(--dim);
+  margin: 16px 8px 5px; font-weight: 600; }
+nav a.e { display: block; padding: 3px 8px; border-radius: 5px; font-size: 13px; color: var(--fg); }
+nav a.e:hover { background: var(--card); text-decoration: none; }
+nav a.e code { background: none; padding: 0; color: var(--accent); }
+nav a.e .restonly { color: var(--dim); font-style: italic; font-size: 12px; }
+
+main { flex: 1 1 auto; min-width: 0; padding: 32px 40px 120px; max-width: 1000px; }
+h2 { font-size: 22px; margin: 48px 0 6px; padding-top: 14px; border-top: 1px solid var(--line); }
+h3.sub { font-size: 16px; margin: 30px 0 4px; color: var(--fg); }
+h2:first-of-type { border-top: none; margin-top: 8px; }
+.groupdoc { color: var(--dim); margin: 0 0 8px; }
+
+.endpoint { border: 1px solid var(--line); border-radius: 12px; padding: 18px 20px;
+  margin: 18px 0; background: var(--card); }
+.endpoint header { display: flex; flex-wrap: wrap; align-items: baseline;
+  justify-content: space-between; gap: 8px; }
+.endpoint h3 { font-size: 17px; margin: 0; }
+.endpoint h3 a { color: var(--fg); }
+.ids { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.cmdname { background: var(--accent); color: #fff; font-weight: 600; }
+.restonly { color: var(--dim); font-style: italic; font-size: 12px; }
+.src { color: var(--dim); font-size: 11px; font-family: var(--mono); }
+.shape { margin: 6px 0; }
+.shape-h { font: 600 10px var(--mono); text-transform: uppercase; letter-spacing: .06em;
+  color: var(--dim); margin-bottom: 4px; }
+pre.ts { background: var(--code); border-left: 3px solid var(--accent); }
+pre.json { background: transparent; border: 1px dashed var(--line); }
+.shape details { margin: 6px 0; }
+.shape summary { cursor: pointer; font-size: 12px; color: var(--dim); user-select: none; }
+.shape summary:hover { color: var(--accent); }
+.core { margin: 8px 0 2px; font-size: 13px; display: flex; align-items: baseline;
+  gap: 8px; flex-wrap: wrap; }
+.core .lbl { font: 600 10px var(--mono); text-transform: uppercase; letter-spacing: .06em;
+  color: var(--dim); border: 1px solid var(--line); border-radius: 3px; padding: 1px 5px; }
+.core code { color: var(--ok); }
+.core.none em { color: var(--dim); font-style: italic; }
+.desc { margin: 8px 0 4px; }
+.desc p { margin: 6px 0; }
+
+.panes { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-top: 14px; }
+@media (max-width: 900px) { .panes { grid-template-columns: 1fr; } }
+.pane { background: var(--bg); border: 1px solid var(--line); border-radius: 9px; padding: 12px 14px;
+  /* A grid item defaults to min-width:auto, so a long unbreakable line makes
+     the column wider than its 1fr share and shoves the next pane sideways.
+     `overflow-x` on the <pre> never gets a chance until this is 0. */
+  min-width: 0; }
+.pane h4 { margin: 0 0 8px; font-size: 12px; text-transform: uppercase;
+  letter-spacing: .07em; color: var(--dim); }
+.pane h5 { margin: 12px 0 4px; font-size: 12px; color: var(--dim); font-weight: 600; }
+.pane.resp, .pane.notes { margin-top: 16px; }
+.pane.cli.none p { margin: 0; }
+.cmd + .cmd { margin-top: 14px; padding-top: 14px; border-top: 1px dashed var(--line); }
+/* A command line is a sentence, not a table: wrap it at the spaces rather
+   than making the reader scroll a pane sideways. `get-transactions` is 322
+   characters. */
+.usage, .ex { white-space: pre-wrap; overflow-wrap: break-word; }
+.usage { background: var(--code); }
+.ex { background: transparent; border: 1px dashed var(--line); }
+.lead { margin: 4px 0; color: var(--dim); font-size: 13px; }
+.note { font-size: 13px; }
+.note p { margin: 4px 0; }
+.pane.notes ul { margin: 0; padding-left: 20px; }
+.pane.notes li { margin: 5px 0; }
+
+.route { margin: 0 0 4px; display: flex; align-items: center; gap: 8px; }
+.m { font: 600 11px var(--mono); padding: 2px 7px; border-radius: 4px; color: #fff; }
+.m-GET { background: #2563eb; } .m-POST { background: #047857; }
+.m-PUT { background: #b45309; } .m-PATCH { background: #7c3aed; }
+.m-DELETE { background: #b91c1c; }
+
+table { border-collapse: collapse; width: 100%; margin: 4px 0; }
+table.fields td, table.flags td, table.flags th { padding: 4px 8px 4px 0;
+  vertical-align: top; font-size: 13px; border-bottom: 1px solid var(--line); }
+table.flags th { text-align: left; font-size: 11px; color: var(--dim); text-transform: uppercase; }
+td.k { white-space: nowrap; width: 1%; }
+td.ty { white-space: nowrap; width: 1%; }
+td.doc { color: var(--dim); }
+tr.d1 td.k { padding-left: 18px; } tr.d2 td.k { padding-left: 36px; }
+.t { color: var(--dim); font-family: var(--mono); font-size: 12px; }
+.t.core { color: var(--warn); border-bottom: 1px dotted var(--warn); cursor: help; }
+.dim { color: var(--dim); }
+.ref { font-family: var(--mono); font-size: 12px; }
+.flag { font-size: 10px; padding: 1px 5px; border-radius: 3px; border: 1px solid var(--line);
+  color: var(--dim); text-transform: uppercase; letter-spacing: .04em; }
+.flag.req { color: var(--warn); border-color: var(--warn); }
+.st { font: 600 11px var(--mono); padding: 1px 6px; border-radius: 4px;
+  background: var(--code); margin-right: 5px; }
+.st.ok { color: var(--ok); }
+.errs { display: flex; flex-wrap: wrap; gap: 6px; margin: 4px 0; }
+a.err { font: 12px var(--mono); border: 1px solid var(--line); border-radius: 5px;
+  padding: 2px 7px; color: var(--fg); }
+a.err:hover { border-color: var(--accent); text-decoration: none; }
+
+.schema { border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; margin: 14px 0;
+  background: var(--card); }
+.schema h3 { margin: 0 0 2px; font-size: 15px; font-family: var(--mono); }
+.schema .src { display: block; margin-bottom: 6px; }
+.hidden { display: none; }
+
+/* An alternate CLI binding's heading, e.g. `spend-max` under `spend`. */
+h5.alt {
+  margin: 1.1rem 0 0.35rem;
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+h5.alt code {
+  font-size: 0.95rem;
+}
diff --git a/scripts/buildApiDocs.ts b/scripts/buildApiDocs.ts
new file mode 100644
index 00000000000..6bcf8af5ebb
--- /dev/null
+++ b/scripts/buildApiDocs.ts
@@ -0,0 +1,800 @@
+/**
+ * Compiles the API reference from the route declarations.
+ *
+ *   docs/api/dist/openapi.json   OpenAPI 3.1, with `x-cli` and `x-core-call`
+ *   docs/api/dist/index.html     self-contained human-readable reference
+ *
+ *   node -r sucrase/register scripts/buildApiDocs.ts
+ *
+ * Everything here comes from `src/cli/engine/routes/*.ts`: the JSDoc above each
+ * `route(…)` supplies the prose, and the cleaners supply the shapes, resolved
+ * through the TypeScript checker. The command line is rendered first in each
+ * entry, because the two are one call seen from two directions.
+ */
+import fs from 'fs'
+import { marked } from 'marked'
+import path from 'path'
+
+import { groupOrder, sectionOrder } from '../docs/api/groups'
+import { CLI_EXIT_CODES, errorCodes } from '../docs/api/shared'
+import { API_VERSION } from '../src/cli/engine/apiVersion'
+import { SCOPE_PARAMS } from '../src/cli/engine/doc'
+import { EXAMPLE_TCP_PORT } from '../src/cli/engine/tcpPort'
+import { usageFor } from './cliUsage'
+import {
+  type ExtractedCli,
+  type ExtractedField,
+  type ExtractedRoute,
+  extractRoutes
+} from './extractRoutes'
+import { writeIfChanged } from './writeIfChanged'
+
+/**
+ * What a path parameter is, in prose.
+ *
+ * A derived positional keeps the description written beside its cleaner; a
+ * scope parameter means the same thing everywhere and is described once.
+ */
+function pathParamDoc(e: ExtractedRoute, name: string): string {
+  if (name === e.pathPositional) {
+    const field = [...(e.query ?? []), ...(e.body ?? [])].find(
+      f => f.name === name
+    )
+    if (field?.doc != null) return field.doc
+  }
+  return SCOPE_PARAMS[name] ?? ''
+}
+
+/**
+ * Request fields, minus the one the path carries.
+ *
+ * A positional is declared as an ordinary field but travels as a path
+ * segment. Listing it in both tables would tell a reader to send it twice.
+ */
+function requestFields(
+  e: ExtractedRoute,
+  fields: ExtractedField[] | undefined
+): ExtractedField[] | undefined {
+  if (fields == null) return undefined
+  const out = fields.filter(f => f.name !== e.pathPositional)
+  return out.length === 0 ? undefined : out
+}
+
+const OUT = path.resolve(__dirname, '../docs/api/dist')
+
+interface Group {
+  id: string
+  title: string
+  doc: string
+  section: string
+  endpoints: ExtractedRoute[]
+}
+
+function buildGroups(): Group[] {
+  const routes = extractRoutes()
+  const out: Group[] = []
+  for (const info of groupOrder) {
+    const endpoints = routes.filter(r => r.group === info.id)
+    if (endpoints.length > 0) out.push({ ...info, endpoints })
+  }
+  const placed = new Set(out.flatMap(g => g.endpoints.map(e => e.id)))
+  const rest = routes.filter(r => !placed.has(r.id))
+  if (rest.length > 0) {
+    out.push({
+      id: 'other',
+      title: 'Other',
+      doc: '',
+      section: 'other',
+      endpoints: rest
+    })
+  }
+  return out
+}
+
+const groups = buildGroups()
+
+interface Section {
+  id: string
+  title: string
+  doc: string
+  groups: Group[]
+}
+
+/** Sections in declared order, each holding the groups that named it. */
+function buildSections(): Section[] {
+  const out: Section[] = []
+  for (const info of sectionOrder) {
+    const inSection = groups.filter(g => g.section === info.id)
+    if (inSection.length > 0) out.push({ ...info, groups: inSection })
+  }
+  const placed = new Set(out.flatMap(s => s.groups.map(g => g.id)))
+  const rest = groups.filter(g => !placed.has(g.id))
+  if (rest.length > 0) {
+    out.push({ id: 'other', title: 'Other', doc: '', groups: rest })
+  }
+  return out
+}
+
+const sections = buildSections()
+
+// ------------------------------------------------------------------ helpers
+
+function esc(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+function md(text: string | undefined): string {
+  if (text == null || text === '') return ''
+  return marked.parseInline(text) as string
+}
+
+function mdBlock(text: string | undefined): string {
+  if (text == null || text === '') return ''
+  return marked.parse(text) as string
+}
+
+/** A resolved type string, rendered with the primitives played down. */
+function typeLabel(type: string): string {
+  return `<span class="t">${esc(type)}</span>`
+}
+
+/** Plausible JSON for a resolved type, so examples read like real payloads. */
+function exampleFor(type: string, name = ''): unknown {
+  const t = type.trim()
+  if (t.endsWith('[]')) return [exampleFor(t.slice(0, -2), name)]
+  if (t.startsWith('Array<')) return [exampleFor(t.slice(6, -1), name)]
+  if (t.includes('|')) {
+    const parts = t.split('|').map(p => p.trim())
+    const first = parts.find(p => p !== 'null' && p !== 'undefined')
+    return first != null ? exampleFor(first, name) : null
+  }
+  if (t === 'boolean') return true
+  if (t === 'number')
+    return /Height|Count|Seconds|Ratio|rate/i.test(name) ? 1 : 0
+  if (t === 'null') return null
+  if (t.startsWith("'")) return t.replace(/'/g, '').split(' ')[0]
+  if (t === 'string') {
+    if (/date|At$/i.test(name)) return '2026-09-02T16:35:00.000Z'
+    if (/Amount|Fee/i.test(name)) return '12345'
+    if (/Id$/i.test(name)) return 'FS8xJ2kQ…'
+    return 'string'
+  }
+  if (t === 'unknown' || t === 'any') return {}
+  if (t.startsWith('{')) return {}
+  return `<${t}>`
+}
+
+function exampleObject(fields: ExtractedField[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const f of fields) out[f.name] = exampleFor(f.type, f.name)
+  return out
+}
+
+/**
+ * Break a resolved type across lines the way a person would write it.
+ *
+ * The compiler hands back one long string —
+ * `{ tokenId: string | null; currencyCode: string; … }[]` — which is
+ * unreadable past a couple of fields. This indents nested object literals and
+ * puts one member per line. Only `{`, `;` and `}` matter; a `;` inside a
+ * string literal type would be misread, and no cleaner produces one.
+ */
+function formatType(type: string, indent = 0): string {
+  let out = ''
+  let depth = indent
+  const pad = (n: number): string => '  '.repeat(n)
+  for (let i = 0; i < type.length; i++) {
+    const c = type[i]
+    if (c === '{') {
+      depth++
+      out += '{\n' + pad(depth)
+    } else if (c === '}') {
+      depth--
+      out = out.replace(/[ \n]+$/, '')
+      out += '\n' + pad(depth) + '}'
+    } else if (c === ';') {
+      // A trailing `;` before `}` would leave a blank line.
+      const rest = type.slice(i + 1).trimStart()
+      out += rest.startsWith('}') ? '' : ';\n' + pad(depth)
+    } else if (c === ' ' && out.endsWith('\n' + pad(depth))) {
+      // Swallow the space the compiler puts after `{` and `;`.
+    } else {
+      out += c
+    }
+  }
+  return out
+}
+
+function tsInterface(fields: ExtractedField[]): string {
+  const lines = fields.map(
+    f =>
+      `  ${f.name}${f.optional ? '?' : ''}: ${formatType(
+        f.type,
+        1
+      ).trimStart()}`
+  )
+  return `{\n${lines.join('\n')}\n}`
+}
+
+function fieldRows(fields: ExtractedField[]): string {
+  return fields
+    .map(
+      f => `<tr>
+  <td class="k"><code>${esc(f.name)}</code></td>
+  <td class="ty">${typeLabel(f.type)}${
+        f.optional ? ' <span class="flag opt">optional</span>' : ''
+      }</td>
+  <td class="doc">${md(f.doc)}</td>
+</tr>`
+    )
+    .join('\n')
+}
+
+/** Type, example and per-field prose: three views of one shape. */
+function shapeBlock(fields: ExtractedField[], label: string): string {
+  if (fields.length === 0) return ''
+  return `<div class="shape">
+    <div class="shape-h">${esc(label)}</div>
+    <pre class="ts"><code>${esc(tsInterface(fields))}</code></pre>
+    <details><summary>Example</summary><pre class="json"><code>${esc(
+      JSON.stringify(exampleObject(fields), null, 2)
+    )}</code></pre></details>
+    <table class="fields"><tbody>${fieldRows(fields)}</tbody></table>
+  </div>`
+}
+
+// ------------------------------------------------------------ endpoint HTML
+
+function coreLine(e: ExtractedRoute): string {
+  const note =
+    e.coreNote != null ? ` <span class="dim">${md(e.coreNote)}</span>` : ''
+  if (e.core == null) {
+    return `<p class="core none"><span class="lbl">core</span><em>${
+      e.coreNote != null ? md(e.coreNote) : 'No direct core call.'
+    }</em></p>`
+  }
+  const diffs = Object.entries(e.coreExtra)
+  const extra =
+    diffs.length === 0
+      ? ''
+      : `<div class="note"><p><strong>Differs from core:</strong></p><ul>${diffs
+          .map(([k, v]) => `<li><code>${esc(k)}</code> — ${md(v)}</li>`)
+          .join('')}</ul></div>`
+  return `<p class="core"><span class="lbl">core</span><code>${esc(
+    e.core
+  )}</code>${note}</p>${extra}`
+}
+
+function cliBlock(e: ExtractedRoute): string {
+  if (e.cli == null) {
+    return `<div class="pane cli none"><h4>Command line</h4>
+      <p class="dim">No <code>edge-cli</code> command. REST only.</p></div>`
+  }
+  const cli: ExtractedCli = e.cli
+  const extras =
+    cli.extra.length === 0
+      ? ''
+      : `<h5>Client-only flags</h5><table class="fields"><tbody>${cli.extra
+          .map(
+            x =>
+              `<tr><td class="k"><code>--${esc(
+                x.name
+              )}</code></td><td class="ty">${
+                x.required === true
+                  ? '<span class="flag req">required</span>'
+                  : '<span class="flag opt">optional</span>'
+              }</td><td class="doc">${md(x.doc)}</td></tr>`
+          )
+          .join('')}</tbody></table>`
+  // A route can bind more than one command — `spend` and `spend-max` share
+  // one, differing only by a preset — and rendering only the first left the
+  // others out of the reference entirely.
+  const alternates = e.cliExtra
+    .map(
+      extra =>
+        // The alternate's own `summary` as a heading. Rendering only its
+        // usage line left `spend-max` under a section headed "Send funds."
+        // — the summary it declares appeared nowhere in the document.
+        `<h5 class="alt"><code>${esc(extra.command)}</code>${
+          extra.summary != null ? ` — ${esc(extra.summary)}` : ''
+        }</h5><pre class="usage"><code>${esc(usageFor(e, extra))}</code></pre>${
+          extra.notes != null
+            ? `<div class="note">${mdBlock(extra.notes)}</div>`
+            : ''
+        }`
+    )
+    .join('')
+  return `<div class="pane cli">
+    <h4>Command line</h4>
+    <pre class="usage"><code>${esc(usageFor(e, e.cli))}</code></pre>
+    ${alternates}
+    ${extras}
+    ${cli.notes != null ? `<div class="note">${mdBlock(cli.notes)}</div>` : ''}
+  </div>`
+}
+
+function curlFor(e: ExtractedRoute): string {
+  const p = e.routePath
+    .replace('{sessionId}', '$SESS')
+    .replace('{walletId}', '$WID')
+    .replace(/\{(\w+)\}/g, (_m, n) => `$${String(n).toUpperCase()}`)
+  const required = (e.query ?? []).filter(q => !q.optional)
+  const qs =
+    required.length > 0 ? '?' + required.map(q => `${q.name}=…`).join('&') : ''
+  const lines = ['curl --unix-socket "$SOCK" \\']
+  if (e.method !== 'GET') lines.push(`  -X ${e.method} \\`)
+  if (e.body != null && e.body.length > 0) {
+    lines.push(`  -H 'Content-Type: application/json' \\`)
+    lines.push(`  -d '${JSON.stringify(exampleObject(e.body))}' \\`)
+  }
+  lines.push(`  'http://localhost${p}${qs}'`)
+  return lines.join('\n')
+}
+
+function restBlock(e: ExtractedRoute): string {
+  const pathTable =
+    e.pathParams.length === 0
+      ? ''
+      : `<h5>Path</h5><table class="fields"><tbody>${e.pathParams
+          .map(
+            n =>
+              `<tr><td class="k"><code>${esc(
+                n
+              )}</code></td><td class="ty">${typeLabel(
+                'string'
+              )}</td><td class="doc">${md(pathParamDoc(e, n))}</td></tr>`
+          )
+          .join('')}</tbody></table>`
+  return `<div class="pane rest">
+    <h4>REST</h4>
+    <p class="route"><span class="m m-${e.method}">${
+    e.method
+  }</span><code>${esc(e.routePath)}</code></p>
+    ${pathTable}
+    ${
+      requestFields(e, e.query) != null
+        ? shapeBlock(requestFields(e, e.query)!, 'Query')
+        : ''
+    }
+    ${
+      e.bodyNote != null ? `<div class="note">${mdBlock(e.bodyNote)}</div>` : ''
+    }
+    ${
+      requestFields(e, e.body) != null
+        ? shapeBlock(requestFields(e, e.body)!, 'Request body')
+        : ''
+    }
+    <h5>Example</h5>
+    <pre class="ex"><code>${esc(curlFor(e))}</code></pre>
+  </div>`
+}
+
+function responseBlock(e: ExtractedRoute): string {
+  const status = e.returns == null && e.returnsType == null ? 204 : 200
+  const errs =
+    e.errors.length === 0
+      ? ''
+      : `<h5>Errors</h5><p class="errs">${e.errors
+          .map(code => {
+            const known = errorCodes.find(x => x.code === code)
+            return `<a href="#err-${code}" class="err" title="${esc(
+              known?.doc ?? ''
+            )}"><span class="st">${known?.status ?? '?'}</span>${code}</a>`
+          })
+          .join(' ')}</p>`
+  const prose = e.returnsProse ?? e.returnsDoc
+  const body =
+    status === 204
+      ? '<p class="lead dim">No body.</p>'
+      : `${prose != null ? `<div class="note">${mdBlock(prose)}</div>` : ''}${
+          e.returns != null && e.returns.length > 0
+            ? shapeBlock(e.returns, 'Response body')
+            : `<pre class="ts"><code>${esc(
+                formatType(e.returnsType ?? 'unknown')
+              )}</code></pre>`
+        }`
+  return `<div class="pane resp">
+    <h4>Response <span class="st ok">${status}</span></h4>
+    ${body}
+    ${errs}
+  </div>`
+}
+
+function endpointHtml(e: ExtractedRoute): string {
+  const name =
+    e.cli != null
+      ? `<code class="cmdname">${esc(e.cli.command)}</code>`
+      : '<span class="restonly">REST only</span>'
+  const notes =
+    e.notes.length === 0
+      ? ''
+      : `<div class="pane notes"><h4>Notes</h4><ul>${e.notes
+          .map(n => `<li>${md(n)}</li>`)
+          .join('')}</ul></div>`
+  return `<section class="endpoint" id="${e.id}">
+    <header>
+      <h3><a href="#${e.id}">${esc(e.summary)}</a></h3>
+      <div class="ids">${name}<span class="src" title="Declared in">src/cli/engine/routes/${esc(
+    e.file
+  )}</span></div>
+    </header>
+    ${coreLine(e)}
+    ${
+      e.description != null
+        ? `<div class="desc">${mdBlock(e.description)}</div>`
+        : ''
+    }
+    <div class="panes">${cliBlock(e)}${restBlock(e)}</div>
+    ${responseBlock(e)}
+    ${notes}
+  </section>`
+}
+
+// ------------------------------------------------------------------- OpenAPI
+
+/** A resolved type string, as JSON Schema. */
+function jsonSchema(type: string): Record<string, unknown> {
+  const t = type.trim()
+  if (t.endsWith('[]'))
+    return { type: 'array', items: jsonSchema(t.slice(0, -2)) }
+  if (t.startsWith('Array<')) {
+    return { type: 'array', items: jsonSchema(t.slice(6, -1)) }
+  }
+  if (t.includes('|')) {
+    const parts = t
+      .split('|')
+      .map(p => p.trim())
+      .filter(p => p !== 'undefined')
+    if (parts.every(p => p.startsWith("'"))) {
+      return { type: 'string', enum: parts.map(p => p.replace(/'/g, '')) }
+    }
+    return { anyOf: parts.map(jsonSchema) }
+  }
+  if (t === 'string' || t.startsWith("'")) return { type: 'string' }
+  if (t === 'number') return { type: 'number' }
+  if (t === 'boolean') return { type: 'boolean' }
+  if (t === 'null') return { type: 'null' }
+  if (t === 'unknown' || t === 'any') return {}
+  return { description: t }
+}
+
+function objectSchema(fields: ExtractedField[]): Record<string, unknown> {
+  const properties: Record<string, unknown> = {}
+  const required: string[] = []
+  for (const f of fields) {
+    properties[f.name] =
+      f.doc != null
+        ? { ...jsonSchema(f.type), description: f.doc }
+        : jsonSchema(f.type)
+    if (!f.optional) required.push(f.name)
+  }
+  const out: Record<string, unknown> = { type: 'object', properties }
+  if (required.length > 0) out.required = required
+  return out
+}
+
+function buildOpenApi(): Record<string, unknown> {
+  const paths: Record<string, Record<string, unknown>> = {}
+  for (const g of groups) {
+    for (const e of g.endpoints) {
+      const coreMd =
+        e.core != null
+          ? `**Core call:** \`${e.core}\`\n\n`
+          : `**Core call:** _none — ${e.coreNote ?? ''}_\n\n`
+      const cliMd =
+        e.cli != null
+          ? '**Command line**\n\n```\n' + usageFor(e, e.cli) + '\n```\n\n'
+          : '_No `edge-cli` command; REST only._\n\n'
+      const op: Record<string, unknown> = {
+        operationId: e.id,
+        summary: e.summary,
+        description: coreMd + cliMd + (e.description ?? ''),
+        tags: [g.title],
+        'x-cli': e.cli,
+        // Routes with a second binding (`spend-max` presets `spend`) were
+        // otherwise absent from the document entirely.
+        ...(e.cliExtra.length > 0 ? { 'x-cli-alternates': e.cliExtra } : {}),
+        'x-core-call': e.core,
+        'x-core-note': e.coreNote,
+        'x-source': `src/cli/engine/routes/${e.file}`,
+        parameters: [
+          ...e.pathParams.map(n => ({
+            name: n,
+            in: 'path',
+            required: true,
+            description: pathParamDoc(e, n),
+            schema: { type: 'string' }
+          })),
+          ...(requestFields(e, e.query) ?? []).map(q => ({
+            name: q.name,
+            in: 'query',
+            required: !q.optional,
+            description: q.doc,
+            schema: jsonSchema(q.type)
+          }))
+        ],
+        responses: {
+          [e.returns == null && e.returnsType == null ? '204' : '200']:
+            e.returns == null && e.returnsType == null
+              ? { description: 'No content.' }
+              : {
+                  description: e.returnsProse ?? e.returnsDoc ?? 'Success.',
+                  content: {
+                    'application/json': {
+                      schema:
+                        e.returns != null && e.returns.length > 0
+                          ? objectSchema(e.returns)
+                          : jsonSchema(e.returnsType ?? 'unknown')
+                    }
+                  }
+                },
+          default: {
+            description: e.errors.length > 0 ? e.errors.join(', ') : 'Error.',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+              }
+            }
+          }
+        }
+      }
+      const bodyFields = requestFields(e, e.body)
+      if (bodyFields != null) {
+        op.requestBody = {
+          required: true,
+          description: e.bodyNote,
+          content: { 'application/json': { schema: objectSchema(bodyFields) } }
+        }
+      }
+      paths[e.routePath] = paths[e.routePath] ?? {}
+      paths[e.routePath][e.method.toLowerCase()] = op
+    }
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'Edge CLI',
+      version: API_VERSION,
+      description:
+        'The `edge-cli` command line and the `edge-engine` JSON REST API, generated from the route declarations in `src/cli/engine/routes/`.'
+    },
+    servers: [
+      {
+        url: 'http://localhost',
+        description: 'Unix socket at ~/.edge-cli/run/<profile>/engine.sock'
+      },
+      {
+        url: `http://127.0.0.1:${EXAMPLE_TCP_PORT}`,
+        description: `Loopback TCP, when started with --tcp=${EXAMPLE_TCP_PORT}. Requires the X-Edge-Token header; see securitySchemes.`
+      }
+    ],
+    // Declared, so the published document says what the TCP transport
+    // requires rather than reading as an open port. The unix socket needs
+    // none — its 0600 mode is the check — which is why this is not a
+    // document-wide `security` requirement.
+    security: [{}, { edgeTcpToken: [] }],
+    tags: groups.map(g => ({ name: g.title, description: g.doc })),
+    paths,
+    components: {
+      securitySchemes: {
+        edgeTcpToken: {
+          type: 'apiKey',
+          in: 'header',
+          name: 'X-Edge-Token',
+          description:
+            'The bearer token the engine mints for its loopback TCP listener, written to the `0600` run file at ~/.edge-cli/run/<profile>/engine.json as `tcpToken`. Required on the TCP transport and ignored on the unix socket. A TCP request that also carries `Origin`, or a `Host` other than the bound address, is refused with 403 whatever token it presents.'
+        }
+      },
+      schemas: {
+        // The one schema here that is not derived from a route's cleaners,
+        // because the envelope belongs to no route: it is what *every*
+        // route answers on failure. `src/cli/engine/errors.ts` names the
+        // runtime shape as `ErrorResponse`, and `src/cli/engine/schemas.ts`
+        // says why there is no cleaner for it.
+        ErrorEnvelope: {
+          type: 'object',
+          description: 'Every failure, on both transports.',
+          properties: {
+            error: {
+              type: 'object',
+              properties: {
+                code: { type: 'string' },
+                message: { type: 'string' },
+                status: { type: 'number' },
+                details: {}
+              },
+              required: ['code', 'message', 'status']
+            }
+          },
+          required: ['error']
+        }
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------- CSS
+
+const CSS = fs.readFileSync(path.join(__dirname, 'apiDocs.css'), 'utf8')
+
+// --------------------------------------------------------------------- HTML
+
+function buildHtml(): string {
+  const nav = sections
+    .map(
+      s =>
+        `<div class="s">${esc(s.title)}</div>` +
+        s.groups
+          .map(
+            g =>
+              `<div class="g">${esc(g.title)}</div>` +
+              g.endpoints
+                .map(e => {
+                  const label =
+                    e.cli != null
+                      ? `<code>${esc(e.cli.command)}</code>`
+                      : `<span class="restonly">${esc(e.summary)}</span>`
+                  // Every binding's command and summary go into the search
+                  // text, not just the first: a reader looking for
+                  // `spend-max` found nothing, because the sidebar and the
+                  // index were built from `e.cli` alone.
+                  const alternateText = e.cliExtra
+                    .map(x => `${x.command} ${x.summary ?? ''}`)
+                    .join(' ')
+                  return `<a class="e" href="#${e.id}" data-s="${esc(
+                    (
+                      e.summary +
+                      ' ' +
+                      e.routePath +
+                      ' ' +
+                      (e.cli?.command ?? '') +
+                      ' ' +
+                      alternateText
+                    ).toLowerCase()
+                  )}">${label}</a>`
+                })
+                .join('')
+          )
+          .join('')
+    )
+    .join('')
+
+  const body = sections
+    .map(
+      s => `<h2 id="${s.id}">${esc(s.title)}</h2>
+      ${s.doc !== '' ? `<div class="groupdoc">${mdBlock(s.doc)}</div>` : ''}
+      ${s.groups
+        .map(
+          g => `<h3 class="sub" id="${g.id}">${esc(g.title)}</h3>
+          ${g.doc !== '' ? `<div class="groupdoc">${mdBlock(g.doc)}</div>` : ''}
+          ${g.endpoints.map(endpointHtml).join('')}`
+        )
+        .join('')}`
+    )
+    .join('')
+
+  const errorSection = `<table class="fields"><tbody>${errorCodes
+    .map(
+      e =>
+        `<tr id="err-${e.code}"><td class="k"><code>${e.code}</code></td>
+        <td class="ty"><span class="st">${e.status}</span><span class="dim">${
+          e.origin
+        }</span></td>
+        <td class="doc">${md(e.doc)}${
+          e.details != null
+            ? ` <span class="dim">details: ${md(e.details)}</span>`
+            : ''
+        }</td></tr>`
+    )
+    .join('')}</tbody></table>`
+
+  const exitSection = `<table class="fields"><tbody>${CLI_EXIT_CODES.map(
+    x =>
+      `<tr><td class="k"><code>${
+        x.code
+      }</code></td><td class="ty"><span class="dim">${
+        x.name
+      }</span></td><td class="doc">${md(x.doc)}</td></tr>`
+  ).join('')}</tbody></table>`
+
+  const count = groups.reduce((n, g) => n + g.endpoints.length, 0)
+
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Edge CLI API</title>
+<style>${CSS}</style>
+</head><body>
+<div class="layout">
+<nav>
+  <h1>Edge CLI API</h1>
+  <p class="ver">v${API_VERSION} · ${count} calls</p>
+  <input id="q" type="search" placeholder="Filter…" autocomplete="off">
+  <a class="e" href="#overview"><strong>Overview</strong></a>
+  ${nav}
+  <div class="g">Reference</div>
+  <a class="e" href="#errors">Error codes</a>
+  <a class="e" href="#exit-codes">Exit codes</a>
+</nav>
+<main>
+<h2 id="overview">Overview</h2>
+<div class="groupdoc">${mdBlock(
+    `Every entry is one API call shown twice: as an \`edge-cli\` command, then as the JSON REST request that command sends. Both are generated from a single declaration in \`src/cli/engine/routes/\`, so the two forms cannot drift apart.
+
+Routes are named after the \`edge-core-js\` call they front, kebab-cased: \`context.forgetAccount\` becomes \`POST /forget-account\`, and the command is \`forget-account\`. Parameters carry core's own names. Every entry states its core call, or says why there is none. Only \`GET\` and \`POST\` appear — core has no HTTP verbs, so reads are GET and everything else is POST.
+
+The \`edge-cli\` client is a thin one-shot process. A long-lived \`edge-engine\` daemon owns the \`EdgeContext\` and every logged-in account, serving this API over a Unix socket at \`~/.edge-cli/run/<profile>/engine.sock\`, plus loopback TCP when started with \`--tcp=${EXAMPLE_TCP_PORT}\`.
+
+**There is no transport authentication.** The socket is owner-only (\`0600\`) and TCP is loopback, so anything that can reach the engine can act as every logged-in account.
+
+<a id="object-handles"></a>
+**Ephemeral object handles.** In \`edge-core-js\` a method-bearing value is identified by object reference — you call \`wallet.signTx(tx)\` on the very \`tx\` that \`makeSpend\` returned. That does not survive HTTP, so the engine parks such values under an \`objectId\` with a 5 minute TTL and later steps name the id. Reads do not extend the TTL; only a step that updates the value does. Finishing a workflow, or \`POST …/objects/{objectId}/delete\`, releases the handle early. Expired handles return \`410 OBJECT_EXPIRED\`.
+
+**Serialization.** \`Uint8Array\` becomes base64, \`Date\` becomes an ISO-8601 string, \`Map\` becomes an object, amounts are always decimal strings, and \`EdgeTokenId\` is JSON \`null\` for a native asset.
+
+**Testing.** Always pass \`-t\` / \`--test\` to point at the \`*-tester.edge.app\` servers.`
+  )}</div>
+${body}
+<h2 id="errors">Error codes</h2>
+${errorSection}
+<h2 id="exit-codes">CLI exit codes</h2>
+${exitSection}
+</main>
+</div>
+<script>
+const q = document.getElementById('q')
+const links = [...document.querySelectorAll('nav a.e[data-s]')]
+q.addEventListener('input', () => {
+  const v = q.value.trim().toLowerCase()
+  for (const a of links) a.classList.toggle('hidden', v !== '' && !a.dataset.s.includes(v))
+  for (const g of document.querySelectorAll('nav .g')) {
+    let el = g.nextElementSibling, any = false
+    while (el != null && el.classList.contains('e')) {
+      if (!el.classList.contains('hidden')) any = true
+      el = el.nextElementSibling
+    }
+    g.classList.toggle('hidden', !any)
+  }
+  // A section heading outlives its groups unless it is hidden too.
+  for (const sec of document.querySelectorAll('nav .s')) {
+    let el = sec.nextElementSibling, any = false
+    while (el != null && !el.classList.contains('s')) {
+      if (el.classList.contains('e') && !el.classList.contains('hidden')) any = true
+      el = el.nextElementSibling
+    }
+    sec.classList.toggle('hidden', !any)
+  }
+})
+</script>
+</body></html>`
+}
+
+// ---------------------------------------------------------------------- main
+
+fs.mkdirSync(OUT, { recursive: true })
+const spec = buildOpenApi()
+const html = buildHtml()
+const wroteJson = writeIfChanged(
+  path.join(OUT, 'openapi.json'),
+  JSON.stringify(spec, null, 2) + '\n'
+)
+const wroteHtml = writeIfChanged(path.join(OUT, 'index.html'), html)
+
+const count = groups.reduce((n, g) => n + g.endpoints.length, 0)
+console.log(`✓ ${count} calls in ${groups.length} groups`)
+console.log(
+  `  ${wroteJson ? 'wrote' : 'unchanged'} docs/api/dist/openapi.json  ${
+    (JSON.stringify(spec).length / 1024) | 0
+  } KB`
+)
+console.log(
+  `  ${wroteHtml ? 'wrote' : 'unchanged'} docs/api/dist/index.html    ${
+    (html.length / 1024) | 0
+  } KB`
+)
diff --git a/scripts/buildCliCommands.ts b/scripts/buildCliCommands.ts
new file mode 100644
index 00000000000..8ba122b4372
--- /dev/null
+++ b/scripts/buildCliCommands.ts
@@ -0,0 +1,136 @@
+/**
+ * Generates the CLI's command table from the route declarations.
+ *
+ * A command that only maps arguments onto a request needs no code: its
+ * positional, flags, method and path all come from the route. This emits that
+ * table as JSON, which `src/cli/commands/generated.ts` turns into commands at
+ * startup.
+ *
+ * Commands marked `custom` in their declaration are hand-written, because they
+ * do something the request shape cannot describe — writing export files,
+ * storing a session, holding a stream open.
+ *
+ * The file is committed, so `src/` never depends on `scripts/`.
+ *
+ *   node -r sucrase/register scripts/buildCliCommands.ts
+ */
+import path from 'path'
+
+import type {
+  ArgSpecInput as ArgSpec,
+  CommandSpecInput as CommandSpec
+} from '../src/cli/generatedSchemas'
+import { isJson, usageFor } from './cliUsage'
+import {
+  type ExtractedCli,
+  type ExtractedRoute,
+  extractRoutes,
+  kebab
+} from './extractRoutes'
+import { writeIfChanged } from './writeIfChanged'
+
+const OUT = path.resolve(__dirname, '../src/cli/generated/commands.json')
+
+/**
+ * A JSON blob is anything the caller cannot express as a scalar flag.
+ *
+ * Structured is the default and scalar is the exception, because getting this
+ * backwards is silent: a field whose cleaner names an interface — an
+ * `EdgeMetadataChange` rather than a bare `unknown` — used to fall through to
+ * a string flag, and the engine then received the *text* of the JSON. The
+ * body cleaner rejects that, but a route forwarding the value untouched would
+ * have written the string into a synced file.
+ */
+function kindOf(type: string, required: boolean): ArgSpec['kind'] {
+  const t = type.replace(/ \| (null|undefined)/g, '').trim()
+  // `boolean` now accepts both `--flag` and `--flag=false`, so requiredness
+  // is no longer the thing that decides. `boolstr` stays for a field that
+  // must be sent either way, where a bare `--flag` would be ambiguous about
+  // whether the caller meant to send anything at all.
+  if (t === 'boolean') return required ? 'boolstr' : 'boolean'
+  return isJson(t) ? 'json' : 'string'
+}
+
+function specFor(r: ExtractedRoute, cli: ExtractedCli): CommandSpec {
+  const fields = [
+    ...(r.query ?? []).map(f => ({ f, target: 'query' as const })),
+    ...(r.body ?? []).map(f => ({ f, target: 'body' as const }))
+  ]
+
+  // `{sessionId}` comes from the stored session; any other path parameter is
+  // the command's positional argument. A positional that is also a declared
+  // field is already on the path, so it must not be sent again as a flag.
+  const pathPositional = r.pathParams.find(p => p !== 'sessionId')
+  const args: ArgSpec[] = []
+  for (const { f, target } of fields) {
+    if (f.name === pathPositional) continue
+    const mapped = cli.flags.find(x => x.maps === f.name)
+    args.push({
+      flag: mapped?.name ?? kebab(f.name),
+      field: f.name,
+      target,
+      kind: mapped?.repeat === true ? 'repeat' : kindOf(f.type, !f.optional),
+      required: !f.optional
+    })
+  }
+
+  // `bodyFlag` means one JSON argument *is* the body, so any other declared
+  // field would be silently dropped. Better to fail the build than to send a
+  // request missing a field the route requires.
+  if (cli.bodyFlag != null && args.length > 0) {
+    throw new Error(
+      `${cli.command}: has bodyFlag "${cli.bodyFlag}" and also declares ` +
+        `${args.map(a => a.field).join(', ')}; drop the bodyFlag so every ` +
+        'field gets its own flag'
+    )
+  }
+
+  return {
+    command: cli.command,
+    method: r.method,
+    path: r.routePath,
+    usage: usageFor(r, cli),
+    help: cli.summary ?? r.summary,
+    needsSession: r.pathParams.includes('sessionId'),
+    pathPositional,
+    args: cli.bodyFlag != null ? [] : args,
+    bodyFlag: cli.bodyFlag,
+    preset: Object.keys(cli.preset).length > 0 ? cli.preset : undefined
+  }
+}
+
+const commands: CommandSpec[] = []
+const custom: string[] = []
+for (const r of extractRoutes()) {
+  if (r.isStream) continue
+  for (const cli of [r.cli, ...r.cliExtra]) {
+    if (cli == null) continue
+    if (cli.custom) {
+      custom.push(cli.command)
+      continue
+    }
+    if (commands.some(c => c.command === cli.command)) {
+      throw new Error(
+        `Command "${cli.command}" is declared on more than one route. ` +
+          'Mark it `custom: true` and hand-write the dispatch.'
+      )
+    }
+    commands.push(specFor(r, cli))
+  }
+}
+commands.sort((a, b) => a.command.localeCompare(b.command))
+
+const payload = {
+  $comment:
+    'GENERATED FILE — DO NOT EDIT. Produced by scripts/buildCliCommands.ts ' +
+    'from the route declarations in src/cli/engine/routes. Commands marked ' +
+    '`custom: true` in a declaration are hand-written instead; see ' +
+    'src/cli/commands/.',
+  commands
+}
+
+const changed = writeIfChanged(OUT, JSON.stringify(payload, null, 2) + '\n')
+console.log(
+  `${changed ? '✓ wrote' : '· unchanged'} src/cli/generated/commands.json ` +
+    `(${commands.length} generated, ${custom.length} hand-written)`
+)
diff --git a/scripts/buildCliHelp.ts b/scripts/buildCliHelp.ts
new file mode 100644
index 00000000000..4204eee303e
--- /dev/null
+++ b/scripts/buildCliHelp.ts
@@ -0,0 +1,134 @@
+/**
+ * Generates the CLI's runtime help text from the route declarations.
+ *
+ * JSDoc is erased at compile time, so `edge-cli help <command>` cannot read it
+ * directly. This lifts the prose out of `src/cli/engine/routes/*.ts` into a
+ * committed JSON file that the CLI imports, keeping a single copy of every
+ * sentence: the declaration itself.
+ *
+ * The file is committed, so a fresh clone runs without ever executing this —
+ * `src/` never depends on `scripts/`. Regenerated by `npm run prepare`.
+ *
+ *   node -r sucrase/register scripts/buildCliHelp.ts
+ */
+import path from 'path'
+
+import type {
+  CommandHelpInput as CommandHelp,
+  ParamHelpInput as ParamHelp
+} from '../src/cli/generatedSchemas'
+import { passForm, usageFor } from './cliUsage'
+import {
+  type ExtractedCli,
+  type ExtractedRoute,
+  extractRoutes
+} from './extractRoutes'
+import { writeIfChanged } from './writeIfChanged'
+
+const OUT = path.resolve(__dirname, '../src/cli/generated/helpDocs.json')
+
+function helpFor(r: ExtractedRoute, cli: ExtractedCli): CommandHelp {
+  const entry: CommandHelp = {
+    summary: cli.summary ?? r.summary,
+    method: r.method,
+    path: r.routePath,
+    usage: usageFor(r, cli)
+  }
+  if (r.description != null) entry.description = r.description
+  if (r.core != null) entry.core = r.core
+
+  const params: Record<string, ParamHelp> = {}
+  for (const f of [...(r.query ?? []), ...(r.body ?? [])]) {
+    params[f.name] = {
+      pass: passForm(cli, f),
+      doc: f.doc,
+      optional: f.optional
+    }
+  }
+  for (const x of cli.extra) {
+    params[x.name] = {
+      pass: x.kind === 'boolean' ? `--${x.name}` : `--${x.name}=<value>`,
+      doc: x.doc,
+      optional: x.required !== true
+    }
+  }
+  if (Object.keys(params).length > 0) entry.params = params
+
+  if (r.returns != null && r.returns.length > 0) {
+    entry.returns = Object.fromEntries(
+      r.returns.map(f => [
+        f.name + (f.optional ? '?' : ''),
+        f.doc != null ? `${f.type} — ${f.doc}` : f.type
+      ])
+    )
+  } else if (r.returnsType != null && r.returnsType !== 'unknown') {
+    entry.returns = { '': r.returnsType }
+  }
+  const returnsProse = r.returnsProse ?? r.returnsDoc
+  if (returnsProse != null) entry.returnsDoc = returnsProse
+
+  const notes = [...r.notes]
+  if (cli.notes != null) notes.push(cli.notes)
+  if (notes.length > 0) entry.notes = notes
+  if (r.errors.length > 0) entry.errors = r.errors
+  return entry
+}
+
+const commands: Record<string, CommandHelp> = {}
+for (const r of extractRoutes()) {
+  for (const cli of [r.cli, ...r.cliExtra]) {
+    if (cli == null) continue
+    const entry = helpFor(r, cli)
+    const existing = commands[cli.command]
+    if (existing == null) {
+      commands[cli.command] = entry
+      continue
+    }
+    // Two routes can share a command name — `local-settings` reads on GET and
+    // writes on POST. Keeping only the last one meant `help local-settings`
+    // showed the write usage alone, so the read form looked invalid. Merge
+    // both, so every form the command accepts is described: its usage line,
+    // its REST route, the fields a caller can send and what comes back.
+    existing.alsoUsage = [...(existing.alsoUsage ?? []), entry.usage]
+    existing.alsoRest = [
+      ...(existing.alsoRest ?? []),
+      `${entry.method} ${entry.path}`
+    ]
+    existing.description = [
+      existing.description,
+      `${entry.summary} ${entry.description ?? ''}`.trim()
+    ]
+      .filter(part => part != null && part !== '')
+      .join('\n\n')
+    if (entry.params != null) {
+      existing.params = { ...(existing.params ?? {}), ...entry.params }
+    }
+    if (entry.returns != null) {
+      existing.returns = { ...(existing.returns ?? {}), ...entry.returns }
+    }
+    if (entry.errors != null) {
+      existing.errors = [
+        ...new Set([...(existing.errors ?? []), ...entry.errors])
+      ]
+    }
+  }
+}
+
+const payload = {
+  $comment:
+    'GENERATED FILE — DO NOT EDIT. Produced by scripts/buildCliHelp.ts from ' +
+    'the route declarations in src/cli/engine/routes. Edit the declaration, ' +
+    'then run `npm run prepare` (or `npm run docs:api`).',
+  commands: Object.fromEntries(
+    Object.keys(commands)
+      .sort((a, b) => a.localeCompare(b))
+      .map(k => [k, commands[k]])
+  )
+}
+
+const changed = writeIfChanged(OUT, JSON.stringify(payload, null, 2) + '\n')
+const count = Object.keys(commands).length
+console.log(
+  `${changed ? '✓ wrote' : '· unchanged'} src/cli/generated/helpDocs.json ` +
+    `(${count} command${count === 1 ? '' : 's'})`
+)
diff --git a/scripts/buildNodeApiSigner.sh b/scripts/buildNodeApiSigner.sh
new file mode 100755
index 00000000000..fb25d129091
--- /dev/null
+++ b/scripts/buildNodeApiSigner.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Generate secret shards from edgeKey.json and build the Node N-API Edge API
+# HMAC signer. Requires a real apiSecret — refuses to link a stub addon.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+if [ ! -f edgeKey.json ]; then
+  echo "error: edgeKey.json required to build the Node API signer" >&2
+  exit 1
+fi
+
+node -r sucrase/register ./scripts/makeApiSigner.ts
+
+NODE_DIR=native/edge-api-signer/node
+if [ ! -f "$NODE_DIR/edge_api_secret.c" ]; then
+  echo "error: $NODE_DIR/edge_api_secret.c missing (edgeKey.json apiSecret required)" >&2
+  exit 1
+fi
+
+(
+  cd "$NODE_DIR"
+  node ../../../node_modules/node-gyp/bin/node-gyp.js configure
+  node ../../../node_modules/node-gyp/bin/node-gyp.js build
+)
+
+echo "built $NODE_DIR/build/Release/edge_api_signer.node"
diff --git a/scripts/checkCliCoverage.ts b/scripts/checkCliCoverage.ts
new file mode 100644
index 00000000000..b274508d990
--- /dev/null
+++ b/scripts/checkCliCoverage.ts
@@ -0,0 +1,113 @@
+/**
+ * Which commands no automated test ever runs.
+ *
+ * Live coverage was about half the surface until the fake world existed, and
+ * the only way anyone knew that was by counting by hand. This counts instead,
+ * and fails on a command that nothing exercises unless it is listed below with
+ * a reason.
+ */
+import fs from 'fs'
+import path from 'path'
+
+import { asCommandsTableJson } from '../src/cli/generatedSchemas'
+
+const ROOT = path.resolve(__dirname, '..')
+
+/**
+ * Commands no automated suite exercises, and why.
+ *
+ * These reach a third party the suites cannot stand in for, so they have no
+ * coverage at all — not in `test:cli:offline` and not in `test:cli:network`,
+ * whose three suites do not mention any of them. The excuse is recorded here
+ * so the gate's own output says that plainly rather than implying a script
+ * covers them.
+ */
+const NETWORK_ONLY: Record<string, string> = {
+  'rates-query': 'Hits the live rates server; no suite covers it.',
+  'rates-usd-to-native': 'Hits the live rates server; no suite covers it.',
+  'fetch-swap-quotes':
+    'Polls the swap providers and needs funded wallets; no suite covers it.',
+  'get-payment-protocol-info':
+    'Fetches a BIP70 request from a merchant; no suite covers it.'
+}
+
+// Cleaned on load, through the writer's own cleaner: a second hand-written
+// shape with a cast is what lets a reader and the writer part ways, which is
+// the drift this gate is here to notice.
+const generated = asCommandsTableJson(
+  fs.readFileSync(path.join(ROOT, 'src/cli/generated/commands.json'), 'utf8')
+)
+
+const commands = new Set(generated.commands.map(c => c.command))
+const handDir = path.join(ROOT, 'src/cli/commands')
+for (const file of fs.readdirSync(handDir)) {
+  const text = fs.readFileSync(path.join(handDir, file), 'utf8')
+  for (const m of text.matchAll(/\bcommand\(\s*'([a-z0-9-]+)'/g)) {
+    commands.add(m[1])
+  }
+}
+
+const tests = ['scripts/testCliFake.ts', 'scripts/testCliSubscribe.ts']
+  .map(f => fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  .join('\n')
+
+/**
+ * Commands the offline suites actually invoke.
+ *
+ * Read from the call sites, not from every quoted string in the file: the
+ * helpers each take the command name at a known position, so
+ *   ok('label', 'command', …)
+ *   refuses('label', 'CODE', 'command', …)
+ *   refusesInternal('label', 'message', 'command', …)
+ *   notInFakeWorld('label', 'marker', 'command', …)
+ *   cli('command', …)
+ * A bare scan counted labels, comments, URL fragments and unrelated literals,
+ * so a command that was merely mentioned passed the gate. This can still
+ * under-count — a command invoked through a variable is invisible — which is
+ * the safe direction for a coverage gate to be wrong in.
+ */
+const CALL_SITES: Array<[RegExp, number]> = [
+  [/\bok\(\s*'[^']*'\s*,\s*'([a-z0-9-]+)'/g, 1],
+  [/\brefuses\(\s*'[^']*'\s*,\s*'[^']*'\s*,\s*'([a-z0-9-]+)'/g, 1],
+  [/\brefusesInternal\(\s*'[^']*'\s*,\s*'[^']*'\s*,\s*'([a-z0-9-]+)'/g, 1],
+  [/\bnotInFakeWorld\(\s*'[^']*'\s*,\s*'[^']*'\s*,\s*'([a-z0-9-]+)'/g, 1],
+  [/\bcli\(\s*'([a-z0-9-]+)'/g, 1],
+  // testCliSubscribe spawns the held-open command as a child process rather
+  // than through a helper: spawn('node', [...CLI, ...BASE, 'subscribe'], …)
+  [/\bspawn(?:Sync)?\(\s*'node'[^)]*?'([a-z0-9-]+)'\s*\]/g, 1]
+]
+const run = new Set<string>()
+for (const [pattern, group] of CALL_SITES) {
+  for (const m of tests.matchAll(pattern)) run.add(m[group])
+}
+
+const missing: string[] = []
+const stale: string[] = []
+for (const name of [...commands].sort()) {
+  const covered = run.has(name)
+  const excused = NETWORK_ONLY[name] != null
+  if (!covered && !excused) missing.push(name)
+  if (covered && excused) stale.push(name)
+}
+
+const offline = [...commands].filter(c => run.has(c)).length
+if (missing.length > 0 || stale.length > 0) {
+  console.error('✗ CLI coverage:\n')
+  for (const name of missing) {
+    console.error(
+      `  ${name}: no offline test runs it. Add one to testCliFake.ts, or ` +
+        'list it in NETWORK_ONLY with the reason it cannot run offline.'
+    )
+  }
+  for (const name of stale) {
+    console.error(
+      `  ${name}: listed as network-only, but an offline test runs it. ` +
+        'Remove the entry.'
+    )
+  }
+  process.exit(1)
+}
+console.log(
+  `✓ ${offline}/${commands.size} commands run offline ` +
+    `(${Object.keys(NETWORK_ONLY).length} need the network)`
+)
diff --git a/scripts/checkCoreAlignment.ts b/scripts/checkCoreAlignment.ts
new file mode 100644
index 00000000000..e99b586c617
--- /dev/null
+++ b/scripts/checkCoreAlignment.ts
@@ -0,0 +1,155 @@
+/**
+ * Compare each route's request against the core call it fronts.
+ *
+ * `verifyApiDocs` only checks that the core member exists by name, which is
+ * how `currency-wallets` came to carry a `waitForAll` parameter that
+ * `account.currencyWallets` does not have — it is a property, and waiting is a
+ * separate method. This resolves the real signature and compares names.
+ */
+import path from 'path'
+import ts from 'typescript'
+
+import { extractRoutes } from './extractRoutes'
+
+const CORE = path.resolve(
+  __dirname,
+  '../node_modules/edge-core-js/src/types/types.ts'
+)
+
+/** Which core interface a `core:` prefix refers to. */
+const INTERFACES: Record<string, string> = {
+  context: 'EdgeContext',
+  account: 'EdgeAccount',
+  wallet: 'EdgeCurrencyWallet',
+  'account.dataStore': 'EdgeDataStore',
+  EdgeSwapQuote: 'EdgeSwapQuote',
+  EdgeLoginRequest: 'EdgeLoginRequest',
+  EdgePendingEdgeLogin: 'EdgePendingEdgeLogin'
+}
+
+const program = ts.createProgram([CORE], {
+  target: ts.ScriptTarget.ES2020,
+  moduleResolution: ts.ModuleResolutionKind.NodeJs
+})
+const checker = program.getTypeChecker()
+const source = program.getSourceFile(CORE)
+if (source == null) throw new Error(`Cannot read ${CORE}`)
+
+/** Every named interface in core's public types. */
+const interfaces = new Map<string, ts.InterfaceDeclaration>()
+source.forEachChild(node => {
+  if (ts.isInterfaceDeclaration(node)) interfaces.set(node.name.text, node)
+})
+
+/**
+ * Property names a type exposes, for an options object.
+ *
+ * Primitives are skipped: asking a `string` for its properties yields
+ * `charAt`, `toUpperCase` and forty more, none of which is a parameter.
+ */
+function paramNames(type: ts.Type): Set<string> {
+  const out = new Set<string>()
+  const objectish =
+    (type.flags & ts.TypeFlags.Object) !== 0 ||
+    (type.isUnionOrIntersection() &&
+      type.types.some(t => (t.flags & ts.TypeFlags.Object) !== 0))
+  if (!objectish) return out
+  // An array or a typed array is a value, not a bag of named options.
+  const name = checker.typeToString(type)
+  if (/\[\]$|^(Array|Uint8Array|Promise)\b/.test(name)) return out
+  for (const prop of checker.getPropertiesOfType(type)) {
+    if (prop.name.startsWith('__@')) continue
+    out.add(prop.name)
+  }
+  return out
+}
+
+interface Signature {
+  kind: 'method' | 'property'
+  params: Set<string>
+}
+
+function signatureOf(coreCall: string): Signature | null {
+  const parts = coreCall.split('.')
+  const member = parts.pop() ?? ''
+  const owner = INTERFACES[parts.join('.')] ?? INTERFACES[parts[0]]
+  const decl = owner != null ? interfaces.get(owner) : undefined
+  if (decl == null) return null
+
+  for (const m of decl.members) {
+    if (m.name?.getText() !== member) continue
+    // Core writes its methods as properties holding function types
+    // (`changePassword: (opts: …) => Promise<void>`), so asking the type for
+    // its call signatures is what distinguishes a method from a real property.
+    const type = checker.getTypeAtLocation(m)
+    const calls = type.getCallSignatures()
+    if (calls.length === 0) return { kind: 'property', params: new Set() }
+
+    const params = new Set<string>()
+    for (const p of calls[0].getParameters()) {
+      const pType = checker.getTypeOfSymbolAtLocation(p, m)
+      const inner = paramNames(pType)
+      // A parameter that is an object of options contributes its properties;
+      // the parameter's own name is not something a caller ever sends.
+      if (inner.size > 0) {
+        for (const n of inner) params.add(n)
+      }
+      params.add(p.name)
+    }
+    return { kind: 'method', params }
+  }
+  return null
+}
+
+// Scope, not arguments: these identify the receiver, not what is passed to it.
+const SCOPE = new Set(['sessionId', 'walletId', 'objectId', 'pendingId'])
+
+let checked = 0
+const problems: string[] = []
+for (const r of extractRoutes()) {
+  if (r.core == null || r.core.includes('$internalStuff')) continue
+  const sig = signatureOf(r.core)
+  if (sig == null) continue
+  checked++
+
+  const declared = [...(r.query ?? []), ...(r.body ?? [])]
+    .map(f => f.name)
+    .filter(n => !SCOPE.has(n))
+
+  const extra =
+    sig.kind === 'property'
+      ? declared
+      : declared.filter(n => !sig.params.has(n))
+  const takes =
+    sig.kind === 'property'
+      ? 'nothing — it is a property, not a method'
+      : [...sig.params].join(', ')
+
+  for (const name of extra) {
+    if (r.coreExtra[name] == null) {
+      problems.push(
+        `${r.id}: ${r.core} has no parameter "${name}". Drop it, or record ` +
+          `in \`coreExtra\` why it exists. Core takes: ${takes}`
+      )
+    }
+  }
+  // A justification that no longer applies is worse than none: it claims a
+  // difference was weighed when the difference is gone.
+  for (const name of Object.keys(r.coreExtra)) {
+    if (!extra.includes(name)) {
+      problems.push(
+        `${r.id}: coreExtra lists "${name}", which is not a divergence any ` +
+          'more. Remove the entry.'
+      )
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✗ ${problems.length} core-alignment problem(s):\n`)
+  for (const p of problems) console.error(`  ${p}`)
+  process.exit(1)
+}
+console.log(
+  `✓ ${checked} routes match their core signature, ` + `or say why they differ`
+)
diff --git a/scripts/checkRouteContracts.ts b/scripts/checkRouteContracts.ts
new file mode 100644
index 00000000000..8899664f258
--- /dev/null
+++ b/scripts/checkRouteContracts.ts
@@ -0,0 +1,181 @@
+/**
+ * Checks each route declaration against itself and against its handler.
+ *
+ * `verifyApiDocs` compares the surface — routes, commands, flags, core names.
+ * This checks the contract: that every field a caller can send is described,
+ * that nothing described has gone away, and that a handler does not read a
+ * field its cleaner would have stripped.
+ *
+ *   node -r sucrase/register scripts/checkRouteContracts.ts
+ */
+import fs from 'fs'
+import path from 'path'
+
+import { errorCodes } from '../docs/api/shared'
+import { extractRoutes } from './extractRoutes'
+
+const ROOT = path.resolve(__dirname, '..')
+const ROUTES = path.join(ROOT, 'src/cli/engine/routes')
+
+/** Source of every route declaration's handler, keyed by `METHOD path`. */
+function handlerSources(): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const name of fs.readdirSync(ROUTES)) {
+    if (!name.endsWith('.ts') || name === 'index.ts' || name === 'helpers.ts') {
+      continue
+    }
+    const src = fs.readFileSync(path.join(ROUTES, name), 'utf8')
+    const re =
+      /\broute\(\{([\s\S]*?\bmethod:\s*'([A-Z]+)',\s*\n?\s*path:\s*'([^']+)'[\s\S]*?)\n\}\)/g
+    let m: RegExpExecArray | null
+    while ((m = re.exec(src)) != null) out.set(`${m[2]} ${m[3]}`, m[1])
+  }
+  return out
+}
+
+/** Fields a handler pulls off `ctx.body` or the validated query. */
+function readsFrom(fn: string, source: 'body' | 'query'): Set<string> {
+  const out = new Set<string>()
+  const base = source === 'body' ? 'ctx\\.body' : 'ctx\\.query\\.valid'
+  for (const m of fn.matchAll(new RegExp(`${base}\\.([a-zA-Z_][\\w]*)`, 'g'))) {
+    out.add(m[1])
+  }
+  // Destructured: `const { a, b } = ctx.body`
+  for (const m of fn.matchAll(
+    new RegExp(`const \\{([^}]*)\\} = ${base}\\b`, 'g')
+  )) {
+    for (const part of m[1].split(',')) {
+      // `{ filter = 'active' }` and `{ tokenId: id }` both name one field.
+      const name = part.split(':')[0].split('=')[0].trim()
+      if (name !== '') out.add(name)
+    }
+  }
+  return out
+}
+
+const handlers = handlerSources()
+const problems: string[] = []
+let described = 0
+let total = 0
+
+for (const r of extractRoutes()) {
+  const fields = [...(r.query ?? []), ...(r.body ?? [])]
+  const names = new Set(fields.map(f => f.name))
+
+  // Every field a caller can send needs a description, beside the field.
+  for (const field of fields) {
+    if (field.doc == null) {
+      problems.push(
+        `${r.id}: field "${field.name}" has no description — wrap it as ` +
+          `doc(cleaner, '…')`
+      )
+    }
+  }
+
+  // A handler must not read a field its cleaner would have stripped.
+  const fn = handlers.get(`${r.method} ${r.routePath}`)
+  if (fn != null) {
+    for (const name of readsFrom(fn, 'body')) {
+      if (r.body != null && !names.has(name)) {
+        problems.push(
+          `${r.id}: handler reads ctx.body.${name}, absent from the body cleaner`
+        )
+      }
+    }
+    for (const name of readsFrom(fn, 'query')) {
+      if (!names.has(name)) {
+        problems.push(
+          `${r.id}: handler reads query "${name}", absent from the query cleaner`
+        )
+      }
+    }
+
+    // A route that declares a query cleaner must read the cleaned result. A
+    // handler that re-parses the raw URLSearchParams gets whatever the caller
+    // sent, so the declared type stops being the enforced type — which is how
+    // `waitForAll` came to be documented as a string while the command wanted
+    // a switch.
+    if (r.query != null) {
+      const raw =
+        /\b(optionalQuery(String|Int|Date|Boolean)|requireQuery(String|Int)|ctx\.query\.(get|has))\b/.exec(
+          fn
+        )
+      if (raw != null) {
+        problems.push(
+          `${r.id}: handler calls ${raw[1]} on the raw query; read ` +
+            'ctx.query.valid instead, so the declared cleaner is what runs'
+        )
+      }
+    }
+  }
+
+  // Error codes must exist in the catalogue.
+  const known = new Set(errorCodes.map(e => e.code))
+  for (const code of r.errors) {
+    if (!known.has(code)) {
+      problems.push(`${r.id}: lists error "${code}", absent from the catalogue`)
+    }
+  }
+
+  described += (r.returns ?? []).filter(f => f.doc != null).length
+  total += (r.returns ?? []).length
+}
+
+// ---------------------------------------------------------------------------
+// Every code the CLI can emit, against the catalogue — in both directions.
+//
+// The existing check above is one-way: a code a route *declares* has to be in
+// the catalogue. That let the program emit conditions the catalogue had no way
+// to describe. `ENGINE_UNAVAILABLE` and `USAGE` are the ones that got through:
+// the client writes them to stderr on the most common failure a first-time
+// user meets, and neither appeared in `errorCodes`, in the HTML reference, in
+// the OpenAPI document or in the guide — so the exit-7 row described the
+// condition in prose while withholding the code a program would match on.
+//
+// Scanned from the source rather than the declarations, because a code the
+// client invents never passes through a route.
+// ---------------------------------------------------------------------------
+{
+  const cliDirs = ['src/cli']
+  const emitted = new Set<string>()
+  const walk = (dir: string): void => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name === 'generated') continue
+        walk(full)
+        continue
+      }
+      if (!entry.name.endsWith('.ts')) continue
+      const text = fs.readFileSync(full, 'utf8')
+      // `engineError('CODE'`, and `code: 'CODE'` in an envelope literal.
+      for (const m of text.matchAll(/engineError\(\s*'([A-Z][A-Z0-9_]*)'/g)) {
+        emitted.add(m[1])
+      }
+      for (const m of text.matchAll(/\bcode: '([A-Z][A-Z0-9_]*)'/g)) {
+        emitted.add(m[1])
+      }
+    }
+  }
+  for (const dir of cliDirs) walk(path.join(ROOT, dir))
+
+  const known = new Set(errorCodes.map(e => e.code))
+  for (const code of [...emitted].sort()) {
+    if (!known.has(code)) {
+      problems.push(
+        `src/cli emits error code "${code}", which is absent from the ` +
+          'catalogue in docs/api/shared.ts — a code a caller cannot look up'
+      )
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✗ ${problems.length} contract problem(s):\n`)
+  for (const p of problems) console.error(`  ${p}`)
+  process.exit(1)
+}
+console.log(
+  `✓ contracts hold across ${handlers.size} declarations ` +
+    `(${described}/${total} response fields carry prose)`
+)
diff --git a/scripts/cliNodeSafeSmoke.js b/scripts/cliNodeSafeSmoke.js
new file mode 100644
index 00000000000..7fa1c771523
--- /dev/null
+++ b/scripts/cliNodeSafeSmoke.js
@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Pre-commit / CI smoke: ensure CLI-shared GUI modules stay Node-loadable
+ * (no react-native* on the require graph) and the CLI entry parses.
+ *
+ * Usage: node scripts/cliNodeSafeSmoke.js
+ */
+'use strict'
+
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+const root = path.join(__dirname, '..')
+
+const SHARED_MODULES = [
+  'src/util/fiatConstants.ts',
+  'src/util/network.ts',
+  'src/util/utils.ts',
+  'src/util/exchangeRates.ts',
+  'src/locales/strings.ts',
+  'src/locales/intl.ts',
+  'src/locales/bootLocale.ts',
+  'src/locales/nodeLocale.ts',
+  'src/cli/bootNodeLocale.ts',
+  'src/util/txDisplay/index.ts',
+  'src/util/localAccountSettings.ts',
+  'src/util/spamThreshold.ts',
+  'src/util/txTagging/index.ts',
+  'src/util/exchangeDenom.ts',
+  'src/util/fillTxsFiat.ts',
+  'src/util/txExport/index.ts',
+  'src/util/exportTxInfo.ts',
+  'src/cli/engine/routes/rates.ts',
+  'src/cli/engine/nodeApiSigner.ts',
+  'src/util/keysServer.ts',
+  'src/cli/engine/fetchPluginKeys.ts',
+  'src/cli/engine/makeCoreContext.ts'
+]
+
+const CHILD_TIMEOUT_MS = 60_000
+
+/**
+ * A child killed by a signal (segfault in the native addon, OOM, timeout)
+ * reports `status: null`, so the exit code has to be derived rather than
+ * forwarded — `process.exit(null)` would exit 0 and pass the gate.
+ */
+function failIfUnsuccessful(result, label) {
+  if (result.error == null && result.signal == null && result.status === 0) {
+    return
+  }
+  console.error(`FAIL ${label}`)
+  const out = `${result.stdout || ''}${result.stderr || ''}`.trim()
+  if (out !== '') console.error(out)
+  if (result.error != null)
+    console.error(`spawn error: ${result.error.message}`)
+  if (result.signal != null) console.error(`killed by signal: ${result.signal}`)
+  process.exit(
+    typeof result.status === 'number' && result.status !== 0 ? result.status : 1
+  )
+}
+
+function assertNodeSafe(relPath) {
+  const abs = path.join(root, relPath)
+  const probe = `
+const Module = require('module')
+const orig = Module._load
+Module._load = function (request, parent, isMain) {
+  const id = request
+  if (
+    id === 'react-native' ||
+    id.startsWith('react-native/') ||
+    id.startsWith('react-native-') ||
+    id === '@sentry/react-native' ||
+    id.startsWith('@react-native')
+  ) {
+    const from = parent && parent.filename ? parent.filename : '(unknown)'
+    const err = new Error('RN_LEAK ' + id + ' from ' + from)
+    err.code = 'RN_LEAK'
+    throw err
+  }
+  return orig.apply(this, arguments)
+}
+require(${JSON.stringify(abs)})
+console.log('OK ' + ${JSON.stringify(relPath)})
+`
+  const result = spawnSync(
+    process.execPath,
+    ['-r', 'sucrase/register', '-e', probe],
+    {
+      cwd: root,
+      encoding: 'utf8',
+      env: process.env,
+      timeout: CHILD_TIMEOUT_MS
+    }
+  )
+  failIfUnsuccessful(result, relPath)
+  process.stdout.write(result.stdout || '')
+}
+
+function assertCliHelp() {
+  const result = spawnSync(
+    process.execPath,
+    ['-r', 'sucrase/register', 'src/cli/index.ts', '--help'],
+    { cwd: root, encoding: 'utf8', env: process.env, timeout: CHILD_TIMEOUT_MS }
+  )
+  failIfUnsuccessful(result, 'cli --help')
+  console.log('OK cli --help')
+}
+
+console.log('cliNodeSafeSmoke: checking shared modules…')
+for (const mod of SHARED_MODULES) {
+  assertNodeSafe(mod)
+}
+console.log('cliNodeSafeSmoke: checking CLI entry…')
+assertCliHelp()
+console.log('cliNodeSafeSmoke: all checks passed')
diff --git a/scripts/cliUsage.ts b/scripts/cliUsage.ts
new file mode 100644
index 00000000000..36e8e611325
--- /dev/null
+++ b/scripts/cliUsage.ts
@@ -0,0 +1,120 @@
+/**
+ * How a command is typed, derived from its route declaration.
+ *
+ * There were three copies of this: one for the command table the CLI runs on,
+ * one for `help`, and one for the HTML reference. They drifted, which is how
+ * `local-settings` came to document `--spam-filter-on=<spamFilterOn>` in the
+ * reference while `help` correctly said `--spam-filter-on=true|false`. One
+ * function means they cannot disagree again.
+ */
+import {
+  type ExtractedCli,
+  type ExtractedField,
+  type ExtractedRoute,
+  kebab
+} from './extractRoutes'
+
+/** The declared type, with the optional/null wrappers taken off. */
+function bareType(type: string): string {
+  return type.replace(/ \| (null|undefined)/g, '').trim()
+}
+
+/**
+ * The allowed values, when the declared type is a union of literals.
+ *
+ * `asValue('active', 'archived', …)` resolves to `"active" | "archived" | …`,
+ * which is exactly the list a reader wants in the usage line. Rendering it as
+ * `<value>` throws away something the declaration already knows.
+ */
+function literalChoices(type: string): string | null {
+  const parts = bareType(type)
+    .split('|')
+    .map(p => p.trim())
+  if (parts.length < 2) return null
+  if (!parts.every(p => /^(['"]).*\1$/.test(p))) return null
+  return parts.map(p => p.slice(1, -1)).join('|')
+}
+
+/**
+ * True for a field the command takes as a bare switch.
+ *
+ * Only an optional boolean qualifies, and `commandArgs` accepts `=false` for
+ * one of those too — so the usage line says `[--flag[=false]]` rather than a
+ * bare `[--flag]`. For `spend`'s `broadcast` and `save` the bare form is
+ * inert (both default to true server-side), so advertising only that form
+ * left no discoverable way to reach a sign-only or a no-save spend and
+ * `edge-cli help spend` showed a flag that did nothing.
+ */
+function isSwitch(field: ExtractedField): boolean {
+  return field.optional && bareType(field.type) === 'boolean'
+}
+
+/**
+ * Whether a field has to be passed as a JSON argument.
+ *
+ * Structured is the default and scalar is the exception, because getting this
+ * backwards is silent: a field whose cleaner names an interface — an
+ * `EdgeMetadataChange` rather than a bare `unknown` — used to fall through to
+ * a plain string flag and the engine received the *text* of the JSON.
+ *
+ * `buildCliCommands` picks a flag's `kind` from this, so the generated usage
+ * line and the generated parser cannot disagree.
+ */
+export function isJson(type: string): boolean {
+  const t = bareType(type)
+  // A union of string literals is still one word on the command line.
+  if (/^"[^"]*"( \| "[^"]*")*$/.test(t)) return false
+  return t !== 'string' && t !== 'number' && t !== 'boolean' && t !== 'Date'
+}
+
+/**
+ * What a field's value looks like on the command line.
+ *
+ * The placeholder names the field rather than saying `<value>`, so a usage
+ * line reads as something a person could type. Where the declaration knows
+ * the exact values — a boolean, or a union of literals — it says them.
+ */
+function valueForm(field: ExtractedField): string {
+  if (bareType(field.type) === 'boolean') return 'true|false'
+  const choices = literalChoices(field.type)
+  if (choices != null) return choices
+  if (isJson(field.type)) return "'<json>'"
+  return `<${field.name}>`
+}
+
+/** How one request field is supplied on the command line. */
+export function passForm(cli: ExtractedCli, field: ExtractedField): string {
+  // A positional rides on the path, so it is typed bare, not as a flag.
+  if (cli.positional === field.name) return `<${field.name}>`
+  const mapped = cli.flags.find(f => f.maps === field.name)
+  const name = mapped?.name ?? kebab(field.name)
+  const token = isSwitch(field)
+    ? `--${name}[=false]`
+    : mapped?.repeat === true
+    ? `--${name}=<${field.name}> …`
+    : `--${name}=${valueForm(field)}`
+  return field.optional ? `[${token}]` : token
+}
+
+/** The full usage line: command, positional, then every named argument. */
+export function usageFor(r: ExtractedRoute, cli: ExtractedCli): string {
+  const parts = [cli.command]
+  // A positional is a path parameter, so the path is the single source for
+  // it; `cli.positional` only names which field it carries.
+  for (const p of r.pathParams) if (p !== 'sessionId') parts.push(`<${p}>`)
+  for (const f of [...(r.query ?? []), ...(r.body ?? [])]) {
+    if (r.pathParams.includes(f.name)) continue
+    // A field this binding presets is not the caller's to pass: the preset
+    // is the whole reason the alias exists. `spend-max` advertised
+    // `[--use-max]`, and because `generated.ts` applies the preset *before*
+    // the flags, `spend-max --use-max=false` was accepted and silently
+    // became a plain `spend`.
+    if (Object.prototype.hasOwnProperty.call(cli.preset, f.name)) continue
+    parts.push(passForm(cli, f))
+  }
+  for (const x of cli.extra) {
+    const token = x.kind === 'boolean' ? `--${x.name}` : `--${x.name}=<value>`
+    parts.push(x.required === true ? token : `[${token}]`)
+  }
+  return parts.join(' ')
+}
diff --git a/scripts/engineRequest.ts b/scripts/engineRequest.ts
new file mode 100644
index 00000000000..6bb9d25fb86
--- /dev/null
+++ b/scripts/engineRequest.ts
@@ -0,0 +1,59 @@
+/**
+ * One raw HTTP client for the test scripts.
+ *
+ * `testCliCaptcha` and `testEdgeLogin` each carried a byte-identical
+ * forty-line copy of this, and `testCli` a third variant. They need the raw
+ * status and body — `ApiClient` throws on a 4xx, which is exactly what these
+ * scripts are asserting — so they cannot simply use the client; one copy
+ * here is the next best thing.
+ */
+import http from 'http'
+
+export interface RawResponse {
+  status: number
+  json: any
+}
+
+export async function engineRequest(
+  socketPath: string,
+  method: string,
+  urlPath: string,
+  body?: unknown
+): Promise<RawResponse> {
+  const payload =
+    body === undefined ? undefined : Buffer.from(JSON.stringify(body))
+  return await new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        method,
+        path: urlPath,
+        socketPath,
+        headers: {
+          Accept: 'application/json',
+          ...(payload != null
+            ? {
+                'Content-Type': 'application/json',
+                'Content-Length': String(payload.length)
+              }
+            : {})
+        }
+      },
+      res => {
+        const chunks: Buffer[] = []
+        res.on('data', (chunk: Buffer) => {
+          chunks.push(chunk)
+        })
+        res.on('end', () => {
+          const raw = Buffer.concat(chunks).toString('utf8')
+          resolve({
+            status: res.statusCode ?? 0,
+            json: raw === '' ? undefined : JSON.parse(raw)
+          })
+        })
+      }
+    )
+    req.on('error', reject)
+    if (payload != null) req.write(payload)
+    req.end()
+  })
+}
diff --git a/scripts/extractRoutes.ts b/scripts/extractRoutes.ts
new file mode 100644
index 00000000000..094fc1eb481
--- /dev/null
+++ b/scripts/extractRoutes.ts
@@ -0,0 +1,862 @@
+/**
+ * Reads route declarations out of `src/cli/engine/routes/*.ts`.
+ *
+ * The JSDoc above each `route(…)` is the prose; the `query`, `body` and
+ * `returns` cleaners are the shapes, resolved through the TypeScript checker
+ * so the documented type is literally the validator's type.
+ */
+import fs from 'fs'
+import path from 'path'
+import ts from 'typescript'
+
+// The shared error-code groups, read rather than re-stated, so a group
+// gaining a code reaches the published reference without anyone having to
+// remember this file. `errorGroups.ts` has no imports, so nothing is dragged
+// in by reading it.
+import * as errorGroups from '../src/cli/engine/errorGroups'
+
+const ROOT = path.resolve(__dirname, '..')
+const ROUTES = path.join(ROOT, 'src/cli/engine/routes')
+
+export interface ExtractedField {
+  name: string
+  type: string
+  optional: boolean
+  doc?: string
+}
+
+export interface ExtractedCliFlag {
+  /** Flag name as typed, without the leading dashes. */
+  name: string
+  /** Request field it carries. */
+  maps: string
+  repeat?: boolean
+  doc?: string
+}
+
+export interface ExtractedCliExtra {
+  name: string
+  kind: string
+  required?: boolean
+  requiredWith?: string
+  doc?: string
+}
+
+export interface ExtractedCli {
+  command: string
+  positional?: string
+  bodyFlag?: string
+  flags: ExtractedCliFlag[]
+  extra: ExtractedCliExtra[]
+  notes?: string
+  /**
+   * This binding's own one-line summary.
+   *
+   * Two commands on one route otherwise share the route's JSDoc first line,
+   * so `spend` and `spend-max` were both published as "Send funds." — the
+   * only duplicated help text in the generated table.
+   */
+  summary?: string
+  custom: boolean
+  /** Fields sent at fixed values. */
+  preset: Record<string, boolean>
+  exits?: Record<string, number>
+}
+
+export interface ExtractedRoute {
+  id: string
+  file: string
+  summary: string
+  description?: string
+  core: string | null
+  coreNote?: string
+  method: string
+  routePath: string
+  /** Fields core has no parameter for, mapped to the reason they exist. */
+  coreExtra: Record<string, string>
+  /** The `path` as written, before the positional is appended. */
+  declaredPath: string
+  /** Field the path carries as its final segment, or null. */
+  pathPositional: string | null
+  cli: ExtractedCli | null
+  /** Additional commands this route backs, e.g. `spend-max`. */
+  cliExtra: ExtractedCli[]
+  /** Path parameters, in order of appearance. */
+  pathParams: string[]
+  /** Source file basename, which is also the documentation group. */
+  group: string
+  isStream: boolean
+  errors: string[]
+  notes: string[]
+  bodyNote?: string
+  returnsDoc?: string
+  params: Record<string, string>
+  query?: ExtractedField[]
+  body?: ExtractedField[]
+  returns?: ExtractedField[]
+  returnsProse?: string
+  returnsType?: string
+}
+
+const FORMAT = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias
+
+function sourceFiles(): string[] {
+  return fs
+    .readdirSync(ROUTES)
+    .filter(n => n.endsWith('.ts') && n !== 'index.ts' && n !== 'helpers.ts')
+    .map(n => path.join(ROUTES, n))
+}
+
+/** Literal value of a property in the `route({…})` object. */
+function literal(obj: ts.ObjectLiteralExpression, key: string): string | null {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue
+    if (prop.name.getText() !== key) continue
+    const init = prop.initializer
+    if (ts.isStringLiteral(init)) return init.text
+    if (init.kind === ts.SyntaxKind.NullKeyword) return null
+    return init.getText()
+  }
+  return undefined as unknown as string
+}
+
+function arrayLiteral(obj: ts.ObjectLiteralExpression, key: string): string[] {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue
+    if (prop.name.getText() !== key) continue
+    return stringArray(prop.initializer)
+  }
+  return []
+}
+
+/**
+ * A declared string array, with the shared error groups expanded.
+ *
+ * `errors: WALLET_ERRORS` and `errors: ['BAD_REQUEST', ...WALLET_ERRORS]` are
+ * exactly what `docs/api/README.md` tells every contributor to write, and the
+ * old reading — bail on a non-literal, then filter the elements down to
+ * string literals — turned the first into nothing and the second into
+ * `['BAD_REQUEST']`. 46 codes across 16 routes were therefore missing from
+ * the reference, the OpenAPI document and `edge-cli help`, including all five
+ * `OBJECT_*` codes on `sign-tx`, `broadcast-tx` and `save-tx`, where
+ * `OBJECT_EXPIRED` is the one a caller holding a five-minute handle has to
+ * branch on. Following the documented convention was what made a route's
+ * errors disappear, and no gate could see it because the codes were already
+ * gone before `verifyApiDocs` looked.
+ *
+ * An unrecognised form throws rather than extracting nothing, so the next
+ * shape nobody anticipated fails the build instead of silently shrinking the
+ * published surface.
+ */
+function stringArray(node: ts.Expression): string[] {
+  if (ts.isIdentifier(node)) return errorGroup(node.text)
+  if (!ts.isArrayLiteralExpression(node)) {
+    throw new Error(
+      `Cannot extract "${node.getText()}": expected a string array, a shared ` +
+        `group from src/cli/engine/errorGroups.ts, or a mix of the two.`
+    )
+  }
+  const out: string[] = []
+  for (const element of node.elements) {
+    if (ts.isStringLiteral(element)) {
+      out.push(element.text)
+    } else if (
+      ts.isSpreadElement(element) &&
+      ts.isIdentifier(element.expression)
+    ) {
+      out.push(...errorGroup(element.expression.text))
+    } else {
+      throw new Error(
+        `Cannot extract array element "${element.getText()}": expected a ` +
+          `string literal or a spread of a shared group.`
+      )
+    }
+  }
+  return out
+}
+
+/**
+ * A route's published error codes.
+ *
+ * `SESSION_ERRORS` is added to every session-scoped route rather than
+ * restated on each of them: the two codes apply uniformly to anything under
+ * `/account/{sessionId}/`, and `errorGroups.ts` says itself that the group
+ * "had no consumer at all" — so no session route documented the two failures
+ * a caller is most likely to meet, which is what the `unpublished error
+ * group` gate now refuses. Deriving it from the path cannot drift as routes
+ * are added.
+ */
+function routeErrors(
+  arg: ts.ObjectLiteralExpression,
+  routePath: string
+): string[] {
+  const declared = arrayLiteral(arg, 'errors')
+  if (!routePath.includes('{sessionId}')) return declared
+  const out = [...declared]
+  for (const code of errorGroup('SESSION_ERRORS')) {
+    if (!out.includes(code)) out.push(code)
+  }
+  return out
+}
+
+/** One shared group's codes, by the name a route refers to it by. */
+function errorGroup(name: string): string[] {
+  const group = (errorGroups as unknown as Record<string, unknown>)[name]
+  if (!Array.isArray(group)) {
+    throw new Error(
+      `Unknown error group "${name}". Shared groups live in ` +
+        `src/cli/engine/errorGroups.ts and must be exported as string arrays.`
+    )
+  }
+  return group.map(String)
+}
+
+function propNode(
+  obj: ts.ObjectLiteralExpression,
+  key: string
+): ts.Expression | undefined {
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop) && prop.name.getText() === key) {
+      return prop.initializer
+    }
+  }
+  return undefined
+}
+
+/** Expand a cleaner's resolved output type into documented fields. */
+/**
+ * A type as text, with the members of a string-literal union sorted.
+ *
+ * The checker's own order for a union is an implementation detail — it
+ * changed when this generator started using the repo's compiler options
+ * instead of six hand-written ones — and these artifacts are committed, so
+ * an arbitrary order means a diff on every toolchain change. Sorted, the
+ * output depends only on the declaration.
+ */
+function stableTypeText(text: string): string {
+  const parts = text.split(' | ').map(p => p.trim())
+  if (parts.length < 2) return text
+  const undefinedLast = parts.filter(p => p !== 'undefined')
+  if (!undefinedLast.every(p => /^(['"]).*\1$/.test(p))) return text
+  const sorted = [...undefinedLast].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+  if (undefinedLast.length !== parts.length) sorted.push('undefined')
+  return sorted.join(' | ')
+}
+
+function fieldsOf(
+  checker: ts.TypeChecker,
+  node: ts.Expression
+): { fields: ExtractedField[]; type: string } {
+  const cleanerType = checker.getTypeAtLocation(node)
+  const call = cleanerType.getCallSignatures()[0]
+  if (call == null) {
+    return {
+      fields: [],
+      type: stableTypeText(checker.typeToString(cleanerType, node, FORMAT))
+    }
+  }
+  const out = checker.getReturnTypeOfSignature(call)
+  const typeText = stableTypeText(checker.typeToString(out, node, FORMAT))
+  // A primitive or `unknown` has no fields of its own — asking for its
+  // properties yields the prototype's, which are not part of the API.
+  const isObjectLike =
+    (out.flags & ts.TypeFlags.Object) !== 0 && !typeText.endsWith('[]')
+  const fields = (isObjectLike ? checker.getPropertiesOfType(out) : []).map(
+    prop => {
+      const t = checker.getTypeOfSymbolAtLocation(prop, node)
+      let text = stableTypeText(checker.typeToString(t, node, FORMAT))
+      // Cleaners type optional fields as `T | undefined`; render them as `T?`.
+      const optional =
+        (prop.flags & ts.SymbolFlags.Optional) !== 0 ||
+        text.endsWith(' | undefined')
+      text = text.replace(/ \| undefined$/, '')
+      return { name: prop.name, type: text, optional }
+    }
+  )
+  return { fields, type: typeText }
+}
+
+/**
+ * Field prose written as `doc(cleaner, 'text')`.
+ *
+ * Read from the syntax tree rather than at runtime, because request cleaners
+ * use `.withRest`, which discards the `.shape` a runtime walk would need.
+ * Resolves a bare identifier (`returns: asSession`) back to its declaration,
+ * so a shared response shape carries its prose once.
+ */
+function proseFor(
+  checker: ts.TypeChecker,
+  node: ts.Expression
+): Record<string, string> {
+  // Null-prototype, so a field called `toString` cannot pick up an inherited
+  // member instead of its own prose.
+  const out: Record<string, string> = Object.create(null)
+
+  const objectOf = (expr: ts.Expression): ts.Expression | undefined => {
+    // A shared field group is a bare object literal, not an asObject() call.
+    if (ts.isObjectLiteralExpression(expr)) return expr
+    // asObject({…}) / asObject({…}).withRest / a name pointing at either.
+    let cur: ts.Expression = expr
+    if (ts.isPropertyAccessExpression(cur)) cur = cur.expression
+    if (ts.isIdentifier(cur)) {
+      let sym = checker.getSymbolAtLocation(cur)
+      // An import is an alias; follow it to the real declaration so a shared
+      // response shape carries its prose from wherever it is defined.
+      if (sym != null && (sym.flags & ts.SymbolFlags.Alias) !== 0) {
+        sym = checker.getAliasedSymbol(sym)
+      }
+      const decl = sym?.declarations?.[0]
+      if (
+        decl != null &&
+        ts.isVariableDeclaration(decl) &&
+        decl.initializer != null
+      ) {
+        return objectOf(decl.initializer)
+      }
+      return undefined
+    }
+    if (ts.isCallExpression(cur)) {
+      const callee = cur.expression.getText()
+      if (callee === 'doc') return objectOf(cur.arguments[0])
+      if (callee.startsWith('asObject')) return cur.arguments[0]
+    }
+    return undefined
+  }
+
+  // Resolve the prose argument: a literal, a `'a' + 'b'` concatenation, or a
+  // named constant shared between fields.
+  const proseText = (expr: ts.Expression): string | undefined => {
+    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+      return expr.text
+    }
+    if (
+      ts.isBinaryExpression(expr) &&
+      expr.operatorToken.kind === ts.SyntaxKind.PlusToken
+    ) {
+      const left = proseText(expr.left)
+      const right = proseText(expr.right)
+      if (left != null && right != null) return left + right
+    }
+    if (ts.isIdentifier(expr)) {
+      let sym = checker.getSymbolAtLocation(expr)
+      if (sym != null && (sym.flags & ts.SymbolFlags.Alias) !== 0) {
+        sym = checker.getAliasedSymbol(sym)
+      }
+      const decl = sym?.declarations?.[0]
+      if (
+        decl != null &&
+        ts.isVariableDeclaration(decl) &&
+        decl.initializer != null
+      ) {
+        return proseText(decl.initializer)
+      }
+    }
+    return undefined
+  }
+
+  // A `doc(…)` call may sit inside a combinator — `asOptional(doc(…))` — so
+  // search the expression rather than only looking at its outermost call.
+  const findDoc = (expr: ts.Expression): string | undefined => {
+    // A shared field cleaner is named: `walletId: asWalletId`, where
+    // `asWalletId` is `doc(asString, '…')` exported from schemas. Follow the
+    // name to its declaration so one description serves every route using it.
+    if (ts.isIdentifier(expr)) {
+      let sym = checker.getSymbolAtLocation(expr)
+      if (sym != null && (sym.flags & ts.SymbolFlags.Alias) !== 0) {
+        sym = checker.getAliasedSymbol(sym)
+      }
+      const decl = sym?.declarations?.[0]
+      if (
+        decl != null &&
+        ts.isVariableDeclaration(decl) &&
+        decl.initializer != null
+      ) {
+        return findDoc(decl.initializer)
+      }
+      return undefined
+    }
+    if (ts.isCallExpression(expr)) {
+      if (expr.expression.getText() === 'doc' && expr.arguments.length > 1) {
+        return proseText(expr.arguments[1])
+      }
+      for (const arg of expr.arguments) {
+        const found = findDoc(arg)
+        if (found != null) return found
+      }
+    }
+    if (ts.isPropertyAccessExpression(expr)) return findDoc(expr.expression)
+    return undefined
+  }
+
+  // Prose attached to the whole cleaner, for pass-through responses. Only the
+  // outermost call counts: a nested field's prose is not the response's.
+  let outer: ts.Expression = node
+  if (ts.isPropertyAccessExpression(outer)) outer = outer.expression
+  if (
+    ts.isCallExpression(outer) &&
+    outer.expression.getText() === 'doc' &&
+    outer.arguments.length > 1
+  ) {
+    const whole = proseText(outer.arguments[1])
+    if (whole != null) out[''] = whole
+  }
+
+  const shape = objectOf(node)
+  if (shape == null || !ts.isObjectLiteralExpression(shape)) return out
+  for (const prop of shape.properties) {
+    if (ts.isSpreadAssignment(prop)) {
+      // `...loginOptionFields` — the spread object carries prose too.
+      Object.assign(out, proseFor(checker, prop.expression))
+      continue
+    }
+    if (!ts.isPropertyAssignment(prop)) continue
+    const found = findDoc(prop.initializer)
+    if (found != null) out[prop.name.getText()] = found
+  }
+  return out
+}
+
+/** Read `{ key: 'text', … }` from a property, for `coreExtra`. */
+function recordLiteral(
+  arg: ts.ObjectLiteralExpression,
+  key: string
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  const node = propNode(arg, key)
+  if (node == null || !ts.isObjectLiteralExpression(node)) return out
+  for (const prop of node.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue
+    const name = prop.name.getText().replace(/'/g, '')
+    const init = prop.initializer
+    if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+      out[name] = init.text
+    } else {
+      // A concatenation spanning lines.
+      out[name] = init
+        .getText()
+        .replace(/'\s*\+\s*'/g, '')
+        .replace(/^'|'$/g, '')
+    }
+  }
+  return out
+}
+
+/** Parse the `cli` field: a bare command name, an object spec, or null. */
+function parseCli(node: ts.Expression | undefined): ExtractedCli | null {
+  if (node == null) return null
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null
+  if (ts.isStringLiteral(node)) {
+    return {
+      command: node.text,
+      flags: [],
+      extra: [],
+      custom: false,
+      preset: {}
+    }
+  }
+  if (!ts.isObjectLiteralExpression(node)) return null
+
+  const str = (
+    o: ts.ObjectLiteralExpression,
+    key: string
+  ): string | undefined => {
+    for (const prop of o.properties) {
+      if (!ts.isPropertyAssignment(prop)) continue
+      if (prop.name.getText() !== key) continue
+      if (ts.isStringLiteral(prop.initializer)) return prop.initializer.text
+      if (ts.isNoSubstitutionTemplateLiteral(prop.initializer)) {
+        return prop.initializer.text
+      }
+      // A concatenated string spanning lines.
+      const text = prop.initializer.getText()
+      const parts = [...text.matchAll(/'([^']*)'/g)].map(m => m[1])
+      if (parts.length > 0) return parts.join('')
+    }
+    return undefined
+  }
+  const obj = (
+    o: ts.ObjectLiteralExpression,
+    key: string
+  ): ts.ObjectLiteralExpression | undefined => {
+    for (const prop of o.properties) {
+      if (
+        ts.isPropertyAssignment(prop) &&
+        prop.name.getText() === key &&
+        ts.isObjectLiteralExpression(prop.initializer)
+      ) {
+        return prop.initializer
+      }
+    }
+    return undefined
+  }
+
+  const command = str(node, 'command') ?? ''
+  const flags: ExtractedCliFlag[] = []
+  const flagsObj = obj(node, 'flags')
+  if (flagsObj != null) {
+    for (const prop of flagsObj.properties) {
+      if (!ts.isPropertyAssignment(prop)) continue
+      const name = prop.name.getText().replace(/'/g, '')
+      const spec = ts.isObjectLiteralExpression(prop.initializer)
+        ? prop.initializer
+        : undefined
+      flags.push({
+        name: kebab(name),
+        maps: spec != null ? str(spec, 'maps') ?? name : name,
+        repeat: spec != null ? /repeat:\s*true/.test(spec.getText()) : false,
+        doc: spec != null ? str(spec, 'doc') : undefined
+      })
+    }
+  }
+  const extra: ExtractedCliExtra[] = []
+  const extraObj = obj(node, 'extra')
+  if (extraObj != null) {
+    for (const prop of extraObj.properties) {
+      if (!ts.isPropertyAssignment(prop)) continue
+      const name = prop.name.getText().replace(/'/g, '')
+      const spec = ts.isObjectLiteralExpression(prop.initializer)
+        ? prop.initializer
+        : undefined
+      extra.push({
+        name: kebab(name),
+        kind: spec != null ? str(spec, 'kind') ?? 'string' : 'string',
+        required:
+          spec != null ? /required:\s*true/.test(spec.getText()) : false,
+        requiredWith: spec != null ? str(spec, 'requiredWith') : undefined,
+        doc: spec != null ? str(spec, 'doc') : undefined
+      })
+    }
+  }
+  return {
+    command,
+    positional: str(node, 'positional'),
+    bodyFlag: str(node, 'bodyFlag'),
+    flags,
+    extra,
+    custom: /custom:\s*true/.test(node.getText()),
+    preset: (() => {
+      const out: Record<string, boolean> = {}
+      const o = obj(node, 'preset')
+      if (o != null) {
+        for (const prop of o.properties) {
+          if (!ts.isPropertyAssignment(prop)) continue
+          const v = prop.initializer.getText()
+          if (v === 'true' || v === 'false') {
+            out[prop.name.getText().replace(/'/g, '')] = v === 'true'
+          }
+        }
+      }
+      return out
+    })(),
+    notes: str(node, 'notes'),
+    summary: str(node, 'summary')
+  }
+}
+
+/** `cli` may be one command or several. */
+function parseCliList(node: ts.Expression | undefined): ExtractedCli[] {
+  if (node != null && ts.isArrayLiteralExpression(node)) {
+    return node.elements
+      .map(el => parseCli(el))
+      .filter((c): c is ExtractedCli => c != null)
+  }
+  const one = parseCli(node)
+  return one != null ? [one] : []
+}
+
+/** camelCase to kebab-case, the CLI's flag spelling. */
+export function kebab(name: string): string {
+  return name.replace(/[A-Z]/g, c => '-' + c.toLowerCase())
+}
+
+/** Split a JSDoc comment into prose and tags. */
+function readJsDoc(node: ts.Node): {
+  summary: string
+  description?: string
+  tags: Array<[string, string]>
+} {
+  const docs = (node as unknown as { jsDoc?: ts.JSDoc[] }).jsDoc
+  if (docs == null || docs.length === 0) return { summary: '', tags: [] }
+  const doc = docs[docs.length - 1]
+  const comment =
+    typeof doc.comment === 'string'
+      ? doc.comment
+      : (doc.comment ?? []).map(c => c.text).join('')
+  const paras = comment
+    .split('\n\n')
+    .map(p => p.replace(/\s*\n\s*/g, ' ').trim())
+  const tags: Array<[string, string]> = []
+  for (const tag of doc.tags ?? []) {
+    const name = tag.tagName.text
+    const text =
+      typeof tag.comment === 'string'
+        ? tag.comment
+        : (tag.comment ?? []).map(c => c.text).join('')
+    const paramName = ts.isJSDocParameterTag(tag)
+      ? tag.name.getText()
+      : undefined
+    // Tag text wraps across comment lines; collapse it back to one line.
+    const flat = text.replace(/\s*\n\s*/g, ' ').trim()
+    tags.push([name, (paramName != null ? `${paramName} ` : '') + flat])
+  }
+  return {
+    summary: paras[0] ?? '',
+    description: paras.length > 1 ? paras.slice(1).join('\n\n') : undefined,
+    tags
+  }
+}
+
+/**
+ * Property names wrapped in `asOptional(…)`.
+ *
+ * `asOptional(asUnknown)` resolves to plain `unknown`, because `unknown`
+ * absorbs `undefined` — so optionality has to be read from the source.
+ */
+function optionalNames(
+  checker: ts.TypeChecker,
+  node: ts.Expression
+): Set<string> {
+  const out = new Set<string>()
+  const walk = (expr: ts.Expression): ts.Expression | undefined => {
+    let cur: ts.Expression = expr
+    if (ts.isPropertyAccessExpression(cur)) cur = cur.expression
+    if (ts.isObjectLiteralExpression(cur)) return cur
+    if (ts.isIdentifier(cur)) {
+      let sym = checker.getSymbolAtLocation(cur)
+      if (sym != null && (sym.flags & ts.SymbolFlags.Alias) !== 0) {
+        sym = checker.getAliasedSymbol(sym)
+      }
+      const decl = sym?.declarations?.[0]
+      if (
+        decl != null &&
+        ts.isVariableDeclaration(decl) &&
+        decl.initializer != null
+      ) {
+        return walk(decl.initializer)
+      }
+      return undefined
+    }
+    if (ts.isCallExpression(cur)) {
+      const callee = cur.expression.getText()
+      if (callee === 'doc') return walk(cur.arguments[0])
+      if (callee.startsWith('asObject')) return cur.arguments[0]
+    }
+    return undefined
+  }
+  const shape = walk(node)
+  if (shape == null || !ts.isObjectLiteralExpression(shape)) return out
+  for (const prop of shape.properties) {
+    if (ts.isSpreadAssignment(prop)) {
+      for (const n of optionalNames(checker, prop.expression)) out.add(n)
+      continue
+    }
+    if (!ts.isPropertyAssignment(prop)) continue
+    if (/\basOptional\s*\(/.test(prop.initializer.getText())) {
+      out.add(prop.name.getText().replace(/'/g, ''))
+    }
+  }
+  return out
+}
+
+/** Resolved fields, each carrying the prose written beside it. */
+function withProse(
+  checker: ts.TypeChecker,
+  node: ts.Expression | undefined
+): ExtractedField[] | undefined {
+  if (node == null) return undefined
+  const prose = proseFor(checker, node)
+  const optional = optionalNames(checker, node)
+  return fieldsOf(checker, node).fields.map(f => ({
+    ...f,
+    optional: f.optional || optional.has(f.name),
+    doc: prose[f.name]
+  }))
+}
+
+/**
+ * The repo's own compiler options, so the checker sees what `tsc` sees.
+ *
+ * Six hand-written options stood in for `tsconfig.json`, and the difference
+ * was not cosmetic: without `resolveJsonModule` every `.json` import in the
+ * route graph resolved to nothing, and without `esModuleInterop` a default
+ * import did. Measured at the time, the hand-written program produced 63
+ * errors over the same files that `npm run tsc` compiles clean — so the
+ * document was generated from a partly broken view of the code, and a type
+ * the checker silently resolved to an error type would have been documented
+ * as such with no gate able to notice.
+ */
+function compilerOptions(): ts.CompilerOptions {
+  const configPath = path.join(ROOT, 'tsconfig.json')
+  // Bound, because `ts.sys.readFile` is a method on `ts.sys`.
+  const read = ts.readConfigFile(configPath, file => ts.sys.readFile(file))
+  if (read.error != null) {
+    throw new Error(
+      `Could not read tsconfig.json: ${ts.flattenDiagnosticMessageText(
+        read.error.messageText,
+        ' '
+      )}`
+    )
+  }
+  const parsed = ts.parseJsonConfigFileContent(
+    read.config,
+    ts.sys,
+    path.dirname(configPath)
+  )
+  return {
+    ...parsed.options,
+    // This program only reads types; it never emits.
+    noEmit: true,
+    // The route graph pulls in React Native's declarations transitively, and
+    // type-checking those is `npm run tsc`'s job, not this generator's.
+    skipLibCheck: true
+  }
+}
+
+export function extractRoutes(): ExtractedRoute[] {
+  const files = sourceFiles()
+  const program = ts.createProgram(files, compilerOptions())
+  // The checker's view has to match the repo's, or a field's documented type
+  // is whatever a broken resolution produced. Only the route files' own
+  // diagnostics are fatal: the graph reaches the whole app, and the app's
+  // type-check is `npm run tsc`.
+  const routeFileSet = new Set(files)
+  const fatal = ts
+    .getPreEmitDiagnostics(program)
+    .filter(d => d.file != null && routeFileSet.has(d.file.fileName))
+  if (fatal.length > 0) {
+    const lines = fatal.slice(0, 10).map(d => {
+      const where =
+        d.file != null && d.start != null
+          ? `${path.relative(ROOT, d.file.fileName)}:${
+              d.file.getLineAndCharacterOfPosition(d.start).line + 1
+            }`
+          : '?'
+      return `  ${where}: ${ts.flattenDiagnosticMessageText(
+        d.messageText,
+        ' '
+      )}`
+    })
+    throw new Error(
+      `extractRoutes: ${fatal.length} type error(s) in the route files, so ` +
+        `the documented types would not be the real ones:\n${lines.join('\n')}`
+    )
+  }
+  const checker = program.getTypeChecker()
+  const out: ExtractedRoute[] = []
+
+  for (const file of files) {
+    const src = program.getSourceFile(file)
+    if (src == null) continue
+    for (const stmt of src.statements) {
+      if (!ts.isVariableStatement(stmt)) continue
+      for (const decl of stmt.declarationList.declarations) {
+        const init = decl.initializer
+        if (
+          init == null ||
+          !ts.isCallExpression(init) ||
+          init.expression.getText() !== 'route'
+        ) {
+          continue
+        }
+        const arg = init.arguments[0]
+        if (arg == null || !ts.isObjectLiteralExpression(arg)) continue
+
+        const { summary, description, tags } = readJsDoc(stmt)
+        const params: Record<string, string> = {}
+        const notes: string[] = []
+        let bodyNote: string | undefined
+        let returnsDoc: string | undefined
+        let coreNote: string | undefined
+        for (const [tag, text] of tags) {
+          if (tag === 'param') {
+            const [name, ...rest] = text.split(' ')
+            params[name] = rest.join(' ').trim()
+          } else if (tag === 'note') notes.push(text.trim())
+          else if (tag === 'bodyNote') bodyNote = text.trim()
+          else if (tag === 'returns') returnsDoc = text.trim()
+          else if (tag === 'coreNote') coreNote = text.trim()
+        }
+
+        const queryNode = propNode(arg, 'query')
+        const bodyNode = propNode(arg, 'body')
+        const returnsNode = propNode(arg, 'returns')
+        const cliNode = propNode(arg, 'cli')
+
+        // The declared `path` carries scope and command; a positional is
+        // appended to it. Mirrors `routePath` in src/cli/engine/route.ts,
+        // which is what the engine actually serves.
+        const declaredPath = literal(arg, 'path') ?? ''
+        const cli = parseCliList(cliNode)[0] ?? null
+        const pathPositional = cli?.positional ?? null
+        const routePath =
+          pathPositional == null
+            ? declaredPath
+            : `${declaredPath}/{${pathPositional}}`
+
+        out.push({
+          id: decl.name.getText(),
+          file: path.basename(file),
+          summary,
+          description,
+          core: literal(arg, 'core'),
+          coreNote,
+          coreExtra: recordLiteral(arg, 'coreExtra'),
+          method: literal(arg, 'method') ?? '',
+          routePath,
+          declaredPath,
+          pathPositional,
+          cli,
+          cliExtra: parseCliList(cliNode).slice(1),
+          pathParams: [...routePath.matchAll(/\{(\w+)\}/g)].map(m => m[1]),
+          group: path.basename(file, '.ts'),
+          isStream: propNode(arg, 'stream') != null,
+          errors: routeErrors(arg, routePath),
+          notes,
+          bodyNote,
+          returnsDoc,
+          params,
+          query: withProse(checker, queryNode),
+          body: withProse(checker, bodyNode),
+          returns: withProse(checker, returnsNode),
+          returnsProse:
+            returnsNode != null
+              ? proseFor(checker, returnsNode)['']
+              : undefined,
+          returnsType:
+            returnsNode != null
+              ? fieldsOf(checker, returnsNode).type
+              : undefined
+        })
+      }
+    }
+  }
+  return out
+}
+
+if (require.main === module) {
+  const routes = extractRoutes()
+  console.log(`extracted ${routes.length} route declaration(s)\n`)
+  for (const r of routes) {
+    console.log(`${r.id}  [${r.file}]`)
+    console.log(`  ${r.method} ${r.routePath}   cli=${r.cli?.command ?? '—'}`)
+    console.log(
+      `  core: ${r.core ?? 'null'}${
+        r.coreNote != null ? ' — ' + r.coreNote.slice(0, 60) : ''
+      }`
+    )
+    console.log(`  summary: ${r.summary}`)
+    if (r.description != null)
+      console.log(`  desc: ${r.description.slice(0, 80)}…`)
+    for (const n of r.notes) console.log(`  note: ${n.slice(0, 78)}`)
+    if (r.returnsDoc != null)
+      console.log(`  returns doc: ${r.returnsDoc.slice(0, 70)}`)
+    if (r.returns != null) {
+      console.log(
+        `  returns: ${r.returns
+          .map(f => f.name + (f.optional ? '?' : '') + ': ' + f.type)
+          .join(', ')}`
+      )
+    }
+    console.log()
+  }
+}
diff --git a/scripts/makeApiSigner.ts b/scripts/makeApiSigner.ts
index 19b41cdafd0..55fe5041ee5 100644
--- a/scripts/makeApiSigner.ts
+++ b/scripts/makeApiSigner.ts
@@ -9,6 +9,7 @@
  * Outputs (gitignored):
  *   ios/EdgeApiSecret.c + ios/EdgeApiSecret.h
  *   android/app/src/main/cpp/edge_api_secret.c (+ header)
+ *   native/edge-api-signer/node/edge_api_secret.c (+ header)
  *
  * Stub secret (`00`) only when EDGE_API_SIGNER_ALLOW_STUB=1 (used by prepare.sh
  * before Jenkins secretFiles). Native generate tasks omit the flag so missing
@@ -19,16 +20,29 @@ import { createHash, randomBytes } from 'crypto'
 import fs from 'fs'
 import path from 'path'
 
+import { NODE_API_SIGNER_BUNDLE_ID } from '../src/cli/engine/nodeApiSigner'
+
 const ROOT = path.join(__dirname, '..')
 const SHARD_COUNT = 6 // 5 random pads + 1 stored remainder (after runtime pad)
 export const MAX_SECRET_LEN = 32
 const STAMP_PATH = path.join(ROOT, '.edgeApiSigner.stamp')
 const ANDROID_CPP = path.join(ROOT, 'android/app/src/main/cpp')
+const NODE_CPP = path.join(ROOT, 'native/edge-api-signer/node')
+/**
+ * Every file this script writes.
+ *
+ * The two Node outputs were module-level consts outside this table, so
+ * `signerOutputsExist` could not see them and the stamp check needed a
+ * bolted-on clause to notice they were missing — a third place to update
+ * when a target is added.
+ */
 const OUTPUT_PATHS = {
   iosSource: path.join(ROOT, 'ios/EdgeApiSecret.c'),
   iosHeader: path.join(ROOT, 'ios/EdgeApiSecret.h'),
   androidSource: path.join(ANDROID_CPP, 'edge_api_secret.c'),
-  androidHeader: path.join(ANDROID_CPP, 'edge_api_secret.h')
+  androidHeader: path.join(ANDROID_CPP, 'edge_api_secret.h'),
+  nodeSource: path.join(NODE_CPP, 'edge_api_secret.c'),
+  nodeHeader: path.join(NODE_CPP, 'edge_api_secret.h')
 }
 export const API_KEY_PLACEHOLDER =
   'Error: Set up edgeKey.json apiKey & re-run scripts/makeApiSigner.ts'
@@ -252,6 +266,24 @@ function makeHeader(): string {
 `
 }
 
+/**
+ * The Node header additionally publishes the runtime pad, so
+ * edge_api_signer_napi.c unpads with exactly the id the shards were built
+ * against instead of repeating the literal.
+ */
+function makeNodeHeader(nodeBundleId: string): string {
+  if (!/^[\x20-\x7e]+$/.test(nodeBundleId)) {
+    throw new Error('nodeBundleId must be printable ASCII')
+  }
+  return `/* auto-generated by scripts/makeApiSigner.ts — do not edit */
+#ifndef EDGE_API_SECRET_GEN_H
+#define EDGE_API_SECRET_GEN_H
+#include "edge_api_sign.h"
+#define EDGE_NODE_BUNDLE_ID ${JSON.stringify(nodeBundleId)}
+#endif
+`
+}
+
 /**
  * Write through a temp file so a concurrent Gradle and Xcode generate cannot
  * leave a half-written source for the compiler to read.
@@ -268,13 +300,32 @@ function anyOutputsExist(): boolean {
   return Object.values(OUTPUT_PATHS).some(p => fs.existsSync(p))
 }
 
-/** True when all four generated secret sources exist (complete tree). */
+/** The four mobile outputs, which every run writes. */
+const MOBILE_OUTPUTS = [
+  OUTPUT_PATHS.iosSource,
+  OUTPUT_PATHS.iosHeader,
+  OUTPUT_PATHS.androidSource,
+  OUTPUT_PATHS.androidHeader
+]
+
+/**
+ * The two Node outputs, which only a run with a real secret writes.
+ *
+ * Kept as a named group rather than loose consts, so `OUTPUT_PATHS` is the
+ * one list of what this script produces — `anyOutputsExist` and the cleanup
+ * loop both read the whole table — while the completeness tests can still
+ * say which group they mean.
+ */
+const NODE_OUTPUTS = [OUTPUT_PATHS.nodeSource, OUTPUT_PATHS.nodeHeader]
+
+/** True when all four mobile secret sources exist (complete tree). */
 export function signerOutputsExist(): boolean {
-  return Object.values(OUTPUT_PATHS).every(p => fs.existsSync(p))
+  return MOBILE_OUTPUTS.every(p => fs.existsSync(p))
 }
 
-function outputsExist(): boolean {
-  return signerOutputsExist()
+/** True when the Node pair exists too. */
+function nodeOutputsExist(): boolean {
+  return NODE_OUTPUTS.every(p => fs.existsSync(p))
 }
 
 function readStampBundleId(): string | undefined {
@@ -306,8 +357,10 @@ export function readEmbeddedSignerApiKey(): string | undefined {
 }
 
 function main(): void {
-  const bundleId = readBundleId()
-  console.log('bundleId', bundleId)
+  const mobileBundleId = readBundleId()
+  const nodeBundleId = NODE_API_SIGNER_BUNDLE_ID
+  console.log('bundleId', mobileBundleId)
+  console.log('nodeBundleId', nodeBundleId)
 
   let apiKey = API_KEY_PLACEHOLDER
   let secretHex = ''
@@ -332,19 +385,24 @@ function main(): void {
     )
   }
 
+  let missingSecret = false
   if (secretHex === '') {
     if (process.env.EDGE_API_SIGNER_ALLOW_STUB !== '1') {
       throw new Error(MISSING_SECRET_MESSAGE)
     }
+    missingSecret = true
+    for (const output of NODE_OUTPUTS) {
+      if (fs.existsSync(output)) fs.unlinkSync(output)
+    }
     // Keep a complete existing tree only when its stamp still matches this
     // bundleId: deployPatches can rewrite applicationId after a prior stub.
-    if (outputsExist() && readStampBundleId() === bundleId) {
+    if (signerOutputsExist() && readStampBundleId() === mobileBundleId) {
       console.log(
         'warn: apiSecret missing; keeping existing EdgeApiSecret outputs'
       )
       return
     }
-    if (outputsExist()) {
+    if (signerOutputsExist()) {
       console.log(
         'warn: apiSecret missing; bundleId changed since last generate, regenerating stub'
       )
@@ -357,7 +415,7 @@ function main(): void {
     apiKey = API_KEY_PLACEHOLDER
     secretHex = '00'
     console.log(
-      'warn: apiSecret missing; emitting stub secret (signing will be wrong)'
+      'warn: apiSecret missing; emitting mobile stub and skipping Node signer'
     )
   } else if (apiKey === API_KEY_PLACEHOLDER) {
     // A real secret with no apiKey would sign correctly while advertising the
@@ -376,12 +434,17 @@ function main(): void {
     .update('\0')
     .update(secretHex, 'utf8')
     .update('\0')
-    .update(bundleId, 'utf8')
+    .update(mobileBundleId, 'utf8')
+    .update('\0')
+    .update(nodeBundleId, 'utf8')
     .update('\0')
     .update(fs.readFileSync(__filename))
     .digest('hex')
   if (
-    outputsExist() &&
+    signerOutputsExist() &&
+    // The Node pair is only written when there is a real secret, so a stub
+    // tree is complete without it.
+    (missingSecret || nodeOutputsExist()) &&
     fs.existsSync(STAMP_PATH) &&
     fs.readFileSync(STAMP_PATH, 'utf8').split('\n')[0].trim() === inputStamp
   ) {
@@ -390,15 +453,22 @@ function main(): void {
   }
 
   const secret = parseHexSecret(secretHex)
-  const source = makeSource(apiKey, secret, bundleId)
+  const mobileSource = makeSource(apiKey, secret, mobileBundleId)
   const header = makeHeader()
 
-  writeFile(OUTPUT_PATHS.iosSource, source)
+  writeFile(OUTPUT_PATHS.iosSource, mobileSource)
   writeFile(OUTPUT_PATHS.iosHeader, header)
-  writeFile(OUTPUT_PATHS.androidSource, source)
+  writeFile(OUTPUT_PATHS.androidSource, mobileSource)
   writeFile(OUTPUT_PATHS.androidHeader, header)
 
-  fs.writeFileSync(STAMP_PATH, `${inputStamp}\n${bundleId}\n`)
+  if (!missingSecret) {
+    // Built here rather than above, where it was computed and then
+    // discarded on the `missingSecret` path.
+    writeFile(OUTPUT_PATHS.nodeSource, makeSource(apiKey, secret, nodeBundleId))
+    writeFile(OUTPUT_PATHS.nodeHeader, makeNodeHeader(nodeBundleId))
+  }
+
+  fs.writeFileSync(STAMP_PATH, `${inputStamp}\n${mobileBundleId}\n`)
 
   // Stub embeds the placeholder apiKey; rewrite EdgeApiKey immediately so a
   // later makeNativeHeaders keep-existing pass cannot leave a prior real key.
diff --git a/scripts/prepare.sh b/scripts/prepare.sh
index bb680fab567..d5b9358f4d3 100755
--- a/scripts/prepare.sh
+++ b/scripts/prepare.sh
@@ -39,5 +39,11 @@ fi
 node ./node_modules/.bin/rollup -c
 node -r sucrase/register ./scripts/stringifyBridge.ts
 
+# Regenerate the API reference and the CLI's command table and help text
+# from the route declarations. All are committed, so a fresh clone works
+# without this; the writes are skipped when nothing changed, so prepare never
+# dirties git.
+npm run docs:api
+
 # Create contract type definitions:
 npm run typechain
diff --git a/scripts/testCliFake.ts b/scripts/testCliFake.ts
new file mode 100644
index 00000000000..e5bca144b9e
--- /dev/null
+++ b/scripts/testCliFake.ts
@@ -0,0 +1,998 @@
+/**
+ * Exercise the CLI against the in-process fake world.
+ *
+ * `makeFakeEdgeWorld` emulates the login, info and sync servers and cuts the
+ * currency plugins off from the network, so every account-shaped command runs
+ * with no server, no API key and no internet. That is what lets these run in a
+ * pre-commit hook, where `testCli.ts` and friends cannot: they need
+ * login-tester.
+ *
+ * Responses are checked against each route's `returns` cleaner in strict mode,
+ * so a shape that drifts from the reference fails here.
+ *
+ *   node -r sucrase/register scripts/testCliFake.ts
+ */
+import { spawnSync } from 'child_process'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { CLI, runRoot } from './util/cliHarness'
+
+const DIR = path.join(os.tmpdir(), `edge-cli-fake-${process.pid}`)
+const BASE = ['--fake', `--directory=${DIR}`]
+
+const USER = `faker${process.pid}`
+const PASS = 'y768Mv4PLFupQjMu'
+const PIN = '1111'
+
+let failures = 0
+/** The engine's own run directory, so the leak check cannot drift. */
+let runProfileDir: string | null = null
+let passes = 0
+
+interface Run {
+  status: number
+  out: string
+  json: any
+}
+
+/**
+ * The first JSON object in a stream, ignoring anything after it.
+ *
+ * Brace-counted rather than regexed, because the envelope is pretty-printed
+ * and its `details` nest.
+ */
+function parseLeadingJson(text: string | undefined): any {
+  if (text == null) return undefined
+  const start = text.indexOf('{')
+  if (!text.includes('{')) return undefined
+  let depth = 0
+  let inString = false
+  let escaped = false
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') inString = true
+    else if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) {
+        try {
+          return JSON.parse(text.slice(start, i + 1))
+        } catch {
+          return undefined
+        }
+      }
+    }
+  }
+  return undefined
+}
+
+function cli(...args: string[]): Run {
+  const result = spawnSync('node', [...CLI, ...BASE, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, EDGE_CLI_CHECK_RESPONSES: 'strict' }
+  })
+  const out = (result.stdout ?? '') + (result.stderr ?? '')
+  // Both streams, and the leading object when a stream carries more than
+  // JSON: a result is printed to stdout and an error envelope to stderr, and
+  // a client-side usage failure prints the envelope *followed by* a usage
+  // line. Parsing only `stdout` whole left `run.json` undefined for every
+  // failure — exactly when a check wants to read `error.code`.
+  let json: any
+  for (const text of [result.stdout, result.stderr]) {
+    json = parseLeadingJson(text)
+    if (json !== undefined) break
+  }
+  return { status: result.status ?? -1, out, json }
+}
+
+/** Run a command and require it to succeed. */
+function ok(label: string, ...args: string[]): Run {
+  const run = cli(...args)
+  // `"error": null` is an ordinary field on a pending login, not a failure.
+  const good = run.status === 0 && !/"error":\s*\{/.test(run.out)
+  if (good) {
+    passes++
+    console.log(`OK   ${label}`)
+  } else {
+    failures++
+    console.error(
+      `FAIL ${label} — ${run.out.replace(/\s+/g, ' ').slice(0, 160)}`
+    )
+  }
+  return run
+}
+
+/**
+ * Run a command that is expected to fail, and say why that is correct.
+ *
+ * The code is compared against the envelope's own `error.code`, not matched
+ * as a substring of stdout+stderr: a substring match passed whenever the
+ * code appeared anywhere, including inside a *message*, and eleven cases
+ * asserted the literal `'error'`, which every envelope contains — so they
+ * pinned "the command failed" and nothing else, and a regression from
+ * `INSUFFICIENT_FUNDS`/422 to `INTERNAL_ERROR`/500 kept the suite green.
+ */
+function refuses(label: string, code: string, ...args: string[]): void {
+  refusesInner(label, code, undefined, args)
+}
+
+/**
+ * As `refuses`, for a failure whose code is `INTERNAL_ERROR`.
+ *
+ * Those are plain `Error`s from core or a plugin that `mapCoreError` has no
+ * arm for, so the code alone pins nothing: the message is the only thing
+ * saying *which* failure this is. Asserting both keeps the case honest
+ * without pretending the engine answers something it does not.
+ */
+function refusesInternal(
+  label: string,
+  message: string,
+  ...args: string[]
+): void {
+  refusesInner(label, 'INTERNAL_ERROR', message, args)
+}
+
+function refusesInner(
+  label: string,
+  code: string,
+  message: string | undefined,
+  args: string[]
+): void {
+  if (code === 'error' || code === '') {
+    failures++
+    console.error(
+      `FAIL ${label} — "${code}" is not an error code; name the real one`
+    )
+    return
+  }
+  const run = cli(...args)
+  const actual = run.json?.error?.code
+  const actualMessage = String(run.json?.error?.message ?? '')
+  const messageOk = message == null || actualMessage.includes(message)
+  if (run.status !== 0 && actual === code && messageOk) {
+    passes++
+    console.log(
+      `OK   ${label} (refused with ${code}${
+        message == null ? '' : `: ${message}`
+      })`
+    )
+  } else {
+    failures++
+    console.error(
+      `FAIL ${label} — expected ${code}${
+        message == null ? '' : ` / ${message}`
+      }, got ${String(actual)} / ${run.out.replace(/\s+/g, ' ').slice(0, 140)}`
+    )
+  }
+}
+
+/**
+ * A command the fake world cannot serve.
+ *
+ * Asserted rather than skipped, so that if `makeFakeEdgeWorld` ever grows the
+ * missing piece this fails and the check gets promoted to a real one.
+ */
+function notInFakeWorld(
+  label: string,
+  marker: string,
+  ...args: string[]
+): void {
+  const run = cli(...args)
+  if (run.status !== 0 && run.out.includes(marker)) {
+    passes++
+    console.log(`OK   ${label} (fake world cannot serve it yet)`)
+  } else {
+    failures++
+    console.error(
+      `FAIL ${label} — expected the fake world to reject with "${marker}"; ` +
+        `promote this to a real check. Got: ${run.out
+          .replace(/\s+/g, ' ')
+          .slice(0, 140)}`
+    )
+  }
+}
+
+/**
+ * The interactive prompt, driven over stdin.
+ *
+ * Its own directory, so the shared engine and `session.json` above are not
+ * disturbed. The prompt used to be handed a *spread copy* of the client
+ * context while `setSessionId` assigned to the original, so a login inside
+ * the prompt never took effect: the next account command answered "Please
+ * log in first" on an account that was logged in, and after a dead session
+ * the copy kept the stale id and repeated a 401 for the life of the prompt.
+ * `docs/EDGE_CLI.md` promises "the engine, session and flags are the same as
+ * one-shot mode".
+ */
+function checkPromptSession(): void {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-prompt-'))
+  const user = `prompt${process.pid}`
+  const script = [
+    `create-account --username=${user} --password=${PASS} --pin=${PIN}`,
+    'account-info',
+    'logout',
+    'engine-stop',
+    ''
+  ].join('\n')
+  const run = spawnSync('node', [...CLI, '--fake', `--directory=${dir}`], {
+    encoding: 'utf8',
+    input: script
+  })
+  const out = (run.stdout ?? '') + (run.stderr ?? '')
+  // `account-info` needs a session, so it is the assertion: it only answers
+  // when the login the prompt just performed reached the context the prompt
+  // itself reads.
+  const loggedIn = /"loggedIn":\s*true/.test(out)
+  const refused = out.includes('Please log in first')
+  if (loggedIn && !refused) {
+    passes++
+    console.log('OK   a login inside the prompt is visible to the next command')
+  } else {
+    failures++
+    console.error(
+      `FAIL a login inside the prompt is visible to the next command — ${out
+        .replace(/\s+/g, ' ')
+        .slice(0, 200)}`
+    )
+  }
+  // The prompt's own `engine-stop` is answered before the engine finishes
+  // tearing down, so wait for its run directory to go rather than leaving one
+  // behind on every run — which is the pile `sweepStaleProfiles` exists to
+  // stop accumulating.
+  const root = runRoot()
+  const before = new Set(readDirSafe(root))
+  const deadline = Date.now() + 10_000
+  while (Date.now() < deadline) {
+    const mine = readDirSafe(root).filter(name => !before.has(name))
+    if (mine.length === 0) break
+    spawnSync('sleep', ['0.1'])
+  }
+  fs.rmSync(dir, { recursive: true, force: true })
+}
+
+/** Directory entries, or none when the directory is not there. */
+function readDirSafe(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+function main(): void {
+  fs.mkdirSync(DIR, { recursive: true })
+  try {
+    const status = ok('engine-status', 'engine-status')
+    // Taken from the engine rather than recomputed, so the leak check below
+    // cannot drift from however the client resolves appId and login server.
+    const socketMatch = /"socketPath":\s*"([^"]+)"/.exec(status.out)
+    if (socketMatch != null) runProfileDir = path.dirname(socketMatch[1])
+    ok('engine-config', 'engine-config')
+    ok('engine-sessions', 'engine-sessions')
+    ok('check-password-rules', 'check-password-rules', `--password=${PASS}`)
+    ok('fix-username', 'fix-username', '--username=Mixed Case')
+
+    // ---------------------------------------------------------- account
+    ok(
+      'create-account',
+      'create-account',
+      `--username=${USER}`,
+      `--password=${PASS}`,
+      `--pin=${PIN}`
+    )
+    ok('account-info', 'account-info')
+    ok('local-users', 'local-users')
+    // Two more published codes nothing produced. They cost nothing offline.
+    refuses(
+      'forget-account for an unknown local user',
+      'USER_NOT_FOUND',
+      'forget-account',
+      '--root-login-id=nosuchuser'
+    )
+    refuses(
+      'cancel-request for an unknown pending login',
+      'PENDING_LOGIN_NOT_FOUND',
+      'cancel-request',
+      'pending_nosuchhandle'
+    )
+    ok('get-login-key', 'get-login-key')
+    ok('touch', 'touch')
+    ok('sync', 'sync')
+    ok('wait-for-all-wallets', 'wait-for-all-wallets')
+    ok('pending-vouchers', 'pending-vouchers')
+    ok('local-settings read', 'local-settings')
+    ok('local-settings write', 'local-settings', '--spam-filter-on=true')
+    ok('help', 'help', 'balance-map')
+
+    // ------------------------------------------------------ credentials
+    ok('check-password', 'check-password', `--password=${PASS}`)
+    ok('get-pin', 'get-pin')
+    ok('check-pin', 'check-pin', `--pin=${PIN}`)
+    ok('change-pin', 'change-pin', '--pin=2222')
+    ok('check-pin after change', 'check-pin', '--pin=2222')
+    // Every login method, each exercised while its credential still exists.
+    const key = ok('get-login-key for re-login', 'get-login-key')
+    ok('logout before login-with-key', 'logout')
+    ok(
+      'login-with-key',
+      'login-with-key',
+      `--username-or-login-id=${USER}`,
+      `--login-key=${String(key.json?.loginKey ?? '')}`
+    )
+    ok('logout before login-with-pin', 'logout')
+    ok(
+      'login-with-pin',
+      'login-with-pin',
+      `--username-or-login-id=${USER}`,
+      '--pin=2222'
+    )
+    ok('delete-pin', 'delete-pin')
+    ok('change-password', 'change-password', '--password=Zq7WmT4rNs2xVb9d')
+    const rec = ok(
+      'change-recovery',
+      'change-recovery',
+      '--question=First pet?',
+      '--answer=rex',
+      '--question=First street?',
+      '--answer=oak'
+    )
+    ok(
+      'fetch-recovery-questions',
+      'fetch-recovery-questions',
+      `--recovery-key=${String(rec.json?.recoveryKey ?? '')}`,
+      `--username=${USER}`
+    )
+    ok('logout before login-with-recovery', 'logout')
+    ok(
+      'login-with-recovery',
+      'login-with-recovery',
+      `--username=${USER}`,
+      `--recovery-key=${String(rec.json?.recoveryKey ?? '')}`,
+      '--answer=rex',
+      '--answer=oak'
+    )
+    ok('delete-recovery', 'delete-recovery')
+
+    // -------------------------------------------------------------- otp
+    ok('otp-key before enabling', 'otp-key')
+    ok('enable-otp', 'enable-otp')
+    // A number in a JSON body arrives as the flag's raw text, so this used
+    // to be `BAD_REQUEST: Expected a number, got "604800" at .timeout` and
+    // the flag the help advertises could never be used.
+    ok('enable-otp with a timeout', 'enable-otp', '--timeout=604800')
+    const otpKey = ok('otp-key', 'otp-key')
+    ok(
+      'repair-otp',
+      'repair-otp',
+      `--otp-key=${String(otpKey.json?.otpKey ?? '')}`
+    )
+    ok('disable-otp', 'disable-otp')
+
+    // -------------------------------------------------------- data store
+    ok('set-item', 'set-item', '--store-id=probe', '--item-id=a', '--value=1')
+    ok('list-store-ids', 'list-store-ids')
+    ok('list-item-ids', 'list-item-ids', '--store-id=probe')
+    ok('get-item', 'get-item', '--store-id=probe', '--item-id=a')
+    ok('delete-item', 'delete-item', '--store-id=probe', '--item-id=a')
+    ok('delete-store', 'delete-store', '--store-id=probe')
+
+    // ----------------------------------------------------------- wallets
+    const made = ok(
+      'create-currency-wallet',
+      'create-currency-wallet',
+      '--wallet-type=wallet:bitcoin',
+      '--name=Fake BTC'
+    )
+    const walletId: string = made.json?.walletId ?? ''
+    const w = `--wallet-id=${walletId}`
+
+    ok('currency-wallets', 'currency-wallets')
+    ok('wallet-info', 'wallet-info', w)
+    ok('all-keys', 'all-keys')
+    ok('get-wallet-info', 'get-wallet-info', `--id=${walletId}`)
+    ok('get-raw-public-key', 'get-raw-public-key', w)
+    ok('get-raw-private-key', 'get-raw-private-key', w)
+    ok('get-display-public-key', 'get-display-public-key', w)
+    ok('get-display-private-key', 'get-display-private-key', w)
+    ok('list-splittable-wallet-types', 'list-splittable-wallet-types', w)
+    ok('rename-wallet', 'rename-wallet', w, '--name=Renamed')
+    ok(
+      'set-fiat-currency-code',
+      'set-fiat-currency-code',
+      w,
+      '--fiat-currency-code=iso:EUR'
+    )
+    ok('change-paused on', 'change-paused', w, '--paused=true')
+    ok('change-paused off', 'change-paused', w, '--paused=false')
+    ok('change-wallet-states', 'change-wallet-states', w, '--archived=true')
+    ok(
+      'change-wallet-states off',
+      'change-wallet-states',
+      w,
+      '--archived=false'
+    )
+    // The fake sync server accepts hash-suffixed wallet-repo routes as of
+    // core 2.49.0, so a wallet sync completes with no network.
+    ok('wallet-sync', 'wallet-sync', w)
+    ok('dump-data', 'dump-data', w)
+    ok('balance-map', 'balance-map', w)
+    ok('get-addresses', 'get-addresses', w)
+    ok('wallet-tokens', 'wallet-tokens', w)
+    // `--remove` of a token that is not enabled leaves the set as it is,
+    // which exercises the read-modify-write path without needing a token.
+    ok(
+      'change-enabled-token-ids',
+      'change-enabled-token-ids',
+      w,
+      '--remove=notatoken'
+    )
+    ok('get-num-transactions', 'get-num-transactions', w)
+    ok('get-transactions', 'get-transactions', w)
+
+    // A key that is a member of `Object.prototype` is caller input like any
+    // other. `wallets['__proto__']` is truthy and
+    // `allTokens['__proto__'] == null` is false, so every guard that exists
+    // to answer 404 was skipped and the `TypeError` that followed surfaced
+    // as 500 with no field name.
+    refuses(
+      'a prototype key as a walletId',
+      'WALLET_NOT_FOUND',
+      'get-transactions',
+      '--wallet-id=__proto__'
+    )
+    refuses(
+      'a prototype key as a tokenId',
+      'TOKEN_NOT_FOUND',
+      'get-transactions',
+      w,
+      '--token-id=__proto__'
+    )
+    refuses(
+      'constructor as a walletId',
+      'WALLET_NOT_FOUND',
+      'get-transactions',
+      '--wallet-id=constructor'
+    )
+    // `limit` and `offset` index an array, so a negative one returned a
+    // silently wrong page beside an unchanged `total`.
+    refuses(
+      'a negative limit',
+      'BAD_REQUEST',
+      'get-transactions',
+      w,
+      '--limit=-1'
+    )
+    refuses(
+      'a negative offset',
+      'BAD_REQUEST',
+      'get-transactions',
+      w,
+      '--offset=-1'
+    )
+
+    // The export mode had no coverage at all: not the format-list parse, not
+    // the `bitwaveAccountId` guards, and not the branch that *writes* the
+    // wallet's synced `exportTxInfo.json`.
+    const exportDir = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-export-'))
+    ok(
+      'get-transactions --export-format=csv',
+      'get-transactions',
+      w,
+      '--export-format=csv',
+      `--out=${path.join(exportDir, 'tx.csv')}`
+    )
+    ok(
+      'get-transactions with two export formats',
+      'get-transactions',
+      w,
+      '--export-format=csv,qbo',
+      `--out=${path.join(exportDir, 'tx')}`
+    )
+    refuses(
+      'an unknown export format',
+      'USAGE',
+      'get-transactions',
+      w,
+      '--export-format=notaformat'
+    )
+    refuses(
+      'bitwave with no account id',
+      'MISSING_BITWAVE_ACCOUNT_ID',
+      'get-transactions',
+      w,
+      '--export-format=bitwave',
+      `--out=${path.join(exportDir, 'tx.csv')}`
+    )
+    refuses(
+      'a bitwave account id without the bitwave format',
+      'USAGE',
+      'get-transactions',
+      w,
+      '--export-format=csv',
+      '--bitwave-account=acct',
+      `--out=${path.join(exportDir, 'tx.csv')}`
+    )
+    ok(
+      'bitwave with an account id, saving the preference',
+      'get-transactions',
+      w,
+      '--export-format=bitwave',
+      '--bitwave-account=acct',
+      '--save-export-prefs',
+      `--out=${path.join(exportDir, 'bw.csv')}`
+    )
+    // The saved id is what the next call falls back to, which is the whole
+    // point of writing it.
+    ok(
+      'bitwave reuses the saved account id',
+      'get-transactions',
+      w,
+      '--export-format=bitwave',
+      `--out=${path.join(exportDir, 'bw2.csv')}`
+    )
+    fs.rmSync(exportDir, { recursive: true, force: true })
+    // A tokenId is free-form caller input over REST, where in the GUI it
+    // always came from a real token. Unvalidated, each of these destructured
+    // an absent token inside core and answered 500 INTERNAL_ERROR with no
+    // field name, outside every error list the routes declare.
+    refuses(
+      'get-transactions with an unknown tokenId',
+      'TOKEN_NOT_FOUND',
+      'get-transactions',
+      w,
+      '--token-id=notatoken'
+    )
+    refuses(
+      'get-num-transactions with an unknown tokenId',
+      'TOKEN_NOT_FOUND',
+      'get-num-transactions',
+      w,
+      '--token-id=notatoken'
+    )
+    refuses(
+      'get-addresses with an unknown tokenId',
+      'TOKEN_NOT_FOUND',
+      'get-addresses',
+      w,
+      '--token-id=notatoken'
+    )
+    refuses(
+      'get-max-spendable with an unknown tokenId',
+      'TOKEN_NOT_FOUND',
+      'get-max-spendable',
+      w,
+      '--token-id=notatoken',
+      '--to=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7'
+    )
+    ok(
+      'encode-uri',
+      'encode-uri',
+      w,
+      '--public-address=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7'
+    )
+    ok(
+      'parse-uri',
+      'parse-uri',
+      w,
+      '--uri=bitcoin:bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7?amount=0.001'
+    )
+
+    // An empty wallet cannot fund a spend, and saying so is the correct
+    // answer — it proves the spend path runs, not just that it errors.
+    refuses(
+      'make-spend on an empty wallet',
+      'INSUFFICIENT_FUNDS',
+      'make-spend',
+      w,
+      '--to=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7',
+      '--native-amount=100000'
+    )
+
+    // A caller-supplied `spendInfo` is free-form input over REST, and core
+    // silently drops a target with no `publicAddress` — so before this was
+    // checked, the first of these signed and broadcast a *one-output*
+    // transaction and answered 200. All three must be refused before the
+    // wallet's balance is ever consulted, which is why an empty wallet
+    // answering BAD_REQUEST rather than INSUFFICIENT_FUNDS is the assertion.
+    refuses(
+      'make-spend with a target missing publicAddress',
+      'BAD_REQUEST',
+      'make-spend',
+      w,
+      '--spend-info={"tokenId":null,"spendTargets":[{"publicAddress":"bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7","nativeAmount":"1"},{"nativeAmount":"2"}]}'
+    )
+    refuses(
+      'make-spend with a misspelled publicAddress field',
+      'BAD_REQUEST',
+      'make-spend',
+      w,
+      '--spend-info={"tokenId":null,"spendTargets":[{"publicAdress":"bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7","nativeAmount":"1"}]}'
+    )
+    refuses(
+      'spend with a target missing nativeAmount',
+      'BAD_REQUEST',
+      'spend',
+      w,
+      '--spend-info={"tokenId":null,"spendTargets":[{"publicAddress":"bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7"}]}'
+    )
+
+    // ------------------------------------------------- local / no server
+    ok('currency-configs', 'currency-configs')
+    ok('admin-hash-username', 'admin-hash-username', `--username=${USER}`)
+    ok('create-wallet', 'create-wallet', '--type=wallet:bitcoin')
+    ok(
+      'create-currency-wallets',
+      'create-currency-wallets',
+      '--create-wallets=[{"walletType":"wallet:bitcoin","name":"Batch"}]'
+    )
+    ok('split', 'split', w, '--split-wallets=[]')
+    ok('resync-blockchain', 'resync-blockchain', w)
+    // No transaction exists to annotate, and saying so proves the path runs.
+    refusesInternal(
+      'save-tx-metadata for an unknown txid',
+      'missing tx',
+      'save-tx-metadata',
+      w,
+      '--txid=deadbeef',
+      '--token-id=null',
+      '--metadata={"name":"x"}'
+    )
+    refusesInternal(
+      'save-tx-action for an unknown txid',
+      'missing tx',
+      'save-tx-action',
+      w,
+      '--txid=deadbeef',
+      '--token-id=null',
+      // A complete `EdgeTxActionSwap`. `{"actionType":"swap"}` alone used to
+      // reach core, because the field was declared `asCoreValue` and cast;
+      // it is now refused for the missing `swapInfo` before it can be
+      // written into the synced transaction file.
+      `--saved-action=${JSON.stringify({
+        actionType: 'swap',
+        swapInfo: {
+          pluginId: 'fakeswap',
+          displayName: 'Fake Swap',
+          supportEmail: 'support@example.com'
+        },
+        fromAsset: { pluginId: 'bitcoin', tokenId: null },
+        toAsset: { pluginId: 'bitcoin', tokenId: null },
+        payoutAddress: 'bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7',
+        payoutWalletId: w
+      })}`
+    )
+    refuses(
+      'save-tx-action with an incomplete savedAction',
+      'BAD_REQUEST',
+      'save-tx-action',
+      w,
+      '--txid=deadbeef',
+      '--saved-action={"actionType":"swap"}'
+    )
+    refuses(
+      'save-tx-metadata with a non-object metadata',
+      'BAD_REQUEST',
+      'save-tx-metadata',
+      w,
+      '--txid=deadbeef',
+      '--metadata=[]'
+    )
+
+    // ------------------------------------------------------ login server
+    ok('fetch-login-messages', 'fetch-login-messages')
+    notInFakeWorld('fetch-challenge', 'Unknown API endpoint', 'fetch-challenge')
+    ok(
+      'change-username',
+      'change-username',
+      `--username=${USER}b`,
+      '--password=Zq7WmT4rNs2xVb9d'
+    )
+    // 2FA was disabled above, so refusing is the correct answer.
+    refusesInternal(
+      'cancel-otp-reset with 2FA off',
+      'not enabled',
+      'cancel-otp-reset'
+    )
+
+    // ------------------------------------------------- object handles
+    const pending = ok('request-edge-login', 'request-edge-login', '--no-wait')
+    const pendingId: string = pending.json?.pendingId ?? ''
+    const lobbyId: string = pending.json?.lobbyId ?? ''
+    ok('poll-edge-login', 'poll-edge-login', pendingId)
+    // A pending edge login belongs to no session — there is no session until
+    // the login completes — so it is reachable through the un-scoped
+    // `poll-edge-login` and `cancel-request` above and below, and *not*
+    // through the account-scoped object routes. Skipping the ownership
+    // comparison for an owner-less handle let any logged-in session read
+    // another's pending login out of `object-get` and cancel it through
+    // `object-delete`.
+    refuses(
+      'object-get on a handle that belongs to no session',
+      'OBJECT_SESSION_MISMATCH',
+      'object-get',
+      pendingId
+    )
+    ok('fetch-lobby', 'fetch-lobby', lobbyId)
+    ok('approve-login-request', 'approve-login-request', lobbyId)
+    ok('cancel-request', 'cancel-request', pendingId)
+
+    // ------------------------------------------------------------ admin
+    // Seconds, converted to the milliseconds core takes, with a floor: zero
+    // polled Edge's production login server as fast as it would answer.
+    ok(
+      'admin-make-lobby with a period',
+      'admin-make-lobby',
+      '--period-seconds=30'
+    )
+    refuses(
+      'admin-make-lobby with a zero period',
+      'BAD_REQUEST',
+      'admin-make-lobby',
+      '--period-seconds=0'
+    )
+    const lobby = ok('admin-make-lobby', 'admin-make-lobby')
+    const handle: string = lobby.json?.objectId ?? ''
+    ok(
+      'admin-fetch-lobby-request',
+      'admin-fetch-lobby-request',
+      lobby.json?.lobbyId ?? ''
+    )
+    ok('admin-lobby-handle-delete', 'admin-lobby-handle-delete', handle)
+
+    // ------------------------------------------------- refusals that prove
+    // the path runs even though the fake world cannot fund a wallet
+    ok(
+      'get-max-spendable',
+      'get-max-spendable',
+      w,
+      '--to=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7'
+    )
+    refuses(
+      'sign-tx with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'sign-tx',
+      'tx_nosuchhandle'
+    )
+    refuses(
+      'broadcast-tx with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'broadcast-tx',
+      'tx_nosuchhandle'
+    )
+    refuses(
+      'save-tx with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'save-tx',
+      'tx_nosuchhandle'
+    )
+    refuses(
+      'object-delete with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'object-delete',
+      'tx_nosuchhandle'
+    )
+    refuses(
+      'swap-quote-get with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'swap-quote-get',
+      'swap_nosuchhandle'
+    )
+
+    // --------------------------------------------------- signing / admin
+    const addr = ok(
+      'get-addresses for signing',
+      'get-addresses',
+      w,
+      '--token-id=null'
+    )
+    const publicAddress: string = addr.json?.addresses?.[0]?.publicAddress ?? ''
+    ok(
+      'sign-bytes',
+      'sign-bytes',
+      w,
+      '--bytes=aGVsbG8=',
+      `--other-params={"publicAddress":"${publicAddress}"}`
+    )
+    ok(
+      'admin-auth-request',
+      'admin-auth-request',
+      '--method=POST',
+      '--path=/v2/messages',
+      '--body={"loginIds":[]}'
+    )
+
+    // These need state the fake world cannot produce, so the refusal is what
+    // proves the route runs at all.
+    // Core accepts any voucher id without complaint, so success here is the
+    // engine reporting core faithfully, not the voucher having existed.
+    ok('approve-voucher', 'approve-voucher', '--voucher-id=nosuchvoucher')
+    ok('reject-voucher', 'reject-voucher', '--voucher-id=nosuchvoucher')
+    refuses(
+      'request-otp-reset with a bad token',
+      'PASSWORD_ERROR',
+      'request-otp-reset',
+      `--username=${USER}b`,
+      '--otp-reset-token=nosuchtoken'
+    )
+    refuses(
+      'admin-repo-get with a bad key',
+      'INTERNAL_ERROR',
+      'admin-repo-get',
+      '11111111111111111111',
+      '--data-key=11111111111111111111',
+      '--path=x'
+    )
+    // Succeeds with an empty listing: a repo nobody has written to is not
+    // an error to list. The check used to pass a `--sync-key` flag that does
+    // not exist, so it never reached the route at all — and `refuses(...,
+    // 'error')` accepted the resulting usage envelope.
+    ok(
+      'admin-repo-list on an unwritten repo is empty',
+      'admin-repo-list',
+      '11111111111111111111',
+      '--data-key=11111111111111111111'
+    )
+    refuses(
+      'admin-repo-set with a bad key',
+      'INTERNAL_ERROR',
+      'admin-repo-set',
+      '11111111111111111111',
+      '--data-key=11111111111111111111',
+      '--path=x',
+      '--text=y'
+    )
+    // Also succeeds: deleting a path that is not there is a no-op, which is
+    // what disklet's `delete` does. Same wrong-flag history as the listing
+    // above.
+    ok(
+      'admin-repo-delete of an absent path is a no-op',
+      'admin-repo-delete',
+      '11111111111111111111',
+      '--data-key=11111111111111111111',
+      '--path=x'
+    )
+    refuses(
+      'admin-sync-repo with a bad key',
+      'INTERNAL_ERROR',
+      'admin-sync-repo',
+      '11111111111111111111'
+    )
+    refuses(
+      'admin-send-lobby-reply to an unknown lobby',
+      'INTERNAL_ERROR',
+      'admin-send-lobby-reply',
+      'nosuchlobby',
+      '--lobby-request={}'
+    )
+    refuses(
+      'spend with save but no broadcast',
+      'BAD_REQUEST',
+      'spend',
+      w,
+      '--to=bc1qnotarealaddressatall',
+      '--native-amount=1000',
+      '--broadcast=false',
+      '--save=true'
+    )
+    refuses(
+      'spend on an empty wallet',
+      'INSUFFICIENT_FUNDS',
+      'spend',
+      w,
+      '--to=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7',
+      '--native-amount=100000'
+    )
+    refuses(
+      'spend-max on an empty wallet',
+      'INSUFFICIENT_FUNDS',
+      'spend-max',
+      w,
+      '--to=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7'
+    )
+    refuses(
+      'sweep-private-keys with no funds',
+      'INTERNAL_ERROR',
+      'sweep-private-keys',
+      w,
+      '--spend-info={"tokenId":null,"privateKeys":["x"]}'
+    )
+    refuses(
+      'accelerate an unknown transaction',
+      'OBJECT_NOT_FOUND',
+      'accelerate',
+      w,
+      '--object-id=tx_nosuchhandle'
+    )
+
+    // Rates, swap quotes and payment requests reach third-party APIs over the
+    // real internet, which the fake world does not intercept. They belong to
+    // `npm run test:cli:network`, not to a hook that must work offline.
+    refuses(
+      'approve-swap-quote with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'approve-swap-quote',
+      'swap_nosuchhandle'
+    )
+    refuses(
+      'close-swap-quote with an unknown handle',
+      'OBJECT_NOT_FOUND',
+      'close-swap-quote',
+      'swap_nosuchhandle'
+    )
+
+    // ------------------------------------------------------------- login
+    ok('logout', 'logout')
+    ok(
+      'login-with-password',
+      'login-with-password',
+      `--username=${USER}b`,
+      '--password=Zq7WmT4rNs2xVb9d'
+    )
+    ok('username-available', 'username-available', `--username=${USER}nobody`)
+    // Core refuses while the account is open, which is the interesting half
+    // of the contract; forgetting it for real would end the session the rest
+    // of this suite still needs.
+    refusesInternal(
+      'forget-account while logged in',
+      'Cannot remove logged-in user',
+      'forget-account',
+      `--root-login-id=${USER}b`
+    )
+
+    // Last, because it leaves the account with no password to log in with.
+    ok('delete-password', 'delete-password')
+
+    // ---------------------------------------------------------- teardown
+    // The fake login server implements no /api/v2/login/delete.
+    notInFakeWorld(
+      'delete-remote-account',
+      'Unknown API endpoint',
+      'delete-remote-account',
+      '--yes'
+    )
+    ok('engine-stop', 'engine-stop')
+  } finally {
+    cli('engine-stop')
+    // A clean stop must leave nothing behind in `~/.edge-cli/run`. Every run
+    // of this suite uses a fresh data directory and therefore a fresh profile
+    // hash, so a leak here is permanent — and each leaked directory may
+    // still hold a `session.json`, which is a bearer token.
+    if (runProfileDir != null) {
+      // `engine-stop` answers *before* the teardown finishes — it has to, or
+      // the caller would wait out the drain — so the directory goes away a
+      // moment later. Poll rather than assert immediately, or this check
+      // fails on whichever run the shutdown happens to be slowest.
+      const deadline = Date.now() + 10_000
+      while (fs.existsSync(runProfileDir) && Date.now() < deadline) {
+        spawnSync('sleep', ['0.1'])
+      }
+      if (!fs.existsSync(runProfileDir)) {
+        passes++
+        console.log('OK   engine-stop leaves no profile directory behind')
+      } else {
+        failures++
+        console.error(
+          `FAIL engine-stop leaves no profile directory behind — ${runProfileDir} still holds ${fs
+            .readdirSync(runProfileDir)
+            .join(', ')}`
+        )
+      }
+    }
+    fs.rmSync(DIR, { recursive: true, force: true })
+  }
+
+  checkPromptSession()
+
+  console.log(`\ntestCliFake: ${passes} passed, ${failures} failed`)
+  if (failures > 0) process.exit(1)
+}
+
+main()
diff --git a/scripts/testCliSubscribe.ts b/scripts/testCliSubscribe.ts
new file mode 100644
index 00000000000..781892b0e5d
--- /dev/null
+++ b/scripts/testCliSubscribe.ts
@@ -0,0 +1,543 @@
+/**
+ * Proves the subscribe/one-shot concurrency contract against a real engine:
+ *
+ *   1. A subscriber holds the engine open even with no account logged in.
+ *   2. One-shot commands run normally while a subscriber is attached.
+ *   3. The idle timer re-arms once the last subscriber detaches.
+ *   4. Stopping the engine closes the stream with a reason and exit code 7.
+ *   5. Ctrl-C during a cold start still ends the process, rather than opening
+ *      the stream once the engine finally answers and holding it forever.
+ *   6. A `sessionId`-scoped stream is closed by that session's logout, while
+ *      an unscoped one survives it.
+ *   7. The idle timer re-arms on the *same* engine when the last subscriber
+ *      detaches, which is the path claim 3 is actually about.
+ *   8. The loopback TCP listener answers the same thing the unix socket does,
+ *      and binds loopback rather than every interface.
+ *
+ * Uses its own --directory so it never touches a developer's live engine, and
+ * the fake world so the contract holds without an Edge API key or a network.
+ *
+ *   node -r sucrase/register scripts/testCliSubscribe.ts
+ */
+import { type ChildProcess, spawn, spawnSync } from 'child_process'
+import fs from 'fs'
+import http from 'http'
+import os from 'os'
+import path from 'path'
+
+import { CLI, runRoot } from './util/cliHarness'
+
+const DIR = path.join(os.tmpdir(), `edge-cli-subscribe-${process.pid}`)
+const BASE = ['--fake', `--directory=${DIR}`]
+
+let failures = 0
+/**
+ * The TCP bearer token the engine minted, read the way a script would.
+ *
+ * Black-box on purpose: rather than recompute `profileHash`, this scans the
+ * run root for the engine whose run file names this port. The token lives
+ * only in that `0600` file, which is what authorises a TCP caller.
+ */
+function readTcpToken(port: number): string | null {
+  const root = runRoot()
+  let names: string[] = []
+  try {
+    names = fs.readdirSync(root)
+  } catch {
+    return null
+  }
+  for (const name of names) {
+    try {
+      const raw = fs.readFileSync(path.join(root, name, 'engine.json'), 'utf8')
+      const parsed = JSON.parse(raw)
+      if (parsed?.tcpPort === port && typeof parsed?.tcpToken === 'string') {
+        return parsed.tcpToken
+      }
+    } catch {
+      // Not this profile's run file, or it is mid-write.
+    }
+  }
+  return null
+}
+
+function check(label: string, ok: boolean, detail = ''): void {
+  if (ok) console.log(`OK   ${label}`)
+  else {
+    failures++
+    console.error(`FAIL ${label}${detail !== '' ? ` — ${detail}` : ''}`)
+  }
+}
+
+function cli(...args: string[]): { status: number; out: string } {
+  const result = spawnSync('node', [...CLI, ...BASE, ...args], {
+    encoding: 'utf8'
+  })
+  return { status: result.status ?? -1, out: result.stdout + result.stderr }
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function main(): Promise<void> {
+  fs.mkdirSync(DIR, { recursive: true })
+
+  const status = cli('engine-status')
+  check('engine starts', status.status === 0, status.out.slice(0, 200))
+
+  // The two scope flags the route declares and the published usage line
+  // advertises. The hand-written command accepted only `--type`, so these
+  // died at the parser with `Unknown option` and exit 2 — the account-scoped
+  // stream the engine supports had no CLI path at all. An unknown session is
+  // the right refusal here; `Unknown option` is not.
+  const sessionFlag = cli('subscribe', '--session-id=sess_nosuchsession')
+  check(
+    'subscribe accepts --session-id',
+    sessionFlag.status !== 2 && !sessionFlag.out.includes('Unknown option'),
+    sessionFlag.out.slice(0, 200)
+  )
+  const walletFlag = cli(
+    'subscribe',
+    '--session-id=sess_nosuchsession',
+    '--wallet-id=w'
+  )
+  check(
+    'subscribe accepts --wallet-id',
+    walletFlag.status !== 2 && !walletFlag.out.includes('Unknown option'),
+    walletFlag.out.slice(0, 200)
+  )
+
+  let subOut = ''
+  const sub: ChildProcess = spawn('node', [...CLI, ...BASE, 'subscribe'], {
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+  sub.stdout?.on('data', d => (subOut += String(d)))
+  sub.stderr?.on('data', d => (subOut += String(d)))
+  const subExit = new Promise<number>(resolve => {
+    sub.on('exit', code => {
+      resolve(code ?? -1)
+    })
+  })
+  await sleep(2500)
+
+  const held = cli('engine-status')
+  check(
+    'a subscriber holds off idle shutdown',
+    /"idleShutdownAt":\s*null/.test(held.out) &&
+      /"sessionCount":\s*0/.test(held.out),
+    held.out.slice(0, 200)
+  )
+
+  const concurrent = cli('local-users')
+  check(
+    'one-shot commands run while subscribed',
+    concurrent.status === 0 && concurrent.out.includes('localUsers'),
+    concurrent.out.slice(0, 200)
+  )
+
+  const stopped = cli('engine-stop')
+  check('engine-stop succeeds', stopped.status === 0, stopped.out.slice(0, 200))
+
+  const code = await Promise.race([subExit, sleep(8000).then(() => -2)])
+  check('subscriber exits when the engine stops', code === 7, `exit ${code}`)
+  check(
+    'subscriber is told why the stream ended',
+    subOut.includes('engineShutdown'),
+    subOut.slice(0, 300)
+  )
+
+  // A session-scoped stream has to be closed by that session's logout. Every
+  // client used to be context-scoped, so `closeScope` matched nothing and the
+  // published reference promised a teardown that could not happen.
+  const scoped = await (async (): Promise<string> => {
+    const created = cli(
+      'create-account',
+      `--username=sub${process.pid}`,
+      '--password=Aa1!aaaaaa',
+      '--pin=1234'
+    )
+    check(
+      'create-account for the scope check',
+      created.status === 0,
+      created.out.slice(0, 200)
+    )
+    const statusOut = cli('engine-status').out
+    const socketPath = /"socketPath":\s*"([^"]+)"/.exec(statusOut)?.[1] ?? ''
+    const sessionId = JSON.parse(
+      fs.readFileSync(
+        path.join(path.dirname(socketPath), 'session.json'),
+        'utf8'
+      )
+    ).sessionId as string
+
+    let frames = ''
+    await new Promise<void>(resolve => {
+      const req = http.request(
+        {
+          socketPath,
+          method: 'GET',
+          path: `/engine/events?sessionId=${sessionId}`,
+          headers: { Accept: 'text/event-stream' }
+        },
+        res => {
+          res.setEncoding('utf8')
+          res.on('data', (chunk: string) => {
+            frames += chunk
+          })
+          res.on('end', resolve)
+        }
+      )
+      req.on('error', () => {
+        resolve()
+      })
+      req.end()
+      // Give the stream a moment to open, then log out underneath it.
+      setTimeout(() => {
+        cli('logout')
+      }, 1000)
+      setTimeout(() => {
+        req.destroy()
+        resolve()
+      }, 6000)
+    })
+    return frames
+  })()
+  check(
+    'a session-scoped stream is closed by that session logging out',
+    scoped.includes('subscription.closed') &&
+      scoped.includes('"reason":"logout"'),
+    scoped.replace(/\s+/g, ' ').slice(0, 200)
+  )
+
+  // Ctrl-C while the engine is still spawning. The abort lands before the
+  // stream request exists, so it is only observable by re-checking the signal
+  // on the second attempt; without that, `subscribe` opened the stream after
+  // the spawn and swallowed every later signal.
+  const coldDir = `${DIR}-cold`
+  fs.mkdirSync(coldDir, { recursive: true })
+  const cold: ChildProcess = spawn(
+    'node',
+    [...CLI, '--fake', `--directory=${coldDir}`, 'subscribe'],
+    { stdio: ['ignore', 'pipe', 'pipe'] }
+  )
+  const coldExit = new Promise<string>(resolve => {
+    cold.on('exit', (code, signal) => {
+      // Either outcome is a prompt exit. Under load the signal can arrive
+      // before `subscribe` has registered its handler, and Node's own
+      // terminate-on-SIGINT takes it — which is equally fine, and is why this
+      // accepts a signalled exit rather than only codes 0 and 130.
+      resolve(signal != null ? `signal ${signal}` : `code ${code ?? -1}`)
+    })
+  })
+  await sleep(300)
+  cold.kill('SIGINT')
+  const coldCode = await Promise.race([
+    coldExit,
+    sleep(15000).then(() => 'HUNG')
+  ])
+  check(
+    'Ctrl-C during a cold start exits',
+    coldCode === 'code 0' ||
+      coldCode === 'code 130' ||
+      coldCode === 'signal SIGINT',
+    coldCode
+  )
+  spawnSync('node', [...CLI, '--fake', `--directory=${coldDir}`, 'engine-stop'])
+  fs.rmSync(coldDir, { recursive: true, force: true })
+
+  // Claim 3, on the *same* engine. Asserting it against a fresh engine
+  // started after `engine-stop` never executed the path the contract is
+  // about: `EventHub.onClientsChanged` -> `IdleShutdown.notifySubscribersChanged`
+  // when the last subscriber detaches.
+  const detachDir = `${DIR}-detach`
+  fs.mkdirSync(detachDir, { recursive: true })
+  const detachBase = ['--fake', `--directory=${detachDir}`]
+  const detachCli = (...args: string[]): { status: number; out: string } => {
+    const result = spawnSync('node', [...CLI, ...detachBase, ...args], {
+      encoding: 'utf8'
+    })
+    return { status: result.status ?? -1, out: result.stdout + result.stderr }
+  }
+  detachCli('engine-status')
+  const detachSub: ChildProcess = spawn(
+    'node',
+    [...CLI, ...detachBase, 'subscribe'],
+    { stdio: ['ignore', 'pipe', 'pipe'] }
+  )
+  detachSub.stdout?.resume()
+  detachSub.stderr?.resume()
+  const detachExit = new Promise<number>(resolve => {
+    detachSub.on('exit', code => {
+      resolve(code ?? -1)
+    })
+  })
+  await sleep(2500)
+  const whileHeld = detachCli('engine-status')
+  check(
+    'the idle timer is disarmed while a subscriber is attached',
+    /"idleShutdownAt":\s*null/.test(whileHeld.out),
+    whileHeld.out.slice(0, 200)
+  )
+
+  // Kill only the subscriber: the engine stays up.
+  detachSub.kill('SIGINT')
+  await Promise.race([detachExit, sleep(8000)])
+  await sleep(500)
+  const afterDetach = detachCli('engine-status')
+  check(
+    'the idle timer re-arms on the same engine when the last subscriber detaches',
+    /"idleShutdownAt":\s*"/.test(afterDetach.out),
+    afterDetach.out.slice(0, 200)
+  )
+  detachCli('engine-stop')
+  fs.rmSync(detachDir, { recursive: true, force: true })
+
+  // A fresh engine must re-arm its idle timer with no subscriber attached.
+  const rearmed = cli('engine-status')
+  check(
+    'idle timer re-arms with no subscriber',
+    /"idleShutdownAt":\s*"/.test(rearmed.out),
+    rearmed.out.slice(0, 200)
+  )
+  cli('engine-stop')
+
+  // The TCP transport is documented and published in the reference, and its
+  // only test needed tester servers, so it had no offline coverage at all.
+  const tcpDir = `${DIR}-tcp`
+  fs.mkdirSync(tcpDir, { recursive: true })
+  const tcpPort = 45700 + (process.pid % 200)
+  const tcpBase = ['--fake', `--directory=${tcpDir}`, `--tcp=${tcpPort}`]
+  const viaUnix = spawnSync('node', [...CLI, ...tcpBase, 'engine-status'], {
+    encoding: 'utf8'
+  })
+  check(
+    'an engine with --tcp still answers on its unix socket',
+    (viaUnix.status ?? -1) === 0,
+    (viaUnix.stdout + viaUnix.stderr).slice(0, 200)
+  )
+
+  /** One raw TCP request, with whatever headers the case is testing. */
+  const tcpRequest = async (
+    headers: Record<string, string>,
+    reqPath = '/engine/status'
+  ): Promise<{ status: number; raw: string }> =>
+    await new Promise(resolve => {
+      const req = http.request(
+        {
+          host: '127.0.0.1',
+          port: tcpPort,
+          method: 'GET',
+          path: reqPath,
+          headers
+        },
+        res => {
+          let raw = ''
+          res.setEncoding('utf8')
+          res.on('data', (chunk: string) => {
+            raw += chunk
+          })
+          res.on('end', () => {
+            resolve({ status: res.statusCode ?? 0, raw })
+          })
+        }
+      )
+      req.on('error', (error: Error) => {
+        resolve({ status: 0, raw: `ERROR ${error.message}` })
+      })
+      req.end()
+    })
+
+  const unauthorized = await tcpRequest({})
+  check(
+    'TCP refuses a request with no token',
+    unauthorized.status === 401 && unauthorized.raw.includes('UNAUTHORIZED'),
+    `status=${unauthorized.status} ${unauthorized.raw
+      .replace(/\s+/g, ' ')
+      .slice(0, 160)}`
+  )
+
+  const tcpToken = readTcpToken(tcpPort)
+  check(
+    'the run file carries a TCP token',
+    tcpToken != null && tcpToken.length >= 40,
+    String(tcpToken)
+  )
+
+  const wrongOrigin = await tcpRequest({
+    'X-Edge-Token': tcpToken ?? '',
+    Origin: 'https://evil.example'
+  })
+  check(
+    'TCP refuses a request carrying Origin',
+    wrongOrigin.status === 403 && wrongOrigin.raw.includes('FORBIDDEN'),
+    `status=${wrongOrigin.status}`
+  )
+
+  const wrongHost = await tcpRequest({
+    'X-Edge-Token': tcpToken ?? '',
+    Host: `evil.example:${tcpPort}`
+  })
+  check(
+    'TCP refuses a foreign Host header',
+    wrongHost.status === 403 && wrongHost.raw.includes('FORBIDDEN'),
+    `status=${wrongHost.status}`
+  )
+
+  // Three published codes the CLI client cannot produce, because it never
+  // makes a raw request: a wrong method, a wrong content type, and an
+  // oversized body. The gates check that a *declared* code is in the
+  // catalogue, never that a catalogued code can be produced, so these arms
+  // could rot silently.
+  const wrongMethod = await tcpRequest(
+    { 'X-Edge-Token': readTcpToken(tcpPort) ?? '' },
+    '/engine/stop'
+  )
+  check(
+    'TCP answers a wrong method with 405',
+    wrongMethod.status === 405 &&
+      wrongMethod.raw.includes('METHOD_NOT_ALLOWED'),
+    `status=${wrongMethod.status}`
+  )
+
+  const token = readTcpToken(tcpPort) ?? ''
+  const rawPost = async (
+    headers: Record<string, string>,
+    payload: string
+  ): Promise<{ status: number; raw: string }> =>
+    await new Promise(resolve => {
+      const req = http.request(
+        {
+          host: '127.0.0.1',
+          port: tcpPort,
+          method: 'POST',
+          path: '/rates/query',
+          headers: { 'X-Edge-Token': token, ...headers }
+        },
+        res => {
+          let raw = ''
+          res.setEncoding('utf8')
+          res.on('data', (chunk: string) => {
+            raw += chunk
+          })
+          res.on('end', () => {
+            resolve({ status: res.statusCode ?? 0, raw })
+          })
+        }
+      )
+      req.on('error', (error: Error) => {
+        resolve({ status: 0, raw: `ERROR ${error.message}` })
+      })
+      req.write(payload)
+      req.end()
+    })
+
+  const wrongType = await rawPost({ 'Content-Type': 'text/plain' }, '{}')
+  check(
+    'TCP answers a non-JSON content type with 415',
+    wrongType.status === 415 &&
+      wrongType.raw.includes('UNSUPPORTED_MEDIA_TYPE'),
+    `status=${wrongType.status}`
+  )
+
+  const tcpStatus = await new Promise<string>(resolve => {
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port: tcpPort,
+        method: 'GET',
+        path: '/engine/status',
+        headers: { 'X-Edge-Token': tcpToken ?? '' }
+      },
+      res => {
+        let raw = ''
+        res.setEncoding('utf8')
+        res.on('data', (chunk: string) => {
+          raw += chunk
+        })
+        res.on('end', () => {
+          resolve(raw)
+        })
+      }
+    )
+    req.on('error', (error: Error) => {
+      resolve(`ERROR ${error.message}`)
+    })
+    req.end()
+  })
+  check(
+    'the same engine answers /engine/status over TCP',
+    tcpStatus.includes('"socketPath"') && tcpStatus.includes('"apiVersion"'),
+    tcpStatus.replace(/\s+/g, ' ').slice(0, 200)
+  )
+
+  // Last of the TCP checks: this arm answers and then drops the connection,
+  // so the rest of the oversized upload is never read into memory, which
+  // upsets any request that follows it on the same keep-alive socket.
+  const tooBig = await rawPost(
+    { 'Content-Type': 'application/json', 'Content-Length': '9999999' },
+    '{}'
+  )
+  check(
+    'TCP answers an oversized declared body with 413',
+    tooBig.status === 413 && tooBig.raw.includes('PAYLOAD_TOO_LARGE'),
+    `status=${tooBig.status}`
+  )
+
+  // `--tcp-host` defaults to loopback and refuses anything else, so no
+  // external address answers even with a valid token.
+  const addresses = Object.values(os.networkInterfaces())
+    .flat()
+    .filter(
+      (info): info is os.NetworkInterfaceInfo =>
+        info != null && info.family === 'IPv4' && !info.internal
+    )
+  if (addresses.length === 0) {
+    check('no external IPv4 address to probe (skipped)', true)
+  } else {
+    const external = addresses[0].address
+    const reachable = await new Promise<boolean>(resolve => {
+      const req = http.request(
+        {
+          host: external,
+          port: tcpPort,
+          method: 'GET',
+          path: '/engine/status',
+          timeout: 3000
+        },
+        res => {
+          res.resume()
+          resolve(true)
+        }
+      )
+      req.on('error', () => {
+        resolve(false)
+      })
+      req.on('timeout', () => {
+        req.destroy()
+        resolve(false)
+      })
+      req.end()
+    })
+    check(
+      `the TCP listener is not reachable on ${external}`,
+      !reachable,
+      'the default bind host must be loopback'
+    )
+  }
+
+  spawnSync('node', [...CLI, ...tcpBase, 'engine-stop'], { encoding: 'utf8' })
+  fs.rmSync(tcpDir, { recursive: true, force: true })
+
+  fs.rmSync(DIR, { recursive: true, force: true })
+  if (failures > 0) {
+    console.error(`\n${failures} check(s) failed`)
+    process.exit(1)
+  }
+  console.log('\ntestCliSubscribe: all checks passed')
+}
+
+main().catch((error: unknown) => {
+  console.error(error)
+  fs.rmSync(DIR, { recursive: true, force: true })
+  process.exit(1)
+})
diff --git a/scripts/util/cliHarness.ts b/scripts/util/cliHarness.ts
new file mode 100644
index 00000000000..a4dc3d166bf
--- /dev/null
+++ b/scripts/util/cliHarness.ts
@@ -0,0 +1,64 @@
+/**
+ * What the CLI's offline suites share.
+ *
+ * `testCliFake.ts` and `testCliSubscribe.ts` each carried a byte-identical
+ * `EDGE_CLI_BIN` / `CLI` block with the same comment, and all three suites
+ * had their own pass/fail counter and summary printer. One copy, so a change
+ * to how the suites are pointed at a built bundle happens once.
+ */
+import os from 'os'
+import path from 'path'
+
+/**
+ * How to invoke the CLI: the sources through sucrase, or a built bundle.
+ *
+ * `EDGE_CLI_BIN` runs a suite against `lib/edgeCli.js` instead. Three
+ * transforms produce a CLI — sucrase here, Babel for jest, and
+ * `@babel/preset-env` for the rollup bundle — and only the bundle is what
+ * `build:cli` produces and what `docs/EDGE_CLI.md` tells people to run, so a
+ * transform-only defect is invisible to every other suite.
+ */
+export const CLI: string[] =
+  process.env.EDGE_CLI_BIN != null
+    ? [process.env.EDGE_CLI_BIN]
+    : ['-r', 'sucrase/register', 'src/cli/index.ts']
+
+/** Where the CLI keeps its per-profile run directories. */
+export function runRoot(): string {
+  return path.join(os.homedir(), '.edge-cli', 'run')
+}
+
+/** A pass/fail tally with the summary line the suites print. */
+export class Checks {
+  passes = 0
+  failures = 0
+  private readonly label: string
+
+  constructor(label: string) {
+    this.label = label
+  }
+
+  /** Record one check. `detail` is printed only on failure. */
+  check(name: string, ok: boolean, detail?: string): boolean {
+    if (ok) {
+      this.passes++
+      console.log(`OK   ${name}`)
+    } else {
+      this.failures++
+      console.error(`FAIL ${name}${detail == null ? '' : ` — ${detail}`}`)
+    }
+    return ok
+  }
+
+  /** Print the summary and exit non-zero if anything failed. */
+  finish(): void {
+    if (this.failures === 0) {
+      console.log(`\n${this.label}: all checks passed`)
+      return
+    }
+    console.log(
+      `\n${this.label}: ${this.passes} passed, ${this.failures} failed`
+    )
+    process.exit(1)
+  }
+}
diff --git a/scripts/util/solveCaptcha.ts b/scripts/util/solveCaptcha.ts
new file mode 100644
index 00000000000..67c10897a12
--- /dev/null
+++ b/scripts/util/solveCaptcha.ts
@@ -0,0 +1 @@
+export { solveCaptcha, solveChallenge } from '../../src/cli/client/solveCaptcha'
diff --git a/scripts/verifyApiDocs.ts b/scripts/verifyApiDocs.ts
new file mode 100644
index 00000000000..8fb85d47c9f
--- /dev/null
+++ b/scripts/verifyApiDocs.ts
@@ -0,0 +1,470 @@
+/**
+ * Drift checker for the API surface.
+ *
+ * Reads the route declarations and the registered CLI commands out of
+ * `src/cli`, and asserts they describe the same API: no route without a
+ * command it claims, no command nobody declares, no flag on one side missing
+ * from the other, and no `core` naming a member `edge-core-js` does not have.
+ *
+ *   node -r sucrase/register scripts/verifyApiDocs.ts
+ *
+ * Exits non-zero on any drift, so it can gate CI.
+ */
+import fs from 'fs'
+import path from 'path'
+
+import { groupOrder } from '../docs/api/groups'
+import { errorCodes } from '../docs/api/shared'
+import * as errorGroups from '../src/cli/engine/errorGroups'
+import { asCommandsTableJson } from '../src/cli/generatedSchemas'
+import { extractRoutes, kebab } from './extractRoutes'
+
+const ROOT = path.resolve(__dirname, '..')
+const COMMANDS_DIR = path.join(ROOT, 'src/cli/commands')
+const CORE_TYPES = path.join(
+  ROOT,
+  'node_modules/edge-core-js/src/types/types.ts'
+)
+const INTERNAL_TYPES = path.join(ROOT, 'src/cli/engine/internal.ts')
+
+/** Commands that talk to no route. */
+const LOCAL_ONLY_COMMANDS = new Set(['help'])
+
+function read(dir: string): string {
+  return fs
+    .readdirSync(dir)
+    .filter(name => name.endsWith('.ts'))
+    .map(name => fs.readFileSync(path.join(dir, name), 'utf8'))
+    .join('\n')
+}
+
+const commandSource = read(COMMANDS_DIR)
+
+/**
+ * The generated table, cleaned on load rather than cast.
+ *
+ * `asCommandsTable` is the writer's own cleaner, so this gate reads the file
+ * through the same shape `buildCliCommands` writes it with. A third
+ * hand-written `interface` plus a cast is the drift a gate exists to catch,
+ * and it suppresses the check in the one place that is supposed to notice.
+ */
+const generated = asCommandsTableJson(
+  fs.readFileSync(path.join(ROOT, 'src/cli/generated/commands.json'), 'utf8')
+)
+
+function registeredCommands(): Set<string> {
+  const found = new Set<string>()
+  const re =
+    /(?<![\w.])(?:command|objectIdCmd|walletActionCmd)\(\s*'([a-z0-9-]+)'/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(commandSource)) != null) found.add(m[1])
+  for (const c of generated.commands) found.add(c.command)
+  return found
+}
+
+/** Flags each command's parser really accepts. */
+function registeredFlags(): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>()
+  const flagsIn = (text: string): Set<string> => {
+    const flags = new Set<string>()
+    const block = /flags:\s*\{([\s\S]*?)\}/.exec(text)
+    if (block == null) return flags
+    const re =
+      /['"]?([a-zA-Z0-9-]+)['"]?\s*:\s*'(?:string|boolean|repeat|boolstr)'/g
+    let m: RegExpExecArray | null
+    while ((m = re.exec(block[1])) != null) flags.add(m[1])
+    return flags
+  }
+  const helpers: Array<[RegExp, RegExp]> = [
+    [
+      /function objectIdCmd\([\s\S]*?\n\}/,
+      /^objectIdCmd\(\s*\n?\s*'([a-z0-9-]+)'/gm
+    ],
+    [
+      /function walletActionCmd\([\s\S]*?\n\}/,
+      /^walletActionCmd\(\s*\n?\s*'([a-z0-9-]+)'/gm
+    ]
+  ]
+  for (const block of commandSource.split(/\n(?=(?:const \w+ = )?command\()/)) {
+    const name = /^(?:const \w+ = )?command\(\s*\n?\s*'([a-z0-9-]+)'/.exec(
+      block
+    )
+    if (name != null) out.set(name[1], flagsIn(block))
+  }
+  for (const [bodyRe, callRe] of helpers) {
+    const body = bodyRe.exec(commandSource)
+    const flags = body != null ? flagsIn(body[0]) : new Set<string>()
+    let m: RegExpExecArray | null
+    while ((m = callRe.exec(commandSource)) != null) out.set(m[1], flags)
+  }
+  for (const c of generated.commands) {
+    const flags = new Set<string>()
+    for (const a of c.args) if (a.flag != null) flags.add(a.flag)
+    if (c.bodyFlag != null) flags.add(c.bodyFlag)
+    out.set(c.command, flags)
+  }
+  return out
+}
+
+const problems: string[] = []
+function fail(kind: string, detail: string): void {
+  problems.push(`${kind}: ${detail}`)
+}
+
+const routes = extractRoutes()
+const commands = registeredCommands()
+const flagsByCommand = registeredFlags()
+const coreSource = fs.existsSync(CORE_TYPES)
+  ? fs.readFileSync(CORE_TYPES, 'utf8')
+  : ''
+const internalSource = fs.existsSync(INTERNAL_TYPES)
+  ? fs.readFileSync(INTERNAL_TYPES, 'utf8')
+  : ''
+
+// -------------------------------------------------------------- uniqueness
+const seen = new Map<string, number>()
+for (const r of routes) {
+  const key = `${r.method} ${r.routePath}`
+  seen.set(key, (seen.get(key) ?? 0) + 1)
+}
+for (const [key, count] of seen) {
+  if (count > 1) fail('duplicate route', `${key} declared ${count} times`)
+}
+
+// ------------------------------------------------------------ path shape
+// Path parameters are base58 identifiers, and nothing else. Base58 has no
+// `/`, `?` or `#`, so such a value survives a URL as written. A base64 wallet
+// id (`7o7i6/tlI+qi…=`) or a free-text username does not: it needs
+// percent-encoding, and a caller who forgets gets a 404 rather than an error
+// that names the mistake. Those travel as named arguments instead.
+const BASE58_PARAMS = new Set([
+  'sessionId',
+  'objectId',
+  'pendingId',
+  'lobbyId',
+  'syncKey'
+])
+
+// A REST path reads in the same order the command does: scope, then command,
+// then the one argument the command takes bare. Anything the caller names
+// stays in the query or the body.
+for (const r of routes) {
+  const segments = r.routePath.split('/').filter(x => x !== '')
+  const params = segments.filter(x => x.startsWith('{'))
+
+  for (const seg of params) {
+    const name = seg.slice(1, -1)
+    if (!BASE58_PARAMS.has(name)) {
+      fail(
+        'path shape',
+        `${r.method} ${r.routePath} carries "${name}" on the path; only ` +
+          `base58 identifiers (${[...BASE58_PARAMS].join(', ')}) may be path ` +
+          'parameters — everything else needs a named argument'
+      )
+    }
+  }
+
+  for (const [i, seg] of segments.entries()) {
+    if (!seg.startsWith('{')) continue
+    const name = seg.slice(1, -1)
+    if (name === 'sessionId') continue
+    if (i !== segments.length - 1) {
+      fail(
+        'path shape',
+        `${r.method} ${r.routePath} puts {${name}} before a literal segment; ` +
+          'a positional is the final segment'
+      )
+    }
+  }
+
+  // `{sessionId}` is scope, so it may lead; nothing else may repeat it.
+  if (params.length > 2) {
+    fail(
+      'path shape',
+      `${r.method} ${r.routePath} takes more than one argument`
+    )
+  }
+
+  // A plural collection segment means the call acts on many; these all act on
+  // exactly one.
+  for (const seg of segments) {
+    if (seg === 'wallets' || seg === 'objects' || seg === 'swap-quotes') {
+      fail(
+        'path shape',
+        `${r.method} ${r.routePath} names "${seg}" plural but acts on one`
+      )
+    }
+  }
+
+  // The positional must actually be on the path, or the CLI and REST disagree
+  // about where the argument goes.
+  const pos = r.cli?.positional
+  if (pos != null) {
+    if (!r.routePath.endsWith(`/{${pos}}`)) {
+      fail(
+        'path shape',
+        `${r.method} ${r.routePath} declares positional "${pos}" but does not ` +
+          'carry it as the final path segment'
+      )
+    }
+  }
+
+  // A written `path` carries scope and command only. The positional is
+  // appended from `cli.positional`, so spelling it out here would be a second
+  // copy of the same name, free to disagree with the first. `{sessionId}` is
+  // scope rather than an argument, and a route with no command has nothing to
+  // derive from.
+  for (const m of r.declaredPath.matchAll(/\{(\w+)\}/g)) {
+    if (m[1] === 'sessionId') continue
+    if (r.cli == null) continue
+    fail(
+      'path shape',
+      `${r.id} writes {${m[1]}} into its path; declare ` +
+        `\`positional: '${m[1]}'\` on the command and let the path derive it`
+    )
+  }
+}
+
+// --------------------------------------------------------- section by core
+// A call is filed under the object it acts on. That is the rule the reference
+// is organised by, and it is easy to break by putting a route in a convenient
+// file: `account.createCurrencyWallet` sat in `wallets.ts`, and so appeared
+// under Wallet, for as long as nobody read that section closely.
+const SECTION_BY_CORE: Array<[RegExp, string]> = [
+  [/^context\.\$internalStuff\./, 'admin'],
+  [/^context\./, 'context'],
+  [/^account\./, 'account'],
+  [/^wallet\./, 'wallet'],
+  [/^EdgeSwapQuote\./, 'account'],
+  [/^EdgeLoginRequest\./, 'account']
+]
+const sectionOf = new Map<string, string>(
+  groupOrder.map(g => [g.id, g.section])
+)
+for (const r of routes) {
+  if (r.core == null) continue
+  const rule = SECTION_BY_CORE.find(([re]) => re.test(r.core ?? ''))
+  if (rule == null) continue
+  const actual = sectionOf.get(r.group)
+  if (actual !== rule[1]) {
+    fail(
+      'section',
+      `${r.id} fronts ${r.core} but sits in "${r.group}", which is filed ` +
+        `under "${actual ?? '?'}" instead of "${rule[1]}"`
+    )
+  }
+}
+
+// ---------------------------------------------------------------- commands
+const claimed = new Set<string>()
+for (const r of routes) {
+  for (const cli of [r.cli, ...r.cliExtra]) {
+    if (cli == null) continue
+    claimed.add(cli.command)
+    if (!commands.has(cli.command)) {
+      fail(
+        'phantom command',
+        `"${cli.command}" claimed by ${r.id} is not registered`
+      )
+    }
+  }
+}
+for (const name of commands) {
+  if (!claimed.has(name) && !LOCAL_ONLY_COMMANDS.has(name)) {
+    fail('undeclared command', `"${name}" is registered but no route claims it`)
+  }
+}
+
+// ------------------------------------------------------------------- flags
+// A command may serve several routes, so gather what it declares across all.
+const declaredFlags = new Map<string, Set<string>>()
+for (const r of routes) {
+  for (const cli of [r.cli, ...r.cliExtra]) {
+    if (cli == null) continue
+    const set = declaredFlags.get(cli.command) ?? new Set<string>()
+    for (const f of cli.flags) set.add(f.name)
+    for (const x of cli.extra) set.add(x.name)
+    if (cli.bodyFlag != null) set.add(cli.bodyFlag)
+    // Fields with no override become their kebab-cased name.
+    for (const f of [...(r.query ?? []), ...(r.body ?? [])]) {
+      if (f.name === cli.positional) continue
+      set.add(kebab(f.name))
+    }
+    declaredFlags.set(cli.command, set)
+  }
+}
+for (const [command, real] of flagsByCommand) {
+  const declared = declaredFlags.get(command)
+  if (declared == null) continue
+  for (const name of real) {
+    if (!declared.has(name)) {
+      fail(
+        'undeclared flag',
+        `"${command}" accepts --${name}, no route declares it`
+      )
+    }
+  }
+}
+
+// -------------------------------------------------------------- core calls
+for (const r of routes) {
+  if (r.core == null) {
+    if (r.coreNote == null || r.coreNote === '') {
+      fail('missing core note', `${r.id} has no core call and no @coreNote`)
+    }
+    continue
+  }
+  const member = r.core.split('.').pop() ?? ''
+  const haystack = r.core.includes('$internalStuff')
+    ? internalSource
+    : coreSource
+  if (haystack !== '' && !new RegExp(`\\b${member}\\b`).test(haystack)) {
+    fail('unknown core call', `${r.id} names "${r.core}", absent from core`)
+  }
+}
+
+// ------------------------------------------------------------------ shapes
+const knownCodes = new Set(errorCodes.map(e => e.code))
+for (const r of routes) {
+  for (const code of r.errors) {
+    if (!knownCodes.has(code)) {
+      fail('unknown error code', `${r.id} lists "${code}"`)
+    }
+  }
+  if (r.summary === '') fail('missing summary', `${r.id} has no JSDoc summary`)
+}
+
+// Every shared group reaches the published surface. `extractRoutes` used to
+// read `errors: WALLET_ERRORS` as no codes at all and drop every
+// `...WALLET_ERRORS` element, so 56 entries across 21 routes were missing
+// from the reference and from `edge-cli help` — and the check above could
+// not see it, because it only asks whether an extracted code is a real one
+// and the codes were gone before it looked. This asks the other question.
+const publishedCodes = new Set(routes.flatMap(r => r.errors))
+for (const [group, codes] of Object.entries(errorGroups)) {
+  if (!Array.isArray(codes)) continue
+  const missing = codes.filter(code => !publishedCodes.has(String(code)))
+  if (missing.length > 0) {
+    fail(
+      'unpublished error group',
+      `${group} has ${missing.length} code(s) no route publishes: ` +
+        `${missing.join(', ')} — a route declares the group but the ` +
+        `extractor did not expand it`
+    )
+  }
+}
+
+// ------------------------------------------------- paths named in the prose
+// Narrative text is not generated, so a rename can leave it behind. Any
+// `METHOD /path` mentioned anywhere in the docs must be a real route.
+const realPaths = new Set(routes.map(r => `${r.method} ${r.routePath}`))
+/** Paths on other services that the prose legitimately mentions. */
+const EXTERNAL_PATHS = new Set(['GET /v1/getKeys'])
+const proseSources: Array<[string, string]> = []
+for (const file of ['docs/EDGE_CLI.md', 'docs/api/README.md']) {
+  const full = path.join(ROOT, file)
+  if (fs.existsSync(full))
+    proseSources.push([file, fs.readFileSync(full, 'utf8')])
+}
+for (const r of routes) {
+  const text = [
+    r.summary,
+    r.description ?? '',
+    ...r.notes,
+    r.coreNote ?? ''
+  ].join(' ')
+  proseSources.push([r.id, text])
+}
+for (const [where, text] of proseSources) {
+  for (const m of text.matchAll(
+    /\b(GET|POST|PUT|PATCH|DELETE) (\/[\w{}/-]+)/g
+  )) {
+    const cited = `${m[1]} ${m[2]}`
+    // `…` stands in for an elided prefix; only check fully-written paths.
+    if (m[2].includes('…')) continue
+    if (!realPaths.has(cited) && !EXTERNAL_PATHS.has(cited)) {
+      fail(
+        'stale path in prose',
+        `${where} cites "${cited}", which is not a route`
+      )
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The global flags, against the table `docs/EDGE_CLI.md` publishes.
+//
+// Every route-derived surface in this branch is generated and gated; the
+// global flags were the last hand-maintained table, written out in the
+// client's help, again in the engine's `printHelp()` and again in the docs,
+// and all three had drifted — `-h, --help` was "Display options", "Show
+// help" and "Show options".
+//
+// The two help texts are now rendered from `src/cli/flagTable.ts`, so this
+// checks the one remaining copy: the guide's table has to carry every flag
+// with the right `Who`, and its description has to *start with* the
+// canonical one — the guide may add prose after it, not instead of it.
+// ---------------------------------------------------------------------------
+{
+  const { GLOBAL_FLAGS } = require('../src/cli/flagTable') as {
+    GLOBAL_FLAGS: Array<{
+      docName: string
+      who: 'client' | 'engine' | 'both'
+      description: string
+    }>
+  }
+  const docsText = fs.readFileSync(path.join(ROOT, 'docs/EDGE_CLI.md'), 'utf8')
+
+  /** Every flag row in the guide's table: name, audience, description. */
+  const docRows = new Map<string, { who: string; description: string }>()
+  for (const m of docsText.matchAll(
+    /^\| `([^`]+)` \| (client|engine|both) \| ([^|]*)\|/gm
+  )) {
+    docRows.set(m[1].trim(), { who: m[2], description: m[3].trim() })
+  }
+  if (docRows.size === 0) {
+    fail('global flags', 'no flag rows found in docs/EDGE_CLI.md')
+  }
+
+  const canonical = new Set(GLOBAL_FLAGS.map(f => f.docName))
+  for (const flag of GLOBAL_FLAGS) {
+    const row = docRows.get(flag.docName)
+    if (row == null) {
+      fail(
+        'undocumented flag',
+        `${flag.docName} is in src/cli/flagTable.ts but not in docs/EDGE_CLI.md`
+      )
+      continue
+    }
+    if (row.who !== flag.who) {
+      fail(
+        'wrong audience',
+        `${flag.docName} is "${flag.who}" in src/cli/flagTable.ts and "${row.who}" in docs/EDGE_CLI.md`
+      )
+    }
+    if (!row.description.startsWith(flag.description)) {
+      fail(
+        'flag description drift',
+        `${flag.docName} reads "${row.description}" in docs/EDGE_CLI.md; it must begin with "${flag.description}"`
+      )
+    }
+  }
+  for (const name of docRows.keys()) {
+    if (!canonical.has(name)) {
+      fail(
+        'stale documented flag',
+        `${name} is in docs/EDGE_CLI.md but not in src/cli/flagTable.ts`
+      )
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✗ ${problems.length} problem(s):\n`)
+  for (const p of problems) console.error(`  ${p}`)
+  process.exit(1)
+}
+console.log(
+  `✓ surface matches: ${routes.length} routes, ` +
+    `${claimed.size} of ${commands.size} commands (${LOCAL_ONLY_COMMANDS.size} local-only)`
+)
diff --git a/scripts/writeIfChanged.ts b/scripts/writeIfChanged.ts
new file mode 100644
index 00000000000..c70f668e214
--- /dev/null
+++ b/scripts/writeIfChanged.ts
@@ -0,0 +1,40 @@
+import fs from 'fs'
+import path from 'path'
+
+/**
+ * True when the generators may only verify, not write.
+ *
+ * `--check` turns every generator into a staleness test: it derives what the
+ * artifact should contain and fails if the committed copy disagrees. That is
+ * what makes committing the generated files safe — an edited declaration
+ * cannot reach a commit while `commands.json` still describes the old one.
+ */
+const CHECK_ONLY = process.argv.includes('--check')
+
+/**
+ * Write a file only when its contents actually change.
+ *
+ * `npm run prepare` regenerates every artifact on each install, so an
+ * unconditional write would touch mtimes and show up as a git diff even when
+ * nothing about the source moved. Returns true when something was written.
+ *
+ * Under `--check` nothing is written; a file that would have changed throws
+ * instead.
+ */
+export function writeIfChanged(file: string, contents: string): boolean {
+  if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === contents) {
+    return false
+  }
+  if (CHECK_ONLY) {
+    // A stack trace would bury the one line that matters.
+    console.error(
+      `✗ ${path.relative(process.cwd(), file)} is out of date.\n` +
+        '  A route declaration changed without regenerating it.\n' +
+        '  Run `npm run docs:api` and commit the result.'
+    )
+    process.exit(1)
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, contents)
+  return true
+}
diff --git a/src/__tests__/cli/apiClient.test.ts b/src/__tests__/cli/apiClient.test.ts
new file mode 100644
index 00000000000..681c3fd7188
--- /dev/null
+++ b/src/__tests__/cli/apiClient.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, beforeAll, describe, expect, it, jest } from '@jest/globals'
+import fs from 'fs'
+import http from 'http'
+import net from 'net'
+import os from 'os'
+import path from 'path'
+
+import { ApiClient } from '../../cli/client/apiClient'
+
+// Real timers: these drive a real socket.
+beforeAll(() => {
+  jest.useRealTimers()
+})
+
+const servers: Array<net.Server | http.Server> = []
+const sockets: string[] = []
+/**
+ * Every connection these servers accepted.
+ *
+ * `close()` stops a server listening but does nothing about a connection it
+ * has already accepted, and one case below deliberately accepts and then says
+ * nothing — so the listener stayed open, jest reported two `PIPEWRAP` handles
+ * and force-exited a worker, and a live socket in a shared worker is how an
+ * unrelated suite starts failing intermittently.
+ */
+const accepted: net.Socket[] = []
+
+afterEach(async () => {
+  for (const socket of accepted.splice(0)) socket.destroy()
+  // Awaited: `close` is asynchronous, so returning before its callback left
+  // the handle open for whatever ran next.
+  await Promise.all(
+    servers.splice(0).map(async server => {
+      await new Promise<void>(resolve => {
+        server.close(() => {
+          resolve()
+        })
+      })
+    })
+  )
+  for (const socketPath of sockets.splice(0)) {
+    // The whole `mkdtemp` directory, not just the socket file inside it:
+    // unlinking one file left the directory behind, and 132 of them had
+    // accumulated in $TMPDIR on this machine.
+    fs.rmSync(path.dirname(socketPath), { recursive: true, force: true })
+  }
+})
+
+/** A unix socket path this test owns. */
+function tempSocket(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-api-'))
+  const socketPath = path.join(dir, 'engine.sock')
+  sockets.push(socketPath)
+  return socketPath
+}
+
+/** Listen on `socketPath` and hand each connection to `onConnection`. */
+async function rawServer(
+  socketPath: string,
+  onConnection: (socket: net.Socket) => void
+): Promise<void> {
+  const server = net.createServer(socket => {
+    accepted.push(socket)
+    onConnection(socket)
+  })
+  servers.push(server)
+  await new Promise<void>(resolve => server.listen(socketPath, resolve))
+}
+
+describe('ApiClient.sendRequest', () => {
+  it('rejects when the engine dies mid-response', async () => {
+    const socketPath = tempSocket()
+    // Headers, then a truncated body, then the connection drops. Node routes
+    // this to the *response*, not the request, so without `res.on('error')`
+    // and `res.on('aborted')` the promise never settled: the CLI printed
+    // nothing and exited 0, and `edge-cli spend … && echo sent` printed
+    // `sent`.
+    await rawServer(socketPath, socket => {
+      socket.write(
+        'HTTP/1.1 200 OK\r\n' +
+          'Content-Type: application/json\r\n' +
+          'Content-Length: 120\r\n' +
+          '\r\n' +
+          '{"apiVersion":"1.0.0","pid":1234,'
+      )
+      setTimeout(() => socket.destroy(), 20)
+    })
+
+    const client = new ApiClient({ socketPath, timeoutMs: 5000 })
+    await expect(client.get('/engine/status')).rejects.toThrow(
+      /closed the connection while answering/
+    )
+  })
+
+  it('rejects, rather than hanging, when the response ends with no body', async () => {
+    const socketPath = tempSocket()
+    await rawServer(socketPath, socket => {
+      socket.write('HTTP/1.1 500 Internal Server Error\r\n\r\n')
+      socket.end()
+    })
+    const client = new ApiClient({ socketPath, timeoutMs: 5000 })
+    await expect(client.get('/engine/status')).rejects.toThrow(/HTTP 500/)
+  })
+
+  it('reports the route and the deadline when a request times out', async () => {
+    const socketPath = tempSocket()
+    // Accept and say nothing at all.
+    await rawServer(socketPath, () => {})
+    const client = new ApiClient({ socketPath, timeoutMs: 150 })
+    await expect(client.get('/engine/status')).rejects.toThrow(
+      /timed out after 0\.15s: GET \/engine\/status/
+    )
+  })
+
+  it('cleans the error envelope rather than casting it', async () => {
+    const socketPath = tempSocket()
+    const server = http.createServer((req, res) => {
+      accepted.push(req.socket)
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      res.end(
+        JSON.stringify({
+          error: {
+            code: 'WALLET_NOT_FOUND',
+            message: 'No wallet matches that id',
+            status: 404
+          }
+        })
+      )
+    })
+    servers.push(server)
+    await new Promise<void>(resolve => server.listen(socketPath, resolve))
+
+    const client = new ApiClient({ socketPath, timeoutMs: 5000 })
+    await expect(client.get('/engine/status')).rejects.toMatchObject({
+      code: 'WALLET_NOT_FOUND',
+      status: 404
+    })
+  })
+})
diff --git a/src/__tests__/cli/configSubsets.test.ts b/src/__tests__/cli/configSubsets.test.ts
new file mode 100644
index 00000000000..6e73ce04c02
--- /dev/null
+++ b/src/__tests__/cli/configSubsets.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { asConfigJson, asKeysJson } from '../../configKeysSchema'
+
+/**
+ * The engine reads `config.json` and `keys.json` with narrower cleaners than
+ * the app's, because it needs three fields out of each and must not write
+ * either file back.
+ *
+ * The app's loader goes through `cleaner-config`'s `makeConfig`, which fills
+ * defaults and **writes the file back** on a round-trip
+ * (`src/configKeysSchema.ts` says so). That is right for a developer tool and
+ * wrong for a daemon: an engine asked to read a user's `keys.json` must not
+ * rewrite it. So the engine keeps its own read, and these cases are what stop
+ * the two shapes parting ways — the same job
+ * `syncedSettingsFile.test.ts` does for the settings subset.
+ */
+describe('the engine config subsets', () => {
+  it('accepts what the app’s config.json cleaner produces', () => {
+    const { loadAppConfig } = requireAppConfig()
+    const full = asConfigJson.withRest({
+      corePlugins: { bitcoin: true },
+      swapPlugins: { changelly: { apiKey: 'k' } },
+      guiApiKeys: {},
+      rampPlugins: {}
+    })
+    // The engine reads only `swapPlugins`, and it has to survive the app's
+    // own cleaner having materialised every other key.
+    const narrow = narrowAppConfig()(full)
+    expect(narrow.swapPlugins).toStrictEqual({ changelly: { apiKey: 'k' } })
+    expect(typeof loadAppConfig).toBe('function')
+  })
+
+  it('accepts what the app’s keys.json cleaner produces', () => {
+    // `.withRest`, which is what `scripts/configure.ts` actually loads with.
+    // The bare cleaner drops every key it does not declare — including the
+    // three the engine reads — so the app's loader preserving the rest is
+    // the contract this pins: without it, a `makeConfig` round-trip would
+    // strip a developer's `edgeApiKey`, `edgeApiSecret` and `pluginApiKeys`.
+    const full = asKeysJson.withRest({
+      corePlugins: {},
+      swapPlugins: {},
+      guiApiKeys: {},
+      rampPlugins: {},
+      POSTHOG_API_KEY: null,
+      edgeApiKey: 'api-key',
+      edgeApiSecret: '00ff',
+      pluginApiKeys: { monero: true }
+    })
+    const narrow = narrowKeysConfig()(full)
+    expect(narrow.edgeApiKey).toBe('api-key')
+    expect(narrow.edgeApiSecret).toBe('00ff')
+    expect(narrow.pluginApiKeys).toStrictEqual({ monero: true })
+  })
+
+  it('defaults the fields the app’s cleaner leaves out', () => {
+    // A `config.json` with no `swapPlugins` at all, and a `keys.json` with
+    // no Edge API credentials: the engine's own defaults have to hold,
+    // because that is the state a fresh clone is in.
+    expect(narrowAppConfig()({}).swapPlugins).toBeUndefined()
+    const keys = narrowKeysConfig()({})
+    expect(keys.edgeApiKey).toBe('')
+    expect(keys.pluginApiKeys).toStrictEqual({})
+  })
+})
+
+/** The engine's own cleaners, reached without its loaders' file reads. */
+function narrowAppConfig(): (raw: unknown) => { swapPlugins?: unknown } {
+  const { asAppConfigFileForTests } = require('../../cli/engine/appConfig')
+  return asAppConfigFileForTests
+}
+function narrowKeysConfig(): (raw: unknown) => {
+  edgeApiKey: string
+  edgeApiSecret?: string
+  pluginApiKeys: Record<string, unknown>
+} {
+  const { asKeysConfigForTests } = require('../../cli/engine/keysConfig')
+  return asKeysConfigForTests
+}
+function requireAppConfig(): { loadAppConfig: unknown } {
+  return require('../../cli/engine/appConfig')
+}
diff --git a/src/__tests__/cli/discovery.test.ts b/src/__tests__/cli/discovery.test.ts
new file mode 100644
index 00000000000..524225b7298
--- /dev/null
+++ b/src/__tests__/cli/discovery.test.ts
@@ -0,0 +1,330 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest
+} from '@jest/globals'
+import fs from 'fs'
+import net from 'net'
+import os from 'os'
+import path from 'path'
+
+import type * as DiscoveryModule from '../../cli/engine/discovery'
+
+/**
+ * `discovery` resolves the home directory at call time, so stubbing
+ * `os.homedir` is enough to keep every case off the developer's real
+ * `~/.edge-cli`. Setting `HOME` is *not* enough: under jest `os.homedir()`
+ * does not read it, and a sweep would then delete the real run directory.
+ */
+let home: string
+let homedir: jest.SpiedFunction<typeof os.homedir>
+
+type Discovery = typeof DiscoveryModule
+function load(): Discovery {
+  return require('../../cli/engine/discovery')
+}
+
+beforeEach(() => {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-discovery-'))
+  homedir = jest.spyOn(os, 'homedir').mockReturnValue(home)
+  jest.resetModules()
+})
+
+afterEach(() => {
+  homedir.mockRestore()
+  fs.rmSync(home, { recursive: true, force: true })
+})
+
+const key = {
+  directory: '/tmp/data',
+  appId: 'edge.app',
+  testMode: false,
+  loginServer: undefined
+}
+
+describe('profileHash', () => {
+  it('is stable for the same key', () => {
+    const { profileHash } = load()
+    expect(profileHash(key)).toBe(profileHash({ ...key }))
+  })
+
+  it('differs for every field that picks a different engine', () => {
+    const { profileHash } = load()
+    const base = profileHash(key)
+    expect(profileHash({ ...key, directory: '/tmp/other' })).not.toBe(base)
+    expect(profileHash({ ...key, appId: 'other.app' })).not.toBe(base)
+    expect(profileHash({ ...key, testMode: true })).not.toBe(base)
+    expect(
+      profileHash({ ...key, loginServer: 'https://login.example' })
+    ).not.toBe(base)
+  })
+
+  it('is one profile per directory, however the path is spelled', () => {
+    const { profileHash } = load()
+    // The hash is the only thing keeping two engines off one core data
+    // directory. Taken over the raw argv string, a trailing slash or a
+    // relative path gave one directory several profiles, each holding what it
+    // believed was an exclusive claim — the same two-EdgeContexts state the
+    // claim ordering exists to prevent, reached with no race at all.
+    const real = fs.realpathSync.native(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'edge-dir-'))
+    )
+    const link = path.join(home, 'link-to-data')
+    fs.symlinkSync(real, link)
+    const spellings = [
+      real,
+      `${real}/`,
+      `${real}/.`,
+      path.join(real, 'x', '..'),
+      link
+    ]
+    const hashes = spellings.map(directory =>
+      profileHash({ ...key, directory })
+    )
+    expect(new Set(hashes).size).toBe(1)
+
+    // A path that does not exist yet still resolves, because the engine is
+    // what creates the directory.
+    const missing = path.join(real, 'not-yet')
+    expect(profileHash({ ...key, directory: `${missing}/` })).toBe(
+      profileHash({ ...key, directory: missing })
+    )
+    fs.rmSync(real, { recursive: true, force: true })
+  })
+
+  it('still separates genuinely different directories', () => {
+    const { profileHash } = load()
+    expect(profileHash({ ...key, directory: '/tmp/a' })).not.toBe(
+      profileHash({ ...key, directory: '/tmp/b' })
+    )
+  })
+})
+
+describe('claimRunFile', () => {
+  it('refuses a second claim on the same profile', () => {
+    const { claimRunFile, ensureRunDir } = load()
+    ensureRunDir('p1')
+    const run = {
+      pid: process.pid,
+      apiVersion: '1',
+      socketPath: path.join(home, 'engine.sock'),
+      tcpPort: null,
+      appId: 'edge.app',
+      testMode: false,
+      startedAt: new Date().toISOString()
+    }
+    expect(claimRunFile('p1', run as any)).toBe(true)
+    // `flag: 'wx'` is the lock: two engines racing for one profile must not
+    // both believe they own it.
+    expect(claimRunFile('p1', run as any)).toBe(false)
+  })
+})
+
+describe('cleanupStaleLock', () => {
+  /**
+   * `startedAt` is a parameter because it is what separates the two cases
+   * that otherwise look identical — a live pid with nothing listening. A
+   * booting engine's claim is seconds old; a recycled pid's claim is however
+   * long ago that engine was killed. Only the age tells them apart.
+   */
+  function seed(
+    profile: string,
+    pid: number,
+    opts: { startedAt?: string | null } = {}
+  ): void {
+    const {
+      ensureRunDir,
+      runFilePath,
+      sessionFilePath,
+      socketPathFor,
+      runDir
+    } = load()
+    const startedAt =
+      opts.startedAt === undefined ? new Date().toISOString() : opts.startedAt
+    ensureRunDir(profile)
+    fs.writeFileSync(
+      runFilePath(profile),
+      JSON.stringify({
+        pid,
+        apiVersion: '1',
+        socketPath: socketPathFor(profile),
+        tcpPort: null,
+        appId: 'edge.app',
+        testMode: false,
+        ...(startedAt == null ? {} : { startedAt })
+      })
+    )
+    fs.writeFileSync(sessionFilePath(profile), '{"sessionId":"sess_x"}')
+    fs.writeFileSync(socketPathFor(profile), '')
+    fs.writeFileSync(path.join(runDir(profile), 'engine-startup.log'), 'boot')
+  }
+
+  /** A real listener on this profile's socket, closed by the caller. */
+  async function listen(profile: string): Promise<net.Server> {
+    const { socketPathFor } = load()
+    const socketPath = socketPathFor(profile)
+    try {
+      fs.unlinkSync(socketPath)
+    } catch {
+      // not there
+    }
+    const server = net.createServer(socket => socket.end())
+    await new Promise<void>(resolve => server.listen(socketPath, resolve))
+    return server
+  }
+
+  it('returns the pid and removes nothing while the engine is alive', async () => {
+    const { cleanupStaleLock, runFilePath, sessionFilePath } = load()
+    seed('live', process.pid)
+    const server = await listen('live')
+    try {
+      expect(await cleanupStaleLock('live')).toBe(process.pid)
+      expect(fs.existsSync(runFilePath('live'))).toBe(true)
+      expect(fs.existsSync(sessionFilePath('live'))).toBe(true)
+    } finally {
+      server.close()
+    }
+  })
+
+  it('clears a claim whose pid is live but whose socket is not', async () => {
+    const { cleanupStaleLock, runFilePath } = load()
+    // The recycled-pid case: a SIGKILLed engine's run file names a pid the
+    // OS later handed to something else, so `process.kill(pid, 0)` succeeds
+    // for ever. On the pid alone the engine printed "already running" and
+    // exited 1 on every invocation, and the sweep skipped the directory for
+    // the same reason, so the profile stayed wedged until someone deleted it
+    // by hand. `process.pid` is certainly alive, and nothing is listening.
+    // Backdated past the boot grace, because that is what a recycled pid
+    // always is: the engine that wrote this file died long enough ago for the
+    // OS to hand its pid out again.
+    seed('ghost', process.pid, {
+      startedAt: new Date(Date.now() - 600_000).toISOString()
+    })
+    expect(await cleanupStaleLock('ghost')).toBeNull()
+    expect(fs.existsSync(runFilePath('ghost'))).toBe(false)
+  })
+
+  it('honours a fresh claim with nothing listening yet', async () => {
+    const { cleanupStaleLock, runFilePath, sessionFilePath, socketPathFor } =
+      load()
+    // The boot window. `claimRunFile` runs before `makeCoreContext`, which
+    // opens the repos and starts every plugin, so for seconds a live engine
+    // holds the claim with nothing bound. Treating that as stale let a second
+    // cold invocation delete this engine's artifacts and claim the same
+    // profile, so two EdgeContexts opened one core directory — and when the
+    // two converged, the loser's cleanup unlinked the winner's live socket.
+    seed('booting', process.pid)
+    fs.unlinkSync(socketPathFor('booting'))
+    expect(await cleanupStaleLock('booting')).toBe(process.pid)
+    expect(fs.existsSync(runFilePath('booting'))).toBe(true)
+    expect(fs.existsSync(sessionFilePath('booting'))).toBe(true)
+  })
+
+  it('falls back to the run file mtime when the claim has no startedAt', async () => {
+    const { cleanupStaleLock, runFilePath } = load()
+    // An engine from before `startedAt` existed is still booting-or-not, and
+    // guessing "stale" would sweep it mid-boot. A fresh file is young.
+    seed('legacy', process.pid, { startedAt: null })
+    expect(await cleanupStaleLock('legacy')).toBe(process.pid)
+    expect(fs.existsSync(runFilePath('legacy'))).toBe(true)
+
+    // The same file, backdated past the grace, is stale again.
+    seed('old-legacy', process.pid, { startedAt: null })
+    const past = Date.now() - 600_000
+    fs.utimesSync(runFilePath('old-legacy'), past / 1000, past / 1000)
+    expect(await cleanupStaleLock('old-legacy')).toBeNull()
+    expect(fs.existsSync(runFilePath('old-legacy'))).toBe(false)
+  })
+
+  it('clears a dead engine and keeps the startup log', async () => {
+    const { cleanupStaleLock, runDir, runFilePath, sessionFilePath } = load()
+    // A pid that cannot be running: 0x7FFFFFFF is above every pid_max.
+    seed('dead', 0x7fffffff)
+    expect(await cleanupStaleLock('dead')).toBeNull()
+    expect(fs.existsSync(runFilePath('dead'))).toBe(false)
+    // The bearer token must not survive the engine that issued it.
+    expect(fs.existsSync(sessionFilePath('dead'))).toBe(false)
+    expect(fs.existsSync(path.join(runDir('dead'), 'engine-startup.log'))).toBe(
+      true
+    )
+  })
+
+  it('keeps the socket and session when asked, clearing only the run file', async () => {
+    const { removeRunArtifacts, runFilePath, sessionFilePath, socketPathFor } =
+      load()
+    // What a startup that claimed the profile and then lost the `listen` race
+    // must do. The socket is the winner's and `session.json` is the user's;
+    // removing them left the winner resident and unreachable, with every
+    // later command spawning another engine on the same directory.
+    seed('loser', process.pid)
+    removeRunArtifacts('loser', {
+      keepStartupLog: true,
+      keepSocket: true,
+      keepSession: true
+    })
+    expect(fs.existsSync(runFilePath('loser'))).toBe(false)
+    expect(fs.existsSync(socketPathFor('loser'))).toBe(true)
+    expect(fs.existsSync(sessionFilePath('loser'))).toBe(true)
+  })
+
+  it('treats a malformed run file as no claim and removes the socket', async () => {
+    const { cleanupStaleLock, ensureRunDir, runFilePath, socketPathFor } =
+      load()
+    ensureRunDir('broken')
+    fs.writeFileSync(runFilePath('broken'), 'not json')
+    fs.writeFileSync(socketPathFor('broken'), '')
+    // A live engine always has a well-formed run file, because
+    // `claimRunFile` writes it before anything binds — so an unreadable one
+    // is not a claim, and the profile must not stay wedged.
+    expect(await cleanupStaleLock('broken')).toBeNull()
+    expect(fs.existsSync(socketPathFor('broken'))).toBe(false)
+  })
+})
+
+describe('sweepStaleProfiles', () => {
+  it('removes every profile no live process owns, except the caller', () => {
+    const {
+      ensureRunDir,
+      runDir,
+      runFilePath,
+      sessionFilePath,
+      socketPathFor,
+      sweepStaleProfiles
+    } = load()
+    const write = (profile: string, pid: number): void => {
+      ensureRunDir(profile)
+      fs.writeFileSync(
+        runFilePath(profile),
+        JSON.stringify({
+          pid,
+          apiVersion: '1',
+          socketPath: socketPathFor(profile),
+          tcpPort: null,
+          appId: 'edge.app',
+          testMode: false,
+          startedAt: new Date().toISOString()
+        })
+      )
+      fs.writeFileSync(sessionFilePath(profile), '{"sessionId":"sess_x"}')
+    }
+    write('orphan1', 0x7fffffff)
+    write('orphan2', 0x7ffffffe)
+    write('alive', process.pid)
+    ensureRunDir('mine')
+
+    expect(sweepStaleProfiles('mine')).toBe(2)
+    expect(fs.existsSync(runDir('orphan1'))).toBe(false)
+    expect(fs.existsSync(runDir('orphan2'))).toBe(false)
+    // A live engine's directory and the caller's own are untouched.
+    expect(fs.existsSync(runFilePath('alive'))).toBe(true)
+    expect(fs.existsSync(runDir('mine'))).toBe(true)
+  })
+
+  it('does nothing when there is no run root yet', () => {
+    const { sweepStaleProfiles } = load()
+    expect(sweepStaleProfiles('mine')).toBe(0)
+  })
+})
diff --git a/src/__tests__/cli/engineCodecs.test.ts b/src/__tests__/cli/engineCodecs.test.ts
new file mode 100644
index 00000000000..fb3a96def13
--- /dev/null
+++ b/src/__tests__/cli/engineCodecs.test.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it } from '@jest/globals'
+import type { EdgeAccount, EdgeCurrencyWallet } from 'edge-core-js'
+
+import { jsonReplacer, stringifyJson } from '../../cli/engine/json'
+import { findWallet } from '../../cli/engine/resolve'
+import { base58, utf8 } from '../../util/encoding'
+
+/** The error shape `engineError` produces. */
+function thrown(fn: () => unknown): { code: string; status: number } {
+  try {
+    fn()
+  } catch (error) {
+    const engineError = error as { code: string; status: number }
+    return { code: engineError.code, status: engineError.status }
+  }
+  throw new Error('expected a throw')
+}
+
+describe('jsonReplacer', () => {
+  it('encodes a Uint8Array as base64', () => {
+    expect(jsonReplacer('k', new Uint8Array([1, 2, 3]))).toBe('AQID')
+    expect(stringifyJson({ bytes: new Uint8Array([255]) })).toBe(
+      '{"bytes":"/w=="}'
+    )
+  })
+
+  it('encodes a Map as an object, stringifying its keys', () => {
+    const map = new Map<unknown, unknown>([
+      ['a', 1],
+      [2, 'b']
+    ])
+    expect(jsonReplacer('k', map)).toStrictEqual({ a: 1, '2': 'b' })
+    // The wallet balance maps core hands back are keyed by tokenId or null.
+    expect(stringifyJson({ balanceMap: new Map([[null, '100']]) })).toBe(
+      '{"balanceMap":{"null":"100"}}'
+    )
+  })
+
+  it('passes everything else through', () => {
+    for (const value of [1, 'x', true, null, undefined, { a: 1 }, [1, 2]]) {
+      expect(jsonReplacer('k', value)).toStrictEqual(value)
+    }
+  })
+
+  it('serialises a Date to ISO without a replacer arm for it', () => {
+    // `JSON.stringify` calls `Date.prototype.toJSON` before the replacer, so
+    // a `value instanceof Date` arm can never fire. The output is the same,
+    // which is why the dead arm went unnoticed.
+    expect(stringifyJson({ d: new Date(0) })).toBe(
+      '{"d":"1970-01-01T00:00:00.000Z"}'
+    )
+    expect(jsonReplacer('d', new Date(0))).toBeInstanceOf(Date)
+  })
+})
+
+describe('base58', () => {
+  it('round-trips', () => {
+    for (const bytes of [
+      new Uint8Array([]),
+      new Uint8Array([0]),
+      new Uint8Array([1, 2, 3]),
+      new Uint8Array([255, 254, 0, 1])
+    ]) {
+      expect([...base58.parse(base58.stringify(bytes))]).toStrictEqual([
+        ...bytes
+      ])
+    }
+  })
+
+  it('uses the alphabet session ids are read in', () => {
+    // Session and handle ids are base58 precisely so they can be path
+    // parameters, so the alphabet must exclude 0, O, I and l.
+    const text = base58.stringify(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]))
+    expect(text).not.toMatch(/[0OIl]/)
+  })
+})
+
+describe('utf8', () => {
+  it('round-trips ASCII and multi-byte text', () => {
+    for (const text of ['', 'hello', 'héllo wörld', '日本語', '😀']) {
+      expect(utf8.stringify(utf8.parse(text))).toBe(text)
+    }
+  })
+
+  it('agrees with Buffer on byte length', () => {
+    for (const text of ['hello', 'héllo', '日本語', '😀']) {
+      expect(utf8.parse(text).length).toBe(Buffer.byteLength(text, 'utf8'))
+    }
+  })
+})
+
+describe('findWallet', () => {
+  function makeAccount(ids: string[]): EdgeAccount {
+    const currencyWallets: Record<string, EdgeCurrencyWallet> = {}
+    for (const id of ids) {
+      currencyWallets[id] = { id } as unknown as EdgeCurrencyWallet
+    }
+    return { currencyWallets } as unknown as EdgeAccount
+  }
+
+  it('matches a full id, and a unique prefix', () => {
+    const account = makeAccount(['aaa111', 'bbb222'])
+    expect(findWallet(account, 'aaa111').id).toBe('aaa111')
+    expect(findWallet(account, 'aaa').id).toBe('aaa111')
+  })
+
+  it('reports an ambiguous prefix with its candidates', () => {
+    const account = makeAccount(['aaa111', 'aaa222'])
+    expect(thrown(() => findWallet(account, 'aaa'))).toStrictEqual({
+      code: 'AMBIGUOUS_WALLET_ID',
+      status: 409
+    })
+  })
+
+  it('reports a prefix that matches nothing', () => {
+    const account = makeAccount(['aaa111'])
+    expect(thrown(() => findWallet(account, 'zzz'))).toStrictEqual({
+      code: 'WALLET_NOT_FOUND',
+      status: 404
+    })
+  })
+
+  it('refuses an empty prefix rather than resolving the only wallet', () => {
+    // `''` is a prefix of every id, so on a single-wallet account this used
+    // to resolve silently to that wallet — and this is what `spend` resolves
+    // through.
+    const account = makeAccount(['aaa111'])
+    expect(thrown(() => findWallet(account, ''))).toStrictEqual({
+      code: 'BAD_REQUEST',
+      status: 400
+    })
+  })
+
+  it('prefers an exact id over a prefix of a longer one', () => {
+    const account = makeAccount(['aaa', 'aaa111'])
+    expect(findWallet(account, 'aaa').id).toBe('aaa')
+  })
+})
diff --git a/src/__tests__/cli/errors.test.ts b/src/__tests__/cli/errors.test.ts
new file mode 100644
index 00000000000..e3d49aea53f
--- /dev/null
+++ b/src/__tests__/cli/errors.test.ts
@@ -0,0 +1,223 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  ChallengeError,
+  DustSpendError,
+  InsufficientFundsError,
+  NetworkError,
+  NoAmountSpecifiedError,
+  ObsoleteApiError,
+  OtpError,
+  PasswordError,
+  PendingFundsError,
+  PinDisabledError,
+  SameCurrencyError,
+  SpendToSelfError,
+  SwapAboveLimitError,
+  SwapAddressError,
+  SwapBelowLimitError,
+  SwapCurrencyError,
+  SwapPermissionError,
+  UsernameError
+} from 'edge-core-js'
+
+import { errorCodes } from '../../../docs/api/shared'
+import { engineError, toErrorBody } from '../../cli/engine/errors'
+
+const swapInfo = {
+  pluginId: 'fakeswap',
+  displayName: 'Fake Swap',
+  supportEmail: 'support@example.com'
+}
+
+const swapRequest: any = {
+  fromWallet: {
+    id: 'w1',
+    currencyConfig: { currencyInfo: { pluginId: 'bitcoin' } }
+  },
+  toWallet: {
+    id: 'w2',
+    currencyConfig: { currencyInfo: { pluginId: 'ethereum' } }
+  },
+  fromTokenId: null,
+  toTokenId: null,
+  nativeAmount: '1000',
+  quoteFor: 'from'
+}
+
+/**
+ * Every arm of `mapCoreError`, as a table.
+ *
+ * Two gates already check that a code a *route* declares exists in the
+ * catalogue, but neither asserts that `mapCoreError` emits that code, with
+ * that status, for the corresponding core error — so an arm returning the
+ * wrong status, or an `asMaybe*` import that quietly stops matching after a
+ * core upgrade, would fall through to the `INTERNAL_ERROR`/500 default with
+ * every gate still green.
+ */
+const cases: Array<{
+  code: string
+  status: number
+  error: unknown
+  /** Keys the arm promises in `details`. */
+  details?: string[]
+}> = [
+  {
+    code: 'CHALLENGE_REQUIRED',
+    status: 403,
+    error: new ChallengeError({
+      challengeId: 'cid',
+      challengeUri: 'https://example.com/c'
+    }),
+    details: ['challengeId', 'challengeUri']
+  },
+  {
+    code: 'PASSWORD_ERROR',
+    status: 401,
+    error: new PasswordError({ wait_seconds: 30 }),
+    // The caller needs the wait to know when to retry.
+    details: ['wait']
+  },
+  {
+    code: 'OTP_REQUIRED',
+    status: 401,
+    error: new OtpError({ otp_reset_auth: 'token', voucher_id: 'v' }),
+    // Seven fields, two of which are credentials the client redacts — see
+    // `redaction.test.ts`. The arm has to emit them for that to be possible.
+    details: ['reason', 'resetToken', 'voucherId']
+  },
+  { code: 'USERNAME_ERROR', status: 400, error: new UsernameError() },
+  {
+    code: 'PIN_DISABLED',
+    status: 403,
+    error: new PinDisabledError('PIN login is disabled')
+  },
+  {
+    code: 'INSUFFICIENT_FUNDS',
+    status: 422,
+    error: new InsufficientFundsError({ tokenId: null })
+  },
+  { code: 'DUST_SPEND', status: 422, error: new DustSpendError() },
+  { code: 'PENDING_FUNDS', status: 422, error: new PendingFundsError() },
+  { code: 'SPEND_TO_SELF', status: 422, error: new SpendToSelfError() },
+  {
+    code: 'NO_AMOUNT_SPECIFIED',
+    status: 400,
+    error: new NoAmountSpecifiedError()
+  },
+  { code: 'NETWORK_ERROR', status: 503, error: new NetworkError() },
+  { code: 'OBSOLETE_API', status: 426, error: new ObsoleteApiError() },
+  {
+    code: 'SWAP_ABOVE_LIMIT',
+    status: 422,
+    error: new SwapAboveLimitError(swapInfo, '999'),
+    details: ['nativeMax']
+  },
+  {
+    code: 'SWAP_BELOW_LIMIT',
+    status: 422,
+    error: new SwapBelowLimitError(swapInfo, '1'),
+    details: ['nativeMin']
+  },
+  {
+    code: 'SWAP_CURRENCY',
+    status: 422,
+    error: new SwapCurrencyError(swapInfo, swapRequest)
+  },
+  {
+    code: 'SWAP_PERMISSION',
+    status: 403,
+    error: new SwapPermissionError(swapInfo, 'geoRestriction')
+  },
+  {
+    code: 'SWAP_ADDRESS',
+    status: 422,
+    error: new SwapAddressError(swapInfo, { reason: 'mustMatch' })
+  },
+  { code: 'SAME_CURRENCY', status: 400, error: new SameCurrencyError() }
+]
+
+describe('toErrorBody', () => {
+  it.each(cases)('maps $code to $status', ({ code, status, error }) => {
+    const result = toErrorBody(error)
+    expect(result.status).toBe(status)
+    expect(result.body.error.code).toBe(code)
+    // The status is repeated in the body for clients that only see the body.
+    expect(result.body.error.status).toBe(status)
+    expect(typeof result.body.error.message).toBe('string')
+    expect(result.body.error.message).not.toBe('')
+  })
+
+  it.each(cases.filter(c => c.details != null))(
+    '$code carries the details it promises',
+    ({ details, error }) => {
+      const { body } = toErrorBody(error)
+      for (const key of details ?? []) {
+        expect(body.error.details).toHaveProperty(key)
+      }
+    }
+  )
+
+  it('substitutes prose when core supplies an empty message', () => {
+    // Most of core's error constructors take the message as an argument, so
+    // an empty one is reachable, and `{"code":"PIN_DISABLED","message":""}`
+    // tells a caller nothing the code did not already say.
+    const { body } = toErrorBody(new PinDisabledError(''))
+    expect(body.error.code).toBe('PIN_DISABLED')
+    expect(body.error.message).not.toBe('')
+  })
+
+  it('passes an EngineError through unchanged', () => {
+    const result = toErrorBody(
+      engineError('OBJECT_IN_USE', 'busy', 409, { objectId: 'tx_1' })
+    )
+    expect(result).toStrictEqual({
+      status: 409,
+      body: {
+        error: {
+          code: 'OBJECT_IN_USE',
+          message: 'busy',
+          status: 409,
+          details: { objectId: 'tx_1' }
+        }
+      }
+    })
+  })
+
+  it('falls back to INTERNAL_ERROR/500 for anything unrecognised', () => {
+    expect(toErrorBody(new Error('boom'))).toStrictEqual({
+      status: 500,
+      body: { error: { code: 'INTERNAL_ERROR', message: 'boom', status: 500 } }
+    })
+    // A thrown non-Error still has to produce a body rather than crash the
+    // response path.
+    expect(toErrorBody('boom').body.error.code).toBe('INTERNAL_ERROR')
+    expect(toErrorBody(undefined).body.error.code).toBe('INTERNAL_ERROR')
+  })
+})
+
+describe('the published catalogue and mapCoreError agree', () => {
+  const coreCodes = errorCodes.filter(e => e.origin === 'core')
+
+  it('produces every code the reference documents as coming from core', () => {
+    const produced = new Set(cases.map(c => c.code))
+    const missing = coreCodes
+      .map(e => e.code)
+      .filter(code => !produced.has(code))
+    expect(missing).toStrictEqual([])
+  })
+
+  it('uses the status the reference publishes for each code', () => {
+    const published = new Map(coreCodes.map(e => [e.code, e.status]))
+    for (const { code, status } of cases) {
+      // No `?? status` fallback: comparing a value against itself whenever
+      // the code is absent from the catalogue meant a case with a wrong code
+      // *and* a wrong status passed both assertions in this describe — the
+      // `missing` check above only tests catalogue ⊆ cases.
+      expect(published.has(code)).toBe(true)
+      expect({ code, status }).toStrictEqual({
+        code,
+        status: published.get(code)
+      })
+    }
+  })
+})
diff --git a/src/__tests__/cli/events.test.ts b/src/__tests__/cli/events.test.ts
new file mode 100644
index 00000000000..33a32488412
--- /dev/null
+++ b/src/__tests__/cli/events.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it, jest } from '@jest/globals'
+import type { ServerResponse } from 'http'
+
+import { EventHub } from '../../cli/engine/events'
+
+/** Just enough of a `ServerResponse` for the hub to write to. */
+function makeClient(opts: { writableLength?: number } = {}): {
+  res: ServerResponse
+  frames: string[]
+  destroyed: () => boolean
+  close: () => void
+} {
+  const frames: string[] = []
+  let destroyed = false
+  let onClose: (() => void) | undefined
+  const res = {
+    writeHead: () => {},
+    write: (frame: string) => {
+      frames.push(frame)
+      return true
+    },
+    end: () => {},
+    destroy: () => {
+      destroyed = true
+    },
+    get writableLength() {
+      return opts.writableLength ?? 0
+    },
+    writableEnded: false,
+    destroyed: false,
+    on: (event: string, handler: () => void) => {
+      if (event === 'close') onClose = handler
+    }
+  } as unknown as ServerResponse
+  return {
+    res,
+    frames,
+    destroyed: () => destroyed,
+    close: () => onClose?.()
+  }
+}
+
+/** The data payload of one SSE frame. */
+function payloadOf(frame: string): any {
+  const line = frame.split('\n').find(l => l.startsWith('data: '))
+  return JSON.parse((line ?? '').slice('data: '.length))
+}
+
+describe('EventHub', () => {
+  it('sends a filtered client only the types it asked for', () => {
+    const hub = new EventHub()
+    const client = makeClient()
+    hub.addSseClient(client.res, { kind: 'context' }, new Set(['core.log']))
+    client.frames.length = 0
+
+    hub.emit('core.log', { message: 'kept' })
+    hub.emit('session.created', { sessionId: 'dropped' })
+    expect(client.frames).toHaveLength(1)
+    expect(payloadOf(client.frames[0])).toStrictEqual({ message: 'kept' })
+  })
+
+  it('always sends subscription.closed to a filtered client', () => {
+    const hub = new EventHub()
+    const client = makeClient()
+    hub.addSseClient(client.res, { kind: 'context' }, new Set(['core.log']))
+    client.frames.length = 0
+
+    // Without the exemption a filtering client would never learn why its
+    // stream ended.
+    hub.closeAll('engineShutdown')
+    expect(client.frames).toHaveLength(1)
+    expect(payloadOf(client.frames[0])).toStrictEqual({
+      reason: 'engineShutdown'
+    })
+  })
+
+  it('drops a client that is too far behind, and says so', () => {
+    const hub = new EventHub()
+    const changed = jest.fn<() => void>()
+    hub.onClientsChanged = changed
+    // Past MAX_SSE_BUFFER_BYTES: a consumer this slow is the reason the
+    // `--type` filter moved to the transport in the first place.
+    const client = makeClient({ writableLength: 2 * 1024 * 1024 })
+    hub.addSseClient(client.res, { kind: 'context' })
+    changed.mockClear()
+
+    hub.emit('core.log', { message: 'x' })
+    expect(client.destroyed()).toBe(true)
+    expect(hub.clientCount).toBe(0)
+    expect(changed).toHaveBeenCalled()
+  })
+
+  it('keeps every client when one payload cannot be serialised', () => {
+    const hub = new EventHub()
+    const a = makeClient()
+    const b = makeClient()
+    hub.addSseClient(a.res, { kind: 'context' })
+    hub.addSseClient(b.res, { kind: 'context' })
+    a.frames.length = 0
+    b.frames.length = 0
+
+    const circular: any = {}
+    circular.self = circular
+    hub.emit('core.log', circular)
+    // One bad payload used to disconnect every subscriber.
+    expect(hub.clientCount).toBe(2)
+    expect(a.frames).toHaveLength(0)
+
+    hub.emit('core.log', { message: 'after' })
+    expect(a.frames).toHaveLength(1)
+    expect(b.frames).toHaveLength(1)
+  })
+
+  it('scopes a session event to that session', () => {
+    const hub = new EventHub()
+    const mine = makeClient()
+    const other = makeClient()
+    const context = makeClient()
+    hub.addSseClient(mine.res, { kind: 'session', sessionId: 'sess_a' })
+    hub.addSseClient(other.res, { kind: 'session', sessionId: 'sess_b' })
+    hub.addSseClient(context.res, { kind: 'context' })
+    for (const c of [mine, other, context]) c.frames.length = 0
+
+    hub.emit(
+      'session.created',
+      { sessionId: 'sess_a…' },
+      { kind: 'session', sessionId: 'sess_a' }
+    )
+    // A stream opened against one account used to receive another account's
+    // username and session prefix.
+    expect(mine.frames).toHaveLength(1)
+    expect(other.frames).toHaveLength(0)
+    // A context stream is broader than any session, so it still sees it.
+    expect(context.frames).toHaveLength(1)
+  })
+
+  it('reaps a client whose write fails on the keepalive', () => {
+    const hub = new EventHub()
+    const client = makeClient()
+    hub.addSseClient(client.res, { kind: 'context' })
+    ;(client.res as any).write = () => {
+      throw new Error('EPIPE')
+    }
+
+    // A subscriber that vanished without a clean FIN never emitted 'close',
+    // so it held the engine's EdgeContext open indefinitely.
+    hub.pingClients()
+    expect(hub.clientCount).toBe(0)
+  })
+
+  it('serialises one frame however many clients there are', () => {
+    const hub = new EventHub()
+    const a = makeClient()
+    const b = makeClient()
+    hub.addSseClient(a.res, { kind: 'context' })
+    hub.addSseClient(b.res, { kind: 'context' })
+    a.frames.length = 0
+    b.frames.length = 0
+
+    let serialised = 0
+    const payload = {
+      toJSON: () => {
+        serialised++
+        return { message: 'once' }
+      }
+    }
+    hub.emit('core.log', payload)
+    expect(serialised).toBe(1)
+    expect(a.frames).toHaveLength(1)
+    expect(b.frames).toHaveLength(1)
+  })
+
+  it('does nothing at all with no listeners and no clients', () => {
+    const hub = new EventHub()
+    let serialised = 0
+    hub.emit('core.log', {
+      toJSON: () => {
+        serialised++
+        return {}
+      }
+    })
+    // `core.log` is a firehose, so the no-subscriber case must be free.
+    expect(serialised).toBe(0)
+  })
+})
diff --git a/src/__tests__/cli/exitCodes.test.ts b/src/__tests__/cli/exitCodes.test.ts
new file mode 100644
index 00000000000..62f84bd7b9d
--- /dev/null
+++ b/src/__tests__/cli/exitCodes.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { CLI_EXIT_CODES, errorCodes } from '../../../docs/api/shared'
+import {
+  errorCodesFor,
+  EXIT,
+  EXIT_CODE_BY_ERROR,
+  exitCodeForApiError
+} from '../../cli/client/exitCodes'
+
+describe('exitCodeForApiError', () => {
+  it('maps every code in the table to its exit code', () => {
+    for (const [code, exit] of Object.entries(EXIT_CODE_BY_ERROR)) {
+      expect({ code, exit: exitCodeForApiError(code, 400) }).toStrictEqual({
+        code,
+        exit
+      })
+    }
+  })
+
+  it('prefers the explicit code over the 503 rule', () => {
+    // The engine only ever sends this code with a 503, so testing the status
+    // first made EXIT.ENGINE unreachable and reported a daemon that is going
+    // away as a network failure.
+    expect(exitCodeForApiError('ENGINE_SHUTTING_DOWN', 503)).toBe(EXIT.ENGINE)
+    expect(exitCodeForApiError('NETWORK_ERROR', 503)).toBe(EXIT.NETWORK)
+  })
+
+  it('falls back to NETWORK for any other 503, and GENERIC otherwise', () => {
+    expect(exitCodeForApiError('SOMETHING_NEW', 503)).toBe(EXIT.NETWORK)
+    expect(exitCodeForApiError('SOMETHING_NEW', 500)).toBe(EXIT.GENERIC)
+    expect(exitCodeForApiError('', 418)).toBe(EXIT.GENERIC)
+  })
+})
+
+describe('the published exit-code table', () => {
+  it('lists every mapped error code', () => {
+    // Both sides used to state the membership separately — a 35-line
+    // `if`-chain and English prose in a `doc` field — and `ENGINE_SHUTTING_DOWN`
+    // was missing from the published one.
+    for (const code of Object.keys(EXIT_CODE_BY_ERROR)) {
+      const row = CLI_EXIT_CODES.find(r => r.code === EXIT_CODE_BY_ERROR[code])
+      expect(row?.doc).toContain(`\`${code}\``)
+    }
+  })
+
+  it('covers every exit code the CLI can return', () => {
+    const published = new Set(CLI_EXIT_CODES.map(r => r.code))
+    for (const code of Object.values(EXIT)) {
+      expect(published.has(code)).toBe(true)
+    }
+  })
+
+  it('only maps codes the error catalogue defines', () => {
+    const known = new Set(errorCodes.map(e => e.code))
+    const unknown = Object.keys(EXIT_CODE_BY_ERROR).filter(
+      code => !known.has(code)
+    )
+    expect(unknown).toStrictEqual([])
+  })
+
+  it('groups the codes the same way the table does', () => {
+    expect(errorCodesFor(EXIT.NOT_FOUND)).toStrictEqual([
+      'NOT_FOUND',
+      'WALLET_NOT_FOUND',
+      'TOKEN_NOT_FOUND'
+    ])
+  })
+})
diff --git a/src/__tests__/cli/fetchPluginKeys.test.ts b/src/__tests__/cli/fetchPluginKeys.test.ts
new file mode 100644
index 00000000000..de45fbc17d3
--- /dev/null
+++ b/src/__tests__/cli/fetchPluginKeys.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { fetchPluginKeys, getKeysAppId } from '../../cli/engine/fetchPluginKeys'
+
+describe('getKeysAppId', () => {
+  it('uses edge when the CLI appId is empty, matching the GUI infoRollup slug', () => {
+    expect(getKeysAppId('')).toBe('edge')
+  })
+
+  it('keeps an explicit CLI appId', () => {
+    expect(getKeysAppId('co.edgesecure.app')).toBe('co.edgesecure.app')
+  })
+})
+
+describe('fetchPluginKeys', () => {
+  it('throws when neither a native signer nor apiKey/apiSecret is provided', async () => {
+    await expect(
+      fetchPluginKeys({ appId: '', testMode: true })
+    ).rejects.toThrow('No HMAC credentials available for infoRollup appKeys')
+  })
+})
diff --git a/src/__tests__/cli/idleShutdown.test.ts b/src/__tests__/cli/idleShutdown.test.ts
new file mode 100644
index 00000000000..46c0cc5c68d
--- /dev/null
+++ b/src/__tests__/cli/idleShutdown.test.ts
@@ -0,0 +1,176 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+import { IdleShutdown } from '../../cli/engine/idleShutdown'
+
+/**
+ * The third async engine component, and the one with no unit test.
+ *
+ * Counts are injected, so each case drives the exact state the engine would
+ * be in without needing a core, a socket or a session.
+ */
+function makeIdle(opts: {
+  seconds?: number
+  sessions?: number
+  subscribers?: number
+  handles?: number
+}): {
+  idle: IdleShutdown
+  onFire: jest.Mock<() => void>
+  setSessions: (n: number) => void
+  setSubscribers: (n: number) => void
+  setHandles: (n: number) => void
+} {
+  let sessions = opts.sessions ?? 0
+  let subscribers = opts.subscribers ?? 0
+  let handles = opts.handles ?? 0
+  const onFire = jest.fn<() => void>()
+  const idle = new IdleShutdown({
+    idleTimeoutSeconds: opts.seconds ?? 60,
+    getSessionCount: () => sessions,
+    getSubscriberCount: () => subscribers,
+    getSessionlessHandleCount: () => handles,
+    onFire
+  })
+  return {
+    idle,
+    onFire,
+    setSessions: (n: number) => {
+      sessions = n
+    },
+    setSubscribers: (n: number) => {
+      subscribers = n
+    },
+    setHandles: (n: number) => {
+      handles = n
+    }
+  }
+}
+
+describe('IdleShutdown', () => {
+  beforeEach(() => {
+    jest.useFakeTimers()
+  })
+
+  it('fires once the idle window passes with nothing holding it', async () => {
+    const { idle, onFire } = makeIdle({ seconds: 60 })
+    await jest.advanceTimersByTimeAsync(59_000)
+    expect(onFire).not.toHaveBeenCalled()
+    await jest.advanceTimersByTimeAsync(2_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+
+  it('never fires with the timeout disabled', async () => {
+    const { idle, onFire } = makeIdle({ seconds: 0 })
+    expect(idle.idleShutdownAt).toBeNull()
+    await jest.advanceTimersByTimeAsync(24 * 60 * 60 * 1000)
+    expect(onFire).not.toHaveBeenCalled()
+    idle.stop()
+  })
+
+  it('is held open by a logged-in session', async () => {
+    const { idle, onFire, setSessions } = makeIdle({ seconds: 60 })
+    setSessions(1)
+    idle.notifySessionsChanged()
+    expect(idle.idleShutdownAt).toBeNull()
+    await jest.advanceTimersByTimeAsync(5 * 60 * 1000)
+    expect(onFire).not.toHaveBeenCalled()
+
+    // The last logout re-arms it, rather than leaving the engine lingering
+    // until the next request.
+    setSessions(0)
+    idle.notifySessionsChanged()
+    expect(idle.idleShutdownAt).not.toBeNull()
+    await jest.advanceTimersByTimeAsync(61_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+
+  it('is held open by a subscriber and re-arms when the last one leaves', async () => {
+    const { idle, onFire, setSubscribers } = makeIdle({ seconds: 60 })
+    setSubscribers(1)
+    idle.notifySubscribersChanged()
+    // The documented contract: a subscription holds the *engine* open even
+    // with no account logged in, because the stream would die under it.
+    expect(idle.idleShutdownAt).toBeNull()
+    await jest.advanceTimersByTimeAsync(5 * 60 * 1000)
+    expect(onFire).not.toHaveBeenCalled()
+
+    setSubscribers(0)
+    idle.notifySubscribersChanged()
+    expect(idle.idleShutdownAt).not.toBeNull()
+    await jest.advanceTimersByTimeAsync(61_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+
+  it('is held open by an in-flight request past the window', async () => {
+    const { idle, onFire } = makeIdle({ seconds: 60 })
+    idle.beginRequest()
+    expect(idle.requestsInFlight).toBe(1)
+    // A cold login or a `resync-blockchain` outlives the idle timeout, and
+    // shutting down underneath it left the client holding a destroyed socket.
+    await jest.advanceTimersByTimeAsync(5 * 60 * 1000)
+    expect(onFire).not.toHaveBeenCalled()
+
+    idle.endRequest()
+    expect(idle.requestsInFlight).toBe(0)
+    await jest.advanceTimersByTimeAsync(61_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+
+  it('is held open by a pending login that has no session', async () => {
+    const { idle, onFire, setHandles } = makeIdle({ seconds: 60 })
+    setHandles(1)
+    idle.notifyHandlesChanged()
+    // `request-edge-login --no-wait` prints a lobby and exits, leaving no
+    // session and no subscriber; the handle's TTL is exactly the default idle
+    // timeout, so the engine used to shut down under the QR code.
+    expect(idle.idleShutdownAt).toBeNull()
+    await jest.advanceTimersByTimeAsync(5 * 60 * 1000)
+    expect(onFire).not.toHaveBeenCalled()
+
+    setHandles(0)
+    idle.notifyHandlesChanged()
+    await jest.advanceTimersByTimeAsync(61_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+
+  it('reports an in-flight request without hiding its own shutdown time', () => {
+    const { idle } = makeIdle({ seconds: 60 })
+    idle.beginRequest()
+    // `idleShutdownAt` deliberately ignores in-flight requests: the request
+    // asking for the shutdown time is itself in flight.
+    expect(idle.idleShutdownAt).not.toBeNull()
+    idle.endRequest()
+    idle.stop()
+  })
+
+  it('applies a new timeout immediately', async () => {
+    const { idle, onFire } = makeIdle({ seconds: 600 })
+    idle.setTimeoutSeconds(30)
+    await jest.advanceTimersByTimeAsync(31_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+
+  it('stop disarms it for good', async () => {
+    const { idle, onFire } = makeIdle({ seconds: 60 })
+    idle.stop()
+    await jest.advanceTimersByTimeAsync(5 * 60 * 1000)
+    expect(onFire).not.toHaveBeenCalled()
+  })
+
+  it('touch pushes the window out', async () => {
+    const { idle, onFire } = makeIdle({ seconds: 60 })
+    await jest.advanceTimersByTimeAsync(50_000)
+    idle.touch()
+    await jest.advanceTimersByTimeAsync(50_000)
+    expect(onFire).not.toHaveBeenCalled()
+    await jest.advanceTimersByTimeAsync(11_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+    idle.stop()
+  })
+})
diff --git a/src/__tests__/cli/jsonBody.test.ts b/src/__tests__/cli/jsonBody.test.ts
new file mode 100644
index 00000000000..80e07ba300f
--- /dev/null
+++ b/src/__tests__/cli/jsonBody.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from '@jest/globals'
+import { Readable } from 'stream'
+
+import { readJsonBody } from '../../cli/engine/json'
+
+/** A request-shaped stream carrying `text`, with whatever headers it needs. */
+function makeRequest(text: string, headers: Record<string, string> = {}): any {
+  const stream: any = Readable.from([Buffer.from(text, 'utf8')])
+  stream.headers = headers
+  return stream
+}
+
+/** The `code` an engineError carries. */
+async function codeOf(fn: () => Promise<unknown>): Promise<string> {
+  try {
+    await fn()
+  } catch (error) {
+    return (error as { code: string }).code
+  }
+  throw new Error('expected a rejection')
+}
+
+describe('readJsonBody', () => {
+  it('parses a JSON object', async () => {
+    const body = await readJsonBody(makeRequest('{"walletId":"abc"}'))
+    expect(body).toStrictEqual({ walletId: 'abc' })
+  })
+
+  it('answers an empty body with undefined', async () => {
+    // Not an error: a POST with no body is how `engine-stop` is called.
+    expect(await readJsonBody(makeRequest(''))).toBeUndefined()
+  })
+
+  it('refuses invalid JSON with BAD_REQUEST', async () => {
+    expect(await codeOf(async () => await readJsonBody(makeRequest('{')))).toBe(
+      'BAD_REQUEST'
+    )
+  })
+
+  it('refuses an oversized content-length before reading anything', async () => {
+    // The pre-check exists so a declared-huge upload is refused without
+    // being buffered.
+    expect(
+      await codeOf(
+        async () =>
+          await readJsonBody(
+            makeRequest('{}', { 'content-length': String(8 * 1024 * 1024) })
+          )
+      )
+    ).toBe('PAYLOAD_TOO_LARGE')
+  })
+
+  it('refuses a stream that outgrows the cap even when content-length lies', async () => {
+    const big = `{"x":"${'a'.repeat(5 * 1024 * 1024)}"}`
+    expect(
+      await codeOf(
+        async () =>
+          await readJsonBody(makeRequest(big, { 'content-length': '2' }))
+      )
+    ).toBe('PAYLOAD_TOO_LARGE')
+  })
+
+  it('accepts a body with no content-length at all', async () => {
+    const body = await readJsonBody(makeRequest('{"ok":true}'))
+    expect(body).toStrictEqual({ ok: true })
+  })
+})
diff --git a/src/__tests__/cli/keysConfig.test.ts b/src/__tests__/cli/keysConfig.test.ts
new file mode 100644
index 00000000000..affc39b2eeb
--- /dev/null
+++ b/src/__tests__/cli/keysConfig.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { mergePluginApiKeys } from '../../cli/engine/keysConfig'
+
+describe('mergePluginApiKeys', () => {
+  it('lets the preferred object win field-by-field', () => {
+    expect(
+      mergePluginApiKeys(
+        { monero: { edgeApiKey: 'remote' } },
+        { monero: { edgeApiKey: 'local', apiKey: 'keep' }, bitcoin: true }
+      )
+    ).toEqual({
+      bitcoin: true,
+      monero: { apiKey: 'keep', edgeApiKey: 'remote' }
+    })
+  })
+})
diff --git a/src/__tests__/cli/logger.test.ts b/src/__tests__/cli/logger.test.ts
new file mode 100644
index 00000000000..409177cc138
--- /dev/null
+++ b/src/__tests__/cli/logger.test.ts
@@ -0,0 +1,125 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest
+} from '@jest/globals'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import type * as LoggerModule from '../../cli/engine/logger'
+
+/**
+ * `logger` resolves the home directory at call time, so stubbing
+ * `os.homedir` keeps every case off the developer's real `~/.edge-cli`.
+ * Setting `HOME` is *not* enough: under jest `os.homedir()` does not read it,
+ * and the sweep would then delete real logs.
+ */
+let home: string
+let homedir: jest.SpiedFunction<typeof os.homedir>
+
+type Logger = typeof LoggerModule
+function load(): Logger {
+  return require('../../cli/engine/logger')
+}
+
+beforeEach(() => {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-logger-'))
+  homedir = jest.spyOn(os, 'homedir').mockReturnValue(home)
+  jest.resetModules()
+})
+afterEach(() => {
+  homedir.mockRestore()
+  fs.rmSync(home, { recursive: true, force: true })
+})
+
+const DAY = 86_400_000
+
+function logsDir(): string {
+  return path.join(home, '.edge-cli', 'logs')
+}
+
+/** Seed one log file, `ageDays` old. */
+function seedLog(name: string, ageDays: number): string {
+  fs.mkdirSync(logsDir(), { recursive: true })
+  const file = path.join(logsDir(), name)
+  fs.writeFileSync(file, 'log line\n')
+  const when = new Date(Date.now() - ageDays * DAY)
+  fs.utimesSync(file, when, when)
+  return file
+}
+
+/** Seed a run file claiming `pid` for `profile`. */
+function seedRunFile(profile: string, pid: number): void {
+  const dir = path.join(home, '.edge-cli', 'run', profile)
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(path.join(dir, 'engine.json'), JSON.stringify({ pid }))
+}
+
+describe('sweepOldLogs', () => {
+  it('removes a back-dated engine log and keeps a fresh one', () => {
+    const { sweepOldLogs } = load()
+    const old = seedLog('engine-aaaa.log', 30)
+    const fresh = seedLog('engine-bbbb.log', 1)
+    expect(sweepOldLogs()).toBe(1)
+    expect(fs.existsSync(old)).toBe(false)
+    expect(fs.existsSync(fresh)).toBe(true)
+  })
+
+  it('removes a rolled log too', () => {
+    const { sweepOldLogs } = load()
+    const rolled = seedLog('engine-aaaa.log.1', 30)
+    expect(sweepOldLogs()).toBe(1)
+    expect(fs.existsSync(rolled)).toBe(false)
+  })
+
+  it('leaves a file that is not an engine log', () => {
+    const { sweepOldLogs } = load()
+    const other = seedLog('something-else.log', 30)
+    expect(sweepOldLogs()).toBe(0)
+    expect(fs.existsSync(other)).toBe(true)
+  })
+
+  it('keeps a log whose profile still has a live run file', () => {
+    const { sweepOldLogs } = load()
+    // `unlinkSync` succeeds on POSIX for a file another process holds open,
+    // so the age test alone let one engine delete a live engine's log: the
+    // writer kept writing to an unlinked inode while `logger.logPath` still
+    // named the file.
+    const live = seedLog('engine-liveprof.log', 30)
+    seedRunFile('liveprof', process.pid)
+    expect(sweepOldLogs()).toBe(0)
+    expect(fs.existsSync(live)).toBe(true)
+  })
+
+  it('removes a log whose profile names a dead process', () => {
+    const { sweepOldLogs } = load()
+    const dead = seedLog('engine-deadprof.log', 30)
+    // 0x7FFFFFFF is above every pid_max.
+    seedRunFile('deadprof', 0x7fffffff)
+    expect(sweepOldLogs()).toBe(1)
+    expect(fs.existsSync(dead)).toBe(false)
+  })
+
+  it('keeps the caller’s own log whatever its age', () => {
+    const { sweepOldLogs } = load()
+    const mine = seedLog('engine-mine.log', 30)
+    expect(sweepOldLogs(undefined, mine)).toBe(0)
+    expect(fs.existsSync(mine)).toBe(true)
+  })
+
+  it('returns 0 when there is no logs directory yet', () => {
+    const { sweepOldLogs } = load()
+    expect(sweepOldLogs()).toBe(0)
+  })
+
+  it('honours an explicit max age', () => {
+    const { sweepOldLogs } = load()
+    const twoDays = seedLog('engine-aaaa.log', 2)
+    expect(sweepOldLogs(DAY)).toBe(1)
+    expect(fs.existsSync(twoDays)).toBe(false)
+  })
+})
diff --git a/src/__tests__/cli/objectHandles.test.ts b/src/__tests__/cli/objectHandles.test.ts
new file mode 100644
index 00000000000..9cd324b1329
--- /dev/null
+++ b/src/__tests__/cli/objectHandles.test.ts
@@ -0,0 +1,193 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+import {
+  OBJECT_HANDLE_TTL_MS,
+  ObjectHandleStore
+} from '../../cli/engine/objectHandles'
+
+/** The error shape `engineError` produces. */
+interface ThrownEngineError extends Error {
+  code: string
+  status: number
+}
+
+function codeOf(fn: () => unknown): { code: string; status: number } {
+  try {
+    fn()
+  } catch (error) {
+    const engineError = error as ThrownEngineError
+    return { code: engineError.code, status: engineError.status }
+  }
+  throw new Error('expected a throw')
+}
+
+describe('ObjectHandleStore', () => {
+  let store: ObjectHandleStore
+
+  beforeEach(() => {
+    jest.useFakeTimers()
+    store = new ObjectHandleStore()
+  })
+
+  it('reads do not refresh the TTL, updates do', () => {
+    const { objectId } = store.create({
+      kind: 'transaction',
+      prefix: 'tx_',
+      value: { txid: 'a' }
+    })
+
+    jest.advanceTimersByTime(OBJECT_HANDLE_TTL_MS - 1000)
+    store.get(objectId)
+    jest.advanceTimersByTime(2000)
+    expect(codeOf(() => store.get(objectId))).toEqual({
+      code: 'OBJECT_EXPIRED',
+      status: 410
+    })
+    expect(store.size).toBe(0)
+  })
+
+  it('refuses a handle of the wrong kind', () => {
+    const { objectId } = store.create({
+      kind: 'transaction',
+      prefix: 'tx_',
+      value: { txid: 'a' }
+    })
+    expect(codeOf(() => store.get(objectId, 'swap'))).toEqual({
+      code: 'OBJECT_KIND_MISMATCH',
+      status: 400
+    })
+  })
+
+  it('runs onExpire exactly once when released', async () => {
+    const onExpire = jest.fn<() => void>()
+    const { objectId } = store.create({
+      kind: 'swap',
+      prefix: 'swap_',
+      value: { quote: true },
+      onExpire
+    })
+
+    expect(await store.delete(objectId)).toBe(true)
+    expect(await store.delete(objectId)).toBe(false)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  describe('consume', () => {
+    it('refuses a second call while the first is in flight', async () => {
+      const { objectId } = store.create({
+        kind: 'swap',
+        prefix: 'swap_',
+        value: { quote: true }
+      })
+      const record = store.get(objectId, 'swap')
+
+      let release = (): void => {}
+      const inFlight = store.consume(record, async () => {
+        await new Promise<void>(resolve => {
+          release = resolve
+        })
+        return 'approved'
+      })
+
+      // The retry a client makes after its own socket timeout.
+      expect(codeOf(() => store.get(objectId, 'swap'))).toEqual({
+        code: 'OBJECT_IN_USE',
+        status: 409
+      })
+
+      release()
+      expect(await inFlight).toBe('approved')
+      expect(store.size).toBe(0)
+    })
+
+    it('is not swept while in flight, even past its TTL', async () => {
+      const onExpire = jest.fn<() => void>()
+      const { objectId } = store.create({
+        kind: 'swap',
+        prefix: 'swap_',
+        value: { quote: true },
+        onExpire,
+        ttlMs: 1000
+      })
+      const record = store.get(objectId, 'swap')
+      store.startTicker()
+
+      let release = (): void => {}
+      const inFlight = store.consume(record, async () => {
+        await new Promise<void>(resolve => {
+          release = resolve
+        })
+        return 'approved'
+      })
+
+      // Long enough for the original TTL to lapse and the sweeper to run.
+      await jest.advanceTimersByTimeAsync(60_000)
+
+      // `delete` runs `onExpire`, which for a swap closes the quote at the
+      // exchange — never while its approval is still running.
+      expect(onExpire).not.toHaveBeenCalled()
+
+      release()
+      await inFlight
+      expect(onExpire).toHaveBeenCalledTimes(1)
+      store.stopTicker()
+    })
+
+    it('releases the handle when the operation fails', async () => {
+      const onExpire = jest.fn<() => void>()
+      const { objectId } = store.create({
+        kind: 'swap',
+        prefix: 'swap_',
+        value: { quote: true },
+        onExpire,
+        ttlMs: 1000
+      })
+      const record = store.get(objectId, 'swap')
+
+      await expect(
+        store.consume(record, async () => {
+          jest.advanceTimersByTime(5000)
+          throw new Error('INSUFFICIENT_FUNDS')
+        })
+      ).rejects.toThrow('INSUFFICIENT_FUNDS')
+
+      // A swap `approve()` signs, broadcasts, and then does post-broadcast
+      // bookkeeping. From out here a failure after the money moved is
+      // indistinguishable from one before it, so the handle is gone and a
+      // retry has to fetch a fresh quote rather than re-broadcasting.
+      expect(onExpire).toHaveBeenCalledTimes(1)
+      expect(codeOf(() => store.get(objectId, 'swap')).code).toBe(
+        'OBJECT_NOT_FOUND'
+      )
+    })
+  })
+
+  describe('hold', () => {
+    it('keeps a handle alive across a call that outlives its TTL', async () => {
+      const onExpire = jest.fn<() => void>()
+      const { objectId } = store.create({
+        kind: 'transaction',
+        prefix: 'tx_',
+        value: { txid: 'unsigned' },
+        onExpire,
+        ttlMs: 1000
+      })
+      const record = store.get(objectId, 'transaction')
+      store.startTicker()
+
+      const broadcast = store.hold(record, async () => {
+        await jest.advanceTimersByTimeAsync(60_000)
+        return { txid: 'broadcast' }
+      })
+
+      expect(await broadcast).toEqual({ txid: 'broadcast' })
+      expect(onExpire).not.toHaveBeenCalled()
+
+      // The handle survives, so `save-tx` can still run against it.
+      expect(store.update(objectId, { txid: 'broadcast' }).objectId).toBe(
+        objectId
+      )
+      store.stopTicker()
+    })
+  })
+})
diff --git a/src/__tests__/cli/parseArgs.test.ts b/src/__tests__/cli/parseArgs.test.ts
new file mode 100644
index 00000000000..9dd2b18a8e5
--- /dev/null
+++ b/src/__tests__/cli/parseArgs.test.ts
@@ -0,0 +1,229 @@
+// The generated command table, so `isCommandName` has a registry to read:
+// the "value is a command" guard is the whole point of one of these cases.
+import '../../cli/commands/all'
+
+import { describe, expect, it } from '@jest/globals'
+
+import { UsageError } from '../../cli/command'
+import { parseCommandArgs } from '../../cli/commandArgs'
+import { parseCliArgs } from '../../cli/parseArgs'
+
+/**
+ * The CLI's argv front door.
+ *
+ * Every corner these two files were hardened against was recorded as a
+ * comment rather than a test, and the 130 offline invocations cover only the
+ * shapes they happen to use.
+ */
+function usage(fn: () => unknown): string {
+  try {
+    fn()
+  } catch (error) {
+    if (error instanceof UsageError) return error.message
+    throw error
+  }
+  throw new Error('expected a UsageError')
+}
+
+describe('parseCliArgs', () => {
+  it('separates options from the command and its arguments', () => {
+    const { options, argv } = parseCliArgs([
+      '-t',
+      '--directory=/tmp/x',
+      'balance-map',
+      '--wallet-id=abc'
+    ])
+    expect(options.test).toBe(true)
+    expect(options.directory).toBe('/tmp/x')
+    expect(argv).toStrictEqual(['balance-map', '--wallet-id=abc'])
+  })
+
+  it('takes a value in either spelling', () => {
+    expect(parseCliArgs(['--directory=/tmp/a']).options.directory).toBe(
+      '/tmp/a'
+    )
+    expect(parseCliArgs(['--directory', '/tmp/a']).options.directory).toBe(
+      '/tmp/a'
+    )
+  })
+
+  it('refuses an empty value, because the profile hash is built from it', () => {
+    // An empty directory on this side and a default on the engine's side are
+    // two different engines.
+    expect(usage(() => parseCliArgs(['--directory=']))).toContain(
+      'Missing value'
+    )
+    expect(usage(() => parseCliArgs(['--app-id=']))).toContain('Missing value')
+    expect(usage(() => parseCliArgs(['--api-key=']))).toContain('Missing value')
+  })
+
+  it('refuses an empty value in the space form too', () => {
+    // `-d ""` is the same forgotten value as `--directory=`, and it reached
+    // the profile hash as an empty directory while the engine used its
+    // default: two different engines, and a 30-second spawn timeout with a
+    // healthy engine running.
+    expect(usage(() => parseCliArgs(['-d', '']))).toContain('Missing value')
+    expect(usage(() => parseCliArgs(['--directory', '']))).toContain(
+      'Missing value'
+    )
+  })
+
+  it('refuses a bare --tcp and an empty one, and takes a port', () => {
+    // The docs document `--tcp=<port>`; a bare flag has no port, and
+    // `--tcp=` used to mean "no listener" on one side and bad argv on the
+    // other.
+    expect(usage(() => parseCliArgs(['--tcp']))).toContain('requires a port')
+    expect(usage(() => parseCliArgs(['--tcp=']))).toContain('Missing value')
+    expect(parseCliArgs(['--tcp=9008']).options.tcp).toBe('9008')
+    // 0 is documented as "pick an ephemeral port".
+    expect(parseCliArgs(['--tcp=0']).options.tcp).toBe('0')
+  })
+
+  it('stops parsing options at a bare --', () => {
+    // The only way to pass a command argument that looks like an option.
+    const { options, argv } = parseCliArgs([
+      '--fake',
+      'spend',
+      '--',
+      '--to=-weird'
+    ])
+    expect(options.fake).toBe(true)
+    expect(argv).toStrictEqual(['spend', '--', '--to=-weird'])
+  })
+
+  it('refuses a missing value rather than eating the next flag', () => {
+    expect(usage(() => parseCliArgs(['--directory']))).toContain(
+      'Missing value'
+    )
+    expect(usage(() => parseCliArgs(['--directory', '-t']))).toContain(
+      'Missing value'
+    )
+  })
+
+  it('refuses a command name where a value belongs', () => {
+    // `edge-cli --directory balance-map` is a forgotten value, not a
+    // directory called `balance-map`: taking it silently swallowed the
+    // command and dropped the caller into the prompt with exit 0.
+    const message = usage(() => parseCliArgs(['--directory', 'balance-map']))
+    expect(message).toContain('is a command')
+    expect(message).toContain('--directory=<value>')
+  })
+
+  it('reads the short forms', () => {
+    const { options } = parseCliArgs(['-t', '-a', 'edge.app', '-k', 'key123'])
+    expect(options.test).toBe(true)
+    expect(options['app-id']).toBe('edge.app')
+    expect(options['api-key']).toBe('key123')
+  })
+
+  it('reads the boolean switches', () => {
+    const { options } = parseCliArgs([
+      '--fake',
+      '--no-spawn',
+      '--solve-captcha',
+      '--help'
+    ])
+    expect(options.fake).toBe(true)
+    expect(options['no-spawn']).toBe(true)
+    expect(options['solve-captcha']).toBe(true)
+    expect(options.help).toBe(true)
+  })
+
+  it('refuses an unknown option', () => {
+    expect(usage(() => parseCliArgs(['--nope']))).toContain('--nope')
+  })
+
+  it('stops reading options at the command name', () => {
+    // Everything after the command belongs to the command, including flags
+    // whose names the front door also knows.
+    const { options, argv } = parseCliArgs([
+      'subscribe',
+      '--type=session.created'
+    ])
+    expect(options).toStrictEqual({})
+    expect(argv).toStrictEqual(['subscribe', '--type=session.created'])
+  })
+})
+
+describe('parseCommandArgs', () => {
+  const cmd = { name: 'demo', invoke: async () => {} }
+
+  it('reads a string flag in either spelling', () => {
+    const args = parseCommandArgs(cmd, ['--to=addr'], {
+      positional: 'none',
+      flags: { to: 'string' }
+    })
+    expect(args.string('to')).toBe('addr')
+  })
+
+  it('reads a bare boolean as true and an explicit value as given', () => {
+    const flags = { 'use-max': 'boolean' } as const
+    expect(
+      parseCommandArgs(cmd, ['--use-max'], {
+        positional: 'none',
+        flags
+      }).boolean('use-max')
+    ).toBe(true)
+    expect(
+      parseCommandArgs(cmd, ['--use-max=false'], {
+        positional: 'none',
+        flags
+      }).boolean('use-max')
+    ).toBe(false)
+  })
+
+  it('reports an absent boolean as false, and says it was not given', () => {
+    const args = parseCommandArgs(cmd, [], {
+      positional: 'none',
+      flags: { 'use-max': 'boolean' }
+    })
+    expect(args.boolean('use-max')).toBe(false)
+    expect(args.booleanGiven('use-max')).toBe(false)
+  })
+
+  it('collects a repeat flag in order', () => {
+    const args = parseCommandArgs(cmd, ['--type=a', '--type=b', '--type=a'], {
+      positional: 'none',
+      flags: { type: 'repeat' }
+    })
+    expect(args.strings('type')).toStrictEqual(['a', 'b', 'a'])
+  })
+
+  it('refuses an unknown flag, and a second positional', () => {
+    expect(
+      usage(() =>
+        parseCommandArgs(cmd, ['--nope=1'], {
+          positional: 'none',
+          flags: {}
+        })
+      )
+    ).toContain('--nope')
+    expect(
+      usage(() =>
+        parseCommandArgs(cmd, ['one', 'two'], {
+          positional: 'optional',
+          flags: {}
+        })
+      )
+    ).toBeTruthy()
+  })
+
+  it('refuses a positional where none is allowed', () => {
+    expect(
+      usage(() =>
+        parseCommandArgs(cmd, ['stray'], { positional: 'none', flags: {} })
+      )
+    ).toBeTruthy()
+  })
+
+  it('refuses a bad boolean value', () => {
+    expect(
+      usage(() =>
+        parseCommandArgs(cmd, ['--use-max=maybe'], {
+          positional: 'none',
+          flags: { 'use-max': 'boolean' }
+        })
+      )
+    ).toBeTruthy()
+  })
+})
diff --git a/src/__tests__/cli/persistedSchemas.test.ts b/src/__tests__/cli/persistedSchemas.test.ts
new file mode 100644
index 00000000000..8cf6f290276
--- /dev/null
+++ b/src/__tests__/cli/persistedSchemas.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it } from '@jest/globals'
+
+import {
+  asEdgeAssetAction,
+  asEdgeMetadata,
+  asEdgeMetadataChange,
+  asEdgeTxAction
+} from '../../cli/engine/schemas'
+
+/**
+ * These three shapes go into the wallet's synced transaction file, and core
+ * validates nothing between an HTTP body and the disklet — so the cleaner
+ * here is the only thing standing between a caller and that file.
+ */
+describe('asEdgeMetadataChange', () => {
+  it('accepts an empty change and a null deletion', () => {
+    // `toEqual` rather than `toStrictEqual`: `asObject` materialises every
+    // declared key, and core's `mergeMetadata` reads an explicit `undefined`
+    // as "leave this field unchanged", which is what an absent field means.
+    expect(asEdgeMetadataChange({})).toEqual({})
+    expect(asEdgeMetadataChange({ notes: 'hi', bizId: null })).toEqual({
+      notes: 'hi',
+      bizId: null
+    })
+    expect(
+      asEdgeMetadataChange({ exchangeAmount: { 'iso:USD': 1.5 } })
+    ).toEqual({ exchangeAmount: { 'iso:USD': 1.5 } })
+  })
+
+  it('refuses a non-object', () => {
+    expect(() => asEdgeMetadataChange('hello')).toThrow('Expected an object')
+    expect(() => asEdgeMetadataChange(123)).toThrow('Expected an object')
+  })
+
+  it('refuses an array', () => {
+    // `asObject` accepts one, and core's `mergeMetadata` then reads no
+    // properties off it, so the route answered 204 having written nothing.
+    expect(() => asEdgeMetadataChange([])).toThrow('got an array')
+  })
+
+  it('names the field that is the wrong type', () => {
+    expect(() => asEdgeMetadataChange({ notes: 123 })).toThrow('.notes')
+    expect(() => asEdgeMetadataChange({ bizId: 'one' })).toThrow('.bizId')
+  })
+})
+
+describe('asEdgeMetadata', () => {
+  it('reads a null as an absent field, having no deletion to express', () => {
+    expect(asEdgeMetadata({ notes: 'hi' })).toEqual({ notes: 'hi' })
+    // `EdgeMetadata` is a plain value rather than a change set, so there is
+    // nothing for `null` to delete and it means the same as omitting it.
+    expect(asEdgeMetadata({ notes: null })).toEqual({})
+    expect(() => asEdgeMetadata({ notes: 123 })).toThrow('.notes')
+  })
+})
+
+describe('asEdgeAssetAction', () => {
+  it('accepts a known assetActionType', () => {
+    expect(asEdgeAssetAction({ assetActionType: 'transfer' })).toStrictEqual({
+      assetActionType: 'transfer'
+    })
+  })
+
+  it('refuses an unknown one, and an array', () => {
+    expect(() => asEdgeAssetAction({ assetActionType: 'nope' })).toThrow()
+    expect(() => asEdgeAssetAction([])).toThrow('got an array')
+  })
+})
+
+describe('asEdgeTxAction', () => {
+  it('accepts each actionType in the union', () => {
+    const asset = { pluginId: 'bitcoin', tokenId: null }
+    expect(
+      asEdgeTxAction({ actionType: 'stake', pluginId: 'p', stakeAssets: [] })
+    ).toMatchObject({ actionType: 'stake' })
+    expect(
+      asEdgeTxAction({
+        actionType: 'swap',
+        swapInfo: {
+          pluginId: 'p',
+          displayName: 'P',
+          supportEmail: 'a@b.c'
+        },
+        fromAsset: asset,
+        toAsset: asset,
+        payoutAddress: 'addr',
+        payoutWalletId: 'w'
+      })
+    ).toMatchObject({ actionType: 'swap' })
+    expect(
+      asEdgeTxAction({
+        actionType: 'tokenApproval',
+        tokenApproved: asset,
+        tokenContractAddress: 'a',
+        contractAddress: 'b'
+      })
+    ).toMatchObject({ actionType: 'tokenApproval' })
+
+    // `fiat` and `giftCard` are the only two with nested objects, and
+    // therefore the only two where the hand transcription from core's own
+    // types could be wrong about a required field. These cleaners gate a
+    // write to the wallet's *synced* transaction file, so a wrong
+    // `asOptional` means either a legitimate `save-tx-action` 400s or a
+    // malformed one reaches disk.
+    expect(
+      asEdgeTxAction({
+        actionType: 'fiat',
+        orderId: 'order-1',
+        isEstimate: false,
+        fiatPlugin: { providerId: 'p', providerDisplayName: 'P' },
+        fiatAsset: { fiatCurrencyCode: 'iso:USD', fiatAmount: '10.00' },
+        cryptoAsset: { ...asset, nativeAmount: '1000' }
+      })
+    ).toMatchObject({ actionType: 'fiat' })
+    expect(
+      asEdgeTxAction({
+        actionType: 'giftCard',
+        orderId: 'order-2',
+        provider: { providerId: 'p', displayName: 'P' },
+        card: {
+          name: 'Example card',
+          fiatAmount: '25.00',
+          fiatCurrencyCode: 'iso:USD'
+        }
+      })
+    ).toMatchObject({ actionType: 'giftCard' })
+  })
+
+  it('names the nested required field a fiat action is missing', () => {
+    // `fiatPlugin.providerId` is required, and dropping it has to be
+    // reported as that field rather than as a failed union.
+    let message = ''
+    try {
+      asEdgeTxAction({
+        actionType: 'fiat',
+        orderId: 'order-1',
+        isEstimate: false,
+        fiatPlugin: { providerDisplayName: 'P' },
+        fiatAsset: { fiatCurrencyCode: 'iso:USD', fiatAmount: '10.00' },
+        cryptoAsset: { pluginId: 'bitcoin', tokenId: null }
+      })
+    } catch (error) {
+      message = String((error as Error).message)
+    }
+    expect(message).toContain('providerId')
+  })
+
+  it('refuses a non-integer nativeAmount, as core does', () => {
+    // Core declares `asIntegerString` here. Ours was `asString`, so "1.5"
+    // passed this route, core dispatched the change before awaiting the
+    // save, and the save then rejected — the engine served a `savedAction`
+    // the disk did not have, and the caller got a 500.
+    let message = ''
+    try {
+      asEdgeTxAction({
+        actionType: 'stake',
+        pluginId: 'p',
+        stakeAssets: [
+          { pluginId: 'bitcoin', tokenId: null, nativeAmount: '1.5' }
+        ]
+      })
+    } catch (error) {
+      message = String((error as Error).message)
+    }
+    expect(message).toContain('integer string')
+  })
+
+  it('names the missing field rather than the last alternative tried', () => {
+    // `asEither` reported `Expected "giftCard"` here, naming neither the
+    // field nor the shape the caller was actually aiming at.
+    expect(() => asEdgeTxAction({ actionType: 'stake' })).toThrow('.pluginId')
+  })
+
+  it('refuses an unknown actionType by name', () => {
+    expect(() => asEdgeTxAction({ actionType: 'nonsense' })).toThrow(
+      'Unknown actionType "nonsense"'
+    )
+  })
+
+  it('refuses an array', () => {
+    expect(() => asEdgeTxAction([])).toThrow('got an array')
+  })
+})
diff --git a/src/__tests__/cli/redaction.test.ts b/src/__tests__/cli/redaction.test.ts
new file mode 100644
index 00000000000..ee61e367fe1
--- /dev/null
+++ b/src/__tests__/cli/redaction.test.ts
@@ -0,0 +1,134 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest
+} from '@jest/globals'
+
+import { ApiClientError } from '../../cli/client/apiClient'
+import { EXIT } from '../../cli/client/exitCodes'
+import { printError } from '../../cli/client/output'
+
+let errors: string[]
+let spy: jest.SpiedFunction<typeof console.error>
+
+beforeEach(() => {
+  errors = []
+  spy = jest.spyOn(console, 'error').mockImplementation((...args: any[]) => {
+    errors.push(args.map(String).join(' '))
+  })
+})
+afterEach(() => {
+  spy.mockRestore()
+})
+
+/** The envelope `printError` wrote. */
+function written(): any {
+  expect(errors).toHaveLength(1)
+  return JSON.parse(errors[0])
+}
+
+describe('printError redaction', () => {
+  it('replaces the two secrets in OTP details and keeps the rest', () => {
+    // These are the only thing stopping a `resetToken` — which starts a 2FA
+    // reset on the account — and a `voucherAuth` — which authorises a
+    // pending voucher — from reaching a terminal, a shell history or a CI
+    // log. Both ride in the details `errors.ts` assembles for OTP_REQUIRED.
+    const code = printError(
+      new ApiClientError({
+        code: 'OTP_REQUIRED',
+        message: 'Invalid OTP token',
+        status: 401,
+        details: {
+          reason: 'otp',
+          loginId: 'login-id',
+          resetDate: '2026-01-01T00:00:00.000Z',
+          resetToken: 'SECRET-RESET-TOKEN',
+          voucherId: 'voucher-id',
+          voucherAuth: 'SECRET-VOUCHER-AUTH',
+          voucherActivates: '2026-01-02T00:00:00.000Z'
+        }
+      })
+    )
+    const body = written()
+    expect(body.error.details.resetToken).not.toBe('SECRET-RESET-TOKEN')
+    expect(body.error.details.voucherAuth).not.toBe('SECRET-VOUCHER-AUTH')
+    expect(errors[0]).not.toContain('SECRET-RESET-TOKEN')
+    expect(errors[0]).not.toContain('SECRET-VOUCHER-AUTH')
+    // Everything a caller needs to diagnose it survives.
+    expect(body.error.details.reason).toBe('otp')
+    expect(body.error.details.loginId).toBe('login-id')
+    expect(body.error.details.resetDate).toBe('2026-01-01T00:00:00.000Z')
+    expect(body.error.details.voucherId).toBe('voucher-id')
+    expect(body.error.details.voucherActivates).toBe('2026-01-02T00:00:00.000Z')
+    expect(code).toBe(EXIT.AUTH)
+  })
+
+  it('redacts every field OTP_REQUIRED carries that is a credential', () => {
+    // So the two sides cannot drift: each key the OTP arm emits is either
+    // redacted here or deliberately not. The list comes from
+    // `errors.ts`'s OTP_REQUIRED details projection.
+    const emitted = [
+      'reason',
+      'loginId',
+      'resetDate',
+      'resetToken',
+      'voucherId',
+      'voucherAuth',
+      'voucherActivates'
+    ]
+    const secrets = ['resetToken', 'voucherAuth']
+    const details: Record<string, unknown> = {}
+    for (const key of emitted) details[key] = `value-of-${key}`
+    printError(
+      new ApiClientError({
+        code: 'OTP_REQUIRED',
+        message: 'Invalid OTP token',
+        status: 401,
+        details
+      })
+    )
+    const body = written()
+    for (const key of emitted) {
+      const kept = body.error.details[key] === `value-of-${key}`
+      expect(kept).toBe(!secrets.includes(key))
+    }
+  })
+
+  it('leaves an error with no details alone', () => {
+    const code = printError(
+      new ApiClientError({
+        code: 'WALLET_NOT_FOUND',
+        message: 'No wallet matches that id',
+        status: 404
+      })
+    )
+    const body = written()
+    expect(body).toStrictEqual({
+      error: {
+        code: 'WALLET_NOT_FOUND',
+        message: 'No wallet matches that id',
+        status: 404
+      }
+    })
+    expect(code).toBe(EXIT.NOT_FOUND)
+  })
+
+  it('reports a plain Error as INTERNAL_ERROR without a stack', () => {
+    const code = printError(new Error('boom'))
+    const body = written()
+    expect(body.error).toStrictEqual({
+      code: 'INTERNAL_ERROR',
+      message: 'boom',
+      status: 500
+    })
+    expect(code).toBe(EXIT.GENERIC)
+  })
+
+  it('reports a thrown non-Error', () => {
+    printError('just a string')
+    expect(written().error.message).toBe('just a string')
+  })
+})
diff --git a/src/__tests__/cli/routeHelpers.test.ts b/src/__tests__/cli/routeHelpers.test.ts
new file mode 100644
index 00000000000..83711677454
--- /dev/null
+++ b/src/__tests__/cli/routeHelpers.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { ObjectHandleStore } from '../../cli/engine/objectHandles'
+import type { RouteContext } from '../../cli/engine/router'
+import { requireOwnedHandle } from '../../cli/engine/routes/helpers'
+
+/** The error shape `engineError` produces. */
+interface ThrownEngineError extends Error {
+  code: string
+  status: number
+}
+
+function thrown(fn: () => unknown): { code: string; status: number } {
+  try {
+    fn()
+  } catch (error) {
+    const engineError = error as ThrownEngineError
+    return { code: engineError.code, status: engineError.status }
+  }
+  throw new Error('expected a throw')
+}
+
+/**
+ * Just enough context for `requireOwnedHandle`: a handle store, and a session
+ * store that answers for exactly one session id the way `SessionStore` does.
+ */
+function makeCtx(opts: {
+  objects: ObjectHandleStore
+  sessionId: string
+  liveSessionId?: string
+}): RouteContext {
+  const { objects, sessionId, liveSessionId } = opts
+  const engineError = (
+    code: string,
+    message: string,
+    status: number
+  ): ThrownEngineError => {
+    const error = new Error(message) as ThrownEngineError
+    error.code = code
+    error.status = status
+    return error
+  }
+  return {
+    params: { sessionId, objectId: '' },
+    state: {
+      objects,
+      sessions: {
+        get(id: string) {
+          if (id !== liveSessionId) {
+            throw engineError('INVALID_SESSION', 'Unknown sessionId', 401)
+          }
+          return { account: {} }
+        },
+        touch() {}
+      }
+    }
+  } as unknown as RouteContext
+}
+
+describe('requireOwnedHandle', () => {
+  it('resolves the session before comparing the handle', () => {
+    const objects = new ObjectHandleStore()
+    const { objectId } = objects.create({
+      kind: 'transaction',
+      prefix: 'tx_',
+      value: { txid: 'a' },
+      sessionId: 'live'
+    })
+
+    const ctx = makeCtx({ objects, sessionId: 'live', liveSessionId: 'live' })
+    expect(
+      requireOwnedHandle(ctx, objectId, 'transaction').value
+    ).toStrictEqual({ txid: 'a' })
+  })
+
+  it('rejects a session id the session store no longer knows', () => {
+    const objects = new ObjectHandleStore()
+    const { objectId } = objects.create({
+      kind: 'transaction',
+      prefix: 'tx_',
+      value: { txid: 'a' },
+      sessionId: 'dead'
+    })
+
+    // A logged-out session still matches the handle's recorded id, so a
+    // string comparison alone would authorise this call for the rest of the
+    // handle's TTL.
+    const ctx = makeCtx({ objects, sessionId: 'dead', liveSessionId: 'live' })
+    expect(
+      thrown(() => requireOwnedHandle(ctx, objectId, 'transaction'))
+    ).toStrictEqual({
+      code: 'INVALID_SESSION',
+      status: 401
+    })
+  })
+
+  it('rejects a fabricated session id on a handle that has none', () => {
+    const objects = new ObjectHandleStore()
+    const { objectId } = objects.create({
+      kind: 'pendingLogin',
+      prefix: 'pending_',
+      value: { pendingId: '' }
+    })
+
+    // Every pending login is stored without a `sessionId`, so the ownership
+    // comparison is skipped and the session lookup is the only check left.
+    const ctx = makeCtx({
+      objects,
+      sessionId: 'made-up',
+      liveSessionId: 'live'
+    })
+    expect(thrown(() => requireOwnedHandle(ctx, objectId))).toStrictEqual({
+      code: 'INVALID_SESSION',
+      status: 401
+    })
+  })
+
+  it('still reports a handle owned by a different live session', () => {
+    const objects = new ObjectHandleStore()
+    const { objectId } = objects.create({
+      kind: 'transaction',
+      prefix: 'tx_',
+      value: { txid: 'a' },
+      sessionId: 'other'
+    })
+
+    const ctx = makeCtx({ objects, sessionId: 'live', liveSessionId: 'live' })
+    expect(
+      thrown(() => requireOwnedHandle(ctx, objectId, 'transaction'))
+    ).toStrictEqual({
+      code: 'OBJECT_SESSION_MISMATCH',
+      status: 400
+    })
+  })
+})
diff --git a/src/__tests__/cli/router.test.ts b/src/__tests__/cli/router.test.ts
new file mode 100644
index 00000000000..04776ca2ca8
--- /dev/null
+++ b/src/__tests__/cli/router.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { Router } from '../../cli/engine/router'
+
+/** The `code` an engineError carries, which is the contract callers read. */
+function codeOf(fn: () => unknown): string {
+  try {
+    fn()
+  } catch (error) {
+    return (error as { code: string }).code
+  }
+  throw new Error('expected a throw')
+}
+
+const noop = (): undefined => undefined
+
+describe('Router.match', () => {
+  it('extracts named parameters', () => {
+    const router = new Router()
+    router.add('GET', '/account/{sessionId}/wallet/balance-map', noop)
+    const hit = router.match('GET', '/account/sess_abc/wallet/balance-map')
+    expect(hit?.params).toStrictEqual({ sessionId: 'sess_abc' })
+  })
+
+  it('does not let a parameter swallow a path separator', () => {
+    const router = new Router()
+    router.add('GET', '/object/{objectId}', noop)
+    // `([^/]+)`, not `(.+)`: a greedy pattern would match this and hand the
+    // handler an objectId containing a path.
+    expect(router.match('GET', '/object/tx_1/extra')).toBeNull()
+  })
+
+  it('is case-insensitive about the method and nothing else', () => {
+    const router = new Router()
+    router.add('post', '/engine/stop', noop)
+    expect(router.match('POST', '/engine/stop')).not.toBeNull()
+    expect(router.match('GET', '/engine/stop')).toBeNull()
+    expect(router.match('POST', '/Engine/Stop')).toBeNull()
+  })
+
+  it('escapes regex metacharacters in literal segments', () => {
+    const router = new Router()
+    router.add('GET', '/rates/usd-to-native', noop)
+    // Unescaped, the `-` is harmless but a `.` is not: `/rates/usd.to.native`
+    // would match a pattern written with dots.
+    expect(router.match('GET', '/rates/usd-to-native')).not.toBeNull()
+    expect(router.match('GET', '/ratesXusd-to-native')).toBeNull()
+  })
+
+  it('answers a malformed percent-escape with BAD_REQUEST', () => {
+    const router = new Router()
+    router.add('GET', '/object/{objectId}', noop)
+    // `new URL()` accepts this and `decodeURIComponent` then throws
+    // `URIError`, which reached the catch-all as a 500 — a caller's bad URL
+    // reported as an engine fault on a route declaring 400 and 404.
+    expect(codeOf(() => router.match('GET', '/object/%ZZ'))).toBe('BAD_REQUEST')
+  })
+
+  it('decodes a legitimately encoded parameter', () => {
+    const router = new Router()
+    router.add('GET', '/local-user/{username}', noop)
+    const hit = router.match('GET', '/local-user/a%20b')
+    expect(hit?.params).toStrictEqual({ username: 'a b' })
+  })
+
+  it('returns null for a path no route covers', () => {
+    const router = new Router()
+    router.add('GET', '/engine/status', noop)
+    expect(router.match('GET', '/engine/nope')).toBeNull()
+  })
+})
diff --git a/src/__tests__/cli/sessions.test.ts b/src/__tests__/cli/sessions.test.ts
new file mode 100644
index 00000000000..87499e8df90
--- /dev/null
+++ b/src/__tests__/cli/sessions.test.ts
@@ -0,0 +1,354 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+import type { EdgeAccount } from 'edge-core-js'
+
+import type { EventHub } from '../../cli/engine/events'
+import { ObjectHandleStore } from '../../cli/engine/objectHandles'
+import { SessionStore } from '../../cli/engine/sessions'
+import { makeFakeDiskletAccount } from '../../util/fake/fakeDisklet'
+
+/**
+ * An account whose synced Settings.json is whatever the test supplies.
+ *
+ * Through the shared fake, with a `logout` spy layered on: this store's
+ * whole job is to call it at the right moment.
+ */
+function makeAccount(settings?: string): {
+  account: EdgeAccount
+  logout: jest.Mock<() => Promise<void>>
+} {
+  const logout = jest.fn<() => Promise<void>>(async () => {})
+  const account = {
+    ...makeFakeDiskletAccount({ synced: settings }),
+    logout
+  } as unknown as EdgeAccount
+  return { account, logout }
+}
+
+/** The `code` an engineError carries, which is the contract callers read. */
+function codeOf(fn: () => unknown): string {
+  try {
+    fn()
+  } catch (error) {
+    return (error as { code: string }).code
+  }
+  throw new Error('expected a throw')
+}
+
+const events = {
+  emit: () => {},
+  closeScope: () => {}
+} as unknown as EventHub
+
+describe('SessionStore auto-logout', () => {
+  let store: SessionStore
+
+  beforeEach(() => {
+    // `create` drains the core pixie stack with `setImmediate`, so that one
+    // stays real; everything else is faked so the idle window can be advanced.
+    jest.useFakeTimers({ doNotFake: ['setImmediate', 'nextTick'] })
+    store = new SessionStore(events)
+  })
+
+  it('defaults to an hour when Settings.json is absent', async () => {
+    const { account } = makeAccount()
+    const info = await store.create(account, 'password')
+    expect(info.autoLogoutSeconds).toBe(3600)
+    expect(info.expiresAt).not.toBeNull()
+  })
+
+  it('reads the account setting', async () => {
+    const { account } = makeAccount('{"autoLogoutTimeInSeconds":60}')
+    const info = await store.create(account, 'password')
+    expect(info.autoLogoutSeconds).toBe(60)
+  })
+
+  it('logs the account out once it has been idle for that long', async () => {
+    const { account, logout } = makeAccount('{"autoLogoutTimeInSeconds":60}')
+    const { sessionId } = await store.create(account, 'password')
+    store.startAutoLogoutTicker()
+
+    await jest.advanceTimersByTimeAsync(50_000)
+    expect(store.get(sessionId).sessionId).toBe(sessionId)
+    expect(logout).not.toHaveBeenCalled()
+
+    await jest.advanceTimersByTimeAsync(30_000)
+    expect(logout).toHaveBeenCalledTimes(1)
+    expect(store.size).toBe(0)
+    store.stopAutoLogoutTicker()
+  })
+
+  it('a touched session keeps its window', async () => {
+    const { account, logout } = makeAccount('{"autoLogoutTimeInSeconds":60}')
+    const { sessionId } = await store.create(account, 'password')
+    store.startAutoLogoutTicker()
+
+    await jest.advanceTimersByTimeAsync(50_000)
+    store.touch(sessionId)
+    await jest.advanceTimersByTimeAsync(50_000)
+
+    expect(logout).not.toHaveBeenCalled()
+    expect(store.size).toBe(1)
+    store.stopAutoLogoutTicker()
+  })
+
+  it('0 disables the timeout entirely', async () => {
+    const { account, logout } = makeAccount('{"autoLogoutTimeInSeconds":0}')
+    const info = await store.create(account, 'password')
+    store.startAutoLogoutTicker()
+
+    // `expiresAt` is null exactly when the timeout is disabled.
+    expect(info.expiresAt).toBeNull()
+    await jest.advanceTimersByTimeAsync(4 * 60 * 60 * 1000)
+    expect(logout).not.toHaveBeenCalled()
+    expect(store.size).toBe(1)
+    store.stopAutoLogoutTicker()
+  })
+
+  it('an expired session answers SESSION_EXPIRED, a logged-out one INVALID_SESSION', async () => {
+    const { account } = makeAccount('{"autoLogoutTimeInSeconds":60}')
+    const { sessionId } = await store.create(account, 'password')
+
+    // Past its window but not yet swept: the only path that reports 401
+    // SESSION_EXPIRED rather than a missing session.
+    jest.advanceTimersByTime(61_000)
+    expect(codeOf(() => store.get(sessionId))).toBe('SESSION_EXPIRED')
+
+    const second = await store.create(makeAccount().account, 'password')
+    await store.logout(second.sessionId)
+    expect(codeOf(() => store.get(second.sessionId))).toBe('INVALID_SESSION')
+  })
+
+  it('does not log out a session with a request in flight', async () => {
+    const { account, logout } = makeAccount('{"autoLogoutTimeInSeconds":60}')
+    const { sessionId } = await store.create(account, 'password')
+    store.startAutoLogoutTicker()
+
+    // A call that outlives the window — a cold `wait-for-all-wallets`, a
+    // `spend` on a congested chain — used to be logged out from underneath
+    // itself, because `lastActivityAt` records only when a request started.
+    const release = store.beginRequest(sessionId)
+    await jest.advanceTimersByTimeAsync(5 * 60 * 1000)
+    expect(logout).not.toHaveBeenCalled()
+    expect(store.get(sessionId).sessionId).toBe(sessionId)
+
+    // Releasing refreshes the activity clock, so the window starts again
+    // rather than expiring the moment the request returns.
+    release()
+    await jest.advanceTimersByTimeAsync(30_000)
+    expect(logout).not.toHaveBeenCalled()
+
+    await jest.advanceTimersByTimeAsync(60_000)
+    expect(logout).toHaveBeenCalledTimes(1)
+    store.stopAutoLogoutTicker()
+  })
+
+  it('releases the object handles the session owned', async () => {
+    const onExpire = jest.fn<() => void>()
+    const objects = new ObjectHandleStore()
+    store.objects = objects
+    const { account } = makeAccount()
+    const { sessionId } = await store.create(account, 'password')
+    objects.create({
+      kind: 'swap',
+      prefix: 'swap_',
+      value: { quote: true },
+      sessionId,
+      onExpire
+    })
+    // Another session's handle must survive.
+    objects.create({
+      kind: 'swap',
+      prefix: 'swap_',
+      value: { quote: true },
+      sessionId: 'sess_other'
+    })
+    expect(objects.size).toBe(2)
+
+    await store.logout(sessionId)
+
+    // A `swap_` handle holds a live quote whose `onExpire` closes the order,
+    // so leaving it behind held the exchange's order for the rest of the TTL.
+    expect(onExpire).toHaveBeenCalledTimes(1)
+    expect(objects.size).toBe(1)
+  })
+
+  it('picks up a changed auto-logout setting on the next tick', async () => {
+    const logout = jest.fn<() => Promise<void>>(async () => {})
+    let settings = '{"autoLogoutTimeInSeconds":3600}'
+    const account = {
+      username: 'clitester',
+      rootLoginId: 'root123',
+      logout,
+      waitForAllWallets: async () => {},
+      disklet: { getText: async () => settings }
+    } as unknown as EdgeAccount
+
+    const { sessionId } = await store.create(account, 'password')
+    expect(store.get(sessionId).autoLogoutSeconds).toBe(3600)
+    store.startAutoLogoutTicker()
+
+    // The documentation says the engine mirrors the GUI, where
+    // `AutoLogoutModal` takes effect immediately. Freezing the value at login
+    // meant a user who shortened it on their phone saw no change at all.
+    settings = '{"autoLogoutTimeInSeconds":60}'
+    await jest.advanceTimersByTimeAsync(16_000)
+    expect(logout).not.toHaveBeenCalled()
+
+    await jest.advanceTimersByTimeAsync(61_000)
+    expect(logout).toHaveBeenCalledTimes(1)
+    store.stopAutoLogoutTicker()
+  })
+
+  it('keeps the last known window when the re-read fails', async () => {
+    const logout = jest.fn<() => Promise<void>>(async () => {})
+    let readable = true
+    const account = {
+      username: 'clitester',
+      rootLoginId: 'root123',
+      logout,
+      waitForAllWallets: async () => {},
+      disklet: {
+        getText: async () => {
+          // Not an absent file: a failure to read one that is there.
+          if (!readable) throw new Error('could not decrypt')
+          return '{"autoLogoutTimeInSeconds":0}'
+        }
+      }
+    } as unknown as EdgeAccount
+
+    const { sessionId } = await store.create(account, 'password')
+    // 0 is documented as "auto-logout disabled".
+    expect(store.get(sessionId).autoLogoutSeconds).toBe(0)
+    store.startAutoLogoutTicker()
+
+    readable = false
+    // The ticker's `catch` used to be dead code, because the reader swallowed
+    // the failure and answered with the cleaner's 3600 — so a transient read
+    // error silently re-enabled auto-logout and logged this session out an
+    // hour later.
+    await jest.advanceTimersByTimeAsync(3_600_000 + 60_000)
+    expect(store.peek(sessionId)?.autoLogoutSeconds).toBe(0)
+    expect(logout).not.toHaveBeenCalled()
+    store.stopAutoLogoutTicker()
+  })
+
+  it('refuses a request that arrives after the window closed', async () => {
+    const { account } = makeAccount('{"autoLogoutTimeInSeconds":60}')
+    const { sessionId } = await store.create(account, 'password')
+
+    // The sweeper runs every 15 seconds, so a request can arrive up to that
+    // long after the window closes. `inFlight` makes `isExpired` false, so
+    // taking the hold before testing expiry served that request on a dead
+    // session *and* re-armed the window for another full minute.
+    await jest.advanceTimersByTimeAsync(61_000)
+    expect(codeOf(() => store.beginRequest(sessionId))).toBe('SESSION_EXPIRED')
+  })
+
+  it('does not re-read the synced file when auto-logout is off', async () => {
+    const logout = jest.fn<() => Promise<void>>(async () => {})
+    let reads = 0
+    const account = {
+      username: 'clitester',
+      rootLoginId: 'root123',
+      logout,
+      waitForAllWallets: async () => {},
+      disklet: {
+        getText: async () => {
+          reads++
+          return '{"autoLogoutTimeInSeconds":0}'
+        }
+      }
+    } as unknown as EdgeAccount
+
+    await store.create(account, 'password')
+    const afterLogin = reads
+    store.startAutoLogoutTicker()
+    // `isExpired` returns false before it looks at the window, so re-reading
+    // a decrypt-and-parse 240 times an hour per session buys nothing.
+    await jest.advanceTimersByTimeAsync(120_000)
+    expect(reads).toBe(afterLogin)
+    store.stopAutoLogoutTicker()
+  })
+})
+
+describe('SessionStore teardown order', () => {
+  beforeEach(() => {
+    jest.useFakeTimers({ doNotFake: ['setImmediate', 'nextTick'] })
+  })
+
+  it('releases what the account owns before logging it out', async () => {
+    // The order this class documents, and the one it did not follow:
+    // `account.logout()` invalidates every wallet the handlers hold, so
+    // running it first left a live swap quote or a signed transaction with
+    // nothing able to release it — exactly what the class comment warns
+    // about — and made the bounded wait in `deleteMany` protect nothing.
+    const order: string[] = []
+    const { account, logout } = makeAccount()
+    logout.mockImplementation(async () => {
+      order.push('logout')
+    })
+    const store = new SessionStore({
+      emit: () => {},
+      closeScope: () => order.push('closeScope')
+    } as unknown as EventHub)
+    store.objects = {
+      deleteBySession: async () => {
+        order.push('releaseHandles')
+      }
+    } as unknown as ObjectHandleStore
+
+    const { sessionId } = await store.create(account, 'password')
+    await store.logout(sessionId)
+
+    expect(order).toStrictEqual(['closeScope', 'releaseHandles', 'logout'])
+  })
+
+  it('waits for the session own requests before logging out', async () => {
+    const { account, logout } = makeAccount()
+    const store = new SessionStore(events)
+    const { sessionId } = await store.create(account, 'password')
+
+    // Two holds, as the real arrangement has: the request serving the logout
+    // itself, and a second shell's `spend` that is still running. `inFlight`
+    // exists for this — its comment names a `spend` on a congested chain —
+    // and only `isExpired` read it, so a `POST /logout` could land between
+    // `broadcastTx` and `saveTx`. The logout's own hold is discounted or the
+    // wait would deadlock on itself.
+    const ownHold = store.beginRequest(sessionId)
+    const release = store.beginRequest(sessionId)
+    const pending = store.logout(sessionId)
+    await jest.advanceTimersByTimeAsync(5_000)
+    expect(logout).not.toHaveBeenCalled()
+
+    release()
+    await jest.advanceTimersByTimeAsync(100)
+    await pending
+    expect(logout).toHaveBeenCalledTimes(1)
+    ownHold()
+  })
+
+  it('logs out anyway once the wait is exhausted', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { account, logout } = makeAccount()
+      const store = new SessionStore(events)
+      const { sessionId } = await store.create(account, 'password')
+      // The logout's own hold, plus one that is never released: a wedged
+      // request must not make logout impossible, because logout is a
+      // security control.
+      store.beginRequest(sessionId)
+      store.beginRequest(sessionId)
+
+      const pending = store.logout(sessionId)
+      await jest.advanceTimersByTimeAsync(31_000)
+      await pending
+
+      expect(logout).toHaveBeenCalledTimes(1)
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('still in flight')
+      )
+    } finally {
+      warn.mockRestore()
+    }
+  })
+})
diff --git a/src/__tests__/cli/solveCaptcha.test.ts b/src/__tests__/cli/solveCaptcha.test.ts
new file mode 100644
index 00000000000..29d6e3a0eef
--- /dev/null
+++ b/src/__tests__/cli/solveCaptcha.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it } from '@jest/globals'
+import fs from 'fs'
+import path from 'path'
+
+import {
+  parseAltchaChallenge,
+  solveAltcha
+} from '../../cli/client/solveCaptcha'
+
+/** A page shaped like login-tester's, carrying `challenge`. */
+function page(challenge: string): string {
+  return `<html><script>var opts = { challenge: ${challenge}, other: 1 }</script></html>`
+}
+
+describe('parseAltchaChallenge', () => {
+  it('reads the challenge out of the page', () => {
+    const ch = parseAltchaChallenge(
+      page('{"challenge":"deadbeef","maxnumber":100,"salt":"abc"}')
+    )
+    expect(ch).toStrictEqual({
+      challenge: 'deadbeef',
+      maxnumber: 100,
+      salt: 'abc'
+    })
+  })
+
+  it('says so when the markup has moved', () => {
+    expect(() =>
+      parseAltchaChallenge('<html>no challenge here</html>')
+    ).toThrow(/Could not find challenge/)
+  })
+
+  it('names the shape rather than throwing a SyntaxError', () => {
+    // With `JSON.parse` outside the cleaner this threw a bare SyntaxError,
+    // past the guard and the message written for exactly this case.
+    expect(() => parseAltchaChallenge(page('{challenge: deadbeef}'))).toThrow(
+      /not in the expected shape/
+    )
+  })
+
+  it('refuses a challenge missing a field', () => {
+    expect(() =>
+      parseAltchaChallenge(page('{"challenge":"deadbeef","salt":"abc"}'))
+    ).toThrow(/not in the expected shape/)
+  })
+
+  it('refuses a maxnumber above the cap', () => {
+    // `maxnumber` bounds a synchronous hash loop, so an unbounded value
+    // blocks the process with no timeout — the two HTTPS calls are the only
+    // thing `REQUEST_TIMEOUT_MS` covers.
+    expect(() =>
+      parseAltchaChallenge(
+        page('{"challenge":"x","maxnumber":999999999,"salt":"abc"}')
+      )
+    ).toThrow(/above the 10000000 limit/)
+  })
+})
+
+describe('solveAltcha', () => {
+  it('finds the number whose hash matches', async () => {
+    // sha256('abc7'), computed in advance.
+    const challenge =
+      '53dd02b72c4e7463b448e5374abedc168dcd200ad7e1221fe92d440c545859c6'
+    expect(await solveAltcha({ challenge, maxnumber: 100, salt: 'abc' })).toBe(
+      7
+    )
+  })
+
+  it('returns null when no number in range matches', async () => {
+    expect(
+      await solveAltcha({ challenge: 'nope', maxnumber: 50, salt: 'abc' })
+    ).toBeNull()
+  })
+
+  it('stops at maxnumber rather than searching past it', async () => {
+    // The answer is 7, which is outside this range.
+    const challenge =
+      '53dd02b72c4e7463b448e5374abedc168dcd200ad7e1221fe92d440c545859c6'
+    expect(
+      await solveAltcha({ challenge, maxnumber: 5, salt: 'abc' })
+    ).toBeNull()
+  })
+})
+
+/**
+ * A structural guard, because this bug arrived twice.
+ *
+ * `apiClient.request` was fixed in iteration 2 and the same gap was left in
+ * `solveCaptcha`'s two helpers and in `openStream`'s 4xx branch: once headers
+ * have arrived Node routes a socket close to the *response* and clears the
+ * request timer, so a request/response pair with no `error` and `aborted`
+ * handler never settles and the command hangs for ever. These are not
+ * exported, and testing them for real would need a TLS server, so the
+ * invariant is checked at the source: every response consumer handles
+ * `error`, and every one that resolves with a value also handles `aborted`.
+ */
+describe('https response handlers', () => {
+  const read = (name: string): string =>
+    fs.readFileSync(
+      path.join(__dirname, '..', '..', 'cli', 'client', name),
+      'utf8'
+    )
+  const count = (text: string, needle: string): number =>
+    text.split(needle).length - 1
+
+  it('handles error on every response it consumes', () => {
+    for (const name of ['solveCaptcha.ts', 'apiClient.ts']) {
+      const text = read(name)
+      expect(count(text, "res.on('error'")).toBe(count(text, "res.on('end'"))
+    }
+  })
+
+  it('handles aborted on every request/response pair', () => {
+    // Both of `solveCaptcha`'s helpers resolve with a value, so each needs
+    // the pair.
+    const captcha = read('solveCaptcha.ts')
+    expect(count(captcha, "res.on('aborted'")).toBe(
+      count(captcha, "res.on('end'")
+    )
+
+    // `apiClient` has three consumers and two need it: `request` and
+    // `openStream`'s 4xx branch. `openStream`'s success branch resolves on
+    // `end`, which a dropped stream also reaches, so it settles either way —
+    // a stream ending is the documented termination, reported as
+    // `subscription.ended` with exit 7.
+    const client = read('apiClient.ts')
+    expect(count(client, "res.on('aborted'")).toBe(2)
+  })
+})
diff --git a/src/__tests__/util/exchangeDenom.test.ts b/src/__tests__/util/exchangeDenom.test.ts
new file mode 100644
index 00000000000..11e75945d1a
--- /dev/null
+++ b/src/__tests__/util/exchangeDenom.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from '@jest/globals'
+import type { EdgeCurrencyConfig } from 'edge-core-js'
+
+import {
+  emptyEdgeDenomination,
+  getExchangeDenom
+} from '../../util/exchangeDenom'
+
+const btc = { name: 'BTC', multiplier: '100000000', symbol: '₿' }
+const usdc = { name: 'USDC', multiplier: '1000000', symbol: '' }
+
+const currencyConfig = {
+  currencyInfo: { pluginId: 'bitcoin', denominations: [btc] },
+  allTokens: {
+    deadbeef: { currencyCode: 'USDC', denominations: [usdc] }
+  }
+} as unknown as EdgeCurrencyConfig
+
+describe('getExchangeDenom', () => {
+  it('returns the native denomination for a null tokenId', () => {
+    expect(getExchangeDenom(currencyConfig, null)).toStrictEqual(btc)
+  })
+
+  it('returns the token denomination for a known tokenId', () => {
+    expect(getExchangeDenom(currencyConfig, 'deadbeef')).toStrictEqual(usdc)
+  })
+
+  it('returns the empty denomination for an unknown tokenId', () => {
+    // This is the silent-wrong-number path: `multiplier: '1'` is used as the
+    // divisor by the CSV, QBO and Bitwave exporters, so an export of an
+    // unknown token would carry amounts scaled 1:1 into an accounting file
+    // rather than failing. The route refuses an unknown tokenId before
+    // reaching here (`assertTokenId`), and this pins what the fallback is.
+    expect(getExchangeDenom(currencyConfig, 'notatoken')).toStrictEqual(
+      emptyEdgeDenomination
+    )
+    expect(getExchangeDenom(currencyConfig, 'notatoken').multiplier).toBe('1')
+  })
+
+  it('returns a frozen empty denomination, so a caller cannot mutate it', () => {
+    const denom = getExchangeDenom(currencyConfig, 'notatoken')
+    expect(Object.isFrozen(denom)).toBe(true)
+  })
+})
diff --git a/src/cli/bootEngineLocale.ts b/src/cli/bootEngineLocale.ts
new file mode 100644
index 00000000000..19d94b7a263
--- /dev/null
+++ b/src/cli/bootEngineLocale.ts
@@ -0,0 +1,22 @@
+/**
+ * Side-effect locale boot for the engine.
+ *
+ * Detection happens in `bootNodeLocale`, which both entries import; applying
+ * it — which pulls in `locales/strings` and every translation table — happens
+ * only here, because only the engine builds localized prose.
+ *
+ * Must be the first import in `src/cli/engine/index.ts`.
+ */
+import { applyLocale } from '../locales/bootLocale'
+import { getDetectedLocale } from './bootNodeLocale'
+
+const applied = applyLocale(getDetectedLocale())
+
+// Say so when the tag was accepted but no table exists for it. Discarding
+// this made "the engine has your language" and "the engine is answering in
+// English" indistinguishable, including from `engine-status`.
+if (!applied.matched) {
+  console.error(
+    `[edge-engine] No translation table for locale ${applied.languageTag}; answering in English.`
+  )
+}
diff --git a/src/cli/bootNodeLocale.ts b/src/cli/bootNodeLocale.ts
new file mode 100644
index 00000000000..929642a44f9
--- /dev/null
+++ b/src/cli/bootNodeLocale.ts
@@ -0,0 +1,50 @@
+/**
+ * Side-effect locale *detection* for both CLI entries.
+ *
+ * Detection only. The client renders no localized string — `git grep lstrings
+ * src/cli` outside `engine/` is empty — so applying the language here dragged
+ * `locales/strings` and all eleven translation tables into `lib/edgeCli.js`
+ * for a value it never reads. It needs the *tag*, to pass `--locale` to the
+ * engine and to warn on a mismatch; `bootEngineLocale` is what applies it.
+ *
+ * Must be the first import in `src/cli/index.ts`.
+ */
+import type { LocaleSource } from '../locales/bootLocale'
+import { detectNodeLocale, parseConfigPathFlag } from '../locales/nodeLocale'
+import { loadConfig } from './engine/cliConfig'
+
+const argv = process.argv.slice(2)
+
+// This runs at import, before `main()` has a handler, so a bad `-c/--config`
+// would otherwise print Node's uncaught-exception format — source line, caret,
+// stack — and exit 1. The documented failure model is the JSON envelope with
+// exit 2 for bad argv, so report it that way and stop here.
+let fileConfig
+try {
+  fileConfig = loadConfig(parseConfigPathFlag(argv))
+} catch (error: unknown) {
+  console.error(
+    JSON.stringify(
+      {
+        error: {
+          code: 'USAGE',
+          message: error instanceof Error ? error.message : String(error),
+          status: 400
+        }
+      },
+      null,
+      2
+    )
+  )
+  process.exit(2)
+}
+const detected: LocaleSource = detectNodeLocale({
+  argv,
+  env: process.env,
+  configLocale: fileConfig.locale
+})
+
+/** What this process resolved from argv, config and the environment. */
+export function getDetectedLocale(): LocaleSource {
+  return detected
+}
diff --git a/src/cli/client/apiClient.ts b/src/cli/client/apiClient.ts
new file mode 100644
index 00000000000..66b63d7adef
--- /dev/null
+++ b/src/cli/client/apiClient.ts
@@ -0,0 +1,493 @@
+import {
+  asMaybe,
+  asNumber,
+  asObject,
+  asOptional,
+  asString,
+  asUnknown
+} from 'cleaners'
+import http from 'http'
+
+import { stringifyJson } from '../engine/json'
+import { EXAMPLE_TCP_PORT } from '../engine/tcpPort'
+
+/**
+ * The error envelope every failure arrives in, on both transports.
+ *
+ * Cleaned, not cast. `'error' in parsed` was the only guard, so
+ * `{"error":"boom"}` built an `ApiClientError` from the string: `code` and
+ * `status` were `undefined`, `super(body.message)` was `super(undefined)`,
+ * and the CLI printed `{"error":{"code":undefined,…}}` and exited 1. The
+ * same reasoning is written out on `sessionFile.ts`'s own cleaner.
+ */
+export const asApiErrorBody = asObject({
+  error: asObject({
+    code: asString,
+    message: asString,
+    status: asNumber,
+    details: asOptional(asObject(asUnknown))
+  })
+})
+
+export type ApiErrorBody = ReturnType<typeof asApiErrorBody>
+
+export class ApiClientError extends Error {
+  status: number
+  code: string
+  details?: Record<string, unknown>
+
+  /**
+   * `details` is optional here where the cleaner materialises it, so a
+   * hand-built failure does not have to spell `details: undefined`.
+   */
+  constructor(body: {
+    code: string
+    message: string
+    status: number
+    details?: Record<string, unknown>
+  }) {
+    super(body.message)
+    this.name = 'ApiClientError'
+    this.status = body.status
+    this.code = body.code
+    this.details = body.details
+  }
+}
+
+export interface ApiClientOptions {
+  socketPath?: string
+  host?: string
+  port?: number
+  /**
+   * How long one request may take, in milliseconds.
+   *
+   * `--timeout=<seconds>` sets it. There has to be a way: on expiry the
+   * client destroys the socket and reports a failure while the engine runs
+   * the request to completion, so for `broadcast-tx` the caller is told the
+   * call failed after the funds have left, and a long `get-transactions`,
+   * `wait-for-all-wallets` or `resync-blockchain` had no way to ask for more
+   * time.
+   */
+  timeoutMs?: number
+  /**
+   * Start the engine, called once when a request finds nothing listening.
+   *
+   * Spawning on demand rather than up front means a command that fails before
+   * it ever sends a request — an unknown flag, a missing value, no session —
+   * leaves no daemon behind.
+   */
+  onConnectFail?: () => Promise<void>
+
+  /**
+   * Called once, after the first request that reaches an engine.
+   *
+   * For checks that need a live engine but must not cause one to start: doing
+   * them up front would spawn a daemon for a command that never runs.
+   */
+  onFirstResponse?: (client: ApiClient) => Promise<void>
+}
+
+/** The per-request deadline when no `--timeout` is given. */
+export const DEFAULT_TIMEOUT_MS = 120_000
+
+/** How long to wait for a shutting-down engine to let go of its socket. */
+const SHUTDOWN_WAIT_MS = 15_000
+
+/** Nothing is listening on the socket or port yet. */
+function isNotListening(error: unknown): boolean {
+  const code = (error as { code?: string } | null)?.code
+  return code === 'ENOENT' || code === 'ECONNREFUSED'
+}
+
+/**
+ * The engine is going away, so a fresh one will answer this.
+ *
+ * `shutdown()` sets `shuttingDown` as its second statement and does not close
+ * the listeners until the drain, the logouts and `context.close()` are done,
+ * so for that whole window a bound socket answers `503
+ * ENGINE_SHUTTING_DOWN`. Treating it as terminal made `engine-stop` followed
+ * by any command in the same script a guaranteed failure, and every command
+ * a race once the idle timer starts firing — which the guide presents as
+ * invisible housekeeping.
+ */
+function isShuttingDown(error: unknown): boolean {
+  return (
+    error instanceof ApiClientError && error.code === 'ENGINE_SHUTTING_DOWN'
+  )
+}
+
+export class ApiClient {
+  private readonly opts: ApiClientOptions
+
+  constructor(opts: ApiClientOptions) {
+    this.opts = opts
+  }
+
+  /** A spawn in flight, so concurrent calls wait on one rather than racing. */
+  private spawning: Promise<void> | null = null
+  private firstResponseDone = false
+
+  /**
+   * Run something against the engine, starting it if nothing is listening.
+   *
+   * Only an in-flight spawn is shared. A *completed* one is forgotten, because
+   * the engine it started can go away again — `engine-stop`, or the documented
+   * idle shutdown — and a long-lived client like the interactive prompt has to
+   * be able to start another.
+   */
+  private async withEngine<T>(attempt: () => Promise<T>): Promise<T> {
+    let result: T
+    try {
+      result = await attempt()
+    } catch (error: unknown) {
+      const spawn = this.opts.onConnectFail
+      if (spawn == null) throw error
+      if (isShuttingDown(error)) {
+        // Wait for the socket to go, bounded, then start a fresh engine. The
+        // old one is still bound and still answering 503, so retrying
+        // immediately would just collect another one.
+        await this.waitForSocketToClose()
+      } else if (!isNotListening(error)) {
+        throw error
+      }
+      this.spawning ??= spawn().finally(() => {
+        this.spawning = null
+      })
+      await this.spawning
+      result = await attempt()
+    }
+    await this.runFirstResponseHook()
+    return result
+  }
+
+  /**
+   * Poll until the engine stops answering, or give up.
+   *
+   * Bounded by the drain the engine itself allows, plus a margin: past that
+   * the engine is wedged rather than shutting down, and `onConnectFail` will
+   * report whatever it finds.
+   */
+  private async waitForSocketToClose(): Promise<void> {
+    const deadline = Date.now() + SHUTDOWN_WAIT_MS
+    while (Date.now() < deadline) {
+      await new Promise(resolve => setTimeout(resolve, 100))
+      try {
+        await this.sendRequest('GET', '/engine/status')
+      } catch (error: unknown) {
+        if (isNotListening(error)) return
+      }
+    }
+  }
+
+  private async runFirstResponseHook(): Promise<void> {
+    const hook = this.opts.onFirstResponse
+    if (hook == null || this.firstResponseDone) return
+    // Set before calling: the hook talks to the engine itself.
+    this.firstResponseDone = true
+    await hook(this)
+  }
+
+  async request<T = unknown>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    // Asking an engine to stop must never *start* one. Without this, a stop
+    // sent after the daemon has already gone found nothing listening, took
+    // the auto-spawn path, and brought up a replacement engine purely to
+    // tell it to shut down — which then sat idle under a fresh profile
+    // directory. The offline suite's own leak check caught it.
+    const isStop = method === 'POST' && path === '/engine/stop'
+    if (isStop) {
+      try {
+        return await this.sendRequest<T>(method, path, body)
+      } catch (error: unknown) {
+        // Nothing listening means there is nothing to stop, which is what
+        // the caller wanted. Reporting the raw `connect ENOENT` as a 500
+        // made a no-op fail, and spawning an engine to receive the stop was
+        // worse.
+        if (isNotListening(error)) {
+          const noop: unknown = { ok: true }
+          return noop as T
+        }
+        throw error
+      }
+    }
+    return await this.withEngine(
+      async () => await this.sendRequest<T>(method, path, body)
+    )
+  }
+
+  private async sendRequest<T = unknown>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const payload =
+      body === undefined ? undefined : Buffer.from(stringifyJson(body), 'utf8')
+
+    const headers: Record<string, string> = {
+      Accept: 'application/json'
+    }
+    if (payload != null) {
+      headers['Content-Type'] = 'application/json; charset=utf-8'
+      headers['Content-Length'] = String(payload.length)
+    }
+
+    const response = await new Promise<{
+      status: number
+      raw: string
+    }>((resolve, reject) => {
+      const req = http.request(
+        {
+          method,
+          path,
+          headers,
+          ...(this.opts.socketPath != null
+            ? { socketPath: this.opts.socketPath }
+            : {
+                host: this.opts.host ?? '127.0.0.1',
+                port: this.opts.port ?? EXAMPLE_TCP_PORT
+              }),
+          timeout: this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+        },
+        res => {
+          const chunks: Buffer[] = []
+          res.on('data', (c: Buffer) => chunks.push(c))
+          res.on('end', () => {
+            resolve({
+              status: res.statusCode ?? 0,
+              raw: Buffer.concat(chunks).toString('utf8')
+            })
+          })
+          // Once headers have arrived Node routes a socket close to the
+          // *response*, not the request, and `IncomingMessage` only emits it
+          // when something is listening. Without these two the promise never
+          // settled: `main()` never resolved, `process.exitCode` was never
+          // assigned, the loop drained, and the CLI exited **0** with empty
+          // stdout — so `edge-cli spend … && echo sent` printed `sent` for a
+          // request the engine died in the middle of answering. The socket
+          // timeout cannot cover it either, because the socket is already
+          // destroyed. `openStream` below always had the handler.
+          res.on('error', reject)
+          res.on('aborted', () => {
+            reject(
+              new Error(
+                `The engine closed the connection while answering ${method} ${path}. The command may or may not have taken effect.`
+              )
+            )
+          })
+        }
+      )
+      req.on('error', reject)
+      req.on('timeout', () => {
+        req.destroy(
+          new Error(
+            `Request timed out after ${
+              (this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) / 1000
+            }s: ${method} ${path}. The engine may still be working; raise the deadline with --timeout=<seconds>.`
+          )
+        )
+      })
+      if (payload != null) req.write(payload)
+      req.end()
+    })
+
+    if (response.status === 204 || response.raw === '') {
+      if (response.status >= 400) {
+        throw new ApiClientError({
+          code: 'INTERNAL_ERROR',
+          message: `HTTP ${response.status}`,
+          status: response.status
+        })
+      }
+      return undefined as T
+    }
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(response.raw)
+    } catch {
+      throw new ApiClientError({
+        code: 'INTERNAL_ERROR',
+        message: `Non-JSON response (${response.status}): ${response.raw.slice(
+          0,
+          200
+        )}`,
+        status: response.status
+      })
+    }
+
+    if (response.status >= 400) {
+      // A well-formed envelope is used as-is; anything else — an HTML error
+      // page from a proxy, a truncated body, `{"error":"boom"}` — becomes a
+      // generic failure that still carries the status and the raw body.
+      const envelope = asMaybe(asApiErrorBody)(parsed)
+      if (envelope != null) throw new ApiClientError(envelope.error)
+      throw new ApiClientError({
+        code: 'INTERNAL_ERROR',
+        message: `HTTP ${response.status}`,
+        status: response.status,
+        details: { body: parsed }
+      })
+    }
+
+    return parsed as T
+  }
+
+  /**
+   * Hold a Server-Sent Events stream open, handing each frame to `onEvent` as
+   * it arrives. Unlike `request`, nothing is buffered: the response body never
+   * ends until the engine closes it or the caller aborts.
+   *
+   * Resolves when the engine ends the stream, rejects if it cannot be opened.
+   */
+  async stream(
+    path: string,
+    onEvent: (event: string, data: unknown) => void,
+    opts: { signal?: AbortSignal } = {}
+  ): Promise<void> {
+    // Through `withEngine` like `request`: a held-open stream is the first
+    // thing a cold `subscribe` does, and it has to start the engine too.
+    await this.withEngine(async () => {
+      await this.openStream(path, onEvent, opts)
+    })
+  }
+
+  private async openStream(
+    path: string,
+    onEvent: (event: string, data: unknown) => void,
+    opts: { signal?: AbortSignal } = {}
+  ): Promise<void> {
+    // An abort that landed before this attempt still has to end the stream.
+    // `addEventListener('abort')` on an already-aborted signal never fires,
+    // and a cold `subscribe` spends up to 30s inside `ensureEngine` between
+    // the failed first attempt and this one, so a Ctrl-C in that window would
+    // otherwise open the stream and hold it forever.
+    if (opts.signal?.aborted === true) return
+
+    let onAbort: (() => void) | undefined
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const req = http.request(
+          {
+            socketPath: this.opts.socketPath,
+            host: this.opts.host,
+            port: this.opts.port,
+            method: 'GET',
+            path,
+            headers: { Accept: 'text/event-stream' }
+          },
+          res => {
+            if (res.statusCode != null && res.statusCode >= 400) {
+              let raw = ''
+              res.setEncoding('utf8')
+              // This branch returns before the success branch's handler, so
+              // an engine that died while sending a 4xx body hung
+              // `subscribe` instead of reporting the status.
+              res.on('error', reject)
+              res.on('aborted', () => {
+                reject(
+                  new Error(
+                    `The engine closed the connection while answering GET ${path} with HTTP ${
+                      res.statusCode ?? 0
+                    }.`
+                  )
+                )
+              })
+              res.on('data', chunk => (raw += chunk))
+              res.on('end', () => {
+                try {
+                  const envelope = asApiErrorBody(JSON.parse(raw))
+                  reject(new ApiClientError(envelope.error))
+                } catch {
+                  reject(
+                    new ApiClientError({
+                      code: 'INTERNAL_ERROR',
+                      message: `HTTP ${res.statusCode ?? 0}`,
+                      status: res.statusCode ?? 500
+                    })
+                  )
+                }
+              })
+              return
+            }
+
+            // SSE frames are separated by a blank line. Hold a partial tail
+            // between chunks, since a frame can straddle a TCP read.
+            let buffer = ''
+            res.setEncoding('utf8')
+            res.on('data', (chunk: string) => {
+              buffer += chunk
+              let split = buffer.indexOf('\n\n')
+              while (split !== -1) {
+                const frame = buffer.slice(0, split)
+                buffer = buffer.slice(split + 2)
+                emitFrame(frame, onEvent)
+                split = buffer.indexOf('\n\n')
+              }
+            })
+            res.on('end', () => {
+              resolve()
+            })
+            res.on('error', reject)
+          }
+        )
+        req.on('error', reject)
+        onAbort = () => {
+          req.destroy()
+          resolve()
+        }
+        // `once`, so an abort cannot fire twice, and removed in `finally` so
+        // a long-lived signal does not accumulate listeners per attempt.
+        opts.signal?.addEventListener('abort', onAbort, { once: true })
+        req.end()
+      })
+    } finally {
+      if (onAbort != null) opts.signal?.removeEventListener('abort', onAbort)
+    }
+  }
+
+  async get<T = unknown>(path: string): Promise<T> {
+    return await this.request<T>('GET', path)
+  }
+
+  async post<T = unknown>(path: string, body?: unknown): Promise<T> {
+    return await this.request<T>('POST', path, body)
+  }
+
+  async put<T = unknown>(path: string, body?: unknown): Promise<T> {
+    return await this.request<T>('PUT', path, body)
+  }
+
+  async patch<T = unknown>(path: string, body?: unknown): Promise<T> {
+    return await this.request<T>('PATCH', path, body)
+  }
+
+  async delete<T = unknown>(path: string, body?: unknown): Promise<T> {
+    return await this.request<T>('DELETE', path, body)
+  }
+}
+
+/** Parse one `event:` / `data:` frame. Comment lines (`: ok`) are ignored. */
+function emitFrame(
+  frame: string,
+  onEvent: (event: string, data: unknown) => void
+): void {
+  let event = 'message'
+  const dataLines: string[] = []
+  for (const line of frame.split('\n')) {
+    if (line === '' || line.startsWith(':')) continue
+    if (line.startsWith('event:')) event = line.slice(6).trim()
+    else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim())
+  }
+  if (dataLines.length === 0) return
+  const raw = dataLines.join('\n')
+  let data: unknown = raw
+  try {
+    data = JSON.parse(raw)
+  } catch {
+    // Leave non-JSON payloads as the raw string.
+  }
+  onEvent(event, data)
+}
diff --git a/src/cli/client/exitCodes.ts b/src/cli/client/exitCodes.ts
new file mode 100644
index 00000000000..3560c1aee5d
--- /dev/null
+++ b/src/cli/client/exitCodes.ts
@@ -0,0 +1,71 @@
+/**
+ * The exit code each error code maps to.
+ *
+ * One table, read by `output.ts` to choose the code and by
+ * `docs/api/shared.ts` to publish it. Both used to state the same membership
+ * separately — a 35-line `if`-chain here and English prose inside a `doc`
+ * field there — with nothing tying them together, so a code added to one
+ * would silently not appear in the other.
+ *
+ * No imports, so the docs build does not pull in the client.
+ */
+export const EXIT = {
+  OK: 0,
+  GENERIC: 1,
+  USAGE: 2,
+  AUTH: 3,
+  NOT_FOUND: 4,
+  VALIDATION: 5,
+  NETWORK: 6,
+  ENGINE: 7
+} as const
+
+/** The codes assigned from an explicit list, in the order they are tried. */
+export const EXIT_CODE_BY_ERROR: Record<string, number> = {
+  INVALID_SESSION: EXIT.AUTH,
+  SESSION_EXPIRED: EXIT.AUTH,
+  // The TCP transport's own guards. An exit code of its own would be a new
+  // public contract; "the call was refused for an auth reason" is what a
+  // script needs, and that is what AUTH means.
+  UNAUTHORIZED: EXIT.AUTH,
+  FORBIDDEN: EXIT.AUTH,
+  PASSWORD_ERROR: EXIT.AUTH,
+  OTP_REQUIRED: EXIT.AUTH,
+  CHALLENGE_REQUIRED: EXIT.AUTH,
+  PIN_DISABLED: EXIT.AUTH,
+
+  NOT_FOUND: EXIT.NOT_FOUND,
+  WALLET_NOT_FOUND: EXIT.NOT_FOUND,
+  TOKEN_NOT_FOUND: EXIT.NOT_FOUND,
+
+  BAD_REQUEST: EXIT.VALIDATION,
+  INSUFFICIENT_FUNDS: EXIT.VALIDATION,
+  DUST_SPEND: EXIT.VALIDATION,
+  PENDING_FUNDS: EXIT.VALIDATION,
+  SPEND_TO_SELF: EXIT.VALIDATION,
+  NO_AMOUNT_SPECIFIED: EXIT.VALIDATION,
+  AMBIGUOUS_WALLET_ID: EXIT.VALIDATION,
+  USERNAME_ERROR: EXIT.VALIDATION,
+
+  NETWORK_ERROR: EXIT.NETWORK,
+
+  // Before the 503 rule: the engine only ever sends this code with a 503, so
+  // testing the status first made EXIT.ENGINE unreachable and reported a
+  // daemon that is going away as a network failure.
+  ENGINE_SHUTTING_DOWN: EXIT.ENGINE
+}
+
+/** Every error code that maps to one exit code, for the published table. */
+export function errorCodesFor(exitCode: number): string[] {
+  return Object.keys(EXIT_CODE_BY_ERROR).filter(
+    code => EXIT_CODE_BY_ERROR[code] === exitCode
+  )
+}
+
+/** The exit code for one API error. */
+export function exitCodeForApiError(code: string, status: number): number {
+  const mapped = EXIT_CODE_BY_ERROR[code]
+  if (mapped != null) return mapped
+  if (status === 503) return EXIT.NETWORK
+  return EXIT.GENERIC
+}
diff --git a/src/cli/client/output.ts b/src/cli/client/output.ts
new file mode 100644
index 00000000000..be813b2a042
--- /dev/null
+++ b/src/cli/client/output.ts
@@ -0,0 +1,93 @@
+import type { ErrorResponse } from '../engine/errors'
+import { ApiClientError } from './apiClient'
+import { EXIT, exitCodeForApiError } from './exitCodes'
+import { EngineUnavailableError } from './spawnEngine'
+// Re-exported, so every existing `import { EXIT } from './output'` still
+// resolves while the table itself lives in a module the docs build can read.
+export { EXIT, exitCodeForApiError } from './exitCodes'
+
+export function printJson(value: unknown): void {
+  if (typeof value === 'string') {
+    console.log(value)
+  } else {
+    console.log(JSON.stringify(value, null, 2))
+  }
+}
+
+/**
+ * One object, one line.
+ *
+ * For a held-open stream, where the documented contract is newline-delimited
+ * JSON so `jq -c` and `while read line` work. Pretty-printing spans a frame
+ * across a dozen lines, none of which parse on their own.
+ */
+export function printJsonLine(value: unknown): void {
+  console.log(typeof value === 'string' ? value : JSON.stringify(value))
+}
+
+/**
+ * Bearer values that must not reach a terminal, a shell history or a CI log.
+ *
+ * `resetToken` starts a 2FA reset on the account and `voucherAuth` authorises
+ * acting on a pending voucher. Both ride in the OTP_REQUIRED details so that a
+ * program can pass them to `request-otp-reset` or `approve-voucher`, which
+ * read them from the REST body — the terminal has no use for either.
+ */
+const SECRET_DETAIL_FIELDS = ['resetToken', 'voucherAuth']
+
+function redactDetails(
+  details: Record<string, unknown>
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...details }
+  for (const field of SECRET_DETAIL_FIELDS) {
+    if (out[field] != null)
+      out[field] = '[redacted: read it from the REST body]'
+  }
+  return out
+}
+
+/**
+ * Always emit a single JSON object on stderr for machine-readable errors.
+ * No prose banners (e.g. CAPTCHA hints).
+ */
+export function printError(error: unknown): number {
+  if (error instanceof ApiClientError) {
+    printErrorBody({
+      code: error.code,
+      message: error.message,
+      status: error.status,
+      details: error.details == null ? undefined : redactDetails(error.details)
+    })
+    return exitCodeForApiError(error.code, error.status)
+  }
+  if (error instanceof EngineUnavailableError) {
+    // The documented exit 7. Keyed off the type rather than a regex over the
+    // message, which already missed "Engine is up but run file is missing"
+    // and would have changed the published contract on any reword.
+    printErrorBody({
+      code: 'ENGINE_UNAVAILABLE',
+      message: error.message,
+      status: 503
+    })
+    return EXIT.ENGINE
+  }
+  printErrorBody({
+    code: 'INTERNAL_ERROR',
+    message: error instanceof Error ? error.message : String(error),
+    status: 500
+  })
+  return EXIT.GENERIC
+}
+
+/**
+ * Write one error envelope to stderr.
+ *
+ * Typed by `ErrorResponse['body']`, the shape the engine answers with, so
+ * the client and the engine cannot describe a failure differently. It was
+ * spelled out four times here, differing only in three constants, while
+ * `errors.ts` already named the shape.
+ */
+function printErrorBody(error: ErrorResponse['body']['error']): void {
+  const body: ErrorResponse['body'] = { error }
+  console.error(JSON.stringify(body, null, 2))
+}
diff --git a/src/cli/client/sessionFile.ts b/src/cli/client/sessionFile.ts
new file mode 100644
index 00000000000..80e0209c286
--- /dev/null
+++ b/src/cli/client/sessionFile.ts
@@ -0,0 +1,71 @@
+import {
+  asJSON,
+  asMaybe,
+  asObject,
+  asOptional,
+  asString,
+  uncleaner
+} from 'cleaners'
+import fs from 'fs'
+
+import { ensureRunDir, sessionFilePath } from '../engine/discovery'
+
+/**
+ * The session file, cleaned.
+ *
+ * The `sessionId` is a bearer token every account-scoped command sends. A cast
+ * let a malformed file through with `sessionId: undefined`, which reached the
+ * engine as the literal string 'undefined'.
+ */
+const asSessionFile = asJSON(
+  asObject({
+    sessionId: asString,
+    username: asOptional(asString),
+    updatedAt: asString
+  })
+)
+
+const uncleanSessionFile = uncleaner(asSessionFile)
+
+export type SessionFile = ReturnType<typeof asSessionFile>
+
+export function readSessionFile(profile: string): SessionFile | null {
+  try {
+    const text = fs.readFileSync(sessionFilePath(profile), 'utf8')
+    return asMaybe(asSessionFile)(text) ?? null
+  } catch {
+    return null
+  }
+}
+
+export function writeSessionFile(
+  profile: string,
+  sessionId: string,
+  username?: string
+): void {
+  ensureRunDir(profile)
+  const data: SessionFile = {
+    sessionId,
+    username,
+    updatedAt: new Date().toISOString()
+  }
+  const file = sessionFilePath(profile)
+  // Through the cleaner's uncleaner: this file is a bearer token, and a
+  // cast here is what let a malformed one through as `sessionId: undefined`.
+  // `asSessionFile` is an `asJSON` cleaner, so its uncleaner returns the JSON
+  // text already; `JSON.stringify` on top of that writes a quoted string.
+  fs.writeFileSync(file, uncleanSessionFile(data) + '\n', { mode: 0o600 })
+  // `mode` only applies when the file is created, so a session file written
+  // before that option was added keeps its old permissions forever. The run
+  // directory is already 0700, but a session id is a bearer token — narrow it
+  // on every write rather than trusting the directory alone.
+  fs.chmodSync(file, 0o600)
+}
+
+export function clearSessionFile(profile: string): void {
+  try {
+    fs.unlinkSync(sessionFilePath(profile))
+  } catch {
+    // ignore
+  }
+}
diff --git a/src/cli/client/solveCaptcha.ts b/src/cli/client/solveCaptcha.ts
new file mode 100644
index 00000000000..4e77c37e0e4
--- /dev/null
+++ b/src/cli/client/solveCaptcha.ts
@@ -0,0 +1,197 @@
+/**
+ * Headless ALTCHA proof-of-work CAPTCHA solver for login-tester.
+ */
+import { asJSON, asMaybe, asNumber, asObject, asString } from 'cleaners'
+import crypto from 'crypto'
+import https from 'https'
+
+const REQUEST_TIMEOUT_MS = 30_000
+
+/**
+ * The altcha challenge embedded in the CAPTCHA page.
+ *
+ * `maxnumber` bounds a synchronous hash loop, so it is both cleaned and
+ * capped: an unbounded value blocks the process with no timeout — the two
+ * HTTPS calls are the only thing `REQUEST_TIMEOUT_MS` covers.
+ */
+export type AltchaChallenge = ReturnType<typeof asAltchaChallenge>
+
+const asAltchaChallenge = asJSON(
+  asObject({
+    challenge: asString,
+    maxnumber: asNumber,
+    salt: asString
+  })
+)
+
+/** 10 million sha256 hashes is already several seconds of work. */
+const MAX_CHALLENGE_NUMBER = 10_000_000
+
+async function httpsGet(
+  url: string
+): Promise<{ status: number; data: string }> {
+  return await new Promise((resolve, reject) => {
+    const req = https.get(url, res => {
+      const chunks: Buffer[] = []
+      res.on('data', (chunk: Buffer | string) => {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk)
+      })
+      res.on('end', () => {
+        resolve({
+          status: res.statusCode ?? 0,
+          data: Buffer.concat(chunks).toString('utf8')
+        })
+      })
+      // Once headers have arrived Node routes a socket close to the
+      // *response*, not the request, and clears the request timer — so
+      // without these two a connection dropped mid-body never settled and
+      // `--solve-captcha` hung for ever with no output and no recovery but
+      // Ctrl-C. `req.setTimeout` below cannot cover it. Same gap and same
+      // fix as `apiClient`'s.
+      res.on('error', reject)
+      res.on('aborted', () => {
+        reject(
+          new Error(`The CAPTCHA server closed the connection: GET ${url}`)
+        )
+      })
+    })
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+      req.destroy(
+        new Error(`CAPTCHA GET timed out after ${REQUEST_TIMEOUT_MS}ms`)
+      )
+    })
+    req.on('error', reject)
+  })
+}
+
+async function httpsPost(
+  url: string,
+  body: object
+): Promise<{ status: number; data: string }> {
+  const u = new URL(url)
+  const payload = Buffer.from(JSON.stringify(body), 'utf8')
+  return await new Promise((resolve, reject) => {
+    const req = https.request(
+      {
+        hostname: u.hostname,
+        port: u.port !== '' ? Number(u.port) : 443,
+        path: u.pathname + u.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': payload.length
+        }
+      },
+      res => {
+        const chunks: Buffer[] = []
+        res.on('data', (chunk: Buffer | string) => {
+          chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk)
+        })
+        res.on('end', () => {
+          resolve({
+            status: res.statusCode ?? 0,
+            data: Buffer.concat(chunks).toString('utf8')
+          })
+        })
+        // As in `httpsGet` above, and for the same reason.
+        res.on('error', reject)
+        res.on('aborted', () => {
+          reject(
+            new Error(`The CAPTCHA server closed the connection: POST ${url}`)
+          )
+        })
+      }
+    )
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+      req.destroy(
+        new Error(`CAPTCHA POST timed out after ${REQUEST_TIMEOUT_MS}ms`)
+      )
+    })
+    req.on('error', reject)
+    req.write(payload)
+    req.end()
+  })
+}
+
+/**
+ * The ALTCHA challenge embedded in a page, validated and bounded.
+ *
+ * Split out from `solveCaptcha` so it can be tested: everything interesting
+ * about it is pure given the page text — the scrape, the clean, and the cap
+ * on a synchronous hash loop — while the function around it is two HTTPS
+ * calls. `--solve-captcha` is the flag unattended runs depend on, and the
+ * only exercise it had was a live request to login-tester.
+ */
+export function parseAltchaChallenge(pageText: string): AltchaChallenge {
+  const match = /challenge:\s*(\{[^}]+\})/.exec(pageText)
+  if (match == null) throw new Error('Could not find challenge in page')
+
+  // Cleaned, not cast, and one cleaner owns both the parse and the shape:
+  // every field here comes from a page the CLI did not write, and
+  // `maxnumber` is the bound of a synchronous hash loop. With `JSON.parse`
+  // outside the cleaner, a capture that is not valid JSON — an unquoted key,
+  // a truncated blob — threw a bare `SyntaxError` straight out of here, past
+  // the `asMaybe` guard and the message just below that was written for
+  // exactly that case.
+  const ch = asMaybe(asAltchaChallenge)(match[1])
+  if (ch == null) {
+    throw new Error('Challenge in page is not in the expected shape')
+  }
+  if (ch.maxnumber > MAX_CHALLENGE_NUMBER) {
+    throw new Error(
+      `Challenge asks for up to ${ch.maxnumber} hashes, above the ${MAX_CHALLENGE_NUMBER} limit`
+    )
+  }
+  return ch
+}
+
+/**
+ * The number whose hash matches the challenge, or null if there is none.
+ *
+ * Pure, and therefore testable with a salt and number chosen in advance.
+ */
+export async function solveAltcha(ch: AltchaChallenge): Promise<number | null> {
+  for (let i = 0; i <= ch.maxnumber; i++) {
+    // Yield periodically. The loop is synchronous, so without this a large
+    // `maxnumber` blocks the process with no output and no way to interrupt
+    // it: SIGINT is never delivered because control never returns to the
+    // event loop.
+    if (i % 5000 === 0 && i > 0) await yieldToEventLoop()
+    const hash = crypto
+      .createHash('sha256')
+      .update(ch.salt + String(i))
+      .digest('hex')
+    if (hash === ch.challenge) return i
+  }
+  return null
+}
+
+export async function solveCaptcha(challengeUri: string): Promise<boolean> {
+  const page = await httpsGet(challengeUri)
+  if (page.status < 200 || page.status >= 300) {
+    throw new Error(`CAPTCHA challenge GET failed with status ${page.status}`)
+  }
+  const solution = await solveAltcha(parseAltchaChallenge(page.data))
+  if (solution == null) return false
+  const resp = await httpsPost(challengeUri, { solution, trail: [] })
+  return resp.status >= 200 && resp.status < 300
+}
+
+async function yieldToEventLoop(): Promise<void> {
+  await new Promise<void>(resolve => setImmediate(resolve))
+}
+
+/**
+ * Given challengeId + challengeUri from a CHALLENGE_REQUIRED error,
+ * solve the CAPTCHA and return the challengeId for retry.
+ */
+export async function solveChallenge(details: {
+  challengeId: string
+  challengeUri?: string
+}): Promise<string> {
+  if (details.challengeUri != null) {
+    const ok = await solveCaptcha(details.challengeUri)
+    if (!ok) throw new Error('Failed to solve CAPTCHA')
+  }
+  return details.challengeId
+}
diff --git a/src/cli/client/spawnEngine.ts b/src/cli/client/spawnEngine.ts
new file mode 100644
index 00000000000..3c77a75b5d4
--- /dev/null
+++ b/src/cli/client/spawnEngine.ts
@@ -0,0 +1,304 @@
+import { spawn } from 'child_process'
+import fs from 'fs'
+import path from 'path'
+
+import { localeTagsMatch } from '../../locales/nodeLocale'
+import { getDetectedLocale } from '../bootNodeLocale'
+import { defaultDirectory } from '../engine/cliConfig'
+import {
+  canonicalDirectory,
+  ensureRunDir,
+  profileHash,
+  type ProfileKey,
+  socketPathFor
+} from '../engine/discovery'
+import { ApiClient } from './apiClient'
+
+/**
+ * The engine could not be reached or could not be started.
+ *
+ * A type rather than a message, because `output.ts` maps this to the
+ * documented exit code 7 and used to do it with a regex over the error's
+ * prose — which missed cases and would silently change the published
+ * contract on a reword.
+ */
+export class EngineUnavailableError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'EngineUnavailableError'
+  }
+}
+
+/**
+ * Quote one argument for a shell, so a printed command can be pasted.
+ *
+ * The `--no-spawn` hint interpolated the directory raw, and `-d` is never
+ * absent because it defaults to `~/.config/edge-cli`. A path with a space
+ * printed as `-d /Users/you/My Dir`, which the engine reads as `-d
+ * /Users/you/My` plus an unknown argument — so the advice either failed
+ * outright or started an engine under a different profile hash.
+ */
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) return value
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/** Last few KB of the spawned engine's output, for error messages. */
+function readTail(file: string, maxBytes: number): string {
+  try {
+    const text = fs.readFileSync(file, 'utf8').trimEnd()
+    if (text === '') return ''
+    return text.length > maxBytes ? text.slice(-maxBytes) : text
+  } catch {
+    return ''
+  }
+}
+
+export interface EnsureEngineOpts extends ProfileKey {
+  /** Serve an in-process fake world instead of a login server. */
+  fake?: boolean
+  /**
+   * An API key the caller gave *explicitly*, with `-k`.
+   *
+   * Only the explicit flag: a key that came from the config file is not
+   * forwarded, because the engine reads the same file itself and because
+   * `makeCoreContext` reads an explicit key as an operator override that
+   * turns off the keys.json secret and the native HMAC signer.
+   */
+  apiKey?: string
+  /**
+   * The config file the caller named with `-c`.
+   *
+   * Forwarded, because without it the spawned engine read the *default*
+   * config instead. `testMode` lives in that file and feeds the profile
+   * hash, so the two halves computed different hashes, the client polled a
+   * socket the engine never bound, and the command died after the full
+   * 30-second spawn timeout leaving a detached engine behind.
+   */
+  configPath?: string
+  noSpawn?: boolean
+  tcpPort?: number | null
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function pingEngine(socketPath: string): Promise<boolean> {
+  try {
+    const client = new ApiClient({ socketPath, timeoutMs: 3000 })
+    await client.get('/engine/status')
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function warnIfEngineLocaleDiffers(
+  client: ApiClient
+): Promise<void> {
+  try {
+    const status = await client.get<{ locale?: string }>('/engine/status')
+    const wanted = getDetectedLocale().languageTag
+    if (
+      status.locale != null &&
+      status.locale !== '' &&
+      !localeTagsMatch(status.locale, wanted)
+    ) {
+      console.error(
+        `[edge-cli] Warning: engine locale is ${status.locale}; this client requested ${wanted}. Using the engine locale.`
+      )
+    }
+  } catch {
+    // Status is optional for locale mismatch; spend/login still work.
+  }
+}
+
+/** How long to wait for a spawned engine to answer. */
+const SPAWN_TIMEOUT_MS = 30_000
+
+/**
+ * Make sure an engine is listening for this profile.
+ *
+ * Returns nothing. Its one caller is `ApiClient`'s `onConnectFail`, which
+ * discards the result and retries the request — so reading the run file back
+ * bought nothing and cost a failure mode: `Engine is up but run file is
+ * missing` killed the command on a narrow but real race, where the socket
+ * answers before `engine.json` is visible. The socket answering *is* the
+ * readiness signal, which is what `pingEngine` tests.
+ */
+export async function ensureEngine(opts: EnsureEngineOpts): Promise<void> {
+  const profile = profileHash({
+    appId: opts.appId,
+    directory: opts.directory,
+    testMode: opts.testMode,
+    loginServer: opts.loginServer
+  })
+  const socketPath = socketPathFor(profile)
+
+  if (await pingEngine(socketPath)) return
+
+  // Resolve engine entry relative to this source file or the package root.
+  // The sibling bundle comes first. Rollup flattens src/cli into lib/edgeCli.js,
+  // so in a built or installed tree (npm, Homebrew's libexec, /usr/lib/edgecli)
+  // `__dirname` is the package's `lib/` and its sibling is lib/edgeEngine.js —
+  // while `../engine/index.ts` resolves above the package and the cwd
+  // candidates point at whatever directory the user's shell happens to be in.
+  // Running from source it cannot false-positive: `__dirname` is
+  // src/cli/client, which has no edgeEngine.js.
+  const candidates = [
+    path.resolve(__dirname, 'edgeEngine.js'),
+    path.resolve(__dirname, '../engine/index.ts'),
+    path.resolve(process.cwd(), 'src/cli/engine/index.ts'),
+    path.resolve(process.cwd(), 'lib/edgeEngine.js')
+  ]
+  const engineEntry = candidates.find(p => {
+    try {
+      return fs.existsSync(p)
+    } catch {
+      return false
+    }
+  })
+  if (engineEntry == null) {
+    // An `EngineUnavailableError`, not a bare one: a broken or partial
+    // install is exactly the "could not connect to or spawn the engine"
+    // condition the published exit-code table assigns 7, and the generic
+    // `Error` arm reported it as `INTERNAL_ERROR` and exit 1, which a
+    // wrapper script branching on 7 mis-handles.
+    throw new EngineUnavailableError(
+      `Could not find edge-engine entry. Tried:\n${candidates
+        .map(p => `  - ${p}`)
+        .join('\n')}`
+    )
+  }
+
+  // One list, so the flags that reach the child and the flags the
+  // `--no-spawn` hint prints cannot drift. They had: the hint omitted `-k`,
+  // `--tcp`, `-c` and `--locale`, so it told an operator to start an engine
+  // without the key or the config file they had just supplied.
+  const engineFlags: string[] = []
+  if (opts.testMode) engineFlags.push('-t')
+  if (opts.fake === true) engineFlags.push('--fake')
+  if (opts.directory !== '' && opts.directory !== defaultDirectory()) {
+    // The canonical form, so the directory the child opens is the same
+    // string the profile hash was taken over. Forwarding the raw argv value
+    // let the two disagree.
+    engineFlags.push('-d', canonicalDirectory(opts.directory))
+  }
+  if (opts.appId !== '') engineFlags.push('-a', opts.appId)
+  if (opts.configPath != null && opts.configPath !== '') {
+    engineFlags.push('-c', opts.configPath)
+  }
+  if (opts.tcpPort != null) engineFlags.push(`--tcp=${opts.tcpPort}`)
+  const applied = getDetectedLocale()
+  engineFlags.push(`--locale=${applied.languageTag}`)
+
+  if (opts.noSpawn === true) {
+    // The hint has to name *this* profile's flags. A hardcoded
+    // `npm run engine -- -t` started an engine on a different profile hash
+    // for anyone not on the default test profile, so the next command still
+    // found nothing listening. It also has to name a command the reader can
+    // actually run: `npm run engine` only exists inside this checkout, and
+    // `docs/EDGE_CLI.md` tells people to run `node lib/edgeCli.js`.
+    const runner = engineEntry.endsWith('.js')
+      ? `${shellQuote(process.execPath)} ${shellQuote(engineEntry)}`
+      : 'npm run engine --'
+    const printed = engineFlags.map(shellQuote).join(' ')
+    throw new EngineUnavailableError(
+      `Engine is not running for profile ${profile} (socket ${socketPath}). Start it with: ${runner}${
+        printed === '' ? '' : ` ${printed}`
+      }`
+    )
+  }
+
+  const args = engineEntry.endsWith('.js')
+    ? [engineEntry, ...engineFlags]
+    : ['-r', 'sucrase/register', engineEntry, ...engineFlags]
+
+  // The core data directory holds the login stashes — `pin2Key`, `otpKey`,
+  // and the password and recovery boxes — so it is `0700` like every other
+  // root this CLI owns. Without a mode it was `0755` under a default umask
+  // and disklet then wrote `logins/*.json` at `0644`, readable by every
+  // other local user. `chmodSync` as well, because an earlier run may have
+  // created it laxer.
+  try {
+    fs.mkdirSync(opts.directory, { recursive: true, mode: 0o700 })
+  } catch {
+    // ignore
+  }
+  try {
+    fs.chmodSync(opts.directory, 0o700)
+  } catch {
+    // ignore
+  }
+
+  // Capture the child's output: a detached engine that dies during startup
+  // (bad keys.json, plugin load failure) would otherwise fail silently and
+  // surface only as a spawn timeout.
+  const startupLog = path.join(ensureRunDir(profile), 'engine-startup.log')
+  // 0600 like its siblings: it captures the engine's stdout/stderr, which
+  // includes paths and, on a failure, whatever the engine was doing.
+  const logFd = fs.openSync(startupLog, 'w', 0o600)
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env: {
+      ...process.env,
+      EDGE_CLI_LOCALE: applied.languageTag,
+      // Not on argv: `ps` shows a command line to every user on the host,
+      // and this is a credential. The engine reads it as an explicit `-k`.
+      ...(opts.apiKey != null && opts.apiKey !== ''
+        ? { EDGE_CLI_API_KEY: opts.apiKey }
+        : {})
+    }
+  })
+  // An unhandled `'error'` on a ChildProcess is an uncaught exception — a
+  // spawn failure under fork pressure, or a `process.execPath` that moved
+  // after a Node upgrade — and it would kill the client with a raw Node stack
+  // instead of the JSON envelope every other failure produces, outside
+  // `main().catch` because it never becomes a rejection.
+  let spawnError: Error | undefined
+  let exitInfo: string | undefined
+  child.once('error', (error: Error) => {
+    spawnError = error
+  })
+  // An engine that dies during startup — a bad keys.json, a plugin that
+  // throws, the "already running" exit — otherwise costs the caller the whole
+  // spawn timeout before anyone looks at the log.
+  child.once('exit', (code, signal) => {
+    exitInfo =
+      signal != null ? `killed by ${signal}` : `exited with code ${code ?? 0}`
+  })
+  child.unref()
+  fs.closeSync(logFd)
+
+  const start = Date.now()
+  while (Date.now() - start < SPAWN_TIMEOUT_MS) {
+    await sleep(250)
+    if (spawnError != null) {
+      throw new EngineUnavailableError(
+        `Could not start the engine: ${spawnError.message} (${process.execPath})`
+      )
+    }
+    if (exitInfo != null && !(await pingEngine(socketPath))) {
+      const earlyTail = readTail(startupLog, 2000)
+      throw new EngineUnavailableError(
+        `The engine ${exitInfo} during startup (profile ${profile}).` +
+          (earlyTail === ''
+            ? ` No engine output; see ${startupLog}.`
+            : `\n--- engine output (${startupLog}) ---\n${earlyTail}`)
+      )
+    }
+    if (await pingEngine(socketPath)) return
+  }
+
+  const tail = readTail(startupLog, 2000)
+  throw new EngineUnavailableError(
+    `Timed out waiting for engine to start (profile ${profile})${
+      exitInfo != null ? `; the process ${exitInfo}` : ''
+    }.` +
+      (tail === ''
+        ? ` No engine output; see ${startupLog}.`
+        : `\n--- engine output (${startupLog}) ---\n${tail}`)
+  )
+}
diff --git a/src/cli/clientResponses.ts b/src/cli/clientResponses.ts
new file mode 100644
index 00000000000..86dffaf4f4b
--- /dev/null
+++ b/src/cli/clientResponses.ts
@@ -0,0 +1,58 @@
+/**
+ * The response shapes the client reads, cleaned rather than cast.
+ *
+ * `ApiClient.request` ends `return parsed as T`, which is a type assertion
+ * over whatever the engine sent. For most commands that is harmless — the
+ * value is printed and forgotten — but two of them act on it: a login reads
+ * `sessionId` and writes it to the `0600` session file, and the edge-login
+ * poll drives a five-minute loop off `state`. A cast there means an
+ * unexpected response becomes `undefined` deep inside the client instead of
+ * a named failure here.
+ *
+ * The cleaners come from the engine's own `schemas.ts`, so the client and
+ * the engine cannot describe a session differently — the shape was
+ * hand-declared three times on this side, beside the engine's `asSession`
+ * and `SessionInfo`.
+ */
+import { asMaybe } from 'cleaners'
+
+import { asPendingEdgeLogin, asSession } from './engine/schemas'
+
+export type Session = ReturnType<typeof asSession>
+export type PendingEdgeLogin = ReturnType<typeof asPendingEdgeLogin>
+
+/**
+ * Clean one response, naming the route when it does not fit.
+ *
+ * `asMaybe` plus an explicit throw, rather than letting the cleaner's own
+ * `TypeError` out: the message a caller sees should say which call answered
+ * unexpectedly, not which property was missing from an anonymous object.
+ */
+function cleanResponse<T>(
+  cleaner: (raw: unknown) => T | undefined,
+  raw: unknown,
+  what: string
+): T {
+  const clean = cleaner(raw)
+  if (clean == null) {
+    throw new Error(
+      `The engine's ${what} response was not in the expected shape. This ` +
+        'usually means the client and the engine are different versions; ' +
+        'check `edge-cli engine-status` for the engine’s apiVersion.'
+    )
+  }
+  return clean
+}
+
+/** A login or keepalive response, with a usable `sessionId`. */
+export function readSession(raw: unknown, what: string): Session {
+  return cleanResponse(asMaybe(asSession), raw, what)
+}
+
+/** A pending edge login, as `request-edge-login` and the poll return it. */
+export function readPendingEdgeLogin(
+  raw: unknown,
+  what: string
+): PendingEdgeLogin {
+  return cleanResponse(asMaybe(asPendingEdgeLogin), raw, what)
+}
diff --git a/src/cli/command.ts b/src/cli/command.ts
new file mode 100644
index 00000000000..d2ec8424d58
--- /dev/null
+++ b/src/cli/command.ts
@@ -0,0 +1,92 @@
+import type { ApiClient } from './client/apiClient'
+
+export interface CliContext {
+  client: ApiClient
+  profile: string
+  sessionId: string | null
+  setSessionId: (sessionId: string | null, username?: string) => void
+  testMode: boolean
+  /**
+   * True inside the interactive prompt.
+   *
+   * `process.exitCode` is a global, so a command that reports through it is
+   * reporting for the whole session: one `subscribe` whose engine restarted
+   * left the prompt exiting non-zero however many commands succeeded
+   * afterwards.
+   */
+  interactive?: boolean
+  /** Set when --solve-captcha retries a login after CHALLENGE_REQUIRED. */
+  challengeId?: string
+}
+
+export type CommandHandler = (
+  ctx: CliContext,
+  argv: string[]
+) => Promise<void> | void
+
+export interface Command {
+  name: string
+  usage?: string
+  help?: string
+  needsSession?: boolean
+  invoke: CommandHandler
+}
+
+// A null-prototype map, so user input like `constructor` or `toString` cannot
+// resolve to an inherited Object.prototype member instead of a Command.
+const commands: Record<string, Command> = Object.create(null)
+
+export class UsageError extends Error {
+  command?: Command
+  constructor(command?: Command, message = 'Incorrect arguments') {
+    super(message)
+    this.name = 'UsageError'
+    this.command = command
+  }
+}
+
+export function command(
+  name: string,
+  opts: {
+    usage?: string
+    help?: string
+    needsSession?: boolean
+    replace?: boolean
+  },
+  invoke: CommandHandler
+): Command {
+  if (name in commands && opts.replace !== true) {
+    throw new Error(`Command "${name}" defined twice`)
+  }
+  const cmd: Command = {
+    name,
+    usage: opts.usage,
+    help: opts.help,
+    needsSession: opts.needsSession === true,
+    invoke
+  }
+  commands[name] = cmd
+  return cmd
+}
+
+export function findCommand(name: string): Command {
+  const cmd = commands[name]
+  if (cmd == null) throw new UsageError(undefined, `No command named "${name}"`)
+  return cmd
+}
+
+/** True when a command with this name is registered. */
+export function hasCommand(name: string): boolean {
+  return commands[name] != null
+}
+
+export function listCommands(): string[] {
+  return Object.keys(commands).sort((a, b) => a.localeCompare(b))
+}
+
+export function requireSession(ctx: CliContext): string {
+  if (ctx.sessionId == null) {
+    throw new UsageError(undefined, 'Please log in first (no sessionId)')
+  }
+  return ctx.sessionId
+}
diff --git a/src/cli/commandArgs.ts b/src/cli/commandArgs.ts
new file mode 100644
index 00000000000..3df503b750f
--- /dev/null
+++ b/src/cli/commandArgs.ts
@@ -0,0 +1,129 @@
+import { type Command, UsageError } from './command'
+
+export type FlagKind = 'string' | 'boolean' | 'repeat' | 'boolstr'
+
+export interface ParseSpec {
+  /** Default `required` when omitted and a positional is expected. */
+  positional?: 'required' | 'optional' | 'none'
+  flags?: Record<string, FlagKind>
+}
+
+export interface ParsedCommandArgs {
+  positional?: string
+  string: (name: string) => string | undefined
+  requireString: (name: string) => string
+  strings: (name: string) => string[]
+  boolean: (name: string) => boolean
+  boolstr: (name: string) => boolean | undefined
+  booleanGiven: (name: string) => boolean
+}
+
+function parseBoolstr(cmd: Command, name: string, raw: string): boolean {
+  if (raw === 'true' || raw === '1') return true
+  if (raw === 'false' || raw === '0') return false
+  throw new UsageError(cmd, `--${name} must be true or false`)
+}
+
+/**
+ * Parse command-local argv after the command name.
+ * `--name=value` is preferred; `--name value` is accepted.
+ * Boolean flags are presence-only (`--dry-run`).
+ */
+export function parseCommandArgs(
+  cmd: Command,
+  argv: string[],
+  spec: ParseSpec
+): ParsedCommandArgs {
+  const positionalMode = spec.positional ?? 'none'
+  const strings: Record<string, string[]> = Object.create(null)
+  const booleans: Record<string, boolean> = Object.create(null)
+  let positional: string | undefined
+  let sawPositional = false
+
+  const takeValue = (
+    name: string,
+    current: string,
+    i: number
+  ): { value: string; next: number } => {
+    const eq = current.indexOf('=')
+    if (eq !== -1) {
+      const value = current.slice(eq + 1)
+      if (value === '') {
+        throw new UsageError(cmd, `--${name} requires a value`)
+      }
+      return { value, next: i }
+    }
+    const next = argv[i + 1]
+    if (next == null || next.startsWith('-')) {
+      throw new UsageError(cmd, `--${name} requires a value`)
+    }
+    return { value: next, next: i + 1 }
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--') {
+      throw new UsageError(cmd, 'Unexpected --')
+    }
+    if (arg.startsWith('--')) {
+      const name = arg.slice(2).split('=')[0]
+      const kind = spec.flags?.[name]
+      if (kind == null) {
+        throw new UsageError(cmd, `Unknown option --${name}`)
+      }
+      if (kind === 'boolean') {
+        // A bare `--flag` means true, and `--flag=false` is how a caller
+        // turns off a field the server defaults to true. Refusing the value
+        // form left `--broadcast` and `--save` inert on `spend`, with no CLI
+        // path to a sign-only or a no-save spend although the usage line
+        // advertised both.
+        if (arg.includes('=')) {
+          const raw = arg.slice(arg.indexOf('=') + 1)
+          booleans[name] = parseBoolstr(cmd, name, raw)
+        } else {
+          booleans[name] = true
+        }
+        continue
+      }
+      const { value, next } = takeValue(name, arg, i)
+      i = next
+      if (kind === 'repeat') {
+        strings[name] = [...(strings[name] ?? []), value]
+      } else {
+        strings[name] = [value]
+      }
+      continue
+    }
+    if (arg.startsWith('-')) {
+      throw new UsageError(cmd, `Unknown option ${arg}`)
+    }
+    if (positionalMode === 'none' || sawPositional) {
+      throw new UsageError(cmd)
+    }
+    positional = arg
+    sawPositional = true
+  }
+
+  if (positionalMode === 'required' && positional == null) {
+    throw new UsageError(cmd)
+  }
+
+  return {
+    positional,
+    string: name => strings[name]?.[0],
+    requireString: name => {
+      const value = strings[name]?.[0]
+      if (value == null) throw new UsageError(cmd, `Missing --${name}`)
+      return value
+    },
+    strings: name => strings[name] ?? [],
+    boolean: name => booleans[name] ?? false,
+    /** Whether the flag was given at all, however it was spelled. */
+    booleanGiven: name => booleans[name] !== undefined,
+    boolstr: name => {
+      const raw = strings[name]?.[0]
+      if (raw == null) return undefined
+      return parseBoolstr(cmd, name, raw)
+    }
+  }
+}
diff --git a/src/cli/commands/all.ts b/src/cli/commands/all.ts
new file mode 100644
index 00000000000..32a61c87fe1
--- /dev/null
+++ b/src/cli/commands/all.ts
@@ -0,0 +1,8 @@
+/**
+ * Importing this module registers every one-shot CLI command as a
+ * side-effect. Import it once from the CLI entry point.
+ */
+import './generated'
+import './help'
+import './login'
+import './subscribe'
diff --git a/src/cli/commands/generated.ts b/src/cli/commands/generated.ts
new file mode 100644
index 00000000000..01371a3d6a2
--- /dev/null
+++ b/src/cli/commands/generated.ts
@@ -0,0 +1,158 @@
+/**
+ * Registers every command that is just an argument mapping.
+ *
+ * The table comes from `src/cli/generated/commands.json`, produced from the
+ * route declarations. A command listed there needs no code: its positional,
+ * flags, method and path are all in the declaration, so the mapping below is
+ * the same for all of them.
+ *
+ * Commands doing something the request shape cannot describe are hand-written
+ * in their own module and marked `custom: true` on the route.
+ */
+import { printJson } from '../client/output'
+import { type Command, command, requireSession, UsageError } from '../command'
+import { type FlagKind, parseCommandArgs } from '../commandArgs'
+import table from '../generated/commands.json'
+import { type ArgSpec, asCommandsTable } from '../generatedSchemas'
+
+/** Argument kinds map onto the parser's flag kinds. */
+function flagKind(kind: ArgSpec['kind']): FlagKind {
+  if (kind === 'boolean') return 'boolean'
+  if (kind === 'repeat') return 'repeat'
+  return 'string'
+}
+
+function parseJson(raw: string, what: string, cmd: Command): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    // `cmd`, not `undefined`: every sibling throw in this handler passes it,
+    // so `--metadata '{bad'` printed no usage line where a *missing*
+    // `--metadata` did.
+    throw new UsageError(cmd, `--${what} must be valid JSON`)
+  }
+}
+
+for (const spec of asCommandsTable(table).commands) {
+  const cmd = command(
+    spec.command,
+    {
+      usage: spec.usage,
+      help: spec.help,
+      needsSession: spec.needsSession
+    },
+    async (ctx, argv) => {
+      const flags: Record<string, FlagKind> = {}
+      for (const a of spec.args) {
+        if (a.flag != null) flags[a.flag] = flagKind(a.kind)
+      }
+      if (spec.bodyFlag != null) flags[spec.bodyFlag] = 'string'
+
+      const args = parseCommandArgs(cmd, argv, {
+        positional: spec.pathPositional != null ? 'required' : 'none',
+        flags
+      })
+
+      const query = new URLSearchParams()
+      let body: Record<string, unknown> | undefined
+
+      const put = (a: ArgSpec, value: unknown): void => {
+        if (a.target === 'query') {
+          query.set(a.field, String(value))
+        } else {
+          body = body ?? {}
+          body[a.field] = value
+        }
+      }
+
+      if (spec.preset != null) {
+        body = { ...(body ?? {}), ...spec.preset }
+      }
+      if (spec.bodyFlag != null) {
+        const raw = args.requireString(spec.bodyFlag)
+        body = parseJson(raw, spec.bodyFlag, cmd) as Record<string, unknown>
+      } else {
+        for (const a of spec.args) {
+          if (a.flag == null) continue
+          if (a.kind === 'boolean') {
+            // Sent only when the caller actually gave the flag, so a field
+            // the server defaults to true keeps that default when the flag
+            // is absent and can still be turned off with `--flag=false`.
+            if (args.booleanGiven(a.flag)) put(a, args.boolean(a.flag))
+            else if (a.required)
+              throw new UsageError(cmd, `Missing --${a.flag}`)
+            continue
+          }
+          if (a.kind === 'boolstr') {
+            // `--flag=true|false`, for a field that must be sent either way.
+            const value = args.boolstr(a.flag)
+            if (value == null) {
+              if (a.required) throw new UsageError(cmd, `Missing --${a.flag}`)
+              continue
+            }
+            put(a, value)
+            continue
+          }
+          if (a.kind === 'repeat') {
+            const values = args.strings(a.flag)
+            if (values.length > 0) put(a, values)
+            else if (a.required)
+              throw new UsageError(cmd, `Missing --${a.flag}`)
+            continue
+          }
+          const value = args.string(a.flag)
+          if (value == null) {
+            if (a.required) throw new UsageError(cmd, `Missing --${a.flag}`)
+            continue
+          }
+          put(a, a.kind === 'json' ? parseJson(value, a.flag, cmd) : value)
+        }
+      }
+
+      // `{sessionId}` is filled from the stored session; other path params
+      // come from the command's positional.
+      let path = spec.path
+      if (spec.needsSession) {
+        path = path.replace(
+          '{sessionId}',
+          encodeURIComponent(requireSession(ctx))
+        )
+      }
+      if (spec.pathPositional != null) {
+        path = path.replace(
+          `{${spec.pathPositional}}`,
+          encodeURIComponent(String(args.positional ?? ''))
+        )
+      }
+
+      // A challenge solved by `--solve-captcha` arrives on the retry, not in
+      // argv, so inject it when the route takes one and the caller did not
+      // pass `--challenge-id` itself. Without this the retry re-sends the
+      // request unchallenged and the server issues a fresh challenge.
+      const challengeArg = spec.args.find(a => a.field === 'challengeId')
+      if (challengeArg != null && ctx.challengeId != null) {
+        if (challengeArg.target === 'query') {
+          if (query.get('challengeId') == null) {
+            query.set('challengeId', ctx.challengeId)
+          }
+        } else {
+          // The body is created if it does not exist yet. Guarding the whole
+          // branch on `body != null` dropped a `challengeId` whenever no
+          // other field happened to build a body, so the retry went out
+          // unchallenged and the server issued a fresh challenge. The query
+          // branch above has no such condition.
+          body = { challengeId: ctx.challengeId, ...body }
+        }
+      }
+
+      const qs = query.toString()
+      if (qs !== '') path += (path.includes('?') ? '&' : '?') + qs
+
+      const result =
+        spec.method === 'GET'
+          ? await ctx.client.get(path)
+          : await ctx.client.post(path, body)
+      printJson(result ?? { ok: true })
+    }
+  )
+}
diff --git a/src/cli/commands/help.ts b/src/cli/commands/help.ts
new file mode 100644
index 00000000000..df0902337a9
--- /dev/null
+++ b/src/cli/commands/help.ts
@@ -0,0 +1,46 @@
+import { printJson } from '../client/output'
+import { command, findCommand, listCommands, UsageError } from '../command'
+import helpDocs from '../generated/helpDocs.json'
+import { asHelpDocs } from '../generatedSchemas'
+
+const { commands: generated } = asHelpDocs(helpDocs)
+
+const helpCmd = command(
+  'help',
+  {
+    usage: 'help [<command>]',
+    help: 'List all commands, or show usage and documentation for one command'
+  },
+  (_ctx, argv) => {
+    if (argv.length > 1) throw new UsageError(helpCmd)
+
+    if (argv.length === 0) {
+      printJson({ commands: listCommands() })
+      return
+    }
+
+    const [name] = argv
+    const target = findCommand(name)
+    // Prose comes from the route's JSDoc via src/cli/generated/helpDocs.json.
+    // Commands not yet declared with route() fall back to their own string.
+    const docs = generated[target.name]
+    printJson({
+      name: target.name,
+      usage: docs?.usage ?? target.usage ?? target.name,
+      // A command two routes share — `local-settings` reads on GET, writes on
+      // POST — carries both forms, so neither looks invalid.
+      ...(docs?.alsoUsage != null ? { alsoUsage: docs.alsoUsage } : {}),
+      ...(docs?.alsoRest != null ? { alsoRest: docs.alsoRest } : {}),
+      summary: docs?.summary ?? target.help ?? null,
+      ...(docs?.description != null ? { description: docs.description } : {}),
+      ...(docs?.core != null ? { core: docs.core } : {}),
+      ...(docs != null ? { rest: `${docs.method} ${docs.path}` } : {}),
+      ...(docs?.params != null ? { params: docs.params } : {}),
+      ...(docs?.returns != null ? { returns: docs.returns } : {}),
+      ...(docs?.returnsDoc != null ? { returnsDoc: docs.returnsDoc } : {}),
+      ...(docs?.notes != null ? { notes: docs.notes } : {}),
+      ...(docs?.errors != null ? { errors: docs.errors } : {}),
+      needsSession: target.needsSession === true
+    })
+  }
+)
diff --git a/src/cli/commands/login.ts b/src/cli/commands/login.ts
new file mode 100644
index 00000000000..e877a25a076
--- /dev/null
+++ b/src/cli/commands/login.ts
@@ -0,0 +1,198 @@
+import { printJson } from '../client/output'
+import { readSession } from '../clientResponses'
+import {
+  type CliContext,
+  command,
+  requireSession,
+  UsageError
+} from '../command'
+import { parseCommandArgs } from '../commandArgs'
+import { accountPath } from './paths'
+
+const accountCreateCmd = command(
+  'create-account',
+  {
+    usage:
+      'create-account [--username=<name>] --password=<pass> --pin=<pin> [--otp=<code>] [--otp-key=<key>] [--challenge-id=<id>]',
+    help: 'Create a new Edge account'
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(accountCreateCmd, argv, {
+      positional: 'none',
+      flags: {
+        username: 'string',
+        password: 'string',
+        pin: 'string',
+        otp: 'string',
+        'otp-key': 'string',
+        'challenge-id': 'string'
+      }
+    })
+    const session = readSession(
+      await ctx.client.post('/create-account', {
+        username: args.string('username'),
+        password: args.requireString('password'),
+        pin: args.requireString('pin'),
+        otp: args.string('otp'),
+        otpKey: args.string('otp-key'),
+        challengeId: args.string('challenge-id') ?? ctx.challengeId
+      }),
+      'create-account'
+    )
+    ctx.setSessionId(session.sessionId, session.username)
+    printJson(session)
+  }
+)
+
+const passwordLoginCmd = command(
+  'login-with-password',
+  {
+    usage:
+      'login-with-password --username=<name> --password=<pass> [--otp=<code>] [--otp-key=<key>] [--challenge-id=<id>]',
+    help: 'Log in with a username and password'
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(passwordLoginCmd, argv, {
+      positional: 'none',
+      flags: {
+        username: 'string',
+        password: 'string',
+        otp: 'string',
+        'otp-key': 'string',
+        'challenge-id': 'string'
+      }
+    })
+    const session = readSession(
+      await ctx.client.post('/login-with-password', {
+        username: args.requireString('username'),
+        password: args.requireString('password'),
+        otp: args.string('otp'),
+        otpKey: args.string('otp-key'),
+        challengeId: args.string('challenge-id') ?? ctx.challengeId
+      }),
+      'login-with-password'
+    )
+    ctx.setSessionId(session.sessionId, session.username)
+    printJson(session)
+  }
+)
+
+const keyLoginCmd = command(
+  'login-with-key',
+  {
+    usage:
+      'login-with-key --username-or-login-id=<value> --login-key=<key> [--otp=<code>] [--otp-key=<key>] [--challenge-id=<id>]',
+    help: 'Log in with a raw account login key'
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(keyLoginCmd, argv, {
+      positional: 'none',
+      flags: {
+        'username-or-login-id': 'string',
+        'login-key': 'string',
+        otp: 'string',
+        'otp-key': 'string',
+        'challenge-id': 'string'
+      }
+    })
+    const session = readSession(
+      await ctx.client.post('/login-with-key', {
+        usernameOrLoginId: args.requireString('username-or-login-id'),
+        loginKey: args.requireString('login-key'),
+        otp: args.string('otp'),
+        otpKey: args.string('otp-key'),
+        challengeId: args.string('challenge-id') ?? ctx.challengeId
+      }),
+      'login-with-key'
+    )
+    ctx.setSessionId(session.sessionId, session.username)
+    printJson(session)
+  }
+)
+
+const pinLoginCmd = command(
+  'login-with-pin',
+  {
+    usage:
+      'login-with-pin --username-or-login-id=<value> --pin=<pin> [--otp=<code>] [--otp-key=<key>] [--challenge-id=<id>]',
+    help: 'Log in with a device PIN'
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(pinLoginCmd, argv, {
+      positional: 'none',
+      flags: {
+        'username-or-login-id': 'string',
+        pin: 'string',
+        otp: 'string',
+        'otp-key': 'string',
+        'challenge-id': 'string'
+      }
+    })
+    const session = readSession(
+      await ctx.client.post('/login-with-pin', {
+        usernameOrLoginId: args.requireString('username-or-login-id'),
+        pin: args.requireString('pin'),
+        otp: args.string('otp'),
+        otpKey: args.string('otp-key'),
+        challengeId: args.string('challenge-id') ?? ctx.challengeId
+      }),
+      'login-with-pin'
+    )
+    ctx.setSessionId(session.sessionId, session.username)
+    printJson(session)
+  }
+)
+
+const recoveryLoginCmd = command(
+  'login-with-recovery',
+  {
+    usage:
+      'login-with-recovery --username=<name> --recovery-key=<key> --answer=<text> [--answer=…] [--otp=<code>] [--otp-key=<key>] [--challenge-id=<id>]',
+    help: 'Log in with recovery-question answers'
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(recoveryLoginCmd, argv, {
+      positional: 'none',
+      flags: {
+        username: 'string',
+        'recovery-key': 'string',
+        answer: 'repeat',
+        otp: 'string',
+        'otp-key': 'string',
+        'challenge-id': 'string'
+      }
+    })
+    const answers = args.strings('answer')
+    if (answers.length === 0) {
+      throw new UsageError(recoveryLoginCmd, 'Missing --answer')
+    }
+    const session = readSession(
+      await ctx.client.post('/login-with-recovery', {
+        username: args.requireString('username'),
+        recoveryKey: args.requireString('recovery-key'),
+        answers,
+        otp: args.string('otp'),
+        otpKey: args.string('otp-key'),
+        challengeId: args.string('challenge-id') ?? ctx.challengeId
+      }),
+      'login-with-recovery'
+    )
+    ctx.setSessionId(session.sessionId, session.username)
+    printJson(session)
+  }
+)
+
+command(
+  'logout',
+  {
+    usage: 'logout',
+    help: 'Log out of the current session',
+    needsSession: true
+  },
+  async (ctx: CliContext) => {
+    const sessionId = requireSession(ctx)
+    await ctx.client.post(accountPath(sessionId, '/logout'))
+    ctx.setSessionId(null)
+    printJson({ ok: true })
+  }
+)
diff --git a/src/cli/commands/paths.ts b/src/cli/commands/paths.ts
new file mode 100644
index 00000000000..a0206edaac4
--- /dev/null
+++ b/src/cli/commands/paths.ts
@@ -0,0 +1,17 @@
+/**
+ * The two account-scoped path shapes the hand-written commands build.
+ *
+ * `accountPath` existed in `account.ts` with one caller, `walletPath` in
+ * `wallet.ts` was the same template plus `/wallet`, and four other call sites
+ * wrote the `/account/${encodeURIComponent(sessionId)}…` template out by
+ * hand. The encoding is the part that must not be forgotten: a sessionId is
+ * base58 so it needs none today, but a path built without it is one id format
+ * away from a broken URL.
+ */
+export function accountPath(sessionId: string, suffix = ''): string {
+  return `/account/${encodeURIComponent(sessionId)}${suffix}`
+}
+
+export function walletPath(sessionId: string, suffix = ''): string {
+  return accountPath(sessionId, `/wallet${suffix}`)
+}
diff --git a/src/cli/commands/subscribe.ts b/src/cli/commands/subscribe.ts
new file mode 100644
index 00000000000..5decaa84c3f
--- /dev/null
+++ b/src/cli/commands/subscribe.ts
@@ -0,0 +1,117 @@
+import { EXIT, printJsonLine } from '../client/output'
+import { command } from '../command'
+import { parseCommandArgs } from '../commandArgs'
+
+interface ClosedData {
+  reason?: string
+}
+
+/**
+ * Why the stream ended, as an exit code.
+ *
+ * A context-scoped stream ends only when the engine does, so any reason means
+ * the engine went away. A stream opened with `--session-id` is also closed by
+ * that session logging out, which is an orderly end rather than a failure:
+ * this comment used to say every subscriber was context-scoped, which stopped
+ * being true when the route gained a scope.
+ */
+function exitCodeForClose(reason: string | undefined, scoped: boolean): number {
+  if (scoped && reason === 'logout') return EXIT.OK
+  return EXIT.ENGINE
+}
+
+const subscribeCmd = command(
+  'subscribe',
+  {
+    usage:
+      'subscribe [--session-id=<sessionId>] [--wallet-id=<walletId>] [--type=<eventType>]',
+    help: 'Stream engine events as newline-delimited JSON until interrupted'
+  },
+  async (ctx, argv) => {
+    // All three flags the route declares. `--session-id` and `--wallet-id`
+    // were published in the usage line and then refused here with
+    // `Unknown option`, so the account-scoped stream the engine supports had
+    // no CLI path at all.
+    const args = parseCommandArgs(subscribeCmd, argv, {
+      positional: 'none',
+      flags: {
+        type: 'repeat',
+        'session-id': 'string',
+        'wallet-id': 'string'
+      }
+    })
+    const wanted = new Set(args.strings('type'))
+    const sessionId = args.string('session-id')
+    const walletId = args.string('wallet-id')
+
+    const controller = new AbortController()
+    let closeReason: string | undefined
+    let interrupted = false
+
+    const stop = (): void => {
+      // Registering these handlers removes Node's own terminate-on-SIGINT, so
+      // a second signal has to end the process itself: aborting an already
+      // aborted controller is a no-op, and a cold start can sit in
+      // `ensureEngine` for up to 30s before the abort is observed.
+      // 128 + SIGINT, the shell's own convention for a signalled exit.
+      if (interrupted) process.exit(130)
+      interrupted = true
+      controller.abort()
+    }
+    process.on('SIGINT', stop)
+    process.on('SIGTERM', stop)
+
+    // The engine filters too, so an unwanted type never crosses the socket.
+    // The client-side check below stays: it also covers a type the engine
+    // sends unconditionally, like `subscription.closed`.
+    const query = [...wanted].map(t => `type=${encodeURIComponent(t)}`)
+    if (sessionId != null && sessionId !== '') {
+      query.push(`sessionId=${encodeURIComponent(sessionId)}`)
+      // Only meaningful with a session, which is what the route documents.
+      if (walletId != null && walletId !== '') {
+        query.push(`walletId=${encodeURIComponent(walletId)}`)
+      }
+    }
+    const path =
+      query.length > 0 ? `/engine/events?${query.join('&')}` : '/engine/events'
+
+    try {
+      await ctx.client.stream(
+        path,
+        (type, data) => {
+          if (type === 'subscription.closed') {
+            closeReason = (data as ClosedData)?.reason
+          }
+          if (wanted.size > 0 && !wanted.has(type)) return
+          // One JSON object per line, so the stream pipes into jq or a log.
+          printJsonLine({ type, data })
+        },
+        { signal: controller.signal }
+      )
+    } finally {
+      // `finally`, because a stream that rejects — a 4xx from the engine, a
+      // socket error — used to leave both listeners behind, and inside the
+      // interactive prompt each failed `subscribe` leaked two of them until
+      // Node warned at eleven.
+      process.off('SIGINT', stop)
+      process.off('SIGTERM', stop)
+    }
+
+    if (interrupted) return
+    // The engine ended the stream. Say why, and exit accordingly.
+    printJsonLine({ type: 'subscription.ended', data: { reason: closeReason } })
+    // Not `process.exit`: this command is documented as newline-delimited
+    // JSON for piping, and exiting here discarded whatever stdout had not
+    // flushed — including this final frame.
+    //
+    // Not in the prompt either: `process.exitCode` is a global, so one
+    // subscription whose engine restarted would otherwise decide the exit
+    // code of the whole interactive session.
+    if (ctx.interactive !== true) {
+      process.exitCode = exitCodeForClose(
+        closeReason,
+        sessionId != null && sessionId !== ''
+      )
+    }
+  }
+)
diff --git a/src/cli/declare-modules.d.ts b/src/cli/declare-modules.d.ts
new file mode 100644
index 00000000000..e4e870111f0
--- /dev/null
+++ b/src/cli/declare-modules.d.ts
@@ -0,0 +1 @@
+declare module 'lib-cmdparse'
diff --git a/src/cli/engine/apiVersion.ts b/src/cli/engine/apiVersion.ts
new file mode 100644
index 00000000000..ec571e6044b
--- /dev/null
+++ b/src/cli/engine/apiVersion.ts
@@ -0,0 +1,14 @@
+/**
+ * The protocol version clients branch on.
+ *
+ * One declaration, because it reaches five protocol-visible surfaces that
+ * nothing gated against each other: the run file's `apiVersion`, the
+ * `X-Edge-Api-Version` header on both the REST and the SSE responses,
+ * `/engine/status`, the OpenAPI document's `info.version` and the HTML
+ * reference's header. Separate copies meant bumping one left the others
+ * lying about the protocol — the SSE header was exactly that, a literal
+ * this comment claimed could not exist.
+ *
+ * It lived in `router.ts`, which is URL matching, not versioning.
+ */
+export const API_VERSION = '1.0.0'
diff --git a/src/cli/engine/appConfig.ts b/src/cli/engine/appConfig.ts
new file mode 100644
index 00000000000..bc047919bba
--- /dev/null
+++ b/src/cli/engine/appConfig.ts
@@ -0,0 +1,50 @@
+/**
+ * Load GUI-style config.json (swapPlugins).
+ * Searches ./config.json then ~/.edge-cli/config.json.
+ */
+import { asObject, asOptional, asUnknown } from 'cleaners'
+
+import { configSearchPaths, readJsonConfig } from './readJsonConfig'
+
+const asAppConfigFile = asObject({
+  swapPlugins: asOptional(asObject(asUnknown))
+})
+
+/** Derived from the cleaner, so the two cannot drift. */
+export type AppConfigFile = ReturnType<typeof asAppConfigFile>
+
+/** Where loadAppConfig looks, in order. */
+function appConfigSearchPaths(): string[] {
+  return configSearchPaths('config.json')
+}
+
+function readAppConfigFile(path: string): AppConfigFile | null {
+  return readJsonConfig(path, asAppConfigFile, 'config.json')
+}
+
+/**
+ * Loads config.json from (in order):
+ * 1. ./config.json
+ * 2. ~/.edge-cli/config.json
+ *
+ * Missing files are skipped. Present but invalid JSON/cleaner failures throw,
+ * matching loadKeys, so a typo cannot silently disable every swap plugin.
+ */
+export function loadAppConfig(): AppConfigFile {
+  for (const path of appConfigSearchPaths()) {
+    const parsed = readAppConfigFile(path)
+    if (parsed != null) return parsed
+  }
+  return asAppConfigFile({})
+}
+
+/**
+ * The cleaner itself, for the drift test.
+ *
+ * `configSubsets.test.ts` feeds it what the app's own `config.json` /
+ * `keys.json` cleaner produces, so this narrower subset cannot stop
+ * accepting the file the app writes. The engine deliberately does not use
+ * the app's `makeConfig` loader, which fills defaults and writes the file
+ * back — a daemon asked to read a user's keys must not rewrite them.
+ */
+export const asAppConfigFileForTests = asAppConfigFile
diff --git a/src/cli/engine/cliConfig.ts b/src/cli/engine/cliConfig.ts
new file mode 100644
index 00000000000..7f187703444
--- /dev/null
+++ b/src/cli/engine/cliConfig.ts
@@ -0,0 +1,59 @@
+import { asBoolean, asJSON, asObject, asOptional, asString } from 'cleaners'
+import fs from 'fs'
+import os from 'os'
+import { join, resolve } from 'path'
+
+const asCliConfig = asObject({
+  apiKey: asOptional(asString),
+  appId: asOptional(asString),
+  authServer: asOptional(asString),
+  directory: asOptional(asString),
+  locale: asOptional(asString),
+  password: asOptional(asString),
+  testMode: asOptional(asBoolean),
+  username: asOptional(asString),
+  workingDir: asOptional(asString)
+})
+
+/** Derived from the cleaner, so the two cannot drift. */
+export type CliConfig = ReturnType<typeof asCliConfig>
+
+export function loadConfig(configPath?: string): CliConfig {
+  let where: string | undefined
+  let text: string | undefined
+
+  if (configPath != null) {
+    try {
+      where = resolve(configPath)
+      text = fs.readFileSync(where, 'utf8')
+    } catch (error) {
+      throw new Error(
+        `Cannot load config file "${configPath}": ${String(error)}`
+      )
+    }
+  } else {
+    try {
+      where = resolve(
+        join(os.homedir(), '.config', 'edge-cli', 'edge-cli.conf')
+      )
+      text = fs.readFileSync(where, 'utf8')
+    } catch {
+      // optional
+    }
+  }
+
+  // Through the cleaner, so "no config file" and "an empty config file"
+  // are the same value rather than two shapes.
+  if (text == null || where == null) return asCliConfig({})
+
+  try {
+    // `asJSON`, so one cleaner owns both the parse and the shape.
+    return asJSON(asCliConfig)(text)
+  } catch (error) {
+    throw new Error(`Cannot load config file "${where}": ${String(error)}`)
+  }
+}
+
+export function defaultDirectory(): string {
+  return join(os.homedir(), '.config', 'edge-cli')
+}
diff --git a/src/cli/engine/cliHome.ts b/src/cli/engine/cliHome.ts
new file mode 100644
index 00000000000..2964e820957
--- /dev/null
+++ b/src/cli/engine/cliHome.ts
@@ -0,0 +1,37 @@
+/**
+ * The CLI's own home directory, and the paths under it.
+ *
+ * `join(os.homedir(), '.edge-cli', …)` was written out at six call sites in
+ * four modules — `run`, `logs` twice, `config.json` and `keys.json` — so the
+ * one place `docs/EDGE_CLI.md` documents as a single root had no single
+ * declaration, and moving it would have silently orphaned whichever sites
+ * were missed.
+ *
+ * Resolved at call time, not at module load: under jest `os.homedir()` is
+ * what the tests stub, and a value captured at import would be the
+ * developer's real home.
+ *
+ * No imports beyond `os` and `path`, so any module can use it.
+ */
+import os from 'os'
+import { join } from 'path'
+
+/** `~/.edge-cli`. */
+export function cliHome(): string {
+  return join(os.homedir(), '.edge-cli')
+}
+
+/** `~/.edge-cli/run`, which holds one directory per profile. */
+export function cliRunRoot(): string {
+  return join(cliHome(), 'run')
+}
+
+/** `~/.edge-cli/logs`, one file per profile. */
+export function cliLogsDir(): string {
+  return join(cliHome(), 'logs')
+}
+
+/** A file directly under `~/.edge-cli`, such as `keys.json`. */
+export function cliHomeFile(name: string): string {
+  return join(cliHome(), name)
+}
diff --git a/src/cli/engine/discovery.ts b/src/cli/engine/discovery.ts
new file mode 100644
index 00000000000..e94e1472dea
--- /dev/null
+++ b/src/cli/engine/discovery.ts
@@ -0,0 +1,467 @@
+import {
+  asBoolean,
+  asJSON,
+  asMaybe,
+  asNumber,
+  asObject,
+  asOptional,
+  asString,
+  uncleaner
+} from 'cleaners'
+import crypto from 'crypto'
+import fs from 'fs'
+import net from 'net'
+import { join, resolve } from 'path'
+
+import { cliRunRoot } from './cliHome'
+
+export interface ProfileKey {
+  appId: string
+  directory: string
+  testMode: boolean
+  loginServer?: string
+}
+
+/**
+ * One directory, one string.
+ *
+ * The profile hash is the only thing keeping two engines off one core data
+ * directory, and it was taken over the raw argv string — so `/x/edge-data`,
+ * `/x/edge-data/`, `/x/./edge-data` and a relative `edge-data` were four
+ * profiles for one directory, each holding what it believed was an exclusive
+ * claim, with no race needed to get there. `realpathSync` as well as
+ * `resolve`, so a symlink and its target agree; `resolve` alone where the
+ * path does not exist yet, because the engine is what creates it.
+ */
+export function canonicalDirectory(directory: string): string {
+  const resolved = resolve(directory)
+  try {
+    return fs.realpathSync.native(resolved)
+  } catch {
+    return resolved
+  }
+}
+
+export function profileHash(key: ProfileKey): string {
+  const payload = JSON.stringify({
+    appId: key.appId,
+    directory: canonicalDirectory(key.directory),
+    testMode: key.testMode,
+    loginServer: key.loginServer ?? null
+  })
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16)
+}
+
+/**
+ * How long a profile with no run file is treated as mid-boot.
+ *
+ * Longer than a Node + sucrase startup, shorter than anyone would wait
+ * before wondering why a directory is still there.
+ */
+const BOOT_GRACE_MS = 60_000
+
+/** How long to wait for a connect before calling a socket dead. */
+const LISTEN_PROBE_MS = 1000
+
+/** Where every profile's run directory lives. */
+function runRoot(): string {
+  return cliRunRoot()
+}
+
+export function runDir(profile: string): string {
+  return join(runRoot(), profile)
+}
+
+export function socketPathFor(profile: string): string {
+  return join(runDir(profile), 'engine.sock')
+}
+
+export function runFilePath(profile: string): string {
+  return join(runDir(profile), 'engine.json')
+}
+
+export function sessionFilePath(profile: string): string {
+  return join(runDir(profile), 'session.json')
+}
+
+export function ensureRunDir(profile: string): string {
+  const dir = runDir(profile)
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+/**
+ * Serialize a run file. One spelling, through the cleaner's uncleaner, so a
+ * shape change is a compile error rather than a file `readRunFile` rejects.
+ *
+ * `asEngineRunFile` is an `asJSON` cleaner, so its uncleaner already returns
+ * JSON *text* — wrapping that in `JSON.stringify` writes a quoted string and
+ * the engine cannot read its own run file.
+ */
+function runFileText(data: EngineRunFile): string {
+  return uncleanRunFile(data) + '\n'
+}
+
+/**
+ * Replace the run file, atomically.
+ *
+ * Write-then-rename, because this runs *after* the socket is bound: a
+ * truncating `writeFileSync` left a window in which a live engine's run file
+ * was empty or half-written, which is exactly the state `cleanupStaleLock`
+ * reads as "no claim" before unlinking the socket. A rename is atomic within
+ * one directory, so a reader sees either the old record or the new one.
+ */
+export function writeRunFile(profile: string, data: EngineRunFile): void {
+  ensureRunDir(profile)
+  const path = runFilePath(profile)
+  const temp = `${path}.${process.pid}.tmp`
+  fs.writeFileSync(temp, runFileText(data), { mode: 0o600 })
+  try {
+    // `mode` only applies when creating; force 0600 before it is visible.
+    fs.chmodSync(temp, 0o600)
+  } catch {
+    // ignore
+  }
+  fs.renameSync(temp, path)
+}
+
+/**
+ * Claim the profile by creating the run file exclusively.
+ *
+ * `wx` fails when the file already exists, so two engines racing from cold
+ * cannot both believe they own the profile. The socket path is deterministic
+ * from the profile, so it can be recorded before anything is bound; the real
+ * `tcpPort` follows in the full `writeRunFile` once the listeners are up.
+ *
+ * Returns false when another engine won the race.
+ */
+export function claimRunFile(profile: string, data: EngineRunFile): boolean {
+  ensureRunDir(profile)
+  try {
+    fs.writeFileSync(runFilePath(profile), runFileText(data), {
+      mode: 0o600,
+      flag: 'wx'
+    })
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
+    throw error
+  }
+}
+
+/**
+ * The run file, cleaned.
+ *
+ * A cast would let a truncated or hand-edited engine.json through as an object
+ * whose `pid` is undefined, which `isProcessAlive` then hands to
+ * `process.kill`, and whose `socketPath` callers try to connect to.
+ */
+const asEngineRunFile = asJSON(
+  asObject({
+    // The only field any reader uses, so the only one that may be required.
+    pid: asNumber,
+    // Everything else is written for an operator reading the file by hand.
+    // `asOptional`, because a *required* field here is destructive: a run
+    // file the cleaner rejects makes `readRunFile` answer null,
+    // `cleanupStaleLock` unlink the socket but leave the file, and
+    // `claimRunFile`'s `flag: 'wx'` then fail EEXIST — so the engine reports
+    // "already running" with no pid and exits 1, the live engine has no
+    // socket, `engine-stop` cannot reach it, and every later invocation
+    // repeats that until the profile directory is removed by hand. Reachable
+    // today by a SIGKILL during `claimRunFile`'s `wx` create — the one write
+    // here that is not a rename — and guaranteed on the next release that
+    // adds a field while an engine from this one is still detached and
+    // running.
+    apiVersion: asOptional(asString),
+    socketPath: asOptional(asString),
+    tcpPort: asOptional(asNumber, null),
+    // The bearer token the TCP listener requires. Written only here, in a
+    // `0600` file inside a `0700` directory, so being able to read it is
+    // what authorises a caller.
+    tcpToken: asOptional(asString),
+    appId: asOptional(asString),
+    testMode: asOptional(asBoolean),
+    startedAt: asOptional(asString)
+  })
+)
+
+const uncleanRunFile = uncleaner(asEngineRunFile)
+
+/**
+ * Derived from the cleaner, not declared beside it: a hand-written copy went
+ * stale the moment the cleaner's optionality changed, and the compiler can
+ * only notice that when one of them is the source of truth.
+ */
+export type EngineRunFile = ReturnType<typeof asEngineRunFile>
+
+export function readRunFile(profile: string): EngineRunFile | null {
+  try {
+    const text = fs.readFileSync(runFilePath(profile), 'utf8')
+    return asMaybe(asEngineRunFile)(text) ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Clear everything a dead engine leaves in its profile directory.
+ *
+ * `session.json` goes too: a sessionId cannot outlive the engine that issued
+ * it, so keeping it only means the next command fails `INVALID_SESSION` until
+ * the user works out why.
+ */
+export function removeRunArtifacts(
+  profile: string,
+  opts: {
+    keepStartupLog?: boolean
+    /**
+     * Both set by a startup that claimed the profile and then died without
+     * ever serving on it — above all one that died *because* it lost the
+     * `listen` race. The socket then belongs to the engine that won, and
+     * `session.json` belongs to the user: unlinking them left the winner
+     * resident and unreachable with the user's session gone, and every later
+     * command spawning another engine on the same directory. Only the run
+     * file is this process's to clear.
+     */
+    keepSocket?: boolean
+    keepSession?: boolean
+  } = {}
+): void {
+  for (const file of [
+    ...(opts.keepSocket === true ? [] : [socketPathFor(profile)]),
+    runFilePath(profile),
+    ...(opts.keepSession === true ? [] : [sessionFilePath(profile)]),
+    // Not while an engine is booting: the client opens this before the engine
+    // claims the profile, and it is the only record of a startup that dies
+    // before the socket exists — the case it was added for.
+    ...(opts.keepStartupLog === true
+      ? []
+      : [join(runDir(profile), 'engine-startup.log')])
+  ]) {
+    try {
+      fs.unlinkSync(file)
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    // Leave no empty profile directory behind: one per engine per data
+    // directory otherwise accumulates under ~/.edge-cli/run forever.
+    fs.rmdirSync(runDir(profile))
+  } catch {
+    // not empty, or already gone
+  }
+}
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error: unknown) {
+    // EPERM means the pid exists but belongs to another user.
+    return (
+      error != null &&
+      typeof error === 'object' &&
+      'code' in error &&
+      (error as { code: string }).code === 'EPERM'
+    )
+  }
+}
+
+/**
+ * Whether a claim is young enough that its engine may still be booting.
+ *
+ * `startedAt` when the claim carries one, and the run file's own mtime
+ * otherwise, so a file written by an engine from before that field existed is
+ * still given the grace rather than swept out from under itself.
+ */
+function claimedWithin(
+  profile: string,
+  run: EngineRunFile,
+  graceMs: number
+): boolean {
+  const started =
+    run.startedAt != null
+      ? Date.parse(run.startedAt)
+      : mtimeMsOf(runFilePath(profile))
+  if (!Number.isFinite(started)) return false
+  return Date.now() - started < graceMs
+}
+
+/** A file's mtime in milliseconds, or `NaN` when it cannot be read. */
+function mtimeMsOf(path: string): number {
+  try {
+    return fs.statSync(path).mtimeMs
+  } catch {
+    return Number.NaN
+  }
+}
+
+/**
+ * Clear the artifacts of an engine that is no longer running.
+ *
+ * Returns the pid of a live engine for this profile, so the caller can refuse
+ * to start rather than unlinking a working socket out from under it, and
+ * `null` when the profile is free.
+ *
+ * `null` also covers an `engine.json` that is missing, malformed or truncated,
+ * since `readRunFile` cleans it and yields nothing for all three. A file it
+ * cannot read is treated as no claim at all and its socket is removed, which
+ * is the safe reading: a live engine always has a well-formed run file.
+ * `claimRunFile` writes a complete record before anything binds, and
+ * `writeRunFile` replaces it by rename rather than truncation, so there is no
+ * window in which a running engine's file is half-written.
+ */
+export async function cleanupStaleLock(
+  profile: string
+): Promise<number | null> {
+  const run = readRunFile(profile)
+  if (run == null) {
+    // No readable claim, so nothing here is in use. The run file goes with
+    // the socket: leaving an unreadable one behind made `claimRunFile` fail
+    // EEXIST forever and wedged the profile until someone deleted the
+    // directory by hand.
+    for (const file of [socketPathFor(profile), runFilePath(profile)]) {
+      try {
+        fs.unlinkSync(file)
+      } catch {
+        // ignore
+      }
+    }
+    return null
+  }
+  // `isProcessAlive` alone is not enough. It is `process.kill(pid, 0)`, so a
+  // run file left behind by a SIGKILLed engine whose pid the OS has since
+  // recycled looks live for ever: the engine prints "already running" and
+  // exits 1 on every invocation, `sweepStaleProfiles` skips the directory
+  // for the same reason, and the only recovery is deleting it by hand — the
+  // exact wedge this function exists to prevent. So the claim also has to be
+  // backed by something actually listening on the socket it names.
+  if (isProcessAlive(run.pid)) {
+    if (await isEngineListening(run.socketPath ?? socketPathFor(profile))) {
+      return run.pid
+    }
+    // Nothing listening yet is not the same as nothing coming. The claim is
+    // written before `makeCoreContext`, which opens the on-disk repos and
+    // starts every plugin, and the socket is not bound until seconds later —
+    // so for that whole window a live, *booting* engine reads exactly like a
+    // dead one. Sweeping it let a second cold invocation claim the same
+    // profile and open a second EdgeContext on one directory, which is the
+    // corruption the claim ordering exists to prevent. This is the reasoning
+    // `sweepStaleProfiles` already applies to its own `run == null` arm.
+    if (claimedWithin(profile, run, BOOT_GRACE_MS)) return run.pid
+  }
+  // A dead engine's artifacts go, but not the startup log: a client spawning
+  // the replacement has already opened it, and it is where a boot failure is
+  // recorded.
+  removeRunArtifacts(profile, { keepStartupLog: true })
+  return null
+}
+
+/**
+ * Whether anything answers on a unix socket path.
+ *
+ * A connect, not a request: this runs before the engine has a client and
+ * only needs to know whether the previous owner is still there. A socket
+ * *file* proves nothing, because a SIGKILLed engine leaves one behind.
+ */
+export async function isEngineListening(socketPath: string): Promise<boolean> {
+  return await new Promise<boolean>(resolve => {
+    let settled = false
+    const done = (answer: boolean): void => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      resolve(answer)
+    }
+    const socket = net.connect(socketPath)
+    socket.setTimeout(LISTEN_PROBE_MS)
+    socket.once('connect', () => {
+      done(true)
+    })
+    socket.once('error', () => {
+      done(false)
+    })
+    socket.once('timeout', () => {
+      done(false)
+    })
+  })
+}
+
+/**
+ * Clear out profile directories no engine owns any more.
+ *
+ * `cleanupStaleLock` only ever looks at the profile being started, so a
+ * profile nothing revisits keeps its artifacts forever: every interrupted run
+ * orphans one, and because `testCliFake` derives its data directory from the
+ * pid, every run has a fresh hash. Those directories accumulate
+ * indefinitely, each one possibly still holding a `session.json` — the
+ * engine's bearer token — which directly contradicts this module's own
+ * comments.
+ *
+ * Swept at engine startup. A directory whose run file names a live process is
+ * left alone, as is one belonging to the profile starting up, and as is one
+ * young enough to be mid-boot.
+ */
+export function sweepStaleProfiles(except: string): number {
+  let profiles: string[]
+  try {
+    profiles = fs.readdirSync(runRoot())
+  } catch {
+    return 0
+  }
+  let removed = 0
+  const now = Date.now()
+  for (const profile of profiles) {
+    if (profile === except) continue
+    let newestMtime: number
+    try {
+      const dir = runDir(profile)
+      if (!fs.statSync(dir).isDirectory()) continue
+      newestMtime = newestMtimeIn(dir)
+    } catch {
+      continue
+    }
+    // A profile that is *starting* looks exactly like an abandoned one: the
+    // client creates the run directory and `engine-startup.log` before it
+    // spawns, and the engine does not write `engine.json` until
+    // `claimRunFile`, a whole Node startup later. Another engine booting in
+    // that window read "no run file" as "abandoned" and deleted the socket,
+    // the session file and the very startup log the spawning client was
+    // about to read — so a failed spawn reported "No engine output" and
+    // pointed at a file that had just been removed.
+    const run = readRunFile(profile)
+    if (run == null && now - newestMtime < BOOT_GRACE_MS) continue
+    if (run != null && isProcessAlive(run.pid)) continue
+    // No live owner, so nothing here can be in use. The startup log is kept:
+    // it is the only record of a boot that died before the socket existed,
+    // and the cost of keeping one stale file is a few hundred bytes.
+    removeRunArtifacts(profile, { keepStartupLog: true })
+    removed++
+  }
+  return removed
+}
+
+/** The most recent mtime of a directory's own entries, or 0. */
+function newestMtimeIn(dir: string): number {
+  let newest = 0
+  try {
+    newest = fs.statSync(dir).mtimeMs
+  } catch {
+    return 0
+  }
+  let names: string[]
+  try {
+    names = fs.readdirSync(dir)
+  } catch {
+    return newest
+  }
+  for (const name of names) {
+    try {
+      const { mtimeMs } = fs.statSync(join(dir, name))
+      if (mtimeMs > newest) newest = mtimeMs
+    } catch {
+      // Gone between the listing and the stat.
+    }
+  }
+  return newest
+}
diff --git a/src/cli/engine/doc.ts b/src/cli/engine/doc.ts
new file mode 100644
index 00000000000..f297667f268
--- /dev/null
+++ b/src/cli/engine/doc.ts
@@ -0,0 +1,37 @@
+/**
+ * Attaches prose to a cleaner.
+ *
+ * `doc(asString, 'The name to normalize.')` returns the same cleaner, so it is
+ * invisible at runtime and safe to wrap anything. The documentation build
+ * reads these calls out of the source, which means a field's description sits
+ * against the field itself rather than in a separate tag that has to repeat
+ * its name to find it.
+ *
+ * It works on a whole cleaner too, for responses the engine passes straight
+ * through from core:
+ *
+ *     returns: doc(asCoreValue, 'EdgeLoginMessages, keyed by loginId.')
+ */
+import type { Cleaner } from 'cleaners'
+
+export function doc<T>(cleaner: Cleaner<T>, _prose: string): Cleaner<T> {
+  return cleaner
+}
+
+/**
+ * Path parameters carry scope, and mean the same thing on every route that
+ * takes them, so they are described once here rather than per route.
+ *
+ * Every one of these is base58, which is the rule for a path parameter: no
+ * `/`, `?` or `#`, so it survives a URL without percent-encoding. Anything
+ * else — a base64 wallet id, a free-text username — travels in the query or
+ * the body instead.
+ */
+export const SCOPE_PARAMS: Record<string, string> = {
+  sessionId:
+    'From a successful login. The CLI supplies this from `session.json`, `--session`, or `EDGE_CLI_SESSION`.',
+  objectId: 'An ephemeral object handle id.',
+  pendingId: 'The `pendingId` returned when the QR login was requested.',
+  lobbyId: 'The lobby to act on.',
+  syncKey: 'Base58 sync key for the repo.'
+}
diff --git a/src/cli/engine/errorGroups.ts b/src/cli/engine/errorGroups.ts
new file mode 100644
index 00000000000..f5dfaa3b93b
--- /dev/null
+++ b/src/cli/engine/errorGroups.ts
@@ -0,0 +1,27 @@
+/**
+ * Error codes that recur across routes, declared once.
+ *
+ * `docs/api/README.md` tells every future contributor to reuse these rather
+ * than restating them, and the branch that shipped that advice followed it
+ * nowhere: `SESSION_ERRORS` had no consumer at all and `WALLET_ERRORS` was
+ * re-declared byte-identically in two route files. They live here, in runtime
+ * code, so the routes can import them and the docs can re-export them —
+ * routes importing from `docs/` would have the dependency backwards.
+ *
+ * No imports, so nothing is dragged in by using them.
+ */
+
+/** Errors possible on any session-scoped route. */
+export const SESSION_ERRORS = ['INVALID_SESSION', 'SESSION_EXPIRED']
+
+/** Errors possible on any route that names a wallet. */
+export const WALLET_ERRORS = ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID']
+
+/** Errors possible on any route that takes an object handle. */
+export const HANDLE_ERRORS = [
+  'OBJECT_NOT_FOUND',
+  'OBJECT_EXPIRED',
+  'OBJECT_KIND_MISMATCH',
+  'OBJECT_WALLET_MISMATCH',
+  'OBJECT_SESSION_MISMATCH'
+]
diff --git a/src/cli/engine/errors.ts b/src/cli/engine/errors.ts
new file mode 100644
index 00000000000..840304e87d0
--- /dev/null
+++ b/src/cli/engine/errors.ts
@@ -0,0 +1,343 @@
+/**
+ * The engine's error contract, in one place.
+ *
+ * Three jobs. `EngineError` and `engineError()` are what a route throws when
+ * the fault is the caller's. `mapCoreError` turns an `edge-core-js` error
+ * type into the published code, status and `details` for it — a table, so an
+ * arm cannot be the only place a code appears. And `toErrorBody` is the sink
+ * every failure passes through on its way to the wire.
+ *
+ * Every code here must be in the catalogue in `docs/api/shared.ts`, which
+ * `npm run docs:api:verify` enforces: a code the engine can emit and the
+ * reference cannot describe is a contract a caller cannot program against.
+ */
+import {
+  asMaybeChallengeError,
+  asMaybeDustSpendError,
+  asMaybeInsufficientFundsError,
+  asMaybeNetworkError,
+  asMaybeNoAmountSpecifiedError,
+  asMaybeObsoleteApiError,
+  asMaybeOtpError,
+  asMaybePasswordError,
+  asMaybePendingFundsError,
+  asMaybePinDisabledError,
+  asMaybeSameCurrencyError,
+  asMaybeSpendToSelfError,
+  asMaybeSwapAboveLimitError,
+  asMaybeSwapAddressError,
+  asMaybeSwapBelowLimitError,
+  asMaybeSwapCurrencyError,
+  asMaybeSwapPermissionError,
+  asMaybeUsernameError
+} from 'edge-core-js'
+
+export class EngineError extends Error {
+  code: string
+  status: number
+  details?: Record<string, unknown>
+
+  constructor(
+    code: string,
+    message: string,
+    status: number,
+    details?: Record<string, unknown>
+  ) {
+    super(message)
+    this.name = 'EngineError'
+    this.code = code
+    this.status = status
+    this.details = details
+  }
+}
+
+export function engineError(
+  code: string,
+  message: string,
+  status: number,
+  details?: Record<string, unknown>
+): EngineError {
+  return new EngineError(code, message, status, details)
+}
+
+/**
+ * The response every failure becomes.
+ *
+ * Named once. The `{ status, body: { error: { code, message, status,
+ * details? } } }` shape was spelled out verbatim three times in this file and
+ * again in the client's `output.ts`.
+ */
+export interface ErrorResponse {
+  status: number
+  body: {
+    error: {
+      code: string
+      message: string
+      status: number
+      details?: Record<string, unknown>
+    }
+  }
+}
+
+/**
+ * A message the caller can act on.
+ *
+ * Every arm below copies core's own `message`, which is the right default —
+ * it is written for a person. But most of core's error constructors take the
+ * message as an argument, so an empty one reaches here, and a body of
+ * `{"code":"PIN_DISABLED","message":""}` tells a caller nothing the code did
+ * not already say.
+ */
+function messageOr(message: string, fallback: string): string {
+  return message.trim() === '' ? fallback : message
+}
+
+export function toErrorBody(error: unknown): ErrorResponse {
+  if (error instanceof EngineError) {
+    return {
+      status: error.status,
+      body: {
+        error: {
+          code: error.code,
+          message: error.message,
+          status: error.status,
+          details: error.details
+        }
+      }
+    }
+  }
+
+  const mapped = mapCoreError(error)
+  if (mapped != null) return mapped
+
+  const message = error instanceof Error ? error.message : String(error)
+  return {
+    status: 500,
+    body: {
+      error: {
+        code: 'INTERNAL_ERROR',
+        message,
+        status: 500
+      }
+    }
+  }
+}
+
+/**
+ * One core error type, and the response it becomes.
+ *
+ * A table rather than eighteen near-identical blocks. Each block wrote its
+ * status *twice* — once for the HTTP response and once inside the body — so
+ * half the file was a place for the two to disagree, and adding an arm meant
+ * copying thirty lines and changing four things in it.
+ */
+interface CoreErrorArm<T> {
+  /** The `asMaybe*` cleaner that recognises it. */
+  match: (error: unknown) => T | undefined
+  code: string
+  status: number
+  /** Used when core's own message is empty. */
+  fallback: string
+  /** The fields this code promises in `details`. */
+  details?: (error: T) => Record<string, unknown>
+  /** Only for a code whose message is assembled rather than copied. */
+  message?: (error: T) => string
+}
+
+/**
+ * Checked in order, so a more specific arm can precede a general one.
+ *
+ * `any` on the arm type: each `asMaybe*` returns its own core error shape and
+ * the table is heterogeneous by construction, which a single generic cannot
+ * express without a union of all eighteen.
+ */
+const CORE_ERROR_ARMS: Array<CoreErrorArm<any>> = [
+  {
+    match: asMaybeChallengeError,
+    code: 'CHALLENGE_REQUIRED',
+    status: 403,
+    fallback: 'Login requires a CAPTCHA challenge',
+    // Assembled, not copied: the id and the URI are what a caller needs to
+    // act on, and they are easy to miss in `details` alone.
+    message: error =>
+      [
+        messageOr(error.message, 'Login requires a CAPTCHA challenge'),
+        error.challengeId != null ? `challengeId=${error.challengeId}` : null,
+        error.challengeUri != null
+          ? `challengeUri=${error.challengeUri}`
+          : null,
+        'Retry the same request with body/query challengeId after solving, or use CLI --solve-captcha.'
+      ]
+        .filter((part): part is string => part != null && part !== '')
+        .join(' '),
+    details: error => ({
+      challengeId: error.challengeId,
+      challengeUri: error.challengeUri
+    })
+  },
+  {
+    match: asMaybePasswordError,
+    code: 'PASSWORD_ERROR',
+    status: 401,
+    fallback: 'Invalid password',
+    details: error => ({ wait: error.wait })
+  },
+  {
+    match: asMaybeOtpError,
+    code: 'OTP_REQUIRED',
+    status: 401,
+    fallback: 'Invalid OTP token',
+    details: error => ({
+      reason: error.reason,
+      loginId: error.loginId,
+      resetDate: error.resetDate?.toISOString(),
+      resetToken: error.resetToken,
+      voucherId: error.voucherId,
+      voucherAuth: error.voucherAuth,
+      voucherActivates: error.voucherActivates?.toISOString()
+    })
+  },
+  {
+    match: asMaybeUsernameError,
+    code: 'USERNAME_ERROR',
+    status: 400,
+    fallback: 'Invalid username'
+  },
+  {
+    match: asMaybePinDisabledError,
+    code: 'PIN_DISABLED',
+    status: 403,
+    fallback: 'PIN login is disabled for this account'
+  },
+  {
+    match: asMaybeInsufficientFundsError,
+    code: 'INSUFFICIENT_FUNDS',
+    status: 422,
+    fallback: 'Insufficient funds',
+    details: error => ({
+      tokenId: error.tokenId,
+      networkFee: error.networkFee
+    })
+  },
+  {
+    match: asMaybeDustSpendError,
+    code: 'DUST_SPEND',
+    status: 422,
+    fallback: 'Amount is below the dust threshold'
+  },
+  {
+    match: asMaybePendingFundsError,
+    code: 'PENDING_FUNDS',
+    status: 422,
+    fallback: 'Funds are still pending'
+  },
+  {
+    match: asMaybeSpendToSelfError,
+    code: 'SPEND_TO_SELF',
+    status: 422,
+    fallback: 'Cannot send to the sending wallet'
+  },
+  {
+    match: asMaybeNoAmountSpecifiedError,
+    code: 'NO_AMOUNT_SPECIFIED',
+    status: 400,
+    fallback: 'No amount specified'
+  },
+  {
+    match: asMaybeNetworkError,
+    code: 'NETWORK_ERROR',
+    status: 503,
+    fallback: 'Network request failed'
+  },
+  {
+    match: asMaybeObsoleteApiError,
+    code: 'OBSOLETE_API',
+    status: 426,
+    fallback: 'This API version is no longer supported'
+  },
+  {
+    match: asMaybeSwapAboveLimitError,
+    code: 'SWAP_ABOVE_LIMIT',
+    status: 422,
+    fallback: 'Amount is above the exchange maximum',
+    details: error => ({
+      swapPluginId: error.swapPluginId,
+      nativeMax: error.nativeMax,
+      direction: error.direction
+    })
+  },
+  {
+    match: asMaybeSwapBelowLimitError,
+    code: 'SWAP_BELOW_LIMIT',
+    status: 422,
+    fallback: 'Amount is below the exchange minimum',
+    details: error => ({
+      swapPluginId: error.swapPluginId,
+      nativeMin: error.nativeMin,
+      direction: error.direction
+    })
+  },
+  {
+    match: asMaybeSwapCurrencyError,
+    code: 'SWAP_CURRENCY',
+    status: 422,
+    fallback: 'The exchange does not support this currency pair',
+    details: error => ({
+      pluginId: error.pluginId,
+      fromTokenId: error.fromTokenId,
+      toTokenId: error.toTokenId
+    })
+  },
+  {
+    match: asMaybeSwapPermissionError,
+    code: 'SWAP_PERMISSION',
+    status: 403,
+    fallback: 'The exchange refused this request',
+    details: error => ({ pluginId: error.pluginId, reason: error.reason })
+  },
+  {
+    match: asMaybeSwapAddressError,
+    code: 'SWAP_ADDRESS',
+    status: 422,
+    fallback: 'The exchange refused this address',
+    details: error => ({
+      swapPluginId: error.swapPluginId,
+      reason: error.reason
+    })
+  },
+  {
+    match: asMaybeSameCurrencyError,
+    code: 'SAME_CURRENCY',
+    status: 400,
+    fallback: 'Cannot exchange a currency for itself'
+  }
+]
+
+function mapCoreError(error: unknown): ErrorResponse | undefined {
+  for (const arm of CORE_ERROR_ARMS) {
+    const matched = arm.match(error)
+    if (matched == null) continue
+    // An all-undefined projection is omitted, not sent as `{}`: several arms
+    // promise fields core may not have set, and `details: {}` tells a caller
+    // there is detail when there is none.
+    const projected = arm.details?.(matched)
+    const details =
+      projected != null &&
+      Object.values(projected).some(value => value !== undefined)
+        ? projected
+        : undefined
+    return {
+      status: arm.status,
+      body: {
+        error: {
+          code: arm.code,
+          message:
+            arm.message?.(matched) ?? messageOr(matched.message, arm.fallback),
+          status: arm.status,
+          ...(details != null ? { details } : {})
+        }
+      }
+    }
+  }
+  return undefined
+}
diff --git a/src/cli/engine/events.ts b/src/cli/engine/events.ts
new file mode 100644
index 00000000000..b26bdb02610
--- /dev/null
+++ b/src/cli/engine/events.ts
@@ -0,0 +1,256 @@
+import type { ServerResponse } from 'http'
+
+import { API_VERSION } from './apiVersion'
+import { stringifyJson } from './json'
+import { redactSessionId } from './sessions'
+
+type Listener = (event: string, data: unknown) => void
+
+/**
+ * Drop an SSE client once this much data is queued for it. A subscriber that
+ * stops reading would otherwise grow the engine's heap without bound.
+ */
+const MAX_SSE_BUFFER_BYTES = 1024 * 1024
+
+/**
+ * What a subscription depends on, which decides when it has to die.
+ *
+ * The `EdgeContext` outlives every account, so `context` streams survive
+ * logout. Anything reading an account or a wallet cannot outlive the session
+ * that owns it, and is torn down when that session goes away.
+ */
+export type SubscriptionScope =
+  | { kind: 'context' }
+  | { kind: 'session'; sessionId: string }
+  | { kind: 'wallet'; sessionId: string; walletId: string }
+
+interface SseClient {
+  res: ServerResponse
+  scope: SubscriptionScope
+  /**
+   * Event types this client asked for, or undefined for all of them.
+   *
+   * Filtering client-side only meant a caller who wanted one event type
+   * still received the whole `core.log` firehose over the socket and threw
+   * it away — and `write` destroys any client more than
+   * MAX_SSE_BUFFER_BYTES behind, so a slow consumer was dropped for volume
+   * it had explicitly asked not to receive.
+   */
+  types?: Set<string>
+}
+
+/** Simple SSE hub. Clients connect via GET /engine/events. */
+export class EventHub {
+  private readonly listeners = new Set<Listener>()
+  private readonly clients = new Set<SseClient>()
+
+  /**
+   * Notified whenever a subscriber attaches or detaches, so the idle timer can
+   * re-arm once the last one leaves.
+   */
+  onClientsChanged: (() => void) | null = null
+
+  /** Live subscriber count. The idle timer holds off while this is non-zero. */
+  get clientCount(): number {
+    return this.clients.size
+  }
+
+  private clientsChanged(): void {
+    try {
+      this.onClientsChanged?.()
+    } catch {
+      // A listener must never break subscribe or logout.
+    }
+  }
+
+  /**
+   * Write one already-serialised frame to one client.
+   *
+   * The frame arrives built, because `emit` builds it once: serialising
+   * inside here meant N subscribers serialised the identical payload N
+   * times. The per-client `types` test stays here, before the write, which
+   * is the whole point of filtering at the transport.
+   */
+  private write(client: SseClient, event: string, frame: string): boolean {
+    const { res } = client
+    if (res.writableEnded || res.destroyed) return false
+    // `subscription.closed` always goes through: a client that filtered it
+    // out would never learn why its stream ended.
+    if (
+      client.types != null &&
+      !client.types.has(event) &&
+      event !== 'subscription.closed'
+    ) {
+      return true
+    }
+    if (res.writableLength > MAX_SSE_BUFFER_BYTES) {
+      res.destroy()
+      return false
+    }
+
+    try {
+      res.write(frame)
+      return true
+    } catch {
+      // Cannot write to *this socket*: the client really is gone.
+      return false
+    }
+  }
+
+  /**
+   * One SSE frame, or null when the payload cannot be serialised.
+   *
+   * `stringifyJson`, not bare `JSON.stringify`: it is the encoding every
+   * REST response uses, so a `Uint8Array` is base64 and a `Map` is an object
+   * on both transports. No frame carries either today, which is why this was
+   * invisible — the next one would have serialised a Uint8Array as
+   * {"0":1,…} on the stream and base64 over REST.
+   */
+  private buildFrame(event: string, data: unknown): string | null {
+    try {
+      return `event: ${event}\ndata: ${stringifyJson(data)}\n\n`
+    } catch (error: unknown) {
+      // Cannot serialise *this event*. Every client is fine, and dropping
+      // them here disconnected every subscriber over one bad payload.
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(`[edge-engine] cannot serialise event ${event}: ${message}`)
+      return null
+    }
+  }
+
+  emit(event: string, data: unknown, scope?: SubscriptionScope): void {
+    // Nothing is listening, so nothing below can have an effect. `core.log`
+    // is a firehose — around 8 MB an hour — and every one of those used to
+    // pay an array allocation for the client spread and an object literal
+    // for the payload with zero listeners and zero clients.
+    if (this.listeners.size === 0 && this.clients.size === 0) return
+
+    for (const listener of this.listeners) {
+      try {
+        listener(event, data)
+      } catch {
+        // ignore
+      }
+    }
+    if (this.clients.size === 0) return
+
+    const frame = this.buildFrame(event, data)
+    if (frame == null) return
+
+    for (const client of [...this.clients]) {
+      if (scope != null && !scopeMatches(client.scope, scope)) continue
+      if (!this.write(client, event, frame)) {
+        this.clients.delete(client)
+        this.clientsChanged()
+      }
+    }
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  addSseClient(
+    res: ServerResponse,
+    scope: SubscriptionScope = { kind: 'context' },
+    types?: Set<string>
+  ): void {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'X-Edge-Api-Version': API_VERSION
+    })
+    res.write(': ok\n\n')
+    const client: SseClient = { res, scope, types }
+    this.clients.add(client)
+    this.clientsChanged()
+    res.on('close', () => {
+      if (this.clients.delete(client)) this.clientsChanged()
+    })
+  }
+
+  /**
+   * Keep each stream warm, and notice a subscriber that vanished.
+   *
+   * A stream is written to only when an event fires, and liveness was
+   * detected solely through `res.on('close')` — which a clean FIN produces
+   * and a sleeping laptop, a killed container or a dropped link do not. Such
+   * a client was never reaped: `clientCount` stayed non-zero, so
+   * `heldByClients` stayed true and the daemon held its `EdgeContext` and
+   * every plugin's polling open indefinitely. A comment frame costs nothing
+   * and surfaces the write failure, which the drop path below already
+   * handles.
+   */
+  pingClients(): void {
+    for (const client of [...this.clients]) {
+      const { res } = client
+      let alive = !res.writableEnded && !res.destroyed
+      if (alive) {
+        try {
+          res.write(': ping\n\n')
+        } catch {
+          alive = false
+        }
+      }
+      if (!alive) {
+        if (this.clients.delete(client)) this.clientsChanged()
+      }
+    }
+  }
+
+  /**
+   * End every subscription that depends on this session, so an auto-logout
+   * cannot leave a stream reading an account that no longer exists. Context
+   * subscriptions are untouched.
+   */
+  closeScope(sessionId: string, reason: string): void {
+    const frame = this.buildFrame('subscription.closed', {
+      reason,
+      sessionId: redactSessionId(sessionId)
+    })
+    if (frame == null) return
+    for (const client of [...this.clients]) {
+      if (client.scope.kind === 'context') continue
+      if (client.scope.sessionId !== sessionId) continue
+      this.write(client, 'subscription.closed', frame)
+      this.clients.delete(client)
+      try {
+        client.res.end()
+      } catch {
+        // best effort
+      }
+      this.clientsChanged()
+    }
+  }
+
+  closeAll(reason: string): void {
+    const frame = this.buildFrame('subscription.closed', { reason })
+    if (frame == null) return
+    for (const client of [...this.clients]) {
+      this.write(client, 'subscription.closed', frame)
+      this.clients.delete(client)
+      try {
+        client.res.end()
+      } catch {
+        // best effort
+      }
+    }
+    this.clientsChanged()
+  }
+}
+
+/** A client receives an event when its scope is the event's scope or broader. */
+function scopeMatches(
+  client: SubscriptionScope,
+  event: SubscriptionScope
+): boolean {
+  if (client.kind === 'context') return true
+  if (event.kind === 'context') return false
+  if (client.sessionId !== event.sessionId) return false
+  if (client.kind === 'session') return true
+  return event.kind === 'wallet' && client.walletId === event.walletId
+}
diff --git a/src/cli/engine/fetchPluginKeys.ts b/src/cli/engine/fetchPluginKeys.ts
new file mode 100644
index 00000000000..6ea05c8cf9d
--- /dev/null
+++ b/src/cli/engine/fetchPluginKeys.ts
@@ -0,0 +1,110 @@
+/**
+ * Fetch plugin secrets from the info server signed infoRollup (`appKeys`)
+ * the same way the GUI `keysStore` does, using the Node native HMAC addon
+ * when available.
+ */
+import { asMaybe } from 'cleaners'
+import type { EdgeApiSigner } from 'edge-core-js'
+import { asInfoRollup } from 'edge-info-server'
+import os from 'os'
+
+import { version as APP_VERSION } from '../../../package.json'
+import { fetchRemoteKeys } from '../../util/keysServer'
+import {
+  configureNetwork,
+  DEFAULT_INFO_SERVERS,
+  infoServerData
+} from '../../util/network'
+import { isPlainObject } from '../../util/predicates'
+import { TESTER_SERVERS } from './testerServers'
+
+export interface FetchPluginKeysOpts {
+  apiSigner?: EdgeApiSigner
+  apiKey?: string
+  apiSecret?: Uint8Array
+  appId: string
+  testMode: boolean
+}
+
+export interface FetchedPluginKeys {
+  pluginApiKeys: Record<string, unknown>
+  assuranceLevel?: string
+}
+
+/**
+ * HMAC appKeys is a keys.json overlay (`corePlugins` / `swapPlugins`).
+ * Older getKeys payloads used a top-level `pluginApiKeys` map.
+ */
+function pluginApiKeysFromRemote(keys: unknown): Record<string, unknown> {
+  if (!isPlainObject(keys)) return {}
+  const core = isPlainObject(keys.corePlugins) ? keys.corePlugins : {}
+  const swap = isPlainObject(keys.swapPlugins) ? keys.swapPlugins : {}
+  const legacy = isPlainObject(keys.pluginApiKeys) ? keys.pluginApiKeys : {}
+  return { ...legacy, ...swap, ...core }
+}
+
+/**
+ * GUI infoRollup uses theme `config.appId ?? 'edge'`. The CLI core context
+ * often boots with an empty appId; the info server still expects the Edge slug.
+ */
+export function getKeysAppId(cliAppId: string): string {
+  return cliAppId === '' ? 'edge' : cliAppId
+}
+
+function rememberPublicRollup(rollup: unknown): void {
+  if (infoServerData.rollup != null) return
+  const cleaned = asMaybe(asInfoRollup)(rollup)
+  if (cleaned != null) infoServerData.rollup = cleaned
+}
+
+function cliOsParams(): {
+  os: 'ios' | 'android'
+  osVersion: string
+  appVersion: string
+} {
+  // infoRollup's HMAC cleaner only accepts the GUI's two OS tags.
+  // Map Node platforms onto those: darwin matches iOS; everything else Android.
+  return {
+    os: os.platform() === 'darwin' ? 'ios' : 'android',
+    osVersion: `${os.platform()}-${os.release()}`,
+    appVersion: APP_VERSION
+  }
+}
+
+export async function fetchPluginKeys(
+  opts: FetchPluginKeysOpts
+): Promise<FetchedPluginKeys> {
+  const infoServers = opts.testMode
+    ? [TESTER_SERVERS.infoServer]
+    : DEFAULT_INFO_SERVERS
+  configureNetwork({ infoServers })
+
+  const appId = getKeysAppId(opts.appId)
+  const osParams = cliOsParams()
+  if (opts.apiSigner != null) {
+    const result = await fetchRemoteKeys({
+      apiSigner: opts.apiSigner,
+      appId,
+      ...osParams
+    })
+    rememberPublicRollup(result.rollup)
+    return {
+      pluginApiKeys: pluginApiKeysFromRemote(result.keys),
+      assuranceLevel: result.assuranceLevel
+    }
+  }
+  if (opts.apiKey != null && opts.apiKey !== '' && opts.apiSecret != null) {
+    const result = await fetchRemoteKeys({
+      apiKey: opts.apiKey,
+      secret: opts.apiSecret,
+      appId,
+      ...osParams
+    })
+    rememberPublicRollup(result.rollup)
+    return {
+      pluginApiKeys: pluginApiKeysFromRemote(result.keys),
+      assuranceLevel: result.assuranceLevel
+    }
+  }
+  throw new Error('No HMAC credentials available for infoRollup appKeys')
+}
diff --git a/src/cli/engine/fieldDocs.ts b/src/cli/engine/fieldDocs.ts
new file mode 100644
index 00000000000..3699f5cb5cc
--- /dev/null
+++ b/src/cli/engine/fieldDocs.ts
@@ -0,0 +1,38 @@
+/**
+ * Field descriptions more than one route publishes.
+ *
+ * A `doc()` string is the published reference: it reaches the HTML, the
+ * OpenAPI document and `edge-cli help`. So the same field described in two
+ * places is the same hazard as two copies of a type — a reword in one gives
+ * a caller two different descriptions of one field, and nothing fails when
+ * they disagree, because `checkRouteContracts` only asserts that a
+ * description *exists*.
+ *
+ * `'Defaults to the native asset.'` was written out twelve times across six
+ * route files, with one of them already extracted locally as `TOKEN_ID_DOC`.
+ *
+ * No imports, so any route file can use it.
+ */
+
+/** A request-position `tokenId`, which is optional on every route. */
+export const TOKEN_ID_DOC = 'Defaults to the native asset.'
+
+/** The `walletId` every wallet route takes. */
+export const WALLET_ID_DOC = 'The wallet to act on. Accepts a unique id prefix.'
+
+/** A spend's destination, in the convenience shorthand. */
+export const SPEND_TO_DOC =
+  'Address or BIP21 URI, run through `wallet.parseUri`.'
+
+/** How much to send, in the convenience shorthand. */
+export const SPEND_AMOUNT_DOC = 'How much, in native units.'
+
+/** The alias the `to` shorthand accepts for `nativeAmount`. */
+export const SPEND_AMOUNT_ALIAS_DOC = 'Alias of `nativeAmount`.'
+
+/** Metadata supplied with a spend, against whatever the URI carried. */
+export const SPEND_METADATA_DOC = 'Wins over anything parsed out of the URI.'
+
+/** An object handle's id, as every handle-advancing route takes it. */
+export const OBJECT_ID_DOC =
+  'The handle from the step before. It expires five minutes after it was created.'
diff --git a/src/cli/engine/idleShutdown.ts b/src/cli/engine/idleShutdown.ts
new file mode 100644
index 00000000000..e3a5fce8832
--- /dev/null
+++ b/src/cli/engine/idleShutdown.ts
@@ -0,0 +1,172 @@
+/**
+ * Engine self-shutdown once nothing is holding it open.
+ *
+ * Four things hold it: a logged-in session, a live subscription, a request
+ * being served, and an object handle that belongs to no session. Default:
+ * 300 seconds (5 minutes). Set 0 to disable.
+ *
+ * A subscription holds the engine open even with no account logged in — the
+ * stream would otherwise die under the subscriber. An in-flight request does
+ * too, which is what `beginRequest` exists for: a cold login or a
+ * `resync-blockchain` can outlive the window. A sessionless handle is the
+ * pending edge login, whose own TTL equals the default timeout. The account
+ * auto-logout timer is separate and is *not* held off by any of them.
+ */
+export class IdleShutdown {
+  private idleTimeoutMs: number
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private lastActivityAt = Date.now()
+  private readonly onFire: () => void | Promise<void>
+  private readonly getSessionCount: () => number
+  private readonly getSubscriberCount: () => number
+  private readonly getSessionlessHandleCount: () => number
+  private shuttingDown = false
+
+  constructor(opts: {
+    idleTimeoutSeconds: number
+    getSessionCount: () => number
+    getSubscriberCount?: () => number
+    getSessionlessHandleCount?: () => number
+    onFire: () => void | Promise<void>
+  }) {
+    this.idleTimeoutMs = opts.idleTimeoutSeconds * 1000
+    this.getSessionCount = opts.getSessionCount
+    this.getSubscriberCount = opts.getSubscriberCount ?? (() => 0)
+    this.getSessionlessHandleCount = opts.getSessionlessHandleCount ?? (() => 0)
+    this.onFire = opts.onFire
+    this.reset()
+  }
+
+  /** Requests currently being served. */
+  private inFlight = 0
+
+  /**
+   * How many requests are being served right now.
+   *
+   * Shutdown reads this: the idle path already refuses to fire while a
+   * request is open, and `engine-stop` and SIGINT have to refuse too.
+   */
+  get requestsInFlight(): number {
+    return this.inFlight
+  }
+
+  /**
+   * True while a client is deliberately keeping the engine alive.
+   *
+   * Reported to callers, so it deliberately excludes in-flight requests: the
+   * request asking for the shutdown time is itself in flight, and by the time
+   * the answer is read it is not.
+   */
+  private get heldByClients(): boolean {
+    return (
+      this.getSessionCount() > 0 ||
+      this.getSubscriberCount() > 0 ||
+      // A pending edge login holds no session and its TTL equals the default
+      // idle timeout, so without this the engine shut down under a lobby the
+      // user was still showing a QR code for.
+      this.getSessionlessHandleCount() > 0
+    )
+  }
+
+  /** True while anything at all should keep the timer disarmed. */
+  private get held(): boolean {
+    return this.inFlight > 0 || this.heldByClients
+  }
+
+  /**
+   * Hold the engine open for the duration of one request.
+   *
+   * `touch` only records when a request *started*, so a call that outlives the
+   * idle timeout — a cold login, `wait-for-all-wallets`, `resync-blockchain` —
+   * could be shut down underneath itself, and the client saw a destroyed
+   * socket rather than a result or an error. Pre-login calls hold nothing
+   * else: there is no session or subscriber to keep the timer disarmed.
+   */
+  beginRequest(): void {
+    this.inFlight++
+    this.reset()
+  }
+
+  endRequest(): void {
+    if (this.inFlight > 0) this.inFlight--
+    this.lastActivityAt = Date.now()
+    this.reset()
+  }
+
+  get idleShutdownAt(): string | null {
+    if (this.idleTimeoutMs === 0) return null
+    if (this.heldByClients) return null
+    return new Date(this.lastActivityAt + this.idleTimeoutMs).toISOString()
+  }
+
+  touch(): void {
+    this.lastActivityAt = Date.now()
+    this.reset()
+  }
+
+  /**
+   * Re-evaluate the timer after a login or logout. Without this the engine
+   * disarms itself while an account is logged in and never re-arms when the
+   * last session goes away, so it would linger until the next request.
+   */
+  notifySessionsChanged(): void {
+    if (this.shuttingDown) return
+    this.touch()
+  }
+
+  /**
+   * Re-evaluate after a subscriber attaches or detaches. Without this the
+   * engine would stay disarmed after the last subscriber left.
+   */
+  notifySubscribersChanged(): void {
+    if (this.shuttingDown) return
+    this.touch()
+  }
+
+  /** Re-evaluate after a handle is created or released. */
+  notifyHandlesChanged(): void {
+    if (this.shuttingDown) return
+    this.touch()
+  }
+
+  setTimeoutSeconds(seconds: number): void {
+    this.idleTimeoutMs = seconds * 1000
+    this.reset()
+  }
+
+  stop(): void {
+    if (this.timer != null) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  private reset(): void {
+    this.stop()
+    if (this.idleTimeoutMs === 0) return
+    if (this.held) return
+    this.timer = setTimeout(() => {
+      this.fire().catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        console.warn(`[edge-engine] idle shutdown failed: ${message}`)
+      })
+    }, this.idleTimeoutMs)
+    this.timer.unref?.()
+  }
+
+  private async fire(): Promise<void> {
+    if (this.shuttingDown) return
+    if (this.held) {
+      this.reset()
+      return
+    }
+    this.shuttingDown = true
+    try {
+      await this.onFire()
+    } catch (error: unknown) {
+      this.shuttingDown = false
+      this.reset()
+      throw error
+    }
+  }
+}
diff --git a/src/cli/engine/index.ts b/src/cli/engine/index.ts
new file mode 100644
index 00000000000..8dcd629bf13
--- /dev/null
+++ b/src/cli/engine/index.ts
@@ -0,0 +1,700 @@
+/**
+ * Edge CLI engine daemon entry point.
+ *
+ * Usage:
+ *   node -r sucrase/register src/cli/engine/index.ts [options]
+ *   edge-engine -t --tcp=<port>
+ *
+ * Run `edge-engine --help` for the options. `printHelp` below is the one
+ * place they are written out as user-facing text: a copy here had already
+ * drifted from it ("after idle" against "when idle"), and a reader has no way
+ * to tell which of two lists is current.
+ */
+
+import '../bootEngineLocale'
+
+import fs from 'fs'
+
+import { clearRateCache, stopRateQueue } from '../../util/exchangeRates'
+import { renderFlagHelp } from '../flagTable'
+import { API_VERSION } from './apiVersion'
+import { defaultDirectory, loadConfig } from './cliConfig'
+import {
+  claimRunFile,
+  cleanupStaleLock,
+  ensureRunDir,
+  profileHash,
+  readRunFile,
+  removeRunArtifacts,
+  runFilePath,
+  socketPathFor,
+  sweepStaleProfiles,
+  writeRunFile
+} from './discovery'
+import { EventHub } from './events'
+import { IdleShutdown } from './idleShutdown'
+import { EngineLogger, sweepOldLogs } from './logger'
+import { makeCoreContext } from './makeCoreContext'
+import { ObjectHandleStore } from './objectHandles'
+import { type EngineState, Router } from './router'
+import { registerRoutes } from './routes'
+import { createRequestHandler, listenTcp, listenUnix } from './server'
+import { SessionStore } from './sessions'
+import { makeSweepTicker } from './sweepTicker'
+import { EXAMPLE_TCP_PORT, parseTcpPort } from './tcpPort'
+import { TESTER_SERVERS } from './testerServers'
+import {
+  allowedHostnamesFor,
+  makeTcpToken,
+  type TcpGuard
+} from './transportAuth'
+
+interface EngineArgs {
+  testMode: boolean
+  fake: boolean
+  directory?: string
+  appId?: string
+  apiKey?: string
+  locale?: string
+  tcpPort: number | null
+  tcpHost: string
+  idleTimeoutSeconds: number
+  configPath?: string
+  help: boolean
+}
+
+/** An inline `--flag=` value, refused when empty. */
+function requireNonEmpty(value: string, flag: string): string {
+  if (value === '') throw new EngineUsageError(`${flag} requires a value`)
+  return value
+}
+
+/**
+ * Refuse a TCP bind address that is not loopback.
+ *
+ * `--tcp` opens an authenticated port for local scripts, and every surface
+ * that describes it — the help text, `docs/EDGE_CLI.md`, the comment on the
+ * listener — says `127.0.0.1`. Binding elsewhere publishes
+ * `get-raw-private-key`, `get-pin` and `spend` to whatever network the host
+ * is on, which no token makes safe to offer by accident.
+ */
+function requireLoopback(host: string): string {
+  const loopback =
+    host === 'localhost' ||
+    host === '::1' ||
+    host === '[::1]' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
+  if (!loopback) {
+    throw new EngineUsageError(
+      `--tcp-host must be a loopback address (127.0.0.0/8, ::1 or localhost), not "${host}": the TCP transport is for local scripts`
+    )
+  }
+  return host
+}
+
+/**
+ * The `--idle-timeout` value, validated once for both spellings.
+ *
+ * It was written out twice in the same function with error text that
+ * disagreed, and neither copy refused an empty value: `Number('')` is `0`,
+ * which is documented as "never", so `--idle-timeout=` produced an immortal
+ * daemon holding an `EdgeContext` and a logged-in account open, silently.
+ */
+function parseIdleTimeout(raw: string | undefined): number {
+  if (raw == null || raw === '') {
+    throw new EngineUsageError(
+      '--idle-timeout requires a value in seconds, where 0 means never'
+    )
+  }
+  const seconds = Number(raw)
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new EngineUsageError(`Invalid --idle-timeout: ${raw}`)
+  }
+  return seconds
+}
+
+/**
+ * The profile this process has claimed, once it has one.
+ *
+ * Module scope because `main().catch` runs outside `main`'s own scope and
+ * still has to clean up what the claim created.
+ */
+let claimedProfile: string | null = null
+/**
+ * Whether this process ever bound the unix socket.
+ *
+ * A startup that claimed the profile and then died has to clear it, but the
+ * socket and the user's `session.json` are only this process's to remove once
+ * it has actually served on them. The case that matters is losing the
+ * `listen` race: unlinking the winner's socket left it resident and
+ * unreachable, holding an EdgeContext and a logged-in account open.
+ */
+let boundSocket = false
+
+/**
+ * How long a shutdown waits for requests that have already started.
+ *
+ * Long enough for a broadcast to finish saving, short enough that a wedged
+ * request cannot keep the process alive. It is deliberately the same order
+ * as the client's own socket timeout: a bound shorter than that let the
+ * engine exit while the client was still waiting for an answer, which for a
+ * `spend` means the money has left and the caller is told nothing.
+ */
+const SHUTDOWN_DRAIN_MS = 110_000
+
+/** An env var that is set but blank is as good as unset. */
+function emptyToUndefined(value: string | undefined): string | undefined {
+  return value == null || value === '' ? undefined : value
+}
+
+/**
+ * Create the core data directory `0700`, and tighten it if it is laxer.
+ *
+ * `<directory>/logins/*.json` carry `pin2Key`, `otpKey` and the password and
+ * recovery boxes. Disklet's node backend writes them at the umask default,
+ * so without this they were `0644` inside a `0755` directory and any other
+ * local user could copy an account's stash and attack it offline. Every
+ * other root this CLI owns is already `0700`.
+ */
+function ensureDataDir(directory: string): void {
+  try {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  } catch {
+    // Already there, or unwritable — core will report the latter.
+  }
+  try {
+    fs.chmodSync(directory, 0o700)
+  } catch {
+    // Not ours to tighten; core will fail if it cannot use it.
+  }
+}
+
+/** Bad argv for the engine: reported cleanly, not as a crash. */
+class EngineUsageError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'EngineUsageError'
+  }
+}
+
+/**
+ * The value after a flag, refused when it is missing or is itself a flag.
+ *
+ * `argv[++i]` took whatever came next, so `--directory` at the end of the line
+ * silently fell back to the default data directory, and
+ * `--directory --tcp=9312` created a directory named `--tcp=9312` and dropped
+ * the TCP flag.
+ */
+function flagValue(argv: string[], i: number, flag: string): string {
+  const value = argv[i]
+  if (value == null || value === '' || value.startsWith('-')) {
+    throw new EngineUsageError(`${flag} requires a value`)
+  }
+  return value
+}
+
+function parseArgs(argv: string[]): EngineArgs {
+  const args: EngineArgs = {
+    testMode: false,
+    fake: false,
+    tcpPort: null,
+    tcpHost: '127.0.0.1',
+    idleTimeoutSeconds: 300,
+    help: false
+  }
+
+  /**
+   * The value of one valued flag, whichever spelling was used.
+   *
+   * Every valued flag used to be written twice — once for `--flag value`
+   * through `flagValue`, once for `--flag=value` through `requireNonEmpty` —
+   * so six flags took thirteen arms, and the two paths' error text had
+   * already drifted. One arm each now, and `i` advances through the closure
+   * because the space form consumes the next token.
+   */
+  let i = 0
+  const valueOf = (long: string, short?: string): string | undefined => {
+    const a = argv[i]
+    if (a === long || (short != null && a === short)) {
+      return flagValue(argv, ++i, a)
+    }
+    if (a.startsWith(`${long}=`)) {
+      return requireNonEmpty(a.slice(long.length + 1), long)
+    }
+    return undefined
+  }
+
+  for (i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const directory = valueOf('--directory', '-d')
+    const appId = valueOf('--app-id', '-a')
+    const apiKey = valueOf('--api-key', '-k')
+    const locale = valueOf('--locale')
+    const configPath = valueOf('--config', '-c')
+    if (directory != null) {
+      args.directory = directory
+    } else if (appId != null) {
+      args.appId = appId
+    } else if (apiKey != null) {
+      args.apiKey = apiKey
+    } else if (locale != null) {
+      args.locale = locale
+    } else if (configPath != null) {
+      args.configPath = configPath
+    } else if (a === '-h' || a === '--help') {
+      args.help = true
+    } else if (a === '-t' || a === '--test') {
+      args.testMode = true
+    } else if (a === '--fake') {
+      args.fake = true
+    } else if (a === '--tcp') {
+      throw new EngineUsageError(
+        `--tcp requires a port, e.g. --tcp=${EXAMPLE_TCP_PORT}`
+      )
+    } else if (a.startsWith('--tcp=')) {
+      // The same validator the client uses, so one spelling cannot be
+      // accepted here and refused there.
+      try {
+        args.tcpPort = parseTcpPort(a.slice('--tcp='.length))
+      } catch (error: unknown) {
+        throw new EngineUsageError(
+          error instanceof Error ? error.message : String(error)
+        )
+      }
+    } else if (a.startsWith('--tcp-host=')) {
+      // Node's `server.listen(port, '')` takes the falsy-host branch and
+      // binds the unspecified address, so `--tcp-host=` used to publish the
+      // engine on every interface. An explicit non-loopback address did the
+      // same thing and was the bigger hole: the help text, the guide and this
+      // code's own intent all say loopback, and an engine reachable from the
+      // LAN exposes `get-raw-private-key` and `spend` to it.
+      args.tcpHost = requireLoopback(
+        requireNonEmpty(a.slice('--tcp-host='.length), '--tcp-host')
+      )
+    } else if (a.startsWith('--idle-timeout=')) {
+      args.idleTimeoutSeconds = parseIdleTimeout(
+        a.slice('--idle-timeout='.length)
+      )
+    } else if (a === '--idle-timeout') {
+      args.idleTimeoutSeconds = parseIdleTimeout(argv[++i])
+    } else {
+      throw new EngineUsageError(`Unknown argument: ${a}`)
+    }
+  }
+  return args
+}
+
+function printHelp(): void {
+  console.log(`Usage: edge-engine [options]
+
+Options:
+${renderFlagHelp('engine')}
+`)
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    printHelp()
+    process.exit(0)
+  }
+
+  const fileConfig = loadConfig(args.configPath)
+  const appId = args.appId ?? fileConfig.appId ?? ''
+  const directory =
+    args.directory ??
+    fileConfig.directory ??
+    fileConfig.workingDir ??
+    defaultDirectory()
+  const testMode = args.testMode || fileConfig.testMode === true
+  // Two distinct things, deliberately. An *explicit* key — `-k`, or
+  // `EDGE_CLI_API_KEY` which is how the client forwards one without putting
+  // a credential on a command line `ps` shows to every user — is an
+  // operator override: `makeCoreContext` drops the keys.json secret and
+  // skips the native HMAC signer for it, which is what the guide documents.
+  // A key that merely sits in the config file is not an override, and
+  // conflating them turned off request signing for anyone who put `apiKey`
+  // in `edge-cli.conf`.
+  const explicitApiKey =
+    args.apiKey ?? emptyToUndefined(process.env.EDGE_CLI_API_KEY)
+  const configApiKey = fileConfig.apiKey
+
+  const events = new EventHub()
+  const sessions = new SessionStore(events)
+  const objects = new ObjectHandleStore()
+  // Peers: a logout releases the handles that session owned, so they cannot
+  // outlive the account they belong to.
+  sessions.objects = objects
+
+  // The fake world is its own profile, so a fake engine never answers on the
+  // socket a real one is using, or vice versa.
+  const profile = profileHash({
+    appId,
+    directory,
+    testMode,
+    loginServer: args.fake
+      ? 'fake://login'
+      : testMode
+      ? TESTER_SERVERS.loginServer
+      : undefined
+  })
+  const logger = new EngineLogger(profile)
+  logger.info('Engine starting', {
+    pid: process.pid,
+    appId,
+    directory,
+    testMode,
+    locale: args.locale
+  })
+
+  // Claim the profile before touching the data directory. `makeCoreContext`
+  // opens the on-disk repos and starts every plugin, so doing it first let two
+  // cold `edge-cli` invocations hold two EdgeContexts on one directory for
+  // seconds before either noticed the other — and, because the run file was
+  // not written until the listeners were up, the second engine's
+  // `cleanupStaleLock` would unlink the first engine's live socket.
+  ensureRunDir(profile)
+  // Housekeeping, before this engine adds to either pile. Both are bounded
+  // only by how many throwaway profiles a machine has ever used: 428 run
+  // directories and 612 log files had accumulated on one development
+  // machine, and 235 of those directories still held a session.json.
+  const staleProfiles = sweepStaleProfiles(profile)
+  // `logger.logPath` is this process's own file, which `unlinkSync` would
+  // happily remove on POSIX while the stream kept writing to the inode.
+  const staleLogs = sweepOldLogs(undefined, logger.logPath)
+  // From here on this process owns the profile directory, so a fatal startup
+  // has to clear it rather than leave a socket and run file that make the
+  // profile look live to the next client.
+  claimedProfile = profile
+  const livePid = await cleanupStaleLock(profile)
+  const socketPath = socketPathFor(profile)
+  const claimed =
+    livePid == null &&
+    claimRunFile(profile, {
+      pid: process.pid,
+      apiVersion: API_VERSION,
+      socketPath,
+      // Both filled in by the `writeRunFile` below, once the listeners are
+      // up and the core's effective `testMode` is known.
+      tcpPort: null,
+      tcpToken: undefined,
+      appId,
+      testMode,
+      startedAt: new Date().toISOString()
+    })
+  if (!claimed) {
+    const owner = livePid ?? readRunFile(profile)?.pid
+    console.error(
+      `[edge-engine] An engine is already running for profile ${profile}` +
+        (owner != null ? ` (pid ${owner})` : '') +
+        `.\nStop it first (edge-cli engine-stop) or use a different --directory/--app-id.`
+    )
+    process.exit(1)
+  }
+
+  // The core data directory holds the login stashes, so the engine creates
+  // it `0700` itself rather than leaving it to whoever spawned it: `npm run
+  // engine` and `node lib/edgeEngine.js` reach this with no client involved,
+  // and core's disklet then creates it at the umask default.
+  ensureDataDir(directory)
+
+  const core = await makeCoreContext({
+    apiKey: explicitApiKey,
+    configApiKey,
+    appId,
+    directory,
+    testMode,
+    fake: args.fake,
+    events,
+    logger
+  })
+
+  let shuttingDown = false
+  let unixServer: Awaited<ReturnType<typeof listenUnix>> | null = null
+  let tcpServer: Awaited<ReturnType<typeof listenTcp>>['server'] | null = null
+  let boundTcpPort: number | null = null
+  let tcpToken: string | null = null
+
+  /** Wait for in-flight requests to finish, up to SHUTDOWN_DRAIN_MS. */
+  const drainRequests = async (): Promise<void> => {
+    const deadline = Date.now() + SHUTDOWN_DRAIN_MS
+    while (idle.requestsInFlight > 0 && Date.now() < deadline) {
+      await new Promise<void>(resolve => setTimeout(resolve, 25))
+    }
+    const stuck = idle.requestsInFlight
+    if (stuck > 0) {
+      logger.warn(
+        `Shutting down with ${stuck} request(s) still in flight after ${SHUTDOWN_DRAIN_MS}ms`
+      )
+    }
+  }
+
+  /**
+   * The SSE keepalive ticker, which only exists once the routes are up.
+   *
+   * A `let` rather than the `const` further down, because `shutdown` closes
+   * over it and ran 154 lines earlier in the temporal dead zone: a teardown
+   * during the startup tail threw `Cannot access 'ssePing' before
+   * initialization`, and since `shutdown` sets `state.shuttingDown` as its
+   * second statement the daemon was left answering 503 for ever. The window
+   * is real — `--tcp-host=localhost` is not an IP literal, so binding does a
+   * `dns.lookup`, which yields to the event loop.
+   */
+  let ssePing: ReturnType<typeof makeSweepTicker> | null = null
+
+  /**
+   * Report a teardown that failed, and still let go of the profile.
+   *
+   * `shutdown()` sets `state.shuttingDown` as its second statement, so a
+   * rejection after that point left the engine permanently wedged: it never
+   * reached `process.exit(0)`, every later request answered
+   * `503 ENGINE_SHUTTING_DOWN`, a second `engine-stop` returned early, and
+   * the socket and run file stayed in place. Both callers discarded the
+   * error, so nothing was written to the log either — the operator saw
+   * Ctrl-C do nothing and had to `kill -9` and clear the run directory by
+   * hand.
+   */
+  const onShutdownFailure = (error: unknown): void => {
+    const message = error instanceof Error ? error.message : String(error)
+    try {
+      logger.error('Shutdown failed', { message })
+    } catch {
+      // The logger may be what failed.
+    }
+    console.error(`[edge-engine] shutdown failed: ${message}`)
+    removeRunArtifacts(profile, {
+      keepSocket: !boundSocket,
+      keepSession: !boundSocket
+    })
+    process.exit(1)
+  }
+  /**
+   * Stop the engine, saying why.
+   *
+   * The reason reaches two places that need it: the `engine.shutdown` event,
+   * which a subscriber reads, and the exit status. All three outcomes —
+   * `engine-stop`, the idle timeout and a crash — used to emit
+   * `reason: 'requested'` and exit 0, so a supervisor could not tell them
+   * apart and `spawnEngine`'s startup diagnostic told an operator "the
+   * engine exited with code 0 during startup" for an engine that had thrown
+   * while loading a bad `keys.json` or a plugin.
+   */
+  const shutdown = async (
+    reason: 'requested' | 'idle' | 'fatal' = 'requested'
+  ): Promise<void> => {
+    if (shuttingDown) return
+    shuttingDown = true
+    state.shuttingDown = true
+    events.emit('engine.shutdown', { reason })
+    idle.stop()
+    // `state.shuttingDown` already answers new requests with
+    // `503 ENGINE_SHUTTING_DOWN`, but a request that has already started
+    // keeps its account: tearing the core down mid-`spend` could land between
+    // `broadcastTx` and `saveTx`, so the money leaves the wallet, the client
+    // gets no response at all, and local history does not have the
+    // transaction until a sync finds it. The idle path already refuses to
+    // fire while anything is in flight; `engine-stop` and SIGINT now wait the
+    // same way, with a bound so a wedged request cannot block the exit.
+    await drainRequests()
+    sessions.stopAutoLogoutTicker()
+    objects.stopTicker()
+    ssePing?.stop()
+    await objects.clearAll()
+    await sessions.logoutAll()
+    // Both: the cache is state, and the queue is work. A debounce armed just
+    // before shutdown would otherwise fire against a closing context, and
+    // anything still awaiting a rate would never settle.
+    stopRateQueue()
+    clearRateCache()
+    try {
+      await core.context.close()
+    } catch {
+      // ignore
+    }
+    // Let subscribers learn why the stream ended before the socket closes.
+    events.closeAll('engineShutdown')
+    logger.info('Engine shutdown complete')
+    await logger.close()
+    await new Promise<void>(resolve => {
+      if (unixServer == null) {
+        resolve()
+        return
+      }
+      unixServer.close(() => {
+        resolve()
+      })
+    })
+    await new Promise<void>(resolve => {
+      if (tcpServer == null) {
+        resolve()
+        return
+      }
+      tcpServer.close(() => {
+        resolve()
+      })
+    })
+    removeRunArtifacts(profile)
+    // Non-zero for a crash, so a supervisor restarts it and the client's own
+    // diagnostic says something useful. `main().catch` already gets this
+    // right; it is the post-startup path that lost it.
+    process.exit(reason === 'fatal' ? 1 : 0)
+  }
+
+  const idle = new IdleShutdown({
+    idleTimeoutSeconds: args.idleTimeoutSeconds,
+    getSessionCount: () => sessions.size,
+    getSubscriberCount: () => events.clientCount,
+    getSessionlessHandleCount: () => objects.sessionlessCount,
+    onFire: async () => {
+      logger.warn('Idle timeout — shutting down')
+      await shutdown('idle')
+    }
+  })
+  sessions.onSessionsChanged = () => {
+    idle.notifySessionsChanged()
+  }
+  events.onClientsChanged = () => {
+    idle.notifySubscribersChanged()
+  }
+  objects.onHandlesChanged = () => {
+    idle.notifyHandlesChanged()
+  }
+
+  const state: EngineState = {
+    core,
+    sessions,
+    objects,
+    events,
+    idle,
+    // The real handler, not a placeholder replaced further down: a teardown
+    // that threw during the startup tail landed in the no-op that used to sit
+    // here, so the rejection was discarded and the engine stayed wedged with
+    // `state.shuttingDown` already true.
+    onShutdownFailure,
+    logger,
+    profile,
+    socketPath,
+    tcpPort: null,
+    startedAt: Date.now(),
+    shuttingDown: false,
+    shutdown
+  }
+
+  const router = new Router()
+  registerRoutes(router)
+
+  unixServer = await listenUnix(createRequestHandler(state, router), socketPath)
+  boundSocket = true
+  console.error(`[edge-engine] Listening on unix:${socketPath}`)
+
+  if (args.tcpPort != null) {
+    // Opt-in loopback TCP for local scripts, authenticated. The unix socket
+    // can rely on its `0600` mode; a TCP port cannot, and a `sessionId` is
+    // full account authority, so `transportAuth.ts` requires a bearer token
+    // from the `0600` run file, refuses a foreign `Host` and refuses any
+    // request carrying `Origin`.
+    tcpToken = makeTcpToken()
+    const guard: TcpGuard = {
+      token: tcpToken,
+      allowedHostnames: allowedHostnamesFor(args.tcpHost)
+    }
+    const tcp = await listenTcp(
+      createRequestHandler(state, router, guard),
+      args.tcpPort,
+      args.tcpHost
+    )
+    tcpServer = tcp.server
+    boundTcpPort = tcp.port
+    state.tcpPort = boundTcpPort
+    console.error(
+      `[edge-engine] Listening on http://${
+        args.tcpHost
+      }:${boundTcpPort} (token in ${runFilePath(profile)})`
+    )
+  }
+
+  writeRunFile(profile, {
+    pid: process.pid,
+    apiVersion: API_VERSION,
+    socketPath,
+    tcpPort: boundTcpPort,
+    // Only set when the TCP listener is on, and only readable by this user:
+    // the run file is `0600` inside a `0700` directory, which is what makes
+    // being able to read it the authorisation to call.
+    tcpToken: tcpToken ?? undefined,
+    appId,
+    // The core's effective value, not the argv-derived one, so the run file
+    // agrees with what `engine-status` and `engine-config` report. `--fake`
+    // reports true: the fake world is not production, which is what a caller
+    // checking this field wants to know.
+    testMode: core.testMode,
+    startedAt: new Date().toISOString()
+  })
+
+  sessions.startAutoLogoutTicker()
+  objects.startTicker()
+  // A comment frame on every sweep, so a subscriber that vanished without a
+  // clean FIN — a sleeping laptop, a killed container, a dropped TCP link —
+  // is reaped rather than holding the engine open for good.
+  ssePing = makeSweepTicker('sse keepalive', async () => {
+    events.pingClients()
+  })
+  ssePing.start()
+
+  const onSignal = (): void => {
+    shutdown().catch(onShutdownFailure)
+  }
+  process.on('SIGINT', onSignal)
+  process.on('SIGTERM', onSignal)
+
+  // A daemon that dies without running `shutdown()` leaves its socket and run
+  // file behind, so the next client finds a profile that looks live and waits
+  // out its connect timeout. `main().catch` cannot cover this: an uncaught
+  // exception or an unhandled rejection after startup never becomes a
+  // rejection of `main`.
+  const onFatal = (what: string) => (error: unknown) => {
+    const message =
+      error instanceof Error ? error.stack ?? error.message : String(error)
+    console.error(`[edge-engine] ${what}: ${message}`)
+    try {
+      logger.error(what, { error: message })
+    } catch {
+      // The logger itself may be what failed.
+    }
+    shutdown('fatal').catch(onShutdownFailure)
+  }
+  process.on('uncaughtException', onFatal('uncaught exception'))
+  process.on('unhandledRejection', onFatal('unhandled rejection'))
+
+  console.error(
+    `[edge-engine] Ready (pid=${process.pid}, profile=${profile}, testMode=${testMode}, log=${logger.logPath})`
+  )
+  logger.info('Ready', { pid: process.pid, profile, testMode })
+  if (staleProfiles > 0 || staleLogs > 0) {
+    logger.info('Swept abandoned engine state', { staleProfiles, staleLogs })
+  }
+}
+
+main().catch((error: unknown) => {
+  // Bad argv is the operator's mistake, not a crash: one line and exit 2,
+  // matching the client's documented exit model. Anything else keeps its
+  // stack, because that is a fault worth reading.
+  if (error instanceof EngineUsageError) {
+    console.error(`[edge-engine] ${error.message}`)
+    process.exit(2)
+  }
+  console.error('[edge-engine] Fatal:', error)
+  // A startup that dies after claiming the profile — a port already in use, a
+  // plugin that throws — used to leave its socket, run file and any
+  // session.json behind, so the next client found a profile that looked live
+  // and waited out its connect timeout. The startup log is kept: it is the
+  // only record of what happened.
+  if (claimedProfile != null) {
+    removeRunArtifacts(claimedProfile, {
+      keepStartupLog: true,
+      keepSocket: !boundSocket,
+      keepSession: !boundSocket
+    })
+  }
+  process.exit(1)
+})
diff --git a/src/cli/engine/internal.ts b/src/cli/engine/internal.ts
new file mode 100644
index 00000000000..b04df7921e8
--- /dev/null
+++ b/src/cli/engine/internal.ts
@@ -0,0 +1,45 @@
+import type { Disklet } from 'disklet'
+import type { EdgeContext } from 'edge-core-js'
+import type { Subscriber } from 'yaob'
+
+export interface LobbyRequest {
+  timeout?: number
+  publicKey?: string
+  loginRequest?: { appId: string }
+  replies?: unknown[]
+}
+
+interface EdgeLobby {
+  readonly on: Subscriber<{ error: Error }>
+  readonly watch: Subscriber<EdgeLobby>
+  readonly lobbyId: string
+  readonly replies: unknown[]
+  close: () => void
+}
+
+export interface SyncResult {
+  changes: Record<string, unknown>
+  status: {
+    lastHash?: string | null
+    lastSync: number
+  }
+}
+
+export interface EdgeInternalStuff {
+  authRequest: (method: string, path: string, body?: object) => Promise<unknown>
+  hashUsername: (username: string) => Promise<Uint8Array>
+  makeLobby: (lobbyRequest: LobbyRequest, period?: number) => Promise<EdgeLobby>
+  fetchLobbyRequest: (lobbyId: string) => Promise<LobbyRequest>
+  sendLobbyReply: (
+    lobbyId: string,
+    lobbyRequest: LobbyRequest,
+    replyData: unknown
+  ) => Promise<void>
+  syncRepo: (syncKey: Uint8Array) => Promise<SyncResult>
+  getRepoDisklet: (syncKey: Uint8Array, dataKey: Uint8Array) => Promise<Disklet>
+}
+
+export function getInternalStuff(context: EdgeContext): EdgeInternalStuff {
+  return (context as unknown as { $internalStuff: EdgeInternalStuff })
+    .$internalStuff
+}
diff --git a/src/cli/engine/json.ts b/src/cli/engine/json.ts
new file mode 100644
index 00000000000..dd0a4b50baa
--- /dev/null
+++ b/src/cli/engine/json.ts
@@ -0,0 +1,72 @@
+/**
+ * JSON helpers for the engine REST API.
+ * Uint8Array -> base64, Map -> object.
+ */
+import { base64 } from 'rfc4648'
+
+import type { EngineError } from './errors'
+import { engineError } from './errors'
+
+/**
+ * Encode the values core hands back that JSON cannot carry.
+ *
+ * No `Date` arm: `JSON.stringify` calls `Date.prototype.toJSON` *before* the
+ * replacer, so a replacer is handed the ISO string and can never see the
+ * Date. The output is the same either way, which is why the arm went
+ * unnoticed.
+ */
+export function jsonReplacer(_key: string, value: unknown): unknown {
+  if (value instanceof Uint8Array) {
+    // `rfc4648`, not `Buffer`: this is the engine's response serializer, so
+    // every Uint8Array the API returns goes through it.
+    return base64.stringify(value)
+  }
+  if (value instanceof Map) {
+    const obj: Record<string, unknown> = {}
+    for (const [k, v] of value.entries()) {
+      obj[String(k)] = v
+    }
+    return obj
+  }
+  return value
+}
+
+export function stringifyJson(value: unknown): string {
+  return JSON.stringify(value, jsonReplacer)
+}
+
+/** Nothing the REST API accepts is anywhere near this large. */
+const MAX_BODY_BYTES = 4 * 1024 * 1024
+
+function tooLarge(): EngineError {
+  return engineError(
+    'PAYLOAD_TOO_LARGE',
+    `Request body exceeds ${MAX_BODY_BYTES} bytes`,
+    413
+  )
+}
+
+export async function readJsonBody(
+  req: NodeJS.ReadableStream & {
+    headers?: Record<string, string | string[] | undefined>
+  }
+): Promise<unknown> {
+  const declared = Number(req.headers?.['content-length'] ?? '0')
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) throw tooLarge()
+
+  const chunks: Buffer[] = []
+  let total = 0
+  for await (const chunk of req) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    total += buf.length
+    if (total > MAX_BODY_BYTES) throw tooLarge()
+    chunks.push(buf)
+  }
+  const raw = Buffer.concat(chunks).toString('utf8')
+  if (raw === '') return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw engineError('BAD_REQUEST', 'Invalid JSON body', 400)
+  }
+}
diff --git a/src/cli/engine/keysConfig.ts b/src/cli/engine/keysConfig.ts
new file mode 100644
index 00000000000..9e2b975472e
--- /dev/null
+++ b/src/cli/engine/keysConfig.ts
@@ -0,0 +1,97 @@
+import { asObject, asOptional, asString, asUnknown } from 'cleaners'
+
+import { isPlainObject } from '../../util/predicates'
+import { configSearchPaths, readJsonConfig } from './readJsonConfig'
+
+const asKeysConfig = asObject({
+  edgeApiKey: asOptional(asString, ''),
+  edgeApiSecret: asOptional(asString),
+  pluginApiKeys: asOptional(asObject(asUnknown), () => ({}))
+})
+
+/**
+ * Derived from the cleaner. The `Cleaner<KeysConfig>` annotation it replaces
+ * hid what the cleaner really returns — `edgeApiKey` has a `''` fallback, so
+ * it is always present, which the interface happened to agree with only by
+ * hand.
+ */
+export type KeysConfig = ReturnType<typeof asKeysConfig>
+
+function makeDefaultKeys(): KeysConfig {
+  return { edgeApiKey: '', edgeApiSecret: undefined, pluginApiKeys: {} }
+}
+
+/**
+ * Merge plugin settings with the earlier search path taking precedence.
+ * Object values merge field-by-field so a CLI fallback key can supplement,
+ * but cannot replace, GUI config such as Changelly's partnerId.
+ */
+export function mergePluginApiKeys(
+  preferred: Record<string, unknown>,
+  fallback: Record<string, unknown>
+): Record<string, unknown> {
+  const out = { ...fallback }
+  for (const [pluginId, preferredValue] of Object.entries(preferred)) {
+    const fallbackValue = out[pluginId]
+    out[pluginId] =
+      isPlainObject(preferredValue) && isPlainObject(fallbackValue)
+        ? { ...fallbackValue, ...preferredValue }
+        : preferredValue
+  }
+  return out
+}
+
+/** Where loadKeys looks, in order. */
+export function keysSearchPaths(): string[] {
+  return configSearchPaths('keys.json')
+}
+
+function readKeysFile(path: string): KeysConfig | null {
+  return readJsonConfig(path, asKeysConfig, 'keys.json')
+}
+
+/**
+ * Loads keys.json from (in order):
+ * 1. ./keys.json
+ * 2. ~/.edge-cli/keys.json
+ *
+ * Missing files are skipped. Present but invalid JSON/cleaner failures throw
+ * so misconfiguration is not silently treated as empty defaults. A file that
+ * parses but carries no `edgeApiKey` — such as the GUI's own repo-root
+ * keys.json — does not shadow a later file that does have one.
+ *
+ * Plugin secrets (including Monero LWS `edgeApiKey`) come from signed
+ * infoRollup `appKeys` at engine boot, not from leftover `env.json`
+ * `MONERO_INIT`.
+ */
+export function loadKeys(): KeysConfig {
+  const out = makeDefaultKeys()
+  let foundApiKey = false
+
+  for (const path of keysSearchPaths()) {
+    const parsed = readKeysFile(path)
+    if (parsed == null) continue
+    out.pluginApiKeys = mergePluginApiKeys(
+      out.pluginApiKeys,
+      parsed.pluginApiKeys
+    )
+    if (!foundApiKey && parsed.edgeApiKey !== '') {
+      out.edgeApiKey = parsed.edgeApiKey
+      out.edgeApiSecret = parsed.edgeApiSecret
+      foundApiKey = true
+    }
+  }
+
+  return out
+}
+
+/**
+ * The cleaner itself, for the drift test.
+ *
+ * `configSubsets.test.ts` feeds it what the app's own `config.json` /
+ * `keys.json` cleaner produces, so this narrower subset cannot stop
+ * accepting the file the app writes. The engine deliberately does not use
+ * the app's `makeConfig` loader, which fills defaults and writes the file
+ * back — a daemon asked to read a user's keys must not rewrite them.
+ */
+export const asKeysConfigForTests = asKeysConfig
diff --git a/src/cli/engine/logger.ts b/src/cli/engine/logger.ts
new file mode 100644
index 00000000000..712c9059287
--- /dev/null
+++ b/src/cli/engine/logger.ts
@@ -0,0 +1,225 @@
+/**
+ * Engine file logger — background/core logs go here, not to the CLI user's
+ * stdout/stderr. Lifecycle "Ready" lines may still go to stderr for scripts
+ * that wait on startup.
+ */
+import fs from 'fs'
+import path from 'path'
+
+import { cliLogsDir, cliRunRoot } from './cliHome'
+
+/**
+ * How large one engine log may grow before it rolls.
+ *
+ * A daemon held open past its idle timeout — which `subscribe` does by
+ * design, and `--idle-timeout=0` does explicitly — writes continuously, and a
+ * plugin stuck in a retry loop writes fast — fast enough to reach several
+ * megabytes an hour, most of it one repeated warning. One previous
+ * generation is kept, so a profile costs at most 2 × this.
+ */
+const MAX_LOG_BYTES = 8 * 1024 * 1024
+
+/** Engine logs older than this are swept at startup. */
+const LOG_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+
+export class EngineLogger {
+  private stream: fs.WriteStream | null = null
+  private bytesWritten = 0
+  readonly logPath: string
+
+  constructor(profile: string) {
+    // Engine logs carry usernames, login ids and core diagnostics, so keep
+    // them owner-only rather than at the default umask.
+    const dir = cliLogsDir()
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    this.logPath = path.join(dir, `engine-${profile}.log`)
+    try {
+      this.bytesWritten = fs.statSync(this.logPath).size
+    } catch {
+      // No log yet.
+    }
+    this.stream = fs.createWriteStream(this.logPath, {
+      flags: 'a',
+      mode: 0o600
+    })
+    try {
+      // `mode` only applies on creation, so tighten anything an earlier,
+      // laxer run left behind.
+      fs.chmodSync(dir, 0o700)
+      fs.chmodSync(this.logPath, 0o600)
+    } catch {
+      // ignore
+    }
+    // `createWriteStream` reports EACCES (a logs directory left root-owned or
+    // read-only), ENOSPC and EDQUOT *asynchronously*, and an unhandled
+    // `'error'` on an EventEmitter throws — an uncaught exception, which
+    // would kill a long-lived daemon mid-request and skip
+    // `removeRunArtifacts`. Logging is never worth the process.
+    this.stream.on('error', (error: Error) => {
+      this.stream = null
+      console.error(
+        `[edge-engine] log file unusable (${this.logPath}): ${error.message}`
+      )
+    })
+  }
+
+  write(level: string, message: string, extra?: Record<string, unknown>): void {
+    const line = JSON.stringify({
+      time: new Date().toISOString(),
+      level,
+      message,
+      ...extra
+    })
+    const text = line + '\n'
+    this.bytesWritten += Buffer.byteLength(text)
+    if (this.bytesWritten > MAX_LOG_BYTES) this.roll()
+    this.stream?.write(text)
+  }
+
+  /**
+   * Start a fresh log, keeping one previous generation.
+   *
+   * Renaming rather than truncating means a reader following the old file
+   * keeps a consistent view of it.
+   */
+  private roll(): void {
+    const previous = this.stream
+    this.stream = null
+    try {
+      previous?.end()
+      fs.renameSync(this.logPath, `${this.logPath}.1`)
+    } catch {
+      // If the rename fails there is nothing useful to do but keep going on
+      // the file we have.
+    }
+    try {
+      this.stream = fs.createWriteStream(this.logPath, {
+        flags: 'a',
+        mode: 0o600
+      })
+      this.stream.on('error', (error: Error) => {
+        this.stream = null
+        console.error(
+          `[edge-engine] log file unusable (${this.logPath}): ${error.message}`
+        )
+      })
+      this.bytesWritten = 0
+    } catch (error) {
+      console.error(
+        `[edge-engine] could not roll the log: ${String(
+          error instanceof Error ? error.message : error
+        )}`
+      )
+    }
+  }
+
+  info(message: string, extra?: Record<string, unknown>): void {
+    this.write('info', message, extra)
+  }
+
+  warn(message: string, extra?: Record<string, unknown>): void {
+    this.write('warn', message, extra)
+  }
+
+  error(message: string, extra?: Record<string, unknown>): void {
+    this.write('error', message, extra)
+  }
+
+  /** Resolves once buffered lines reach disk, so shutdown can await it. */
+  async close(): Promise<void> {
+    const stream = this.stream
+    this.stream = null
+    if (stream == null) return
+    await new Promise<void>(resolve => {
+      stream.end(() => {
+        resolve()
+      })
+    })
+  }
+}
+
+/**
+ * Remove engine logs nothing is writing any more.
+ *
+ * Every throwaway `--directory` gets its own profile hash and therefore its
+ * own log file, so a machine that runs the test suites accumulates one per
+ * run, indefinitely. Swept at engine startup
+ * rather than on shutdown, so the log of the run you just did is still there
+ * to read.
+ *
+ * A log whose profile still has a live run file is kept, whatever its age.
+ * `fs.unlinkSync` succeeds on POSIX for a file another process holds open,
+ * so the `catch` below does not protect a live writer: an engine started
+ * `--idle-timeout=0` and left quiet kept writing to an unlinked inode after
+ * another engine's startup sweep removed it, so its log silently stopped
+ * existing while `logger.logPath` and the `Ready` line still named it.
+ * `keep` is the file this process has open, which the caller knows.
+ */
+export function sweepOldLogs(
+  maxAgeMs: number = LOG_MAX_AGE_MS,
+  keep?: string
+): number {
+  const dir = cliLogsDir()
+  let removed = 0
+  let names: string[]
+  try {
+    names = fs.readdirSync(dir)
+  } catch {
+    return 0
+  }
+  const cutoff = Date.now() - maxAgeMs
+  const liveProfiles = liveLogProfiles()
+  for (const name of names) {
+    if (!name.startsWith('engine-')) continue
+    const file = path.join(dir, name)
+    if (keep != null && file === keep) continue
+    // `engine-<profile>.log`, and `engine-<profile>.log.1` after a roll.
+    const profile = name.slice('engine-'.length).replace(/\.log(\.\d+)?$/, '')
+    if (liveProfiles.has(profile)) continue
+    try {
+      if (fs.statSync(file).mtimeMs >= cutoff) continue
+      fs.unlinkSync(file)
+      removed++
+    } catch {
+      // Already gone.
+    }
+  }
+  return removed
+}
+
+/**
+ * Profiles whose run file names a process that is still running.
+ *
+ * The same test `sweepStaleProfiles` applies, read here directly rather than
+ * imported, because this module is loaded before the engine has a profile
+ * and must not drag the discovery module's `net` probe into that path.
+ */
+function liveLogProfiles(): Set<string> {
+  const live = new Set<string>()
+  const runRoot = cliRunRoot()
+  let profiles: string[]
+  try {
+    profiles = fs.readdirSync(runRoot)
+  } catch {
+    return live
+  }
+  for (const profile of profiles) {
+    try {
+      const raw = fs.readFileSync(
+        path.join(runRoot, profile, 'engine.json'),
+        'utf8'
+      )
+      const pid = JSON.parse(raw)?.pid
+      if (typeof pid !== 'number') continue
+      process.kill(pid, 0)
+      live.add(profile)
+    } catch (error: unknown) {
+      // EPERM means the pid exists and belongs to another user, which still
+      // counts as live. Anything else — no file, bad JSON, ESRCH — does not.
+      if ((error as { code?: string } | null)?.code === 'EPERM') {
+        live.add(profile)
+      }
+    }
+  }
+  return live
+}
diff --git a/src/cli/engine/makeCoreContext.ts b/src/cli/engine/makeCoreContext.ts
new file mode 100644
index 00000000000..a1906163a83
--- /dev/null
+++ b/src/cli/engine/makeCoreContext.ts
@@ -0,0 +1,400 @@
+import { asMaybe } from 'cleaners'
+import {
+  addEdgeCorePlugins,
+  type EdgeContext,
+  type EdgeCorePluginsInit,
+  lockEdgeCorePlugins,
+  makeEdgeContext,
+  makeFakeEdgeWorld
+} from 'edge-core-js'
+import accountbasedPluginsImport from 'edge-currency-accountbased'
+import currencyPluginsImport from 'edge-currency-plugins'
+import exchangePluginsImport from 'edge-exchange-plugins'
+import { base16 } from 'rfc4648'
+
+import { loadAppConfig } from './appConfig'
+import { defaultDirectory } from './cliConfig'
+import type { EventHub } from './events'
+import { fetchPluginKeys } from './fetchPluginKeys'
+import { keysSearchPaths, loadKeys, mergePluginApiKeys } from './keysConfig'
+import type { EngineLogger } from './logger'
+import { hasNodeApiSigner, makeNodeApiSigner } from './nodeApiSigner'
+import { asPluginKeysEntry } from './schemas'
+import { TESTER_SERVERS } from './testerServers'
+
+let pluginsLocked = false
+
+/**
+ * CJS/ESM interop: these packages often export `{ default: { bitcoin, … } }`.
+ */
+function unwrapPlugins(mod: Record<string, unknown>): Record<string, unknown> {
+  const inner = mod.default
+  if (
+    inner != null &&
+    typeof inner === 'object' &&
+    !Array.isArray(inner) &&
+    Object.keys(mod).length <= 2
+  ) {
+    return inner as Record<string, unknown>
+  }
+  return mod
+}
+
+function mergePluginInit(
+  configValue: unknown,
+  keysValue: unknown
+): boolean | Record<string, unknown> {
+  if (configValue === false || keysValue === false) return false
+  const cfg =
+    configValue != null &&
+    typeof configValue === 'object' &&
+    !Array.isArray(configValue)
+      ? { ...(configValue as Record<string, unknown>) }
+      : {}
+  const keys =
+    keysValue != null &&
+    typeof keysValue === 'object' &&
+    !Array.isArray(keysValue)
+      ? { ...(keysValue as Record<string, unknown>) }
+      : {}
+  const { enabled: cfgEnabled, ...cfgRest } = cfg
+  const { enabled: keysEnabled, ...keysRest } = keys
+  if (cfgEnabled === false || keysEnabled === false) return false
+  const merged = { ...cfgRest, ...keysRest }
+  if (Object.keys(merged).length > 0) return merged
+  if (configValue === true || keysValue === true) return true
+  if (configValue != null || keysValue != null) return true
+  return false
+}
+
+const currencyPlugins = unwrapPlugins(
+  currencyPluginsImport as unknown as Record<string, unknown>
+)
+const accountbasedPlugins = unwrapPlugins(
+  accountbasedPluginsImport as unknown as Record<string, unknown>
+)
+const exchangePlugins = unwrapPlugins(
+  exchangePluginsImport as unknown as Record<string, unknown>
+)
+
+function ensurePlugins(): void {
+  if (pluginsLocked) return
+  addEdgeCorePlugins(
+    currencyPlugins as Parameters<typeof addEdgeCorePlugins>[0]
+  )
+  addEdgeCorePlugins(
+    accountbasedPlugins as Parameters<typeof addEdgeCorePlugins>[0]
+  )
+  addEdgeCorePlugins(
+    exchangePlugins as Parameters<typeof addEdgeCorePlugins>[0]
+  )
+  lockEdgeCorePlugins()
+  pluginsLocked = true
+}
+
+export interface MakeCoreContextOpts {
+  /**
+   * An API key the operator supplied explicitly, with `-k`.
+   *
+   * An override: it replaces the key *and* drops the keys.json secret and
+   * the native HMAC signer, which is what the guide documents `-k` and
+   * `EDGE_CLI_FORCE_KEYS_JSON=1` as doing.
+   */
+  apiKey?: string
+  /**
+   * An API key from the config file.
+   *
+   * Used as the key when there is no explicit one, and nothing more: it does
+   * not disable signing. Reading a config value as an override turned HMAC
+   * signing off for anyone who put `apiKey` in `edge-cli.conf`.
+   */
+  configApiKey?: string
+  appId?: string
+  directory?: string
+  testMode?: boolean
+  /**
+   * Serve a `makeFakeEdgeWorld` context instead of talking to a server.
+   *
+   * The login, info and sync servers are emulated in-process and currency
+   * plugins are cut off from the network, so the whole API can be exercised
+   * with no account, no key and no internet. That is what lets the CLI tests
+   * run in a pre-commit hook.
+   */
+  fake?: boolean
+  events: EventHub
+  logger?: EngineLogger
+}
+
+/**
+ * A context backed by the in-process fake world.
+ *
+ * No API key is needed and `fetchPluginKeys` is skipped, because there is no
+ * server to authenticate to. Every plugin is *registered* — `ensurePlugins`
+ * runs before this function is reached, for a fake context as much as a real
+ * one — and only the currency plugins are *enabled*, through `pluginsInit`:
+ * the swap and exchange-rate plugins exist to call other people's APIs,
+ * which is exactly what this mode forbids.
+ */
+async function makeFakeCoreContext(
+  opts: MakeCoreContextOpts
+): Promise<CoreContextBundle> {
+  const appId = opts.appId ?? ''
+  const directory = opts.directory ?? defaultDirectory()
+  const pluginsInit: EdgeCorePluginsInit = {}
+  for (const id of Object.keys(currencyPlugins)) pluginsInit[id] = true
+
+  const world = await makeFakeEdgeWorld([], {
+    onLog(event) {
+      opts.logger?.write(String(event.type ?? 'info'), event.message, {
+        source: event.source
+      })
+    }
+  })
+  const context = await world.makeEdgeContext({
+    appId,
+    apiKey: 'fake',
+    cleanDevice: true,
+    plugins: pluginsInit
+  })
+  opts.logger?.info('Using the fake world; no network, no server')
+
+  return {
+    context,
+    appId,
+    testMode: true,
+    directory,
+    servers: { loginServer: 'fake://login', syncServer: 'fake://sync' },
+    pluginsInit,
+    currencyPluginIds: Object.keys(currencyPlugins)
+  }
+}
+
+export interface CoreContextBundle {
+  context: EdgeContext
+  appId: string
+  testMode: boolean
+  directory: string
+  servers: {
+    loginServer?: string
+    infoServer?: string
+    changeServer?: string
+    syncServer?: string | string[]
+  }
+  pluginsInit: EdgeCorePluginsInit
+  /** Enabled currency/accountbased plugin ids (not swap). For wallet-create. */
+  currencyPluginIds: string[]
+}
+
+export async function makeCoreContext(
+  opts: MakeCoreContextOpts
+): Promise<CoreContextBundle> {
+  ensurePlugins()
+  if (opts.fake === true) return await makeFakeCoreContext(opts)
+  const keysConfig = loadKeys()
+  const appConfig = loadAppConfig()
+  const pluginsInit: EdgeCorePluginsInit = {}
+
+  const appId = opts.appId ?? ''
+  const directory = opts.directory ?? defaultDirectory()
+  const testMode = opts.testMode === true
+  // Order: an explicit `-k`, then the config file, then keys.json. Only the
+  // first is an override.
+  const effectiveApiKey =
+    opts.apiKey ?? opts.configApiKey ?? keysConfig.edgeApiKey
+  // An explicit -k replaces the key, so the keys.json secret no longer belongs
+  // to it. Pairing them would sign every request with a mismatched secret.
+  // A key from the config file is *not* an override — it is just where the
+  // key came from — so it keeps the secret and the native signer. Treating
+  // the two alike silently turned off HMAC signing for anyone who wrote
+  // `apiKey` into `edge-cli.conf`, which is the opposite of what
+  // `docs/EDGE_CLI.md` promises.
+  const apiSecretHex =
+    opts.apiKey != null ? undefined : keysConfig.edgeApiSecret
+  const apiSecret =
+    apiSecretHex != null
+      ? base16.parse(apiSecretHex.replace(/^0x/i, '').toUpperCase())
+      : undefined
+  // Explicit -k / EDGE_CLI_FORCE_KEYS_JSON skips the N-API signer so operators
+  // can point a native-built engine at alternate keys for tester/debug.
+  const forceKeysJson =
+    opts.apiKey != null || process.env.EDGE_CLI_FORCE_KEYS_JSON === '1'
+  const useNativeSigner = !forceKeysJson && hasNodeApiSigner()
+  const apiSigner = useNativeSigner ? makeNodeApiSigner() : undefined
+
+  if (apiSigner == null && effectiveApiKey === '') {
+    throw new Error(
+      'No Edge API key available. Pass one with -k, build the native signer, ' +
+        `or add "edgeApiKey" to one of: ${keysSearchPaths().join(', ')}`
+    )
+  }
+
+  const servers = testMode
+    ? {
+        loginServer: TESTER_SERVERS.loginServer,
+        infoServer: TESTER_SERVERS.infoServer,
+        changeServer: TESTER_SERVERS.changeServer,
+        syncServer: [...TESTER_SERVERS.syncServer]
+      }
+    : {}
+
+  if (testMode) {
+    opts.logger?.info('Using tester servers', { servers })
+  }
+  if (useNativeSigner) {
+    opts.logger?.info('Using Node native Edge API HMAC signer')
+  }
+
+  try {
+    const remote = await fetchPluginKeys({
+      apiSigner,
+      apiKey: effectiveApiKey,
+      apiSecret,
+      appId,
+      testMode
+    })
+    keysConfig.pluginApiKeys = mergePluginApiKeys(
+      remote.pluginApiKeys,
+      keysConfig.pluginApiKeys
+    )
+    const monero = asMaybe(asPluginKeysEntry)(remote.pluginApiKeys.monero)
+    const moneroHasKey = monero?.edgeApiKey != null && monero.edgeApiKey !== ''
+    opts.logger?.info('Fetched infoRollup appKeys', {
+      pluginApiKeys: Object.keys(remote.pluginApiKeys).length,
+      moneroEdgeApiKey: moneroHasKey,
+      assuranceLevel: remote.assuranceLevel,
+      signer: apiSigner != null ? 'native' : 'js'
+    })
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    opts.logger?.warn(
+      `infoRollup appKeys fetch failed; using local plugin keys: ${message}`
+    )
+  }
+
+  const applyCurrencyPluginKeys = (pluginId: string): void => {
+    const pluginKeys = keysConfig.pluginApiKeys[pluginId]
+    if (pluginKeys === false) {
+      pluginsInit[pluginId] = false
+      return
+    }
+    if (pluginKeys == null) {
+      pluginsInit[pluginId] = true
+      return
+    }
+    // `true` is this repo's spelling for "enabled, no init options": it is
+    // what `src/configKeysMerge.ts` documents, what core's own `pluginsInit`
+    // takes, and what `mergePluginInit` accepts on the swap path a few
+    // functions above. `asPluginKeysEntry` is an `asObject`, so a boolean
+    // failed it and fell into the disable-on-garbage arm below — one line in
+    // a log file, and the currency silently gone from `currencyPluginIds`,
+    // so the user's wallets of that type never loaded.
+    if (pluginKeys === true) {
+      pluginsInit[pluginId] = true
+      return
+    }
+    const entry = asMaybe(asPluginKeysEntry)(pluginKeys)
+    if (entry == null) {
+      // Neither `false`, nor absent, nor a usable object. Treating this as
+      // "enabled" is how a server sending `"monero": "false"` — the string —
+      // switched the plugin *on* with no keys instead of disabling it.
+      opts.logger?.warn(
+        `Ignoring unusable plugin keys for ${pluginId}; the plugin is disabled`
+      )
+      pluginsInit[pluginId] = false
+      return
+    }
+    if (entry.enabled === false) {
+      pluginsInit[pluginId] = false
+      return
+    }
+    // `asObject` materialises every declared key, so `{}` and
+    // `{"enabled":true}` both clean to an object carrying
+    // `edgeApiKey: undefined`. Counting those made `pluginsInit[pluginId]` an
+    // object with one undefined key where it should be `true`, which also
+    // stopped the `moneroInit === true` check below warning about Monero
+    // enabled with no key.
+    const { enabled, ...rest } = entry
+    const options = Object.fromEntries(
+      Object.entries(rest).filter(([, value]) => value !== undefined)
+    )
+    pluginsInit[pluginId] = Object.keys(options).length > 0 ? options : true
+  }
+
+  for (const pluginId of Object.keys(currencyPlugins)) {
+    applyCurrencyPluginKeys(pluginId)
+  }
+
+  for (const pluginId of Object.keys(accountbasedPlugins)) {
+    applyCurrencyPluginKeys(pluginId)
+  }
+
+  const swapConfig = appConfig.swapPlugins ?? {}
+  for (const pluginId of Object.keys(exchangePlugins)) {
+    pluginsInit[pluginId] = mergePluginInit(
+      swapConfig[pluginId],
+      keysConfig.pluginApiKeys[pluginId]
+    )
+  }
+
+  const moneroInit = pluginsInit.monero
+  const moneroEdgeApiKey =
+    typeof moneroInit === 'object' && moneroInit != null
+      ? (moneroInit as { edgeApiKey?: unknown }).edgeApiKey
+      : undefined
+  if (moneroInit === true) {
+    opts.logger?.warn(
+      'Monero enabled without edgeApiKey; Edge LWS /login will omit api_key'
+    )
+  } else if (typeof moneroEdgeApiKey === 'string' && moneroEdgeApiKey !== '') {
+    opts.logger?.info('Monero LWS edgeApiKey configured')
+  }
+
+  const enabledSwap = Object.keys(exchangePlugins).filter(
+    id => pluginsInit[id] !== false && pluginsInit[id] != null
+  )
+  opts.logger?.info('Swap plugins enabled', { plugins: enabledSwap })
+
+  const currencyPluginIds = [
+    ...Object.keys(currencyPlugins),
+    ...Object.keys(accountbasedPlugins)
+  ].filter(id => pluginsInit[id] !== false && pluginsInit[id] != null)
+
+  const context = await makeEdgeContext({
+    ...(apiSigner != null
+      ? { apiSigner }
+      : {
+          apiKey: effectiveApiKey,
+          apiSecret
+        }),
+    appId,
+    path: directory,
+    plugins: pluginsInit,
+    ...servers,
+    onLog(event) {
+      const type = String(event.type ?? 'info')
+      // `info` is a plugin's own poll-loop chatter and there is a lot of it:
+      // 7,319 of 7,691 lines in one 9.6 MB log were a single plugin's
+      // `init:` messages. It still reaches a `subscribe` stream, which is
+      // where someone watching a live engine wants it; it is only kept out
+      // of the file unless EDGE_CLI_LOG_LEVEL asks for it.
+      if (type !== 'info' || process.env.EDGE_CLI_LOG_LEVEL === 'info') {
+        opts.logger?.write(type, event.message, { source: event.source })
+      }
+      opts.events.emit('core.log', {
+        source: event.source,
+        message: event.message,
+        type: event.type
+      })
+    }
+  })
+
+  return {
+    context,
+    appId,
+    testMode,
+    directory,
+    servers,
+    pluginsInit,
+    currencyPluginIds
+  }
+}
diff --git a/src/cli/engine/nodeApiSigner.ts b/src/cli/engine/nodeApiSigner.ts
new file mode 100644
index 00000000000..9480cd33604
--- /dev/null
+++ b/src/cli/engine/nodeApiSigner.ts
@@ -0,0 +1,97 @@
+import type { EdgeApiSigner } from 'edge-core-js'
+import fs from 'fs'
+import path from 'path'
+
+/**
+ * Runtime XOR pad for the Node signer's embedded secret. The CLI gets its own
+ * id rather than reusing the mobile bundle id, so a CLI shard set cannot be
+ * lifted into a mobile build (or the reverse). Three places must agree, and
+ * `scripts/testNodeApiSigner.ts` fails if they drift:
+ *
+ *   - this constant, which `scripts/makeApiSigner.ts` bakes into the shards
+ *   - `EDGE_NODE_BUNDLE_ID` in the generated `edge_api_secret.h`
+ *   - the pad `edge_api_signer_napi.c` passes to `edge_api_hmac_sign`
+ *
+ * It is a local obfuscation detail only: nothing sends it to a server.
+ */
+export const NODE_API_SIGNER_BUNDLE_ID = 'app.edge.cli'
+
+interface EdgeApiSignerNative {
+  signMessage: (message: string) => {
+    apiKey: string
+    signature: string
+  }
+  getApiKey: () => string
+}
+
+let cachedNative: EdgeApiSignerNative | null | undefined
+
+function candidatePaths(): string[] {
+  const here = __dirname
+  return [
+    // Dev: built next to binding.gyp
+    path.join(
+      here,
+      '../../../native/edge-api-signer/node/build/Release/edge_api_signer.node'
+    ),
+    path.join(
+      here,
+      '../../../../native/edge-api-signer/node/build/Release/edge_api_signer.node'
+    ),
+    // Published CLI: .node shipped beside the rolled-up engine
+    path.join(here, 'edge_api_signer.node'),
+    path.join(here, '../edge_api_signer.node')
+  ]
+}
+
+/**
+ * Lazily load the N-API addon. Returns null when the binary is missing so
+ * local/dev CLI can keep using keys.json apiKey/apiSecret.
+ */
+function loadNodeApiSignerNative(): EdgeApiSignerNative | null {
+  if (cachedNative !== undefined) return cachedNative
+
+  for (const candidate of candidatePaths()) {
+    try {
+      if (!fs.existsSync(candidate)) continue
+      // Native addon — loaded at runtime when the .node binary exists.
+      const mod = require(candidate) as EdgeApiSignerNative
+      if (typeof mod.signMessage === 'function') {
+        cachedNative = mod
+        return cachedNative
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(
+        `[edge-engine] failed to load Edge API signer at ${candidate}: ${message}`
+      )
+    }
+  }
+
+  cachedNative = null
+  return null
+}
+
+export function hasNodeApiSigner(): boolean {
+  return loadNodeApiSignerNative() != null
+}
+
+/**
+ * EdgeContextOptions.apiSigner backed by the Node N-API addon.
+ */
+export function makeNodeApiSigner(): EdgeApiSigner {
+  const native = loadNodeApiSignerNative()
+  if (native == null) {
+    throw new Error('EdgeApiSigner Node native module is not available')
+  }
+  return {
+    async signMessage(message: string) {
+      return native.signMessage(message)
+    }
+  }
+}
+
+/** Test helper: clear the cached require result. */
+export function resetNodeApiSignerCacheForTests(): void {
+  cachedNative = undefined
+}
diff --git a/src/cli/engine/objectHandles.ts b/src/cli/engine/objectHandles.ts
new file mode 100644
index 00000000000..792868bd4c1
--- /dev/null
+++ b/src/cli/engine/objectHandles.ts
@@ -0,0 +1,381 @@
+/**
+ * Ephemeral handles for core objects that expose methods.
+ *
+ * In the core JS API, identity is "the object reference." Over HTTP that
+ * does not work, so the engine stores the live value under an `objectId` and
+ * deletes it after OBJECT_HANDLE_TTL_MS (5 minutes) from create/update, or
+ * sooner when the caller finishes (e.g. save-tx) or explicitly deletes the
+ * handle. Reads do not refresh the TTL; only `update` does.
+ *
+ * Holds the four kinds in `ObjectHandleKind`: a staged `transaction` from
+ * makeSpend, a `pendingLogin` from requestEdgeLogin, a `swap` quote, and a
+ * `lobby` — anything core returns that you later call methods on, and so
+ * cannot cross JSON.
+ */
+import crypto from 'crypto'
+
+import { base58 } from '../../util/encoding'
+import type { PeriodicTask } from '../../util/PeriodicTask'
+import { engineError } from './errors'
+import { makeSweepTicker } from './sweepTicker'
+
+/**
+ * How long a bulk release waits for a handle that is mid-call.
+ *
+ * Long enough for a broadcast to finish, short enough that a wedged plugin
+ * call cannot keep the process alive. The engine's own shutdown drain is the
+ * outer bound.
+ */
+const BUSY_WAIT_MS = 10_000
+
+/** Default TTL for method-bearing core object handles. */
+export const OBJECT_HANDLE_TTL_MS = 5 * 60 * 1000
+
+export type ObjectHandleKind = 'transaction' | 'pendingLogin' | 'swap' | 'lobby'
+
+export interface ObjectHandleInfo {
+  objectId: string
+  kind: ObjectHandleKind
+  /** When the handle was created. */
+  createdAt: string
+  expiresAt: string
+  sessionId?: string
+  walletId?: string
+}
+
+export interface HandleRecord<T = unknown> {
+  objectId: string
+  kind: ObjectHandleKind
+  value: T
+  sessionId?: string
+  walletId?: string
+  createdAt: number
+  expiresAt: number
+  /** The handle's own window, so a refresh cannot silently promote it. */
+  ttlMs: number
+  onExpire?: (value: T) => void | Promise<void>
+  /**
+   * Set while a consuming call is in flight. A handle whose operation moves
+   * funds must not be usable twice, and the operation outlives the client's
+   * socket timeout, so a retry would otherwise find the handle still present.
+   */
+  consuming?: boolean
+}
+
+function makeObjectId(prefix: string): string {
+  return prefix + base58.stringify(crypto.randomBytes(12))
+}
+
+export class ObjectHandleStore {
+  private readonly handles = new Map<string, HandleRecord>()
+  private ticker: PeriodicTask | null = null
+
+  get size(): number {
+    return this.handles.size
+  }
+
+  /**
+   * Handles that nothing else is holding the engine open for.
+   *
+   * Every handle kind but one implies a session, and a session already holds
+   * the engine. `requestEdgeLogin` needs no session — `/request-edge-login`
+   * is not account-scoped — and its handle's TTL is exactly the default idle
+   * timeout, so the `--no-wait` flow the route documents left the engine with
+   * nothing to hold it and the idle timer tore the context down under the
+   * lobby the user was still showing a QR code for.
+   */
+  get sessionlessCount(): number {
+    let n = 0
+    for (const record of this.handles.values()) {
+      if (record.sessionId == null) n++
+    }
+    return n
+  }
+
+  /** Notified whenever a handle is created or released. */
+  onHandlesChanged: (() => void) | null = null
+
+  private handlesChanged(): void {
+    try {
+      this.onHandlesChanged?.()
+    } catch {
+      // A listener must never break handle creation or release.
+    }
+  }
+
+  startTicker(): void {
+    if (this.ticker != null) return
+    this.ticker = makeSweepTicker('handle sweep', async () => {
+      await this.sweep()
+    })
+    this.ticker.start()
+  }
+
+  stopTicker(): void {
+    if (this.ticker != null) {
+      this.ticker.stop()
+      this.ticker = null
+    }
+  }
+
+  /**
+   * Release every handle a session owned.
+   *
+   * Called on logout: a `swap_` handle holds a live `EdgeSwapQuote` whose
+   * `onExpire` closes the order, and a staged `tx_` handle holds a signed
+   * transaction, so left behind they outlive their account for the rest of
+   * the TTL with nothing able to release them earlier.
+   */
+  async deleteBySession(sessionId: string): Promise<void> {
+    const ids = [...this.handles.entries()]
+      .filter(([, record]) => record.sessionId === sessionId)
+      .map(([id]) => id)
+    await this.deleteMany(ids, `session ${sessionId.slice(0, 10)}`)
+  }
+
+  async clearAll(): Promise<void> {
+    await this.deleteMany([...this.handles.keys()], 'engine shutdown')
+  }
+
+  /**
+   * Release a set of handles, waiting for any that are mid-call.
+   *
+   * The bulk paths used to call `delete` straight away, which does not test
+   * `consuming` — so they bypassed the invariant the rest of the store
+   * honours, and `objectHandles.test.ts` asserts. Two states reached it: a
+   * `logout` from a second shell while `approve-swap-quote` was inside
+   * `consume`, which ran `onExpire` → `quote.close()` on a quote mid-approve;
+   * and a shutdown during a `broadcast-tx`, which released the handle under
+   * the call so `txHandleResponse` answered 404 after the money had left.
+   *
+   * Bounded, because a wedged call must not stop the engine exiting, and the
+   * abandonment is logged rather than silent.
+   */
+  private async deleteMany(ids: string[], why: string): Promise<void> {
+    const deadline = Date.now() + BUSY_WAIT_MS
+    const abandoned: string[] = []
+    for (const id of ids) {
+      while (this.handles.get(id)?.consuming === true) {
+        if (Date.now() > deadline) break
+        await new Promise(resolve => setTimeout(resolve, 50))
+      }
+      if (this.handles.get(id)?.consuming === true) {
+        abandoned.push(id)
+        continue
+      }
+      await this.delete(id)
+    }
+    if (abandoned.length > 0) {
+      console.warn(
+        `[edge-engine] ${why}: gave up waiting for ${abandoned.join(
+          ', '
+        )} after ${BUSY_WAIT_MS}ms; left in place`
+      )
+    }
+  }
+
+  create<T>(opts: {
+    kind: ObjectHandleKind
+    prefix: string
+    value: T
+    sessionId?: string
+    walletId?: string
+    onExpire?: (value: T) => void | Promise<void>
+    ttlMs?: number
+  }): ObjectHandleInfo & { value: T } {
+    const ttlMs = opts.ttlMs ?? OBJECT_HANDLE_TTL_MS
+    const now = Date.now()
+    const objectId = makeObjectId(opts.prefix)
+    const record: HandleRecord<T> = {
+      objectId,
+      kind: opts.kind,
+      value: opts.value,
+      sessionId: opts.sessionId,
+      walletId: opts.walletId,
+      createdAt: now,
+      expiresAt: now + ttlMs,
+      ttlMs,
+      onExpire: opts.onExpire
+    }
+    this.handles.set(objectId, record as HandleRecord)
+    this.handlesChanged()
+    return {
+      objectId,
+      kind: opts.kind,
+      createdAt: new Date(record.createdAt).toISOString(),
+      expiresAt: new Date(record.expiresAt).toISOString(),
+      sessionId: opts.sessionId,
+      walletId: opts.walletId,
+      value: opts.value
+    }
+  }
+
+  get<T>(objectId: string, kind?: ObjectHandleKind): HandleRecord<T> {
+    const record = this.handles.get(objectId)
+    if (record == null) {
+      throw engineError(
+        'OBJECT_NOT_FOUND',
+        `No object handle: ${objectId}`,
+        404
+      )
+    }
+    // Before expiry: a handle whose operation is still running has not
+    // expired, it is busy. Reporting it as expired would also release it, and
+    // releasing runs `onExpire` — for a swap that is `quote.close()` on a
+    // quote that is mid-approval.
+    if (record.consuming === true) {
+      throw engineError(
+        'OBJECT_IN_USE',
+        `Object handle is already being consumed: ${objectId}`,
+        409
+      )
+    }
+    if (Date.now() > record.expiresAt) {
+      // Logged, not discarded: `delete` runs `onExpire`, which for a swap
+      // closes the quote at the exchange.
+      this.delete(objectId).catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        console.warn(
+          `[edge-engine] releasing handle ${objectId} failed: ${message}`
+        )
+      })
+      throw engineError(
+        'OBJECT_EXPIRED',
+        `Object handle expired: ${objectId}`,
+        410
+      )
+    }
+    if (kind != null && record.kind !== kind) {
+      throw engineError(
+        'OBJECT_KIND_MISMATCH',
+        `Expected kind ${kind}, got ${record.kind}`,
+        400
+      )
+    }
+    return record as HandleRecord<T>
+  }
+
+  /**
+   * Run a consuming operation under an in-flight guard, releasing the handle
+   * whether it succeeds or fails.
+   *
+   * `get` rejects the handle with `OBJECT_IN_USE` for as long as `operation`
+   * runs, so a client that retries after its own socket timeout cannot start
+   * the same fund-moving call twice.
+   *
+   * A failure releases too, because from outside the plugin there is no way
+   * to tell a failure before the money moved from one after. A swap
+   * `approve()` signs, broadcasts, and then does post-broadcast bookkeeping;
+   * an error from that last step used to unlock the handle, so a retry of
+   * `approve-swap-quote` re-signed and re-broadcast — on an account-based
+   * chain, a second real transfer of the user's funds. Releasing means a
+   * retry answers `OBJECT_NOT_FOUND` and the caller has to fetch a fresh
+   * quote, which is the only safe reading of an ambiguous failure.
+   *
+   * A call that genuinely does not consume its handle uses `hold` instead.
+   */
+  async consume<T, R>(
+    record: HandleRecord<T>,
+    operation: (value: T) => Promise<R>
+  ): Promise<R> {
+    record.consuming = true
+    // Push the expiry out before the await, not after. A core call can take
+    // minutes, and an expiry that lands mid-call would otherwise release the
+    // handle and run `onExpire` underneath the operation. The sweeper skips a
+    // consuming record as well, because an operation can outlive even a
+    // refreshed window.
+    record.expiresAt = Date.now() + record.ttlMs
+    try {
+      return await operation(record.value)
+    } finally {
+      await this.delete(record.objectId)
+    }
+  }
+
+  /**
+   * Hold a handle open across a call that does not consume it.
+   *
+   * `broadcast-tx` and `sign-tx` keep their handle afterwards, but their core
+   * call can outlive the TTL: the expiry was checked on the way *out*, through
+   * `update`, so a broadcast that crossed the boundary threw `OBJECT_EXPIRED`
+   * after the money had already left — no txid in the response, no handle left
+   * to `save-tx` with, and the transaction missing from local history until a
+   * sync found it.
+   */
+  async hold<T, R>(
+    record: HandleRecord<T>,
+    operation: (value: T) => Promise<R>
+  ): Promise<R> {
+    record.consuming = true
+    record.expiresAt = Date.now() + record.ttlMs
+    try {
+      return await operation(record.value)
+    } finally {
+      record.consuming = false
+      record.expiresAt = Date.now() + record.ttlMs
+    }
+  }
+
+  /**
+   * Replace the stored value and refresh the TTL (another full window).
+   */
+  update<T>(
+    objectId: string,
+    value: T,
+    opts?: { ttlMs?: number }
+  ): ObjectHandleInfo {
+    // Deliberately not `get`: the caller already holds this record, and a
+    // handle being written to is not a handle to reject as busy or expired.
+    const record = this.handles.get(objectId) as HandleRecord<T> | undefined
+    if (record == null) {
+      throw engineError(
+        'OBJECT_NOT_FOUND',
+        `No object handle: ${objectId}`,
+        404
+      )
+    }
+    const ttlMs = opts?.ttlMs ?? record.ttlMs
+    record.value = value
+    record.ttlMs = ttlMs
+    record.expiresAt = Date.now() + ttlMs
+    return this.toInfo(record)
+  }
+
+  toInfo<T = unknown>(record: HandleRecord<T>): ObjectHandleInfo {
+    return {
+      objectId: record.objectId,
+      kind: record.kind,
+      createdAt: new Date(record.createdAt).toISOString(),
+      expiresAt: new Date(record.expiresAt).toISOString(),
+      sessionId: record.sessionId,
+      walletId: record.walletId
+    }
+  }
+
+  async delete(objectId: string): Promise<boolean> {
+    const record = this.handles.get(objectId)
+    if (record == null) return false
+    this.handles.delete(objectId)
+    this.handlesChanged()
+    if (record.onExpire != null) {
+      try {
+        await record.onExpire(record.value)
+      } catch {
+        // best effort
+      }
+    }
+    return true
+  }
+
+  private async sweep(): Promise<void> {
+    const now = Date.now()
+    for (const [id, record] of this.handles) {
+      // A busy handle is never swept: `delete` runs `onExpire`, which for a
+      // swap closes the quote at the exchange.
+      if (record.consuming === true) continue
+      if (now > record.expiresAt) {
+        await this.delete(id)
+      }
+    }
+  }
+}
diff --git a/src/cli/engine/readJsonConfig.ts b/src/cli/engine/readJsonConfig.ts
new file mode 100644
index 00000000000..21494770b3b
--- /dev/null
+++ b/src/cli/engine/readJsonConfig.ts
@@ -0,0 +1,58 @@
+/**
+ * Read one JSON config file through a cleaner.
+ *
+ * `appConfig.ts` and `keysConfig.ts` each had the same twenty-odd
+ * statements in the same order — `readFileSync` → `isMissingFile` → null,
+ * `JSON.parse` → "Invalid JSON in <path>", cleaner → "Invalid <label> at
+ * <path>" — differing only in the cleaner and one word of each message, and
+ * `cliConfig.ts` was a third hand-rolled variant of the same read.
+ *
+ * An absent file is `null`, which is what the search-path loop above each
+ * caller treats as "try the next one". Anything else throws, naming the file
+ * and the field: a config this version cannot read must not be answered with
+ * silent defaults, because the values in it decide which servers the engine
+ * talks to.
+ */
+import type { Cleaner } from 'cleaners'
+import fs from 'fs'
+import { resolve } from 'path'
+
+import { isMissingFile } from '../../util/predicates'
+import { cliHomeFile } from './cliHome'
+
+export function readJsonConfig<T>(
+  path: string,
+  cleaner: Cleaner<T>,
+  label: string
+): T | null {
+  let text: string
+  try {
+    text = fs.readFileSync(path, 'utf8')
+  } catch (error: unknown) {
+    if (isMissingFile(error)) return null
+    throw error
+  }
+  let json: unknown
+  try {
+    json = JSON.parse(text)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid JSON in ${path}: ${message}`)
+  }
+  try {
+    return cleaner(json)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid ${label} at ${path}: ${message}`)
+  }
+}
+
+/**
+ * Where a config file is looked for, in order.
+ *
+ * The working directory first, so a checkout or a container can override,
+ * then the CLI's own home.
+ */
+export function configSearchPaths(filename: string): string[] {
+  return [resolve(`./${filename}`), cliHomeFile(filename)]
+}
diff --git a/src/cli/engine/resolve.ts b/src/cli/engine/resolve.ts
new file mode 100644
index 00000000000..462d9c32a94
--- /dev/null
+++ b/src/cli/engine/resolve.ts
@@ -0,0 +1,88 @@
+import type { EdgeAccount, EdgeCurrencyWallet, EdgeTokenId } from 'edge-core-js'
+
+import { getExchangeDenom } from '../../util/exchangeDenom'
+import { hasOwn } from '../../util/predicates'
+import { engineError } from './errors'
+
+/**
+ * Resolve a wallet id or unique prefix against account.currencyWallets.
+ */
+export function findWallet(
+  account: EdgeAccount,
+  prefix: string
+): EdgeCurrencyWallet {
+  // Belt and braces with `asWalletId`: `''` is a prefix of every wallet, so
+  // on a single-wallet account it would resolve to that wallet rather than
+  // reporting a missing field — and this function is what `spend` resolves
+  // through.
+  if (prefix === '') {
+    throw engineError('BAD_REQUEST', 'walletId must not be empty', 400)
+  }
+  const wallets = account.currencyWallets
+  // `hasOwn`, not `wallets[prefix] != null`. `currencyWallets` is a plain
+  // object literal, so `wallets['__proto__']` is `Object.prototype` and that
+  // test passed: `--wallet-id=__proto__` returned the prototype cast as an
+  // `EdgeCurrencyWallet` and the first `wallet.currencyInfo.pluginId` was a
+  // `TypeError` — `500 INTERNAL_ERROR` where this function's whole job is to
+  // answer `WALLET_NOT_FOUND`. `constructor`, `toString`, `valueOf` and the
+  // rest behave the same way.
+  if (hasOwn(wallets, prefix)) return wallets[prefix]
+
+  const matches = Object.keys(wallets).filter(id => id.startsWith(prefix))
+  if (matches.length === 0) {
+    throw engineError(
+      'WALLET_NOT_FOUND',
+      `No wallet found matching: ${prefix}`,
+      404
+    )
+  }
+  if (matches.length > 1) {
+    throw engineError(
+      'AMBIGUOUS_WALLET_ID',
+      `Ambiguous wallet ID "${prefix}"`,
+      409,
+      { candidates: matches }
+    )
+  }
+  return wallets[matches[0]]
+}
+
+/**
+ * Refuse a tokenId the wallet's plugin does not know.
+ *
+ * Over REST a tokenId is free-form caller input, where in the GUI it always
+ * came from a real token. Core does not check it: `wallet.getTransactions`,
+ * `getNumTransactions` and `getAddresses` all destructure the token's own
+ * record and throw a `TypeError` that surfaces as `500 INTERNAL_ERROR` with
+ * no field name, outside every error list those routes declare.
+ */
+export function assertTokenId(
+  wallet: EdgeCurrencyWallet,
+  tokenId: EdgeTokenId
+): void {
+  if (tokenId == null) return
+  // `hasOwn`: `allTokens` is a plain object literal built with a spread, so
+  // `allTokens['__proto__'] == null` is **false** and this guard returned
+  // without throwing — which defeats the entire function, as the comment
+  // above describes.
+  if (!hasOwn(wallet.currencyConfig.allTokens, tokenId)) {
+    throw engineError('TOKEN_NOT_FOUND', `Unknown token: ${tokenId}`, 404)
+  }
+}
+
+/**
+ * The multiplier an asset reports amounts in.
+ *
+ * Through `getExchangeDenom`, which this branch added and which already
+ * answers exactly this: the hand-rolled `denominations[0]?.multiplier ?? '1'`
+ * was written out twice here. The `TOKEN_NOT_FOUND` throw is kept, because
+ * `getExchangeDenom`'s own fallback for an unknown token is a multiplier of
+ * `1`, which is a silently wrong number rather than an error.
+ */
+export function getMultiplier(
+  wallet: EdgeCurrencyWallet,
+  tokenId: EdgeTokenId
+): string {
+  assertTokenId(wallet, tokenId)
+  return getExchangeDenom(wallet.currencyConfig, tokenId).multiplier
+}
diff --git a/src/cli/engine/route.ts b/src/cli/engine/route.ts
new file mode 100644
index 00000000000..b1064fee77d
--- /dev/null
+++ b/src/cli/engine/route.ts
@@ -0,0 +1,282 @@
+/**
+ * A single API call: one typed function, its cleaners, and the prose above it.
+ *
+ * The JSDoc comment on each `route(…)` call is the documentation source. The
+ * `query` / `body` cleaners validate the request *and* describe it — the
+ * documented shape is the enforced shape, so the two cannot disagree. The
+ * `returns` cleaner does the same for the response.
+ *
+ * `scripts/buildApiDocs.ts` reads these declarations with the TypeScript
+ * compiler API: the resolved cleaner types render the request and response
+ * shapes, and the JSDoc supplies the prose.
+ */
+import type { Cleaner } from 'cleaners'
+
+import { engineError } from './errors'
+import { requireBodyObject, type RouteContext, type Router } from './router'
+
+export type HttpMethod = 'GET' | 'POST'
+
+/** How a CLI flag differs from the field it carries. */
+export interface CliFlagSpec {
+  /** Request field this flag supplies, when the names differ. */
+  maps?: string
+  /** Repeatable; collected into an array. */
+  repeat?: boolean
+  doc?: string
+}
+
+/** A flag with no request counterpart — purely client-side behaviour. */
+export interface CliExtraSpec {
+  kind: 'string' | 'boolean' | 'boolstr' | 'repeat'
+  required?: boolean
+  /** Required whenever this request field is present. */
+  requiredWith?: string
+  doc?: string
+}
+
+export interface CliSpec {
+  command: string
+  /**
+   * Request field taken as the bare positional argument.
+   *
+   * A positional also decides the REST path: it becomes the final path
+   * segment, so `<objectId>` on the command line and `{objectId}` in the URL
+   * are the same value declared once. `routePath` derives that, which is why
+   * `path` must not spell the parameter out itself.
+   *
+   * Only base58 identifiers qualify. A value that can contain `/`, `?` or `#`
+   * — a base64 wallet id, a free-text username — cannot be a path segment
+   * without percent-encoding that callers forget, so it travels as a named
+   * argument in the query or the body instead.
+   */
+  positional?: string
+  /** Overrides for flags whose name is not the kebab-cased field name. */
+  flags?: Record<string, CliFlagSpec>
+  /** Client-only flags. */
+  extra?: Record<string, CliExtraSpec>
+  /** Fields sent at fixed values, for commands that preset part of a body. */
+  preset?: Record<string, unknown>
+  /** Flag carrying the entire body as one JSON argument. */
+  bodyFlag?: string
+  /** Exit codes for a streaming command. */
+  exits?: Record<string, number>
+  /** Behaviour the request shape cannot express. */
+  notes?: string
+  /**
+   * This binding's own one-line summary.
+   *
+   * Two commands on one route otherwise share the route's JSDoc first line,
+   * so `spend` and `spend-max` were both published as "Send funds."
+   */
+  summary?: string
+  /**
+   * Hand-written because the command does something the request shape cannot
+   * describe — writing files, storing a session, holding a stream open.
+   * Everything else is generated from this spec.
+   */
+  custom?: boolean
+}
+
+/**
+ * A route that holds a stream open rather than answering once.
+ *
+ * `extractRoutes` records only *whether* `stream` is present — that is what
+ * makes `buildCliCommands` skip it and what the reference uses to mark it —
+ * so the fields below reach no generated output. The frame list a reader
+ * sees is the `@note` on the route's own JSDoc, which is also where the
+ * scoping rules are written, because the scope comes from the query string
+ * and so cannot be a constant here.
+ *
+ * Declared all the same, because the shape is part of the declaration format
+ * and an empty marker would read as an oversight. A field here that looked
+ * like it reached the reference and did not was worse: `scope: 'context'`
+ * was stale the moment the route started honouring `?sessionId=`.
+ */
+export interface StreamSpec {
+  /** Present to mark the route as a stream; nothing reads the value. */
+  marker: true
+}
+
+export interface RouteSpec<Q = unknown, B = unknown, R = unknown> {
+  /** The `edge-core-js` call this fronts, or null with a `coreNote`. */
+  core: string | null
+  coreNote?: string
+  /**
+   * Request fields the core call has no parameter for, and why.
+   *
+   * The API is core's signature in another representation, so a field core
+   * does not know about is either a deliberate convenience or a mistake.
+   * Writing the reason is what tells the two apart: `currency-wallets` once
+   * carried a `waitForAll` that core has no parameter for — waiting is a
+   * separate method — and nothing caught it.
+   *
+   * `checkCoreAlignment` resolves the real signature and fails on a
+   * difference that is not listed here, or a listing that is no longer true.
+   */
+  coreExtra?: Record<string, string>
+  method: HttpMethod
+  path: string
+  /** Command name, a spec, or several when one route backs more than one. */
+  cli?: string | CliSpec | CliSpec[] | null
+  query?: Cleaner<Q>
+  body?: Cleaner<B>
+  /** Response shape. Omit for a `204`. */
+  returns?: Cleaner<R>
+  /** Codes raised indirectly; directly-thrown ones are read from the handler. */
+  errors?: string[]
+  /** Set when the stream is served outside the router. */
+  stream?: StreamSpec
+  handler: (ctx: TypedContext<Q, B>) => Promise<unknown> | unknown
+}
+
+/** A `RouteContext` whose query and body have been through their cleaners. */
+export interface TypedContext<Q, B> extends Omit<RouteContext, 'body'> {
+  query: URLSearchParams & { valid: Q }
+  body: B
+}
+
+const registry: Array<RouteSpec<any, any, any>> = []
+
+export function route<Q, B, R>(spec: RouteSpec<Q, B, R>): RouteSpec<Q, B, R> {
+  registry.push(spec)
+  return spec
+}
+
+export function allRoutes(): Array<RouteSpec<any, any, any>> {
+  return registry
+}
+
+/**
+ * How hard a response that fails its own `returns` cleaner should land.
+ *
+ * A mismatch is a documentation bug: the reference says one shape and the
+ * engine sends another. It is never the caller's fault, so the default is to
+ * log it and send the response through untouched rather than fail a request
+ * that would otherwise have worked. Tests set `strict` to turn drift into a
+ * failure, and `off` skips the check.
+ */
+type ResponseCheckMode = 'warn' | 'strict' | 'off'
+
+function responseCheckMode(): ResponseCheckMode {
+  const raw = process.env.EDGE_CLI_CHECK_RESPONSES
+  if (raw === 'strict' || raw === '1') return 'strict'
+  if (raw === 'off' || raw === '0') return 'off'
+  return 'warn'
+}
+
+/**
+ * Confirms a response matches the cleaner that documents it.
+ *
+ * The cleaned value is discarded. Response cleaners strip unknown keys, so
+ * returning it would quietly delete fields the engine means to send — the
+ * check exists to report drift, not to reshape anything.
+ */
+function checkResponse(
+  spec: RouteSpec<any, any, any>,
+  ctx: RouteContext,
+  response: unknown
+): void {
+  if (spec.returns == null) return
+  const mode = responseCheckMode()
+  if (mode === 'off') return
+  try {
+    spec.returns(response)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    const detail = `${spec.method} ${spec.path} response does not match its documented type: ${message}`
+    if (mode === 'strict') throw engineError('INTERNAL_ERROR', detail, 500)
+    ctx.state.logger.warn('Response type mismatch', {
+      route: `${spec.method} ${spec.path}`,
+      message
+    })
+  }
+}
+
+/** Turn a cleaner failure into a `400` instead of a `500`. */
+function clean<T>(cleaner: Cleaner<T>, raw: unknown, what: string): T {
+  try {
+    return cleaner(raw)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw engineError('BAD_REQUEST', `Invalid ${what}: ${message}`, 400)
+  }
+}
+
+/**
+ * Query strings are all strings; coerce to what the cleaner expects.
+ *
+ * `?x=` means the parameter is absent, and this is the one layer that decides
+ * that — so a required field reports as missing rather than arriving as `''`,
+ * and `asOptional`'s fallback applies. Downstream code must not re-interpret
+ * `''`: three such branches existed and none of them could fire.
+ */
+function queryToObject(query: URLSearchParams): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of query.entries()) {
+    if (value === '') continue
+    out[key] = value
+  }
+  return out
+}
+
+/**
+ * The URL a route actually answers on.
+ *
+ * `path` carries the scope — the account, the wallet, the handle — and the
+ * command. A positional argument is appended to it, so the REST path reads in
+ * the same order the command does: `wallet/get-addresses/{walletId}` for
+ * `get-addresses <walletId>`. Named arguments stay in the query or the body.
+ */
+export function routePath(spec: RouteSpec<any, any, any>): string {
+  const positional = positionalParam(spec)
+  return positional == null ? spec.path : `${spec.path}/{${positional}}`
+}
+
+/** The field a route carries on the path, or null when it takes none. */
+function positionalParam(spec: RouteSpec<any, any, any>): string | null {
+  const cli = spec.cli
+  if (cli == null || typeof cli === 'string' || Array.isArray(cli)) return null
+  if (cli.positional == null) return null
+  return cli.positional
+}
+
+export function registerRoute(
+  router: Router,
+  spec: RouteSpec<any, any, any>
+): void {
+  if (spec.stream != null) return // served directly by the HTTP handler
+  const positional = positionalParam(spec)
+  router.add(spec.method, routePath(spec), async ctx => {
+    // The positional arrives as a path segment, but it is declared as an
+    // ordinary field, so it is folded back in before the cleaner runs. The
+    // handler reads it from the same place whichever transport it came over.
+    const fromPath = (raw: Record<string, unknown>): Record<string, unknown> =>
+      positional == null
+        ? raw
+        : { ...raw, [positional]: ctx.params[positional] }
+
+    if (spec.query != null) {
+      const parsed = clean(
+        spec.query,
+        fromPath(queryToObject(ctx.query)),
+        'query'
+      )
+      ;(ctx.query as any).valid = parsed
+    }
+    if (spec.body != null) {
+      // A POST whose every field rides on the path has nothing left to send,
+      // so an absent body means an empty one. A body that is present but not
+      // an object is still a bad request, and the cleaner reports any field
+      // that is genuinely missing.
+      const raw =
+        spec.method === 'GET' || ctx.body == null
+          ? {}
+          : requireBodyObject(ctx.body)
+      ctx.body = clean(spec.body, fromPath(raw), 'body')
+    }
+    const response = await spec.handler(ctx as any)
+    checkResponse(spec, ctx, response)
+    return response
+  })
+}
diff --git a/src/cli/engine/router.ts b/src/cli/engine/router.ts
new file mode 100644
index 00000000000..da22e9fb4c3
--- /dev/null
+++ b/src/cli/engine/router.ts
@@ -0,0 +1,121 @@
+/**
+ * Method and path dispatch, and the shared engine state every route reads.
+ *
+ * The matching is deliberately small: `{param}` becomes `([^/]+)`, literal
+ * segments are escaped, and a parameter is decoded with the failure reported
+ * as the caller's rather than the engine's. Anything about what a route
+ * *means* — its cleaners, its errors, its prose — lives on the `route()`
+ * declaration in `route.ts`.
+ */
+import type { IncomingMessage, ServerResponse } from 'http'
+
+import { isPlainObject } from '../../util/predicates'
+import { engineError } from './errors'
+import type { EventHub } from './events'
+import type { IdleShutdown } from './idleShutdown'
+import type { EngineLogger } from './logger'
+import type { CoreContextBundle } from './makeCoreContext'
+import type { ObjectHandleStore } from './objectHandles'
+import type { SessionStore } from './sessions'
+
+export interface EngineState {
+  core: CoreContextBundle
+  sessions: SessionStore
+  objects: ObjectHandleStore
+  events: EventHub
+  idle: IdleShutdown
+  logger: EngineLogger
+  profile: string
+  socketPath: string
+  tcpPort: number | null
+  startedAt: number
+  shuttingDown: boolean
+  shutdown: () => Promise<void>
+  /**
+   * Handles a `shutdown()` that rejected.
+   *
+   * Set by the engine entry. A rejection after `shuttingDown` is set leaves
+   * the engine answering 503 forever with its socket still in place, so it
+   * has to be reported and the profile released rather than discarded.
+   */
+  onShutdownFailure: (error: unknown) => void
+}
+
+export interface RouteContext {
+  state: EngineState
+  req: IncomingMessage
+  res: ServerResponse
+  params: Record<string, string>
+  query: URLSearchParams
+  body: unknown
+}
+
+export type RouteHandler = (ctx: RouteContext) => Promise<unknown> | unknown
+
+export interface CompiledRoute {
+  method: string
+  regex: RegExp
+  keys: string[]
+  handler: RouteHandler
+}
+
+function compile(pattern: string): { regex: RegExp; keys: string[] } {
+  const keys: string[] = []
+  const parts = pattern.split('/').map(part => {
+    if (part.startsWith('{') && part.endsWith('}')) {
+      keys.push(part.slice(1, -1))
+      return '([^/]+)'
+    }
+    return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  })
+  return {
+    regex: new RegExp('^' + parts.join('/') + '$'),
+    keys
+  }
+}
+
+export class Router {
+  private readonly routes: CompiledRoute[] = []
+
+  add(method: string, pattern: string, handler: RouteHandler): void {
+    const { regex, keys } = compile(pattern)
+    this.routes.push({ method: method.toUpperCase(), regex, keys, handler })
+  }
+
+  match(
+    method: string,
+    pathname: string
+  ): { handler: RouteHandler; params: Record<string, string> } | null {
+    const m = method.toUpperCase()
+    for (const route of this.routes) {
+      if (route.method !== m) continue
+      const match = route.regex.exec(pathname)
+      if (match == null) continue
+      const params: Record<string, string> = {}
+      route.keys.forEach((key, i) => {
+        try {
+          params[key] = decodeURIComponent(match[i + 1])
+        } catch {
+          // `new URL()` accepts a malformed percent-escape and
+          // `decodeURIComponent` then throws `URIError`, which reached the
+          // handler's catch-all as a 500 — a caller's bad URL reported as an
+          // engine fault, on routes whose declared errors are 400 and 404.
+          throw engineError(
+            'BAD_REQUEST',
+            `Malformed path parameter "${key}"`,
+            400
+          )
+        }
+      })
+      return { handler: route.handler, params }
+    }
+    return null
+  }
+}
+
+export function requireBodyObject(body: unknown): Record<string, unknown> {
+  if (!isPlainObject(body)) {
+    throw engineError('BAD_REQUEST', 'JSON object body required', 400)
+  }
+  return body
+}
diff --git a/src/cli/engine/routes/account.ts b/src/cli/engine/routes/account.ts
new file mode 100644
index 00000000000..a06e0ecb584
--- /dev/null
+++ b/src/cli/engine/routes/account.ts
@@ -0,0 +1,401 @@
+import {
+  asArray,
+  asBoolean,
+  asEither,
+  asObject,
+  asOptional,
+  asString,
+  asValue
+} from 'cleaners'
+import type { EdgeAccount, EdgeCurrencyWallet } from 'edge-core-js'
+
+import { doc } from '../doc'
+import { route } from '../route'
+import {
+  asCoreValue,
+  asCreateCurrencyWallet,
+  asSession,
+  asWalletSummary
+} from '../schemas'
+import { getAccount, getSession, summarizeWallet } from './helpers'
+
+/** Which of the account's three wallet lists to read. */
+const asWalletFilter = asValue('active', 'archived', 'hidden', 'all')
+type WalletFilter = ReturnType<typeof asWalletFilter>
+
+function walletIdsForFilter(
+  account: EdgeAccount,
+  filter: WalletFilter
+): string[] {
+  switch (filter) {
+    case 'archived':
+      return account.archivedWalletIds
+    case 'hidden':
+      return account.hiddenWalletIds
+    case 'all':
+      return [
+        ...account.activeWalletIds,
+        ...account.archivedWalletIds,
+        ...account.hiddenWalletIds
+      ]
+    case 'active':
+    default:
+      return account.activeWalletIds
+  }
+}
+
+/**
+ * Account and session summary.
+ *
+ * Session fields are spread at the top level alongside the account's own
+ * properties — there is no nested `session` object.
+ *
+ * @note The `otpEnabled` and `otpResetPending` flags here are derived. For the
+ *   secret itself use `otp-key`.
+ * @coreNote Engine composite of the session record plus EdgeAccount
+ *   properties.
+ */
+export const accountInfo = route({
+  core: null,
+  method: 'GET',
+  path: '/account/{sessionId}',
+  cli: 'account-info',
+  returns: asObject({
+    appId: doc(asString, 'Application this session logged into.'),
+    created: doc(
+      asEither(asString, asValue(null)),
+      'When the account was created, null for accounts predating the field.'
+    ),
+    lastLogin: doc(asString, 'The previous login, not this one.'),
+    loggedIn: doc(
+      asBoolean,
+      'False once the account has been logged out; the session object outlives it briefly.'
+    ),
+    recoveryKey: doc(
+      asEither(asString, asValue(null)),
+      'Present only while recovery is configured.'
+    ),
+    otpEnabled: doc(asBoolean, '2FA is on for this account.'),
+    otpResetPending: doc(
+      asBoolean,
+      'True while somebody has a reset pending against this account.'
+    ),
+    canDuressLogin: doc(
+      asBoolean,
+      'A duress PIN is configured, so this account can be opened in duress mode.'
+    ),
+    isDuressAccount: doc(
+      asBoolean,
+      'True when this very session is the duress account rather than the real one.'
+    ),
+    edgeLogin: doc(asBoolean, 'This account was reached by QR login.'),
+    keyLogin: doc(asBoolean, 'This session was reached with a login key.'),
+    newAccount: doc(
+      asBoolean,
+      'This session created the account rather than logging into an existing one.'
+    ),
+    passwordLogin: doc(asBoolean, 'This session was reached with a password.'),
+    pinLogin: doc(asBoolean, 'This session was reached with a PIN.'),
+    recoveryLogin: doc(
+      asBoolean,
+      'This session was reached by answering recovery questions.'
+    )
+  }).withRest,
+
+  handler(ctx) {
+    const session = getSession(ctx)
+    const { account } = session
+    const info = ctx.state.sessions.toInfo(session)
+    return {
+      ...info,
+      username: account.username,
+      rootLoginId: account.rootLoginId,
+      appId: account.appId,
+      created: account.created?.toISOString() ?? null,
+      lastLogin: account.lastLogin.toISOString(),
+      loggedIn: account.loggedIn,
+      recoveryKey: account.recoveryKey ?? null,
+      otpEnabled: account.otpKey != null,
+      otpResetPending: account.otpResetDate != null,
+      canDuressLogin: account.canDuressLogin,
+      isDuressAccount: account.isDuressAccount,
+      edgeLogin: account.edgeLogin,
+      keyLogin: account.keyLogin,
+      newAccount: account.newAccount,
+      passwordLogin: account.passwordLogin,
+      pinLogin: account.pinLogin,
+      recoveryLogin: account.recoveryLogin
+    }
+  }
+})
+
+/**
+ * Log out.
+ *
+ * Ends the session and drops it from the engine. Any subscription scoped to
+ * this account or its wallets is closed with it.
+ */
+export const logout = route({
+  core: 'account.logout',
+  method: 'POST',
+  path: '/account/{sessionId}/logout',
+  cli: {
+    command: 'logout',
+    custom: true,
+    notes: 'Also clears the stored id from `session.json`.'
+  },
+
+  async handler(ctx) {
+    await ctx.state.sessions.logout(ctx.params.sessionId)
+    return undefined
+  }
+})
+
+/**
+ * Keepalive.
+ *
+ * Resets the idle auto-logout timer without doing any other work.
+ *
+ * @coreNote Engine auto-logout timer; core has no idle concept.
+ */
+export const touchSession = route({
+  core: null,
+  method: 'POST',
+  path: '/account/{sessionId}/touch',
+  cli: 'touch',
+  returns: doc(asSession, 'The session, with a refreshed `expiresAt`.'),
+
+  handler(ctx) {
+    return ctx.state.sessions.touch(ctx.params.sessionId)
+  }
+})
+
+/**
+ * Read the account login key.
+ *
+ * The key `login-with-key` takes. It grants full account access, so treat the
+ * output as secret.
+ */
+export const getLoginKey = route({
+  core: 'account.getLoginKey',
+  method: 'GET',
+  path: '/account/{sessionId}/get-login-key',
+  cli: 'get-login-key',
+  returns: asObject({
+    loginKey: doc(asString, 'base58. Full account access — keep it safe.')
+  }),
+
+  async handler(ctx) {
+    return { loginKey: await getAccount(ctx).getLoginKey() }
+  }
+})
+
+/**
+ * Force an account data sync.
+ *
+ * Pushes and pulls the account repos immediately rather than waiting for the
+ * next scheduled sync.
+ */
+export const accountSync = route({
+  core: 'account.sync',
+  method: 'POST',
+  path: '/account/{sessionId}/sync',
+  cli: {
+    command: 'sync',
+    notes: 'Named `sync` for the account; the wallet one is `wallet-sync`.'
+  },
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).sync()
+    return undefined
+  }
+})
+
+/**
+ * Permanently delete the remote account.
+ *
+ * Irreversible. The account is removed from the login server, and funds in its
+ * wallets are unrecoverable without the keys. The session is logged out
+ * afterwards.
+ *
+ * @note The engine performs no confirmation check — the call runs as soon as
+ *   it arrives, so any guard has to live in the caller. The command requires
+ *   `--yes` for exactly this reason.
+ */
+export const deleteRemoteAccount = route({
+  core: 'account.deleteRemoteAccount',
+  method: 'POST',
+  path: '/account/{sessionId}/delete-remote-account',
+  cli: {
+    command: 'delete-remote-account',
+    custom: true,
+    extra: {
+      yes: {
+        kind: 'boolean',
+        required: true,
+        doc: 'Confirms intent. Without it the command refuses to run.'
+      }
+    }
+  },
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).deleteRemoteAccount()
+    await ctx.state.sessions.logout(ctx.params.sessionId)
+    return undefined
+  }
+})
+
+/**
+ * Wait for every wallet to finish loading.
+ *
+ * Wallets load in the background after login, so a list taken straight
+ * afterwards can be short. This resolves once each active wallet has either
+ * loaded or failed — balances may still be syncing afterwards.
+ *
+ * @note There is no timeout: a wallet that never resolves holds this open.
+ *   The engine's own idle shutdown does not fire while a request is in
+ *   flight, so give the client one.
+ * @note Nothing is returned. Call `currency-wallets` afterwards to see the
+ *   result, including any wallet that failed to load.
+ */
+export const waitForAllWallets = route({
+  core: 'account.waitForAllWallets',
+  method: 'POST',
+  path: '/account/{sessionId}/wait-for-all-wallets',
+  cli: 'wait-for-all-wallets',
+
+  async handler(ctx) {
+    await getAccount(ctx).waitForAllWallets()
+    return undefined
+  }
+})
+
+/**
+ * List the account's wallets.
+ *
+ * @note Wallets load in the background after login, so a list taken straight
+ *   afterwards can be short. Call `wait-for-all-wallets` first to be sure the
+ *   account has finished loading.
+ * @coreNote Filtered by account.activeWalletIds / archivedWalletIds /
+ *   hiddenWalletIds.
+ */
+export const currencyWallets = route({
+  core: 'account.currencyWallets',
+  coreExtra: {
+    filter:
+      'Core has no filter: it exposes activeWalletIds, archivedWalletIds and ' +
+      'hiddenWalletIds as separate lists. This picks between them.'
+  },
+  method: 'GET',
+  path: '/account/{sessionId}/currency-wallets',
+  cli: 'currency-wallets',
+  query: asObject({
+    filter: asOptional(
+      doc(
+        asWalletFilter,
+        'Which of the account\u2019s wallet lists to read. Defaults to `active`.'
+      )
+    )
+  }).withRest,
+  returns: asObject({
+    currencyWallets: doc(
+      asArray(asWalletSummary),
+      'Every wallet in the account, including paused ones.'
+    )
+  }),
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    const { filter = 'active' } = ctx.query.valid
+
+    const currencyWallets = walletIdsForFilter(account, filter)
+      .map(id => account.currencyWallets[id])
+      .filter((wallet): wallet is EdgeCurrencyWallet => wallet != null)
+      .map(summarizeWallet)
+    return { currencyWallets }
+  }
+})
+
+/**
+ * Create a currency wallet.
+ *
+ * @note The fiat currency is not set here. Core still accepts it on create,
+ *   but that path is deprecated — use `set-fiat-currency-code` afterwards, so
+ *   there is one way to do it.
+ */
+export const createCurrencyWallet = route({
+  core: 'account.createCurrencyWallet',
+  method: 'POST',
+  path: '/account/{sessionId}/create-currency-wallet',
+  cli: 'create-currency-wallet',
+  body: asObject({
+    walletType: doc(
+      asString,
+      'From `currency-configs`, e.g. `wallet:bitcoin`.'
+    ),
+    name: asOptional(doc(asString, 'Display name.')),
+    importText: asOptional(
+      doc(asString, 'Seed or key text to import instead of generating.')
+    )
+  }).withRest,
+  returns: asWalletSummary,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const wallet = await getAccount(ctx).createCurrencyWallet(
+      ctx.body.walletType,
+      {
+        name: ctx.body.name,
+        importText: ctx.body.importText
+      }
+    )
+    return summarizeWallet(wallet)
+  }
+})
+
+/**
+ * Create several wallets at once.
+ *
+ * Partial success is normal: each entry reports its own outcome, and one
+ * failure does not roll back the others.
+ */
+export const createCurrencyWallets = route({
+  core: 'account.createCurrencyWallets',
+  method: 'POST',
+  path: '/account/{sessionId}/create-currency-wallets',
+  cli: 'create-currency-wallets',
+  body: asObject({
+    createWallets: doc(
+      asArray(asCreateCurrencyWallet),
+      '`EdgeCreateCurrencyWallet[]`: walletType, plus optional name and fiatCurrencyCode.'
+    )
+  }).withRest,
+  returns: asObject({
+    results: doc(
+      asArray(asCoreValue),
+      'Mirrors core’s EdgeResult[]: `{ ok, wallet }` or `{ ok: false, error }`.'
+    )
+  }),
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const results = await getAccount(ctx).createCurrencyWallets(
+      ctx.body.createWallets
+    )
+    return {
+      results: results.map(result =>
+        result.ok
+          ? { ok: true, wallet: summarizeWallet(result.result) }
+          : {
+              ok: false,
+              error:
+                result.error instanceof Error
+                  ? result.error.message
+                  : String(result.error)
+            }
+      )
+    }
+  }
+})
diff --git a/src/cli/engine/routes/context.ts b/src/cli/engine/routes/context.ts
new file mode 100644
index 00000000000..cbf822c0cda
--- /dev/null
+++ b/src/cli/engine/routes/context.ts
@@ -0,0 +1,307 @@
+import { asArray, asBoolean, asObject, asOptional, asString } from 'cleaners'
+
+import { doc } from '../doc'
+import { engineError } from '../errors'
+import { route } from '../route'
+import { asCoreValue } from '../schemas'
+
+const asUsernameQuery = asObject({
+  username: doc(asString, 'The name to check.'),
+  challengeId: asOptional(
+    doc(asString, 'Supply after solving a CAPTCHA to retry the same check.')
+  )
+}).withRest
+
+const asForgetAccountBody = asObject({
+  rootLoginId: doc(
+    asString,
+    'Core takes a `rootLoginId`. A username is also accepted and resolved against `localUsers` first, so callers need not hash it.'
+  )
+}).withRest
+const asOtpResetBody = asObject({
+  username: doc(asString, 'Whose 2FA to reset.'),
+  otpResetToken: doc(
+    asString,
+    'From `details.resetToken` on an `OTP_REQUIRED` error.'
+  )
+}).withRest
+const asRecoveryQuestionsQuery = asObject({
+  recoveryKey: doc(
+    asString,
+    'From `change-recovery`, stored by the user out of band.'
+  ),
+  username: doc(asString, 'Whose questions to fetch.')
+}).withRest
+
+/**
+ * List local users on this device.
+ *
+ * @returns Everything `context.localUsers` reports, including which login
+ *   methods each user has enabled on this device.
+ */
+export const localUsers = route({
+  core: 'context.localUsers',
+  method: 'GET',
+  path: '/local-users',
+  cli: 'local-users',
+  returns: asObject({
+    localUsers: doc(
+      asArray(asCoreValue),
+      '`EdgeUserInfo[]`: one entry per account cached on this device.'
+    )
+  }),
+
+  handler(ctx) {
+    return { localUsers: ctx.state.core.context.localUsers }
+  }
+})
+
+/**
+ * Forget an account on this device.
+ *
+ * Removes locally cached credentials. The remote account is untouched.
+ *
+ */
+export const forgetAccount = route({
+  core: 'context.forgetAccount',
+  method: 'POST',
+  path: '/forget-account',
+  cli: 'forget-account',
+  body: asForgetAccountBody,
+  errors: ['USER_NOT_FOUND', 'BAD_REQUEST'],
+
+  async handler(ctx) {
+    const { rootLoginId } = ctx.body
+    const { context } = ctx.state.core
+    const found = context.localUsers.find(
+      user => user.loginId === rootLoginId || user.username === rootLoginId
+    )
+    if (found == null) {
+      throw engineError(
+        'USER_NOT_FOUND',
+        `No local user matching: ${rootLoginId}`,
+        404
+      )
+    }
+    await context.forgetAccount(found.loginId)
+    return undefined
+  }
+})
+
+/**
+ * Check whether a username is free.
+ *
+ */
+export const usernameAvailable = route({
+  core: 'context.usernameAvailable',
+  method: 'GET',
+  path: '/username-available',
+  cli: 'username-available',
+  query: asUsernameQuery,
+  returns: asObject({
+    username: doc(asString, 'The name that was checked, echoed back.'),
+    available: doc(
+      asBoolean,
+      'True when nobody holds this name. It is not reserved by asking.'
+    )
+  }),
+  errors: ['USERNAME_ERROR', 'CHALLENGE_REQUIRED', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const { username, challengeId } = ctx.query.valid
+    const available = await ctx.state.core.context.usernameAvailable(username, {
+      challengeId
+    })
+    return { username, available }
+  }
+})
+
+/**
+ * Normalize a username.
+ *
+ * Applies the same rules the login server does, so a caller can show the user
+ * what their name will actually be before creating an account.
+ */
+export const fixUsername = route({
+  core: 'context.fixUsername',
+  method: 'GET',
+  path: '/fix-username',
+  cli: 'fix-username',
+  query: asObject({
+    username: doc(asString, 'The name to normalize.')
+  }).withRest,
+  returns: asObject({
+    username: doc(asString, 'The normalized value. The input is not echoed.')
+  }),
+
+  handler(ctx) {
+    return {
+      username: ctx.state.core.context.fixUsername(ctx.query.valid.username)
+    }
+  }
+})
+
+/**
+ * Score a candidate password.
+ *
+ * @note Send it with `curl --get --data-urlencode` rather than putting it in a
+ *   shell-visible URL.
+ * @returns `EdgePasswordRules` from core: passed, tooShort, noNumber,
+ *   noLowerCase, noUpperCase, secondsToCrack.
+ */
+export const checkPasswordRules = route({
+  core: 'context.checkPasswordRules',
+  method: 'GET',
+  path: '/check-password-rules',
+  cli: 'check-password-rules',
+  query: asObject({
+    password: doc(asString, 'The candidate password to score.')
+  }).withRest,
+  returns: asCoreValue,
+
+  handler(ctx) {
+    return ctx.state.core.context.checkPasswordRules(ctx.query.valid.password)
+  }
+})
+
+/**
+ * Fetch login-server messages for every local user.
+ *
+ * @returns `EdgeLoginMessages` from core, keyed by loginId; each value carries
+ *   otpResetPending and pendingVouchers. Passed straight through.
+ */
+export const fetchLoginMessages = route({
+  core: 'context.fetchLoginMessages',
+  method: 'GET',
+  path: '/fetch-login-messages',
+  cli: 'fetch-login-messages',
+  returns: doc(
+    asCoreValue,
+    '`EdgeLoginMessages` from core, keyed by loginId; each value carries otpResetPending and pendingVouchers.'
+  ),
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    return await ctx.state.core.context.fetchLoginMessages()
+  }
+})
+
+/**
+ * Request a 2FA reset.
+ *
+ * Starts the timed reset a user falls back on after losing their
+ * authenticator.
+ *
+ * @returns When the reset completes if nobody cancels it.
+ */
+export const requestOtpReset = route({
+  core: 'context.requestOtpReset',
+  method: 'POST',
+  path: '/request-otp-reset',
+  cli: 'request-otp-reset',
+  body: asOtpResetBody,
+  returns: asObject({
+    resetDate: doc(
+      asString,
+      'When 2FA will actually come off. The login server enforces a waiting ' +
+        'period so the real owner has time to cancel.'
+    )
+  }),
+  errors: ['USERNAME_ERROR', 'BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const resetDate = await ctx.state.core.context.requestOtpReset(
+      ctx.body.username,
+      ctx.body.otpResetToken
+    )
+    return { resetDate: resetDate.toISOString() }
+  }
+})
+
+/**
+ * Fetch a user’s recovery questions.
+ *
+ * @coreNote Our surface drops the `2` from the path, command and `recoveryKey`
+ *   parameter; a future Recovery1 would be suffixed `V1`.
+ */
+export const fetchRecoveryQuestions = route({
+  core: 'context.fetchRecovery2Questions',
+  coreExtra: {
+    recoveryKey: 'Core calls it recovery2Key. The `2` is dropped throughout.'
+  },
+  method: 'GET',
+  path: '/fetch-recovery-questions',
+  cli: 'fetch-recovery-questions',
+  query: asRecoveryQuestionsQuery,
+  returns: asObject({
+    questions: doc(
+      asArray(asString),
+      'The questions in the order `login-with-recovery` expects the answers.'
+    )
+  }),
+  errors: ['USERNAME_ERROR', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const { recoveryKey, username } = ctx.query.valid
+    const questions = await ctx.state.core.context.fetchRecovery2Questions(
+      recoveryKey,
+      username
+    )
+    return { questions }
+  }
+})
+
+/**
+ * Pre-fetch a CAPTCHA challenge.
+ *
+ * Lets a client solve a challenge before it hits `403 CHALLENGE_REQUIRED`
+ * mid-flow.
+ *
+ * @returns `challengeUri` is absent when the server considers the challenge
+ *   already satisfied.
+ */
+export const fetchChallenge = route({
+  core: 'context.fetchChallenge',
+  method: 'POST',
+  path: '/fetch-challenge',
+  cli: 'fetch-challenge',
+  body: asObject({}).withRest,
+  returns: asObject({
+    challengeId: doc(
+      asString,
+      'Pass to the call that demanded a challenge once the user has solved it.'
+    ),
+    challengeUri: doc(
+      asOptional(asString),
+      'Where to send the user to solve the CAPTCHA. Absent when the server ' +
+        'issued a challenge that needs no interaction.'
+    )
+  }),
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    return await ctx.state.core.context.fetchChallenge()
+  }
+})
+
+/**
+ * List plugin ids usable for wallet creation.
+ *
+ * Currency and accountbased plugins only — swap plugins are excluded.
+ *
+ * @coreNote Engine view of the enabled plugin set; core exposes
+ *   `account.currencyConfig` per plugin instead.
+ */
+export const currencyConfigs = route({
+  core: null,
+  method: 'GET',
+  path: '/currency-configs',
+  cli: 'currency-configs',
+  returns: asObject({
+    pluginIds: doc(asArray(asString), 'Currency plugins this engine loaded.')
+  }),
+
+  handler(ctx) {
+    return { pluginIds: ctx.state.core.currencyPluginIds }
+  }
+})
diff --git a/src/cli/engine/routes/events.ts b/src/cli/engine/routes/events.ts
new file mode 100644
index 00000000000..126ec0aecf7
--- /dev/null
+++ b/src/cli/engine/routes/events.ts
@@ -0,0 +1,88 @@
+import { asObject, asOptional, asString, asUnknown } from 'cleaners'
+
+import { doc } from '../doc'
+import { route } from '../route'
+
+/**
+ * Subscribe to engine events.
+ *
+ * Holds a Server-Sent Events stream open until the caller disconnects or the
+ * engine closes it. Runs concurrently with one-shot calls, so a subscriber in
+ * one terminal watches what another terminal does.
+ *
+ * A live subscription holds the engine open past its idle timeout. It does not
+ * hold an account logged in: the auto-logout timer still fires, and closes any
+ * subscription scoped to that account or one of its wallets. Context-scoped
+ * subscriptions survive, because the context outlives every account.
+ *
+ * Scope comes from the query string. With no `sessionId` the stream is
+ * context-scoped and nothing but the engine stopping ends it, which is what
+ * the `subscribe` command asks for. With `sessionId` it is account-scoped: a
+ * logout closes it, and the session events of *other* accounts are filtered
+ * out. `walletId` narrows it further, for whenever a wallet-scoped event
+ * exists — no event carries a wallet scope today, so on its own it changes
+ * only which events close the stream.
+ *
+ * @note Frame types: `core.log`, `session.created`, `session.expired`,
+ *   `engine.shutdown`, and `subscription.closed` when the engine ends it.
+ * @note The `subscribe` command prints one further frame of its own once the
+ *   stream is over, `subscription.ended`, carrying the close reason. It comes
+ *   from the client, so `--type` does not filter it.
+ * @note `sessionId` in event payloads is truncated to its first 10 characters.
+ * @note A client more than 1 MiB behind is disconnected rather than buffered.
+ * @note Served directly by the HTTP handler rather than through the router,
+ *   because the response never ends.
+ * @coreNote Engine-side fan-out; `core.log` frames carry core's onLog output.
+ */
+export const engineEvents = route({
+  core: null,
+  method: 'GET',
+  path: '/engine/events',
+  cli: {
+    command: 'subscribe',
+    custom: true,
+    extra: {
+      type: {
+        kind: 'repeat',
+        doc: 'Only these event types. Applied by the engine, so an unwanted type never crosses the socket; the client filters again for the types the engine sends regardless, like `subscription.closed`.'
+      }
+    },
+    exits: { interrupted: 0, engineClosed: 7 },
+    notes:
+      'Prints newline-delimited JSON and runs until interrupted. Exits 0 on SIGINT and 7 when the engine ends the stream. `subscribe` opens an unscoped stream, which only the engine stopping ends; a stream opened with `sessionId` is closed by that session logging out.'
+  },
+  // `type` is declared once, by `cli.extra` above, which is what carries its
+  // repeatability. Declaring it here as well published `--type` twice in the
+  // usage line. Inline, not a named const: `extractRoutes` reads this through
+  // the checker as an object *literal*.
+  query: asObject({
+    sessionId: asOptional(
+      doc(
+        asString,
+        'Scope the stream to one account, so a logout closes it. Omitted, the stream is context-scoped and only the engine stopping ends it.'
+      )
+    ),
+    walletId: asOptional(
+      doc(
+        asString,
+        'With `sessionId`, narrow the stream to one wallet. No event carries a wallet scope yet, so today this only narrows which events can close the stream. Ignored on its own.'
+      )
+    )
+  }).withRest,
+  // The frame list and the scoping rules are in this route's `@note`s, which
+  // is what the reference publishes; `StreamSpec` says why they are not
+  // fields here.
+  stream: { marker: true },
+  returns: doc(
+    asObject({
+      type: doc(asString, 'The event name.'),
+      data: doc(asUnknown, 'Payload, shaped by the event type.')
+    }),
+    'One frame per event, as `event:` then `data:` lines.'
+  ),
+
+  handler() {
+    // The SSE upgrade happens in server.ts, which owns the response.
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/helpers.ts b/src/cli/engine/routes/helpers.ts
new file mode 100644
index 00000000000..175f35039e8
--- /dev/null
+++ b/src/cli/engine/routes/helpers.ts
@@ -0,0 +1,92 @@
+/**
+ * Shared helpers for route handlers: session/account lookup, body field
+ * validation, and query-string parsing. Not part of the core engine
+ * infrastructure — just utilities reused across route modules.
+ */
+import type { EdgeAccount, EdgeCurrencyWallet } from 'edge-core-js'
+
+import { engineError } from '../errors'
+import type { HandleRecord, ObjectHandleKind } from '../objectHandles'
+import type { RouteContext } from '../router'
+import type { SessionRecord } from '../sessions'
+
+/**
+ * The session a route is acting on, with its activity clock refreshed.
+ *
+ * One lookup. Calling `sessions.touch` after `sessions.get` repeated the Map
+ * lookup and the expiry test, and built a `SessionInfo` — eight fields and
+ * three `Date#toISOString` calls — that nobody read, on every session-scoped
+ * request.
+ */
+export function getSession(ctx: RouteContext): SessionRecord {
+  const session = ctx.state.sessions.get(ctx.params.sessionId)
+  session.lastActivityAt = Date.now()
+  return session
+}
+
+export function getAccount(ctx: RouteContext): EdgeAccount {
+  return getSession(ctx).account
+}
+
+/**
+ * The object handle an `/account/{sessionId}/…` path names, once the session
+ * itself has been resolved.
+ *
+ * Resolving the session is the authorisation step, and it has to come first:
+ * `SessionStore.get` is the only thing that rejects a logged-out or expired
+ * session id, so comparing the handle's own recorded `sessionId` proves only
+ * that two strings match. A handle stored without a `sessionId` — every
+ * pending login is — skips that comparison entirely, which would leave these
+ * paths answering for a session id that was never issued.
+ */
+export function requireOwnedHandle<T>(
+  ctx: RouteContext,
+  objectId: string,
+  kind?: ObjectHandleKind
+): HandleRecord<T> {
+  getSession(ctx)
+  const record = ctx.state.objects.get<T>(objectId, kind)
+  // An owner-less handle is refused here too, not just a mismatched one.
+  // Skipping the comparison when `sessionId` was null made every
+  // session-less handle reachable from *any* session: with two accounts
+  // logged into one engine, A could read B's pending edge login out of
+  // `object-get` and cancel it through `object-delete`. A handle that
+  // belongs to no session belongs on the un-scoped paths it already has.
+  if (record.sessionId !== ctx.params.sessionId) {
+    throw engineError(
+      'OBJECT_SESSION_MISMATCH',
+      record.sessionId == null
+        ? `objectId ${objectId} belongs to no session; use the un-scoped path for it`
+        : `objectId ${objectId} belongs to a different session`,
+      400
+    )
+  }
+  return record
+}
+
+/** The wallet fields every listing and creation route returns. */
+export function summarizeWallet(
+  wallet: EdgeCurrencyWallet
+): Record<string, unknown> {
+  return {
+    walletId: wallet.id,
+    id: wallet.id,
+    type: wallet.type,
+    name: wallet.name,
+    pluginId: wallet.currencyInfo.pluginId,
+    currencyCode: wallet.currencyInfo.currencyCode,
+    fiatCurrencyCode: wallet.fiatCurrencyCode,
+    blockHeight: wallet.blockHeight,
+    syncStatus: wallet.syncStatus,
+    syncRatio:
+      wallet.syncStatus?.totalRatio != null
+        ? `${Math.round(wallet.syncStatus.totalRatio * 100)}%`
+        : undefined,
+    paused: wallet.paused,
+    imported: wallet.imported,
+    created: wallet.created?.toISOString() ?? null,
+    enabledTokenIds: wallet.enabledTokenIds,
+    detectedTokenIds: wallet.detectedTokenIds,
+    unactivatedTokenIds: wallet.unactivatedTokenIds
+  }
+}
diff --git a/src/cli/engine/routes/index.ts b/src/cli/engine/routes/index.ts
new file mode 100644
index 00000000000..04fc36cebbb
--- /dev/null
+++ b/src/cli/engine/routes/index.ts
@@ -0,0 +1,19 @@
+/**
+ * Route registration.
+ *
+ * Every call is declared with `route(…)`, which records it in a registry, so
+ * importing the module is all the registration a route needs.
+ */
+import './account'
+import './context'
+import './events'
+import './login'
+import './objects'
+import './status'
+
+import { allRoutes, registerRoute } from '../route'
+import type { Router } from '../router'
+
+export function registerRoutes(router: Router): void {
+  for (const spec of allRoutes()) registerRoute(router, spec)
+}
diff --git a/src/cli/engine/routes/login.ts b/src/cli/engine/routes/login.ts
new file mode 100644
index 00000000000..7dc10b45527
--- /dev/null
+++ b/src/cli/engine/routes/login.ts
@@ -0,0 +1,546 @@
+import { asArray, asBoolean, asObject, asOptional, asString } from 'cleaners'
+import type {
+  EdgeAccount,
+  EdgeAccountOptions,
+  EdgePendingEdgeLogin
+} from 'edge-core-js'
+
+import { doc } from '../doc'
+import { EngineError, engineError } from '../errors'
+import { route } from '../route'
+import type { RouteContext } from '../router'
+import { asPendingEdgeLogin, asSession, asSessionListing } from '../schemas'
+import type { SessionInfo } from '../sessions'
+
+interface PendingRecord {
+  pendingId: string
+  pending: EdgePendingEdgeLogin
+  createdAt: number
+  cancelled?: boolean
+  /**
+   * The session this login created, by id only.
+   *
+   * A `SessionInfo` snapshot used to be cached here and returned verbatim for
+   * the rest of the handle's TTL, so `poll-edge-login` kept reporting a
+   * session the engine had already discarded — and its `expiresAt` and
+   * `lastActivityAt` were frozen at creation, so they were wrong even while
+   * the session was alive. The client wrote that dead id back into
+   * `session.json`.
+   */
+  sessionId?: string
+  sessionPromise?: Promise<SessionInfo>
+  error?: string
+  unwatchState?: () => void
+}
+
+interface EdgeSessionApi {
+  create: (account: EdgeAccount, method: 'edge') => Promise<SessionInfo>
+  peek: (sessionId: string) => SessionInfo | null
+  forceLogout: (
+    sessionId: string,
+    reason: 'expired' | 'shutdown' | 'cancelled'
+  ) => Promise<void>
+}
+
+function ensureEdgeSession(
+  record: PendingRecord,
+  sessions: EdgeSessionApi
+): Promise<SessionInfo> | undefined {
+  if (record.cancelled === true) return undefined
+  if (record.sessionId != null) {
+    const live = sessions.peek(record.sessionId)
+    if (live != null) return Promise.resolve(live)
+  }
+  if (record.sessionPromise != null) return record.sessionPromise
+  // A prior create failure is sticky until the pending login is cancelled or
+  // expires — retrying on every GET can wedge the account into a loop.
+  if (record.error != null) return undefined
+  if (record.pending.account == null) return undefined
+
+  record.sessionPromise = sessions
+    .create(record.pending.account, 'edge')
+    .then(async session => {
+      if (record.cancelled === true) {
+        try {
+          await sessions.forceLogout(session.sessionId, 'cancelled')
+        } catch {
+          // best effort
+        }
+        throw engineError(
+          'PENDING_LOGIN_NOT_FOUND',
+          `Pending edge login cancelled: ${record.pendingId}`,
+          404
+        )
+      }
+      record.sessionId = session.sessionId
+      return session
+    })
+    .catch((error: unknown) => {
+      record.error = error instanceof Error ? error.message : String(error)
+      record.sessionPromise = undefined
+      throw error
+    })
+  return record.sessionPromise
+}
+
+interface LoginOptions {
+  otp?: string
+  otpKey?: string
+  challengeId?: string
+}
+
+function accountOptions(body: LoginOptions): EdgeAccountOptions {
+  const opts: EdgeAccountOptions = {}
+  if (body.challengeId != null) opts.challengeId = body.challengeId
+  if (body.otp != null) opts.otp = body.otp
+  if (body.otpKey != null) opts.otpKey = body.otpKey
+  return opts
+}
+
+/** Options every login and create call accepts, from `EdgeAccountOptions`. */
+const loginOptionFields = {
+  otp: asOptional(doc(asString, 'A current 2FA code.')),
+  otpKey: asOptional(
+    doc(asString, 'The 2FA secret itself, instead of a code.')
+  ),
+  challengeId: asOptional(
+    doc(asString, 'Supply after solving a CAPTCHA to retry the same request.')
+  )
+}
+
+function pendingSummary(
+  record: PendingRecord,
+  sessions: EdgeSessionApi,
+  expiresAt?: string
+): Record<string, unknown> {
+  const { pending } = record
+  return {
+    objectId: record.pendingId,
+    pendingId: record.pendingId,
+    kind: 'pendingLogin',
+    expiresAt: expiresAt ?? null,
+    lobbyId: pending.id,
+    uri: 'edge://edge/' + pending.id,
+    state: pending.state,
+    username: pending.username ?? null,
+    // Re-derived on every call, so the session reported cannot outlive the
+    // session it describes.
+    session: record.sessionId != null ? sessions.peek(record.sessionId) : null,
+    error: record.error ?? null
+  }
+}
+
+/**
+ * The pending login a `pending_` handle holds.
+ *
+ * Looked up through `ObjectHandleStore`, which owns it. A module-level
+ * `Map` beside the store was a second copy of the same state, kept
+ * consistent only because `onExpire` happened to be its one removal path —
+ * and `poll-edge-login` already had to patch around that by deleting from
+ * the map itself when the store reported `OBJECT_EXPIRED`.
+ */
+function getPending(ctx: RouteContext, pendingId: string): PendingRecord {
+  let record: PendingRecord | undefined
+  try {
+    record = ctx.state.objects.get<PendingRecord>(
+      pendingId,
+      'pendingLogin'
+    ).value
+  } catch {
+    record = undefined
+  }
+  if (record == null) {
+    throw engineError(
+      'PENDING_LOGIN_NOT_FOUND',
+      `No pending edge login: ${pendingId}`,
+      404
+    )
+  }
+  return record
+}
+
+/**
+ * Log in with a password.
+ *
+ * @note With `--solve-captcha` the client solves a `CHALLENGE_REQUIRED`
+ *   response headlessly (ALTCHA proof-of-work) and retries once.
+ */
+export const loginWithPassword = route({
+  core: 'context.loginWithPassword',
+  method: 'POST',
+  path: '/login-with-password',
+  cli: { command: 'login-with-password', custom: true },
+  body: asObject({
+    username: doc(asString, 'The account name.'),
+    password: doc(asString, 'The account password.'),
+    ...loginOptionFields
+  }).withRest,
+  returns: doc(asSession, 'A session with `loginMethod: "password"`.'),
+  errors: [
+    'PASSWORD_ERROR',
+    'USERNAME_ERROR',
+    'OTP_REQUIRED',
+    'CHALLENGE_REQUIRED',
+    'NETWORK_ERROR'
+  ],
+
+  async handler(ctx) {
+    const account: EdgeAccount = await ctx.state.core.context.loginWithPassword(
+      ctx.body.username,
+      ctx.body.password,
+      accountOptions(ctx.body)
+    )
+    return await ctx.state.sessions.create(account, 'password')
+  }
+})
+
+/**
+ * Log in with a device PIN.
+ *
+ * Only works on a device that has already saved a PIN for the account.
+ */
+export const loginWithPin = route({
+  core: 'context.loginWithPIN',
+  method: 'POST',
+  path: '/login-with-pin',
+  cli: {
+    command: 'login-with-pin',
+    custom: true
+  },
+  body: asObject({
+    usernameOrLoginId: doc(asString, 'A username, or a login id.'),
+    pin: doc(asString, 'The device PIN.'),
+    useLoginId: asOptional(doc(asBoolean, 'Treat the value as a login id.')),
+    ...loginOptionFields
+  }).withRest,
+  returns: doc(asSession, 'A session with `loginMethod: "pin"`.'),
+  errors: [
+    'PASSWORD_ERROR',
+    'PIN_DISABLED',
+    'USERNAME_ERROR',
+    'BAD_REQUEST',
+    'NETWORK_ERROR'
+  ],
+
+  async handler(ctx) {
+    const account: EdgeAccount = await ctx.state.core.context.loginWithPIN(
+      ctx.body.usernameOrLoginId,
+      ctx.body.pin,
+      { ...accountOptions(ctx.body), useLoginId: ctx.body.useLoginId }
+    )
+    return await ctx.state.sessions.create(account, 'pin')
+  }
+})
+
+/**
+ * Log in with an account login key.
+ *
+ * The key comes from `get-login-key` on an already-authenticated session.
+ */
+export const loginWithKey = route({
+  core: 'context.loginWithKey',
+  method: 'POST',
+  path: '/login-with-key',
+  cli: {
+    command: 'login-with-key',
+    custom: true
+  },
+  body: asObject({
+    usernameOrLoginId: doc(asString, 'A username, or a login id.'),
+    loginKey: doc(asString, 'From `get-login-key`.'),
+    useLoginId: asOptional(doc(asBoolean, 'Treat the value as a login id.')),
+    ...loginOptionFields
+  }).withRest,
+  returns: doc(asSession, 'A session with `loginMethod: "key"`.'),
+  errors: ['PASSWORD_ERROR', 'USERNAME_ERROR', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const account: EdgeAccount = await ctx.state.core.context.loginWithKey(
+      ctx.body.usernameOrLoginId,
+      ctx.body.loginKey,
+      { ...accountOptions(ctx.body), useLoginId: ctx.body.useLoginId }
+    )
+    return await ctx.state.sessions.create(account, 'key')
+  }
+})
+
+/**
+ * Log in with recovery answers.
+ *
+ * Needs both the recovery key and the answers; neither works alone.
+ *
+ * @coreNote Our surface drops the `2` from core's recovery2 naming, and calls
+ *   the key `recoveryKey` to match what `change-recovery` returns.
+ */
+export const loginWithRecovery = route({
+  core: 'context.loginWithRecovery2',
+  coreExtra: {
+    recoveryKey: 'Core calls it recovery2Key. The `2` is dropped throughout.'
+  },
+  method: 'POST',
+  path: '/login-with-recovery',
+  cli: {
+    command: 'login-with-recovery',
+    custom: true,
+    flags: { answer: { maps: 'answers', repeat: true } }
+  },
+  body: asObject({
+    recoveryKey: doc(asString, 'From `change-recovery`.'),
+    username: doc(asString, 'The account name.'),
+    answers: doc(asArray(asString), 'In the same order as the questions.'),
+    ...loginOptionFields
+  }).withRest,
+  returns: doc(asSession, 'A session with `loginMethod: "recovery"`.'),
+  errors: ['PASSWORD_ERROR', 'USERNAME_ERROR', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const account: EdgeAccount =
+      await ctx.state.core.context.loginWithRecovery2(
+        ctx.body.recoveryKey,
+        ctx.body.username,
+        ctx.body.answers,
+        accountOptions(ctx.body)
+      )
+    return await ctx.state.sessions.create(account, 'recovery')
+  }
+})
+
+/**
+ * Create an account.
+ *
+ * Every credential is optional over REST: omitting all three creates a light
+ * account with no username.
+ *
+ * @note The command requires a username, password and PIN. Creating a light
+ *   account is REST-only.
+ */
+export const createAccount = route({
+  core: 'context.createAccount',
+  method: 'POST',
+  path: '/create-account',
+  cli: {
+    command: 'create-account',
+    custom: true
+  },
+  body: asObject({
+    username: asOptional(doc(asString, 'The name to claim.')),
+    password: asOptional(doc(asString, 'The account password.')),
+    pin: asOptional(doc(asString, 'A device PIN to save.')),
+    ...loginOptionFields
+  }).withRest,
+  returns: doc(asSession, 'A session with `loginMethod: "create"`.'),
+  errors: [
+    'USERNAME_ERROR',
+    'CHALLENGE_REQUIRED',
+    'BAD_REQUEST',
+    'NETWORK_ERROR'
+  ],
+
+  async handler(ctx) {
+    const account: EdgeAccount = await ctx.state.core.context.createAccount({
+      ...accountOptions(ctx.body),
+      username: ctx.body.username,
+      password: ctx.body.password,
+      pin: ctx.body.pin
+    })
+    return await ctx.state.sessions.create(account, 'create')
+  }
+})
+
+/**
+ * Start a QR login.
+ *
+ * Asks the login server for a lobby another logged-in Edge device can approve.
+ * The returned `lobbyId` is what goes in the QR code.
+ *
+ * @note The pending login is an object handle with a 5 minute TTL. On expiry
+ *   the engine cancels the request on the login server for you.
+ */
+export const requestEdgeLogin = route({
+  core: 'context.requestEdgeLogin',
+  method: 'POST',
+  path: '/request-edge-login',
+  cli: {
+    command: 'request-edge-login',
+    custom: true,
+    extra: {
+      noWait: {
+        kind: 'boolean',
+        doc: 'Print the lobby and exit instead of polling, so the QR can be displayed while `poll-edge-login` watches the same handle from another process.'
+      }
+    },
+    notes:
+      'Prints the pending login, then polls every 2s for up to 5 minutes. On `done` it stores the session. With `--no-wait` it returns immediately and `poll-edge-login` takes over.'
+  },
+  body: asObject({}).withRest,
+  returns: asPendingEdgeLogin,
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const pending = await ctx.state.core.context.requestEdgeLogin({})
+    const record: PendingRecord = {
+      pendingId: '',
+      pending,
+      createdAt: Date.now()
+    }
+
+    const handle = ctx.state.objects.create({
+      kind: 'pendingLogin',
+      prefix: 'pending_',
+      value: record,
+      onExpire: async value => {
+        value.cancelled = true
+        try {
+          value.unwatchState?.()
+        } catch {
+          // best effort
+        }
+        try {
+          await value.pending.cancelRequest()
+        } catch {
+          // best effort
+        }
+      }
+    })
+    record.pendingId = handle.objectId
+
+    record.unwatchState = pending.watch(
+      'state',
+      (state: EdgePendingEdgeLogin['state']) => {
+        if (state === 'done' && pending.account != null) {
+          const promise = ensureEdgeSession(record, ctx.state.sessions)
+          if (promise != null) {
+            promise.catch(() => {
+              // error already stored on record
+            })
+          }
+        } else if (state === 'error') {
+          const { error } = pending
+          record.error = error instanceof Error ? error.message : String(error)
+        }
+      }
+    )
+
+    return pendingSummary(record, ctx.state.sessions, handle.expiresAt)
+  }
+})
+
+/**
+ * Poll a pending QR login.
+ *
+ * Once `state` reaches `done` the engine has already created the session, so
+ * the response carries one ready to use.
+ *
+ * @note Session creation is attempted once. A failure is sticky, so later
+ *   polls report the same `error` rather than retrying.
+ * @note Polling does not extend the handle TTL; only the original 5 minute
+ *   window applies.
+ * @coreNote Engine state for an in-flight requestEdgeLogin; core exposes it as
+ *   EdgePendingEdgeLogin properties.
+ */
+export const pollEdgeLogin = route({
+  core: null,
+  method: 'GET',
+  path: '/pending-edge-login',
+  cli: {
+    command: 'poll-edge-login',
+    positional: 'pendingId',
+    // Hand-written: a poll that reaches `done` carries a session, and the
+    // command has to store it the way the other login commands do.
+    custom: true
+  },
+  returns: asPendingEdgeLogin,
+  errors: ['PENDING_LOGIN_NOT_FOUND', 'OBJECT_EXPIRED'],
+
+  async handler(ctx) {
+    let expiresAt: string | undefined
+    try {
+      const handle = ctx.state.objects.get<PendingRecord>(
+        ctx.params.pendingId,
+        'pendingLogin'
+      )
+      expiresAt = ctx.state.objects.toInfo(handle).expiresAt
+    } catch (error: unknown) {
+      // Rethrow anything that already carries a code: discarding every code
+      // but `OBJECT_EXPIRED` replaced `OBJECT_KIND_MISMATCH` and
+      // `OBJECT_NOT_FOUND` with whatever `getPending` decided two lines
+      // later.
+      if (error instanceof EngineError) throw error
+    }
+    const record = getPending(ctx, ctx.params.pendingId)
+    if (
+      record.pending.state === 'done' &&
+      record.sessionId == null &&
+      record.error == null &&
+      record.pending.account != null
+    ) {
+      try {
+        await ensureEdgeSession(record, ctx.state.sessions)
+      } catch {
+        // error already stored on record
+      }
+    }
+    return pendingSummary(record, ctx.state.sessions, expiresAt)
+  }
+})
+
+/**
+ * Cancel a pending QR login.
+ *
+ * @note If the login already completed and a session exists, that session is
+ *   force-logged-out too, so cancelling cannot leave an orphan visible in
+ *   `engine-sessions`.
+ */
+export const cancelEdgeLogin = route({
+  core: 'EdgePendingEdgeLogin.cancelRequest',
+  method: 'POST',
+  path: '/pending-edge-login/cancel-request',
+  cli: { command: 'cancel-request', positional: 'pendingId' },
+  errors: ['PENDING_LOGIN_NOT_FOUND'],
+
+  async handler(ctx) {
+    const record = getPending(ctx, ctx.params.pendingId)
+    record.cancelled = true
+    try {
+      record.unwatchState?.()
+    } catch {
+      // best effort
+    }
+    // A completed edge login may already have created a session before the
+    // caller cancelled. Tear it down so cancelling cannot leave a logged-in
+    // orphan discoverable via GET /engine/sessions.
+    if (record.sessionId != null) {
+      try {
+        await ctx.state.sessions.forceLogout(record.sessionId, 'cancelled')
+      } catch {
+        // best effort
+      }
+      record.sessionId = undefined
+    }
+    await ctx.state.objects.delete(ctx.params.pendingId)
+    return undefined
+  }
+})
+
+/**
+ * List active sessions.
+ *
+ * @coreNote The session registry is an engine construct; core has no
+ *   multi-account session concept.
+ */
+export const engineSessions = route({
+  core: null,
+  method: 'GET',
+  path: '/engine/sessions',
+  cli: 'engine-sessions',
+  returns: doc(
+    asArray(asSessionListing),
+    'A bare array, not wrapped in a key. Each `sessionId` is truncated: ' +
+      'this route needs no session, so a usable id here would be a ' +
+      'credential anyone who can reach the engine could collect.'
+  ),
+
+  handler(ctx) {
+    return ctx.state.sessions.list()
+  }
+})
diff --git a/src/cli/engine/routes/objects.ts b/src/cli/engine/routes/objects.ts
new file mode 100644
index 00000000000..0d5ad2b26cd
--- /dev/null
+++ b/src/cli/engine/routes/objects.ts
@@ -0,0 +1,128 @@
+/**
+ * Ephemeral object handles.
+ *
+ * Core values with methods on them — a staged transaction, a swap quote, a
+ * pending login, an edge-login lobby — cannot cross JSON, so the engine keeps
+ * them and hands back an id. These two calls read and release any of them,
+ * whatever kind it is.
+ */
+import type { EdgeSwapQuote, EdgeTransaction } from 'edge-core-js'
+
+import { doc } from '../doc'
+import type { ObjectHandleKind } from '../objectHandles'
+import { route } from '../route'
+import { asObjectHandle, asOkObject } from '../schemas'
+import { requireOwnedHandle } from './helpers'
+
+/**
+ * A JSON-safe view of whatever a handle is holding.
+ *
+ * Only `transaction` holds a plain object. The others hold live core values
+ * whose properties are getters: serializing an `EdgePendingEdgeLogin` walks
+ * into `pending.account` once the login completes, and an `EdgeAccount`'s
+ * `otpKey` and `recoveryKey` getters are ordinary enumerable properties on
+ * the Node path the engine uses — `hideProperties` only applies to the fake
+ * world and the React Native bridge. A swap quote reaches its wallets and
+ * their whole `allTokens` map the same way. So each kind is projected to
+ * scalars rather than handed to `JSON.stringify`.
+ */
+function projectHandleValue(kind: ObjectHandleKind, value: unknown): unknown {
+  switch (kind) {
+    case 'transaction':
+      return value as EdgeTransaction
+
+    case 'pendingLogin': {
+      const record = value as {
+        pending?: { id?: string; state?: string; username?: string }
+        cancelled?: boolean
+        error?: string
+      }
+      return {
+        lobbyId: record.pending?.id ?? null,
+        state: record.pending?.state ?? null,
+        username: record.pending?.username ?? null,
+        cancelled: record.cancelled === true,
+        error: record.error ?? null
+      }
+    }
+
+    case 'swap': {
+      const quote = value as EdgeSwapQuote
+      return {
+        pluginId: quote.pluginId,
+        fromNativeAmount: quote.fromNativeAmount,
+        toNativeAmount: quote.toNativeAmount,
+        expirationDate: quote.expirationDate ?? null,
+        isEstimate: quote.isEstimate
+      }
+    }
+
+    case 'lobby':
+      // Nothing scalar worth reporting, and the value is a live lobby.
+      return null
+  }
+}
+
+/**
+ * Inspect an object handle.
+ *
+ * Works for every kind: transactions, pending logins, swap quotes and
+ * lobbies.
+ *
+ * @note Reading does not extend the TTL. Only a step that updates the value
+ *   does.
+ * @coreNote Engine handle store; core identifies these values by object
+ *   reference.
+ */
+export const getObject = route({
+  core: null,
+  method: 'GET',
+  path: '/account/{sessionId}/object',
+  cli: { command: 'object-get', positional: 'objectId' },
+  returns: doc(
+    asObjectHandle,
+    'The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports `value: null`.'
+  ),
+  errors: [
+    'OBJECT_NOT_FOUND',
+    'OBJECT_EXPIRED',
+    'OBJECT_IN_USE',
+    'OBJECT_SESSION_MISMATCH'
+  ],
+
+  handler(ctx) {
+    const record = requireOwnedHandle(ctx, ctx.params.objectId)
+    return {
+      ...ctx.state.objects.toInfo(record),
+      value: projectHandleValue(record.kind, record.value)
+    }
+  }
+})
+
+/**
+ * Release an object handle.
+ *
+ * Runs the handle's cleanup — closing a swap quote, cancelling a pending
+ * login — instead of waiting out the TTL.
+ *
+ * @coreNote Engine handle store.
+ */
+export const deleteObject = route({
+  core: null,
+  method: 'POST',
+  path: '/account/{sessionId}/object/delete',
+  cli: { command: 'object-delete', positional: 'objectId' },
+  returns: asOkObject,
+  errors: [
+    'OBJECT_NOT_FOUND',
+    'OBJECT_EXPIRED',
+    'OBJECT_IN_USE',
+    'OBJECT_SESSION_MISMATCH'
+  ],
+
+  async handler(ctx) {
+    requireOwnedHandle(ctx, ctx.params.objectId)
+    await ctx.state.objects.delete(ctx.params.objectId)
+    return { ok: true, objectId: ctx.params.objectId }
+  }
+})
diff --git a/src/cli/engine/routes/status.ts b/src/cli/engine/routes/status.ts
new file mode 100644
index 00000000000..c57da7feff0
--- /dev/null
+++ b/src/cli/engine/routes/status.ts
@@ -0,0 +1,176 @@
+import {
+  asArray,
+  asBoolean,
+  asEither,
+  asNumber,
+  asObject,
+  asString,
+  asValue
+} from 'cleaners'
+
+import { getAppliedLocale } from '../../../locales/bootLocale'
+import { rateCacheSize } from '../../../util/exchangeRates'
+import { API_VERSION } from '../apiVersion'
+import { doc } from '../doc'
+import { route } from '../route'
+import { asOk } from '../schemas'
+
+const asEngineStatus = asObject({
+  pid: doc(asNumber, 'The daemon process, for `kill` when it will not stop.'),
+  apiVersion: doc(
+    asString,
+    'The API this engine speaks. A client refusing to talk to an older engine ' +
+      'checks this.'
+  ),
+  uptimeSeconds: doc(asNumber, 'How long the daemon has been running.'),
+  sessionCount: doc(asNumber, 'Logged-in accounts held open right now.'),
+  testMode: doc(
+    asBoolean,
+    'True when the engine is not pointed at production: the tester fleet, or the in-process fake world under `--fake`.'
+  ),
+  idleShutdownAt: doc(
+    asEither(asString, asValue(null)),
+    'When the engine will exit for want of work. Null while anything is ' +
+      'holding it open — a logged-in session, a live subscription, a request ' +
+      'being served, or a pending edge login, whose handle belongs to no ' +
+      'session — and null when the timeout is disabled.'
+  ),
+  tcpPort: doc(
+    asEither(asNumber, asValue(null)),
+    'The loopback port, null unless started with `--tcp`.'
+  ),
+  socketPath: doc(asString, 'Unix socket the CLI connects to.'),
+  rateCachedCount: doc(
+    asNumber,
+    'Exchange rates held in the engine\u2019s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it.'
+  ),
+  locale: doc(asString, 'Language tag the engine resolved at boot.'),
+  localeMatched: doc(
+    asBoolean,
+    'Whether a translation table for that tag was actually found. False means the tag was accepted but the engine is answering in English, which is otherwise indistinguishable from a build that has the language.'
+  ),
+  decimalSeparator: doc(asString, 'Decimal mark for that locale.'),
+  groupingSeparator: doc(asString, 'Thousands mark for that locale.')
+})
+
+const asEngineConfig = asObject({
+  appId: doc(asString, 'Application ID the engine was started with.'),
+  testMode: doc(
+    asBoolean,
+    'True when the engine is not pointed at production: the tester fleet, or the in-process fake world under `--fake`. Read `servers` to tell those apart.'
+  ),
+  directory: doc(asString, 'Working directory holding the core data.'),
+  servers: doc(
+    asObject(asEither(asString, asArray(asString))),
+    'The URLs this engine talks to, keyed by role. `syncServer` is a list, ' +
+      'since core rotates across the sync fleet.'
+  ),
+  plugins: doc(asArray(asString), 'Plugin IDs the engine loaded, sorted.')
+})
+
+/**
+ * Engine liveness and summary.
+ *
+ * The readiness probe the client polls after auto-spawning the engine.
+ *
+ * @returns `idleShutdownAt` is null while a session or a subscription holds
+ *   the engine open, and `tcpPort` is null unless started with `--tcp`.
+ * @coreNote Engine lifecycle; the daemon is not part of the core API.
+ */
+export const engineStatus = route({
+  core: null,
+  method: 'GET',
+  path: '/engine/status',
+  cli: 'engine-status',
+  returns: asEngineStatus,
+  errors: ['ENGINE_SHUTTING_DOWN'],
+
+  handler(ctx) {
+    const { state } = ctx
+    const applied = getAppliedLocale()
+    return {
+      pid: process.pid,
+      apiVersion: API_VERSION,
+      uptimeSeconds: (Date.now() - state.startedAt) / 1000,
+      sessionCount: state.sessions.size,
+      testMode: state.core.testMode,
+      idleShutdownAt: state.idle.idleShutdownAt,
+      tcpPort: state.tcpPort,
+      socketPath: state.socketPath,
+      rateCachedCount: rateCacheSize(),
+      locale: applied.languageTag,
+      localeMatched: applied.matched,
+      decimalSeparator: applied.decimalSeparator,
+      groupingSeparator: applied.groupingSeparator
+    }
+  }
+})
+
+/**
+ * Configured context options.
+ *
+ * What the engine passed to `makeEdgeContext`. Contains no secrets. Use it to
+ * assert tester hosts before a test run.
+ *
+ * @note Outside `-t` / `--test`, `servers` is an empty object — core is using
+ *   its built-in production defaults, so there is nothing to echo back.
+ * @coreNote Reflects the EdgeContextOptions the engine supplied at startup.
+ */
+export const engineConfig = route({
+  core: null,
+  method: 'GET',
+  path: '/engine/config',
+  cli: 'engine-config',
+  returns: asEngineConfig,
+
+  handler(ctx) {
+    const { core } = ctx.state
+    const plugins = Object.keys(core.pluginsInit).filter(pluginId =>
+      Boolean(core.pluginsInit[pluginId])
+    )
+    return {
+      appId: core.appId,
+      testMode: core.testMode,
+      directory: core.directory,
+      servers: core.servers,
+      plugins
+    }
+  }
+})
+
+/**
+ * Stop the engine.
+ *
+ * Logs out every session, closes the context, unlinks the socket and run-file,
+ * then exits. The engine answers before it starts tearing down, so a response
+ * is not proof the process is gone.
+ *
+ * @note `503 ENGINE_SHUTTING_DOWN` reaches requests that arrive *after*
+ *   teardown starts, not ones already in flight: `handleRequest` tests the
+ *   flag at the top only. A request already past that point is waited for —
+ *   shutdown drains in-flight work before logging out — so it gets its real
+ *   response. This route is exempt: a second stop is answered `ok`, because
+ *   stopping an engine that is already stopping has succeeded.
+ * @coreNote Engine lifecycle. Internally calls `context.close()`.
+ */
+export const engineStop = route({
+  core: null,
+  method: 'POST',
+  path: '/engine/stop',
+  cli: 'engine-stop',
+  returns: asOk,
+
+  handler(ctx) {
+    // Idempotent: a second stop against an engine already tearing down is
+    // answered `ok` rather than 503, because what was asked for is already
+    // happening. `shutdown` guards itself as well, so this is belt and
+    // braces — but the 503 was the harmful part, since a client that retries
+    // it would start a replacement engine.
+    if (ctx.state.shuttingDown) return { ok: true }
+    // Respond first; process.exit inside shutdown would otherwise hang the client.
+    setImmediate(() => {
+      ctx.state.shutdown().catch(ctx.state.onShutdownFailure)
+    })
+    return { ok: true }
+  }
+})
diff --git a/src/cli/engine/schemas.ts b/src/cli/engine/schemas.ts
new file mode 100644
index 00000000000..acbcbf172ec
--- /dev/null
+++ b/src/cli/engine/schemas.ts
@@ -0,0 +1,890 @@
+/**
+ * Response shapes the engine reuses across routes.
+ *
+ * These describe what a handler returns, and `checkResponse` in `route.ts`
+ * runs each response through its route's cleaner on every request. The cleaned
+ * value is discarded on purpose: a cleaner strips unknown keys, so returning it
+ * would delete fields a plugin adds. The check reports drift and never
+ * reshapes. `EDGE_CLI_CHECK_RESPONSES` chooses what a mismatch costs — `warn`
+ * (the default) logs it, `strict` fails the request, `off` skips the check.
+ *
+ * Request cleaners live beside their route. They use `.withRest` so declared
+ * fields are validated while anything a handler forwards wholesale to core
+ * still passes through untouched.
+ */
+import type { Cleaner } from 'cleaners'
+import {
+  asArray,
+  asBoolean,
+  asDate,
+  asEither,
+  asNull,
+  asNumber,
+  asObject,
+  asOptional,
+  asString,
+  asUnknown,
+  asValue
+} from 'cleaners'
+import type {
+  EdgeAssetAction,
+  EdgeAssetActionType,
+  EdgeMetadata,
+  EdgeMetadataChange,
+  EdgeTxAction
+} from 'edge-core-js'
+
+import { asBiggystring } from '../../util/cleaners'
+import { doc } from './doc'
+import {
+  SPEND_AMOUNT_ALIAS_DOC,
+  SPEND_AMOUNT_DOC,
+  SPEND_METADATA_DOC,
+  SPEND_TO_DOC,
+  TOKEN_ID_DOC
+} from './fieldDocs'
+
+/** `EdgeTokenId`: a contract id, or null for the native asset. */
+export const asTokenId = asEither(asString, asValue(null))
+
+/** A string with something in it. */
+export const asNonEmptyString: Cleaner<string> = raw => {
+  const value = asString(raw)
+  if (value === '') throw new TypeError('Expected a non-empty string')
+  return value
+}
+
+/**
+ * The wallet a call acts on.
+ *
+ * Not a path parameter. A wallet id is base64 — `7o7i6/tlI+qi…=` is an
+ * ordinary one — and a value containing `/` cannot be a path segment without
+ * percent-encoding that callers forget. Path parameters are reserved for
+ * base58 identifiers, which have no such character.
+ */
+export const asWalletId = doc(
+  // Non-empty, because `findWallet` resolves a prefix: `''` is a prefix of
+  // every wallet, so on a single-wallet account a dropped field used to
+  // resolve silently to that one wallet — and that reaches `spend`.
+  asNonEmptyString,
+  'The wallet to act on. A full wallet id, or any unique prefix of one. An ' +
+    'ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with ' +
+    '`details.candidates`.'
+)
+
+// ------------------------------------------------------------ query values
+// A query string carries only text, so `?saveExportPrefs=true` arrives as
+// the four characters "true". (`paused` is a *body* field on `change-paused`,
+// where it is a plain `asBoolean` and no coercion happens, so it is the
+// opposite of the lesson here.) These cleaners convert on the way in, which lets a route
+// declare the type it actually means: the documented type, the type the
+// handler reads, and the CLI flag kind all follow from one declaration. A
+// route that declared `asString` and converted inside the handler documented a
+// string and produced a `--flag=<value>` where a bare switch belonged.
+
+/** A boolean written out in a query string. */
+export const asQueryBoolean: Cleaner<boolean> = raw => {
+  if (typeof raw === 'boolean') return raw
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  throw new TypeError('Expected "true" or "false"')
+}
+
+/** A whole number written out in a query string. */
+export const asQueryInteger: Cleaner<number> = raw => {
+  if (typeof raw === 'number' && Number.isInteger(raw)) return raw
+  if (typeof raw !== 'string' || raw === '') {
+    throw new TypeError('Expected a whole number')
+  }
+  const n = Number(raw)
+  if (!Number.isInteger(n)) throw new TypeError('Expected a whole number')
+  return n
+}
+
+/**
+ * A whole number that cannot be negative, for a field that indexes.
+ *
+ * `limit`, `offset` and `forceIndex` all reach an array index or a
+ * derivation index, and `asQueryInteger` accepted a negative one:
+ * `?limit=-5` reached `slice(0, -5)`, so the engine returned every
+ * transaction but the last five while `total` still reported the full count —
+ * a pager got wrong data with no error — and `?offset=-5` returned the last
+ * five. Neither is a documented meaning; `0` is already the "everything"
+ * opt-out.
+ */
+export const asQueryNonNegativeInteger: Cleaner<number> = raw => {
+  const n = asQueryInteger(raw)
+  if (n < 0) throw new TypeError('Expected zero or a whole positive number')
+  return n
+}
+
+/**
+ * A positive decimal string, as biggystring parses one.
+ *
+ * `asString` let `"abc"`, `""` and `"-1"` through to biggystring: the first
+ * came back as a plain `Error` and therefore `500 INTERNAL_ERROR` on a route
+ * that declares `BAD_REQUEST`, and the other two produced a silently wrong
+ * `nativeAmount` under a field documented as what a spend actually takes.
+ * `asBiggystring` already rejects blank, hex, exponential, `Infinity` and
+ * `NaN`; this adds the sign and zero test those fields need.
+ */
+export const asPositiveBiggystring: Cleaner<string> = raw => {
+  const value = asBiggystring(raw)
+  if (value.startsWith('-') || /^0(?:\.0+)?$/.test(value)) {
+    throw new TypeError(`"${value}" is not a positive number`)
+  }
+  return value
+}
+
+/**
+ * A number in a JSON request *body*, accepting the string form.
+ *
+ * `kindOf` resolves a body field to `kind: 'string'` unless its cleaner is a
+ * structured one, and the CLI then puts the raw flag text into the body: so
+ * `enable-otp --timeout=604800` sent `{"timeout":"604800"}` into
+ * `asOptional(asNumber)` and the command could never succeed —
+ * `BAD_REQUEST: Expected a number, got "604800" at .timeout`. The query side
+ * already solved this with `asQueryInteger`; this is the body-side twin, and
+ * `routeBodyKinds.test.ts` asserts no `kind: 'string'` body field is left
+ * with a cleaner that refuses a string.
+ */
+export const asBodyNumber: Cleaner<number> = raw => {
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new TypeError('Expected a number')
+  }
+  const n = Number(raw)
+  if (!Number.isFinite(n)) throw new TypeError('Expected a number')
+  return n
+}
+
+/**
+ * A duration in seconds with a floor.
+ *
+ * A poll interval with no floor is a request flood: `0` runs as fast as the
+ * network answers, and the caller who wrote it meant seconds.
+ */
+export const asMinSeconds =
+  (min: number): Cleaner<number> =>
+  raw => {
+    const seconds = asBodyNumber(raw)
+    if (seconds < min) {
+      throw new TypeError(`Expected at least ${min} seconds`)
+    }
+    return seconds
+  }
+
+/**
+ * A date written out in a query string, as ISO-8601 or epoch milliseconds.
+ */
+export const asQueryDate: Cleaner<Date> = raw => {
+  if (raw instanceof Date) return raw
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new TypeError('Expected an ISO-8601 date or epoch milliseconds')
+  }
+  const ms = Number(raw)
+  const date = Number.isFinite(ms) ? new Date(ms) : new Date(raw)
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError('Expected an ISO-8601 date or epoch milliseconds')
+  }
+  return date
+}
+
+/**
+ * `EdgeTokenId` in request position.
+ *
+ * The native asset is `null`, which a query string can only spell as the text
+ * "null" — and the CLI sends every tokenId as a string, body or query alike —
+ * so both that text and a real `null` mean the native asset. `asTokenId` is
+ * the response-position cleaner and deliberately does *not* do this: a
+ * tokenId core hands back is already the right shape, and reading `"null"`
+ * there would be guessing.
+ *
+ * `''` cannot reach a cleaner: `queryToObject` reads an empty query value as
+ * an absent parameter, and `asOptional` intercepts nullish before this runs.
+ */
+export const asRequestTokenId: Cleaner<string | null> = raw => {
+  if (raw === null || raw === 'null') return null
+  if (typeof raw === 'string') return raw
+  throw new TypeError('Expected a token id or null')
+}
+
+/** A core value passed through untouched. Documented by name in JSDoc. */
+export const asCoreValue = asUnknown
+
+export const asVoid = asValue(undefined)
+
+/** A bare acknowledgement. */
+export const asOk = asObject({
+  ok: doc(asBoolean, 'Always true; a failure arrives as an error envelope.')
+})
+
+/** An acknowledgement naming the handle the call consumed. */
+export const asOkObject = asObject({
+  ok: doc(asBoolean, 'Always true; a failure arrives as an error envelope.'),
+  objectId: doc(asString, 'The handle this call consumed. It is now expired.')
+})
+
+export const asLoginMethod = asValue(
+  'password',
+  'pin',
+  'key',
+  'recovery',
+  'edge',
+  'create'
+)
+
+/** Returned by every successful login and by keepalive. */
+export const asSession = asObject({
+  sessionId: doc(
+    asString,
+    'Identifies this login. Every account-scoped call carries it, and the ' +
+      'CLI stores the most recent one so commands can omit it.'
+  ),
+  username: doc(
+    asOptional(asString),
+    'Absent for a light account, which has no username.'
+  ),
+  rootLoginId: doc(
+    asString,
+    'The account root, stable across appIds. Two sessions sharing it are the ' +
+      'same account.'
+  ),
+  loginMethod: doc(asLoginMethod, 'How this session was established.'),
+  autoLogoutSeconds: doc(
+    asNumber,
+    'Idle time before the engine logs the account out. 0 disables it.'
+  ),
+  expiresAt: doc(
+    asEither(asString, asValue(null)),
+    'When auto-logout will fire, or null when it is disabled.'
+  ),
+  lastActivityAt: doc(
+    asString,
+    'Last call on this session, which is what auto-logout measures from.'
+  ),
+  createdAt: doc(asString, 'When the login completed.')
+})
+
+/**
+ * Returned by `engine-sessions`, whose `sessionId` is truncated.
+ *
+ * The listing needs no session of its own, so publishing usable ids made one
+ * unauthenticated call a credential dispenser. Same shape otherwise, built
+ * from `asSession` so the two cannot drift.
+ */
+export const asSessionListing = asObject({
+  ...asSession.shape,
+  sessionId: doc(
+    asString,
+    'The first ten characters of the session id, followed by an ellipsis. ' +
+      'This listing is a diagnostic: a session id is a bearer token, and a ' +
+      'caller entitled to one already has it from its own login response.'
+  )
+})
+
+/** One currency wallet. `walletId` and `id` are the same value. */
+export const asWalletSummary = asObject({
+  walletId: doc(
+    asString,
+    'The full wallet id. Commands taking a wallet accept any unique prefix.'
+  ),
+  id: doc(asString, 'Same value as `walletId`; core exposes both names.'),
+  type: doc(asString, 'Key type, such as `wallet:bitcoin`.'),
+  name: doc(
+    asEither(asString, asValue(null)),
+    'User-assigned name, null until one is set.'
+  ),
+  pluginId: doc(asString, 'Currency plugin backing this wallet.'),
+  currencyCode: doc(asString, 'Ticker for the native asset.'),
+  fiatCurrencyCode: doc(
+    asString,
+    'Fiat the wallet reports value in, as `iso:USD`.'
+  ),
+  blockHeight: doc(asNumber, 'Chain height this wallet has seen.'),
+  syncStatus: doc(asCoreValue, '`EdgeWalletSyncStatus` from core.'),
+  syncRatio: doc(
+    asOptional(asString),
+    'Sync progress as a percentage, for display.'
+  ),
+  paused: doc(asBoolean, 'True while the engine is not syncing this wallet.'),
+  imported: doc(
+    asOptional(asBoolean),
+    'True when the keys came from an import rather than being generated here.'
+  ),
+  created: doc(
+    asEither(asString, asValue(null)),
+    'When the wallet was created, null for wallets predating the field.'
+  ),
+  enabledTokenIds: doc(asArray(asString), 'Tokens the user turned on.'),
+  detectedTokenIds: doc(
+    asArray(asString),
+    'Tokens found on-chain that are not enabled yet.'
+  ),
+  unactivatedTokenIds: doc(
+    asArray(asString),
+    'Enabled tokens still awaiting on-chain activation.'
+  )
+})
+
+/** One asset balance, with the display amount already divided out. */
+export const asBalance = asObject({
+  tokenId: doc(asTokenId, 'The asset, or null for the chain\u2019s own coin.'),
+  currencyCode: doc(asString, 'Ticker for this asset.'),
+  nativeAmount: doc(
+    asString,
+    'The balance in the smallest unit, as a decimal string.'
+  ),
+  displayAmount: doc(
+    asEither(asString, asNull),
+    'The same balance divided by the display multiplier, or null for a token whose config the plugin no longer carries — there is no denomination to divide by.'
+  ),
+  unknownToken: doc(
+    asBoolean,
+    'True when the plugin reports a balance for a token it has no config for, so `displayAmount` and `currencyCode` cannot be resolved.'
+  )
+})
+
+/** Identity for a method-bearing core value held server-side. */
+export const asObjectHandle = asObject({
+  objectId: doc(
+    asString,
+    'Handle for the value the engine is holding. Pass it to the calls that consume it.'
+  ),
+  kind: doc(
+    asValue('transaction', 'pendingLogin', 'swap', 'lobby'),
+    'What the handle refers to, which decides the calls that accept it.'
+  ),
+  createdAt: doc(asString, 'When the engine took the handle.'),
+  expiresAt: doc(
+    asString,
+    'When the engine drops the handle. Handles live 5 minutes.'
+  ),
+  sessionId: doc(
+    asOptional(asString),
+    'Session that created the handle; only that session may use it.'
+  ),
+  walletId: doc(
+    asOptional(asString),
+    'Wallet the handle is bound to, when it belongs to one.'
+  )
+})
+
+/** An object handle carrying the transaction it refers to. */
+export const asTransactionHandle = asObject({
+  objectId: doc(
+    asString,
+    'Handle for the value the engine is holding. Pass it to the calls that consume it.'
+  ),
+  kind: doc(
+    asValue('transaction'),
+    'What the handle refers to, which decides the calls that accept it.'
+  ),
+  expiresAt: doc(
+    asString,
+    'When the engine drops the handle. Handles live 5 minutes.'
+  ),
+  sessionId: doc(
+    asOptional(asString),
+    'Session that created the handle; only that session may use it.'
+  ),
+  walletId: doc(
+    asOptional(asString),
+    'Wallet the handle is bound to, when it belongs to one.'
+  ),
+  transaction: doc(
+    asCoreValue,
+    '`EdgeTransaction` as it stands after this step. Unsigned after ' +
+      '`make-spend`, signed after `sign-tx`, and carrying a txid once broadcast.'
+  )
+})
+
+/** A swap quote, held under a `swap_` handle with a 5 minute TTL. */
+export const asSwapQuote = asObject({
+  objectId: doc(
+    asString,
+    'Handle for the value the engine is holding. Pass it to the calls that consume it.'
+  ),
+  kind: doc(
+    asValue('swap'),
+    'What the handle refers to, which decides the calls that accept it.'
+  ),
+  expiresAt: doc(
+    asString,
+    'When the engine drops the handle. Handles live 5 minutes.'
+  ),
+  pluginId: doc(asString, 'Swap provider that produced this quote.'),
+  isEstimate: doc(
+    asBoolean,
+    'True when the provider may settle at a different rate than quoted.'
+  ),
+  canBePartial: doc(
+    asEither(asBoolean, asValue(null)),
+    'True when the provider may fill only part of the order. Null when it ' +
+      'does not say.'
+  ),
+  maxFulfillmentSeconds: doc(
+    asEither(asNumber, asValue(null)),
+    'Longest the provider expects a partial fill to take.'
+  ),
+  minReceiveAmount: doc(
+    asEither(asString, asValue(null)),
+    'Least the provider guarantees to deliver, in the destination\u2019s ' +
+      'native units.'
+  ),
+  fromNativeAmount: doc(asString, 'Amount leaving the source wallet.'),
+  toNativeAmount: doc(asString, 'Amount arriving in the destination wallet.'),
+  networkFee: doc(
+    asObject({ nativeAmount: asString, tokenId: asTokenId }),
+    'On-chain fee for the sending transaction. It is not the provider\u2019s ' +
+      'own spread, which is already in the rate.'
+  ),
+  quoteExpirationDate: doc(
+    asEither(asString, asValue(null)),
+    'When the provider stops honouring the rate. Null when it does not expire.'
+  ),
+  swapInfo: doc(
+    asObject({
+      pluginId: asString,
+      displayName: asString,
+      supportEmail: asString,
+      isDex: asEither(asBoolean, asValue(null))
+    }),
+    '`EdgeSwapInfo`: how to name the provider and where to send complaints.'
+  ),
+  request: doc(
+    asObject({
+      fromTokenId: asTokenId,
+      toTokenId: asTokenId,
+      nativeAmount: asString,
+      quoteFor: asValue('from', 'to', 'max'),
+      fromWalletId: asString,
+      toWalletId: asString
+    }),
+    'The `EdgeSwapRequest` this quote answers, echoed back so quotes from ' +
+      'different plugins can be compared without tracking what was asked.'
+  )
+})
+
+/** A QR / lobby login in progress. `session` fills once `state` is `done`. */
+export const asPendingEdgeLogin = asObject({
+  objectId: doc(
+    asString,
+    'Handle for the value the engine is holding. Pass it to the calls that consume it.'
+  ),
+  pendingId: doc(
+    asString,
+    'Same value as `objectId`, under the name the poll command takes.'
+  ),
+  kind: doc(
+    asValue('pendingLogin'),
+    'What the handle refers to, which decides the calls that accept it.'
+  ),
+  expiresAt: doc(
+    asEither(asString, asValue(null)),
+    'When the lobby closes and the QR code stops working.'
+  ),
+  lobbyId: doc(asString, 'Lobby the phone connects to.'),
+  uri: doc(
+    asString,
+    'The `edge://` URI to render as a QR code for the phone to scan.'
+  ),
+  state: doc(
+    asValue('pending', 'started', 'done', 'error', 'closed'),
+    'How far the login has got: `pending` before the phone scans, `started` ' +
+      'once it has, and `done` when `session` is filled in.'
+  ),
+  username: doc(
+    asEither(asString, asValue(null)),
+    'Account that approved the login, known once the phone has scanned.'
+  ),
+  session: doc(
+    asEither(asSession, asValue(null)),
+    'The session, null until `state` is `done`.'
+  ),
+  error: doc(
+    asEither(asString, asValue(null)),
+    'Why the login failed, set only when `state` is `error`.'
+  )
+})
+
+/** The enabled token set after a change. */
+export const asEnabledTokens = asObject({
+  enabledTokenIds: doc(
+    asArray(asString),
+    'The wallet\u2019s enabled tokens after the change, not just what changed.'
+  )
+})
+
+/*
+ * The error envelope has no cleaner here, deliberately.
+ *
+ * Every other published shape is a cleaner in this file, because the
+ * generator reads the route declarations. The envelope is not attached to a
+ * route — it is the response of *every* route's failure — so
+ * `scripts/buildApiDocs.ts` writes `components.schemas.ErrorEnvelope` by
+ * hand, and the runtime shape is named once as `ErrorResponse` in
+ * `errors.ts`, which `output.ts` now uses as well.
+ *
+ * A fourth declaration lived here, exported and referenced by nothing, which
+ * read as the source of truth for a document it had no part in generating.
+ */
+
+// `asDate` is re-exported so route files can describe date fields without
+// each importing it from `cleaners` directly.
+export { asDate }
+
+// ---------------------------------------------------------------------------
+// Persisted shapes
+//
+// These three go into the wallet's synced transaction file, and core does not
+// validate them between an HTTP body and the disklet. Both failure modes are
+// silent. A non-object `metadata` merges nothing, because `mergeMetadata`
+// only reads properties off its argument, so the route answers 204 having
+// written nothing. An object with a wrong field type is dispatched to the
+// in-memory transaction *before* `transactionFile.save` runs its own cleaner
+// and throws, so the engine serves metadata that disk does not have for the
+// life of the daemon, and the caller gets a 500 from core where the route
+// declares BAD_REQUEST.
+// ---------------------------------------------------------------------------
+
+/**
+ * Refuse an array where an object is meant.
+ *
+ * `asObject` accepts one, because an array *is* an object in JS — and for a
+ * value that core merges field by field that is the silent case:
+ * `mergeMetadata` reads no properties off `[]`, so the route answered 204
+ * having written nothing.
+ */
+function asNotArray<T>(cleaner: Cleaner<T>): Cleaner<T> {
+  return raw => {
+    if (Array.isArray(raw)) {
+      throw new TypeError('Expected an object, got an array')
+    }
+    return cleaner(raw)
+  }
+}
+
+/**
+ * Optional in the `EdgeMetadataChange` sense, where `undefined` leaves a field
+ * alone and `null` deletes it.
+ *
+ * `asOptional` cannot express this: it maps *both* to its fallback, so a
+ * `{"notes": null}` would have reached core as `{}` and silently stopped
+ * deleting the note.
+ */
+function asChange<T>(cleaner: Cleaner<T>): Cleaner<T | null | undefined> {
+  return raw => {
+    if (raw === undefined) return undefined
+    if (raw === null) return null
+    return cleaner(raw)
+  }
+}
+
+/** `null` deletes a saved value; an absent field leaves it unchanged. */
+export const asEdgeMetadataChange: Cleaner<EdgeMetadataChange> = asNotArray(
+  asObject({
+    bizId: asChange(asNumber),
+    category: asChange(asString),
+    exchangeAmount: asOptional(asObject(asEither(asNumber, asNull))),
+    name: asChange(asString),
+    notes: asChange(asString)
+  })
+)
+
+/** `EdgeMetadata`, for the write paths that do not accept a deletion. */
+export const asEdgeMetadata: Cleaner<EdgeMetadata> = asNotArray(
+  asObject({
+    bizId: asOptional(asNumber),
+    category: asOptional(asString),
+    exchangeAmount: asOptional(asObject(asNumber)),
+    name: asOptional(asString),
+    notes: asOptional(asString)
+  })
+)
+
+/**
+ * Native units as core stores them: digits only.
+ *
+ * `asString` here was the one field of the five `asEdgeTxAction*` cleaners
+ * looser than core's own, and it re-opened the hole those cleaners exist to
+ * close. `save-tx-action` with `"nativeAmount":"1.5"` passed this route,
+ * then core dispatched `CURRENCY_WALLET_FILE_CHANGED` *before* awaiting the
+ * file save, whose `uncleaner(asTransactionFile)` rejected it — so the
+ * engine served a `savedAction` the disk did not have for the life of the
+ * daemon, and the caller got a 500 on a route declaring only 400 and 404.
+ */
+const asIntegerString: Cleaner<string> = raw => {
+  const value = asString(raw)
+  if (!/^\d+$/.test(value)) {
+    throw new TypeError(`"${value}" is not an integer string`)
+  }
+  return value
+}
+
+const asEdgeAssetAmount = asObject({
+  pluginId: asString,
+  tokenId: asEither(asString, asNull),
+  nativeAmount: asOptional(asIntegerString)
+})
+
+const asEdgeFiatAmount = asObject({
+  fiatCurrencyCode: asString,
+  fiatAmount: asString
+})
+
+export const asEdgeAssetAction: Cleaner<EdgeAssetAction> = asNotArray(
+  asObject({
+    assetActionType: asValue<EdgeAssetActionType[]>(
+      'claim',
+      'claimOrder',
+      'stake',
+      'stakeNetworkFee',
+      'stakeOrder',
+      'unstake',
+      'unstakeNetworkFee',
+      'unstakeOrder',
+      'swap',
+      'swapNetworkFee',
+      'swapOrderPost',
+      'swapOrderFill',
+      'swapOrderCancel',
+      'buy',
+      'sell',
+      'sellNetworkFee',
+      'tokenApproval',
+      'transfer',
+      'transferNetworkFee',
+      'giftCard'
+    )
+  })
+)
+
+const asEdgeTxActionSwap = asObject({
+  actionType: asValue<Array<'swap'>>('swap'),
+  swapInfo: asObject({
+    pluginId: asString,
+    displayName: asString,
+    isDex: asOptional(asBoolean),
+    orderUri: asOptional(asString),
+    supportEmail: asString
+  }),
+  orderId: asOptional(asString),
+  orderUri: asOptional(asString),
+  isEstimate: asOptional(asBoolean),
+  canBePartial: asOptional(asBoolean),
+  fromAsset: asEdgeAssetAmount,
+  toAsset: asEdgeAssetAmount,
+  payoutAddress: asString,
+  payoutWalletId: asString,
+  refundAddress: asOptional(asString)
+})
+
+const asEdgeTxActionStake = asObject({
+  actionType: asValue<Array<'stake'>>('stake'),
+  pluginId: asString,
+  stakeAssets: asArray(asEdgeAssetAmount)
+})
+
+const asEdgeTxActionFiat = asObject({
+  actionType: asValue<Array<'fiat'>>('fiat'),
+  orderId: asString,
+  orderUri: asOptional(asString),
+  isEstimate: asBoolean,
+  fiatPlugin: asObject({
+    providerId: asString,
+    providerDisplayName: asString,
+    supportEmail: asOptional(asString)
+  }),
+  payinAddress: asOptional(asString),
+  payoutAddress: asOptional(asString),
+  fiatAsset: asEdgeFiatAmount,
+  cryptoAsset: asEdgeAssetAmount
+})
+
+const asEdgeTxActionTokenApproval = asObject({
+  actionType: asValue<Array<'tokenApproval'>>('tokenApproval'),
+  tokenApproved: asEdgeAssetAmount,
+  tokenContractAddress: asString,
+  contractAddress: asString
+})
+
+const asEdgeTxActionGiftCard = asObject({
+  actionType: asValue<Array<'giftCard'>>('giftCard'),
+  orderId: asString,
+  orderUri: asOptional(asString),
+  productId: asOptional(asString),
+  quoteId: asOptional(asString),
+  provider: asObject({
+    providerId: asString,
+    displayName: asString,
+    supportEmail: asOptional(asString)
+  }),
+  card: asObject({
+    name: asString,
+    imageUrl: asOptional(asString),
+    fiatAmount: asString,
+    fiatCurrencyCode: asString
+  }),
+  redemption: asOptional(
+    asObject({
+      code: asOptional(asString),
+      url: asOptional(asString)
+    })
+  )
+})
+
+const txActionCleaners: Record<string, Cleaner<EdgeTxAction>> = {
+  swap: asEdgeTxActionSwap,
+  stake: asEdgeTxActionStake,
+  fiat: asEdgeTxActionFiat,
+  tokenApproval: asEdgeTxActionTokenApproval,
+  giftCard: asEdgeTxActionGiftCard
+}
+
+/**
+ * The `actionType` union, dispatched on the discriminant core uses.
+ *
+ * Dispatched rather than `asEither`, which reports only the last alternative
+ * it tried — `{ actionType: 'stake' }` with a missing field complained
+ * `Expected "giftCard"`, naming neither the field nor the actual shape.
+ */
+export const asEdgeTxAction: Cleaner<EdgeTxAction> = asNotArray(raw => {
+  const { actionType } = asObject({ actionType: asString }).withRest(raw)
+  const cleaner = txActionCleaners[actionType]
+  if (cleaner == null) {
+    throw new TypeError(
+      `Unknown actionType "${actionType}": expected one of ${Object.keys(
+        txActionCleaners
+      ).join(', ')}`
+    )
+  }
+  return cleaner(raw)
+})
+
+/**
+ * One plugin's entry in `keys.json` or the info server's signed `appKeys`.
+ *
+ * The payload is genuinely open-ended per plugin, so `.withRest` keeps
+ * whatever a plugin needs; the two fields this code reads are not open-ended
+ * and are checked. `false` in place of the object disables the plugin.
+ */
+export const asPluginKeysEntry = asObject({
+  enabled: asOptional(asBoolean),
+  edgeApiKey: asOptional(asString)
+}).withRest
+
+// ---------------------------------------------------------------------------
+// Structured request shapes
+//
+// These were declared `asCoreValue` (i.e. `asUnknown`) and cast in the
+// handler, so a malformed value became a 500 from a property access rather
+// than the 400 the route declares — `create-currency-wallets
+// --create-wallets='[null]'` answered
+// `INTERNAL_ERROR: Cannot read properties of null (reading 'walletType')`.
+// `.withRest` keeps whatever core and the plugins add; only the fields a
+// handler or core itself requires are named.
+// ---------------------------------------------------------------------------
+
+/** One entry of a batch wallet create or split. */
+export const asCreateCurrencyWallet = asObject({
+  walletType: asString,
+  name: asOptional(asString),
+  fiatCurrencyCode: asOptional(asString)
+}).withRest
+
+/** A spend target: where the money goes and how much. */
+export const asSpendTarget = asObject({
+  publicAddress: asOptional(asString),
+  nativeAmount: asOptional(asString),
+  uniqueIdentifier: asOptional(asString),
+  memo: asOptional(asString),
+  otherParams: asOptional(asObject(asUnknown))
+}).withRest
+
+/**
+ * An `EdgeSpendInfo` as a caller may send it.
+ *
+ * `spendTargets` is required because every handler reads it: an empty object
+ * passed `isPlainObject` and then threw on `spendInfo.spendTargets.length`.
+ */
+/**
+ * The body `sweep-private-keys` really takes.
+ *
+ * `asSpendInfo` is the wrong cleaner for it — a sweep legitimately has no
+ * `spendTargets` — and `asCoreValue` plus a cast meant
+ * `--spend-info='{}'` passed the declaration and reached
+ * `UtxoEngine.sweepPrivateKeys`, which throws a plain `Error`: a 500 on a
+ * route declaring 400 and 422. It also meant `privateKeys`, the field the
+ * route actually requires, appeared nowhere in the published type.
+ */
+export const asSweepSpendInfo = asObject({
+  privateKeys: doc(
+    asArray(asString),
+    'The keys to sweep from, in the plugin\u2019s import format.'
+  ),
+  tokenId: asOptional(asRequestTokenId, null),
+  spendTargets: asOptional(asArray(asSpendTarget), () => []),
+  metadata: asOptional(asEdgeMetadata),
+  memos: asOptional(asArray(asObject(asUnknown)))
+}).withRest
+
+/**
+ * Enough of an `EdgeTransaction` to be recognisable.
+ *
+ * `accelerate --transaction='{}'` reached `wallet.accelerate` with a
+ * non-transaction through `asCoreValue` and a cast. `.withRest`, because a
+ * transaction carries plugin-specific fields this engine has no business
+ * enumerating.
+ */
+export const asTransactionInput = asObject({
+  txid: doc(asString, 'The transaction to bump.'),
+  currencyCode: asOptional(asString),
+  nativeAmount: asOptional(asString),
+  networkFee: asOptional(asString),
+  walletId: asOptional(asString)
+}).withRest
+
+export const asSpendInfo = asObject({
+  spendTargets: asArray(asSpendTarget),
+  // `asOptional(asString, null)`, not `asOptional(asEither(asString, asNull))`:
+  // `asOptional` intercepts a nullish value before the inner cleaner runs, so
+  // the `asNull` arm was unreachable.
+  tokenId: asOptional(asString, null),
+  metadata: asOptional(asEdgeMetadata),
+  networkFeeOption: asOptional(asString),
+  customNetworkFee: asOptional(asObject(asUnknown)),
+  rbfTxid: asOptional(asString),
+  memos: asOptional(asArray(asObject(asUnknown))),
+  assetAction: asOptional(asEdgeAssetAction),
+  savedAction: asOptional(asEdgeTxAction),
+  otherParams: asOptional(asObject(asUnknown))
+}).withRest
+
+/**
+ * The convenience spend body, shared by the three routes that take it.
+ *
+ * `get-max-spendable`, `spend` and `make-spend` all accept the same seven
+ * fields, and all three wrote them out verbatim — including the long
+ * `spendInfo` prose and the `amount` alias line. These declarations *are*
+ * the published reference, so three copies meant one wording change
+ * published the same request three different ways, and no gate compares
+ * them: `checkCoreAlignment` cannot, because `spend` declares `core: null`.
+ */
+export const asSpendShorthandBody = asObject({
+  walletId: asWalletId,
+  spendInfo: asOptional(
+    doc(
+      asSpendInfo,
+      'A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required.'
+    )
+  ),
+  to: asOptional(doc(asString, SPEND_TO_DOC)),
+  nativeAmount: asOptional(doc(asString, SPEND_AMOUNT_DOC)),
+  amount: asOptional(doc(asString, SPEND_AMOUNT_ALIAS_DOC)),
+  tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+  metadata: asOptional(doc(asEdgeMetadata, SPEND_METADATA_DOC))
+})
+
+/** Plugin key material for `create-wallet`. */
+export const asWalletKeys = asObject(asUnknown)
diff --git a/src/cli/engine/server.ts b/src/cli/engine/server.ts
new file mode 100644
index 00000000000..30baa62b77f
--- /dev/null
+++ b/src/cli/engine/server.ts
@@ -0,0 +1,342 @@
+/**
+ * The HTTP layer: one handler, two listeners.
+ *
+ * It owns everything that happens to a request before and after a route:
+ * the TCP transport's authentication, the shutting-down gate, the SSE
+ * special case — which bypasses the router because an event stream is not a
+ * request/response — the body size limits, the content-type gate, the
+ * session's in-flight hold, and turning whatever a handler throws into the
+ * published error envelope.
+ *
+ * It does *not* decide what a route means. Path matching is `router.ts`,
+ * validation is the cleaners on each `route()`, and the core→HTTP error
+ * mapping is `errors.ts`.
+ */
+import fs from 'fs'
+import http, { type IncomingMessage, type ServerResponse } from 'http'
+
+import { API_VERSION } from './apiVersion'
+import { EngineError, engineError, toErrorBody } from './errors'
+import { readJsonBody, stringifyJson } from './json'
+import type { EngineState, Router } from './router'
+import { engineEvents } from './routes/events'
+import { checkTcpRequest, type TcpGuard } from './transportAuth'
+
+/** Drop connections that never finish sending headers or a body. */
+const HEADERS_TIMEOUT_MS = 20_000
+const REQUEST_TIMEOUT_MS = 120_000
+
+function setCommonHeaders(res: ServerResponse): void {
+  res.setHeader('X-Edge-Api-Version', API_VERSION)
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  setCommonHeaders(res)
+  res.statusCode = status
+  if (body === undefined || status === 204) {
+    res.end()
+    return
+  }
+  res.end(stringifyJson(body))
+}
+
+/**
+ * One handler per listener.
+ *
+ * `guard` is supplied for the TCP listener and omitted for the unix socket,
+ * whose `0600` mode inside a `0700` directory is already the check. See
+ * `transportAuth.ts` for why a TCP port needs more than that.
+ */
+/**
+ * Validate the SSE query against the route's declaration.
+ *
+ * `/engine/events` is served directly rather than through the router, so
+ * nothing applied its `query` cleaner. Running it here keeps a stream route's
+ * declaration enforced like every other route's, and turns a bad value into
+ * `400 BAD_REQUEST` instead of silently ignoring it.
+ */
+function cleanSseQuery(url: URL): void {
+  const cleaner = engineEvents.query
+  if (cleaner == null) return
+  const raw: Record<string, string> = {}
+  for (const field of ['sessionId', 'walletId']) {
+    const value = url.searchParams.get(field)
+    if (value != null && value !== '') raw[field] = value
+  }
+  try {
+    cleaner(raw)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw engineError('BAD_REQUEST', message, 400)
+  }
+}
+
+export function createRequestHandler(
+  state: EngineState,
+  router: Router,
+  guard?: TcpGuard
+): (req: IncomingMessage, res: ServerResponse) => void {
+  return (req, res) => {
+    handleRequest(state, router, req, res, guard).catch((error: unknown) => {
+      // The last sink. The reachable escapes are in the error path itself —
+      // `sendJson` stringifying an error's `details`, or `endRequest` in the
+      // `finally` — and swallowing them left the response unended, so the
+      // client waited out its own 120s socket timeout and reported
+      // `Request timed out` while the engine log said nothing.
+      const message = error instanceof Error ? error.message : String(error)
+      state.logger.error('Unhandled request failure', { message })
+      if (!res.writableEnded) {
+        res.statusCode = 500
+        res.end()
+      }
+    })
+  }
+}
+
+async function handleRequest(
+  state: EngineState,
+  router: Router,
+  req: IncomingMessage,
+  res: ServerResponse,
+  guard?: TcpGuard
+): Promise<void> {
+  state.idle.touch()
+  state.idle.beginRequest()
+
+  try {
+    // First, before the route table, the body and even the shutdown state: a
+    // caller that cannot authenticate learns nothing about this engine.
+    if (guard != null) checkTcpRequest(req, guard)
+
+    const host = req.headers.host ?? 'localhost'
+    const url = new URL(req.url ?? '/', `http://${host}`)
+    const pathname = url.pathname
+
+    // Stopping an engine that is already stopping has succeeded, so the stop
+    // route is exempt from the 503. Answering it with
+    // `ENGINE_SHUTTING_DOWN` meant a client that retries that condition —
+    // which it must, so a command landing in the teardown window reaches a
+    // fresh engine — started a *replacement* daemon in answer to a request
+    // to stop one.
+    const isStopRequest = req.method === 'POST' && pathname === '/engine/stop'
+    if (state.shuttingDown && !isStopRequest) {
+      throw engineError('ENGINE_SHUTTING_DOWN', 'Engine is shutting down', 503)
+    }
+
+    // SSE special-case
+    if (req.method === 'GET' && pathname === '/engine/events') {
+      // An optional `sessionId` scopes the stream to one account, which is
+      // what makes `closeScope` reachable: without it every client was
+      // context-scoped and an auto-logout closed nothing, though the
+      // published reference said otherwise.
+      // `?type=` repeated narrows the stream at the transport, so a caller
+      // asking for one event type does not pay for the whole firehose.
+      const wanted = url.searchParams.getAll('type').filter(t => t !== '')
+      const types = wanted.length > 0 ? new Set(wanted) : undefined
+      // Through the route's own cleaner, even though this path is served
+      // outside the router: `registerRoute` returns early for a `stream`
+      // route, so the declaration was validated nowhere and the hand parsing
+      // below was the only contract. A declared field with a real type would
+      // have been accepted in any shape at all.
+      cleanSseQuery(url)
+      const scopeSession = url.searchParams.get('sessionId')
+      if (scopeSession != null && scopeSession !== '') {
+        // Resolve it, so a stream cannot be opened against a session that
+        // does not exist and then never be closed by anything.
+        state.sessions.get(scopeSession)
+        const scopeWallet = url.searchParams.get('walletId')
+        state.events.addSseClient(
+          res,
+          scopeWallet != null && scopeWallet !== ''
+            ? { kind: 'wallet', sessionId: scopeSession, walletId: scopeWallet }
+            : { kind: 'session', sessionId: scopeSession },
+          types
+        )
+        return
+      }
+      state.events.addSseClient(res, { kind: 'context' }, types)
+      return
+    }
+
+    const matched = router.match(req.method ?? 'GET', pathname)
+    if (matched == null) {
+      // Check if path exists with different method
+      const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
+      const other = methods.find(
+        m =>
+          m !== (req.method ?? '').toUpperCase() &&
+          router.match(m, pathname) != null
+      )
+      if (other != null) {
+        throw engineError(
+          'METHOD_NOT_ALLOWED',
+          `Method ${req.method} not allowed`,
+          405
+        )
+      }
+      throw engineError('NOT_FOUND', `No route for ${pathname}`, 404)
+    }
+
+    let body: unknown
+    if (
+      req.method === 'POST' ||
+      req.method === 'PUT' ||
+      req.method === 'PATCH'
+    ) {
+      const ct = String(req.headers['content-type'] ?? '')
+      const len = Number(req.headers['content-length'] ?? '0')
+      const hasBody = len > 0 || req.headers['transfer-encoding'] != null
+      if (hasBody && !ct.includes('application/json')) {
+        throw engineError(
+          'UNSUPPORTED_MEDIA_TYPE',
+          'Content-Type must be application/json',
+          415
+        )
+      }
+      try {
+        body = await readJsonBody(req)
+      } catch (error: unknown) {
+        // Narrowed once, so the `message` read needs no cast: the code test
+        // can only pass when this already held, and a cast here would keep
+        // compiling if `json.ts` ever threw something that is not an Error.
+        if (error instanceof EngineError) {
+          if (error.code === 'BAD_REQUEST') {
+            throw engineError('BAD_REQUEST', 'Invalid JSON body', 400)
+          }
+          if (error.code === 'PAYLOAD_TOO_LARGE') {
+            // Answer first, then drop the connection so the rest of the
+            // oversized upload is never read into memory.
+            res.setHeader('Connection', 'close')
+            res.once('finish', () => req.destroy())
+            throw engineError('PAYLOAD_TOO_LARGE', error.message, 413)
+          }
+        }
+        throw error
+      }
+    }
+
+    // Hold the session open for the duration of the handler, the same way
+    // `idle.beginRequest` holds the engine. The auto-logout ticker records
+    // only when a request *started*, so a call that outlives the window —
+    // a cold `wait-for-all-wallets`, a `resync-blockchain`, a `spend` on a
+    // congested chain — could otherwise be logged out from underneath itself.
+    const releaseSession =
+      matched.params.sessionId != null
+        ? state.sessions.beginRequest(matched.params.sessionId)
+        : undefined
+    let result: unknown
+    try {
+      result = await matched.handler({
+        state,
+        req,
+        res,
+        params: matched.params,
+        query: url.searchParams,
+        body
+      })
+    } finally {
+      releaseSession?.()
+    }
+
+    if (res.writableEnded) return
+
+    if (result === undefined) {
+      sendJson(res, 204, undefined)
+    } else {
+      sendJson(res, 200, result)
+    }
+  } catch (error: unknown) {
+    if (res.writableEnded) return
+    const { status, body } = toErrorBody(error)
+    sendJson(res, status, body)
+  } finally {
+    state.idle.endRequest()
+  }
+}
+
+/**
+ * Report a listener error after `listen` has resolved.
+ *
+ * The `once('error', reject)` that guards startup stays bound afterwards and
+ * would silently swallow any later error, leaving a dead socket behind an
+ * engine that still looks healthy.
+ */
+function reportLateErrors(server: http.Server, what: string): void {
+  server.on('error', (error: Error) => {
+    console.error(`[edge-engine] ${what} listener error: ${error.message}`)
+  })
+}
+
+/**
+ * Start one listener and wait for it to be bound.
+ *
+ * The two entries below were 24-line near-duplicates: same
+ * `createServer`, same two timeouts, same `once('error')` / `listen` /
+ * `off('error')` dance, same late-error reporting. Only the `listen`
+ * arguments and what happens after binding differ, so that is all either one
+ * passes.
+ *
+ * The `once('error')` matters: without it a bind failure — a socket another
+ * engine already owns, a port in use — is an unhandled `'error'` event and
+ * therefore an uncaught exception, instead of a rejection the caller can
+ * report.
+ */
+async function listenOn(
+  handler: (req: IncomingMessage, res: ServerResponse) => void,
+  label: string,
+  bind: (server: http.Server, onListening: () => void) => void,
+  afterBind?: () => void
+): Promise<http.Server> {
+  const server = http.createServer(handler)
+  server.headersTimeout = HEADERS_TIMEOUT_MS
+  server.requestTimeout = REQUEST_TIMEOUT_MS
+  await new Promise<void>((resolve, reject) => {
+    const onStartupError = (error: Error): void => {
+      reject(error)
+    }
+    server.once('error', onStartupError)
+    bind(server, () => {
+      server.off('error', onStartupError)
+      afterBind?.()
+      resolve()
+    })
+  })
+  reportLateErrors(server, label)
+  return server
+}
+
+export async function listenUnix(
+  handler: (req: IncomingMessage, res: ServerResponse) => void,
+  socketPath: string
+): Promise<http.Server> {
+  return await listenOn(
+    handler,
+    'unix socket',
+    (server, onListening) => server.listen(socketPath, onListening),
+    () => {
+      // `0600` is this transport's entire authentication: only this user's
+      // processes can connect, which is why the unix socket needs no token.
+      try {
+        fs.chmodSync(socketPath, 0o600)
+      } catch {
+        // ignore
+      }
+    }
+  )
+}
+
+export async function listenTcp(
+  handler: (req: IncomingMessage, res: ServerResponse) => void,
+  port: number,
+  host = '127.0.0.1'
+): Promise<{ server: http.Server; port: number }> {
+  const server = await listenOn(handler, 'tcp', (s, onListening) =>
+    s.listen(port, host, onListening)
+  )
+  // The bound port, not the requested one: `--tcp=0` asks the OS to choose.
+  const address = server.address()
+  const bound =
+    address != null && typeof address === 'object' ? address.port : port
+  return { server, port: bound }
+}
diff --git a/src/cli/engine/sessions.ts b/src/cli/engine/sessions.ts
new file mode 100644
index 00000000000..4e9318c079b
--- /dev/null
+++ b/src/cli/engine/sessions.ts
@@ -0,0 +1,513 @@
+/**
+ * The session table: one `EdgeAccount` per logged-in session.
+ *
+ * A `sessionId` is a bearer token — `getSession` does a map lookup and an
+ * expiry test and nothing else — so everything here treats it as one: it is
+ * redacted in events and logs, truncated in the public listing, and the
+ * auto-logout window is the user's own synced setting, re-read on each sweep
+ * and never silently replaced by a default.
+ *
+ * It also owns the teardown order, which is load-bearing: close the
+ * session's subscriptions, release the object handles it owned, wait for the
+ * session's other requests, log the account out, emit, then clear the process
+ * caches. A handle outliving its account is a live swap quote or a signed
+ * transaction with nothing able to release it — and `account.logout()` is
+ * what invalidates them, so it comes after the release and not before. It was
+ * missing from this list while the code ran it first, which is how that
+ * inversion survived.
+ */
+import crypto from 'crypto'
+import type { EdgeAccount } from 'edge-core-js'
+
+import { base58 } from '../../util/encoding'
+import { clearRateCache } from '../../util/exchangeRates'
+import type { PeriodicTask } from '../../util/PeriodicTask'
+import {
+  readSyncedSettings,
+  readSyncedSettingsOrThrow
+} from '../../util/syncedSettingsFile'
+import { engineError } from './errors'
+import type { EventHub } from './events'
+import type { ObjectHandleStore } from './objectHandles'
+import type { asLoginMethod } from './schemas'
+import { makeSweepTicker } from './sweepTicker'
+
+/**
+ * How long a logout waits for the session's other requests to finish.
+ *
+ * Long enough to cover a broadcast on a congested chain, which is the call
+ * whose interruption actually costs something, and short enough that an
+ * operator does not conclude the command has hung. Shorter than
+ * `SHUTDOWN_DRAIN_MS`, because a shutdown has nothing else to do and a
+ * logout is one request among many.
+ */
+const LOGOUT_WAIT_MS = 30_000
+
+/**
+ * Derived from the response cleaner, not restated beside it.
+ *
+ * The same six values were declared twice, independently, in a different
+ * order: this type is what `create` accepts, and `asLoginMethod` is what the
+ * published `asSession` enforces. A seventh added to the type alone made the
+ * engine answer with a value its own `returns` cleaner rejects — a 500 under
+ * `EDGE_CLI_CHECK_RESPONSES=strict`, which the fake suite runs in — and one
+ * added to the cleaner alone published a value nothing can return.
+ */
+export type LoginMethod = ReturnType<typeof asLoginMethod>
+
+/**
+ * A session as `engine-sessions` publishes it: the id is truncated.
+ *
+ * A distinct type, so a caller of `list()` cannot be handed to something
+ * expecting a usable `sessionId` without the compiler objecting.
+ */
+export interface SessionListing extends Omit<SessionInfo, 'sessionId'> {
+  sessionId: string
+}
+
+export interface SessionInfo {
+  sessionId: string
+  username: string | undefined
+  rootLoginId: string
+  loginMethod: LoginMethod
+  autoLogoutSeconds: number
+  expiresAt: string | null
+  lastActivityAt: string
+  createdAt: string
+}
+
+export interface SessionRecord {
+  sessionId: string
+  account: EdgeAccount
+  loginMethod: LoginMethod
+  autoLogoutSeconds: number
+  lastActivityAt: number
+  createdAt: number
+  /**
+   * Requests being served against this session right now.
+   *
+   * `lastActivityAt` records only when a request *started*, so a call that
+   * outlives the auto-logout window — a cold `wait-for-all-wallets`, a
+   * `resync-blockchain`, a `spend` on a congested chain — would otherwise be
+   * logged out from underneath itself, exactly the failure `IdleShutdown`
+   * counts in-flight requests to avoid.
+   */
+  inFlight: number
+}
+
+function makeSessionId(): string {
+  const bytes = crypto.randomBytes(16)
+  return 'sess_' + base58.stringify(bytes)
+}
+
+/**
+ * The account's auto-logout setting.
+ *
+ * Read through `asSyncedSettingsSubset`, a two-field view of the same
+ * `Settings.json` the GUI writes. Not the GUI's own `asSyncedAccountSettings`
+ * — that lives in `actions/SettingsActions`, which imports Airship, so the
+ * engine cannot load it. `syncedSettingsFile.test.ts` asserts the subset's
+ * defaults still match the GUI cleaner's, which is the drift that would matter.
+ */
+async function readAutoLogoutSeconds(account: EdgeAccount): Promise<number> {
+  const { autoLogoutTimeInSeconds } = await readSyncedSettings(account)
+  return autoLogoutTimeInSeconds
+}
+
+/**
+ * The same read, letting a failure out so the ticker can keep what it has.
+ *
+ * Auto-logout is a security control, and the window is the user's choice:
+ * substituting the cleaner's 3600 on a transient read failure logs out an
+ * account that set `0` to disable it, and reports the substituted value
+ * through `engine-sessions` as if the user had chosen it.
+ */
+async function reReadAutoLogoutSeconds(account: EdgeAccount): Promise<number> {
+  const { autoLogoutTimeInSeconds } = await readSyncedSettingsOrThrow(account)
+  return autoLogoutTimeInSeconds
+}
+
+/**
+ * A session id as it is safe to print or publish.
+ *
+ * A `sessionId` is a bearer token: `getSession` does a map lookup and an
+ * expiry test and nothing else, so holding one is full account authority —
+ * `get-raw-private-key`, `get-pin`, `get-login-key` and `spend` take nothing
+ * more. Event payloads and log lines therefore carry only enough of it to
+ * correlate, and it was spelled out at four call sites, which is three too
+ * many for a redaction.
+ */
+export function redactSessionId(sessionId: string): string {
+  return sessionId.slice(0, 10) + '\u2026'
+}
+
+export class SessionStore {
+  private readonly sessions = new Map<string, SessionRecord>()
+  private ticker: PeriodicTask | null = null
+  private readonly events: EventHub
+
+  /** Notified whenever the number of live sessions changes. */
+  onSessionsChanged: (() => void) | null = null
+
+  /**
+   * The handle store, so a logout can release what the session owned.
+   *
+   * Set after construction because the two stores are peers: the engine
+   * builds the handle store with an `onExpire` that can reach sessions.
+   */
+  objects: ObjectHandleStore | null = null
+
+  constructor(events: EventHub) {
+    this.events = events
+  }
+
+  private sessionsChanged(): void {
+    try {
+      this.onSessionsChanged?.()
+    } catch {
+      // A listener must never break login/logout.
+    }
+  }
+
+  get size(): number {
+    return this.sessions.size
+  }
+
+  /**
+   * Every live session, with the ids redacted.
+   *
+   * `engine-sessions` needs no session of its own, because it is a
+   * diagnostic. Returning the full `sessionId` made it a credential
+   * dispenser: one unauthenticated call turned a reachable TCP port into
+   * account authority over every account the engine had open, and
+   * `get-login-key` turns that into a permanent one. A caller entitled to a
+   * session id already has it, from its own login response or from the
+   * `0600` session file.
+   */
+  list(): SessionListing[] {
+    return [...this.sessions.values()].map(r => ({
+      ...this.toInfo(r),
+      sessionId: redactSessionId(r.sessionId)
+    }))
+  }
+
+  async create(
+    account: EdgeAccount,
+    loginMethod: LoginMethod
+  ): Promise<SessionInfo> {
+    // edge-core-js resolves login from inside the account pixie's first
+    // update(), then returns stopUpdates. createCurrencyWallet's internal
+    // waitForCurrencyWallet throws if the new wallet id is missing from
+    // Redux, so a same-turn create after login never lands the keys.
+    // Drain the pixie stack before exposing the session so POST /wallets
+    // is safe immediately. waitForAllWallets is a no-op on empty accounts.
+    await new Promise<void>(resolve => {
+      setImmediate(resolve)
+    })
+    await account.waitForAllWallets()
+
+    const sessionId = makeSessionId()
+    const autoLogoutSeconds = await readAutoLogoutSeconds(account)
+    const now = Date.now()
+    const record: SessionRecord = {
+      sessionId,
+      account,
+      loginMethod,
+      autoLogoutSeconds,
+      lastActivityAt: now,
+      createdAt: now,
+      inFlight: 0
+    }
+    this.sessions.set(sessionId, record)
+    this.sessionsChanged()
+    // Scoped, so `scopeMatches` actually runs. Without a scope this went
+    // to every subscriber, so a stream opened against account A received
+    // account B's username and session prefix through an API whose own prose
+    // calls it account-scoped.
+    this.events.emit(
+      'session.created',
+      {
+        sessionId: redactSessionId(sessionId),
+        username: account.username,
+        loginMethod
+      },
+      { kind: 'session', sessionId }
+    )
+    return this.toInfo(record)
+  }
+
+  get(sessionId: string): SessionRecord {
+    const record = this.sessions.get(sessionId)
+    if (record == null) {
+      throw engineError('INVALID_SESSION', 'Unknown sessionId', 401)
+    }
+    if (this.isExpired(record)) {
+      // Logged, not discarded: `forceLogout` closes this session's
+      // subscriptions and releases its object handles, and for a swap that
+      // means closing the order at the exchange. A failure there is worth a
+      // line — which is the reason `makeSweepTicker` has an `onError` at
+      // all.
+      this.forceLogout(sessionId, 'expired').catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        console.warn(
+          `[edge-engine] auto-logout of ${redactSessionId(
+            sessionId
+          )} failed: ${message}`
+        )
+      })
+      throw engineError('SESSION_EXPIRED', 'Session auto-logged out', 401)
+    }
+    return record
+  }
+
+  /**
+   * The session's current state, or null when the store no longer holds it.
+   *
+   * Non-throwing, for callers that are reporting on a session rather than
+   * acting on one: a pending-login summary has to be able to say "the session
+   * this login created is gone" instead of failing the request.
+   */
+  peek(sessionId: string): SessionInfo | null {
+    const record = this.sessions.get(sessionId)
+    if (record == null) return null
+    if (this.isExpired(record)) return null
+    return this.toInfo(record)
+  }
+
+  touch(sessionId: string): SessionInfo {
+    const record = this.get(sessionId)
+    record.lastActivityAt = Date.now()
+    return this.toInfo(record)
+  }
+
+  /**
+   * Log out at the caller's request.
+   *
+   * The only difference from `forceLogout` is that an unknown session is an
+   * error here, because the caller named one. The teardown itself is shared:
+   * it was written out twice in the same order, and had already begun to
+   * drift — one copy carried the comment explaining why `closeScope` runs
+   * and the other did not — so a change to the order, which this branch made
+   * twice, had to be made in both or a logout and an auto-logout released
+   * different things.
+   */
+  async logout(sessionId: string): Promise<void> {
+    if (!this.sessions.has(sessionId)) {
+      throw engineError('INVALID_SESSION', 'Unknown sessionId', 401)
+    }
+    // The request serving this logout is itself in flight against this
+    // session, so the wait below has to discount it or it deadlocks on
+    // itself. The ticker, `shutdown` and the two `cancelled` callers hold
+    // nothing: those tear down a session freshly created for a pending edge
+    // login, which no request is running against.
+    await this.forceLogout(sessionId, 'logout', { ownRequests: 1 })
+  }
+
+  async forceLogout(
+    sessionId: string,
+    reason: 'expired' | 'shutdown' | 'cancelled' | 'logout',
+    opts: { ownRequests?: number } = {}
+  ): Promise<void> {
+    const record = this.sessions.get(sessionId)
+    if (record == null) return
+    this.sessions.delete(sessionId)
+    this.sessionsChanged()
+    // Before the account goes, which is the order this class says it owns.
+    // Both of these reach things the account owns — a live swap quote, a
+    // signed transaction — and `account.logout()` invalidates every one of
+    // them, so tearing the account down first produced exactly the state the
+    // class comment warns about and left the bounded wait in `deleteMany`
+    // protecting the ordering of `quote.close()` against an account that was
+    // already gone.
+    this.events.closeScope(sessionId, reason)
+    await this.releaseHandles(sessionId)
+    // And not while this session is still serving something else.
+    await this.waitForQuiet(record, sessionId, opts.ownRequests ?? 0)
+    try {
+      await record.account.logout()
+    } catch {
+      // best effort
+    }
+    this.events.emit(
+      'session.expired',
+      {
+        sessionId: redactSessionId(sessionId),
+        reason
+      },
+      { kind: 'session', sessionId }
+    )
+    this.clearProcessCaches()
+  }
+
+  /**
+   * Wait for the session's other requests to finish, up to LOGOUT_WAIT_MS.
+   *
+   * `SessionRecord.inFlight` exists for exactly this, and its own comment
+   * names "a `spend` on a congested chain" — but only `isExpired` read it,
+   * so the auto-logout ticker was protected and an explicit logout was not.
+   * A `POST /logout` from a second shell could therefore land between
+   * `broadcastTx` and `saveTx`: the money leaves the wallet, the client gets
+   * no response it can trust, and local history does not have the
+   * transaction until a sync finds it. That is the outcome `shutdown` drains
+   * for; the logout path has the same blast radius.
+   *
+   * Bounded, because a wedged request must not make a logout impossible —
+   * logout is a security control. What was abandoned is logged rather than
+   * passed over in silence.
+   */
+  private async waitForQuiet(
+    record: SessionRecord,
+    sessionId: string,
+    ownRequests: number
+  ): Promise<void> {
+    const deadline = Date.now() + LOGOUT_WAIT_MS
+    while (record.inFlight > ownRequests && Date.now() < deadline) {
+      await new Promise(resolve => setTimeout(resolve, 25))
+    }
+    const stuck = record.inFlight - ownRequests
+    if (stuck > 0) {
+      console.warn(
+        `[edge-engine] logging ${redactSessionId(sessionId)} out with ` +
+          `${stuck} request(s) still in flight after ${LOGOUT_WAIT_MS}ms`
+      )
+    }
+  }
+
+  /**
+   * Release every object handle the session owned.
+   *
+   * A `swap_` handle holds a live `EdgeSwapQuote` whose `onExpire` closes the
+   * order, and a staged `tx_` handle holds a signed transaction. Left in the
+   * store they outlive the account they belong to for the rest of their
+   * 5-minute TTL, with nothing able to release them earlier.
+   */
+  private async releaseHandles(sessionId: string): Promise<void> {
+    const objects = this.objects
+    if (objects == null) return
+    await objects.deleteBySession(sessionId)
+  }
+
+  /**
+   * Drop process-wide caches once no account is logged in.
+   *
+   * The rate cache was an app-session cache in the GUI; behind a daemon it
+   * grows one entry per transaction date of every wallet of every account the
+   * engine serves, and an engine started with `--idle-timeout=0` never exits.
+   * Nothing is lost by dropping it: every entry is a historical rate that can
+   * be fetched again.
+   */
+  private clearProcessCaches(): void {
+    if (this.sessions.size > 0) return
+    clearRateCache()
+  }
+
+  async logoutAll(): Promise<void> {
+    const ids = [...this.sessions.keys()]
+    for (const id of ids) {
+      await this.forceLogout(id, 'shutdown')
+    }
+  }
+
+  startAutoLogoutTicker(): void {
+    if (this.ticker != null) return
+    this.ticker = makeSweepTicker('auto-logout ticker', async () => {
+      await this.tick()
+    })
+    this.ticker.start()
+  }
+
+  stopAutoLogoutTicker(): void {
+    if (this.ticker != null) {
+      this.ticker.stop()
+      this.ticker = null
+    }
+  }
+
+  /**
+   * Hold a session open for the duration of one request.
+   *
+   * Returns a release function rather than exposing the counter, so a caller
+   * cannot forget which session it incremented. `lastActivityAt` is refreshed
+   * on release too: a long call means the session was in use the whole time,
+   * not only when it started.
+   */
+  beginRequest(sessionId: string): () => void {
+    const record = this.sessions.get(sessionId)
+    if (record == null) return () => {}
+    // Evaluated *before* the hold is taken. `isExpired` returns false while
+    // `inFlight > 0`, so taking the hold first stopped the session expiring
+    // at the moment a request arrived: the handler's own `getSession` never
+    // saw the expiry, and it then set `lastActivityAt` and re-armed the full
+    // window. Any request landing in the up-to-15-second gap after the
+    // window closed was served on a session that should have been gone, and
+    // revived it — and auto-logout is a security control, not a
+    // convenience. The counter's job is to protect a call that *outlives*
+    // the window, which is a different thing from admitting a new one.
+    if (this.isExpired(record)) {
+      throw engineError('SESSION_EXPIRED', 'Session expired; log in again', 401)
+    }
+    record.inFlight++
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      record.inFlight--
+      record.lastActivityAt = Date.now()
+    }
+  }
+
+  private isExpired(record: SessionRecord): boolean {
+    if (record.autoLogoutSeconds === 0) return false
+    if (record.inFlight > 0) return false
+    const elapsed = (Date.now() - record.lastActivityAt) / 1000
+    return elapsed > record.autoLogoutSeconds
+  }
+
+  private async tick(): Promise<void> {
+    // Re-read the setting before judging the window. It is documented as
+    // mirroring the GUI, where `AutoLogoutModal` takes effect immediately, so
+    // a user who shortens it on their phone — or lengthens it because a long
+    // CLI run keeps timing out — has to see that on a session the engine is
+    // already holding.
+    for (const record of [...this.sessions.values()]) {
+      // Skipped when auto-logout is off: `isExpired` returns false before it
+      // looks at the window, so re-reading a synced file 240 times an hour
+      // per session buys nothing. The read is a decrypt plus a parse on
+      // core's *synced* disklet and there is deliberately no cache.
+      if (record.autoLogoutSeconds === 0) continue
+      try {
+        record.autoLogoutSeconds = await reReadAutoLogoutSeconds(record.account)
+      } catch {
+        // Keep the last known value: an unreadable Settings.json is not a
+        // reason to change the window. This arm is reachable only because
+        // `reReadAutoLogoutSeconds` lets the failure out; the lenient reader
+        // swallows it and answers with the default, which would silently
+        // replace the user's choice.
+      }
+    }
+    for (const [id, record] of this.sessions) {
+      if (this.isExpired(record)) {
+        await this.forceLogout(id, 'expired')
+      }
+    }
+  }
+
+  toInfo(record: SessionRecord): SessionInfo {
+    const expiresAt =
+      record.autoLogoutSeconds === 0
+        ? null
+        : new Date(
+            record.lastActivityAt + record.autoLogoutSeconds * 1000
+          ).toISOString()
+    return {
+      sessionId: record.sessionId,
+      username: record.account.username,
+      rootLoginId: record.account.rootLoginId,
+      loginMethod: record.loginMethod,
+      autoLogoutSeconds: record.autoLogoutSeconds,
+      expiresAt,
+      lastActivityAt: new Date(record.lastActivityAt).toISOString(),
+      createdAt: new Date(record.createdAt).toISOString()
+    }
+  }
+}
diff --git a/src/cli/engine/sweepTicker.ts b/src/cli/engine/sweepTicker.ts
new file mode 100644
index 00000000000..3af3bb82772
--- /dev/null
+++ b/src/cli/engine/sweepTicker.ts
@@ -0,0 +1,31 @@
+/**
+ * The periodic sweep both engine stores run.
+ *
+ * `SessionStore` and `ObjectHandleStore` each had their own `ticker` field,
+ * `start`/`stop` pair, the same `15_000` literal and the same error handler.
+ * One factory, so the interval and the failure reporting are decided once.
+ */
+import type { PeriodicTask } from '../../util/PeriodicTask'
+import { makePeriodicTask } from '../../util/PeriodicTask'
+
+/** How often a store looks for work that has aged out. */
+export const SWEEP_INTERVAL_MS = 15_000
+
+/**
+ * A sweep that reports its failures.
+ *
+ * `makePeriodicTask` rather than `setInterval`: it measures the gap after the
+ * task finishes rather than from a fixed tick, and `onError` puts a failure
+ * in the log where a hand-rolled `.catch(() => {})` discarded it.
+ */
+export function makeSweepTicker(
+  label: string,
+  sweep: () => Promise<void>
+): PeriodicTask {
+  return makePeriodicTask(sweep, SWEEP_INTERVAL_MS, {
+    onError: error => {
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(`[edge-engine] ${label} failed: ${message}`)
+    }
+  })
+}
diff --git a/src/cli/engine/tcpPort.ts b/src/cli/engine/tcpPort.ts
new file mode 100644
index 00000000000..98076a044f0
--- /dev/null
+++ b/src/cli/engine/tcpPort.ts
@@ -0,0 +1,41 @@
+/**
+ * The example and default loopback TCP port.
+ *
+ * `--tcp` has no default — the listener is off unless a port is given — so
+ * this is the number the help text, the two usage errors, the client's
+ * fallback and the OpenAPI server entry all cite. It was written out in four
+ * source locations plus the docs, so a change left some of them stale.
+ */
+export const EXAMPLE_TCP_PORT = 9008
+
+/**
+ * A `--tcp` port, validated the same way on both entries.
+ *
+ * The client demanded `1 <= port <= 65535` while the engine accepted any
+ * finite `port >= 0`, so `--tcp=0` — which the docs document as "ephemeral" —
+ * worked on the engine and was refused by the client, and `--tcp=1.5` or
+ * `--tcp=70000` were accepted by the engine and then crashed at `listen`
+ * with `ERR_SOCKET_BAD_PORT`. `0` is allowed, because an ephemeral port is
+ * the documented behaviour; everything Node's `listen` rejects is rejected
+ * here, with the flag named.
+ */
+export function parseTcpPort(raw: string | undefined): number | null {
+  // `undefined` means the flag is absent, which is the listener's off state.
+  // An *empty* value is a typo — `--tcp=` — and used to mean the same thing,
+  // so `--tcp` was a usage error while `--tcp=` silently started no
+  // listener. One spelling cannot mean "off" at one call site and "bad argv"
+  // at another, so the empty string is refused here, once, for both entries.
+  if (raw == null) return null
+  if (raw === '') {
+    throw new RangeError(
+      `Missing value for --tcp: expected a port, e.g. --tcp=${EXAMPLE_TCP_PORT}`
+    )
+  }
+  const port = Number(raw)
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new RangeError(
+      `Invalid --tcp port "${raw}": expected 0-65535, where 0 picks an ephemeral port`
+    )
+  }
+  return port
+}
diff --git a/src/cli/engine/testerServers.ts b/src/cli/engine/testerServers.ts
new file mode 100644
index 00000000000..ace7cda1902
--- /dev/null
+++ b/src/cli/engine/testerServers.ts
@@ -0,0 +1,33 @@
+/**
+ * Edge tester fleet. Automated tests MUST use these — never production.
+ *
+ * Enumerated by DNS probe of *.edge.app (2026-08-05). Only these six resolve.
+ */
+export const TESTER_SERVERS = {
+  loginServer: 'https://login-tester.edge.app',
+  infoServer: 'https://info-tester.edge.app',
+  changeServer: 'https://change-tester.edge.app',
+  syncServer: [
+    'https://sync-tester-us1.edge.app',
+    'https://sync-tester-us2.edge.app',
+    'https://sync-tester-us3.edge.app'
+  ]
+} as const
+
+/** True if every configured URL looks like a -tester host. */
+export function isTesterConfig(servers: {
+  loginServer?: string
+  infoServer?: string
+  changeServer?: string
+  syncServer?: string | string[]
+}): boolean {
+  const hosts: string[] = []
+  if (servers.loginServer != null) hosts.push(servers.loginServer)
+  if (servers.infoServer != null) hosts.push(servers.infoServer)
+  if (servers.changeServer != null) hosts.push(servers.changeServer)
+  const sync = servers.syncServer
+  if (typeof sync === 'string') hosts.push(sync)
+  else if (Array.isArray(sync)) hosts.push(...sync)
+  if (hosts.length === 0) return false
+  return hosts.every(h => h.includes('-tester') || h.includes('tester-'))
+}
diff --git a/src/cli/engine/transportAuth.ts b/src/cli/engine/transportAuth.ts
new file mode 100644
index 00000000000..765bd371b01
--- /dev/null
+++ b/src/cli/engine/transportAuth.ts
@@ -0,0 +1,138 @@
+/**
+ * Authentication for the optional loopback TCP listener.
+ *
+ * The unix socket needs none: it is `0600` inside a `0700` directory, so the
+ * operating system is the check — only this user's processes can connect. A
+ * TCP port has no such thing. Every process on the host can reach
+ * `127.0.0.1` whatever user it runs as, and a web page the user happens to
+ * visit can reach it as well. That matters here more than it would for most
+ * daemons, because `GET /engine/sessions` hands out session ids and a
+ * `sessionId` is full account authority — `get-raw-private-key`, `get-pin`,
+ * `get-login-key` and `spend` all take nothing else.
+ *
+ * Three guards, because the caller to exclude may be local or remote:
+ *
+ *  - A bearer token, minted per engine and written only to the `0600` run
+ *    file, so a caller has to be able to read that file.
+ *  - It is required in `X-Edge-Token`, which is not a CORS-safelisted request
+ *    header. A browser therefore has to preflight, and this engine answers no
+ *    preflight, which is what stops a cross-site request — including the
+ *    no-body `POST /engine/stop` that is otherwise a CORS "simple request".
+ *  - `Host` has to be the address the listener is bound to, and `Origin` has
+ *    to be absent. That is what stops DNS rebinding, where a page the user is
+ *    looking at resolves an attacker's name to `127.0.0.1` and talks to the
+ *    engine as same-origin.
+ */
+import crypto from 'crypto'
+import type { IncomingMessage } from 'http'
+import { base64url } from 'rfc4648'
+
+import { engineError } from './errors'
+
+/** The header a TCP caller presents its token in. */
+export const TCP_TOKEN_HEADER = 'x-edge-token'
+
+/** What the TCP listener will accept. */
+export interface TcpGuard {
+  token: string
+  /**
+   * Lower-cased host *names* this listener answers to.
+   *
+   * Names, not `host:port`: the port a caller names is not what rebinding
+   * abuses, and comparing names only keeps this independent of the port the
+   * listener actually bound, which `--tcp=0` leaves to the OS.
+   */
+  allowedHostnames: Set<string>
+}
+
+/**
+ * A fresh token for one engine's lifetime.
+ *
+ * 32 bytes from the system CSPRNG, base64url so it survives a header, a
+ * shell and a JSON file unescaped. It is never derived from the profile or
+ * the pid: both are guessable, and the whole point is that reading the run
+ * file is the only way to get it.
+ */
+export function makeTcpToken(): string {
+  return base64url.stringify(crypto.randomBytes(32), { pad: false })
+}
+
+/** Every host name a listener on this address legitimately answers to. */
+export function allowedHostnamesFor(host: string): Set<string> {
+  const names = new Set<string>([host.toLowerCase()])
+  // A loopback listener is reached under any of these spellings, and `Host`
+  // carries whichever one the caller typed.
+  if (host === '127.0.0.1' || host === 'localhost' || host === '::1') {
+    names.add('127.0.0.1')
+    names.add('localhost')
+    names.add('::1')
+  }
+  return names
+}
+
+/**
+ * The host name a `Host` header names, or null when it is unparseable.
+ *
+ * Parsed with `URL` rather than split on a colon, so `[::1]:9008` yields
+ * `::1` and a header with a path, userinfo or whitespace in it is refused
+ * rather than partially matched.
+ */
+function hostnameOf(hostHeader: string): string | null {
+  try {
+    const url = new URL(`http://${hostHeader}`)
+    if (url.hostname === '' || url.pathname !== '/' || url.username !== '') {
+      return null
+    }
+    // `URL` keeps the brackets on an IPv6 literal.
+    return url.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  } catch {
+    return null
+  }
+}
+
+/** Constant-time compare, so a wrong token leaks no prefix length. */
+function sameToken(presented: string, expected: string): boolean {
+  const encoder = new TextEncoder()
+  const a = encoder.encode(presented)
+  const b = encoder.encode(expected)
+  if (a.length !== b.length) return false
+  return crypto.timingSafeEqual(a, b)
+}
+
+/**
+ * Refuse a TCP request that is not from a local caller holding the token.
+ *
+ * Throws an `EngineError`, so the request handler's own error path answers it
+ * as the published envelope.
+ */
+export function checkTcpRequest(req: IncomingMessage, guard: TcpGuard): void {
+  // A browser always sends `Origin` on a cross-site request and cannot forge
+  // its absence, so this is the cheapest of the three to check.
+  if (req.headers.origin != null) {
+    throw engineError(
+      'FORBIDDEN',
+      'Cross-origin requests are not accepted on the TCP transport',
+      403
+    )
+  }
+
+  const header = String(req.headers.host ?? '')
+  const hostname = hostnameOf(header)
+  if (hostname == null || !guard.allowedHostnames.has(hostname)) {
+    throw engineError(
+      'FORBIDDEN',
+      `Unexpected Host header "${header}". The TCP transport answers only to the address it is bound to, so a name that merely resolves to this port is refused.`,
+      403
+    )
+  }
+
+  const presented = req.headers[TCP_TOKEN_HEADER]
+  const token = Array.isArray(presented) ? presented[0] : presented
+  if (token == null || !sameToken(token, guard.token)) {
+    throw engineError(
+      'UNAUTHORIZED',
+      'A valid X-Edge-Token header is required on the TCP transport. The token is the `tcpToken` field of the engine run file.',
+      401
+    )
+  }
+}
diff --git a/src/cli/flagTable.ts b/src/cli/flagTable.ts
new file mode 100644
index 00000000000..621ca6bf060
--- /dev/null
+++ b/src/cli/flagTable.ts
@@ -0,0 +1,151 @@
+/**
+ * Every global flag, once.
+ *
+ * The client's `HELP_TEXT`, the engine's `printHelp` and the table in
+ * `docs/EDGE_CLI.md` each described the same flags in their own words, and
+ * they had drifted: `-h, --help` was "Display options", "Show help" and
+ * "Show options"; `-d, --directory` was "Working directory", "Working
+ * directory for core data" and "Working directory for local Edge data"; and
+ * `-k, --api-key` said "Auth server API key" on the client against "Override
+ * API key from `keys.json`" on the engine — where the engine's wording is
+ * the accurate one, because `-k` is forwarded and that is what it does.
+ *
+ * Both help texts are rendered from this list, and `scripts/verifyApiDocs.ts`
+ * checks the guide's table against it in both directions, so the third copy
+ * cannot drift either.
+ *
+ * No imports, so either entry point can use it.
+ */
+
+/** Which half of the CLI accepts a flag. */
+export type FlagAudience = 'client' | 'engine' | 'both'
+
+export interface GlobalFlag {
+  /** As a help line spells it, e.g. `-d, --directory <path>`. */
+  spelling: string
+  /** As `docs/EDGE_CLI.md`'s first column spells it. */
+  docName: string
+  who: FlagAudience
+  /** One line. The guide may add prose after it, not instead of it. */
+  description: string
+}
+
+export const GLOBAL_FLAGS: GlobalFlag[] = [
+  {
+    spelling: '-t, --test',
+    docName: '-t, --test',
+    who: 'both',
+    description: 'Use the six `-tester` servers'
+  },
+  {
+    spelling: '    --fake',
+    docName: '--fake',
+    who: 'both',
+    description: 'Emulate the login, info and sync servers in-process'
+  },
+  {
+    spelling: '-d, --directory <path>',
+    docName: '-d, --directory',
+    who: 'both',
+    description: 'Working directory for local Edge data'
+  },
+  {
+    spelling: '-a, --app-id <id>',
+    docName: '-a, --app-id',
+    who: 'both',
+    description: 'Application ID'
+  },
+  {
+    spelling: '-k, --api-key <key>',
+    docName: '-k, --api-key',
+    who: 'both',
+    description: 'Override API key from `keys.json`'
+  },
+  {
+    spelling: '    --locale <tag>',
+    docName: '--locale <tag>',
+    who: 'both',
+    description: 'Language tag (BCP 47 or POSIX)'
+  },
+  {
+    spelling: '-c, --config <path>',
+    docName: '-c, --config <path>',
+    who: 'both',
+    description: 'Configuration file'
+  },
+  {
+    spelling: '-u, --username <user>',
+    docName: '-u, --username',
+    who: 'client',
+    description: 'Legacy one-shot login helper'
+  },
+  {
+    spelling: '-p, --password <pass>',
+    docName: '-p, --password',
+    who: 'client',
+    description: 'Legacy one-shot login helper'
+  },
+  {
+    spelling: '    --session <id>',
+    docName: '--session <id>',
+    who: 'client',
+    description: 'Override the persisted `sessionId`'
+  },
+  {
+    spelling: '    --no-spawn',
+    docName: '--no-spawn',
+    who: 'client',
+    description: 'Do not auto-start the engine'
+  },
+  {
+    spelling: '    --solve-captcha',
+    docName: '--solve-captcha',
+    who: 'client',
+    description: 'On `CHALLENGE_REQUIRED`, auto-solve ALTCHA PoW and retry'
+  },
+  {
+    spelling: '    --timeout=<seconds>',
+    docName: '--timeout=<seconds>',
+    who: 'client',
+    description: 'Per-request deadline (default `120`)'
+  },
+  {
+    spelling: '    --tcp=<port>',
+    docName: '--tcp=<port>',
+    who: 'both',
+    description: 'Bind TCP on `127.0.0.1`, token-authenticated'
+  },
+  {
+    spelling: '    --tcp-host=<host>',
+    docName: '--tcp-host=<host>',
+    who: 'engine',
+    description: 'TCP bind host, loopback only (default `127.0.0.1`)'
+  },
+  {
+    spelling: '    --idle-timeout=<seconds>',
+    docName: '--idle-timeout=<seconds>',
+    who: 'engine',
+    description: 'Self-shutdown once nothing holds the engine open'
+  },
+  {
+    spelling: '-h, --help',
+    docName: '-h, --help',
+    who: 'both',
+    description: 'Show options'
+  }
+]
+
+/**
+ * Render the flags one half accepts, as aligned help lines.
+ *
+ * The column is computed from the longest spelling rather than hand-spaced,
+ * which is what left the long-only flags starting two columns left of the
+ * short-flag rows in the engine's help.
+ */
+export function renderFlagHelp(who: 'client' | 'engine'): string {
+  const rows = GLOBAL_FLAGS.filter(f => f.who === who || f.who === 'both')
+  const width = Math.max(...rows.map(f => f.spelling.length)) + 2
+  return rows
+    .map(f => `  ${f.spelling.padEnd(width)}${f.description}`)
+    .join('\n')
+}
diff --git a/src/cli/generated/commands.json b/src/cli/generated/commands.json
new file mode 100644
index 00000000000..ca78cbca013
--- /dev/null
+++ b/src/cli/generated/commands.json
@@ -0,0 +1,2123 @@
+{
+  "$comment": "GENERATED FILE — DO NOT EDIT. Produced by scripts/buildCliCommands.ts from the route declarations in src/cli/engine/routes. Commands marked `custom: true` in a declaration are hand-written instead; see src/cli/commands/.",
+  "commands": [
+    {
+      "command": "accelerate",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/accelerate",
+      "usage": "accelerate --wallet-id=<walletId> [--object-id=<objectId>] [--transaction='<json>']",
+      "help": "Fee-bump a pending transaction.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "object-id",
+          "field": "objectId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "transaction",
+          "field": "transaction",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "account-info",
+      "method": "GET",
+      "path": "/account/{sessionId}",
+      "usage": "account-info",
+      "help": "Account and session summary.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "admin-auth-request",
+      "method": "POST",
+      "path": "/admin/auth-request",
+      "usage": "admin-auth-request --method=<method> --path=<path> [--body='<json>']",
+      "help": "Raw login-server request.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "method",
+          "field": "method",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "path",
+          "field": "path",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "body",
+          "field": "body",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "admin-fetch-lobby-request",
+      "method": "GET",
+      "path": "/admin/fetch-lobby-request/{lobbyId}",
+      "usage": "admin-fetch-lobby-request <lobbyId>",
+      "help": "Read a lobby's contents.",
+      "needsSession": false,
+      "pathPositional": "lobbyId",
+      "args": []
+    },
+    {
+      "command": "admin-hash-username",
+      "method": "GET",
+      "path": "/admin/hash-username",
+      "usage": "admin-hash-username --username=<username>",
+      "help": "Hash a username.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "username",
+          "field": "username",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "admin-lobby-handle-delete",
+      "method": "POST",
+      "path": "/admin/lobby-handle/delete/{objectId}",
+      "usage": "admin-lobby-handle-delete <objectId>",
+      "help": "Close a parked lobby.",
+      "needsSession": false,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "admin-make-lobby",
+      "method": "POST",
+      "path": "/admin/make-lobby",
+      "usage": "admin-make-lobby [--lobby-request='<json>'] [--period-seconds=<period>]",
+      "help": "Create a lobby.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "lobby-request",
+          "field": "lobbyRequest",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        },
+        {
+          "flag": "period-seconds",
+          "field": "period",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "admin-repo-delete",
+      "method": "POST",
+      "path": "/admin/repo-delete/{syncKey}",
+      "usage": "admin-repo-delete <syncKey> --path=<path> --data-key=<dataKey>",
+      "help": "Delete a repo file.",
+      "needsSession": false,
+      "pathPositional": "syncKey",
+      "args": [
+        {
+          "flag": "path",
+          "field": "path",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "data-key",
+          "field": "dataKey",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "admin-repo-get",
+      "method": "GET",
+      "path": "/admin/repo-get/{syncKey}",
+      "usage": "admin-repo-get <syncKey> --path=<path> --data-key=<dataKey>",
+      "help": "Read a repo file.",
+      "needsSession": false,
+      "pathPositional": "syncKey",
+      "args": [
+        {
+          "flag": "path",
+          "field": "path",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "data-key",
+          "field": "dataKey",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "admin-repo-list",
+      "method": "GET",
+      "path": "/admin/repo-list/{syncKey}",
+      "usage": "admin-repo-list <syncKey> [--path=<path>] --data-key=<dataKey>",
+      "help": "List repo contents.",
+      "needsSession": false,
+      "pathPositional": "syncKey",
+      "args": [
+        {
+          "flag": "path",
+          "field": "path",
+          "target": "query",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "data-key",
+          "field": "dataKey",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "admin-repo-set",
+      "method": "POST",
+      "path": "/admin/repo-set/{syncKey}",
+      "usage": "admin-repo-set <syncKey> --path=<path> --text=<text> --data-key=<dataKey>",
+      "help": "Write a repo file.",
+      "needsSession": false,
+      "pathPositional": "syncKey",
+      "args": [
+        {
+          "flag": "path",
+          "field": "path",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "text",
+          "field": "text",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "data-key",
+          "field": "dataKey",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "admin-send-lobby-reply",
+      "method": "POST",
+      "path": "/admin/send-lobby-reply/{lobbyId}",
+      "usage": "admin-send-lobby-reply <lobbyId> --lobby-request='<json>' [--reply-data='<json>']",
+      "help": "Reply to a lobby.",
+      "needsSession": false,
+      "pathPositional": "lobbyId",
+      "args": [
+        {
+          "flag": "lobby-request",
+          "field": "lobbyRequest",
+          "target": "body",
+          "kind": "json",
+          "required": true
+        },
+        {
+          "flag": "reply-data",
+          "field": "replyData",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "admin-sync-repo",
+      "method": "POST",
+      "path": "/admin/sync-repo/{syncKey}",
+      "usage": "admin-sync-repo <syncKey>",
+      "help": "Sync a repo.",
+      "needsSession": false,
+      "pathPositional": "syncKey",
+      "args": []
+    },
+    {
+      "command": "all-keys",
+      "method": "GET",
+      "path": "/account/{sessionId}/all-keys",
+      "usage": "all-keys",
+      "help": "List every key in the account.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "approve-login-request",
+      "method": "POST",
+      "path": "/account/{sessionId}/approve-login-request/{lobbyId}",
+      "usage": "approve-login-request <lobbyId>",
+      "help": "Approve a login request.",
+      "needsSession": true,
+      "pathPositional": "lobbyId",
+      "args": []
+    },
+    {
+      "command": "approve-swap-quote",
+      "method": "POST",
+      "path": "/account/{sessionId}/swap-quote/approve/{objectId}",
+      "usage": "approve-swap-quote <objectId>",
+      "help": "Execute a quote.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "approve-voucher",
+      "method": "POST",
+      "path": "/account/{sessionId}/approve-voucher",
+      "usage": "approve-voucher --voucher-id=<voucherId>",
+      "help": "Approve a voucher.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "voucher-id",
+          "field": "voucherId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "broadcast-tx",
+      "method": "POST",
+      "path": "/account/{sessionId}/broadcast-tx/{objectId}",
+      "usage": "broadcast-tx <objectId>",
+      "help": "Broadcast a signed transaction.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "cancel-otp-reset",
+      "method": "POST",
+      "path": "/account/{sessionId}/cancel-otp-reset",
+      "usage": "cancel-otp-reset",
+      "help": "Cancel a pending 2FA reset.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "cancel-request",
+      "method": "POST",
+      "path": "/pending-edge-login/cancel-request/{pendingId}",
+      "usage": "cancel-request <pendingId>",
+      "help": "Cancel a pending QR login.",
+      "needsSession": false,
+      "pathPositional": "pendingId",
+      "args": []
+    },
+    {
+      "command": "change-password",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-password",
+      "usage": "change-password --password=<password>",
+      "help": "Set or change the password.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "password",
+          "field": "password",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "change-paused",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/change-paused",
+      "usage": "change-paused --wallet-id=<walletId> --paused=true|false",
+      "help": "Pause or resume a wallet engine.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "paused",
+          "field": "paused",
+          "target": "body",
+          "kind": "boolstr",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "change-pin",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-pin",
+      "usage": "change-pin --pin=<pin> [--enable-login[=false]] [--for-duress-account[=false]]",
+      "help": "Set or change the PIN.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "pin",
+          "field": "pin",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "enable-login",
+          "field": "enableLogin",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "for-duress-account",
+          "field": "forDuressAccount",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "change-recovery",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-recovery",
+      "usage": "change-recovery --question=<questions> … --answer=<answers> …",
+      "help": "Set recovery questions and answers.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "question",
+          "field": "questions",
+          "target": "body",
+          "kind": "repeat",
+          "required": true
+        },
+        {
+          "flag": "answer",
+          "field": "answers",
+          "target": "body",
+          "kind": "repeat",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "change-username",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-username",
+      "usage": "change-username --username=<username> [--password=<password>]",
+      "help": "Change the username.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "username",
+          "field": "username",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "password",
+          "field": "password",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "check-password",
+      "method": "POST",
+      "path": "/account/{sessionId}/check-password",
+      "usage": "check-password --password=<password>",
+      "help": "Verify a password.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "password",
+          "field": "password",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "check-password-rules",
+      "method": "GET",
+      "path": "/check-password-rules",
+      "usage": "check-password-rules --password=<password>",
+      "help": "Score a candidate password.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "password",
+          "field": "password",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "check-pin",
+      "method": "POST",
+      "path": "/account/{sessionId}/check-pin",
+      "usage": "check-pin --pin=<pin> [--for-duress-account[=false]]",
+      "help": "Verify a PIN.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "pin",
+          "field": "pin",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "for-duress-account",
+          "field": "forDuressAccount",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "close-swap-quote",
+      "method": "POST",
+      "path": "/account/{sessionId}/swap-quote/close/{objectId}",
+      "usage": "close-swap-quote <objectId>",
+      "help": "Discard a quote.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "create-currency-wallet",
+      "method": "POST",
+      "path": "/account/{sessionId}/create-currency-wallet",
+      "usage": "create-currency-wallet --wallet-type=<walletType> [--name=<name>] [--import-text=<importText>]",
+      "help": "Create a currency wallet.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-type",
+          "field": "walletType",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "name",
+          "field": "name",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "import-text",
+          "field": "importText",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "create-currency-wallets",
+      "method": "POST",
+      "path": "/account/{sessionId}/create-currency-wallets",
+      "usage": "create-currency-wallets --create-wallets='<json>'",
+      "help": "Create several wallets at once.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "create-wallets",
+          "field": "createWallets",
+          "target": "body",
+          "kind": "json",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "create-wallet",
+      "method": "POST",
+      "path": "/account/{sessionId}/create-wallet",
+      "usage": "create-wallet --type=<type> [--keys='<json>']",
+      "help": "Create a wallet from raw key JSON.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "type",
+          "field": "type",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "keys",
+          "field": "keys",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "currency-configs",
+      "method": "GET",
+      "path": "/currency-configs",
+      "usage": "currency-configs",
+      "help": "List plugin ids usable for wallet creation.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "currency-wallets",
+      "method": "GET",
+      "path": "/account/{sessionId}/currency-wallets",
+      "usage": "currency-wallets [--filter=active|all|archived|hidden]",
+      "help": "List the account's wallets.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "filter",
+          "field": "filter",
+          "target": "query",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "delete-item",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-item",
+      "usage": "delete-item --store-id=<storeId> --item-id=<itemId>",
+      "help": "Delete an item.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "store-id",
+          "field": "storeId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "item-id",
+          "field": "itemId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "delete-password",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-password",
+      "usage": "delete-password",
+      "help": "Remove password login.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "delete-pin",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-pin",
+      "usage": "delete-pin",
+      "help": "Remove the PIN.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "delete-recovery",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-recovery",
+      "usage": "delete-recovery",
+      "help": "Disable recovery login.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "delete-store",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-store",
+      "usage": "delete-store --store-id=<storeId>",
+      "help": "Delete an entire store.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "store-id",
+          "field": "storeId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "disable-otp",
+      "method": "POST",
+      "path": "/account/{sessionId}/disable-otp",
+      "usage": "disable-otp",
+      "help": "Disable 2FA.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "dump-data",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/dump-data",
+      "usage": "dump-data --wallet-id=<walletId>",
+      "help": "Dump wallet engine state.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "enable-otp",
+      "method": "POST",
+      "path": "/account/{sessionId}/enable-otp",
+      "usage": "enable-otp [--timeout=<timeout>]",
+      "help": "Enable 2FA.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "timeout",
+          "field": "timeout",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "encode-uri",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/encode-uri",
+      "usage": "encode-uri --wallet-id=<walletId> --public-address=<publicAddress> [--native-amount=<nativeAmount>] [--label=<label>] [--message=<message>] [--currency-code=<currencyCode>]",
+      "help": "Build a payment URI.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "public-address",
+          "field": "publicAddress",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "native-amount",
+          "field": "nativeAmount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "label",
+          "field": "label",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "message",
+          "field": "message",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "currency-code",
+          "field": "currencyCode",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "engine-config",
+      "method": "GET",
+      "path": "/engine/config",
+      "usage": "engine-config",
+      "help": "Configured context options.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "engine-sessions",
+      "method": "GET",
+      "path": "/engine/sessions",
+      "usage": "engine-sessions",
+      "help": "List active sessions.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "engine-status",
+      "method": "GET",
+      "path": "/engine/status",
+      "usage": "engine-status",
+      "help": "Engine liveness and summary.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "engine-stop",
+      "method": "POST",
+      "path": "/engine/stop",
+      "usage": "engine-stop",
+      "help": "Stop the engine.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "fetch-challenge",
+      "method": "POST",
+      "path": "/fetch-challenge",
+      "usage": "fetch-challenge",
+      "help": "Pre-fetch a CAPTCHA challenge.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "fetch-lobby",
+      "method": "GET",
+      "path": "/account/{sessionId}/fetch-lobby/{lobbyId}",
+      "usage": "fetch-lobby <lobbyId>",
+      "help": "Inspect a login request.",
+      "needsSession": true,
+      "pathPositional": "lobbyId",
+      "args": []
+    },
+    {
+      "command": "fetch-login-messages",
+      "method": "GET",
+      "path": "/fetch-login-messages",
+      "usage": "fetch-login-messages",
+      "help": "Fetch login-server messages for every local user.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "fetch-recovery-questions",
+      "method": "GET",
+      "path": "/fetch-recovery-questions",
+      "usage": "fetch-recovery-questions --recovery-key=<recoveryKey> --username=<username>",
+      "help": "Fetch a user’s recovery questions.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "recovery-key",
+          "field": "recoveryKey",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "username",
+          "field": "username",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "fetch-swap-quotes",
+      "method": "POST",
+      "path": "/account/{sessionId}/fetch-swap-quotes",
+      "usage": "fetch-swap-quotes --from-wallet-id=<fromWalletId> --to-wallet-id=<toWalletId> --native-amount=<nativeAmount> [--from-token-id=<fromTokenId>] [--to-token-id=<toTokenId>] [--quote-for=from|max|to] [--plugin-id=<preferPluginId>]",
+      "help": "Fetch swap quotes.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "from-wallet-id",
+          "field": "fromWalletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "to-wallet-id",
+          "field": "toWalletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "native-amount",
+          "field": "nativeAmount",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "from-token-id",
+          "field": "fromTokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "to-token-id",
+          "field": "toTokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "quote-for",
+          "field": "quoteFor",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "plugin-id",
+          "field": "preferPluginId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "fix-username",
+      "method": "GET",
+      "path": "/fix-username",
+      "usage": "fix-username --username=<username>",
+      "help": "Normalize a username.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "username",
+          "field": "username",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "forget-account",
+      "method": "POST",
+      "path": "/forget-account",
+      "usage": "forget-account --root-login-id=<rootLoginId>",
+      "help": "Forget an account on this device.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "root-login-id",
+          "field": "rootLoginId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-addresses",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-addresses",
+      "usage": "get-addresses --wallet-id=<walletId> [--token-id=<tokenId>] [--force-index=<forceIndex>]",
+      "help": "Receive addresses.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "query",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "force-index",
+          "field": "forceIndex",
+          "target": "query",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "get-display-private-key",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-display-private-key",
+      "usage": "get-display-private-key --wallet-id=<walletId>",
+      "help": "Export the private key for display.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-display-public-key",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-display-public-key",
+      "usage": "get-display-public-key --wallet-id=<walletId>",
+      "help": "Export the public key for display.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-item",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-item",
+      "usage": "get-item --store-id=<storeId> --item-id=<itemId>",
+      "help": "Read an item.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "store-id",
+          "field": "storeId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "item-id",
+          "field": "itemId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-login-key",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-login-key",
+      "usage": "get-login-key",
+      "help": "Read the account login key.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "get-max-spendable",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/get-max-spendable",
+      "usage": "get-max-spendable --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "help": "Largest sendable amount.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "spend-info",
+          "field": "spendInfo",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        },
+        {
+          "flag": "to",
+          "field": "to",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "native-amount",
+          "field": "nativeAmount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "amount",
+          "field": "amount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "metadata",
+          "field": "metadata",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "get-num-transactions",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-num-transactions",
+      "usage": "get-num-transactions --wallet-id=<walletId> [--token-id=<tokenId>]",
+      "help": "Count transactions in a wallet.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "query",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "get-payment-protocol-info",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-payment-protocol-info",
+      "usage": "get-payment-protocol-info --wallet-id=<walletId> --payment-protocol-url=<paymentProtocolUrl>",
+      "help": "Fetch a BIP70 payment request.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "payment-protocol-url",
+          "field": "paymentProtocolUrl",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-pin",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-pin",
+      "usage": "get-pin",
+      "help": "Read the account PIN.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "get-raw-private-key",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-raw-private-key",
+      "usage": "get-raw-private-key --wallet-id=<walletId>",
+      "help": "Read raw private key material.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-raw-public-key",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-raw-public-key",
+      "usage": "get-raw-public-key --wallet-id=<walletId>",
+      "help": "Read raw public key material.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "get-wallet-info",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-wallet-info",
+      "usage": "get-wallet-info --id=<id>",
+      "help": "Read one wallet's key info.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "id",
+          "field": "id",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "list-item-ids",
+      "method": "GET",
+      "path": "/account/{sessionId}/list-item-ids",
+      "usage": "list-item-ids --store-id=<storeId>",
+      "help": "List item ids in a store.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "store-id",
+          "field": "storeId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "list-splittable-wallet-types",
+      "method": "GET",
+      "path": "/account/{sessionId}/list-splittable-wallet-types",
+      "usage": "list-splittable-wallet-types --wallet-id=<walletId>",
+      "help": "List chains a wallet can split into.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "list-store-ids",
+      "method": "GET",
+      "path": "/account/{sessionId}/list-store-ids",
+      "usage": "list-store-ids",
+      "help": "List data-store ids.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "local-users",
+      "method": "GET",
+      "path": "/local-users",
+      "usage": "local-users",
+      "help": "List local users on this device.",
+      "needsSession": false,
+      "args": []
+    },
+    {
+      "command": "make-spend",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/make-spend",
+      "usage": "make-spend --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "help": "Build an unsigned transaction.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "spend-info",
+          "field": "spendInfo",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        },
+        {
+          "flag": "to",
+          "field": "to",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "native-amount",
+          "field": "nativeAmount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "amount",
+          "field": "amount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "metadata",
+          "field": "metadata",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "object-delete",
+      "method": "POST",
+      "path": "/account/{sessionId}/object/delete/{objectId}",
+      "usage": "object-delete <objectId>",
+      "help": "Release an object handle.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "object-get",
+      "method": "GET",
+      "path": "/account/{sessionId}/object/{objectId}",
+      "usage": "object-get <objectId>",
+      "help": "Inspect an object handle.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "otp-key",
+      "method": "GET",
+      "path": "/account/{sessionId}/otp-key",
+      "usage": "otp-key",
+      "help": "Read the 2FA secret and reset state.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "parse-uri",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/parse-uri",
+      "usage": "parse-uri --wallet-id=<walletId> --uri=<uri> [--currency-code=<currencyCode>]",
+      "help": "Parse a payment URI or address.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "uri",
+          "field": "uri",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "currency-code",
+          "field": "currencyCode",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "pending-vouchers",
+      "method": "GET",
+      "path": "/account/{sessionId}/pending-vouchers",
+      "usage": "pending-vouchers",
+      "help": "List pending 2FA vouchers.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "rates-query",
+      "method": "POST",
+      "path": "/rates/query",
+      "usage": "rates-query [--crypto='<json>'] [--fiat='<json>']",
+      "help": "Batch crypto and fiat rate lookups.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "crypto",
+          "field": "crypto",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        },
+        {
+          "flag": "fiat",
+          "field": "fiat",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "rates-usd-to-native",
+      "method": "POST",
+      "path": "/rates/usd-to-native",
+      "usage": "rates-usd-to-native --usd-amount=<usdAmount> --plugin-id=<pluginId> [--token-id=<tokenId>] --multiplier=<multiplier> [--date=<date>]",
+      "help": "Convert a USD amount into native units.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "usd-amount",
+          "field": "usdAmount",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "plugin-id",
+          "field": "pluginId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "multiplier",
+          "field": "multiplier",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "date",
+          "field": "date",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "reject-voucher",
+      "method": "POST",
+      "path": "/account/{sessionId}/reject-voucher",
+      "usage": "reject-voucher --voucher-id=<voucherId>",
+      "help": "Reject a voucher.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "voucher-id",
+          "field": "voucherId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "rename-wallet",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/rename-wallet",
+      "usage": "rename-wallet --wallet-id=<walletId> --name=<name>",
+      "help": "Rename a wallet.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "name",
+          "field": "name",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "repair-otp",
+      "method": "POST",
+      "path": "/account/{sessionId}/repair-otp",
+      "usage": "repair-otp --otp-key=<otpKey>",
+      "help": "Re-point the account at a known 2FA secret.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "otp-key",
+          "field": "otpKey",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "request-otp-reset",
+      "method": "POST",
+      "path": "/request-otp-reset",
+      "usage": "request-otp-reset --username=<username> --otp-reset-token=<otpResetToken>",
+      "help": "Request a 2FA reset.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "username",
+          "field": "username",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "otp-reset-token",
+          "field": "otpResetToken",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "resync-blockchain",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/resync-blockchain",
+      "usage": "resync-blockchain --wallet-id=<walletId>",
+      "help": "Rescan the blockchain from scratch.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "save-tx",
+      "method": "POST",
+      "path": "/account/{sessionId}/save-tx/{objectId}",
+      "usage": "save-tx <objectId>",
+      "help": "Record a transaction and release its handle.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "save-tx-action",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/save-tx-action",
+      "usage": "save-tx-action --wallet-id=<walletId> --txid=<txid> [--token-id=<tokenId>] --saved-action='<json>' [--asset-action='<json>']",
+      "help": "Save a transaction action.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "txid",
+          "field": "txid",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "saved-action",
+          "field": "savedAction",
+          "target": "body",
+          "kind": "json",
+          "required": true
+        },
+        {
+          "flag": "asset-action",
+          "field": "assetAction",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "save-tx-metadata",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/save-tx-metadata",
+      "usage": "save-tx-metadata --wallet-id=<walletId> --txid=<txid> [--token-id=<tokenId>] --metadata='<json>'",
+      "help": "Save transaction metadata.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "txid",
+          "field": "txid",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "metadata",
+          "field": "metadata",
+          "target": "body",
+          "kind": "json",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "set-fiat-currency-code",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/set-fiat-currency-code",
+      "usage": "set-fiat-currency-code --wallet-id=<walletId> --fiat-currency-code=<fiatCurrencyCode>",
+      "help": "Change a wallet's fiat currency.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "fiat-currency-code",
+          "field": "fiatCurrencyCode",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "set-item",
+      "method": "POST",
+      "path": "/account/{sessionId}/set-item",
+      "usage": "set-item --store-id=<storeId> --item-id=<itemId> --value=<value>",
+      "help": "Write an item.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "store-id",
+          "field": "storeId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "item-id",
+          "field": "itemId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "value",
+          "field": "value",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "sign-bytes",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/sign-bytes",
+      "usage": "sign-bytes --wallet-id=<walletId> [--bytes=<bytes>] [--other-params='<json>']",
+      "help": "Sign arbitrary bytes.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "bytes",
+          "field": "bytes",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "other-params",
+          "field": "otherParams",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "sign-tx",
+      "method": "POST",
+      "path": "/account/{sessionId}/sign-tx/{objectId}",
+      "usage": "sign-tx <objectId>",
+      "help": "Sign a staged transaction.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "spend",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/spend",
+      "usage": "spend [--use-max[=false]] [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "help": "Send funds.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "use-max",
+          "field": "useMax",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "dry-run",
+          "field": "dryRun",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "broadcast",
+          "field": "broadcast",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "save",
+          "field": "save",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "spend-info",
+          "field": "spendInfo",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        },
+        {
+          "flag": "to",
+          "field": "to",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "native-amount",
+          "field": "nativeAmount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "amount",
+          "field": "amount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "metadata",
+          "field": "metadata",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "spend-max",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/spend",
+      "usage": "spend-max [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "help": "Send a wallet’s entire spendable balance.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "use-max",
+          "field": "useMax",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "dry-run",
+          "field": "dryRun",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "broadcast",
+          "field": "broadcast",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "save",
+          "field": "save",
+          "target": "body",
+          "kind": "boolean",
+          "required": false
+        },
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "spend-info",
+          "field": "spendInfo",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        },
+        {
+          "flag": "to",
+          "field": "to",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "native-amount",
+          "field": "nativeAmount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "amount",
+          "field": "amount",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "token-id",
+          "field": "tokenId",
+          "target": "body",
+          "kind": "string",
+          "required": false
+        },
+        {
+          "flag": "metadata",
+          "field": "metadata",
+          "target": "body",
+          "kind": "json",
+          "required": false
+        }
+      ],
+      "preset": {
+        "useMax": true
+      }
+    },
+    {
+      "command": "split",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/split",
+      "usage": "split --wallet-id=<walletId> --split-wallets='<json>'",
+      "help": "Split a wallet into another chain.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "split-wallets",
+          "field": "splitWallets",
+          "target": "body",
+          "kind": "json",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "swap-quote-get",
+      "method": "GET",
+      "path": "/account/{sessionId}/swap-quote/{objectId}",
+      "usage": "swap-quote-get <objectId>",
+      "help": "Re-read a quote.",
+      "needsSession": true,
+      "pathPositional": "objectId",
+      "args": []
+    },
+    {
+      "command": "sweep-private-keys",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/sweep-private-keys",
+      "usage": "sweep-private-keys --wallet-id=<walletId> --spend-info='<json>'",
+      "help": "Sweep private keys into this wallet.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "spend-info",
+          "field": "spendInfo",
+          "target": "body",
+          "kind": "json",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "sync",
+      "method": "POST",
+      "path": "/account/{sessionId}/sync",
+      "usage": "sync",
+      "help": "Force an account data sync.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "touch",
+      "method": "POST",
+      "path": "/account/{sessionId}/touch",
+      "usage": "touch",
+      "help": "Keepalive.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "username-available",
+      "method": "GET",
+      "path": "/username-available",
+      "usage": "username-available --username=<username> [--challenge-id=<challengeId>]",
+      "help": "Check whether a username is free.",
+      "needsSession": false,
+      "args": [
+        {
+          "flag": "username",
+          "field": "username",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        },
+        {
+          "flag": "challenge-id",
+          "field": "challengeId",
+          "target": "query",
+          "kind": "string",
+          "required": false
+        }
+      ]
+    },
+    {
+      "command": "wait-for-all-wallets",
+      "method": "POST",
+      "path": "/account/{sessionId}/wait-for-all-wallets",
+      "usage": "wait-for-all-wallets",
+      "help": "Wait for every wallet to finish loading.",
+      "needsSession": true,
+      "args": []
+    },
+    {
+      "command": "wallet-info",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet",
+      "usage": "wallet-info --wallet-id=<walletId>",
+      "help": "Wallet detail.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "wallet-sync",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/sync",
+      "usage": "wallet-sync --wallet-id=<walletId>",
+      "help": "Nudge one wallet to sync.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "body",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    },
+    {
+      "command": "wallet-tokens",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/tokens",
+      "usage": "wallet-tokens --wallet-id=<walletId>",
+      "help": "List a wallet's tokens.",
+      "needsSession": true,
+      "args": [
+        {
+          "flag": "wallet-id",
+          "field": "walletId",
+          "target": "query",
+          "kind": "string",
+          "required": true
+        }
+      ]
+    }
+  ]
+}
diff --git a/src/cli/generated/helpDocs.json b/src/cli/generated/helpDocs.json
new file mode 100644
index 00000000000..d4cb3922434
--- /dev/null
+++ b/src/cli/generated/helpDocs.json
@@ -0,0 +1,3427 @@
+{
+  "$comment": "GENERATED FILE — DO NOT EDIT. Produced by scripts/buildCliHelp.ts from the route declarations in src/cli/engine/routes. Edit the declaration, then run `npm run prepare` (or `npm run docs:api`).",
+  "commands": {
+    "accelerate": {
+      "summary": "Fee-bump a pending transaction.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/accelerate",
+      "usage": "accelerate --wallet-id=<walletId> [--object-id=<objectId>] [--transaction='<json>']",
+      "description": "Replace-by-fee, where the plugin supports it. Returns a new unsigned transaction to sign and broadcast.",
+      "core": "wallet.accelerate",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "objectId": {
+          "pass": "[--object-id=<objectId>]",
+          "doc": "Handle of the transaction to bump.",
+          "optional": true
+        },
+        "transaction": {
+          "pass": "[--transaction='<json>']",
+          "doc": "Or the transaction itself.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "sessionId?": "string — Session that created the handle; only that session may use it.",
+        "walletId?": "string — Wallet the handle is bound to, when it belongs to one.",
+        "transaction": "unknown — `EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+      },
+      "returnsDoc": "Given objectId the same handle is updated; given a transaction a new one is created.",
+      "notes": [
+        "A plugin that cannot accelerate returns 400 rather than a null transaction."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_WALLET_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "account-info": {
+      "summary": "Account and session summary.",
+      "method": "GET",
+      "path": "/account/{sessionId}",
+      "usage": "account-info",
+      "description": "Session fields are spread at the top level alongside the account's own properties — there is no nested `session` object.",
+      "returns": {
+        "appId": "string — Application this session logged into.",
+        "created": "string | null — When the account was created, null for accounts predating the field.",
+        "lastLogin": "string — The previous login, not this one.",
+        "loggedIn": "boolean — False once the account has been logged out; the session object outlives it briefly.",
+        "recoveryKey": "string | null — Present only while recovery is configured.",
+        "otpEnabled": "boolean — 2FA is on for this account.",
+        "otpResetPending": "boolean — True while somebody has a reset pending against this account.",
+        "canDuressLogin": "boolean — A duress PIN is configured, so this account can be opened in duress mode.",
+        "isDuressAccount": "boolean — True when this very session is the duress account rather than the real one.",
+        "edgeLogin": "boolean — This account was reached by QR login.",
+        "keyLogin": "boolean — This session was reached with a login key.",
+        "newAccount": "boolean — This session created the account rather than logging into an existing one.",
+        "passwordLogin": "boolean — This session was reached with a password.",
+        "pinLogin": "boolean — This session was reached with a PIN.",
+        "recoveryLogin": "boolean — This session was reached by answering recovery questions."
+      },
+      "notes": [
+        "The `otpEnabled` and `otpResetPending` flags here are derived. For the secret itself use `otp-key`."
+      ],
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "admin-auth-request": {
+      "summary": "Raw login-server request.",
+      "method": "POST",
+      "path": "/admin/auth-request",
+      "usage": "admin-auth-request --method=<method> --path=<path> [--body='<json>']",
+      "description": "Sends an arbitrary request with the context's credentials attached. Debugging only — this is core's private surface.",
+      "core": "context.$internalStuff.authRequest",
+      "params": {
+        "method": {
+          "pass": "--method=<method>",
+          "doc": "HTTP method, e.g. `GET`.",
+          "optional": false
+        },
+        "path": {
+          "pass": "--path=<path>",
+          "doc": "Login-server path, not an engine path.",
+          "optional": false
+        },
+        "body": {
+          "pass": "[--body='<json>']",
+          "doc": "Request body, when the method takes one.",
+          "optional": true
+        }
+      },
+      "returnsDoc": "Whatever the login server returned.",
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "admin-fetch-lobby-request": {
+      "summary": "Read a lobby's contents.",
+      "method": "GET",
+      "path": "/admin/fetch-lobby-request/{lobbyId}",
+      "usage": "admin-fetch-lobby-request <lobbyId>",
+      "core": "context.$internalStuff.fetchLobbyRequest",
+      "params": {
+        "lobbyId": {
+          "pass": "<lobbyId>",
+          "doc": "Which lobby to read.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "The raw lobby request.",
+      "errors": [
+        "NETWORK_ERROR"
+      ]
+    },
+    "admin-hash-username": {
+      "summary": "Hash a username.",
+      "method": "GET",
+      "path": "/admin/hash-username",
+      "usage": "admin-hash-username --username=<username>",
+      "description": "Reproduces the login server's hashing, to derive a login id offline.",
+      "core": "context.$internalStuff.hashUsername",
+      "params": {
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "The name to hash.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "loginId": "string — Base58."
+      }
+    },
+    "admin-lobby-handle-delete": {
+      "summary": "Close a parked lobby.",
+      "method": "POST",
+      "path": "/admin/lobby-handle/delete/{objectId}",
+      "usage": "admin-lobby-handle-delete <objectId>",
+      "returns": {
+        "ok": "boolean — Always true; a failure arrives as an error envelope."
+      },
+      "notes": [
+        "Not under `/account/{sessionId}/objects/`, because admin lobbies belong to no session."
+      ],
+      "errors": [
+        "OBJECT_NOT_FOUND",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_IN_USE"
+      ]
+    },
+    "admin-make-lobby": {
+      "summary": "Create a lobby.",
+      "method": "POST",
+      "path": "/admin/make-lobby",
+      "usage": "admin-make-lobby [--lobby-request='<json>'] [--period-seconds=<period>]",
+      "description": "A lobby polls the login server until closed, so the engine parks it under a `lobby_` handle and closes it on expiry rather than leaking the poll.",
+      "core": "context.$internalStuff.makeLobby",
+      "params": {
+        "lobbyRequest": {
+          "pass": "[--lobby-request='<json>']",
+          "doc": "Defaults to `{}`.",
+          "optional": true
+        },
+        "period": {
+          "pass": "[--period-seconds=<period>]",
+          "doc": "Poll interval in seconds. At least 0.25; the engine converts to the milliseconds core takes.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "objectId": "string — The parked handle.",
+        "expiresAt": "string — When the engine closes the lobby and stops polling.",
+        "lobbyId": "string — Identifies the lobby to the party joining it.",
+        "replies": "unknown[] — Empty at creation; re-read to see replies."
+      },
+      "notes": [
+        "Release it with `admin-lobby-handle-delete`, or the poll runs for the full five minutes."
+      ],
+      "errors": [
+        "NETWORK_ERROR"
+      ]
+    },
+    "admin-repo-delete": {
+      "summary": "Delete a repo file.",
+      "method": "POST",
+      "path": "/admin/repo-delete/{syncKey}",
+      "usage": "admin-repo-delete <syncKey> --path=<path> --data-key=<dataKey>",
+      "description": "Destructive, and not undoable from this API.",
+      "core": "context.$internalStuff.getRepoDisklet",
+      "params": {
+        "path": {
+          "pass": "--path=<path>",
+          "doc": "Path within the repo.",
+          "optional": false
+        },
+        "syncKey": {
+          "pass": "<syncKey>",
+          "doc": "Base58 repo sync key.",
+          "optional": false
+        },
+        "dataKey": {
+          "pass": "--data-key=<dataKey>",
+          "doc": "Base58 repo data key.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST"
+      ]
+    },
+    "admin-repo-get": {
+      "summary": "Read a repo file.",
+      "method": "GET",
+      "path": "/admin/repo-get/{syncKey}",
+      "usage": "admin-repo-get <syncKey> --path=<path> --data-key=<dataKey>",
+      "core": "context.$internalStuff.getRepoDisklet",
+      "params": {
+        "path": {
+          "pass": "--path=<path>",
+          "doc": "Path within the repo.",
+          "optional": false
+        },
+        "syncKey": {
+          "pass": "<syncKey>",
+          "doc": "Base58 repo sync key.",
+          "optional": false
+        },
+        "dataKey": {
+          "pass": "--data-key=<dataKey>",
+          "doc": "Base58 repo data key.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "text": "string — The file contents."
+      },
+      "errors": [
+        "NOT_FOUND",
+        "BAD_REQUEST"
+      ]
+    },
+    "admin-repo-list": {
+      "summary": "List repo contents.",
+      "method": "GET",
+      "path": "/admin/repo-list/{syncKey}",
+      "usage": "admin-repo-list <syncKey> [--path=<path>] --data-key=<dataKey>",
+      "core": "context.$internalStuff.getRepoDisklet",
+      "params": {
+        "path": {
+          "pass": "[--path=<path>]",
+          "doc": "Subdirectory. Defaults to the repo root.",
+          "optional": true
+        },
+        "syncKey": {
+          "pass": "<syncKey>",
+          "doc": "Base58 repo sync key.",
+          "optional": false
+        },
+        "dataKey": {
+          "pass": "--data-key=<dataKey>",
+          "doc": "Base58 repo data key.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "listing": "unknown — Path to entry type: `file` or `folder`."
+      },
+      "errors": [
+        "BAD_REQUEST"
+      ]
+    },
+    "admin-repo-set": {
+      "summary": "Write a repo file.",
+      "method": "POST",
+      "path": "/admin/repo-set/{syncKey}",
+      "usage": "admin-repo-set <syncKey> --path=<path> --text=<text> --data-key=<dataKey>",
+      "description": "Writes directly into a synced repo, bypassing every core-level invariant. A malformed write can break the account for real clients.",
+      "core": "context.$internalStuff.getRepoDisklet",
+      "params": {
+        "path": {
+          "pass": "--path=<path>",
+          "doc": "Path within the repo.",
+          "optional": false
+        },
+        "text": {
+          "pass": "--text=<text>",
+          "doc": "The contents to write.",
+          "optional": false
+        },
+        "syncKey": {
+          "pass": "<syncKey>",
+          "doc": "Base58 repo sync key.",
+          "optional": false
+        },
+        "dataKey": {
+          "pass": "--data-key=<dataKey>",
+          "doc": "Base58 repo data key.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST"
+      ]
+    },
+    "admin-send-lobby-reply": {
+      "summary": "Reply to a lobby.",
+      "method": "POST",
+      "path": "/admin/send-lobby-reply/{lobbyId}",
+      "usage": "admin-send-lobby-reply <lobbyId> --lobby-request='<json>' [--reply-data='<json>']",
+      "core": "context.$internalStuff.sendLobbyReply",
+      "params": {
+        "lobbyId": {
+          "pass": "<lobbyId>",
+          "doc": "Which lobby to answer.",
+          "optional": false
+        },
+        "lobbyRequest": {
+          "pass": "--lobby-request='<json>'",
+          "doc": "Normally the object from `admin-fetch-lobby-request`.",
+          "optional": false
+        },
+        "replyData": {
+          "pass": "[--reply-data='<json>']",
+          "doc": "Payload for the requester.",
+          "optional": true
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "admin-sync-repo": {
+      "summary": "Sync a repo.",
+      "method": "POST",
+      "path": "/admin/sync-repo/{syncKey}",
+      "usage": "admin-sync-repo <syncKey>",
+      "core": "context.$internalStuff.syncRepo",
+      "params": {
+        "syncKey": {
+          "pass": "<syncKey>",
+          "doc": "Base58 repo sync key.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "The changeset summary.",
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "all-keys": {
+      "summary": "List every key in the account.",
+      "method": "GET",
+      "path": "/account/{sessionId}/all-keys",
+      "usage": "all-keys",
+      "description": "Includes archived and deleted keys, unlike `currency-wallets`.",
+      "core": "account.allKeys",
+      "returns": {
+        "allKeys": "unknown[] — `EdgeWalletInfoFull[]`: id, type, keys, archived, deleted, hidden, sortIndex."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "approve-login-request": {
+      "summary": "Approve a login request.",
+      "method": "POST",
+      "path": "/account/{sessionId}/approve-login-request/{lobbyId}",
+      "usage": "approve-login-request <lobbyId>",
+      "description": "Grants the requesting device access to this account.",
+      "core": "EdgeLoginRequest.approve",
+      "params": {
+        "lobbyId": {
+          "pass": "<lobbyId>",
+          "doc": "From the QR code, or an `edge://edge/<lobbyId>` link.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "ok": "boolean — Always true; a failure arrives as an error envelope."
+      },
+      "notes": [
+        "The lobby is re-fetched on approve, so a request that expired between inspecting and approving fails with `404 NO_LOGIN_REQUEST`."
+      ],
+      "errors": [
+        "NO_LOGIN_REQUEST",
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "approve-swap-quote": {
+      "summary": "Execute a quote.",
+      "method": "POST",
+      "path": "/account/{sessionId}/swap-quote/approve/{objectId}",
+      "usage": "approve-swap-quote <objectId>",
+      "description": "Moves funds. The handle is released afterwards whether or not the response is read, so record `orderId` from it.",
+      "core": "EdgeSwapQuote.approve",
+      "returns": {
+        "ok": "unknown — True once the swap is submitted and the send broadcast.",
+        "objectId": "string — The handle that was consumed.",
+        "orderId": "unknown — The exchange’s order reference, when it gives one.",
+        "destinationAddress": "unknown — Address the funds were sent to, when the exchange reports one.",
+        "transaction": "unknown — The on-chain send to the exchange."
+      },
+      "notes": [
+        "A failure releases the handle too, and a retry answers `OBJECT_NOT_FOUND`. `approve()` signs, broadcasts and then does its own bookkeeping, and from outside the plugin an error after the money moved cannot be told from one before it — so a retry has to start from a fresh quote rather than risk a second broadcast.",
+        "The plugin attaches its own savedAction and assetAction metadata; the engine adds none."
+      ],
+      "errors": [
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "OBJECT_IN_USE",
+        "INSUFFICIENT_FUNDS",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "approve-voucher": {
+      "summary": "Approve a voucher.",
+      "method": "POST",
+      "path": "/account/{sessionId}/approve-voucher",
+      "usage": "approve-voucher --voucher-id=<voucherId>",
+      "description": "Lets the waiting device finish logging in.",
+      "core": "account.approveVoucher",
+      "params": {
+        "voucherId": {
+          "pass": "--voucher-id=<voucherId>",
+          "doc": "From `pending-vouchers`, or an `OTP_REQUIRED` error’s `details.voucherId`.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "balance-map": {
+      "summary": "Balances for every asset in the wallet.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/balance-map",
+      "usage": "balance-map --wallet-id=<walletId> [--token-id=<value>]",
+      "description": "The native currency plus every enabled token.",
+      "core": "wallet.balanceMap",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "token-id": {
+          "pass": "--token-id=<value>",
+          "doc": "Client-side filter; core has no single-balance accessor.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "balances": "{ tokenId: string | null; currencyCode: string; nativeAmount: string; displayAmount: string | null; unknownToken: boolean; }[] — One entry per asset the wallet holds, native coin first: `tokenId`, `currencyCode`, `nativeAmount`, `displayAmount` and `unknownToken`. A token the plugin reports a balance for but whose config it no longer carries is listed with `unknownToken: true` and a null `displayAmount`, rather than failing the whole wallet."
+      },
+      "notes": [
+        "On the CLI, omit `--token-id` for the native asset rather than passing the literal `null`."
+      ],
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "broadcast-tx": {
+      "summary": "Broadcast a signed transaction.",
+      "method": "POST",
+      "path": "/account/{sessionId}/broadcast-tx/{objectId}",
+      "usage": "broadcast-tx <objectId>",
+      "description": "The irreversible step: once this returns, the funds have left the wallet.",
+      "core": "wallet.broadcastTx",
+      "params": {
+        "objectId": {
+          "pass": "<objectId>",
+          "doc": "From `sign-tx`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "sessionId?": "string — Session that created the handle; only that session may use it.",
+        "walletId?": "string — Wallet the handle is bound to, when it belongs to one.",
+        "transaction": "unknown — `EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+      },
+      "returnsDoc": "The handle survives, so `save-tx` can still run.",
+      "notes": [
+        "Broadcasting does not record the transaction locally. Follow with `save-tx`, or it stays missing from history until a sync finds it."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_WALLET_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "cancel-otp-reset": {
+      "summary": "Cancel a pending 2FA reset.",
+      "method": "POST",
+      "path": "/account/{sessionId}/cancel-otp-reset",
+      "usage": "cancel-otp-reset",
+      "description": "The defence against somebody else requesting a reset on your account: as long as you cancel before the timer runs out, their reset never lands.",
+      "core": "account.cancelOtpReset",
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "cancel-request": {
+      "summary": "Cancel a pending QR login.",
+      "method": "POST",
+      "path": "/pending-edge-login/cancel-request/{pendingId}",
+      "usage": "cancel-request <pendingId>",
+      "core": "EdgePendingEdgeLogin.cancelRequest",
+      "notes": [
+        "If the login already completed and a session exists, that session is force-logged-out too, so cancelling cannot leave an orphan visible in `engine-sessions`."
+      ],
+      "errors": [
+        "PENDING_LOGIN_NOT_FOUND"
+      ]
+    },
+    "change-enabled-token-ids": {
+      "summary": "Set the enabled token set.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/change-enabled-token-ids",
+      "usage": "change-enabled-token-ids --wallet-id=<walletId> --token-ids='<json>' [--add=<value>] [--remove=<value>]",
+      "description": "Absolute: anything missing from `tokenIds` is disabled. Core has only this setter, so there is no add or remove call.",
+      "core": "wallet.changeEnabledTokenIds",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "tokenIds": {
+          "pass": "--token-ids='<json>'",
+          "doc": "The complete desired set.",
+          "optional": false
+        },
+        "add": {
+          "pass": "--add=<value>",
+          "doc": "Read the current set, add this id, write it back.",
+          "optional": true
+        },
+        "remove": {
+          "pass": "--remove=<value>",
+          "doc": "Read the current set, drop this id, write it back.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "enabledTokenIds": "string[] — The wallet’s enabled tokens after the change, not just what changed."
+      },
+      "notes": [
+        "The command's `--add` and `--remove` are client-side sugar over this one route, and cost an extra read first."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "change-password": {
+      "summary": "Set or change the password.",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-password",
+      "usage": "change-password --password=<password>",
+      "description": "The login server enforces its own rules; `check-password-rules` scores a candidate first.",
+      "core": "account.changePassword",
+      "params": {
+        "password": {
+          "pass": "--password=<password>",
+          "doc": "The new password.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "change-paused": {
+      "summary": "Pause or resume a wallet engine.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/change-paused",
+      "usage": "change-paused --wallet-id=<walletId> --paused=true|false",
+      "description": "A paused wallet stops syncing, which is how a caller quiets a chain it does not currently care about.",
+      "core": "wallet.changePaused",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "paused": {
+          "pass": "--paused=true|false",
+          "doc": "True to stop syncing.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "change-pin": {
+      "summary": "Set or change the PIN.",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-pin",
+      "usage": "change-pin --pin=<pin> [--enable-login[=false]] [--for-duress-account[=false]]",
+      "core": "account.changePin",
+      "params": {
+        "pin": {
+          "pass": "--pin=<pin>",
+          "doc": "The new PIN.",
+          "optional": false
+        },
+        "enableLogin": {
+          "pass": "[--enable-login[=false]]",
+          "doc": "Allow logging in with this PIN on this device.",
+          "optional": true
+        },
+        "forDuressAccount": {
+          "pass": "[--for-duress-account[=false]]",
+          "doc": "Act on the duress account rather than the real one.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "pin2Key": "string — The new PIN login key core returns."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "change-recovery": {
+      "summary": "Set recovery questions and answers.",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-recovery",
+      "usage": "change-recovery --question=<questions> … --answer=<answers> …",
+      "description": "The returned key is half of the credential: without it the answers alone cannot recover the account, so it has to be stored somewhere else.",
+      "core": "account.changeRecovery",
+      "params": {
+        "questions": {
+          "pass": "--question=<questions> …",
+          "doc": "The questions to ask.",
+          "optional": false
+        },
+        "answers": {
+          "pass": "--answer=<answers> …",
+          "doc": "Same length and order as `questions`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "recoveryKey": "string — Store this out of band. `login-with-recovery` needs it alongside the answers."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "change-username": {
+      "summary": "Change the username.",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-username",
+      "usage": "change-username --username=<username> [--password=<password>]",
+      "description": "The old name is released, so it becomes available to anyone else.",
+      "core": "account.changeUsername",
+      "params": {
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "The new username.",
+          "optional": false
+        },
+        "password": {
+          "pass": "[--password=<password>]",
+          "doc": "Required by core when the account has a password.",
+          "optional": true
+        }
+      },
+      "errors": [
+        "USERNAME_ERROR",
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "change-wallet-states": {
+      "summary": "Archive, delete, hide, or reorder wallets.",
+      "method": "POST",
+      "path": "/account/{sessionId}/change-wallet-states",
+      "usage": "change-wallet-states [--wallet-states='<json>'] --wallet-id=<value> [--archived=<value>] [--deleted=<value>] [--hidden=<value>] [--sort-index=<value>]",
+      "description": "The canonical backend for every wallet flag; there are no separate archive, unarchive or undelete verbs.",
+      "core": "account.changeWalletStates",
+      "params": {
+        "walletStates": {
+          "pass": "[--wallet-states='<json>']",
+          "doc": "`EdgeWalletStates`: wallet ids to the flags being changed.",
+          "optional": true
+        },
+        "wallet-id": {
+          "pass": "--wallet-id=<value>",
+          "doc": "The wallet to change. The command makes it the key of a single-entry `walletStates` map.",
+          "optional": false
+        },
+        "archived": {
+          "pass": "--archived=<value>",
+          "doc": "Hide from the active list.",
+          "optional": true
+        },
+        "deleted": {
+          "pass": "--deleted=<value>",
+          "doc": "Mark deleted.",
+          "optional": true
+        },
+        "hidden": {
+          "pass": "--hidden=<value>",
+          "doc": "Hide from the wallet picker.",
+          "optional": true
+        },
+        "sort-index": {
+          "pass": "--sort-index=<value>",
+          "doc": "Position in the wallet list.",
+          "optional": true
+        }
+      },
+      "notes": [
+        "The command builds a single-wallet `walletStates` map from these flags, and needs at least one."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "check-password": {
+      "summary": "Verify a password.",
+      "method": "POST",
+      "path": "/account/{sessionId}/check-password",
+      "usage": "check-password --password=<password>",
+      "description": "Checks without changing anything, which is how a caller gates a destructive action behind a re-entry prompt.",
+      "core": "account.checkPassword",
+      "params": {
+        "password": {
+          "pass": "--password=<password>",
+          "doc": "The account password.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "ok": "boolean — False for a wrong password — not an error response."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "check-password-rules": {
+      "summary": "Score a candidate password.",
+      "method": "GET",
+      "path": "/check-password-rules",
+      "usage": "check-password-rules --password=<password>",
+      "core": "context.checkPasswordRules",
+      "params": {
+        "password": {
+          "pass": "--password=<password>",
+          "doc": "The candidate password to score.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "`EdgePasswordRules` from core: passed, tooShort, noNumber, noLowerCase, noUpperCase, secondsToCrack.",
+      "notes": [
+        "Send it with `curl --get --data-urlencode` rather than putting it in a shell-visible URL."
+      ]
+    },
+    "check-pin": {
+      "summary": "Verify a PIN.",
+      "method": "POST",
+      "path": "/account/{sessionId}/check-pin",
+      "usage": "check-pin --pin=<pin> [--for-duress-account[=false]]",
+      "core": "account.checkPin",
+      "params": {
+        "pin": {
+          "pass": "--pin=<pin>",
+          "doc": "The device PIN, usually four digits.",
+          "optional": false
+        },
+        "forDuressAccount": {
+          "pass": "[--for-duress-account[=false]]",
+          "doc": "Act on the duress account rather than the real one.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "ok": "boolean — False for a wrong PIN — not an error response."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "close-swap-quote": {
+      "summary": "Discard a quote.",
+      "method": "POST",
+      "path": "/account/{sessionId}/swap-quote/close/{objectId}",
+      "usage": "close-swap-quote <objectId>",
+      "description": "Closes the plugin object without executing, freeing whatever the exchange was holding.",
+      "core": "EdgeSwapQuote.close",
+      "returns": {
+        "ok": "boolean — Always true; a failure arrives as an error envelope.",
+        "objectId": "string — The handle this call consumed. It is now expired."
+      },
+      "errors": [
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "create-account": {
+      "summary": "Create an account.",
+      "method": "POST",
+      "path": "/create-account",
+      "usage": "create-account [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] [--username=<username>] [--password=<password>] [--pin=<pin>]",
+      "description": "Every credential is optional over REST: omitting all three creates a light account with no username.",
+      "core": "context.createAccount",
+      "params": {
+        "otp": {
+          "pass": "[--otp=<otp>]",
+          "doc": "A current 2FA code.",
+          "optional": true
+        },
+        "otpKey": {
+          "pass": "[--otp-key=<otpKey>]",
+          "doc": "The 2FA secret itself, instead of a code.",
+          "optional": true
+        },
+        "challengeId": {
+          "pass": "[--challenge-id=<challengeId>]",
+          "doc": "Supply after solving a CAPTCHA to retry the same request.",
+          "optional": true
+        },
+        "username": {
+          "pass": "[--username=<username>]",
+          "doc": "The name to claim.",
+          "optional": true
+        },
+        "password": {
+          "pass": "[--password=<password>]",
+          "doc": "The account password.",
+          "optional": true
+        },
+        "pin": {
+          "pass": "[--pin=<pin>]",
+          "doc": "A device PIN to save.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "sessionId": "string — Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.",
+        "username?": "string — Absent for a light account, which has no username.",
+        "rootLoginId": "string — The account root, stable across appIds. Two sessions sharing it are the same account.",
+        "loginMethod": "\"create\" | \"edge\" | \"key\" | \"password\" | \"pin\" | \"recovery\" — How this session was established.",
+        "autoLogoutSeconds": "number — Idle time before the engine logs the account out. 0 disables it.",
+        "expiresAt": "string | null — When auto-logout will fire, or null when it is disabled.",
+        "lastActivityAt": "string — Last call on this session, which is what auto-logout measures from.",
+        "createdAt": "string — When the login completed."
+      },
+      "returnsDoc": "A session with `loginMethod: \"create\"`.",
+      "notes": [
+        "The command requires a username, password and PIN. Creating a light account is REST-only."
+      ],
+      "errors": [
+        "USERNAME_ERROR",
+        "CHALLENGE_REQUIRED",
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "create-currency-wallet": {
+      "summary": "Create a currency wallet.",
+      "method": "POST",
+      "path": "/account/{sessionId}/create-currency-wallet",
+      "usage": "create-currency-wallet --wallet-type=<walletType> [--name=<name>] [--import-text=<importText>]",
+      "core": "account.createCurrencyWallet",
+      "params": {
+        "walletType": {
+          "pass": "--wallet-type=<walletType>",
+          "doc": "From `currency-configs`, e.g. `wallet:bitcoin`.",
+          "optional": false
+        },
+        "name": {
+          "pass": "[--name=<name>]",
+          "doc": "Display name.",
+          "optional": true
+        },
+        "importText": {
+          "pass": "[--import-text=<importText>]",
+          "doc": "Seed or key text to import instead of generating.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "walletId": "string — The full wallet id. Commands taking a wallet accept any unique prefix.",
+        "id": "string — Same value as `walletId`; core exposes both names.",
+        "type": "string — Key type, such as `wallet:bitcoin`.",
+        "name": "string | null — User-assigned name, null until one is set.",
+        "pluginId": "string — Currency plugin backing this wallet.",
+        "currencyCode": "string — Ticker for the native asset.",
+        "fiatCurrencyCode": "string — Fiat the wallet reports value in, as `iso:USD`.",
+        "blockHeight": "number — Chain height this wallet has seen.",
+        "syncStatus": "unknown — `EdgeWalletSyncStatus` from core.",
+        "syncRatio?": "string — Sync progress as a percentage, for display.",
+        "paused": "boolean — True while the engine is not syncing this wallet.",
+        "imported?": "boolean — True when the keys came from an import rather than being generated here.",
+        "created": "string | null — When the wallet was created, null for wallets predating the field.",
+        "enabledTokenIds": "string[] — Tokens the user turned on.",
+        "detectedTokenIds": "string[] — Tokens found on-chain that are not enabled yet.",
+        "unactivatedTokenIds": "string[] — Enabled tokens still awaiting on-chain activation."
+      },
+      "notes": [
+        "The fiat currency is not set here. Core still accepts it on create, but that path is deprecated — use `set-fiat-currency-code` afterwards, so there is one way to do it."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "create-currency-wallets": {
+      "summary": "Create several wallets at once.",
+      "method": "POST",
+      "path": "/account/{sessionId}/create-currency-wallets",
+      "usage": "create-currency-wallets --create-wallets='<json>'",
+      "description": "Partial success is normal: each entry reports its own outcome, and one failure does not roll back the others.",
+      "core": "account.createCurrencyWallets",
+      "params": {
+        "createWallets": {
+          "pass": "--create-wallets='<json>'",
+          "doc": "`EdgeCreateCurrencyWallet[]`: walletType, plus optional name and fiatCurrencyCode.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "results": "unknown[] — Mirrors core’s EdgeResult[]: `{ ok, wallet }` or `{ ok: false, error }`."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "create-wallet": {
+      "summary": "Create a wallet from raw key JSON.",
+      "method": "POST",
+      "path": "/account/{sessionId}/create-wallet",
+      "usage": "create-wallet --type=<type> [--keys='<json>']",
+      "description": "The import path. Use `create-currency-wallet` to make a fresh wallet with generated keys.",
+      "core": "account.createWallet",
+      "params": {
+        "type": {
+          "pass": "--type=<type>",
+          "doc": "Wallet type, e.g. `wallet:bitcoin`.",
+          "optional": false
+        },
+        "keys": {
+          "pass": "[--keys='<json>']",
+          "doc": "Plugin key material. Omit to let core generate it.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "walletId": "string — The new wallet. Its keys are already saved."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "currency-configs": {
+      "summary": "List plugin ids usable for wallet creation.",
+      "method": "GET",
+      "path": "/currency-configs",
+      "usage": "currency-configs",
+      "description": "Currency and accountbased plugins only — swap plugins are excluded.",
+      "returns": {
+        "pluginIds": "string[] — Currency plugins this engine loaded."
+      }
+    },
+    "currency-wallets": {
+      "summary": "List the account's wallets.",
+      "method": "GET",
+      "path": "/account/{sessionId}/currency-wallets",
+      "usage": "currency-wallets [--filter=active|all|archived|hidden]",
+      "core": "account.currencyWallets",
+      "params": {
+        "filter": {
+          "pass": "[--filter=active|all|archived|hidden]",
+          "doc": "Which of the account’s wallet lists to read. Defaults to `active`.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "currencyWallets": "{ walletId: string; id: string; type: string; name: string | null; pluginId: string; currencyCode: string; fiatCurrencyCode: string; blockHeight: number; syncStatus: unknown; syncRatio: string | undefined; paused: boolean; imported: boolean | undefined; created: string | null; enabledTokenIds: string[]; detectedTokenIds: string[]; unactivatedTokenIds: string[]; }[] — Every wallet in the account, including paused ones."
+      },
+      "notes": [
+        "Wallets load in the background after login, so a list taken straight afterwards can be short. Call `wait-for-all-wallets` first to be sure the account has finished loading."
+      ],
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "delete-item": {
+      "summary": "Delete an item.",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-item",
+      "usage": "delete-item --store-id=<storeId> --item-id=<itemId>",
+      "core": "account.dataStore.deleteItem",
+      "params": {
+        "storeId": {
+          "pass": "--store-id=<storeId>",
+          "doc": "Plugin or app namespace within the account data store.",
+          "optional": false
+        },
+        "itemId": {
+          "pass": "--item-id=<itemId>",
+          "doc": "Key within the store.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "delete-password": {
+      "summary": "Remove password login.",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-password",
+      "usage": "delete-password",
+      "description": "The account keeps its other login methods; only the password stops working.",
+      "core": "account.deletePassword",
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "delete-pin": {
+      "summary": "Remove the PIN.",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-pin",
+      "usage": "delete-pin",
+      "description": "PIN login stops working on this device; other methods are untouched.",
+      "core": "account.deletePin",
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "delete-recovery": {
+      "summary": "Disable recovery login.",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-recovery",
+      "usage": "delete-recovery",
+      "description": "The existing recovery key stops working.",
+      "core": "account.deleteRecovery",
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "delete-remote-account": {
+      "summary": "Permanently delete the remote account.",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-remote-account",
+      "usage": "delete-remote-account --yes",
+      "description": "Irreversible. The account is removed from the login server, and funds in its wallets are unrecoverable without the keys. The session is logged out afterwards.",
+      "core": "account.deleteRemoteAccount",
+      "params": {
+        "yes": {
+          "pass": "--yes",
+          "doc": "Confirms intent. Without it the command refuses to run.",
+          "optional": false
+        }
+      },
+      "notes": [
+        "The engine performs no confirmation check — the call runs as soon as it arrives, so any guard has to live in the caller. The command requires `--yes` for exactly this reason."
+      ],
+      "errors": [
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "delete-store": {
+      "summary": "Delete an entire store.",
+      "method": "POST",
+      "path": "/account/{sessionId}/delete-store",
+      "usage": "delete-store --store-id=<storeId>",
+      "description": "Removes every item in it, which cannot be undone from this API.",
+      "core": "account.dataStore.deleteStore",
+      "params": {
+        "storeId": {
+          "pass": "--store-id=<storeId>",
+          "doc": "Plugin or app namespace within the account data store.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "disable-otp": {
+      "summary": "Disable 2FA.",
+      "method": "POST",
+      "path": "/account/{sessionId}/disable-otp",
+      "usage": "disable-otp",
+      "description": "Logins stop requiring a code immediately.",
+      "core": "account.disableOtp",
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "dump-data": {
+      "summary": "Dump wallet engine state.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/dump-data",
+      "usage": "dump-data --wallet-id=<walletId>",
+      "description": "Plugin-defined debug output. Shape varies by plugin and can be very large.",
+      "core": "wallet.dumpData",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "`EdgeDataDump`, straight from the plugin.",
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "enable-otp": {
+      "summary": "Enable 2FA.",
+      "method": "POST",
+      "path": "/account/{sessionId}/enable-otp",
+      "usage": "enable-otp [--timeout=<timeout>]",
+      "description": "Record the returned key before leaving the terminal: it is the only copy.",
+      "core": "account.enableOtp",
+      "params": {
+        "timeout": {
+          "pass": "[--timeout=<timeout>]",
+          "doc": "How long a reset request must wait before it completes, in seconds. Core supplies the default when omitted.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "otpKey": "string | null — The new secret. The 2FA secret itself. Secret material — record it safely."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "encode-uri": {
+      "summary": "Build a payment URI.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/encode-uri",
+      "usage": "encode-uri --wallet-id=<walletId> --public-address=<publicAddress> [--native-amount=<nativeAmount>] [--label=<label>] [--message=<message>] [--currency-code=<currencyCode>]",
+      "description": "For a receive screen or a QR code.",
+      "core": "wallet.encodeUri",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "publicAddress": {
+          "pass": "--public-address=<publicAddress>",
+          "doc": "Where the payment should go.",
+          "optional": false
+        },
+        "nativeAmount": {
+          "pass": "[--native-amount=<nativeAmount>]",
+          "doc": "Amount, in the native unit.",
+          "optional": true
+        },
+        "label": {
+          "pass": "[--label=<label>]",
+          "doc": "BIP21 `label`; becomes `metadata.name` when parsed back.",
+          "optional": true
+        },
+        "message": {
+          "pass": "[--message=<message>]",
+          "doc": "BIP21 `message`; becomes `metadata.notes`.",
+          "optional": true
+        },
+        "currencyCode": {
+          "pass": "[--currency-code=<currencyCode>]",
+          "doc": "Disambiguates on chains that carry several assets.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "uri": "string — The encoded URI, ready for a QR code."
+      },
+      "notes": [
+        "Only these five fields are read; a fuller `EdgeEncodeUri` has its extras ignored."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "engine-config": {
+      "summary": "Configured context options.",
+      "method": "GET",
+      "path": "/engine/config",
+      "usage": "engine-config",
+      "description": "What the engine passed to `makeEdgeContext`. Contains no secrets. Use it to assert tester hosts before a test run.",
+      "returns": {
+        "appId": "string — Application ID the engine was started with.",
+        "testMode": "boolean — True when the engine is not pointed at production: the tester fleet, or the in-process fake world under `--fake`. Read `servers` to tell those apart.",
+        "directory": "string — Working directory holding the core data.",
+        "servers": "{ [keys: string]: string | string[]; } — The URLs this engine talks to, keyed by role. `syncServer` is a list, since core rotates across the sync fleet.",
+        "plugins": "string[] — Plugin IDs the engine loaded, sorted."
+      },
+      "notes": [
+        "Outside `-t` / `--test`, `servers` is an empty object — core is using its built-in production defaults, so there is nothing to echo back."
+      ]
+    },
+    "engine-sessions": {
+      "summary": "List active sessions.",
+      "method": "GET",
+      "path": "/engine/sessions",
+      "usage": "engine-sessions",
+      "returns": {
+        "": "{ sessionId: string; username: string | undefined; rootLoginId: string; loginMethod: \"password\" | \"pin\" | \"edge\" | \"key\" | \"create\" | \"recovery\"; autoLogoutSeconds: number; expiresAt: string | null; lastActivityAt: string; createdAt: string; }[]"
+      },
+      "returnsDoc": "A bare array, not wrapped in a key. Each `sessionId` is truncated: this route needs no session, so a usable id here would be a credential anyone who can reach the engine could collect."
+    },
+    "engine-status": {
+      "summary": "Engine liveness and summary.",
+      "method": "GET",
+      "path": "/engine/status",
+      "usage": "engine-status",
+      "description": "The readiness probe the client polls after auto-spawning the engine.",
+      "returns": {
+        "pid": "number — The daemon process, for `kill` when it will not stop.",
+        "apiVersion": "string — The API this engine speaks. A client refusing to talk to an older engine checks this.",
+        "uptimeSeconds": "number — How long the daemon has been running.",
+        "sessionCount": "number — Logged-in accounts held open right now.",
+        "testMode": "boolean — True when the engine is not pointed at production: the tester fleet, or the in-process fake world under `--fake`.",
+        "idleShutdownAt": "string | null — When the engine will exit for want of work. Null while anything is holding it open — a logged-in session, a live subscription, a request being served, or a pending edge login, whose handle belongs to no session — and null when the timeout is disabled.",
+        "tcpPort": "number | null — The loopback port, null unless started with `--tcp`.",
+        "socketPath": "string — Unix socket the CLI connects to.",
+        "rateCachedCount": "number — Exchange rates held in the engine’s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it.",
+        "locale": "string — Language tag the engine resolved at boot.",
+        "localeMatched": "boolean — Whether a translation table for that tag was actually found. False means the tag was accepted but the engine is answering in English, which is otherwise indistinguishable from a build that has the language.",
+        "decimalSeparator": "string — Decimal mark for that locale.",
+        "groupingSeparator": "string — Thousands mark for that locale."
+      },
+      "returnsDoc": "`idleShutdownAt` is null while a session or a subscription holds the engine open, and `tcpPort` is null unless started with `--tcp`.",
+      "errors": [
+        "ENGINE_SHUTTING_DOWN"
+      ]
+    },
+    "engine-stop": {
+      "summary": "Stop the engine.",
+      "method": "POST",
+      "path": "/engine/stop",
+      "usage": "engine-stop",
+      "description": "Logs out every session, closes the context, unlinks the socket and run-file, then exits. The engine answers before it starts tearing down, so a response is not proof the process is gone.",
+      "returns": {
+        "ok": "boolean — Always true; a failure arrives as an error envelope."
+      },
+      "notes": [
+        "`503 ENGINE_SHUTTING_DOWN` reaches requests that arrive *after* teardown starts, not ones already in flight: `handleRequest` tests the flag at the top only. A request already past that point is waited for — shutdown drains in-flight work before logging out — so it gets its real response. This route is exempt: a second stop is answered `ok`, because stopping an engine that is already stopping has succeeded."
+      ]
+    },
+    "fetch-challenge": {
+      "summary": "Pre-fetch a CAPTCHA challenge.",
+      "method": "POST",
+      "path": "/fetch-challenge",
+      "usage": "fetch-challenge",
+      "description": "Lets a client solve a challenge before it hits `403 CHALLENGE_REQUIRED` mid-flow.",
+      "core": "context.fetchChallenge",
+      "returns": {
+        "challengeId": "string — Pass to the call that demanded a challenge once the user has solved it.",
+        "challengeUri?": "string — Where to send the user to solve the CAPTCHA. Absent when the server issued a challenge that needs no interaction."
+      },
+      "returnsDoc": "`challengeUri` is absent when the server considers the challenge already satisfied.",
+      "errors": [
+        "NETWORK_ERROR"
+      ]
+    },
+    "fetch-lobby": {
+      "summary": "Inspect a login request.",
+      "method": "GET",
+      "path": "/account/{sessionId}/fetch-lobby/{lobbyId}",
+      "usage": "fetch-lobby <lobbyId>",
+      "description": "The other side of `request-edge-login`: shows who is asking, so a human can decide before approving.",
+      "core": "account.fetchLobby",
+      "params": {
+        "lobbyId": {
+          "pass": "<lobbyId>",
+          "doc": "From the QR code, or an `edge://edge/<lobbyId>` link.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "lobbyId": "string — The lobby that was fetched, echoed back.",
+        "loginRequest": "{ appId: string; displayName: string; displayImageDarkUrl: string | null; displayImageLightUrl: string | null; } | null — Null when the lobby carries no pending login request."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "fetch-login-messages": {
+      "summary": "Fetch login-server messages for every local user.",
+      "method": "GET",
+      "path": "/fetch-login-messages",
+      "usage": "fetch-login-messages",
+      "core": "context.fetchLoginMessages",
+      "returnsDoc": "`EdgeLoginMessages` from core, keyed by loginId; each value carries otpResetPending and pendingVouchers.",
+      "errors": [
+        "NETWORK_ERROR"
+      ]
+    },
+    "fetch-recovery-questions": {
+      "summary": "Fetch a user’s recovery questions.",
+      "method": "GET",
+      "path": "/fetch-recovery-questions",
+      "usage": "fetch-recovery-questions --recovery-key=<recoveryKey> --username=<username>",
+      "core": "context.fetchRecovery2Questions",
+      "params": {
+        "recoveryKey": {
+          "pass": "--recovery-key=<recoveryKey>",
+          "doc": "From `change-recovery`, stored by the user out of band.",
+          "optional": false
+        },
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "Whose questions to fetch.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "questions": "string[] — The questions in the order `login-with-recovery` expects the answers."
+      },
+      "errors": [
+        "USERNAME_ERROR",
+        "NETWORK_ERROR"
+      ]
+    },
+    "fetch-swap-quotes": {
+      "summary": "Fetch swap quotes.",
+      "method": "POST",
+      "path": "/account/{sessionId}/fetch-swap-quotes",
+      "usage": "fetch-swap-quotes --from-wallet-id=<fromWalletId> --to-wallet-id=<toWalletId> --native-amount=<nativeAmount> [--from-token-id=<fromTokenId>] [--to-token-id=<toTokenId>] [--quote-for=from|max|to] [--plugin-id=<preferPluginId>]",
+      "description": "Polls every enabled swap plugin and parks each result under its own `swap_` handle with a 5 minute TTL.",
+      "core": "account.fetchSwapQuotes",
+      "params": {
+        "fromWalletId": {
+          "pass": "--from-wallet-id=<fromWalletId>",
+          "doc": "Source wallet. Accepts a unique prefix.",
+          "optional": false
+        },
+        "toWalletId": {
+          "pass": "--to-wallet-id=<toWalletId>",
+          "doc": "Destination wallet.",
+          "optional": false
+        },
+        "nativeAmount": {
+          "pass": "--native-amount=<nativeAmount>",
+          "doc": "How much, in native units.",
+          "optional": false
+        },
+        "fromTokenId": {
+          "pass": "[--from-token-id=<fromTokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "toTokenId": {
+          "pass": "[--to-token-id=<toTokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "quoteFor": {
+          "pass": "[--quote-for=from|max|to]",
+          "doc": "`from` spends this much of the source, `to` receives this much at the destination, `max` sends everything. Defaults to `from`.",
+          "optional": true
+        },
+        "preferPluginId": {
+          "pass": "[--plugin-id=<preferPluginId>]",
+          "doc": "Restrict to one exchange.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "quoteCount": "number — How many plugins answered.",
+        "quotes": "{ objectId: string; kind: string; expiresAt: string; pluginId: string; isEstimate: boolean; canBePartial: boolean | null; maxFulfillmentSeconds: number | null; minReceiveAmount: string | null; fromNativeAmount: string; toNativeAmount: string; networkFee: { nativeAmount: string; tokenId: string | null; }; quoteExpirationDate: string | null; swapInfo: { pluginId: string; displayName: string; supportEmail: string; isDex: boolean | null; }; request: { fromTokenId: string | null; toTokenId: string | null; nativeAmount: string; quoteFor: \"from\" | \"to\" | \"max\"; fromWalletId: string; toWalletId: string; }; }[] — One quote per plugin that answered, each already parked under its own handle. Plugins that failed or had nothing to offer are simply absent."
+      },
+      "notes": [
+        "Every returned quote holds an open plugin object. Approving one releases only that handle; close the rest, or let them expire.",
+        "An empty `quotes` array with `quoteCount: 0` is a success, not an error — no plugin could serve the pair."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "SWAP_BELOW_LIMIT",
+        "SWAP_ABOVE_LIMIT",
+        "SWAP_CURRENCY",
+        "SWAP_PERMISSION",
+        "SWAP_ADDRESS",
+        "SAME_CURRENCY",
+        "INSUFFICIENT_FUNDS",
+        "WALLET_NOT_FOUND",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "fix-username": {
+      "summary": "Normalize a username.",
+      "method": "GET",
+      "path": "/fix-username",
+      "usage": "fix-username --username=<username>",
+      "description": "Applies the same rules the login server does, so a caller can show the user what their name will actually be before creating an account.",
+      "core": "context.fixUsername",
+      "params": {
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "The name to normalize.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "username": "string — The normalized value. The input is not echoed."
+      }
+    },
+    "forget-account": {
+      "summary": "Forget an account on this device.",
+      "method": "POST",
+      "path": "/forget-account",
+      "usage": "forget-account --root-login-id=<rootLoginId>",
+      "description": "Removes locally cached credentials. The remote account is untouched.",
+      "core": "context.forgetAccount",
+      "params": {
+        "rootLoginId": {
+          "pass": "--root-login-id=<rootLoginId>",
+          "doc": "Core takes a `rootLoginId`. A username is also accepted and resolved against `localUsers` first, so callers need not hash it.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "USER_NOT_FOUND",
+        "BAD_REQUEST"
+      ]
+    },
+    "get-addresses": {
+      "summary": "Receive addresses.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-addresses",
+      "usage": "get-addresses --wallet-id=<walletId> [--token-id=<tokenId>] [--force-index=<forceIndex>]",
+      "core": "wallet.getAddresses",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "forceIndex": {
+          "pass": "[--force-index=<forceIndex>]",
+          "doc": "Derive at a specific index.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "addresses": "unknown[] — `EdgeAddress[]`: addressType, publicAddress, nativeBalance."
+      },
+      "errors": [
+        "TOKEN_NOT_FOUND",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-display-private-key": {
+      "summary": "Export the private key for display.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-display-private-key",
+      "usage": "get-display-private-key --wallet-id=<walletId>",
+      "description": "Secret. The human-facing form — WIF, seed phrase, whatever the plugin shows on its export screen.",
+      "core": "account.getDisplayPrivateKey",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "key": "string — The displayable private key."
+      },
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-display-public-key": {
+      "summary": "Export the public key for display.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-display-public-key",
+      "usage": "get-display-public-key --wallet-id=<walletId>",
+      "description": "The xpub or equivalent — safe to share for watch-only use.",
+      "core": "account.getDisplayPublicKey",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "key": "string — The displayable public key."
+      },
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-item": {
+      "summary": "Read an item.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-item",
+      "usage": "get-item --store-id=<storeId> --item-id=<itemId>",
+      "description": "Values are opaque strings; encoding is the caller's business.",
+      "core": "account.dataStore.getItem",
+      "params": {
+        "storeId": {
+          "pass": "--store-id=<storeId>",
+          "doc": "Plugin or app namespace within the account data store.",
+          "optional": false
+        },
+        "itemId": {
+          "pass": "--item-id=<itemId>",
+          "doc": "Key within the store.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "value": "string — The stored string."
+      },
+      "errors": [
+        "NOT_FOUND",
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-login-key": {
+      "summary": "Read the account login key.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-login-key",
+      "usage": "get-login-key",
+      "description": "The key `login-with-key` takes. It grants full account access, so treat the output as secret.",
+      "core": "account.getLoginKey",
+      "returns": {
+        "loginKey": "string — base58. Full account access — keep it safe."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-max-spendable": {
+      "summary": "Largest sendable amount.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/get-max-spendable",
+      "usage": "get-max-spendable --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "description": "What empties the wallet after fees. A destination is still required, since fees depend on it.",
+      "core": "wallet.getMaxSpendable",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "spendInfo": {
+          "pass": "[--spend-info='<json>']",
+          "doc": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required.",
+          "optional": true
+        },
+        "to": {
+          "pass": "[--to=<to>]",
+          "doc": "Address or BIP21 URI, run through `wallet.parseUri`.",
+          "optional": true
+        },
+        "nativeAmount": {
+          "pass": "[--native-amount=<nativeAmount>]",
+          "doc": "How much, in native units.",
+          "optional": true
+        },
+        "amount": {
+          "pass": "[--amount=<amount>]",
+          "doc": "Alias of `nativeAmount`.",
+          "optional": true
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "metadata": {
+          "pass": "[--metadata='<json>']",
+          "doc": "Wins over anything parsed out of the URI.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "nativeAmount": "string — The most this wallet can send."
+      },
+      "errors": [
+        "TOKEN_NOT_FOUND",
+        "INSUFFICIENT_FUNDS",
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-num-transactions": {
+      "summary": "Count transactions in a wallet.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-num-transactions",
+      "usage": "get-num-transactions --wallet-id=<walletId> [--token-id=<tokenId>]",
+      "description": "Cheaper than listing when only the total matters.",
+      "core": "wallet.getNumTransactions",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "numTransactions": "number — Every transaction the wallet knows of."
+      },
+      "notes": [
+        "Unfiltered: `spamThreshold`, dates and `searchString` do not apply, so this can exceed `total` from `get-transactions`."
+      ],
+      "errors": [
+        "TOKEN_NOT_FOUND",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-payment-protocol-info": {
+      "summary": "Fetch a BIP70 payment request.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-payment-protocol-info",
+      "usage": "get-payment-protocol-info --wallet-id=<walletId> --payment-protocol-url=<paymentProtocolUrl>",
+      "description": "Feed `spendTargets` from the result into `make-spend` to pay it.",
+      "core": "wallet.getPaymentProtocolInfo",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "paymentProtocolUrl": {
+          "pass": "--payment-protocol-url=<paymentProtocolUrl>",
+          "doc": "The payment-request URL.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "`EdgePaymentProtocolInfo`: domain, memo, merchant, nativeAmount, spendTargets.",
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-pin": {
+      "summary": "Read the account PIN.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-pin",
+      "usage": "get-pin",
+      "description": "Returns the PIN itself, not a status flag, so treat the output as secret.",
+      "core": "account.getPin",
+      "returns": {
+        "pin": "string | null — Null when no PIN is set."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-raw-private-key": {
+      "summary": "Read raw private key material.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-raw-private-key",
+      "usage": "get-raw-private-key --wallet-id=<walletId>",
+      "description": "Secret. Whatever the plugin stores — seed, mnemonic, xpriv.",
+      "core": "account.getRawPrivateKey",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "The plugin’s key object, at the top level.",
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-raw-public-key": {
+      "summary": "Read raw public key material.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-raw-public-key",
+      "usage": "get-raw-public-key --wallet-id=<walletId>",
+      "core": "account.getRawPublicKey",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "The plugin’s public key object.",
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-transactions": {
+      "summary": "List or export a wallet's transactions.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/get-transactions",
+      "usage": "get-transactions --wallet-id=<walletId> [--token-id=<tokenId>] [--limit=<limit>] [--offset=<offset>] [--save-export-prefs[=false]] [--start-date=<startDate>] [--end-date=<endDate>] [--search-string=<searchString>] [--spam-threshold=<spamThreshold>] [--fiat=<fiat>] [--export-format=<exportFormat>] [--bitwave-account=<bitwaveAccountId>] [--out=<value>]",
+      "description": "Reads history, overlays the display metadata the GUI shows, fills historical fiat, and optionally formats the result — all on this one call.",
+      "core": "wallet.getTransactions",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "limit": {
+          "pass": "[--limit=<limit>]",
+          "doc": "How many to return. Defaults to 100; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.",
+          "optional": true
+        },
+        "offset": {
+          "pass": "[--offset=<offset>]",
+          "doc": "Where to start. Defaults to 0.",
+          "optional": true
+        },
+        "saveExportPrefs": {
+          "pass": "[--save-export-prefs[=false]]",
+          "doc": "Save `bitwaveAccountId` and the chosen formats into the wallet’s synced `exportTxInfo.json`, which the GUI export scene reads back. Off by default: a read does not change saved preferences.",
+          "optional": true
+        },
+        "startDate": {
+          "pass": "[--start-date=<startDate>]",
+          "doc": "ISO-8601, or epoch milliseconds.",
+          "optional": true
+        },
+        "endDate": {
+          "pass": "[--end-date=<endDate>]",
+          "doc": "ISO-8601, or epoch milliseconds.",
+          "optional": true
+        },
+        "searchString": {
+          "pass": "[--search-string=<searchString>]",
+          "doc": "Matches payee, category, notes and txid.",
+          "optional": true
+        },
+        "spamThreshold": {
+          "pass": "[--spam-threshold=<spamThreshold>]",
+          "doc": "Native-amount floor. Omitted, the account spam-filter setting applies; a value always overrides it, and `0` shows everything. An empty value reads as omitted, like every other query parameter.",
+          "optional": true
+        },
+        "fiat": {
+          "pass": "[--fiat=<fiat>]",
+          "doc": "Three-letter ISO 4217 code. Defaults to the account defaultIsoFiat.",
+          "optional": true
+        },
+        "exportFormat": {
+          "pass": "[--export-format=<exportFormat>]",
+          "doc": "Comma list of `csv`, `qbo`, `bitwave`.",
+          "optional": true
+        },
+        "bitwaveAccountId": {
+          "pass": "[--bitwave-account=<bitwaveAccountId>]",
+          "doc": "A 400 unless `exportFormat` includes `bitwave`.",
+          "optional": true
+        },
+        "out": {
+          "pass": "--out=<value>",
+          "doc": "Where to write the returned files. One format: the path. Several: a stem, plus .csv / .qbo / .bitwave.csv.",
+          "optional": true
+        }
+      },
+      "returnsDoc": "`{ transactions, total, isoFiat }`, or `{ ok, isoFiat, total, files }` when exportFormat is set. Each transaction carries `metadata.name`, `metadata.category` and `metadata.notes` as **localized prose** in the engine’s boot locale — the engine has no per-request locale, so a second shell with a different `LANG` reuses the first engine and gets its language. `displayInfo` beside them carries the machine values the prose was derived from (`direction`, `assetActionType`, `actionType`, and the `category` split whose `category` member is one of `transfer`, `exchange`, `expense`, `income`), so a caller can render its own text.",
+      "notes": [
+        "The metadata overlay and the fiat fill are response-only. Neither writes to disk.",
+        "`limit` and `offset` apply before the fiat fill, so a large page asks the rates server about more dates. Unpriced dates are batched into one request per 100, and every rate is cached for the life of the engine, so a second listing of the same range needs none.",
+        "This is the one GET that can write: passing `bitwaveAccountId` persists it to `exportTxInfo.json` on the wallet disklet."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "MISSING_BITWAVE_ACCOUNT_ID",
+        "TOKEN_NOT_FOUND",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "get-wallet-info": {
+      "summary": "Read one wallet's key info.",
+      "method": "GET",
+      "path": "/account/{sessionId}/get-wallet-info",
+      "usage": "get-wallet-info --id=<id>",
+      "core": "account.getWalletInfo",
+      "params": {
+        "id": {
+          "pass": "--id=<id>",
+          "doc": "The key id, from `all-keys`. Base64, like a wallet id.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "`EdgeWalletInfoFull`, verbatim from core — including the `keys` object.",
+      "notes": [
+        "An exact lookup: unlike the wallet-scoped routes this does not accept an id prefix."
+      ],
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "list-item-ids": {
+      "summary": "List item ids in a store.",
+      "method": "GET",
+      "path": "/account/{sessionId}/list-item-ids",
+      "usage": "list-item-ids --store-id=<storeId>",
+      "core": "account.dataStore.listItemIds",
+      "params": {
+        "storeId": {
+          "pass": "--store-id=<storeId>",
+          "doc": "Plugin or app namespace within the account data store.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "itemIds": "string[] — Keys in this store. Empty if it has none."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "list-splittable-wallet-types": {
+      "summary": "List chains a wallet can split into.",
+      "method": "GET",
+      "path": "/account/{sessionId}/list-splittable-wallet-types",
+      "usage": "list-splittable-wallet-types --wallet-id=<walletId>",
+      "description": "Forked-chain support: which wallet types can be derived from these keys.",
+      "core": "account.listSplittableWalletTypes",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "walletTypes": "string[] — Types valid for `split`."
+      },
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "list-store-ids": {
+      "summary": "List data-store ids.",
+      "method": "GET",
+      "path": "/account/{sessionId}/list-store-ids",
+      "usage": "list-store-ids",
+      "description": "The account's synced key-value store, where plugins keep their own state.",
+      "core": "account.dataStore.listStoreIds",
+      "returns": {
+        "storeIds": "string[] — Every store holding at least one item."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "local-settings": {
+      "summary": "Local settings.",
+      "method": "GET",
+      "path": "/account/{sessionId}/local-settings",
+      "usage": "local-settings",
+      "description": "Device-local account settings, stored in `Settings.json` on `account.localDisklet`. They are not synced — a phone and a CLI keep separate copies unless they share an Edge data directory.\n\nChange local settings. Writes device-local account settings. Every option is a field on the body; `spamFilterOn` is the only one today, and new options are added alongside it.",
+      "returns": {
+        "spamFilterOn": "boolean — Hide spam transactions in `get-transactions` results. Defaults to `true`, matching the GUI. The filter hides rows; it never changes stored metadata."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ],
+      "alsoUsage": [
+        "local-settings --spam-filter-on=true|false"
+      ],
+      "alsoRest": [
+        "POST /account/{sessionId}/change-local-settings"
+      ],
+      "params": {
+        "spamFilterOn": {
+          "pass": "--spam-filter-on=true|false",
+          "doc": "Hide spam transactions in `get-transactions` results. Defaults to `true`, matching the GUI. The filter hides rows; it never changes stored metadata.",
+          "optional": false
+        }
+      }
+    },
+    "local-users": {
+      "summary": "List local users on this device.",
+      "method": "GET",
+      "path": "/local-users",
+      "usage": "local-users",
+      "core": "context.localUsers",
+      "returns": {
+        "localUsers": "unknown[] — `EdgeUserInfo[]`: one entry per account cached on this device."
+      },
+      "returnsDoc": "Everything `context.localUsers` reports, including which login methods each user has enabled on this device."
+    },
+    "login-with-key": {
+      "summary": "Log in with an account login key.",
+      "method": "POST",
+      "path": "/login-with-key",
+      "usage": "login-with-key [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --username-or-login-id=<usernameOrLoginId> --login-key=<loginKey> [--use-login-id[=false]]",
+      "description": "The key comes from `get-login-key` on an already-authenticated session.",
+      "core": "context.loginWithKey",
+      "params": {
+        "otp": {
+          "pass": "[--otp=<otp>]",
+          "doc": "A current 2FA code.",
+          "optional": true
+        },
+        "otpKey": {
+          "pass": "[--otp-key=<otpKey>]",
+          "doc": "The 2FA secret itself, instead of a code.",
+          "optional": true
+        },
+        "challengeId": {
+          "pass": "[--challenge-id=<challengeId>]",
+          "doc": "Supply after solving a CAPTCHA to retry the same request.",
+          "optional": true
+        },
+        "usernameOrLoginId": {
+          "pass": "--username-or-login-id=<usernameOrLoginId>",
+          "doc": "A username, or a login id.",
+          "optional": false
+        },
+        "loginKey": {
+          "pass": "--login-key=<loginKey>",
+          "doc": "From `get-login-key`.",
+          "optional": false
+        },
+        "useLoginId": {
+          "pass": "[--use-login-id[=false]]",
+          "doc": "Treat the value as a login id.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "sessionId": "string — Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.",
+        "username?": "string — Absent for a light account, which has no username.",
+        "rootLoginId": "string — The account root, stable across appIds. Two sessions sharing it are the same account.",
+        "loginMethod": "\"create\" | \"edge\" | \"key\" | \"password\" | \"pin\" | \"recovery\" — How this session was established.",
+        "autoLogoutSeconds": "number — Idle time before the engine logs the account out. 0 disables it.",
+        "expiresAt": "string | null — When auto-logout will fire, or null when it is disabled.",
+        "lastActivityAt": "string — Last call on this session, which is what auto-logout measures from.",
+        "createdAt": "string — When the login completed."
+      },
+      "returnsDoc": "A session with `loginMethod: \"key\"`.",
+      "errors": [
+        "PASSWORD_ERROR",
+        "USERNAME_ERROR",
+        "NETWORK_ERROR"
+      ]
+    },
+    "login-with-password": {
+      "summary": "Log in with a password.",
+      "method": "POST",
+      "path": "/login-with-password",
+      "usage": "login-with-password [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --username=<username> --password=<password>",
+      "core": "context.loginWithPassword",
+      "params": {
+        "otp": {
+          "pass": "[--otp=<otp>]",
+          "doc": "A current 2FA code.",
+          "optional": true
+        },
+        "otpKey": {
+          "pass": "[--otp-key=<otpKey>]",
+          "doc": "The 2FA secret itself, instead of a code.",
+          "optional": true
+        },
+        "challengeId": {
+          "pass": "[--challenge-id=<challengeId>]",
+          "doc": "Supply after solving a CAPTCHA to retry the same request.",
+          "optional": true
+        },
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "The account name.",
+          "optional": false
+        },
+        "password": {
+          "pass": "--password=<password>",
+          "doc": "The account password.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "sessionId": "string — Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.",
+        "username?": "string — Absent for a light account, which has no username.",
+        "rootLoginId": "string — The account root, stable across appIds. Two sessions sharing it are the same account.",
+        "loginMethod": "\"create\" | \"edge\" | \"key\" | \"password\" | \"pin\" | \"recovery\" — How this session was established.",
+        "autoLogoutSeconds": "number — Idle time before the engine logs the account out. 0 disables it.",
+        "expiresAt": "string | null — When auto-logout will fire, or null when it is disabled.",
+        "lastActivityAt": "string — Last call on this session, which is what auto-logout measures from.",
+        "createdAt": "string — When the login completed."
+      },
+      "returnsDoc": "A session with `loginMethod: \"password\"`.",
+      "notes": [
+        "With `--solve-captcha` the client solves a `CHALLENGE_REQUIRED` response headlessly (ALTCHA proof-of-work) and retries once."
+      ],
+      "errors": [
+        "PASSWORD_ERROR",
+        "USERNAME_ERROR",
+        "OTP_REQUIRED",
+        "CHALLENGE_REQUIRED",
+        "NETWORK_ERROR"
+      ]
+    },
+    "login-with-pin": {
+      "summary": "Log in with a device PIN.",
+      "method": "POST",
+      "path": "/login-with-pin",
+      "usage": "login-with-pin [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --username-or-login-id=<usernameOrLoginId> --pin=<pin> [--use-login-id[=false]]",
+      "description": "Only works on a device that has already saved a PIN for the account.",
+      "core": "context.loginWithPIN",
+      "params": {
+        "otp": {
+          "pass": "[--otp=<otp>]",
+          "doc": "A current 2FA code.",
+          "optional": true
+        },
+        "otpKey": {
+          "pass": "[--otp-key=<otpKey>]",
+          "doc": "The 2FA secret itself, instead of a code.",
+          "optional": true
+        },
+        "challengeId": {
+          "pass": "[--challenge-id=<challengeId>]",
+          "doc": "Supply after solving a CAPTCHA to retry the same request.",
+          "optional": true
+        },
+        "usernameOrLoginId": {
+          "pass": "--username-or-login-id=<usernameOrLoginId>",
+          "doc": "A username, or a login id.",
+          "optional": false
+        },
+        "pin": {
+          "pass": "--pin=<pin>",
+          "doc": "The device PIN.",
+          "optional": false
+        },
+        "useLoginId": {
+          "pass": "[--use-login-id[=false]]",
+          "doc": "Treat the value as a login id.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "sessionId": "string — Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.",
+        "username?": "string — Absent for a light account, which has no username.",
+        "rootLoginId": "string — The account root, stable across appIds. Two sessions sharing it are the same account.",
+        "loginMethod": "\"create\" | \"edge\" | \"key\" | \"password\" | \"pin\" | \"recovery\" — How this session was established.",
+        "autoLogoutSeconds": "number — Idle time before the engine logs the account out. 0 disables it.",
+        "expiresAt": "string | null — When auto-logout will fire, or null when it is disabled.",
+        "lastActivityAt": "string — Last call on this session, which is what auto-logout measures from.",
+        "createdAt": "string — When the login completed."
+      },
+      "returnsDoc": "A session with `loginMethod: \"pin\"`.",
+      "errors": [
+        "PASSWORD_ERROR",
+        "PIN_DISABLED",
+        "USERNAME_ERROR",
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "login-with-recovery": {
+      "summary": "Log in with recovery answers.",
+      "method": "POST",
+      "path": "/login-with-recovery",
+      "usage": "login-with-recovery [--otp=<otp>] [--otp-key=<otpKey>] [--challenge-id=<challengeId>] --recovery-key=<recoveryKey> --username=<username> --answer=<answers> …",
+      "description": "Needs both the recovery key and the answers; neither works alone.",
+      "core": "context.loginWithRecovery2",
+      "params": {
+        "otp": {
+          "pass": "[--otp=<otp>]",
+          "doc": "A current 2FA code.",
+          "optional": true
+        },
+        "otpKey": {
+          "pass": "[--otp-key=<otpKey>]",
+          "doc": "The 2FA secret itself, instead of a code.",
+          "optional": true
+        },
+        "challengeId": {
+          "pass": "[--challenge-id=<challengeId>]",
+          "doc": "Supply after solving a CAPTCHA to retry the same request.",
+          "optional": true
+        },
+        "recoveryKey": {
+          "pass": "--recovery-key=<recoveryKey>",
+          "doc": "From `change-recovery`.",
+          "optional": false
+        },
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "The account name.",
+          "optional": false
+        },
+        "answers": {
+          "pass": "--answer=<answers> …",
+          "doc": "In the same order as the questions.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "sessionId": "string — Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.",
+        "username?": "string — Absent for a light account, which has no username.",
+        "rootLoginId": "string — The account root, stable across appIds. Two sessions sharing it are the same account.",
+        "loginMethod": "\"create\" | \"edge\" | \"key\" | \"password\" | \"pin\" | \"recovery\" — How this session was established.",
+        "autoLogoutSeconds": "number — Idle time before the engine logs the account out. 0 disables it.",
+        "expiresAt": "string | null — When auto-logout will fire, or null when it is disabled.",
+        "lastActivityAt": "string — Last call on this session, which is what auto-logout measures from.",
+        "createdAt": "string — When the login completed."
+      },
+      "returnsDoc": "A session with `loginMethod: \"recovery\"`.",
+      "errors": [
+        "PASSWORD_ERROR",
+        "USERNAME_ERROR",
+        "NETWORK_ERROR"
+      ]
+    },
+    "logout": {
+      "summary": "Log out.",
+      "method": "POST",
+      "path": "/account/{sessionId}/logout",
+      "usage": "logout",
+      "description": "Ends the session and drops it from the engine. Any subscription scoped to this account or its wallets is closed with it.",
+      "core": "account.logout",
+      "notes": [
+        "Also clears the stored id from `session.json`."
+      ],
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "make-spend": {
+      "summary": "Build an unsigned transaction.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/make-spend",
+      "usage": "make-spend --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "description": "First step of the staged workflow: nothing is signed and no funds move. Inspect `transaction.networkFee` on the result before signing.",
+      "core": "wallet.makeSpend",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "spendInfo": {
+          "pass": "[--spend-info='<json>']",
+          "doc": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required.",
+          "optional": true
+        },
+        "to": {
+          "pass": "[--to=<to>]",
+          "doc": "Address or BIP21 URI, run through `wallet.parseUri`.",
+          "optional": true
+        },
+        "nativeAmount": {
+          "pass": "[--native-amount=<nativeAmount>]",
+          "doc": "How much, in native units.",
+          "optional": true
+        },
+        "amount": {
+          "pass": "[--amount=<amount>]",
+          "doc": "Alias of `nativeAmount`.",
+          "optional": true
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "metadata": {
+          "pass": "[--metadata='<json>']",
+          "doc": "Wins over anything parsed out of the URI.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "sessionId?": "string — Session that created the handle; only that session may use it.",
+        "walletId?": "string — Wallet the handle is bound to, when it belongs to one.",
+        "transaction": "unknown — `EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+      },
+      "errors": [
+        "TOKEN_NOT_FOUND",
+        "INSUFFICIENT_FUNDS",
+        "DUST_SPEND",
+        "NO_AMOUNT_SPECIFIED",
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "object-delete": {
+      "summary": "Release an object handle.",
+      "method": "POST",
+      "path": "/account/{sessionId}/object/delete/{objectId}",
+      "usage": "object-delete <objectId>",
+      "description": "Runs the handle's cleanup — closing a swap quote, cancelling a pending login — instead of waiting out the TTL.",
+      "returns": {
+        "ok": "boolean — Always true; a failure arrives as an error envelope.",
+        "objectId": "string — The handle this call consumed. It is now expired."
+      },
+      "errors": [
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_IN_USE",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "object-get": {
+      "summary": "Inspect an object handle.",
+      "method": "GET",
+      "path": "/account/{sessionId}/object/{objectId}",
+      "usage": "object-get <objectId>",
+      "description": "Works for every kind: transactions, pending logins, swap quotes and lobbies.",
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "createdAt": "string — When the engine took the handle.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "sessionId?": "string — Session that created the handle; only that session may use it.",
+        "walletId?": "string — Wallet the handle is bound to, when it belongs to one."
+      },
+      "returnsDoc": "The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports `value: null`.",
+      "notes": [
+        "Reading does not extend the TTL. Only a step that updates the value does."
+      ],
+      "errors": [
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_IN_USE",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "otp-key": {
+      "summary": "Read the 2FA secret and reset state.",
+      "method": "GET",
+      "path": "/account/{sessionId}/otp-key",
+      "usage": "otp-key",
+      "core": "account.otpKey",
+      "returns": {
+        "otpKey": "string | null — Null when 2FA is off. The 2FA secret itself. Secret material — record it safely.",
+        "otpResetDate": "string | null — Set once somebody has requested a reset; cancel it with `cancel-otp-reset`."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "parse-uri": {
+      "summary": "Parse a payment URI or address.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/parse-uri",
+      "usage": "parse-uri --wallet-id=<walletId> --uri=<uri> [--currency-code=<currencyCode>]",
+      "description": "What the GUI address tile does when you paste or scan something.",
+      "core": "wallet.parseUri",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "uri": {
+          "pass": "--uri=<uri>",
+          "doc": "A payment URI or a bare address.",
+          "optional": false
+        },
+        "currencyCode": {
+          "pass": "[--currency-code=<currencyCode>]",
+          "doc": "Disambiguates on chains that carry several assets.",
+          "optional": true
+        }
+      },
+      "returnsDoc": "`EdgeParsedUri`: publicAddress, nativeAmount, currencyCode, metadata, paymentProtocolUrl, …",
+      "notes": [
+        "`spend` and `make-spend` run their `to` field through this same call, so parsing separately is only needed to inspect or confirm first."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "pending-vouchers": {
+      "summary": "List pending 2FA vouchers.",
+      "method": "GET",
+      "path": "/account/{sessionId}/pending-vouchers",
+      "usage": "pending-vouchers",
+      "description": "When 2FA blocks a login, the login server issues a voucher that an already-trusted device can approve or reject.",
+      "core": "account.pendingVouchers",
+      "returns": {
+        "pendingVouchers": "unknown[] — `EdgePendingVoucher[]`: voucherId, activates, created, deviceDescription, ipDescription."
+      },
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "poll-edge-login": {
+      "summary": "Poll a pending QR login.",
+      "method": "GET",
+      "path": "/pending-edge-login/{pendingId}",
+      "usage": "poll-edge-login <pendingId>",
+      "description": "Once `state` reaches `done` the engine has already created the session, so the response carries one ready to use.",
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "pendingId": "string — Same value as `objectId`, under the name the poll command takes.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string | null — When the lobby closes and the QR code stops working.",
+        "lobbyId": "string — Lobby the phone connects to.",
+        "uri": "string — The `edge://` URI to render as a QR code for the phone to scan.",
+        "state": "string — How far the login has got: `pending` before the phone scans, `started` once it has, and `done` when `session` is filled in.",
+        "username": "string | null — Account that approved the login, known once the phone has scanned.",
+        "session": "{ sessionId: string; username: string | undefined; rootLoginId: string; loginMethod: \"password\" | \"pin\" | \"edge\" | \"key\" | \"create\" | \"recovery\"; autoLogoutSeconds: number; expiresAt: string | null; lastActivityAt: string; createdAt: string; } | null — The session, null until `state` is `done`.",
+        "error": "string | null — Why the login failed, set only when `state` is `error`."
+      },
+      "notes": [
+        "Session creation is attempted once. A failure is sticky, so later polls report the same `error` rather than retrying.",
+        "Polling does not extend the handle TTL; only the original 5 minute window applies."
+      ],
+      "errors": [
+        "PENDING_LOGIN_NOT_FOUND",
+        "OBJECT_EXPIRED"
+      ]
+    },
+    "rates-query": {
+      "summary": "Batch crypto and fiat rate lookups.",
+      "method": "POST",
+      "path": "/rates/query",
+      "usage": "rates-query [--crypto='<json>'] [--fiat='<json>']",
+      "description": "Concurrent lookups share one rates-server queue, so asking for many rates at once costs a single upstream request.",
+      "params": {
+        "crypto": {
+          "pass": "[--crypto='<json>']",
+          "doc": "Crypto rates to fetch.",
+          "optional": true
+        },
+        "fiat": {
+          "pass": "[--fiat='<json>']",
+          "doc": "Fiat rates to fetch.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "crypto": "{ pluginId: string; tokenId: string | null; targetFiat: string; date: string; rate: number; }[] — Always present; empty when no crypto rates were requested.",
+        "fiat": "{ fiatCode: string; targetFiat: string; date: string; rate: number; }[] — Always present; empty when no fiat rates were requested."
+      },
+      "notes": [
+        "A rate the server cannot supply comes back as `0` rather than an error, so check for zero before dividing."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "rates-usd-to-native": {
+      "summary": "Convert a USD amount into native units.",
+      "method": "POST",
+      "path": "/rates/usd-to-native",
+      "usage": "rates-usd-to-native --usd-amount=<usdAmount> --plugin-id=<pluginId> [--token-id=<tokenId>] --multiplier=<multiplier> [--date=<date>]",
+      "description": "Turns a fiat notional into the native amount a spend needs.",
+      "params": {
+        "usdAmount": {
+          "pass": "--usd-amount=<usdAmount>",
+          "doc": "A positive decimal string.",
+          "optional": false
+        },
+        "pluginId": {
+          "pass": "--plugin-id=<pluginId>",
+          "doc": "Which chain to price.",
+          "optional": false
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "multiplier": {
+          "pass": "--multiplier=<multiplier>",
+          "doc": "Native units per whole coin, as a positive decimal string. This route is not session-scoped, so the engine cannot read the asset’s denomination from core and will not guess one.",
+          "optional": false
+        },
+        "date": {
+          "pass": "[--date=<date>]",
+          "doc": "ISO-8601. Omitted, the current time is sent to the rates server.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "usdAmount": "number — Echoed as a number, though it is sent as a string.",
+        "pluginId": "string — Currency plugin the amount was converted for.",
+        "tokenId": "string | null — The asset, or null for the chain’s own coin.",
+        "multiplier": "string — Native units per whole coin, which is what `displayAmount` was multiplied by to reach `nativeAmount`.",
+        "date": "string — The timestamp actually used for the rate.",
+        "rate": "number — USD per whole coin at that date.",
+        "displayAmount": "string — Whole coins, to 8 decimal places.",
+        "nativeAmount": "string — What a spend actually takes."
+      },
+      "notes": [
+        "`displayAmount` is rounded to 8 decimals before conversion, so assets with finer precision lose the tail. For an exact figure use `rates-query` and do the arithmetic yourself.",
+        "`multiplier` is required. The engine has no logged-in account here, so it cannot read the asset's denomination from core, and a guessed multiplier would return a `nativeAmount` wrong by orders of magnitude under a field documented as what a spend takes."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "NOT_FOUND",
+        "NETWORK_ERROR"
+      ]
+    },
+    "reject-voucher": {
+      "summary": "Reject a voucher.",
+      "method": "POST",
+      "path": "/account/{sessionId}/reject-voucher",
+      "usage": "reject-voucher --voucher-id=<voucherId>",
+      "description": "Denies the waiting device. The login it was issued for cannot complete.",
+      "core": "account.rejectVoucher",
+      "params": {
+        "voucherId": {
+          "pass": "--voucher-id=<voucherId>",
+          "doc": "From `pending-vouchers`, or an `OTP_REQUIRED` error’s `details.voucherId`.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "rename-wallet": {
+      "summary": "Rename a wallet.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/rename-wallet",
+      "usage": "rename-wallet --wallet-id=<walletId> --name=<name>",
+      "core": "wallet.renameWallet",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "name": {
+          "pass": "--name=<name>",
+          "doc": "The new display name.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "repair-otp": {
+      "summary": "Re-point the account at a known 2FA secret.",
+      "method": "POST",
+      "path": "/account/{sessionId}/repair-otp",
+      "usage": "repair-otp --otp-key=<otpKey>",
+      "description": "For a device whose stored secret has drifted from the server's.",
+      "core": "account.repairOtp",
+      "params": {
+        "otpKey": {
+          "pass": "--otp-key=<otpKey>",
+          "doc": "The secret the account should use.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "OTP_REQUIRED",
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "request-edge-login": {
+      "summary": "Start a QR login.",
+      "method": "POST",
+      "path": "/request-edge-login",
+      "usage": "request-edge-login [--no-wait]",
+      "description": "Asks the login server for a lobby another logged-in Edge device can approve. The returned `lobbyId` is what goes in the QR code.",
+      "core": "context.requestEdgeLogin",
+      "params": {
+        "no-wait": {
+          "pass": "--no-wait",
+          "doc": "Print the lobby and exit instead of polling, so the QR can be displayed while `poll-edge-login` watches the same handle from another process.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "pendingId": "string — Same value as `objectId`, under the name the poll command takes.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string | null — When the lobby closes and the QR code stops working.",
+        "lobbyId": "string — Lobby the phone connects to.",
+        "uri": "string — The `edge://` URI to render as a QR code for the phone to scan.",
+        "state": "string — How far the login has got: `pending` before the phone scans, `started` once it has, and `done` when `session` is filled in.",
+        "username": "string | null — Account that approved the login, known once the phone has scanned.",
+        "session": "{ sessionId: string; username: string | undefined; rootLoginId: string; loginMethod: \"password\" | \"pin\" | \"edge\" | \"key\" | \"create\" | \"recovery\"; autoLogoutSeconds: number; expiresAt: string | null; lastActivityAt: string; createdAt: string; } | null — The session, null until `state` is `done`.",
+        "error": "string | null — Why the login failed, set only when `state` is `error`."
+      },
+      "notes": [
+        "The pending login is an object handle with a 5 minute TTL. On expiry the engine cancels the request on the login server for you.",
+        "Prints the pending login, then polls every 2s for up to 5 minutes. On `done` it stores the session. With `--no-wait` it returns immediately and `poll-edge-login` takes over."
+      ],
+      "errors": [
+        "NETWORK_ERROR"
+      ]
+    },
+    "request-otp-reset": {
+      "summary": "Request a 2FA reset.",
+      "method": "POST",
+      "path": "/request-otp-reset",
+      "usage": "request-otp-reset --username=<username> --otp-reset-token=<otpResetToken>",
+      "description": "Starts the timed reset a user falls back on after losing their authenticator.",
+      "core": "context.requestOtpReset",
+      "params": {
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "Whose 2FA to reset.",
+          "optional": false
+        },
+        "otpResetToken": {
+          "pass": "--otp-reset-token=<otpResetToken>",
+          "doc": "From `details.resetToken` on an `OTP_REQUIRED` error.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "resetDate": "string — When 2FA will actually come off. The login server enforces a waiting period so the real owner has time to cancel."
+      },
+      "returnsDoc": "When the reset completes if nobody cancels it.",
+      "errors": [
+        "USERNAME_ERROR",
+        "BAD_REQUEST",
+        "NETWORK_ERROR"
+      ]
+    },
+    "resync-blockchain": {
+      "summary": "Rescan the blockchain from scratch.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/resync-blockchain",
+      "usage": "resync-blockchain --wallet-id=<walletId>",
+      "description": "Drops cached chain state and re-scans. Expensive, and the wallet reports an incomplete balance until it finishes.",
+      "core": "wallet.resyncBlockchain",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "notes": [
+        "Returns when the resync is requested, not when it completes. Watch `syncRatio` for progress."
+      ],
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "save-tx": {
+      "summary": "Record a transaction and release its handle.",
+      "method": "POST",
+      "path": "/account/{sessionId}/save-tx/{objectId}",
+      "usage": "save-tx <objectId>",
+      "description": "Final step. The handle is gone afterwards, so a second call is a 404.",
+      "core": "wallet.saveTx",
+      "params": {
+        "objectId": {
+          "pass": "<objectId>",
+          "doc": "The handle to persist and release.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "ok": "boolean — Always true; a failure arrives as an error envelope.",
+        "objectId": "string — The handle this call consumed. It is now expired."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_WALLET_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "save-tx-action": {
+      "summary": "Save a transaction action.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/save-tx-action",
+      "usage": "save-tx-action --wallet-id=<walletId> --txid=<txid> [--token-id=<tokenId>] --saved-action='<json>' [--asset-action='<json>']",
+      "description": "Records what a transaction *was* — a swap, a stake — beyond its metadata.",
+      "core": "wallet.saveTxAction",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "txid": {
+          "pass": "--txid=<txid>",
+          "doc": "Which transaction to annotate.",
+          "optional": false
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "savedAction": {
+          "pass": "--saved-action='<json>'",
+          "doc": "`EdgeTxAction` describing what happened, discriminated on `actionType`: swap, stake, fiat, tokenApproval or giftCard.",
+          "optional": false
+        },
+        "assetAction": {
+          "pass": "[--asset-action='<json>']",
+          "doc": "`EdgeAssetAction`: one `assetActionType`.",
+          "optional": true
+        }
+      },
+      "notes": [
+        "When `assetAction` is omitted it defaults to `{ assetActionType: 'transfer' }`."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "TOKEN_NOT_FOUND",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "save-tx-metadata": {
+      "summary": "Save transaction metadata.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/save-tx-metadata",
+      "usage": "save-tx-metadata --wallet-id=<walletId> --txid=<txid> [--token-id=<tokenId>] --metadata='<json>'",
+      "description": "One of the paths that write transaction metadata to disk. The others are `save-tx-action`, which writes `savedAction` and `assetAction` to the same file, and `save-tx` and `spend`, both of which re-apply the caller's metadata through `saveTxAndMetadata` after the transaction is saved.",
+      "core": "wallet.saveTxMetadata",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "txid": {
+          "pass": "--txid=<txid>",
+          "doc": "Which transaction to tag.",
+          "optional": false
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "metadata": {
+          "pass": "--metadata='<json>'",
+          "doc": "`EdgeMetadataChange`: name, category, notes, exchangeAmount, bizId. `null` on a field deletes it; omitting the field leaves it unchanged.",
+          "optional": false
+        }
+      },
+      "notes": [
+        "`metadata` is an `EdgeMetadataChange`, so an explicit null clears a field while an omitted one is left alone."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "TOKEN_NOT_FOUND",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "set-fiat-currency-code": {
+      "summary": "Change a wallet's fiat currency.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/set-fiat-currency-code",
+      "usage": "set-fiat-currency-code --wallet-id=<walletId> --fiat-currency-code=<fiatCurrencyCode>",
+      "description": "Affects how balances and history are priced, not the asset itself.",
+      "core": "wallet.setFiatCurrencyCode",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "fiatCurrencyCode": {
+          "pass": "--fiat-currency-code=<fiatCurrencyCode>",
+          "doc": "e.g. `iso:EUR`.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "set-item": {
+      "summary": "Write an item.",
+      "method": "POST",
+      "path": "/account/{sessionId}/set-item",
+      "usage": "set-item --store-id=<storeId> --item-id=<itemId> --value=<value>",
+      "description": "Creates the store if it does not exist.",
+      "core": "account.dataStore.setItem",
+      "params": {
+        "storeId": {
+          "pass": "--store-id=<storeId>",
+          "doc": "Plugin or app namespace within the account data store.",
+          "optional": false
+        },
+        "itemId": {
+          "pass": "--item-id=<itemId>",
+          "doc": "Key within the store.",
+          "optional": false
+        },
+        "value": {
+          "pass": "--value=<value>",
+          "doc": "The string to store.",
+          "optional": false
+        }
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "sign-bytes": {
+      "summary": "Sign arbitrary bytes.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/sign-bytes",
+      "usage": "sign-bytes --wallet-id=<walletId> [--bytes=<bytes>] [--other-params='<json>']",
+      "description": "Message signing and proof-of-ownership, for plugins that support it.",
+      "core": "wallet.signBytes",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "bytes": {
+          "pass": "[--bytes=<bytes>]",
+          "doc": "Base64. Defaults to empty when absent.",
+          "optional": true
+        },
+        "otherParams": {
+          "pass": "[--other-params='<json>']",
+          "doc": "Plugin-specific options. Bitcoin needs `{ publicAddress }`; other plugins take nothing, or refuse the call entirely.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "signature": "string — Base64."
+      },
+      "notes": [
+        "Invalid base64 is refused with `BAD_REQUEST` rather than signed.",
+        "Support is per plugin, and failures surface as `500 INTERNAL_ERROR` from the plugin rather than as a typed error: litecoin answers \"litecoin doesn't support signBytes\", and bitcoin requires `otherParams.publicAddress` naming which address to sign with."
+      ],
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "sign-tx": {
+      "summary": "Sign a staged transaction.",
+      "method": "POST",
+      "path": "/account/{sessionId}/sign-tx/{objectId}",
+      "usage": "sign-tx <objectId>",
+      "description": "Keeps the same handle and pushes its expiry out another five minutes.",
+      "core": "wallet.signTx",
+      "params": {
+        "objectId": {
+          "pass": "<objectId>",
+          "doc": "From `make-spend`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "sessionId?": "string — Session that created the handle; only that session may use it.",
+        "walletId?": "string — Wallet the handle is bound to, when it belongs to one.",
+        "transaction": "unknown — `EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_WALLET_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "spend": {
+      "summary": "Send funds.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/spend",
+      "usage": "spend [--use-max[=false]] [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "description": "`makeSpend`, then `signTx`, then optionally `broadcastTx` and `saveTx`, in one request. `broadcast` and `save` both default to true, so a bare body with a destination and an amount moves real money. A completed spend leaves no handle behind.",
+      "params": {
+        "useMax": {
+          "pass": "[--use-max[=false]]",
+          "doc": "Replace the first target’s amount with the maximum.",
+          "optional": true
+        },
+        "dryRun": {
+          "pass": "[--dry-run[=false]]",
+          "doc": "Build only. Never signs or broadcasts.",
+          "optional": true
+        },
+        "broadcast": {
+          "pass": "[--broadcast[=false]]",
+          "doc": "Defaults to **true**. With `false` the transaction is signed and not sent, so `save` then defaults to false as well — recording an unsent transaction marks its inputs spent locally for something the network will never confirm.",
+          "optional": true
+        },
+        "save": {
+          "pass": "[--save[=false]]",
+          "doc": "Record the transaction in the wallet. Defaults to whatever `broadcast` is. Setting it true alongside `broadcast: false` is refused: use `--dry-run`, or the staged `make-spend` → `sign-tx` → `broadcast-tx` → `save-tx` flow.",
+          "optional": true
+        },
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "spendInfo": {
+          "pass": "[--spend-info='<json>']",
+          "doc": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required.",
+          "optional": true
+        },
+        "to": {
+          "pass": "[--to=<to>]",
+          "doc": "Address or BIP21 URI, run through `wallet.parseUri`.",
+          "optional": true
+        },
+        "nativeAmount": {
+          "pass": "[--native-amount=<nativeAmount>]",
+          "doc": "How much, in native units.",
+          "optional": true
+        },
+        "amount": {
+          "pass": "[--amount=<amount>]",
+          "doc": "Alias of `nativeAmount`.",
+          "optional": true
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "metadata": {
+          "pass": "[--metadata='<json>']",
+          "doc": "Wins over anything parsed out of the URI.",
+          "optional": true
+        }
+      },
+      "returnsDoc": "`{ transaction }`, plus `saveError` when the broadcast succeeded but saving failed. With dryRun, a TransactionHandle instead.",
+      "notes": [
+        "BIP21 `label` and `message` from `to` become metadata name and notes. An explicit `metadata` object wins.",
+        "`saveError` is the case to handle. Once broadcast, the money is gone, so a failure inside saveTx cannot throw — it would hide the txid of a real payment. The response is 200 with the transaction plus `saveError`.",
+        "With `dryRun`, only makeSpend runs and the response is a transaction handle that expires in 5 minutes."
+      ],
+      "errors": [
+        "TOKEN_NOT_FOUND",
+        "INSUFFICIENT_FUNDS",
+        "DUST_SPEND",
+        "PENDING_FUNDS",
+        "SPEND_TO_SELF",
+        "NO_AMOUNT_SPECIFIED",
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "spend-max": {
+      "summary": "Send a wallet’s entire spendable balance.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/spend",
+      "usage": "spend-max [--dry-run[=false]] [--broadcast[=false]] [--save[=false]] --wallet-id=<walletId> [--spend-info='<json>'] [--to=<to>] [--native-amount=<nativeAmount>] [--amount=<amount>] [--token-id=<tokenId>] [--metadata='<json>']",
+      "description": "`makeSpend`, then `signTx`, then optionally `broadcastTx` and `saveTx`, in one request. `broadcast` and `save` both default to true, so a bare body with a destination and an amount moves real money. A completed spend leaves no handle behind.",
+      "params": {
+        "useMax": {
+          "pass": "[--use-max[=false]]",
+          "doc": "Replace the first target’s amount with the maximum.",
+          "optional": true
+        },
+        "dryRun": {
+          "pass": "[--dry-run[=false]]",
+          "doc": "Build only. Never signs or broadcasts.",
+          "optional": true
+        },
+        "broadcast": {
+          "pass": "[--broadcast[=false]]",
+          "doc": "Defaults to **true**. With `false` the transaction is signed and not sent, so `save` then defaults to false as well — recording an unsent transaction marks its inputs spent locally for something the network will never confirm.",
+          "optional": true
+        },
+        "save": {
+          "pass": "[--save[=false]]",
+          "doc": "Record the transaction in the wallet. Defaults to whatever `broadcast` is. Setting it true alongside `broadcast: false` is refused: use `--dry-run`, or the staged `make-spend` → `sign-tx` → `broadcast-tx` → `save-tx` flow.",
+          "optional": true
+        },
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "spendInfo": {
+          "pass": "[--spend-info='<json>']",
+          "doc": "A full `EdgeSpendInfo`, used as-is when present. `spendTargets` is required.",
+          "optional": true
+        },
+        "to": {
+          "pass": "[--to=<to>]",
+          "doc": "Address or BIP21 URI, run through `wallet.parseUri`.",
+          "optional": true
+        },
+        "nativeAmount": {
+          "pass": "[--native-amount=<nativeAmount>]",
+          "doc": "How much, in native units.",
+          "optional": true
+        },
+        "amount": {
+          "pass": "[--amount=<amount>]",
+          "doc": "Alias of `nativeAmount`.",
+          "optional": true
+        },
+        "tokenId": {
+          "pass": "[--token-id=<tokenId>]",
+          "doc": "Defaults to the native asset.",
+          "optional": true
+        },
+        "metadata": {
+          "pass": "[--metadata='<json>']",
+          "doc": "Wins over anything parsed out of the URI.",
+          "optional": true
+        }
+      },
+      "returnsDoc": "`{ transaction }`, plus `saveError` when the broadcast succeeded but saving failed. With dryRun, a TransactionHandle instead.",
+      "notes": [
+        "BIP21 `label` and `message` from `to` become metadata name and notes. An explicit `metadata` object wins.",
+        "`saveError` is the case to handle. Once broadcast, the money is gone, so a failure inside saveTx cannot throw — it would hide the txid of a real payment. The response is 200 with the transaction plus `saveError`.",
+        "With `dryRun`, only makeSpend runs and the response is a transaction handle that expires in 5 minutes.",
+        "The same route with `useMax` preset, so it sends everything."
+      ],
+      "errors": [
+        "TOKEN_NOT_FOUND",
+        "INSUFFICIENT_FUNDS",
+        "DUST_SPEND",
+        "PENDING_FUNDS",
+        "SPEND_TO_SELF",
+        "NO_AMOUNT_SPECIFIED",
+        "BAD_REQUEST",
+        "NETWORK_ERROR",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "split": {
+      "summary": "Split a wallet into another chain.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/split",
+      "usage": "split --wallet-id=<walletId> --split-wallets='<json>'",
+      "description": "Forked-chain support: derive a wallet of a different type from the same keys. `list-splittable-wallet-types` says which are valid.",
+      "core": "wallet.split",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "splitWallets": {
+          "pass": "--split-wallets='<json>'",
+          "doc": "`EdgeSplitCurrencyWallet[]`: walletType, plus optional name and fiatCurrencyCode.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "results": "unknown[] — Per-entry outcomes, like batch create."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "subscribe": {
+      "summary": "Subscribe to engine events.",
+      "method": "GET",
+      "path": "/engine/events",
+      "usage": "subscribe [--session-id=<sessionId>] [--wallet-id=<walletId>] [--type=<value>]",
+      "description": "Holds a Server-Sent Events stream open until the caller disconnects or the engine closes it. Runs concurrently with one-shot calls, so a subscriber in one terminal watches what another terminal does.\n\nA live subscription holds the engine open past its idle timeout. It does not hold an account logged in: the auto-logout timer still fires, and closes any subscription scoped to that account or one of its wallets. Context-scoped subscriptions survive, because the context outlives every account.\n\nScope comes from the query string. With no `sessionId` the stream is context-scoped and nothing but the engine stopping ends it, which is what the `subscribe` command asks for. With `sessionId` it is account-scoped: a logout closes it, and the session events of *other* accounts are filtered out. `walletId` narrows it further, for whenever a wallet-scoped event exists — no event carries a wallet scope today, so on its own it changes only which events close the stream.",
+      "params": {
+        "sessionId": {
+          "pass": "[--session-id=<sessionId>]",
+          "doc": "Scope the stream to one account, so a logout closes it. Omitted, the stream is context-scoped and only the engine stopping ends it.",
+          "optional": true
+        },
+        "walletId": {
+          "pass": "[--wallet-id=<walletId>]",
+          "doc": "With `sessionId`, narrow the stream to one wallet. No event carries a wallet scope yet, so today this only narrows which events can close the stream. Ignored on its own.",
+          "optional": true
+        },
+        "type": {
+          "pass": "--type=<value>",
+          "doc": "Only these event types. Applied by the engine, so an unwanted type never crosses the socket; the client filters again for the types the engine sends regardless, like `subscription.closed`.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "type": "string — The event name.",
+        "data": "unknown — Payload, shaped by the event type."
+      },
+      "returnsDoc": "One frame per event, as `event:` then `data:` lines.",
+      "notes": [
+        "Frame types: `core.log`, `session.created`, `session.expired`, `engine.shutdown`, and `subscription.closed` when the engine ends it.",
+        "The `subscribe` command prints one further frame of its own once the stream is over, `subscription.ended`, carrying the close reason. It comes from the client, so `--type` does not filter it.",
+        "`sessionId` in event payloads is truncated to its first 10 characters.",
+        "A client more than 1 MiB behind is disconnected rather than buffered.",
+        "Served directly by the HTTP handler rather than through the router, because the response never ends.",
+        "Prints newline-delimited JSON and runs until interrupted. Exits 0 on SIGINT and 7 when the engine ends the stream. `subscribe` opens an unscoped stream, which only the engine stopping ends; a stream opened with `sessionId` is closed by that session logging out."
+      ]
+    },
+    "swap-quote-get": {
+      "summary": "Re-read a quote.",
+      "method": "GET",
+      "path": "/account/{sessionId}/swap-quote/{objectId}",
+      "usage": "swap-quote-get <objectId>",
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "pluginId": "string — Swap provider that produced this quote.",
+        "isEstimate": "boolean — True when the provider may settle at a different rate than quoted.",
+        "canBePartial": "boolean | null — True when the provider may fill only part of the order. Null when it does not say.",
+        "maxFulfillmentSeconds": "number | null — Longest the provider expects a partial fill to take.",
+        "minReceiveAmount": "string | null — Least the provider guarantees to deliver, in the destination’s native units.",
+        "fromNativeAmount": "string — Amount leaving the source wallet.",
+        "toNativeAmount": "string — Amount arriving in the destination wallet.",
+        "networkFee": "{ nativeAmount: string; tokenId: string | null; } — On-chain fee for the sending transaction. It is not the provider’s own spread, which is already in the rate.",
+        "quoteExpirationDate": "string | null — When the provider stops honouring the rate. Null when it does not expire.",
+        "swapInfo": "{ pluginId: string; displayName: string; supportEmail: string; isDex: boolean | null; } — `EdgeSwapInfo`: how to name the provider and where to send complaints.",
+        "request": "{ fromTokenId: string | null; toTokenId: string | null; nativeAmount: string; quoteFor: \"from\" | \"to\" | \"max\"; fromWalletId: string; toWalletId: string; } — The `EdgeSwapRequest` this quote answers, echoed back so quotes from different plugins can be compared without tracking what was asked."
+      },
+      "notes": [
+        "Check `quoteExpirationDate` as well as `expiresAt`: the plugin's price can go stale before the handle does."
+      ],
+      "errors": [
+        "OBJECT_NOT_FOUND",
+        "OBJECT_EXPIRED",
+        "OBJECT_KIND_MISMATCH",
+        "OBJECT_SESSION_MISMATCH",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "sweep-private-keys": {
+      "summary": "Sweep private keys into this wallet.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/sweep-private-keys",
+      "usage": "sweep-private-keys --wallet-id=<walletId> --spend-info='<json>'",
+      "description": "Builds a transaction moving everything from an external key. Returns an unsigned handle: sign, broadcast and save it like any staged spend.",
+      "core": "wallet.sweepPrivateKeys",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        },
+        "spendInfo": {
+          "pass": "--spend-info='<json>'",
+          "doc": "The keys to sweep in `privateKeys`, plus the optional `spendTargets`, `tokenId`, `metadata` and `memos` of a spend.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
+        "kind": "string — What the handle refers to, which decides the calls that accept it.",
+        "expiresAt": "string — When the engine drops the handle. Handles live 5 minutes.",
+        "sessionId?": "string — Session that created the handle; only that session may use it.",
+        "walletId?": "string — Wallet the handle is bound to, when it belongs to one.",
+        "transaction": "unknown — `EdgeTransaction` as it stands after this step. Unsigned after `make-spend`, signed after `sign-tx`, and carrying a txid once broadcast."
+      },
+      "errors": [
+        "BAD_REQUEST",
+        "INSUFFICIENT_FUNDS",
+        "NETWORK_ERROR",
+        "TOKEN_NOT_FOUND",
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "sync": {
+      "summary": "Force an account data sync.",
+      "method": "POST",
+      "path": "/account/{sessionId}/sync",
+      "usage": "sync",
+      "description": "Pushes and pulls the account repos immediately rather than waiting for the next scheduled sync.",
+      "core": "account.sync",
+      "notes": [
+        "Named `sync` for the account; the wallet one is `wallet-sync`."
+      ],
+      "errors": [
+        "NETWORK_ERROR",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "touch": {
+      "summary": "Keepalive.",
+      "method": "POST",
+      "path": "/account/{sessionId}/touch",
+      "usage": "touch",
+      "description": "Resets the idle auto-logout timer without doing any other work.",
+      "returns": {
+        "sessionId": "string — Identifies this login. Every account-scoped call carries it, and the CLI stores the most recent one so commands can omit it.",
+        "username?": "string — Absent for a light account, which has no username.",
+        "rootLoginId": "string — The account root, stable across appIds. Two sessions sharing it are the same account.",
+        "loginMethod": "\"create\" | \"edge\" | \"key\" | \"password\" | \"pin\" | \"recovery\" — How this session was established.",
+        "autoLogoutSeconds": "number — Idle time before the engine logs the account out. 0 disables it.",
+        "expiresAt": "string | null — When auto-logout will fire, or null when it is disabled.",
+        "lastActivityAt": "string — Last call on this session, which is what auto-logout measures from.",
+        "createdAt": "string — When the login completed."
+      },
+      "returnsDoc": "The session, with a refreshed `expiresAt`.",
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "username-available": {
+      "summary": "Check whether a username is free.",
+      "method": "GET",
+      "path": "/username-available",
+      "usage": "username-available --username=<username> [--challenge-id=<challengeId>]",
+      "core": "context.usernameAvailable",
+      "params": {
+        "username": {
+          "pass": "--username=<username>",
+          "doc": "The name to check.",
+          "optional": false
+        },
+        "challengeId": {
+          "pass": "[--challenge-id=<challengeId>]",
+          "doc": "Supply after solving a CAPTCHA to retry the same check.",
+          "optional": true
+        }
+      },
+      "returns": {
+        "username": "string — The name that was checked, echoed back.",
+        "available": "boolean — True when nobody holds this name. It is not reserved by asking."
+      },
+      "errors": [
+        "USERNAME_ERROR",
+        "CHALLENGE_REQUIRED",
+        "NETWORK_ERROR"
+      ]
+    },
+    "wait-for-all-wallets": {
+      "summary": "Wait for every wallet to finish loading.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wait-for-all-wallets",
+      "usage": "wait-for-all-wallets",
+      "description": "Wallets load in the background after login, so a list taken straight afterwards can be short. This resolves once each active wallet has either loaded or failed — balances may still be syncing afterwards.",
+      "core": "account.waitForAllWallets",
+      "notes": [
+        "There is no timeout: a wallet that never resolves holds this open. The engine's own idle shutdown does not fire while a request is in flight, so give the client one.",
+        "Nothing is returned. Call `currency-wallets` afterwards to see the result, including any wallet that failed to load."
+      ],
+      "errors": [
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "wallet-info": {
+      "summary": "Wallet detail.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet",
+      "usage": "wallet-info --wallet-id=<walletId>",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returnsDoc": "Every WalletSummary field, plus denominations and walletSettings. `allTokens` is not here — `wallet-tokens` exists to carry it, and returning it from both sent the same map twice in a session that calls both.",
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "wallet-sync": {
+      "summary": "Nudge one wallet to sync.",
+      "method": "POST",
+      "path": "/account/{sessionId}/wallet/sync",
+      "usage": "wallet-sync --wallet-id=<walletId>",
+      "core": "wallet.sync",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "notes": [
+        "Named `wallet-sync` on the CLI because `sync` is `account.sync`."
+      ],
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    },
+    "wallet-tokens": {
+      "summary": "List a wallet's tokens.",
+      "method": "GET",
+      "path": "/account/{sessionId}/wallet/tokens",
+      "usage": "wallet-tokens --wallet-id=<walletId>",
+      "description": "\"Enabled\" tokens are the ones the wallet syncs balances for; \"detected\" ones were seen on-chain but are not yet enabled.",
+      "params": {
+        "walletId": {
+          "pass": "--wallet-id=<walletId>",
+          "doc": "The wallet to act on. A full wallet id, or any unique prefix of one. An ambiguous prefix returns `409 AMBIGUOUS_WALLET_ID` with `details.candidates`.",
+          "optional": false
+        }
+      },
+      "returns": {
+        "allTokens": "{ [keys: string]: unknown; } — `EdgeToken` by tokenId: everything the plugin ships with, plus this account’s own. `builtinTokens` is not returned separately — it is this map minus `customTokens`, and sending both wrote the whole built-in list down the socket twice.",
+        "customTokens": "{ [keys: string]: unknown; } — `EdgeToken` by tokenId: tokens this account added by hand.",
+        "enabledTokenIds": "string[] — Which of the above the wallet is actually tracking.",
+        "detectedTokenIds": "string[] — Seen on-chain but not enabled, so their balances are not synced."
+      },
+      "errors": [
+        "WALLET_NOT_FOUND",
+        "AMBIGUOUS_WALLET_ID",
+        "INVALID_SESSION",
+        "SESSION_EXPIRED"
+      ]
+    }
+  }
+}
diff --git a/src/cli/generatedSchemas.ts b/src/cli/generatedSchemas.ts
new file mode 100644
index 00000000000..c2cbb58a814
--- /dev/null
+++ b/src/cli/generatedSchemas.ts
@@ -0,0 +1,127 @@
+/**
+ * Cleaners for the files `scripts/build*` generate into `src/cli/generated/`.
+ *
+ * One declaration per file, imported by both the writer and the reader. Each
+ * shape used to be hand-declared twice with a cast bridging the gap, and the
+ * cast was load-bearing: `resolveJsonModule` already infers a literal type
+ * for the import, so `table as { commands: CommandSpec[] }` is what
+ * *suppressed* the check — a `kind` the JSON carries but `ArgSpec['kind']`
+ * does not was accepted silently and `flagKind` fell through to `'string'`.
+ * The copies had already drifted: `buildCliHelp`'s `ParamHelp` declared a
+ * `restOnly` that nothing ever set and that appears zero times in the
+ * generated JSON.
+ */
+import {
+  asArray,
+  asBoolean,
+  asEither,
+  asJSON,
+  asNull,
+  asObject,
+  asOptional,
+  asString,
+  asValue
+} from 'cleaners'
+
+/** How one parameter is passed on the command line. */
+export const asParamHelp = asObject({
+  /** How to supply it on the command line, or null when REST-only. */
+  pass: asEither(asString, asNull),
+  doc: asOptional(asString),
+  optional: asOptional(asBoolean)
+})
+
+export const asCommandHelp = asObject({
+  summary: asString,
+  description: asOptional(asString),
+  core: asOptional(asString),
+  method: asString,
+  path: asString,
+  usage: asString,
+  /** Further usage lines, when two routes share this command name. */
+  alsoUsage: asOptional(asArray(asString)),
+  /** Further REST routes, when two routes share this command name. */
+  alsoRest: asOptional(asArray(asString)),
+  params: asOptional(asObject(asParamHelp)),
+  returns: asOptional(asObject(asString)),
+  returnsDoc: asOptional(asString),
+  notes: asOptional(asArray(asString)),
+  errors: asOptional(asArray(asString))
+})
+
+export const asHelpDocs = asObject({
+  commands: asObject(asCommandHelp)
+}).withRest
+
+/** The flag kinds `commandArgs` knows how to parse. */
+export const asArgKind = asValue<
+  Array<'string' | 'boolean' | 'boolstr' | 'repeat' | 'json'>
+>('string', 'boolean', 'boolstr', 'repeat', 'json')
+
+export const asArgSpec = asObject({
+  flag: asOptional(asString),
+  field: asString,
+  target: asValue<Array<'query' | 'body'>>('query', 'body'),
+  kind: asArgKind,
+  required: asBoolean
+})
+
+export const asCommandSpec = asObject({
+  command: asString,
+  method: asString,
+  path: asString,
+  usage: asString,
+  help: asString,
+  needsSession: asBoolean,
+  pathPositional: asOptional(asString),
+  args: asArray(asArgSpec),
+  bodyFlag: asOptional(asString),
+  preset: asOptional(asObject(asBoolean))
+})
+
+export const asCommandsTable = asObject({
+  commands: asArray(asCommandSpec)
+}).withRest
+
+/**
+ * The same table, read straight from the file.
+ *
+ * `asJSON`, so one cleaner owns both the parse and the shape: the two gates
+ * that read `commands.json` each had their own hand-written interface and a
+ * cast, which is the drift a gate exists to notice — and a cast suppresses
+ * the check in the one place that is supposed to make it.
+ */
+export const asCommandsTableJson = asJSON(asCommandsTable)
+
+export type ParamHelp = ReturnType<typeof asParamHelp>
+export type CommandHelp = ReturnType<typeof asCommandHelp>
+export type ArgSpec = ReturnType<typeof asArgSpec>
+export type CommandSpec = ReturnType<typeof asCommandSpec>
+
+/**
+ * The same shape, with every `asOptional` key genuinely optional.
+ *
+ * A cleaner's output type lists those keys as `T | undefined`, which is right
+ * for a *reader* — the key is always there — but a writer building an object
+ * literal cannot satisfy it by omission. These are the writer-facing types,
+ * so the generators and the CLI still share one declaration.
+ */
+type Optionalize<T> = {
+  [K in keyof T as undefined extends T[K] ? never : K]: T[K]
+} & {
+  [K in keyof T as undefined extends T[K] ? K : never]?: T[K]
+}
+
+export type ParamHelpInput = Optionalize<ParamHelp>
+
+// `Optionalize` is shallow, so the nested shapes are re-stated in their own
+// writer form.
+export type CommandHelpInput = Omit<Optionalize<CommandHelp>, 'params'> & {
+  params?: Record<string, ParamHelpInput>
+}
+
+export type ArgSpecInput = Optionalize<ArgSpec>
+
+export type CommandSpecInput = Omit<Optionalize<CommandSpec>, 'args'> & {
+  args: ArgSpecInput[]
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
new file mode 100644
index 00000000000..3f341a38a89
--- /dev/null
+++ b/src/cli/index.ts
@@ -0,0 +1,442 @@
+/**
+ * The `edge-cli` client: argv in, JSON out.
+ *
+ * One process per command by default. It parses the global flags, resolves
+ * the profile — a pure hash, so it needs no engine — builds the context a
+ * command runs with, and lets `ApiClient` start the daemon on the first
+ * request that finds nothing listening. Deferring the spawn that far means a
+ * command that fails while parsing its own flags leaves no daemon behind.
+ *
+ * With no command it reads commands from stdin instead, one per line, over
+ * the same context: the engine, the session and the flags are the same as
+ * one-shot mode, which is only true because the prompt is handed the context
+ * itself rather than a copy of it.
+ *
+ * Nothing here imports `edge-core-js`. The engine owns core; this half owns
+ * argv, the socket and the output.
+ */
+import './bootNodeLocale'
+import './commands/all'
+
+import parse from 'lib-cmdparse'
+import { red } from 'nanocolors'
+import readline from 'readline'
+
+import { ApiClient, ApiClientError } from './client/apiClient'
+import { EXIT, printError } from './client/output'
+import {
+  clearSessionFile,
+  readSessionFile,
+  writeSessionFile
+} from './client/sessionFile'
+import { solveChallenge } from './client/solveCaptcha'
+import { ensureEngine, warnIfEngineLocaleDiffers } from './client/spawnEngine'
+import { readSession } from './clientResponses'
+import {
+  type CliContext,
+  type Command,
+  findCommand,
+  listCommands,
+  UsageError
+} from './command'
+import { defaultDirectory, loadConfig } from './engine/cliConfig'
+import { profileHash, socketPathFor } from './engine/discovery'
+import { parseTcpPort } from './engine/tcpPort'
+import { TESTER_SERVERS } from './engine/testerServers'
+import { type CliOptions, parseCliArgs, showCliHelp } from './parseArgs'
+
+function formatUsage(cmd: {
+  name: string
+  usage?: string
+  needsSession?: boolean
+}): string {
+  // Every usage string starts with its own command name — `docs:api:verify`
+  // enforces that — so prepending the name again would print it twice.
+  const body = cmd.usage ?? cmd.name
+  let out = `Usage: edge-cli ${body}`
+  if (cmd.needsSession === true) out += ' [--session <id>]'
+  return out
+}
+
+/**
+ * The `--tcp` port, validated here rather than forwarded.
+ *
+ * The shared validator, reported the way the client reports bad argv:
+ * `Number('abc')` is `NaN`, which reached the engine as `--tcp=NaN` and cost
+ * the caller a 30-second spawn timeout followed by the engine's stack inside
+ * the error envelope.
+ */
+/**
+ * `--timeout=<seconds>`, as milliseconds.
+ *
+ * On expiry the client destroys its socket while the engine runs the request
+ * to completion, so a caller needs to be able to ask for longer — the
+ * documented "Expensive" routes and a whole-wallet `get-transactions` can
+ * outrun the default, and for `broadcast-tx` the report would be a failure
+ * after the funds had left.
+ */
+function clientTimeoutMs(raw: string | undefined): number | undefined {
+  if (raw == null) return undefined
+  const seconds = Number(raw)
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new UsageError(
+      undefined,
+      `Invalid --timeout "${raw}": expected a positive number of seconds`
+    )
+  }
+  return seconds * 1000
+}
+
+function clientTcpPort(raw: string | undefined): number | null {
+  try {
+    return parseTcpPort(raw)
+  } catch (error: unknown) {
+    throw new UsageError(
+      undefined,
+      error instanceof Error ? error.message : String(error)
+    )
+  }
+}
+
+/**
+ * `CliOptions` itself, not a copy of nine of its fields.
+ *
+ * The inline shape had to be edited alongside `CliOptions` for every new
+ * global flag, and a field left out of it is simply invisible here.
+ */
+async function buildContext(options: CliOptions): Promise<CliContext> {
+  const fileConfig = loadConfig(options.config)
+  const appId = options['app-id'] ?? fileConfig.appId ?? ''
+  const directory =
+    options.directory ??
+    fileConfig.directory ??
+    fileConfig.workingDir ??
+    defaultDirectory()
+  const testMode = options.test === true || fileConfig.testMode === true
+  // The *explicit* key only. A key from the config file is left to the
+  // engine, which reads the same file: forwarding it made `makeCoreContext`
+  // read it as an operator override and silently turn off HMAC request
+  // signing and the native signer.
+  const apiKey = options['api-key']
+
+  const fake = options.fake === true
+  // From the same constant the engine derives it from. The profile hash must
+  // match on both sides or the client spawns an engine under one profile and
+  // then polls a socket under another — a 30-second "Timed out waiting for
+  // engine to start" with a healthy engine running — so this is load-bearing,
+  // not cosmetic.
+  const loginServer = fake
+    ? 'fake://login'
+    : testMode
+    ? TESTER_SERVERS.loginServer
+    : undefined
+  const engineOpts = {
+    appId,
+    directory,
+    testMode,
+    fake,
+    apiKey,
+    configPath: options.config,
+    noSpawn: options['no-spawn'] === true,
+    tcpPort: clientTcpPort(options.tcp),
+    loginServer
+  }
+
+  // The profile is a pure hash of these four, so it needs no engine. Defer the
+  // spawn to the first request: a command that fails while parsing its own
+  // flags, or because it needs a session there isn't one for, then leaves no
+  // daemon behind — and with no `-t` that daemon would point at production.
+  const profile = profileHash({ appId, directory, testMode, loginServer })
+  const client = new ApiClient({
+    socketPath: socketPathFor(profile),
+    timeoutMs: clientTimeoutMs(options.timeout),
+    onConnectFail: async () => {
+      await ensureEngine(engineOpts)
+    },
+    // The one place the locale mismatch is reported. It needs a live engine,
+    // so it rides on the first request that reaches one rather than on
+    // building the context, which would spawn an engine for a command that
+    // never runs.
+    onFirstResponse: warnIfEngineLocaleDiffers
+  })
+
+  const envSession = process.env.EDGE_CLI_SESSION
+  const fileSession = readSessionFile(profile)
+
+  const ctx: CliContext = {
+    client,
+    profile,
+    // The field is the one copy. A closure variable beside it was only ever
+    // written, never read, which read as if it were the source of truth.
+    sessionId: options.session ?? envSession ?? fileSession?.sessionId ?? null,
+    testMode,
+    setSessionId(id, username) {
+      ctx.sessionId = id
+      if (id == null) clearSessionFile(profile)
+      else writeSessionFile(profile, id, username)
+    }
+  }
+  return ctx
+}
+
+async function maybeSolveAndRetry<T>(
+  solve: boolean,
+  run: (challengeId?: string) => Promise<T>
+): Promise<T> {
+  try {
+    return await run()
+  } catch (error: unknown) {
+    if (
+      !solve ||
+      !(error instanceof ApiClientError) ||
+      error.code !== 'CHALLENGE_REQUIRED' ||
+      error.details == null
+    ) {
+      throw error
+    }
+    const challengeId = await solveChallenge({
+      challengeId: String(error.details.challengeId),
+      challengeUri:
+        typeof error.details.challengeUri === 'string'
+          ? error.details.challengeUri
+          : undefined
+    })
+    return await run(challengeId)
+  }
+}
+
+async function runPrompt(
+  ctx: CliContext,
+  solveCaptcha: boolean
+): Promise<number> {
+  const interactive = process.stdin.isTTY
+  if (interactive) {
+    console.log('Use the `help` command for usage information')
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: interactive ? '> ' : '',
+    completer(line: string) {
+      const commands = listCommands()
+      const match = commands.filter(c => c.startsWith(line))
+      return [match.length > 0 ? match : commands, line]
+    }
+  })
+  if (interactive) rl.prompt()
+
+  let worst: number = EXIT.OK
+
+  // `for await` runs one line at a time and ends at EOF, so a piped script
+  // reaches its last command. Asking for lines one at a time and resolving on
+  // `close` dropped everything after the first, because EOF arrived while the
+  // first command was still awaiting.
+  for await (const text of rl) {
+    const trimmed = text.trim()
+    if (trimmed === 'exit' || trimmed === 'quit') break
+    try {
+      const parsed = parse(text)
+      if (parsed.exec != null) {
+        const cmd = findCommand(parsed.exec)
+        if (cmd.needsSession === true && ctx.sessionId == null) {
+          throw new UsageError(cmd, 'Please log in first')
+        }
+        await invokeCommand(ctx, cmd, parsed.args, solveCaptcha)
+      }
+    } catch (error: unknown) {
+      if (error instanceof UsageError) {
+        console.error(red(error.message))
+        if (error.command != null) console.error(formatUsage(error.command))
+        worst = worst === EXIT.OK ? EXIT.USAGE : worst
+      } else {
+        // The worst code any command produced, so a piped chain fails the way
+        // the same commands would one-shot. This loop exists so that a piped
+        // script reaches its last command, and discarding `printError`'s
+        // return made the documented exit-code table unobservable in exactly
+        // that mode.
+        const code = printError(error)
+        if (code !== EXIT.OK) worst = code
+      }
+    }
+    if (interactive) rl.prompt()
+  }
+  rl.close()
+  return worst
+}
+
+/**
+ * Run a command, solving a CAPTCHA and retrying once when asked to.
+ *
+ * Keyed off the thrown error rather than a list of command names, so the flag
+ * works for every command a challenge can reach and cannot rot as commands are
+ * renamed. Shared by one-shot mode and the prompt, which the guide says behave
+ * the same.
+ */
+/**
+ * A session the engine has thrown away must not be sent again.
+ *
+ * `session.json` is removed when the *engine* stops, which an auto-logout
+ * does not do, so without this every later invocation re-read the dead bearer
+ * token off disk and failed 401 indefinitely — and in the prompt the
+ * `needsSession` guard kept passing, so an account command reported
+ * `INVALID_SESSION` rather than "Please log in first".
+ */
+function forgetDeadSession(ctx: CliContext, error: unknown): void {
+  if (!(error instanceof ApiClientError)) return
+  if (error.code !== 'INVALID_SESSION' && error.code !== 'SESSION_EXPIRED') {
+    return
+  }
+  if (ctx.sessionId == null) return
+  ctx.setSessionId(null)
+}
+
+async function invokeCommand(
+  ctx: CliContext,
+  cmd: Command,
+  argv: string[],
+  solveCaptcha: boolean
+): Promise<void> {
+  try {
+    // Through `maybeSolveAndRetry`, which already encapsulates "on
+    // CHALLENGE_REQUIRED, solve and retry once". This re-implemented it
+    // inline, including a verbatim copy of the `solveChallenge({ … })` block.
+    await maybeSolveAndRetry(solveCaptcha, async challengeId => {
+      ctx.challengeId = challengeId
+      try {
+        await cmd.invoke(ctx, argv)
+      } finally {
+        // A challenge id is single-use. In the prompt the context outlives
+        // the command, so leaving it set made every later login send an
+        // already-consumed id that the login server has to reject before a
+        // fresh one can be solved.
+        ctx.challengeId = undefined
+      }
+    })
+  } catch (error: unknown) {
+    forgetDeadSession(ctx, error)
+    throw error
+  }
+}
+
+async function main(): Promise<number> {
+  const { argv, options } = parseCliArgs(process.argv.slice(2))
+
+  if (options.help === true && argv.length === 0) {
+    showCliHelp()
+    console.log('Commands:')
+    for (const name of listCommands()) console.log(`  ${name}`)
+    return EXIT.OK
+  }
+
+  // `help` is answered from the committed help table, so it must not build a
+  // context: that auto-spawns an engine, and without `-t` the daemon it leaves
+  // running points at production.
+  const wantsHelp = options.help === true || argv[0] === 'help'
+  if (wantsHelp) {
+    const helpCmd = findCommand('help')
+    await helpCmd.invoke(
+      {
+        client: null as never,
+        profile: '',
+        sessionId: null,
+        setSessionId: () => {},
+        testMode: false
+      },
+      argv[0] === 'help' ? argv.slice(1) : argv
+    )
+    return EXIT.OK
+  }
+
+  // Resolve the command before building a context. `buildContext` auto-spawns
+  // the engine, so validating the name afterwards meant a typo left a daemon
+  // running — and with no `-t`, a production daemon on the default data
+  // directory. A command that does not exist never needs an engine.
+  const name = argv.length > 0 ? argv[0] : null
+  const cmd = name != null ? findCommand(name) : null
+  if (cmd != null) argv.shift()
+
+  const ctx = await buildContext(options)
+  const solveCaptcha = options['solve-captcha'] === true
+
+  if (cmd == null) {
+    // The context itself, not a spread copy. `setSessionId` is a method on
+    // the object literal `buildContext` built and assigns to *that* object,
+    // so a copy read its own boot-time `sessionId` forever: a login inside
+    // the prompt stored the id on the original and in `session.json` while
+    // the prompt's `needsSession` guard still saw null, so the next account
+    // command died with "Please log in first" on an account that was logged
+    // in — and `forgetDeadSession` cleared the original while the copy kept
+    // the dead id, so a 401 repeated for the life of the prompt.
+    ctx.interactive = true
+    return await runPrompt(ctx, solveCaptcha)
+  }
+
+  if (cmd.needsSession === true && ctx.sessionId == null) {
+    // Legacy helper: -u/-p auto password-login
+    if (options.username != null && options.password != null) {
+      const session = await maybeSolveAndRetry(
+        solveCaptcha,
+        async challengeId =>
+          // Cleaned, not an inline shape: this is the fourth place the
+          // session was declared by hand, and the `sessionId` it reads is
+          // what `setSessionId` writes to the 0600 session file.
+          readSession(
+            await ctx.client.post('/login-with-password', {
+              username: options.username,
+              password: options.password,
+              challengeId
+            }),
+            'login-with-password'
+          )
+      )
+      ctx.setSessionId(session.sessionId, session.username)
+    } else {
+      throw new UsageError(cmd, 'Please log in first (no sessionId)')
+    }
+  }
+
+  await invokeCommand(ctx, cmd, argv, solveCaptcha)
+
+  return EXIT.OK
+}
+
+main()
+  .then(code => {
+    // `process.exitCode` rather than `process.exit`: stdout writes are async
+    // on a pipe, and the documented usage pipes into jq, so `process.exit`
+    // truncated the largest responses at the pipe buffer. `wallet-tokens` is
+    // the biggest of them — tens of KB on an EVM chain, not the megabytes an
+    // earlier version of this comment claimed; the truncation is about the
+    // 64KB pipe buffer, not about megabytes.
+    //
+    // A command that set its own code keeps it: `subscribe` reports why the
+    // stream ended and still resolves normally, so an unconditional
+    // assignment here would overwrite that with 0.
+    if (code !== EXIT.OK) process.exitCode = code
+    else process.exitCode ??= code
+  })
+  .catch((error: unknown) => {
+    if (error instanceof UsageError) {
+      console.error(
+        JSON.stringify(
+          {
+            error: {
+              code: 'USAGE',
+              message: error.message,
+              status: 400
+            }
+          },
+          null,
+          2
+        )
+      )
+      // The prompt prints the usage line on a usage error; one-shot mode did
+      // not, so a reader got "Incorrect arguments" with no hint which flag was
+      // wrong. Usage goes to stderr, keeping stdout machine-readable.
+      if (error.command != null) console.error(formatUsage(error.command))
+      process.exitCode = EXIT.USAGE
+      return
+    }
+    const code = printError(error)
+    process.exitCode = code
+  })
diff --git a/src/cli/parseArgs.ts b/src/cli/parseArgs.ts
new file mode 100644
index 00000000000..3fb4d945d68
--- /dev/null
+++ b/src/cli/parseArgs.ts
@@ -0,0 +1,210 @@
+/**
+ * Minimal argv parser replacing node-getopt (which emits DEP0128 because its
+ * package.json has `"main": "./lib"` instead of a file path).
+ */
+import { hasCommand, UsageError } from './command'
+import { EXAMPLE_TCP_PORT, parseTcpPort } from './engine/tcpPort'
+import { renderFlagHelp } from './flagTable'
+
+export interface CliOptions {
+  'api-key'?: string
+  'app-id'?: string
+  config?: string
+  directory?: string
+  username?: string
+  password?: string
+  test?: boolean
+  fake?: boolean
+  session?: string
+  'no-spawn'?: boolean
+  'solve-captcha'?: boolean
+  tcp?: string
+  timeout?: string
+  help?: boolean
+}
+
+export interface ParsedArgs {
+  options: CliOptions
+  argv: string[]
+}
+
+const HELP_TEXT = `Usage: edge-cli [options] [command] [args...]
+
+Options:
+${renderFlagHelp('client')}
+`
+
+function takeValue(
+  argv: string[],
+  i: number,
+  flag: string
+): { value: string; next: number } {
+  const cur = argv[i]
+  const eq = cur.indexOf('=')
+  if (eq !== -1) {
+    const value = cur.slice(eq + 1)
+    // `--directory=` is not a directory. The client and the engine both hash
+    // the profile from it, so an empty one on this side and a default on the
+    // other are two different engines.
+    if (value === '') {
+      throw new UsageError(undefined, `Missing value for ${flag}`)
+    }
+    return { value, next: i }
+  }
+  const next = argv[i + 1]
+  // `''` as well as absent: `-d ""` is the same forgotten value as
+  // `--directory=`, and it reached the profile hash as an empty directory
+  // while the engine used its default — two different engines, and a
+  // 30-second spawn timeout with a healthy engine running. The `=` form
+  // already refused it; the space form did not.
+  if (next == null || next === '' || next.startsWith('-')) {
+    throw new UsageError(undefined, `Missing value for ${flag}`)
+  }
+  // `edge-cli --directory balance-map` means a forgotten value, not a
+  // directory called `balance-map`: taking it silently swallowed the command
+  // and dropped the caller into the interactive prompt with exit 0.
+  if (hasCommand(next)) {
+    throw new UsageError(
+      undefined,
+      `Missing value for ${flag}: "${next}" is a command. Write ${flag}=<value>.`
+    )
+  }
+  return { value: next, next: i + 1 }
+}
+
+export function parseCliArgs(argv: string[]): ParsedArgs {
+  const options: CliOptions = {}
+  const positional: string[] = []
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+
+    if (a === '--') {
+      positional.push(...argv.slice(i + 1))
+      break
+    }
+
+    if (a === '-h' || a === '--help') {
+      options.help = true
+      continue
+    }
+    if (a === '-t' || a === '--test') {
+      options.test = true
+      continue
+    }
+    if (a === '--fake') {
+      options.fake = true
+      continue
+    }
+    if (a === '--no-spawn') {
+      options['no-spawn'] = true
+      continue
+    }
+    if (a === '--solve-captcha') {
+      options['solve-captcha'] = true
+      continue
+    }
+
+    if (a === '-k' || a === '--api-key' || a.startsWith('--api-key=')) {
+      const { value, next } = takeValue(argv, i, '--api-key')
+      options['api-key'] = value
+      i = next
+      continue
+    }
+    if (a === '-a' || a === '--app-id' || a.startsWith('--app-id=')) {
+      const { value, next } = takeValue(argv, i, '--app-id')
+      options['app-id'] = value
+      i = next
+      continue
+    }
+    if (a === '-c' || a === '--config' || a.startsWith('--config=')) {
+      const { value, next } = takeValue(argv, i, '--config')
+      options.config = value
+      i = next
+      continue
+    }
+    if (a === '-d' || a === '--directory' || a.startsWith('--directory=')) {
+      const { value, next } = takeValue(argv, i, '--directory')
+      options.directory = value
+      i = next
+      continue
+    }
+    if (a === '-u' || a === '--username' || a.startsWith('--username=')) {
+      const { value, next } = takeValue(argv, i, '--username')
+      options.username = value
+      i = next
+      continue
+    }
+    if (a === '-p' || a === '--password' || a.startsWith('--password=')) {
+      const { value, next } = takeValue(argv, i, '--password')
+      options.password = value
+      i = next
+      continue
+    }
+    if (a === '--session' || a.startsWith('--session=')) {
+      const { value, next } = takeValue(argv, i, '--session')
+      options.session = value
+      i = next
+      continue
+    }
+    if (a === '--locale' || a.startsWith('--locale=')) {
+      // Consumed so it is not an unknown option, and *not* recorded:
+      // `detectNodeLocale` reads argv itself, from `bootNodeLocale`, which
+      // runs before this parser. A field here would be written and never
+      // read.
+      const { next } = takeValue(argv, i, '--locale')
+      i = next
+      continue
+    }
+    if (a === '--tcp' || a.startsWith('--tcp=')) {
+      if (a === '--tcp') {
+        throw new UsageError(
+          undefined,
+          `--tcp requires a port, e.g. --tcp=${EXAMPLE_TCP_PORT}`
+        )
+      }
+      // Validated here, where every other bad flag is reported, rather than
+      // only when `buildContext` converts it: `--tcp=` stored an empty
+      // string that silently meant "no listener" on one side of the parse
+      // and bad argv on the other.
+      const raw = a.slice('--tcp='.length)
+      try {
+        parseTcpPort(raw)
+      } catch (error: unknown) {
+        throw new UsageError(
+          undefined,
+          error instanceof Error ? error.message : String(error)
+        )
+      }
+      options.tcp = raw
+      continue
+    }
+    if (a === '--timeout' || a.startsWith('--timeout=')) {
+      const { value, next } = takeValue(argv, i, '--timeout')
+      options.timeout = value
+      i = next
+      continue
+    }
+
+    if (a.startsWith('-')) {
+      // Always: every other path that fills `positional` breaks out of the
+      // loop, so nothing can reach here with one already collected. The
+      // branch this replaces claimed to handle a command-local flag after
+      // the command name, which the `argv.slice(i + 1)` below has already
+      // swallowed by then.
+      throw new UsageError(undefined, `Unknown option: ${a}`)
+    }
+
+    // First non-option is the command name; remaining args (including
+    // flags) belong to the command.
+    positional.push(a)
+    positional.push(...argv.slice(i + 1))
+    break
+  }
+
+  return { options, argv: positional }
+}
+
+export function showCliHelp(): void {
+  console.log(HELP_TEXT)
+}
diff --git a/src/util/CurrencyInfoHelpers.ts b/src/util/CurrencyInfoHelpers.ts
index d3f4327fd14..6ebac911a76 100644
--- a/src/util/CurrencyInfoHelpers.ts
+++ b/src/util/CurrencyInfoHelpers.ts
@@ -1,3 +1,6 @@
+// Re-exported from the Node-safe module that owns it: the GUI and the CLI feed
+// the same user-visible subcategory string from this, so two implementations
+// is one divergence away from describing a transaction two ways.
 import type {
   EdgeAccount,
   EdgeCurrencyConfig,
@@ -17,6 +20,7 @@ import {
 } from '../constants/WalletAndCurrencyConstants'
 import type { EdgeAsset } from '../types/types'
 import { asMaybeContractLocation } from './cleaners'
+export { getCurrencyCodeWithAccount } from './txDisplay/currencyCodes'
 
 /**
  * Returns true if this currency supports existing wallets,
@@ -127,32 +131,6 @@ export const getCurrencyCode = (
   }
 }
 
-/**
- * Get the currencyCode associated with a tokenId
- */
-export const getCurrencyCodeWithAccount = (
-  account: EdgeAccount,
-  pluginId: string,
-  tokenId: EdgeTokenId
-): string | undefined => {
-  if (account.currencyConfig[pluginId] == null) {
-    return
-  }
-
-  if (tokenId == null) {
-    return account.currencyConfig[pluginId].currencyInfo.currencyCode
-  } else {
-    if (account.currencyConfig[pluginId].allTokens[tokenId] == null) {
-      // Fail gracefully if we don't have the token for some reason
-      console.warn(
-        `getCurrencyCodeWithAccount: tokenId: '${tokenId}' not found for pluginId: '${pluginId}'`
-      )
-      return ''
-    }
-    return account.currencyConfig[pluginId].allTokens[tokenId].currencyCode
-  }
-}
-
 export const getToken = (
   wallet: EdgeCurrencyWallet,
   tokenId: EdgeTokenId

From 63a5b9538b6e5df09235083c73b75df0fb5a7ec2 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 10:56:09 -0700
Subject: [PATCH 11/24] Implement the remaining Edge CLI endpoints
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Account and session management, credentials, 2FA and vouchers, the data
store, keys and wallets, tokens, URIs, transactions and their export,
the staged spend path, swaps, exchange rates, and the `$internalStuff`
admin calls — a hundred and four `route({…})` declarations, each
carrying its own cleaners, error list and prose.

The five documentation gates hold across every one of them: the surface
matches, each response field carries prose, each call either matches its
`edge-core-js` signature or records why it differs, and all but four run
offline against the fake world. `npm run docs:api:gates` reports the
counts; they are not repeated here, because a number in a commit message
goes stale the first time a field is added.

Four cannot be exercised in a hook and say so: the two rates calls, swap
quotes and payment-protocol requests each reach a third-party API that
the fake world does not intercept. No suite covers them:
`test:cli:network` runs the one-shot, CAPTCHA and edge-login suites, and
none of the three names any of the four. The coverage gate records that
as the reason it excuses them.

Where the API departs from `edge-core-js` it is recorded in `coreExtra`
with the reason — a wallet object that cannot cross HTTP as anything but
an id, the `to`/`amount` shorthand that expands into `spendTargets`,
engine-side paging and export on `get-transactions`. Anything not listed
there fails the build.

Where a value cannot be derived safely the call refuses rather than
guesses. `rates-usd-to-native` requires its `multiplier`, because this
route has no logged-in account to read a denomination from and an
assumed one returns a `nativeAmount` wrong by orders of magnitude.
`sign-bytes` rejects malformed base64 instead of signing whatever
decoded. Handles record the resolved `wallet.id`, so a wallet id and a
unique prefix of it name the same wallet on every step of a staged
spend.
---
 scripts/testCli.ts                     | 353 ++++++++++
 scripts/testCliCaptcha.ts              | 125 ++++
 scripts/testCliInteractive.ts          |  76 +++
 scripts/testEdgeLogin.ts               | 147 ++++
 scripts/testNodeApiSigner.ts           | 116 ++++
 src/cli/commands/account.ts            |  31 +
 src/cli/commands/all.ts                |   4 +
 src/cli/commands/edge.ts               |  92 +++
 src/cli/commands/localSettings.ts      |  34 +
 src/cli/commands/wallet.ts             | 298 +++++++++
 src/cli/engine/routes/admin.ts         | 372 +++++++++++
 src/cli/engine/routes/credentials.ts   | 252 +++++++
 src/cli/engine/routes/dataStore.ts     | 157 +++++
 src/cli/engine/routes/index.ts         |  15 +
 src/cli/engine/routes/keys.ts          | 273 ++++++++
 src/cli/engine/routes/lobby.ts         |  94 +++
 src/cli/engine/routes/localSettings.ts |  90 +++
 src/cli/engine/routes/otp.ts           | 129 ++++
 src/cli/engine/routes/rates.ts         | 252 +++++++
 src/cli/engine/routes/spend.ts         | 884 +++++++++++++++++++++++++
 src/cli/engine/routes/swap.ts          | 305 +++++++++
 src/cli/engine/routes/tokens.ts        |  94 +++
 src/cli/engine/routes/transactions.ts  | 500 ++++++++++++++
 src/cli/engine/routes/uri.ts           |  84 +++
 src/cli/engine/routes/vouchers.ts      |  76 +++
 src/cli/engine/routes/wallets.ts       | 323 +++++++++
 26 files changed, 5176 insertions(+)
 create mode 100644 scripts/testCli.ts
 create mode 100644 scripts/testCliCaptcha.ts
 create mode 100644 scripts/testCliInteractive.ts
 create mode 100644 scripts/testEdgeLogin.ts
 create mode 100644 scripts/testNodeApiSigner.ts
 create mode 100644 src/cli/commands/account.ts
 create mode 100644 src/cli/commands/edge.ts
 create mode 100644 src/cli/commands/localSettings.ts
 create mode 100644 src/cli/commands/wallet.ts
 create mode 100644 src/cli/engine/routes/admin.ts
 create mode 100644 src/cli/engine/routes/credentials.ts
 create mode 100644 src/cli/engine/routes/dataStore.ts
 create mode 100644 src/cli/engine/routes/keys.ts
 create mode 100644 src/cli/engine/routes/lobby.ts
 create mode 100644 src/cli/engine/routes/localSettings.ts
 create mode 100644 src/cli/engine/routes/otp.ts
 create mode 100644 src/cli/engine/routes/rates.ts
 create mode 100644 src/cli/engine/routes/spend.ts
 create mode 100644 src/cli/engine/routes/swap.ts
 create mode 100644 src/cli/engine/routes/tokens.ts
 create mode 100644 src/cli/engine/routes/transactions.ts
 create mode 100644 src/cli/engine/routes/uri.ts
 create mode 100644 src/cli/engine/routes/vouchers.ts
 create mode 100644 src/cli/engine/routes/wallets.ts

diff --git a/scripts/testCli.ts b/scripts/testCli.ts
new file mode 100644
index 00000000000..0cb795332ee
--- /dev/null
+++ b/scripts/testCli.ts
@@ -0,0 +1,353 @@
+/**
+ * End-to-end one-shot tests for the engine-based Edge CLI.
+ * Always uses tester servers (-t). Never hits production.
+ *
+ * Usage: node -r sucrase/register scripts/testCli.ts
+ */
+import { execSync, spawn } from 'child_process'
+import crypto from 'crypto'
+import fs from 'fs'
+import http from 'http'
+import os from 'os'
+import path from 'path'
+
+import { solveCaptcha } from '../src/cli/client/solveCaptcha'
+import { isTesterConfig } from '../src/cli/engine/testerServers'
+import { engineRequest } from './engineRequest'
+
+interface TestResult {
+  name: string
+  status: 'PASS' | 'FAIL' | 'SKIP'
+  durationMs: number
+  detail?: string
+}
+
+const results: TestResult[] = []
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-test-'))
+const TEST_USER = `clieng${crypto.randomBytes(4).toString('hex')}`
+const TEST_PASS = `Pass${crypto.randomBytes(4).toString('hex')}!a1`
+const TEST_PIN = '1234'
+
+function cli(
+  args: string,
+  timeoutMs = 120_000
+): { code: number; stdout: string; stderr: string } {
+  const cmd = `node -r sucrase/register src/cli/index.ts -t -d ${TMP} --no-spawn ${args}`
+  try {
+    const stdout = execSync(cmd, {
+      cwd: process.cwd(),
+      timeout: timeoutMs,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    })
+    return { code: 0, stdout, stderr: '' }
+  } catch (caught: unknown) {
+    const error = caught as {
+      status?: number
+      stdout?: string
+      stderr?: string
+    }
+    return {
+      code: error.status ?? 1,
+      stdout: String(error.stdout ?? ''),
+      stderr: String(error.stderr ?? '')
+    }
+  }
+}
+
+function record(
+  name: string,
+  start: number,
+  ok: boolean,
+  detail?: string
+): void {
+  results.push({
+    name,
+    status: ok ? 'PASS' : 'FAIL',
+    durationMs: Date.now() - start,
+    detail
+  })
+  console.log(
+    `${ok ? 'PASS' : 'FAIL'} ${name}${detail != null ? ' — ' + detail : ''}`
+  )
+}
+
+async function main(): Promise<void> {
+  console.log(`Test directory: ${TMP}`)
+  console.log(`Test user: ${TEST_USER}`)
+
+  // Start engine with TCP for parity check
+  const engine = spawn(
+    process.execPath,
+    [
+      '-r',
+      'sucrase/register',
+      'src/cli/engine/index.ts',
+      '-t',
+      '-d',
+      TMP,
+      '--tcp=9008',
+      '--idle-timeout=120'
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] }
+  )
+
+  let sock = ''
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('engine start timeout'))
+    }, 60_000)
+    engine.stderr?.on('data', (buf: Buffer) => {
+      const line = buf.toString()
+      process.stderr.write(line)
+      const m = /Listening on unix:(.+)/.exec(line)
+      if (m != null) sock = m[1].trim()
+      if (line.includes('[edge-engine] Ready')) {
+        clearTimeout(timer)
+        resolve()
+      }
+    })
+    engine.on('exit', code => {
+      clearTimeout(timer)
+      reject(new Error(`engine exited early: ${code}`))
+    })
+  })
+
+  try {
+    // Config asserts tester servers
+    let start = Date.now()
+    const config = await engineRequest(sock, 'GET', '/engine/config')
+    const okConfig =
+      config.status === 200 &&
+      config.json.testMode === true &&
+      isTesterConfig(config.json.servers)
+    record(
+      'config uses tester servers',
+      start,
+      okConfig,
+      JSON.stringify(config.json.servers)
+    )
+    if (!okConfig) {
+      throw new Error('Refusing to continue — not on tester servers')
+    }
+
+    // Status over unix and TCP must match
+    start = Date.now()
+    const statusUnix = await engineRequest(sock, 'GET', '/engine/status')
+    const statusTcp = await new Promise<{ status: number; json: any }>(
+      (resolve, reject) => {
+        const req = http.request(
+          {
+            method: 'GET',
+            host: '127.0.0.1',
+            port: 9008,
+            path: '/engine/status'
+          },
+          res => {
+            const chunks: Buffer[] = []
+            res.on('data', c => chunks.push(c))
+            res.on('end', () => {
+              resolve({
+                status: res.statusCode ?? 0,
+                json: JSON.parse(Buffer.concat(chunks).toString('utf8'))
+              })
+            })
+          }
+        )
+        req.on('error', reject)
+        req.end()
+      }
+    )
+    record(
+      'unix/tcp status parity',
+      start,
+      statusUnix.status === 200 &&
+        statusTcp.status === 200 &&
+        statusUnix.json.apiVersion === statusTcp.json.apiVersion &&
+        statusUnix.json.pid === statusTcp.json.pid
+    )
+
+    // CLI engine-status
+    start = Date.now()
+    const st = cli('engine-status')
+    record(
+      'cli engine-status',
+      start,
+      st.code === 0 && st.stdout.includes('apiVersion')
+    )
+
+    // Challenge + account create with CAPTCHA
+    start = Date.now()
+    let create = await engineRequest(sock, 'POST', '/create-account', {
+      username: TEST_USER,
+      password: TEST_PASS,
+      pin: TEST_PIN
+    })
+    if (
+      create.status === 403 &&
+      create.json?.error?.code === 'CHALLENGE_REQUIRED'
+    ) {
+      const { challengeId, challengeUri } = create.json.error.details
+      const ok = await solveCaptcha(challengeUri)
+      if (!ok) throw new Error('CAPTCHA solve failed')
+      create = await engineRequest(sock, 'POST', '/create-account', {
+        username: TEST_USER,
+        password: TEST_PASS,
+        pin: TEST_PIN,
+        challengeId
+      })
+    }
+    const sessionId = create.json?.sessionId as string | undefined
+    record(
+      'account create (with captcha retry)',
+      start,
+      create.status === 200 && typeof sessionId === 'string',
+      `status=${create.status} user=${TEST_USER}`
+    )
+
+    if (sessionId == null) {
+      throw new Error('No sessionId — aborting remaining tests')
+    }
+
+    // Persist session for CLI commands
+    fs.writeFileSync(
+      path.join(path.dirname(sock), 'session.json'),
+      JSON.stringify({
+        sessionId,
+        username: TEST_USER,
+        updatedAt: new Date().toISOString()
+      })
+    )
+
+    // Password login (new session), then create a wallet immediately.
+    // The engine must settle the account before returning the session so
+    // this create-account → login → create-wallet path is a first-try success.
+    start = Date.now()
+    await engineRequest(sock, 'POST', `/account/${sessionId}/logout`)
+    let login = await engineRequest(sock, 'POST', '/login-with-password', {
+      username: TEST_USER,
+      password: TEST_PASS
+    })
+    if (
+      login.status === 403 &&
+      login.json?.error?.code === 'CHALLENGE_REQUIRED'
+    ) {
+      const { challengeId, challengeUri } = login.json.error.details
+      await solveCaptcha(challengeUri)
+      login = await engineRequest(sock, 'POST', '/login-with-password', {
+        username: TEST_USER,
+        password: TEST_PASS,
+        challengeId
+      })
+    }
+    const sessionId2 = login.json?.sessionId as string | undefined
+    record(
+      'password login (with captcha retry)',
+      start,
+      login.status === 200 && typeof sessionId2 === 'string'
+    )
+
+    const sid = sessionId2 ?? sessionId
+    fs.writeFileSync(
+      path.join(path.dirname(sock), 'session.json'),
+      JSON.stringify({
+        sessionId: sid,
+        username: TEST_USER,
+        updatedAt: new Date().toISOString()
+      })
+    )
+
+    start = Date.now()
+    const wallet = await engineRequest(
+      sock,
+      'POST',
+      `/account/${sid}/create-currency-wallet`,
+      {
+        walletType: 'wallet:bitcoin',
+        name: 'Test BTC'
+      }
+    )
+    record(
+      'wallet create',
+      start,
+      wallet.status === 200 &&
+        (wallet.json?.walletId != null || wallet.json?.id != null),
+      wallet.json?.walletId ??
+        wallet.json?.id ??
+        `status=${wallet.status} body=${JSON.stringify(wallet.json)}`
+    )
+    const walletId = (wallet.json?.walletId ?? wallet.json?.id) as string
+
+    start = Date.now()
+    const list = cli('currency-wallets --filter=all')
+    record('cli currency-wallets', start, list.code === 0)
+
+    if (walletId != null) {
+      start = Date.now()
+      const info = cli(`wallet-info --wallet-id=${walletId}`)
+      record('cli wallet-info', start, info.code === 0)
+
+      start = Date.now()
+      const bal = cli(`balance-map --wallet-id=${walletId}`)
+      record('cli balance-map', start, bal.code === 0)
+
+      start = Date.now()
+      const addr = cli(`get-addresses --wallet-id=${walletId}`)
+      record('cli get-addresses', start, addr.code === 0)
+    }
+
+    // Session touch
+    start = Date.now()
+    const touch = await engineRequest(sock, 'POST', `/account/${sid}/touch`)
+    record('session touch', start, touch.status === 200)
+
+    // Logout
+    start = Date.now()
+    const logout = await engineRequest(sock, 'POST', `/account/${sid}/logout`)
+    record('logout', start, logout.status === 204 || logout.status === 200)
+
+    // Edge login request returns lobbyId
+    start = Date.now()
+    const edge = await engineRequest(sock, 'POST', '/request-edge-login')
+    record(
+      'request-edge-login returns lobbyId',
+      start,
+      edge.status === 200 &&
+        typeof edge.json?.lobbyId === 'string' &&
+        typeof edge.json?.uri === 'string' &&
+        edge.json.uri.startsWith('edge://edge/'),
+      edge.json?.uri
+    )
+    if (edge.json?.pendingId != null) {
+      await engineRequest(
+        sock,
+        'POST',
+        `/pending-edge-login/${edge.json.pendingId}/cancel-request`
+      )
+    }
+  } finally {
+    engine.kill('SIGTERM')
+    try {
+      fs.rmSync(TMP, { recursive: true, force: true })
+    } catch {
+      // ignore
+    }
+  }
+
+  console.log('\n=== Summary ===')
+  const failed = results.filter(r => r.status === 'FAIL')
+  for (const r of results) {
+    console.log(
+      `${r.status} ${r.name} (${r.durationMs}ms)${
+        r.detail != null ? ' ' + r.detail : ''
+      }`
+    )
+  }
+  console.log(`\n${results.length - failed.length}/${results.length} passed`)
+  if (failed.length > 0) process.exit(1)
+}
+
+main().catch((err: unknown) => {
+  console.error(err)
+  process.exit(1)
+})
diff --git a/scripts/testCliCaptcha.ts b/scripts/testCliCaptcha.ts
new file mode 100644
index 00000000000..fbd3c089740
--- /dev/null
+++ b/scripts/testCliCaptcha.ts
@@ -0,0 +1,125 @@
+/**
+ * Focused CAPTCHA + account create + password login test against login-tester.
+ *
+ * Usage: node -r sucrase/register scripts/testCliCaptcha.ts
+ */
+import { spawn } from 'child_process'
+import crypto from 'crypto'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { solveCaptcha } from '../src/cli/client/solveCaptcha'
+import { engineRequest } from './engineRequest'
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-captcha-'))
+const USER = `captcha${crypto.randomBytes(4).toString('hex')}`
+const PASS = `Pass${crypto.randomBytes(4).toString('hex')}!b2`
+const PIN = '4321'
+
+async function main(): Promise<void> {
+  console.log(`user=${USER} dir=${TMP}`)
+  const engine = spawn(
+    process.execPath,
+    [
+      '-r',
+      'sucrase/register',
+      'src/cli/engine/index.ts',
+      '-t',
+      '-d',
+      TMP,
+      '--idle-timeout=120'
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] }
+  )
+  let sock = ''
+  await new Promise<void>((resolve, reject) => {
+    const t = setTimeout(() => {
+      reject(new Error('timeout'))
+    }, 60_000)
+    engine.stderr?.on('data', (b: Buffer) => {
+      const line = b.toString()
+      process.stderr.write(line)
+      const m = /Listening on unix:(.+)/.exec(line)
+      if (m != null) sock = m[1].trim()
+      if (line.includes('Ready')) {
+        clearTimeout(t)
+        resolve()
+      }
+    })
+  })
+
+  try {
+    // Create — expect challenge or success
+    let create = await engineRequest(sock, 'POST', '/create-account', {
+      username: USER,
+      password: PASS,
+      pin: PIN
+    })
+    console.log(
+      'create initial status',
+      create.status,
+      create.json?.error?.code
+    )
+    if (create.json?.error?.code === 'CHALLENGE_REQUIRED') {
+      const { challengeId, challengeUri } = create.json.error.details
+      console.log('challengeUri', challengeUri)
+      const ok = await solveCaptcha(challengeUri)
+      console.log('solveCaptcha', ok)
+      if (!ok) throw new Error('CAPTCHA failed')
+      create = await engineRequest(sock, 'POST', '/create-account', {
+        username: USER,
+        password: PASS,
+        pin: PIN,
+        challengeId
+      })
+    }
+    if (create.status !== 200) {
+      throw new Error(`create failed: ${JSON.stringify(create.json)}`)
+    }
+    console.log('CREATED session', create.json.sessionId)
+
+    // Logout
+    await engineRequest(
+      sock,
+      'POST',
+      `/account/${create.json.sessionId}/logout`
+    )
+
+    // Login again with captcha path
+    let login = await engineRequest(sock, 'POST', '/login-with-password', {
+      username: USER,
+      password: PASS
+    })
+    console.log('login initial status', login.status, login.json?.error?.code)
+    if (login.json?.error?.code === 'CHALLENGE_REQUIRED') {
+      const { challengeId, challengeUri } = login.json.error.details
+      await solveCaptcha(challengeUri)
+      login = await engineRequest(sock, 'POST', '/login-with-password', {
+        username: USER,
+        password: PASS,
+        challengeId
+      })
+    }
+    if (login.status !== 200) {
+      throw new Error(`login failed: ${JSON.stringify(login.json)}`)
+    }
+    console.log('LOGGED IN session', login.json.sessionId)
+
+    // Cleanup remote account
+    await engineRequest(
+      sock,
+      'POST',
+      `/account/${login.json.sessionId}/delete-remote-account`
+    )
+    console.log('PASS captcha account create + login')
+  } finally {
+    engine.kill('SIGTERM')
+    fs.rmSync(TMP, { recursive: true, force: true })
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error(error)
+  process.exit(1)
+})
diff --git a/scripts/testCliInteractive.ts b/scripts/testCliInteractive.ts
new file mode 100644
index 00000000000..bd68ebf038b
--- /dev/null
+++ b/scripts/testCliInteractive.ts
@@ -0,0 +1,76 @@
+/**
+ * Interactive smoke test — boots engine, runs a short command sequence.
+ * Always uses tester servers.
+ */
+import { execSync, spawn } from 'child_process'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-interactive-'))
+
+async function main(): Promise<void> {
+  const engine = spawn(
+    process.execPath,
+    [
+      '-r',
+      'sucrase/register',
+      'src/cli/engine/index.ts',
+      '-t',
+      '-d',
+      TMP,
+      '--idle-timeout=60'
+    ],
+    { stdio: ['ignore', 'inherit', 'pipe'] }
+  )
+
+  // Actually poll, rather than sleep and hope: a flat wait is slower than it
+  // needs to be on a warm machine and flaky on a cold one, and it cannot tell
+  // a slow start from an engine that died on its first line.
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('Timed out waiting for the engine to be ready'))
+    }, 60_000)
+    const done = (settle: () => void): void => {
+      clearTimeout(timer)
+      settle()
+    }
+    engine.once('exit', (code, signal) => {
+      const how =
+        signal != null ? `killed by ${signal}` : `exited with code ${code ?? 0}`
+      done(() => {
+        reject(new Error(`The engine ${how} before it was ready`))
+      })
+    })
+    engine.stderr?.on('data', (chunk: Buffer) => {
+      const text = String(chunk)
+      process.stderr.write(text)
+      if (text.includes('Ready')) done(resolve)
+    })
+  })
+
+  const run = (args: string): void => {
+    console.log('>', args)
+    const out = execSync(
+      `node -r sucrase/register src/cli/index.ts -t -d ${TMP} --no-spawn ${args}`,
+      { encoding: 'utf8' }
+    )
+    console.log(out)
+  }
+
+  try {
+    run('engine-status')
+    run('engine-config')
+    run('local-users')
+    run('fetch-challenge')
+    console.log('PASS interactive smoke')
+  } finally {
+    engine.kill('SIGTERM')
+    fs.rmSync(TMP, { recursive: true, force: true })
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error(error)
+  process.exit(1)
+})
diff --git a/scripts/testEdgeLogin.ts b/scripts/testEdgeLogin.ts
new file mode 100644
index 00000000000..1a14e6586ba
--- /dev/null
+++ b/scripts/testEdgeLogin.ts
@@ -0,0 +1,147 @@
+/**
+ * Edge-login E2E against login-tester without the GUI:
+ * 1. Create+login an approving account
+ * 2. Request request-edge-login (returns lobbyId + uri)
+ * 3. Approve the lobby from the logged-in account
+ * 4. Poll until the pending login completes with a session
+ *
+ * Also prints the lobby URI for optional Maestro approval on a
+ * tester-configured Edge build.
+ *
+ * Usage: node -r sucrase/register scripts/testEdgeLogin.ts
+ */
+import { spawn } from 'child_process'
+import crypto from 'crypto'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { solveCaptcha } from '../src/cli/client/solveCaptcha'
+import { engineRequest } from './engineRequest'
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-edgelogin-'))
+const USER = `edgelogin${crypto.randomBytes(3).toString('hex')}`
+const PASS = `Pass${crypto.randomBytes(4).toString('hex')}!e1`
+const PIN = '2468'
+
+async function createWithCaptcha(sock: string): Promise<string> {
+  let create = await engineRequest(sock, 'POST', '/create-account', {
+    username: USER,
+    password: PASS,
+    pin: PIN
+  })
+  if (create.json?.error?.code === 'CHALLENGE_REQUIRED') {
+    const { challengeId, challengeUri } = create.json.error.details
+    const ok = await solveCaptcha(challengeUri)
+    if (!ok) throw new Error('CAPTCHA failed')
+    create = await engineRequest(sock, 'POST', '/create-account', {
+      username: USER,
+      password: PASS,
+      pin: PIN,
+      challengeId
+    })
+  }
+  if (create.status !== 200) {
+    throw new Error(`create failed: ${JSON.stringify(create.json)}`)
+  }
+  return create.json.sessionId as string
+}
+
+async function main(): Promise<void> {
+  console.log(`Approver user=${USER} dir=${TMP}`)
+  const engine = spawn(
+    process.execPath,
+    [
+      '-r',
+      'sucrase/register',
+      'src/cli/engine/index.ts',
+      '-t',
+      '-d',
+      TMP,
+      '--idle-timeout=180'
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] }
+  )
+  let sock = ''
+  await new Promise<void>((resolve, reject) => {
+    const t = setTimeout(() => {
+      reject(new Error('engine timeout'))
+    }, 60_000)
+    engine.stderr?.on('data', (b: Buffer) => {
+      const line = b.toString()
+      process.stderr.write(line)
+      const m = /unix:(.+)/.exec(line)
+      if (m != null) sock = m[1].trim()
+      if (line.includes('Ready')) {
+        clearTimeout(t)
+        resolve()
+      }
+    })
+  })
+
+  try {
+    const approverSession = await createWithCaptcha(sock)
+    console.log('approver session', approverSession)
+
+    const pending = await engineRequest(sock, 'POST', '/request-edge-login')
+    if (pending.status !== 200) {
+      throw new Error(`edge login failed: ${JSON.stringify(pending.json)}`)
+    }
+    const { pendingId, lobbyId, uri } = pending.json
+    console.log(JSON.stringify({ pendingId, lobbyId, uri }, null, 2))
+    console.log(
+      'Maestro tip: paste this URI into Scan QR → Enter on a tester-server Edge build:'
+    )
+    console.log(`  LOBBY_URI=${uri}`)
+    console.log(
+      `  maestro-runner --platform ios -e LOBBY_URI=${uri} test ~/.edge-cli/maestro/C999006-edge-login-approve.yaml`
+    )
+
+    // Approve via REST (same tester login server)
+    const fetched = await engineRequest(
+      sock,
+      'GET',
+      `/account/${approverSession}/fetch-lobby/${lobbyId}`
+    )
+    console.log('lobby fetch', fetched.status, JSON.stringify(fetched.json))
+    const approved = await engineRequest(
+      sock,
+      'POST',
+      `/account/${approverSession}/approve-login-request/${lobbyId}`
+    )
+    console.log('lobby approve', approved.status, JSON.stringify(approved.json))
+
+    const deadline = Date.now() + 60_000
+    while (Date.now() < deadline) {
+      const st = await engineRequest(
+        sock,
+        'GET',
+        `/pending-edge-login/${pendingId}`
+      )
+      console.log('poll', st.json?.state)
+      if (st.json?.state === 'done' && st.json?.session != null) {
+        console.log('PASS request-edge-login', st.json.session.sessionId)
+        // Cleanup
+        await engineRequest(
+          sock,
+          'POST',
+          `/account/${approverSession}/delete-remote-account`
+        )
+        return
+      }
+      if (st.json?.state === 'error' || st.json?.state === 'closed') {
+        throw new Error(`edge login ended: ${JSON.stringify(st.json)}`)
+      }
+      await new Promise(resolve => setTimeout(resolve, 1500))
+    }
+    throw new Error('Timed out waiting for request-edge-login approval')
+  } finally {
+    engine.kill('SIGTERM')
+    fs.rmSync(TMP, { recursive: true, force: true })
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error(error)
+  process.exit(1)
+})
diff --git a/scripts/testNodeApiSigner.ts b/scripts/testNodeApiSigner.ts
new file mode 100644
index 00000000000..15921266958
--- /dev/null
+++ b/scripts/testNodeApiSigner.ts
@@ -0,0 +1,116 @@
+/**
+ * Verify the Node N-API Edge API HMAC signer against a JS HMAC-SHA256
+ * reference using edgeKey.json, and that makeCoreContext prefers apiSigner.
+ */
+import { createHmac } from 'crypto'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { EventHub } from '../src/cli/engine/events'
+import type { EngineLogger } from '../src/cli/engine/logger'
+import { makeCoreContext } from '../src/cli/engine/makeCoreContext'
+import {
+  hasNodeApiSigner,
+  makeNodeApiSigner,
+  NODE_API_SIGNER_BUNDLE_ID,
+  resetNodeApiSignerCacheForTests
+} from '../src/cli/engine/nodeApiSigner'
+
+function assert(cond: boolean, msg: string): asserts cond {
+  if (!cond) throw new Error(msg)
+}
+
+async function main(): Promise<void> {
+  resetNodeApiSignerCacheForTests()
+
+  assert(
+    hasNodeApiSigner(),
+    'Node API signer addon missing — run npm run build:cli:native first'
+  )
+
+  const edgeKeyPath = path.join(__dirname, '..', 'edgeKey.json')
+  assert(fs.existsSync(edgeKeyPath), 'edgeKey.json required for HMAC reference')
+  const edgeKey = JSON.parse(fs.readFileSync(edgeKeyPath, 'utf8')) as {
+    apiKey: string
+    apiSecret: string
+  }
+  assert(typeof edgeKey.apiKey === 'string' && edgeKey.apiKey !== '', 'apiKey')
+  assert(
+    typeof edgeKey.apiSecret === 'string' && edgeKey.apiSecret !== '',
+    'apiSecret'
+  )
+
+  const secret = Buffer.from(edgeKey.apiSecret.replace(/^0x/i, ''), 'hex')
+  const message = 'POST\n/v2/login\n{"userId":"test"}'
+  const expectedSig = createHmac('sha256', secret)
+    .update(message, 'utf8')
+    .digest('base64')
+
+  const signer = makeNodeApiSigner()
+  const signed = await signer.signMessage(message)
+
+  assert(
+    signed.apiKey === edgeKey.apiKey,
+    `apiKey mismatch: ${signed.apiKey} !== ${edgeKey.apiKey}`
+  )
+  assert(
+    signed.signature === expectedSig,
+    `signature mismatch\n native=${signed.signature}\n expect=${expectedSig}\n pad=${NODE_API_SIGNER_BUNDLE_ID}`
+  )
+  console.log('PASS node HMAC matches JS reference')
+
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-node-hmac-'))
+  const events = new EventHub()
+  const logs: string[] = []
+  const logger = {
+    logPath: path.join(dir, 'test.log'),
+    write(level: string, message: string) {
+      logs.push(`${level}:${message}`)
+    },
+    info(message: string) {
+      logs.push(`info:${message}`)
+    },
+    warn(message: string) {
+      logs.push(`warn:${message}`)
+    },
+    error(message: string) {
+      logs.push(`error:${message}`)
+    },
+    close() {}
+  } as unknown as EngineLogger
+
+  const bundle = await makeCoreContext({
+    directory: dir,
+    testMode: true,
+    events,
+    logger
+  })
+  assert(
+    logs.some(l => l.includes('Node native Edge API HMAC')),
+    'expected makeCoreContext to log native signer use'
+  )
+  assert(
+    logs.some(l => l.includes('Fetched infoRollup appKeys')),
+    `expected makeCoreContext to fetch infoRollup appKeys with the native HMAC signer\nlogs:\n${logs.join(
+      '\n'
+    )}`
+  )
+  assert(
+    !logs.some(l => l.includes('infoRollup appKeys fetch failed')),
+    `infoRollup appKeys fetch failed; native HMAC signer should authorize info-tester\nlogs:\n${logs.join(
+      '\n'
+    )}`
+  )
+  assert(bundle.context != null, 'missing context')
+  console.log('PASS makeCoreContext uses native signer on tester')
+  console.log(
+    'PASS makeCoreContext fetched infoRollup appKeys with native signer'
+  )
+  await bundle.context.close()
+}
+
+main().catch((err: unknown) => {
+  console.error(err)
+  process.exit(1)
+})
diff --git a/src/cli/commands/account.ts b/src/cli/commands/account.ts
new file mode 100644
index 00000000000..09863efca59
--- /dev/null
+++ b/src/cli/commands/account.ts
@@ -0,0 +1,31 @@
+import { printJson } from '../client/output'
+import { command, requireSession, UsageError } from '../command'
+import { parseCommandArgs } from '../commandArgs'
+import { accountPath } from './paths'
+
+const deleteRemoteCmd = command(
+  'delete-remote-account',
+  {
+    usage: 'delete-remote-account --yes',
+    help: 'Permanently delete the remote account (account.deleteRemoteAccount)',
+    needsSession: true
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(deleteRemoteCmd, argv, {
+      positional: 'none',
+      flags: { yes: 'boolean' }
+    })
+    // The endpoint has no guard, so the guard lives here: this is
+    // irreversible and takes the account's funds with it.
+    if (!args.boolean('yes')) {
+      throw new UsageError(
+        deleteRemoteCmd,
+        'delete-remote-account is irreversible; pass --yes to confirm'
+      )
+    }
+    const sessionId = requireSession(ctx)
+    await ctx.client.post(accountPath(sessionId, '/delete-remote-account'))
+    ctx.setSessionId(null)
+    printJson({ ok: true })
+  }
+)
diff --git a/src/cli/commands/all.ts b/src/cli/commands/all.ts
index 32a61c87fe1..c5bc699f6a1 100644
--- a/src/cli/commands/all.ts
+++ b/src/cli/commands/all.ts
@@ -2,7 +2,11 @@
  * Importing this module registers every one-shot CLI command as a
  * side-effect. Import it once from the CLI entry point.
  */
+import './account'
 import './generated'
+import './edge'
 import './help'
+import './localSettings'
 import './login'
 import './subscribe'
+import './wallet'
diff --git a/src/cli/commands/edge.ts b/src/cli/commands/edge.ts
new file mode 100644
index 00000000000..ba843ae7cb9
--- /dev/null
+++ b/src/cli/commands/edge.ts
@@ -0,0 +1,92 @@
+import { printJson } from '../client/output'
+import { readPendingEdgeLogin } from '../clientResponses'
+import { command } from '../command'
+import { parseCommandArgs } from '../commandArgs'
+
+const POLL_INTERVAL_MS = 2000
+const TIMEOUT_MS = 5 * 60 * 1000
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, ms))
+}
+
+const requestCmd = command(
+  'request-edge-login',
+  {
+    usage: 'request-edge-login [--no-wait]',
+    help: 'Request a QR / lobby Edge login and wait for approval'
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(requestCmd, argv, {
+      positional: 'none',
+      flags: { 'no-wait': 'boolean' }
+    })
+    const pending = readPendingEdgeLogin(
+      await ctx.client.post('/request-edge-login'),
+      'request-edge-login'
+    )
+    // `--no-wait` prints the lobby and stops, so the QR can be shown while
+    // another process polls the same handle with `poll-edge-login`.
+    if (args.boolean('no-wait')) {
+      printJson(pending)
+      return
+    }
+    printJson(pending)
+
+    const deadline = Date.now() + TIMEOUT_MS
+    let current = pending
+    while (
+      current.state !== 'done' &&
+      current.state !== 'error' &&
+      current.state !== 'closed'
+    ) {
+      if (Date.now() > deadline) {
+        throw new Error('Timed out waiting for Edge login approval')
+      }
+      await sleep(POLL_INTERVAL_MS)
+      current = readPendingEdgeLogin(
+        await ctx.client.get(
+          `/pending-edge-login/${encodeURIComponent(pending.pendingId)}`
+        ),
+        'poll-edge-login'
+      )
+    }
+
+    if (current.state === 'done' && current.session != null) {
+      ctx.setSessionId(current.session.sessionId, current.session.username)
+      printJson(current)
+    } else {
+      printJson(current)
+      throw new Error(
+        current.error ?? `Edge login ended in state "${current.state}"`
+      )
+    }
+  }
+)
+
+const pollCmd = command(
+  'poll-edge-login',
+  {
+    usage: 'poll-edge-login <pendingId>',
+    help: 'Check a pending QR login once, without waiting',
+    needsSession: false
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(pollCmd, argv, {
+      positional: 'required',
+      flags: {}
+    })
+    const current = readPendingEdgeLogin(
+      await ctx.client.get(
+        `/pending-edge-login/${encodeURIComponent(args.positional ?? '')}`
+      ),
+      'poll-edge-login'
+    )
+    // A finished poll carries the session, so store it here rather than
+    // making the caller copy a sessionId out of the JSON.
+    if (current.state === 'done' && current.session != null) {
+      ctx.setSessionId(current.session.sessionId, current.session.username)
+    }
+    printJson(current)
+  }
+)
diff --git a/src/cli/commands/localSettings.ts b/src/cli/commands/localSettings.ts
new file mode 100644
index 00000000000..d182d3957bd
--- /dev/null
+++ b/src/cli/commands/localSettings.ts
@@ -0,0 +1,34 @@
+import { printJson } from '../client/output'
+import { command, requireSession } from '../command'
+import { parseCommandArgs } from '../commandArgs'
+import { accountPath } from './paths'
+
+/**
+ * One command over two routes: reading with no flag, writing with one. That
+ * dispatch is why this is hand-written rather than generated.
+ */
+const localSettingsCmd = command(
+  'local-settings',
+  {
+    usage: 'local-settings [--spam-filter-on=true|false]',
+    help: 'Show or set device-local account settings',
+    needsSession: true
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(localSettingsCmd, argv, {
+      positional: 'none',
+      flags: { 'spam-filter-on': 'boolstr' }
+    })
+    const sessionId = requireSession(ctx)
+    const spamFilterOn = args.boolstr('spam-filter-on')
+    if (spamFilterOn == null) {
+      printJson(await ctx.client.get(accountPath(sessionId, '/local-settings')))
+      return
+    }
+    printJson(
+      await ctx.client.post(accountPath(sessionId, '/change-local-settings'), {
+        spamFilterOn
+      })
+    )
+  }
+)
diff --git a/src/cli/commands/wallet.ts b/src/cli/commands/wallet.ts
new file mode 100644
index 00000000000..5e3ba1e2e05
--- /dev/null
+++ b/src/cli/commands/wallet.ts
@@ -0,0 +1,298 @@
+import fs from 'fs'
+import path from 'path'
+
+import { parseExportFormats, type TxExportFormat } from '../../util/txExport'
+import { printJson } from '../client/output'
+import { command, requireSession, UsageError } from '../command'
+import { parseCommandArgs } from '../commandArgs'
+import { accountPath, walletPath } from './paths'
+
+/**
+ * A wallet-scoped URL.
+ *
+ * The wallet id is not in it: ids are base64, so `7o7i6/tlI+qi…=` contains a
+ * path delimiter. It travels as a named argument instead — in the query for
+ * `GET`, the body for `POST`.
+ */
+const walletStateCmd = command(
+  'change-wallet-states',
+  {
+    usage:
+      'change-wallet-states --wallet-id=<id> [--archived=true|false] [--deleted=true|false] [--hidden=true|false] [--sort-index=N]',
+    help: 'Set wallet archived/deleted/hidden/sortIndex (account.changeWalletStates)',
+    needsSession: true
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(walletStateCmd, argv, {
+      positional: 'none',
+      flags: {
+        'wallet-id': 'string',
+        archived: 'boolstr',
+        deleted: 'boolstr',
+        hidden: 'boolstr',
+        'sort-index': 'string'
+      }
+    })
+    const state: Record<string, unknown> = {}
+    const archived = args.boolstr('archived')
+    const deleted = args.boolstr('deleted')
+    const hidden = args.boolstr('hidden')
+    const sortIndexRaw = args.string('sort-index')
+    if (archived != null) state.archived = archived
+    if (deleted != null) state.deleted = deleted
+    if (hidden != null) state.hidden = hidden
+    if (sortIndexRaw != null) {
+      const sortIndex = Number(sortIndexRaw)
+      if (!Number.isFinite(sortIndex)) {
+        throw new UsageError(walletStateCmd, '--sort-index must be a number')
+      }
+      state.sortIndex = sortIndex
+    }
+    if (Object.keys(state).length === 0) {
+      throw new UsageError(
+        walletStateCmd,
+        'Provide at least one of --archived, --deleted, --hidden, --sort-index'
+      )
+    }
+    const sessionId = requireSession(ctx)
+    await ctx.client.post(accountPath(sessionId, '/change-wallet-states'), {
+      walletStates: { [args.requireString('wallet-id')]: state }
+    })
+    printJson({ ok: true })
+  }
+)
+
+const balanceCmd = command(
+  'balance-map',
+  {
+    usage: 'balance-map --wallet-id=<id> [--token-id=<tokenId>]',
+    help: 'Show native and exchange balance-map for a wallet (or one token)',
+    needsSession: true
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(balanceCmd, argv, {
+      positional: 'none',
+      flags: { 'wallet-id': 'string', 'token-id': 'string' }
+    })
+    const sessionId = requireSession(ctx)
+    const tokenId = args.string('token-id')
+    const result = await ctx.client.get<{
+      balances: Array<{ tokenId: string | null }>
+    }>(
+      walletPath(sessionId, '/balance-map') +
+        `?walletId=${encodeURIComponent(args.requireString('wallet-id'))}`
+    )
+    if (tokenId == null) {
+      printJson(result)
+      return
+    }
+    printJson({
+      balances: result.balances.filter(entry => entry.tokenId === tokenId)
+    })
+  }
+)
+
+const txListCmd = command(
+  'get-transactions',
+  {
+    usage:
+      'get-transactions --wallet-id=<id> [--token-id=<id>] [--limit=<n>] [--offset=<n>] [--start-date=<ISO-8601>] [--end-date=<ISO-8601>] [--search-string=<text>] [--spam-threshold=<n>] [--fiat=USD] [--export-format=csv,qbo,bitwave] [--out=<path>] [--bitwave-account=<id>] [--save-export-prefs]',
+    help: 'List or export wallet transactions (JSON by default; CSV/QBO/Bitwave via REST exportFormat)',
+    needsSession: true
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(txListCmd, argv, {
+      positional: 'none',
+      flags: {
+        'wallet-id': 'string',
+        'token-id': 'string',
+        limit: 'string',
+        offset: 'string',
+        'start-date': 'string',
+        'end-date': 'string',
+        'search-string': 'string',
+        'spam-threshold': 'string',
+        fiat: 'string',
+        'export-format': 'string',
+        out: 'string',
+        'bitwave-account': 'string',
+        // Both were advertised by `edge-cli help get-transactions`, which is
+        // generated from the route declaration, and refused here, which is
+        // hand-written — so the one branch that writes the wallet's synced
+        // `exportTxInfo.json` had no reachable caller at all.
+        'save-export-prefs': 'boolean'
+      }
+    })
+    let formats: TxExportFormat[]
+    try {
+      formats = parseExportFormats(args.string('export-format'))
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new UsageError(txListCmd, message)
+    }
+    const out = args.string('out')
+    if (formats.length > 0 && out == null) {
+      throw new UsageError(
+        txListCmd,
+        '--export-format requires --out=<path> (relative to the current directory or absolute)'
+      )
+    }
+    if (formats.length === 0 && out != null) {
+      throw new UsageError(txListCmd, '--out requires --export-format')
+    }
+    const bitwaveAccount = args.string('bitwave-account')
+    if (bitwaveAccount != null && !formats.includes('bitwave')) {
+      throw new UsageError(
+        txListCmd,
+        '--bitwave-account requires bitwave in --export-format'
+      )
+    }
+
+    const sessionId = requireSession(ctx)
+    const query = new URLSearchParams()
+    query.set('walletId', args.requireString('wallet-id'))
+    const tokenId = args.string('token-id')
+    const limit = args.string('limit')
+    const offset = args.string('offset')
+    const startDate = args.string('start-date')
+    const endDate = args.string('end-date')
+    const searchString = args.string('search-string')
+    const spamThreshold = args.string('spam-threshold')
+    const fiat = args.string('fiat')
+    const saveExportPrefs = args.boolean('save-export-prefs')
+    if (tokenId != null) query.set('tokenId', tokenId)
+    if (limit != null) query.set('limit', limit)
+    if (offset != null) query.set('offset', offset)
+    if (startDate != null) query.set('startDate', startDate)
+    if (endDate != null) query.set('endDate', endDate)
+    if (searchString != null) query.set('searchString', searchString)
+    if (spamThreshold != null) query.set('spamThreshold', spamThreshold)
+    if (fiat != null) query.set('fiat', fiat)
+    if (formats.length > 0) query.set('exportFormat', formats.join(','))
+    if (bitwaveAccount != null) query.set('bitwaveAccountId', bitwaveAccount)
+    if (saveExportPrefs) query.set('saveExportPrefs', 'true')
+    const qs = query.toString()
+    const result = await ctx.client.get<{
+      ok?: boolean
+      isoFiat?: string
+      total?: number
+      transactions?: unknown
+      files?: Array<{ format: TxExportFormat; contents: string }>
+    }>(walletPath(sessionId, '/get-transactions') + `?${qs}`)
+
+    if (formats.length === 0 || result.files == null) {
+      printJson(result)
+      return
+    }
+
+    const written = await writeExportFiles(out!, result.files)
+    printJson({
+      ok: true,
+      isoFiat: result.isoFiat,
+      total: result.total,
+      files: written
+    })
+  }
+)
+
+function resolveUserPath(out: string): string {
+  return path.isAbsolute(out) ? out : path.resolve(process.cwd(), out)
+}
+
+function exportFilePath(
+  out: string,
+  format: TxExportFormat,
+  count: number
+): string {
+  const resolved = resolveUserPath(out)
+  if (count <= 1) return resolved
+  let stem = resolved
+  if (stem.endsWith('.bitwave.csv')) {
+    stem = stem.slice(0, -'.bitwave.csv'.length)
+  } else if (stem.endsWith('.csv')) {
+    stem = stem.slice(0, -'.csv'.length)
+  } else if (stem.endsWith('.qbo')) {
+    stem = stem.slice(0, -'.qbo'.length)
+  }
+  if (format === 'bitwave') return `${stem}.bitwave.csv`
+  if (format === 'qbo') return `${stem}.qbo`
+  return `${stem}.csv`
+}
+
+async function writeExportFiles(
+  out: string,
+  files: Array<{ format: TxExportFormat; contents: string }>
+): Promise<Array<{ format: TxExportFormat; path: string }>> {
+  const written: Array<{ format: TxExportFormat; path: string }> = []
+  for (const file of files) {
+    const filePath = exportFilePath(out, file.format, files.length)
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.promises.writeFile(filePath, file.contents, 'utf8')
+    written.push({ format: file.format, path: filePath })
+  }
+  return written
+}
+
+const changeEnabledTokenIdsCmd = command(
+  'change-enabled-token-ids',
+  {
+    usage:
+      'change-enabled-token-ids --wallet-id=<id> (--token-ids=<a,b,c> | --add=<id> | --remove=<id>)',
+    help: 'Set the wallet\u2019s enabled token set (wallet.changeEnabledTokenIds)',
+    needsSession: true
+  },
+  async (ctx, argv) => {
+    const args = parseCommandArgs(changeEnabledTokenIdsCmd, argv, {
+      positional: 'none',
+      flags: {
+        'wallet-id': 'string',
+        'token-ids': 'string',
+        add: 'repeat',
+        remove: 'repeat'
+      }
+    })
+    const sessionId = requireSession(ctx)
+    const walletId = args.requireString('wallet-id')
+    const listed = args.string('token-ids')
+    const added = args.strings('add')
+    const removed = args.strings('remove')
+
+    if (listed != null && (added.length > 0 || removed.length > 0)) {
+      throw new UsageError(
+        changeEnabledTokenIdsCmd,
+        '--token-ids cannot be combined with --add or --remove'
+      )
+    }
+
+    let tokenIds: string[]
+    if (listed != null) {
+      tokenIds = listed
+        .split(',')
+        .map(id => id.trim())
+        .filter(id => id !== '')
+    } else if (added.length > 0 || removed.length > 0) {
+      // --add / --remove are client-side sugar: core only has a full setter,
+      // so read the current set first and send back the whole list.
+      const current = await ctx.client.get<{ enabledTokenIds: string[] }>(
+        walletPath(sessionId, '/tokens') +
+          `?walletId=${encodeURIComponent(walletId)}`
+      )
+      const next = new Set(current.enabledTokenIds)
+      for (const id of added) next.add(id)
+      for (const id of removed) next.delete(id)
+      tokenIds = [...next]
+    } else {
+      throw new UsageError(
+        changeEnabledTokenIdsCmd,
+        'Provide --token-ids, --add, or --remove'
+      )
+    }
+
+    printJson(
+      await ctx.client.post(
+        walletPath(sessionId, '/change-enabled-token-ids'),
+        { walletId, tokenIds }
+      )
+    )
+  }
+)
diff --git a/src/cli/engine/routes/admin.ts b/src/cli/engine/routes/admin.ts
new file mode 100644
index 00000000000..bcba452be6d
--- /dev/null
+++ b/src/cli/engine/routes/admin.ts
@@ -0,0 +1,372 @@
+import { asArray, asObject, asOptional, asString, asUnknown } from 'cleaners'
+
+import { base58 } from '../../../util/encoding'
+import { doc } from '../doc'
+import { engineError } from '../errors'
+import { getInternalStuff, type LobbyRequest } from '../internal'
+import { route } from '../route'
+import { asCoreValue, asMinSeconds, asOk } from '../schemas'
+
+const REPO_KEYS = {
+  syncKey: doc(asString, 'Base58 repo sync key.'),
+  dataKey: doc(asString, 'Base58 repo data key.')
+}
+
+/**
+ * Raw login-server request.
+ *
+ * Sends an arbitrary request with the context's credentials attached.
+ * Debugging only — this is core's private surface.
+ */
+export const adminAuthRequest = route({
+  core: 'context.$internalStuff.authRequest',
+  method: 'POST',
+  path: '/admin/auth-request',
+  cli: 'admin-auth-request',
+  body: asObject({
+    method: doc(asString, 'HTTP method, e.g. `GET`.'),
+    path: doc(asString, 'Login-server path, not an engine path.'),
+    // `asObject(asUnknown)`, so a non-object is a 400 naming the field. As
+    // `asCoreValue` it was accepted by the declaration and then *dropped* by
+    // the handler's `isPlainObject` ternary, which sent the login-server
+    // request with no body at all.
+    body: asOptional(
+      doc(asObject(asUnknown), 'Request body, when the method takes one.')
+    )
+  }).withRest,
+  returns: doc(asCoreValue, 'Whatever the login server returned.'),
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const { method, path } = ctx.body
+    const internal = getInternalStuff(ctx.state.core.context)
+    return await internal.authRequest(method, path, ctx.body.body)
+  }
+})
+
+/**
+ * Hash a username.
+ *
+ * Reproduces the login server's hashing, to derive a login id offline.
+ */
+export const adminHashUsername = route({
+  core: 'context.$internalStuff.hashUsername',
+  method: 'GET',
+  path: '/admin/hash-username',
+  cli: 'admin-hash-username',
+  query: asObject({ username: doc(asString, 'The name to hash.') }).withRest,
+  returns: asObject({ loginId: doc(asString, 'Base58.') }),
+
+  async handler(ctx) {
+    const { username } = ctx.query.valid
+    const internal = getInternalStuff(ctx.state.core.context)
+    const hash = await internal.hashUsername(username)
+    return { loginId: base58.stringify(hash) }
+  }
+})
+
+/**
+ * Create a lobby.
+ *
+ * A lobby polls the login server until closed, so the engine parks it under a
+ * `lobby_` handle and closes it on expiry rather than leaking the poll.
+ *
+ * @note Release it with `admin-lobby-handle-delete`, or the poll runs for the
+ *   full five minutes.
+ */
+export const adminMakeLobby = route({
+  core: 'context.$internalStuff.makeLobby',
+  method: 'POST',
+  path: '/admin/make-lobby',
+  cli: {
+    command: 'admin-make-lobby',
+    flags: { periodSeconds: { maps: 'period' } }
+  },
+  body: asObject({
+    lobbyRequest: asOptional(
+      doc(asObject(asUnknown), 'Defaults to `{}`.'),
+      () => ({})
+    ),
+    // `asCoreValue` plus a `typeof body.period === 'number'` check in the
+    // handler meant `{"period":"30"}` over REST was *silently ignored* and
+    // the lobby polled at the default rate, while the generated table
+    // advertised `--period-seconds='<json>'` where a number belongs.
+    //
+    // Floored, because core's unit is milliseconds and this field's is
+    // seconds: an unbounded value let `--period-seconds=0` poll as fast as
+    // the network answers, from a route that needs no session, against
+    // Edge's production login server.
+    period: asOptional(
+      doc(
+        asMinSeconds(0.25),
+        'Poll interval in seconds. At least 0.25; the engine converts to the milliseconds core takes.'
+      )
+    )
+  }).withRest,
+  returns: asObject({
+    objectId: doc(asString, 'The parked handle.'),
+    expiresAt: doc(
+      asString,
+      'When the engine closes the lobby and stops polling.'
+    ),
+    lobbyId: doc(asString, 'Identifies the lobby to the party joining it.'),
+    replies: doc(
+      asArray(asCoreValue),
+      'Empty at creation; re-read to see replies.'
+    )
+  }),
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const internal = getInternalStuff(ctx.state.core.context)
+    const lobby = await internal.makeLobby(
+      ctx.body.lobbyRequest as unknown as LobbyRequest,
+      // Seconds in, milliseconds out. Core's `makeLobby` forwards this to
+      // `makePeriodicTask`, whose parameter is named `msGap`, so passing the
+      // documented `--period-seconds=30` straight through polled
+      // `GET /v2/lobby/{id}` every 30 *milliseconds* — about 33 requests a
+      // second for the handle's whole five-minute TTL, roughly 10,000
+      // requests, with the engine's single event loop saturated throughout.
+      ctx.body.period == null ? undefined : Math.round(ctx.body.period * 1000)
+    )
+    // A lobby polls the login server until it is closed. Returning only its id
+    // would drop the last reference and leave that poll running for the life
+    // of the engine, so park it in the handle store and close it on expiry.
+    const handle = ctx.state.objects.create({
+      kind: 'lobby',
+      prefix: 'lobby_',
+      value: lobby,
+      onExpire: value => {
+        value.close()
+      }
+    })
+    return {
+      objectId: handle.objectId,
+      expiresAt: handle.expiresAt,
+      lobbyId: lobby.lobbyId,
+      replies: lobby.replies
+    }
+  }
+})
+
+/**
+ * Close a parked lobby.
+ *
+ * @note Not under `/account/{sessionId}/objects/`, because admin lobbies
+ *   belong to no session.
+ * @coreNote Engine handle store for a lobby created via makeLobby.
+ */
+export const adminDeleteLobbyHandle = route({
+  core: null,
+  method: 'POST',
+  path: '/admin/lobby-handle/delete',
+  cli: { command: 'admin-lobby-handle-delete', positional: 'objectId' },
+  returns: asOk,
+  errors: ['OBJECT_NOT_FOUND', 'OBJECT_KIND_MISMATCH', 'OBJECT_IN_USE'],
+
+  async handler(ctx) {
+    // Only a lobby, and only through `get`, which also refuses a handle that
+    // is mid-call. This route needs no session — admin lobbies belong to
+    // none — so without the kind filter
+    // `POST /admin/lobby-handle/delete/<tx_…>` discarded another session's
+    // staged transaction, and `<swap_…>` ran `quote.close()` on its live
+    // quote, from an unauthenticated path.
+    ctx.state.objects.get(ctx.params.objectId, 'lobby')
+    const deleted = await ctx.state.objects.delete(ctx.params.objectId)
+    if (!deleted) {
+      throw engineError(
+        'OBJECT_NOT_FOUND',
+        `No object handle: ${ctx.params.objectId}`,
+        404
+      )
+    }
+    return { ok: true }
+  }
+})
+
+/**
+ * Read a lobby's contents.
+ */
+export const adminFetchLobbyRequest = route({
+  core: 'context.$internalStuff.fetchLobbyRequest',
+  method: 'GET',
+  path: '/admin/fetch-lobby-request',
+  cli: { command: 'admin-fetch-lobby-request', positional: 'lobbyId' },
+  query: asObject({ lobbyId: doc(asString, 'Which lobby to read.') }).withRest,
+  returns: doc(asCoreValue, 'The raw lobby request.'),
+  errors: ['NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const { lobbyId } = ctx.query.valid
+    const internal = getInternalStuff(ctx.state.core.context)
+    return await internal.fetchLobbyRequest(lobbyId)
+  }
+})
+
+/**
+ * Reply to a lobby.
+ */
+export const adminSendLobbyReply = route({
+  core: 'context.$internalStuff.sendLobbyReply',
+  method: 'POST',
+  path: '/admin/send-lobby-reply',
+  cli: { command: 'admin-send-lobby-reply', positional: 'lobbyId' },
+  body: asObject({
+    lobbyId: doc(asString, 'Which lobby to answer.'),
+    // Declared as an object, so the 400 comes from the declaration with the
+    // field named, in one layer rather than two with two messages.
+    lobbyRequest: doc(
+      asObject(asUnknown),
+      'Normally the object from `admin-fetch-lobby-request`.'
+    ),
+    replyData: asOptional(doc(asCoreValue, 'Payload for the requester.'))
+  }).withRest,
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const body = ctx.body
+    const { lobbyId } = body
+    const internal = getInternalStuff(ctx.state.core.context)
+    await internal.sendLobbyReply(
+      lobbyId,
+      body.lobbyRequest as LobbyRequest,
+      body.replyData
+    )
+    return undefined
+  }
+})
+
+/**
+ * Sync a repo.
+ */
+export const adminSyncRepo = route({
+  core: 'context.$internalStuff.syncRepo',
+  method: 'POST',
+  path: '/admin/sync-repo',
+  cli: { command: 'admin-sync-repo', positional: 'syncKey' },
+  body: asObject({ syncKey: doc(asString, 'Base58 repo sync key.') }).withRest,
+  returns: doc(asCoreValue, 'The changeset summary.'),
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const body = ctx.body
+    const { syncKey } = body
+    const internal = getInternalStuff(ctx.state.core.context)
+    return await internal.syncRepo(base58.parse(syncKey))
+  }
+})
+
+/**
+ * List repo contents.
+ */
+export const adminRepoList = route({
+  core: 'context.$internalStuff.getRepoDisklet',
+  method: 'GET',
+  path: '/admin/repo-list',
+  cli: { command: 'admin-repo-list', positional: 'syncKey' },
+  query: asObject({
+    ...REPO_KEYS,
+    path: asOptional(doc(asString, 'Subdirectory. Defaults to the repo root.'))
+  }).withRest,
+  returns: asObject({
+    listing: doc(asCoreValue, 'Path to entry type: `file` or `folder`.')
+  }),
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const { syncKey, dataKey } = ctx.query.valid
+    const path = ctx.query.valid.path ?? ''
+    const internal = getInternalStuff(ctx.state.core.context)
+    const disklet = await internal.getRepoDisklet(
+      base58.parse(syncKey),
+      base58.parse(dataKey)
+    )
+    const listing = await disklet.list(path)
+    return { listing }
+  }
+})
+
+/**
+ * Read a repo file.
+ */
+export const adminRepoGet = route({
+  core: 'context.$internalStuff.getRepoDisklet',
+  method: 'GET',
+  path: '/admin/repo-get',
+  cli: { command: 'admin-repo-get', positional: 'syncKey' },
+  query: asObject({
+    ...REPO_KEYS,
+    path: doc(asString, 'Path within the repo.')
+  }).withRest,
+  returns: asObject({ text: doc(asString, 'The file contents.') }),
+  errors: ['NOT_FOUND', 'BAD_REQUEST'],
+
+  async handler(ctx) {
+    const { syncKey, dataKey, path } = ctx.query.valid
+    const internal = getInternalStuff(ctx.state.core.context)
+    const disklet = await internal.getRepoDisklet(
+      base58.parse(syncKey),
+      base58.parse(dataKey)
+    )
+    const text = await disklet.getText(path)
+    return { text }
+  }
+})
+
+/**
+ * Write a repo file.
+ *
+ * Writes directly into a synced repo, bypassing every core-level invariant. A
+ * malformed write can break the account for real clients.
+ */
+export const adminRepoSet = route({
+  core: 'context.$internalStuff.getRepoDisklet',
+  method: 'POST',
+  path: '/admin/repo-set',
+  cli: { command: 'admin-repo-set', positional: 'syncKey' },
+  body: asObject({
+    ...REPO_KEYS,
+    path: doc(asString, 'Path within the repo.'),
+    text: doc(asString, 'The contents to write.')
+  }).withRest,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const body = ctx.body
+    const { syncKey, dataKey, path, text } = body
+    const internal = getInternalStuff(ctx.state.core.context)
+    const disklet = await internal.getRepoDisklet(
+      base58.parse(syncKey),
+      base58.parse(dataKey)
+    )
+    await disklet.setText(path, text)
+    return undefined
+  }
+})
+
+/**
+ * Delete a repo file.
+ *
+ * Destructive, and not undoable from this API.
+ */
+export const adminRepoDelete = route({
+  core: 'context.$internalStuff.getRepoDisklet',
+  method: 'POST',
+  path: '/admin/repo-delete',
+  cli: { command: 'admin-repo-delete', positional: 'syncKey' },
+  body: asObject({ ...REPO_KEYS, path: doc(asString, 'Path within the repo.') })
+    .withRest,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const body = ctx.body
+    const { syncKey, dataKey, path } = body
+    const internal = getInternalStuff(ctx.state.core.context)
+    const disklet = await internal.getRepoDisklet(
+      base58.parse(syncKey),
+      base58.parse(dataKey)
+    )
+    await disklet.delete(path)
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/credentials.ts b/src/cli/engine/routes/credentials.ts
new file mode 100644
index 00000000000..3d13c7d4feb
--- /dev/null
+++ b/src/cli/engine/routes/credentials.ts
@@ -0,0 +1,252 @@
+import {
+  asArray,
+  asBoolean,
+  asEither,
+  asObject,
+  asOptional,
+  asString,
+  asValue
+} from 'cleaners'
+
+import { doc } from '../doc'
+import { route } from '../route'
+import { getAccount } from './helpers'
+
+const PASSWORD_DOC = 'The account password.'
+const PIN_DOC = 'The device PIN, usually four digits.'
+const DURESS_DOC = 'Act on the duress account rather than the real one.'
+
+/**
+ * Set or change the password.
+ *
+ * The login server enforces its own rules; `check-password-rules` scores a
+ * candidate first.
+ */
+export const changePassword = route({
+  core: 'account.changePassword',
+  method: 'POST',
+  path: '/account/{sessionId}/change-password',
+  cli: 'change-password',
+  body: asObject({ password: doc(asString, 'The new password.') }).withRest,
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).changePassword(ctx.body.password)
+    return undefined
+  }
+})
+
+/**
+ * Remove password login.
+ *
+ * The account keeps its other login methods; only the password stops working.
+ */
+export const deletePassword = route({
+  core: 'account.deletePassword',
+  method: 'POST',
+  path: '/account/{sessionId}/delete-password',
+  cli: 'delete-password',
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).deletePassword()
+    return undefined
+  }
+})
+
+/**
+ * Verify a password.
+ *
+ * Checks without changing anything, which is how a caller gates a destructive
+ * action behind a re-entry prompt.
+ */
+export const checkPassword = route({
+  core: 'account.checkPassword',
+  method: 'POST',
+  path: '/account/{sessionId}/check-password',
+  cli: 'check-password',
+  body: asObject({ password: doc(asString, PASSWORD_DOC) }).withRest,
+  returns: asObject({
+    ok: doc(asBoolean, 'False for a wrong password — not an error response.')
+  }),
+
+  async handler(ctx) {
+    return { ok: await getAccount(ctx).checkPassword(ctx.body.password) }
+  }
+})
+
+/**
+ * Read the account PIN.
+ *
+ * Returns the PIN itself, not a status flag, so treat the output as secret.
+ */
+export const getPin = route({
+  core: 'account.getPin',
+  method: 'GET',
+  path: '/account/{sessionId}/get-pin',
+  cli: 'get-pin',
+  returns: asObject({
+    pin: doc(asEither(asString, asValue(null)), 'Null when no PIN is set.')
+  }),
+
+  async handler(ctx) {
+    const pin = await getAccount(ctx).getPin()
+    return { pin: pin ?? null }
+  }
+})
+
+/**
+ * Set or change the PIN.
+ */
+export const changePin = route({
+  core: 'account.changePin',
+  method: 'POST',
+  path: '/account/{sessionId}/change-pin',
+  cli: 'change-pin',
+  body: asObject({
+    pin: doc(asString, 'The new PIN.'),
+    enableLogin: asOptional(
+      doc(asBoolean, 'Allow logging in with this PIN on this device.')
+    ),
+    forDuressAccount: asOptional(doc(asBoolean, DURESS_DOC))
+  }).withRest,
+  returns: asObject({
+    pin2Key: doc(asString, 'The new PIN login key core returns.')
+  }),
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const pin2Key = await getAccount(ctx).changePin({
+      pin: ctx.body.pin,
+      enableLogin: ctx.body.enableLogin,
+      forDuressAccount: ctx.body.forDuressAccount
+    })
+    return { pin2Key }
+  }
+})
+
+/**
+ * Remove the PIN.
+ *
+ * PIN login stops working on this device; other methods are untouched.
+ */
+export const deletePin = route({
+  core: 'account.deletePin',
+  method: 'POST',
+  path: '/account/{sessionId}/delete-pin',
+  cli: 'delete-pin',
+
+  async handler(ctx) {
+    await getAccount(ctx).deletePin()
+    return undefined
+  }
+})
+
+/**
+ * Verify a PIN.
+ */
+export const checkPin = route({
+  core: 'account.checkPin',
+  method: 'POST',
+  path: '/account/{sessionId}/check-pin',
+  cli: 'check-pin',
+  body: asObject({
+    pin: doc(asString, PIN_DOC),
+    forDuressAccount: asOptional(doc(asBoolean, DURESS_DOC))
+  }).withRest,
+  returns: asObject({
+    ok: doc(asBoolean, 'False for a wrong PIN — not an error response.')
+  }),
+
+  async handler(ctx) {
+    const ok = await getAccount(ctx).checkPin(ctx.body.pin, {
+      forDuressAccount: ctx.body.forDuressAccount
+    })
+    return { ok }
+  }
+})
+
+/**
+ * Change the username.
+ *
+ * The old name is released, so it becomes available to anyone else.
+ */
+export const changeUsername = route({
+  core: 'account.changeUsername',
+  method: 'POST',
+  path: '/account/{sessionId}/change-username',
+  cli: 'change-username',
+  body: asObject({
+    username: doc(asString, 'The new username.'),
+    password: asOptional(
+      doc(asString, 'Required by core when the account has a password.')
+    )
+  }).withRest,
+  errors: ['USERNAME_ERROR', 'BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).changeUsername({
+      username: ctx.body.username,
+      password: ctx.body.password
+    })
+    return undefined
+  }
+})
+
+/**
+ * Set recovery questions and answers.
+ *
+ * The returned key is half of the credential: without it the answers alone
+ * cannot recover the account, so it has to be stored somewhere else.
+ *
+ * @coreNote Our surface drops the `2` from core's recovery2 naming; a future
+ *   Recovery1 would be suffixed `V1`.
+ */
+export const changeRecovery = route({
+  core: 'account.changeRecovery',
+  method: 'POST',
+  path: '/account/{sessionId}/change-recovery',
+  cli: {
+    command: 'change-recovery',
+    flags: {
+      question: { maps: 'questions', repeat: true },
+      answer: { maps: 'answers', repeat: true }
+    }
+  },
+  body: asObject({
+    questions: doc(asArray(asString), 'The questions to ask.'),
+    answers: doc(asArray(asString), 'Same length and order as `questions`.')
+  }).withRest,
+  returns: asObject({
+    recoveryKey: doc(
+      asString,
+      'Store this out of band. `login-with-recovery` needs it alongside the answers.'
+    )
+  }),
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const recoveryKey = await getAccount(ctx).changeRecovery(
+      ctx.body.questions,
+      ctx.body.answers
+    )
+    return { recoveryKey }
+  }
+})
+
+/**
+ * Disable recovery login.
+ *
+ * The existing recovery key stops working.
+ */
+export const deleteRecovery = route({
+  core: 'account.deleteRecovery',
+  method: 'POST',
+  path: '/account/{sessionId}/delete-recovery',
+  cli: 'delete-recovery',
+
+  async handler(ctx) {
+    await getAccount(ctx).deleteRecovery()
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/dataStore.ts b/src/cli/engine/routes/dataStore.ts
new file mode 100644
index 00000000000..286bafcb771
--- /dev/null
+++ b/src/cli/engine/routes/dataStore.ts
@@ -0,0 +1,157 @@
+import { asArray, asObject, asString } from 'cleaners'
+
+import { doc } from '../doc'
+import { EngineError, engineError } from '../errors'
+import { route } from '../route'
+import { getAccount } from './helpers'
+
+const STORE_ID_DOC = 'Plugin or app namespace within the account data store.'
+const ITEM_ID_DOC = 'Key within the store.'
+
+/**
+ * List data-store ids.
+ *
+ * The account's synced key-value store, where plugins keep their own state.
+ */
+export const listStoreIds = route({
+  core: 'account.dataStore.listStoreIds',
+  method: 'GET',
+  path: '/account/{sessionId}/list-store-ids',
+  cli: 'list-store-ids',
+  returns: asObject({
+    storeIds: doc(asArray(asString), 'Every store holding at least one item.')
+  }),
+
+  async handler(ctx) {
+    return { storeIds: await getAccount(ctx).dataStore.listStoreIds() }
+  }
+})
+
+/**
+ * List item ids in a store.
+ */
+export const listItemIds = route({
+  core: 'account.dataStore.listItemIds',
+  method: 'GET',
+  path: '/account/{sessionId}/list-item-ids',
+  cli: 'list-item-ids',
+  query: asObject({ storeId: doc(asString, STORE_ID_DOC) }).withRest,
+  returns: asObject({
+    itemIds: doc(asArray(asString), 'Keys in this store. Empty if it has none.')
+  }),
+
+  async handler(ctx) {
+    const itemIds = await getAccount(ctx).dataStore.listItemIds(
+      ctx.query.valid.storeId
+    )
+    return { itemIds }
+  }
+})
+
+/**
+ * Read an item.
+ *
+ * Values are opaque strings; encoding is the caller's business.
+ */
+export const getItem = route({
+  core: 'account.dataStore.getItem',
+  method: 'GET',
+  path: '/account/{sessionId}/get-item',
+  cli: 'get-item',
+  query: asObject({
+    storeId: doc(asString, STORE_ID_DOC),
+    itemId: doc(asString, ITEM_ID_DOC)
+  }).withRest,
+  returns: asObject({ value: doc(asString, 'The stored string.') }),
+  errors: ['NOT_FOUND', 'BAD_REQUEST'],
+
+  async handler(ctx) {
+    const { storeId, itemId } = ctx.query.valid
+    // The account is resolved outside the `try`: a session error is a 401,
+    // and rewriting it as a 404 told a scripted caller that the item was
+    // missing rather than that it had to log in again.
+    const account = getAccount(ctx)
+    try {
+      const value = await account.dataStore.getItem(storeId, itemId)
+      return { value }
+    } catch (error: unknown) {
+      // Anything that already carries a code and a status says what it means.
+      if (error instanceof EngineError) throw error
+      // core throws a plain Error for an absent item, which would otherwise
+      // surface as an engine fault rather than the 404 this route declares.
+      throw engineError(
+        'NOT_FOUND',
+        error instanceof Error
+          ? error.message
+          : `No item ${itemId} in store ${storeId}`,
+        404
+      )
+    }
+  }
+})
+
+/**
+ * Write an item.
+ *
+ * Creates the store if it does not exist.
+ */
+export const setItem = route({
+  core: 'account.dataStore.setItem',
+  method: 'POST',
+  path: '/account/{sessionId}/set-item',
+  cli: 'set-item',
+  body: asObject({
+    storeId: doc(asString, STORE_ID_DOC),
+    itemId: doc(asString, ITEM_ID_DOC),
+    value: doc(asString, 'The string to store.')
+  }).withRest,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const { storeId, itemId, value } = ctx.body
+    await getAccount(ctx).dataStore.setItem(storeId, itemId, value)
+    return undefined
+  }
+})
+
+/**
+ * Delete an item.
+ */
+export const deleteItem = route({
+  core: 'account.dataStore.deleteItem',
+  method: 'POST',
+  path: '/account/{sessionId}/delete-item',
+  cli: 'delete-item',
+  body: asObject({
+    storeId: doc(asString, STORE_ID_DOC),
+    itemId: doc(asString, ITEM_ID_DOC)
+  }).withRest,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    await getAccount(ctx).dataStore.deleteItem(
+      ctx.body.storeId,
+      ctx.body.itemId
+    )
+    return undefined
+  }
+})
+
+/**
+ * Delete an entire store.
+ *
+ * Removes every item in it, which cannot be undone from this API.
+ */
+export const deleteStore = route({
+  core: 'account.dataStore.deleteStore',
+  method: 'POST',
+  path: '/account/{sessionId}/delete-store',
+  cli: 'delete-store',
+  body: asObject({ storeId: doc(asString, STORE_ID_DOC) }).withRest,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    await getAccount(ctx).dataStore.deleteStore(ctx.body.storeId)
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/index.ts b/src/cli/engine/routes/index.ts
index 04fc36cebbb..ae3d3708e88 100644
--- a/src/cli/engine/routes/index.ts
+++ b/src/cli/engine/routes/index.ts
@@ -5,11 +5,26 @@
  * importing the module is all the registration a route needs.
  */
 import './account'
+import './admin'
 import './context'
+import './credentials'
+import './dataStore'
 import './events'
+import './keys'
+import './lobby'
+import './localSettings'
 import './login'
 import './objects'
+import './otp'
+import './rates'
+import './spend'
 import './status'
+import './swap'
+import './tokens'
+import './transactions'
+import './uri'
+import './vouchers'
+import './wallets'
 
 import { allRoutes, registerRoute } from '../route'
 import type { Router } from '../router'
diff --git a/src/cli/engine/routes/keys.ts b/src/cli/engine/routes/keys.ts
new file mode 100644
index 00000000000..c6049cfe956
--- /dev/null
+++ b/src/cli/engine/routes/keys.ts
@@ -0,0 +1,273 @@
+import {
+  asArray,
+  asBoolean,
+  asNumber,
+  asObject,
+  asOptional,
+  asString
+} from 'cleaners'
+import type { EdgeWalletStates } from 'edge-core-js'
+
+import { doc } from '../doc'
+import { engineError } from '../errors'
+import { findWallet } from '../resolve'
+import { route } from '../route'
+import type { RouteContext } from '../router'
+import { asCoreValue, asWalletId, asWalletKeys } from '../schemas'
+import { getAccount } from './helpers'
+
+/**
+ * The full wallet id behind a `walletId` query field.
+ *
+ * These routes hand the id straight to core, which only knows full ids. The
+ * documented contract is that any unique prefix works, so resolve it here
+ * rather than making these five calls the exceptions.
+ */
+function walletIdFor(
+  ctx: RouteContext & {
+    query: { valid: { walletId: string } }
+  }
+): string {
+  return findWallet(getAccount(ctx), ctx.query.valid.walletId).id
+}
+
+const asWalletIdQuery = asObject({ walletId: asWalletId }).withRest
+
+/**
+ * List every key in the account.
+ *
+ * Includes archived and deleted keys, unlike `currency-wallets`.
+ */
+export const allKeys = route({
+  core: 'account.allKeys',
+  method: 'GET',
+  path: '/account/{sessionId}/all-keys',
+  cli: 'all-keys',
+  returns: asObject({
+    allKeys: doc(
+      asArray(asCoreValue),
+      '`EdgeWalletInfoFull[]`: id, type, keys, archived, deleted, hidden, sortIndex.'
+    )
+  }),
+
+  handler(ctx) {
+    return { allKeys: getAccount(ctx).allKeys }
+  }
+})
+
+/**
+ * Create a wallet from raw key JSON.
+ *
+ * The import path. Use `create-currency-wallet` to make a fresh wallet with
+ * generated keys.
+ */
+export const createWallet = route({
+  core: 'account.createWallet',
+  method: 'POST',
+  path: '/account/{sessionId}/create-wallet',
+  cli: 'create-wallet',
+  body: asObject({
+    type: doc(asString, 'Wallet type, e.g. `wallet:bitcoin`.'),
+    keys: asOptional(
+      doc(asWalletKeys, 'Plugin key material. Omit to let core generate it.')
+    )
+  }).withRest,
+  returns: asObject({
+    walletId: doc(asString, 'The new wallet. Its keys are already saved.')
+  }),
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    const walletId = await getAccount(ctx).createWallet(
+      ctx.body.type,
+      ctx.body.keys
+    )
+    return { walletId }
+  }
+})
+
+/**
+ * Read one wallet's key info.
+ *
+ * @note An exact lookup: unlike the wallet-scoped routes this does not accept
+ *   an id prefix.
+ */
+export const getWalletInfo = route({
+  core: 'account.getWalletInfo',
+  method: 'GET',
+  path: '/account/{sessionId}/get-wallet-info',
+  cli: 'get-wallet-info',
+  query: asObject({
+    id: doc(asString, 'The key id, from `all-keys`. Base64, like a wallet id.')
+  }).withRest,
+  returns: doc(
+    asCoreValue,
+    '`EdgeWalletInfoFull`, verbatim from core — including the `keys` object.'
+  ),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  handler(ctx) {
+    const info = getAccount(ctx).getWalletInfo(ctx.query.valid.id)
+    if (info == null) {
+      throw engineError(
+        'WALLET_NOT_FOUND',
+        `No wallet found matching: ${ctx.query.valid.id}`,
+        404
+      )
+    }
+    return info
+  }
+})
+
+/**
+ * Read raw private key material.
+ *
+ * Secret. Whatever the plugin stores — seed, mnemonic, xpriv.
+ */
+export const getRawPrivateKey = route({
+  core: 'account.getRawPrivateKey',
+  method: 'GET',
+  path: '/account/{sessionId}/get-raw-private-key',
+  cli: 'get-raw-private-key',
+  query: asWalletIdQuery,
+  returns: doc(asCoreValue, 'The plugin’s key object, at the top level.'),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    return await account.getRawPrivateKey(walletIdFor(ctx))
+  }
+})
+
+/**
+ * Read raw public key material.
+ */
+export const getRawPublicKey = route({
+  core: 'account.getRawPublicKey',
+  method: 'GET',
+  path: '/account/{sessionId}/get-raw-public-key',
+  cli: 'get-raw-public-key',
+  query: asWalletIdQuery,
+  returns: doc(asCoreValue, 'The plugin’s public key object.'),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    return await account.getRawPublicKey(walletIdFor(ctx))
+  }
+})
+
+/**
+ * Export the private key for display.
+ *
+ * Secret. The human-facing form — WIF, seed phrase, whatever the plugin shows
+ * on its export screen.
+ */
+export const getDisplayPrivateKey = route({
+  core: 'account.getDisplayPrivateKey',
+  method: 'GET',
+  path: '/account/{sessionId}/get-display-private-key',
+  cli: 'get-display-private-key',
+  query: asWalletIdQuery,
+  returns: asObject({ key: doc(asString, 'The displayable private key.') }),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const key = await getAccount(ctx).getDisplayPrivateKey(walletIdFor(ctx))
+    return { key }
+  }
+})
+
+/**
+ * Export the public key for display.
+ *
+ * The xpub or equivalent — safe to share for watch-only use.
+ */
+export const getDisplayPublicKey = route({
+  core: 'account.getDisplayPublicKey',
+  method: 'GET',
+  path: '/account/{sessionId}/get-display-public-key',
+  cli: 'get-display-public-key',
+  query: asWalletIdQuery,
+  returns: asObject({ key: doc(asString, 'The displayable public key.') }),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const key = await getAccount(ctx).getDisplayPublicKey(walletIdFor(ctx))
+    return { key }
+  }
+})
+
+/**
+ * List chains a wallet can split into.
+ *
+ * Forked-chain support: which wallet types can be derived from these keys.
+ */
+export const listSplittableWalletTypes = route({
+  core: 'account.listSplittableWalletTypes',
+  method: 'GET',
+  path: '/account/{sessionId}/list-splittable-wallet-types',
+  cli: 'list-splittable-wallet-types',
+  query: asWalletIdQuery,
+  returns: asObject({
+    walletTypes: doc(asArray(asString), 'Types valid for `split`.')
+  }),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const walletTypes = await getAccount(ctx).listSplittableWalletTypes(
+      walletIdFor(ctx)
+    )
+    return { walletTypes }
+  }
+})
+
+/**
+ * Archive, delete, hide, or reorder wallets.
+ *
+ * The canonical backend for every wallet flag; there are no separate archive,
+ * unarchive or undelete verbs.
+ */
+export const changeWalletStates = route({
+  core: 'account.changeWalletStates',
+  method: 'POST',
+  path: '/account/{sessionId}/change-wallet-states',
+  cli: {
+    command: 'change-wallet-states',
+    custom: true,
+    extra: {
+      walletId: {
+        kind: 'string',
+        required: true,
+        doc: 'The wallet to change. The command makes it the key of a single-entry `walletStates` map.'
+      },
+      archived: { kind: 'boolstr', doc: 'Hide from the active list.' },
+      deleted: { kind: 'boolstr', doc: 'Mark deleted.' },
+      hidden: { kind: 'boolstr', doc: 'Hide from the wallet picker.' },
+      sortIndex: { kind: 'string', doc: 'Position in the wallet list.' }
+    },
+    notes:
+      'The command builds a single-wallet `walletStates` map from these flags, and needs at least one.'
+  },
+  body: asObject({
+    walletStates: doc(
+      asObject(
+        asObject({
+          archived: asOptional(asBoolean),
+          deleted: asOptional(asBoolean),
+          hidden: asOptional(asBoolean),
+          sortIndex: asOptional(asNumber)
+        }).withRest
+      ),
+      '`EdgeWalletStates`: wallet ids to the flags being changed.'
+    )
+  }).withRest,
+  errors: ['BAD_REQUEST'],
+
+  async handler(ctx) {
+    await getAccount(ctx).changeWalletStates(
+      ctx.body.walletStates as unknown as EdgeWalletStates
+    )
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/lobby.ts b/src/cli/engine/routes/lobby.ts
new file mode 100644
index 00000000000..428876094de
--- /dev/null
+++ b/src/cli/engine/routes/lobby.ts
@@ -0,0 +1,94 @@
+import { asEither, asObject, asString, asValue } from 'cleaners'
+
+import { doc } from '../doc'
+import { engineError } from '../errors'
+import { route } from '../route'
+import { asOk } from '../schemas'
+import { getAccount } from './helpers'
+
+const LOBBY_ID_DOC = 'From the QR code, or an `edge://edge/<lobbyId>` link.'
+
+/**
+ * Inspect a login request.
+ *
+ * The other side of `request-edge-login`: shows who is asking, so a human can
+ * decide before approving.
+ */
+export const fetchLobby = route({
+  core: 'account.fetchLobby',
+  method: 'GET',
+  path: '/account/{sessionId}/fetch-lobby',
+  cli: { command: 'fetch-lobby', positional: 'lobbyId' },
+  query: asObject({ lobbyId: doc(asString, LOBBY_ID_DOC) }).withRest,
+  returns: asObject({
+    lobbyId: doc(asString, 'The lobby that was fetched, echoed back.'),
+    loginRequest: doc(
+      asEither(
+        asObject({
+          appId: asString,
+          displayName: asString,
+          displayImageDarkUrl: asEither(asString, asValue(null)),
+          displayImageLightUrl: asEither(asString, asValue(null))
+        }),
+        asValue(null)
+      ),
+      'Null when the lobby carries no pending login request.'
+    )
+  }),
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const { lobbyId } = ctx.query.valid
+    const lobby = await getAccount(ctx).fetchLobby(lobbyId)
+    const { loginRequest } = lobby
+    return {
+      lobbyId,
+      loginRequest:
+        loginRequest == null
+          ? null
+          : {
+              appId: loginRequest.appId,
+              displayName: loginRequest.displayName,
+              displayImageDarkUrl: loginRequest.displayImageDarkUrl ?? null,
+              displayImageLightUrl: loginRequest.displayImageLightUrl ?? null
+            }
+    }
+  }
+})
+
+/**
+ * Approve a login request.
+ *
+ * Grants the requesting device access to this account.
+ *
+ * @note The lobby is re-fetched on approve, so a request that expired between
+ *   inspecting and approving fails with `404 NO_LOGIN_REQUEST`.
+ * @coreNote Reached through account.fetchLobby(lobbyId).loginRequest.
+ */
+export const approveLoginRequest = route({
+  core: 'EdgeLoginRequest.approve',
+  coreExtra: {
+    lobbyId:
+      'Core calls approve() on a request object. Over HTTP there is no ' +
+      'object to hold, so the lobby names which one to approve.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/approve-login-request',
+  cli: { command: 'approve-login-request', positional: 'lobbyId' },
+  body: asObject({ lobbyId: doc(asString, LOBBY_ID_DOC) }).withRest,
+  returns: asOk,
+  errors: ['NO_LOGIN_REQUEST', 'BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const lobby = await getAccount(ctx).fetchLobby(ctx.body.lobbyId)
+    if (lobby.loginRequest == null) {
+      throw engineError(
+        'NO_LOGIN_REQUEST',
+        'Lobby has no pending login request',
+        404
+      )
+    }
+    await lobby.loginRequest.approve()
+    return { ok: true }
+  }
+})
diff --git a/src/cli/engine/routes/localSettings.ts b/src/cli/engine/routes/localSettings.ts
new file mode 100644
index 00000000000..33d6f4f645e
--- /dev/null
+++ b/src/cli/engine/routes/localSettings.ts
@@ -0,0 +1,90 @@
+import { asBoolean, asObject } from 'cleaners'
+
+import {
+  readLocalAccountSettingsFromDisk,
+  readLocalAccountSettingsOrDefaults,
+  writeLocalAccountSettingsToDisk
+} from '../../../util/localAccountSettings'
+import { serializeByKey } from '../../../util/serializeByKey'
+import { doc } from '../doc'
+import { route } from '../route'
+import { getAccount } from './helpers'
+
+const SPAM_FILTER_DOC =
+  'Hide spam transactions in `get-transactions` results. Defaults to `true`, ' +
+  'matching the GUI. The filter hides rows; it never changes stored metadata.'
+
+/** Every device-local setting. One today; new ones are added as fields here. */
+const asLocalSettings = asObject({
+  spamFilterOn: doc(asBoolean, SPAM_FILTER_DOC)
+})
+
+/**
+ * Local settings.
+ *
+ * Device-local account settings, stored in `Settings.json` on
+ * `account.localDisklet`. They are not synced — a phone and a CLI keep
+ * separate copies unless they share an Edge data directory.
+ *
+ * @coreNote GUI code (src/util/localAccountSettings), reached through
+ *   account.localDisklet.
+ */
+export const localSettings = route({
+  core: null,
+  method: 'GET',
+  path: '/account/{sessionId}/local-settings',
+  cli: { command: 'local-settings', custom: true },
+  returns: asLocalSettings,
+
+  async handler(ctx) {
+    // Lenient: a read-only route must not answer 500 for a file it could
+    // report defaults for. The read-modify-write below stays strict, because
+    // there the defaults would be written back.
+    const { settings } = await readLocalAccountSettingsOrDefaults(
+      getAccount(ctx)
+    )
+    return { spamFilterOn: settings.spamFilterOn }
+  }
+})
+
+/**
+ * Change local settings.
+ *
+ * Writes device-local account settings. Every option is a field on the body;
+ * `spamFilterOn` is the only one today, and new options are added alongside it.
+ *
+ * @note Omitting a field is a `400`, not a no-op, so a caller cannot clear a
+ *   setting by accident.
+ * @coreNote GUI code (src/util/localAccountSettings).
+ */
+export const changeLocalSettings = route({
+  core: null,
+  method: 'POST',
+  path: '/account/{sessionId}/change-local-settings',
+  cli: {
+    command: 'local-settings',
+    custom: true,
+    notes: 'With no flag the command reads; with one it writes.'
+  },
+  body: asLocalSettings.withRest,
+  returns: asLocalSettings,
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    // Read-modify-write over the whole `Settings.json`, so two concurrent
+    // writes must not interleave: the loser's fields would be silently
+    // dropped, and the route's own note says new settings are "added
+    // alongside it", so the blast radius grows with every option.
+    return await serializeByKey(
+      `localSettings:${account.rootLoginId}`,
+      async () => {
+        const settings = await readLocalAccountSettingsFromDisk(account)
+        const updated = await writeLocalAccountSettingsToDisk(account, {
+          ...settings,
+          spamFilterOn: ctx.body.spamFilterOn
+        })
+        return { spamFilterOn: updated.spamFilterOn }
+      }
+    )
+  }
+})
diff --git a/src/cli/engine/routes/otp.ts b/src/cli/engine/routes/otp.ts
new file mode 100644
index 00000000000..bfb025a4010
--- /dev/null
+++ b/src/cli/engine/routes/otp.ts
@@ -0,0 +1,129 @@
+import { asEither, asObject, asOptional, asString, asValue } from 'cleaners'
+
+import { doc } from '../doc'
+import { route } from '../route'
+import { asBodyNumber } from '../schemas'
+import { getAccount } from './helpers'
+
+const OTP_KEY_DOC = 'The 2FA secret itself. Secret material — record it safely.'
+
+/**
+ * Read the 2FA secret and reset state.
+ *
+ * @coreNote Also carries account.otpResetDate.
+ */
+export const otpKey = route({
+  core: 'account.otpKey',
+  method: 'GET',
+  path: '/account/{sessionId}/otp-key',
+  cli: 'otp-key',
+  returns: asObject({
+    otpKey: doc(
+      asEither(asString, asValue(null)),
+      'Null when 2FA is off. ' + OTP_KEY_DOC
+    ),
+    otpResetDate: doc(
+      asEither(asString, asValue(null)),
+      'Set once somebody has requested a reset; cancel it with `cancel-otp-reset`.'
+    )
+  }),
+
+  handler(ctx) {
+    const account = getAccount(ctx)
+    return {
+      otpKey: account.otpKey ?? null,
+      otpResetDate: account.otpResetDate?.toISOString() ?? null
+    }
+  }
+})
+
+/**
+ * Enable 2FA.
+ *
+ * Record the returned key before leaving the terminal: it is the only copy.
+ */
+export const enableOtp = route({
+  core: 'account.enableOtp',
+  method: 'POST',
+  path: '/account/{sessionId}/enable-otp',
+  cli: 'enable-otp',
+  body: asObject({
+    // `asBodyNumber`, not `asNumber`: the CLI puts a flag's raw text into
+    // the body, so `enable-otp --timeout=604800` sent `{"timeout":"604800"}`
+    // and this command could never succeed.
+    timeout: asOptional(
+      doc(
+        asBodyNumber,
+        'How long a reset request must wait before it completes, in seconds. Core supplies the default when omitted.'
+      )
+    )
+  }).withRest,
+  returns: asObject({
+    otpKey: doc(
+      asEither(asString, asValue(null)),
+      'The new secret. ' + OTP_KEY_DOC
+    )
+  }),
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    await account.enableOtp(ctx.body.timeout)
+    return { otpKey: account.otpKey ?? null }
+  }
+})
+
+/**
+ * Disable 2FA.
+ *
+ * Logins stop requiring a code immediately.
+ */
+export const disableOtp = route({
+  core: 'account.disableOtp',
+  method: 'POST',
+  path: '/account/{sessionId}/disable-otp',
+  cli: 'disable-otp',
+
+  async handler(ctx) {
+    await getAccount(ctx).disableOtp()
+    return undefined
+  }
+})
+
+/**
+ * Cancel a pending 2FA reset.
+ *
+ * The defence against somebody else requesting a reset on your account: as
+ * long as you cancel before the timer runs out, their reset never lands.
+ */
+export const cancelOtpReset = route({
+  core: 'account.cancelOtpReset',
+  method: 'POST',
+  path: '/account/{sessionId}/cancel-otp-reset',
+  cli: 'cancel-otp-reset',
+
+  async handler(ctx) {
+    await getAccount(ctx).cancelOtpReset()
+    return undefined
+  }
+})
+
+/**
+ * Re-point the account at a known 2FA secret.
+ *
+ * For a device whose stored secret has drifted from the server's.
+ */
+export const repairOtp = route({
+  core: 'account.repairOtp',
+  method: 'POST',
+  path: '/account/{sessionId}/repair-otp',
+  cli: 'repair-otp',
+  body: asObject({
+    otpKey: doc(asString, 'The secret the account should use.')
+  }).withRest,
+  errors: ['OTP_REQUIRED', 'BAD_REQUEST'],
+
+  async handler(ctx) {
+    await getAccount(ctx).repairOtp(ctx.body.otpKey)
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/rates.ts b/src/cli/engine/routes/rates.ts
new file mode 100644
index 00000000000..b2327a149dc
--- /dev/null
+++ b/src/cli/engine/routes/rates.ts
@@ -0,0 +1,252 @@
+import { floor, mul } from 'biggystring'
+import { asArray, asNumber, asObject, asOptional, asString } from 'cleaners'
+import type { EdgeFetchFunction } from 'edge-core-js'
+
+import {
+  getHistoricalCryptoRate,
+  getHistoricalFiatRate
+} from '../../../util/exchangeRates'
+import { doc } from '../doc'
+import { engineError } from '../errors'
+import { TOKEN_ID_DOC } from '../fieldDocs'
+import { route } from '../route'
+import { asPositiveBiggystring, asRequestTokenId, asTokenId } from '../schemas'
+
+const nodeFetch: EdgeFetchFunction = async (uri, opts) =>
+  await fetch(uri, opts as RequestInit)
+
+/**
+ * Scale a whole-coin amount by the asset's multiplier.
+ *
+ * `floor` because a native amount is an integer number of the smallest unit,
+ * and biggystring rejects a malformed amount instead of scrubbing it into a
+ * plausible-looking number.
+ */
+function displayToNative(displayAmount: string, multiplier: string): string {
+  return floor(mul(displayAmount, multiplier), 0)
+}
+
+const TARGET_FIAT_DOC = 'ISO 4217 code to price against. Defaults to `iso:USD`.'
+const DATE_DOC =
+  'ISO-8601. Omitted, the current time is sent to the rates server.'
+
+const asCryptoQuery = asObject({
+  pluginId: doc(asString, 'Which chain, e.g. `bitcoin`.'),
+  tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+  targetFiat: asOptional(doc(asString, TARGET_FIAT_DOC)),
+  date: asOptional(doc(asString, DATE_DOC))
+}).withRest
+
+const asFiatQuery = asObject({
+  fiatCode: doc(asString, 'The fiat to price, e.g. `EUR`.'),
+  targetFiat: asOptional(doc(asString, TARGET_FIAT_DOC)),
+  date: asOptional(doc(asString, DATE_DOC))
+}).withRest
+
+/**
+ * Batch crypto and fiat rate lookups.
+ *
+ * Concurrent lookups share one rates-server queue, so asking for many rates at
+ * once costs a single upstream request.
+ *
+ * @note A rate the server cannot supply comes back as `0` rather than an
+ *   error, so check for zero before dividing.
+ * @coreNote GUI code (src/util/exchangeRates): getHistoricalCryptoRate and
+ *   getHistoricalFiatRate.
+ */
+export const ratesQuery = route({
+  core: null,
+  method: 'POST',
+  path: '/rates/query',
+  cli: 'rates-query',
+  body: asObject({
+    crypto: asOptional(doc(asArray(asCryptoQuery), 'Crypto rates to fetch.')),
+    fiat: asOptional(doc(asArray(asFiatQuery), 'Fiat rates to fetch.'))
+  }).withRest,
+  returns: asObject({
+    crypto: doc(
+      asArray(
+        asObject({
+          pluginId: asString,
+          // Response position, so `asTokenId`: the literal string "null" is
+          // a *request* spelling, and publishing it here would describe a
+          // response the engine never sends.
+          tokenId: asTokenId,
+          targetFiat: asString,
+          date: doc(asString, 'The timestamp actually queried.'),
+          rate: asNumber
+        })
+      ),
+      'Always present; empty when no crypto rates were requested.'
+    ),
+    fiat: doc(
+      asArray(
+        asObject({
+          fiatCode: asString,
+          targetFiat: asString,
+          date: asString,
+          rate: asNumber
+        })
+      ),
+      'Always present; empty when no fiat rates were requested.'
+    )
+  }),
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    const cryptoRaw = ctx.body.crypto
+    const fiatRaw = ctx.body.fiat
+    if (
+      (cryptoRaw == null || cryptoRaw.length === 0) &&
+      (fiatRaw == null || fiatRaw.length === 0)
+    ) {
+      throw engineError(
+        'BAD_REQUEST',
+        'Provide at least one crypto or fiat rate query',
+        400
+      )
+    }
+    const now = new Date().toISOString()
+
+    // Both sets are *queued* before either is awaited. Awaiting the crypto
+    // lookups first and only then starting the fiat ones made a mixed body
+    // pay two `FETCH_FREQUENCY` debounces and two upstream requests:
+    // `exchangeRates` batches crypto and fiat into the same group, but
+    // `inQuery` clears the moment the first pass drains, so the second set
+    // armed a fresh 1,000ms timer. Measured at 2,006ms / 2 requests the old
+    // way against 1,005ms / 1 this way — and this route's own description
+    // promises that asking for many rates at once costs a single request.
+    const cryptoPending = (cryptoRaw ?? []).map(async item => {
+      // Already cleaned by `asRequestTokenId` at the declaration.
+      const tokenId = item.tokenId
+      const targetFiat = item.targetFiat ?? 'iso:USD'
+      const date = item.date ?? now
+      const rate = await getHistoricalCryptoRate(
+        item.pluginId,
+        tokenId,
+        targetFiat,
+        date,
+        undefined,
+        nodeFetch
+      )
+      return { pluginId: item.pluginId, tokenId, targetFiat, date, rate }
+    })
+
+    const fiatPending = (fiatRaw ?? []).map(async item => {
+      const targetFiat = item.targetFiat ?? 'iso:USD'
+      const date = item.date ?? now
+      const rate = await getHistoricalFiatRate(
+        item.fiatCode,
+        targetFiat,
+        date,
+        undefined,
+        nodeFetch
+      )
+      return { fiatCode: item.fiatCode, targetFiat, date, rate }
+    })
+
+    const [crypto, fiat] = await Promise.all([
+      Promise.all(cryptoPending),
+      Promise.all(fiatPending)
+    ])
+    return { crypto, fiat }
+  }
+})
+
+/**
+ * Convert a USD amount into native units.
+ *
+ * Turns a fiat notional into the native amount a spend needs.
+ *
+ * @note `displayAmount` is rounded to 8 decimals before conversion, so assets
+ *   with finer precision lose the tail. For an exact figure use `rates-query`
+ *   and do the arithmetic yourself.
+ * @note `multiplier` is required. The engine has no logged-in account here, so
+ *   it cannot read the asset's denomination from core, and a guessed
+ *   multiplier would return a `nativeAmount` wrong by orders of magnitude
+ *   under a field documented as what a spend takes.
+ * @coreNote GUI code (src/util/exchangeRates): getHistoricalCryptoRate.
+ */
+export const ratesUsdToNative = route({
+  core: null,
+  method: 'POST',
+  path: '/rates/usd-to-native',
+  cli: 'rates-usd-to-native',
+  body: asObject({
+    usdAmount: doc(asPositiveBiggystring, 'A positive decimal string.'),
+    pluginId: doc(asString, 'Which chain to price.'),
+    tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    // `asPositiveBiggystring`, not `asString`. Unvalidated, `"abc"` reached
+    // biggystring and came back as a plain `Error` — `500 INTERNAL_ERROR` on
+    // a route that declares `BAD_REQUEST` — while `""` returned `"0"` and
+    // `"-1"` returned `"-1"`: a silently wrong `nativeAmount` under a field
+    // documented as what a spend actually takes.
+    multiplier: doc(
+      asPositiveBiggystring,
+      'Native units per whole coin, as a positive decimal string. This route is not session-scoped, so the engine cannot read the asset\u2019s denomination from core and will not guess one.'
+    ),
+    date: asOptional(doc(asString, DATE_DOC))
+  }).withRest,
+  returns: asObject({
+    usdAmount: doc(
+      asNumber,
+      'Echoed as a number, though it is sent as a string.'
+    ),
+    pluginId: doc(asString, 'Currency plugin the amount was converted for.'),
+    tokenId: doc(
+      asTokenId,
+      'The asset, or null for the chain\u2019s own coin.'
+    ),
+    multiplier: doc(
+      asString,
+      'Native units per whole coin, which is what `displayAmount` was multiplied by to reach `nativeAmount`.'
+    ),
+    date: doc(asString, 'The timestamp actually used for the rate.'),
+    rate: doc(asNumber, 'USD per whole coin at that date.'),
+    displayAmount: doc(asString, 'Whole coins, to 8 decimal places.'),
+    nativeAmount: doc(asString, 'What a spend actually takes.')
+  }),
+  errors: ['BAD_REQUEST', 'NOT_FOUND', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    // Both numbers are validated by the declaration, so a bad one is the
+    // 400 this route publishes rather than a 500 from biggystring or a
+    // silently wrong `nativeAmount`. The hand-written positivity test that
+    // used to live here only covered `usdAmount`.
+    const usdAmount = Number(ctx.body.usdAmount)
+    const { pluginId } = ctx.body
+    // `asOptional(asRequestTokenId, null)` already guarantees non-undefined.
+    const { tokenId } = ctx.body
+    // Required by the cleaner, so a missing one is already a 400 with the
+    // field named. Guessing would return a `nativeAmount` wrong by orders of
+    // magnitude under a field documented as what a spend actually takes.
+    const { multiplier } = ctx.body
+    const date = ctx.body.date ?? new Date().toISOString()
+    const rate = await getHistoricalCryptoRate(
+      pluginId,
+      tokenId,
+      'iso:USD',
+      date,
+      undefined,
+      nodeFetch
+    )
+    if (!(rate > 0)) {
+      throw engineError(
+        'NOT_FOUND',
+        `No USD rate for ${pluginId}/${String(tokenId)}`,
+        404
+      )
+    }
+    const displayAmount = (usdAmount / rate).toFixed(8)
+    return {
+      usdAmount,
+      pluginId,
+      tokenId,
+      multiplier,
+      date,
+      rate,
+      displayAmount,
+      nativeAmount: displayToNative(displayAmount, multiplier)
+    }
+  }
+})
diff --git a/src/cli/engine/routes/spend.ts b/src/cli/engine/routes/spend.ts
new file mode 100644
index 00000000000..c23d04c0dbd
--- /dev/null
+++ b/src/cli/engine/routes/spend.ts
@@ -0,0 +1,884 @@
+import { asBoolean, asObject, asOptional, asString, asUnknown } from 'cleaners'
+import type {
+  EdgeCurrencyWallet,
+  EdgeMemo,
+  EdgeMetadata,
+  EdgeSpendInfo,
+  EdgeSpendTarget,
+  EdgeTransaction
+} from 'edge-core-js'
+import { base64 } from 'rfc4648'
+
+import { saveTxAndMetadata } from '../../../util/txTagging'
+import { doc } from '../doc'
+import { HANDLE_ERRORS, WALLET_ERRORS } from '../errorGroups'
+import { engineError } from '../errors'
+import type { HandleRecord, ObjectHandleInfo } from '../objectHandles'
+import { assertTokenId, findWallet } from '../resolve'
+import { route } from '../route'
+import type { RouteContext } from '../router'
+import {
+  asCoreValue,
+  type asEdgeMetadata,
+  asOkObject,
+  type asSpendInfo,
+  asSpendShorthandBody,
+  asSweepSpendInfo,
+  asTransactionHandle,
+  asTransactionInput,
+  asWalletId
+} from '../schemas'
+import { getAccount, requireOwnedHandle } from './helpers'
+
+function mergeMetadata(
+  base: EdgeMetadata | undefined,
+  overlay: EdgeMetadata | undefined
+): EdgeMetadata | undefined {
+  if (base == null && overlay == null) return undefined
+  const merged = { ...base, ...overlay }
+  return Object.keys(merged).length > 0 ? merged : undefined
+}
+
+/**
+ * The fields `buildSpendInfo` reads, as its three callers declare them.
+ *
+ * Named rather than `Record<string, unknown>`: the erased type threw away
+ * what `route.ts` had already validated, so every field was checked twice
+ * with two different messages and a renamed declaration would have left the
+ * helper's string literals silently stale.
+ */
+interface SpendInput {
+  spendInfo?: ReturnType<typeof asSpendInfo>
+  to?: string
+  nativeAmount?: string
+  amount?: string
+  tokenId?: string | null
+  // Typed, because the declaration validates it now: it was `unknown` while
+  // the field was `asCoreValue` and the handler re-checked it by hand.
+  metadata?: ReturnType<typeof asEdgeMetadata>
+}
+
+/**
+ * Every target says where the money goes, and how much when the route needs it.
+ *
+ * `requireAmount` mirrors the `to` path exactly: the routes that broadcast
+ * demand an amount, and `make-spend` and `--max` leave it to core. The index
+ * is in the message because a caller sending several targets otherwise has no
+ * way to tell which one it got wrong.
+ */
+function assertSpendTargets(
+  targets: EdgeSpendTarget[] | undefined,
+  requireAmount: boolean
+): void {
+  if (targets == null) return
+  targets.forEach((target, index) => {
+    const where = `spendTargets[${index}]`
+    if (target.publicAddress == null || target.publicAddress === '') {
+      throw engineError(
+        'BAD_REQUEST',
+        `Missing required field "${where}.publicAddress"`,
+        400
+      )
+    }
+    if (
+      requireAmount &&
+      (target.nativeAmount == null || target.nativeAmount === '')
+    ) {
+      throw engineError(
+        'BAD_REQUEST',
+        `Missing required field "${where}.nativeAmount"`,
+        400
+      )
+    }
+  })
+}
+
+async function buildSpendInfo(
+  wallet: EdgeCurrencyWallet,
+  body: SpendInput,
+  opts: { requireAmount: boolean }
+): Promise<EdgeSpendInfo> {
+  const bodyMetadata = body.metadata
+
+  if (body.spendInfo != null) {
+    const spendInfo = { ...body.spendInfo } as unknown as EdgeSpendInfo
+    // Above the return, not below it. Core does
+    // `tokenId == null ? currencyInfo : allTokens[tokenId]` and destructures
+    // the result, so an unknown tokenId inside a caller-supplied `spendInfo`
+    // was a `TypeError` — `500 INTERNAL_ERROR` with no field name, on routes
+    // that declare `TOKEN_NOT_FOUND`.
+    assertTokenId(wallet, spendInfo.tokenId ?? null)
+    // Above the return for the same reason, and this gap was worse than the
+    // tokenId one. Core does `if (publicAddress == null) continue`, so a
+    // target with no address is dropped and the *rest* of the transaction is
+    // still signed and broadcast: the engine answered 200 with a transaction
+    // paying fewer outputs than the caller asked for, which no amount of
+    // retrying can take back. `.withRest` keeps a typo such as
+    // `publicAdress` as an unread rest field, which is the common way in,
+    // and the `spendTargets.length === 0` guard cannot see any of it because
+    // the array is not empty. The `to` shorthand below has always checked
+    // both of these; only the caller-supplied `spendInfo` escaped.
+    assertSpendTargets(spendInfo.spendTargets, opts.requireAmount)
+    const metadata = mergeMetadata(spendInfo.metadata, bodyMetadata)
+    if (metadata != null) spendInfo.metadata = metadata
+    return spendInfo
+  }
+
+  const tokenId = body.tokenId ?? null
+  const to = body.to
+  const amount = body.nativeAmount ?? body.amount
+  const spendTargets: EdgeSpendTarget[] = []
+  let metadata = bodyMetadata
+  let memos: EdgeMemo[] | undefined
+
+  if (to != null) {
+    let parsed
+    try {
+      parsed = await wallet.parseUri(to)
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw engineError(
+        'BAD_REQUEST',
+        `Could not parse destination: ${message}`,
+        400
+      )
+    }
+    if (parsed.publicAddress == null || parsed.publicAddress === '') {
+      throw engineError(
+        'BAD_REQUEST',
+        parsed.paymentProtocolUrl != null
+          ? 'Payment protocol URIs are not supported on convenience spend; use GET .../payment-protocol'
+          : 'Destination did not contain a public address',
+        400
+      )
+    }
+    const nativeAmount = amount ?? parsed.nativeAmount
+    if (opts.requireAmount && nativeAmount == null) {
+      throw engineError(
+        'BAD_REQUEST',
+        'Missing required field "nativeAmount" or "amount"',
+        400
+      )
+    }
+    spendTargets.push({
+      publicAddress: parsed.publicAddress,
+      nativeAmount
+    })
+    if (parsed.uniqueIdentifier != null) {
+      memos = [{ type: 'text', value: parsed.uniqueIdentifier }]
+    }
+    metadata = mergeMetadata(parsed.metadata, bodyMetadata)
+  }
+
+  assertTokenId(wallet, tokenId)
+  const spendInfo: EdgeSpendInfo = { tokenId, spendTargets }
+  if (metadata != null) spendInfo.metadata = metadata
+  if (memos != null) spendInfo.memos = memos
+  return spendInfo
+}
+
+function storeTransaction(
+  ctx: RouteContext,
+  opts: {
+    sessionId: string
+    walletId: string
+    transaction: EdgeTransaction
+  }
+): ObjectHandleInfo & { transaction: EdgeTransaction } {
+  const handle = ctx.state.objects.create({
+    kind: 'transaction',
+    prefix: 'tx_',
+    value: opts.transaction,
+    sessionId: opts.sessionId,
+    walletId: opts.walletId
+  })
+  return {
+    objectId: handle.objectId,
+    kind: handle.kind,
+    createdAt: handle.createdAt,
+    expiresAt: handle.expiresAt,
+    sessionId: handle.sessionId,
+    walletId: handle.walletId,
+    transaction: opts.transaction
+  }
+}
+
+/**
+ * The staged transaction named by `objectId`, checked against a wallet.
+ *
+ * `walletId` must be a resolved `wallet.id`, never the caller's raw input:
+ * `asWalletId` accepts any unique prefix, so comparing raw strings rejected a
+ * prefix and a full id that name the same wallet.
+ */
+function requireTxHandle(
+  ctx: RouteContext,
+  body: { objectId?: string },
+  walletId: string
+): {
+  objectId: string
+  transaction: EdgeTransaction
+  /** The record itself, for a caller that has to `hold` it across a call. */
+  record: HandleRecord<EdgeTransaction>
+} {
+  const objectId = body.objectId
+  if (objectId == null) {
+    throw engineError(
+      'BAD_REQUEST',
+      'Missing required field "objectId" (from make-spend / prior step)',
+      400
+    )
+  }
+  const record = requireOwnedHandle<EdgeTransaction>(
+    ctx,
+    objectId,
+    'transaction'
+  )
+  if (record.walletId != null && record.walletId !== walletId) {
+    throw engineError(
+      'OBJECT_WALLET_MISMATCH',
+      `objectId ${objectId} belongs to a different wallet`,
+      400
+    )
+  }
+  return { objectId, transaction: record.value, record }
+}
+
+/**
+ * The wallet and transaction behind a `tx_` handle.
+ *
+ * A handle records the wallet it was staged against, so the later steps do
+ * not ask for it again: `make-spend` names a wallet, and everything after it
+ * names the handle. The session check still runs, so one session cannot
+ * advance another's transaction.
+ */
+function stagedTx(
+  ctx: RouteContext,
+  objectId: string
+): {
+  objectId: string
+  wallet: EdgeCurrencyWallet
+  transaction: EdgeTransaction
+  record: HandleRecord<EdgeTransaction>
+} {
+  const record = requireOwnedHandle<EdgeTransaction>(
+    ctx,
+    objectId,
+    'transaction'
+  )
+  if (record.walletId == null) {
+    throw engineError(
+      'OBJECT_WALLET_MISMATCH',
+      `objectId ${objectId} is not bound to a wallet`,
+      400
+    )
+  }
+  return {
+    objectId,
+    wallet: findWallet(getAccount(ctx), record.walletId),
+    transaction: record.value,
+    record
+  }
+}
+
+function txHandleResponse(
+  ctx: RouteContext,
+  objectId: string,
+  transaction: EdgeTransaction
+): ObjectHandleInfo & { transaction: EdgeTransaction } {
+  const info = ctx.state.objects.update(objectId, transaction)
+  return {
+    ...info,
+    transaction
+  }
+}
+
+/**
+ * Largest sendable amount.
+ *
+ * What empties the wallet after fees. A destination is still required, since
+ * fees depend on it.
+ */
+export const getMaxSpendable = route({
+  core: 'wallet.getMaxSpendable',
+  // Inline, not shared. `scripts/extractRoutes.ts` reads `coreExtra` with
+  // the TypeScript checker as an object literal, so a reference to an
+  // imported const is invisible to it and `checkCoreAlignment` then reports
+  // every shorthand field as unexplained. The body above *can* be shared,
+  // because that is a type the checker resolves.
+  coreExtra: {
+    to:
+      'Shorthand the engine expands into `spendTargets`, so a one-output ' +
+      'send needs no nested JSON.',
+    nativeAmount: 'Amount for the `to` shorthand, in the smallest unit.',
+    amount:
+      'Alias of `nativeAmount` for the `to` shorthand: the chain\u2019s smallest unit, not whole coins.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/get-max-spendable',
+  cli: 'get-max-spendable',
+  body: asSpendShorthandBody.withRest,
+  returns: asObject({
+    nativeAmount: doc(asString, 'The most this wallet can send.')
+  }),
+  errors: [
+    'TOKEN_NOT_FOUND',
+    'INSUFFICIENT_FUNDS',
+    'BAD_REQUEST',
+    'NETWORK_ERROR',
+    ...WALLET_ERRORS
+  ],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    const spendInfo = await buildSpendInfo(wallet, ctx.body, {
+      requireAmount: false
+    })
+    if (spendInfo.spendTargets.length === 0) {
+      throw engineError(
+        'BAD_REQUEST',
+        'A destination is required: pass `to`, or `spendTargets`. Fees depend on it, so core cannot compute a maximum without one.',
+        400
+      )
+    }
+    const nativeAmount = await wallet.getMaxSpendable(spendInfo)
+    return { nativeAmount }
+  }
+})
+
+/**
+ * Send funds.
+ *
+ * `makeSpend`, then `signTx`, then optionally `broadcastTx` and `saveTx`, in
+ * one request. `broadcast` and `save` both default to true, so a bare body
+ * with a destination and an amount moves real money. A completed spend leaves
+ * no handle behind.
+ *
+ * @note BIP21 `label` and `message` from `to` become metadata name and notes.
+ *   An explicit `metadata` object wins.
+ * @note `saveError` is the case to handle. Once broadcast, the money is gone,
+ *   so a failure inside saveTx cannot throw — it would hide the txid of a real
+ *   payment. The response is 200 with the transaction plus `saveError`.
+ * @note With `dryRun`, only makeSpend runs and the response is a transaction
+ *   handle that expires in 5 minutes.
+ * @coreNote GUI composite: makeSpend, signTx, broadcastTx and saveTx together.
+ */
+export const spend = route({
+  core: null,
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/spend',
+  cli: [
+    { command: 'spend' },
+    {
+      command: 'spend-max',
+      preset: { useMax: true },
+      summary: 'Send a wallet\u2019s entire spendable balance.',
+      notes: 'The same route with `useMax` preset, so it sends everything.'
+    }
+  ],
+  body: asObject({
+    ...asSpendShorthandBody.shape,
+    useMax: asOptional(
+      doc(asBoolean, 'Replace the first target’s amount with the maximum.')
+    ),
+    dryRun: asOptional(
+      doc(asBoolean, 'Build only. Never signs or broadcasts.')
+    ),
+    broadcast: asOptional(
+      doc(
+        asBoolean,
+        'Defaults to **true**. With `false` the transaction is signed and not sent, so `save` then defaults to false as well — recording an unsent transaction marks its inputs spent locally for something the network will never confirm.'
+      )
+    ),
+    save: asOptional(
+      doc(
+        asBoolean,
+        'Record the transaction in the wallet. Defaults to whatever `broadcast` is. Setting it true alongside `broadcast: false` is refused: use `--dry-run`, or the staged `make-spend` → `sign-tx` → `broadcast-tx` → `save-tx` flow.'
+      )
+    )
+  }).withRest,
+  returns: doc(
+    asCoreValue,
+    '`{ transaction }`, plus `saveError` when the broadcast succeeded but saving failed. With dryRun, a TransactionHandle instead.'
+  ),
+  errors: [
+    'TOKEN_NOT_FOUND',
+    'INSUFFICIENT_FUNDS',
+    'DUST_SPEND',
+    'PENDING_FUNDS',
+    'SPEND_TO_SELF',
+    'NO_AMOUNT_SPECIFIED',
+    'BAD_REQUEST',
+    'NETWORK_ERROR',
+    ...WALLET_ERRORS
+  ],
+
+  async handler(ctx) {
+    const broadcast = ctx.body.broadcast ?? true
+    // `save` follows `broadcast` rather than defaulting to true on its own.
+    // The pair `broadcast: false, save: true` signed a transaction, never
+    // sent it, and then wrote it into the wallet as a real one:
+    // `wallet.saveTx` reaches the UTXO engine's `saveTx`, which stores the
+    // transaction *and* processes its own UTXOs, so the inputs are marked
+    // spent locally for something that will never confirm and will never be
+    // dropped, because nothing on the network has it. The wallet shows a
+    // phantom pending send and a reduced balance until a full
+    // `resync-blockchain`.
+    //
+    // Refused up front: it is a usage error, so it must not depend on the
+    // wallet having enough funds to get as far as signing.
+    const save = ctx.body.save ?? broadcast
+    if (!broadcast && save) {
+      throw engineError(
+        'BAD_REQUEST',
+        'save requires broadcast: recording a transaction that was never sent marks its inputs spent for something the network will not confirm. Use dryRun to build only, or make-spend → sign-tx → broadcast-tx → save-tx to stage it.',
+        400
+      )
+    }
+
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    // `ctx.body` is the cleaned value `route.ts` substituted. Re-reading the
+    // raw body through `optionalBoolean` validated every field a second time,
+    // with a different message, and left the string literals silently stale
+    // if a declaration were renamed.
+    const useMax = ctx.body.useMax ?? false
+    const spendInfo = await buildSpendInfo(wallet, ctx.body, {
+      requireAmount: !useMax
+    })
+
+    // The same guard `get-max-spendable` has, 90 lines up. `spend` only
+    // consulted the maximum when a target already existed and otherwise fell
+    // through to `makeSpend({ spendTargets: [] })`, where the plugin throws a
+    // plain `Error` — so `edge-cli spend-max --wallet-id=<id>`, a one-flag
+    // mistake on a documented command, answered `500 INTERNAL_ERROR` outside
+    // the route's declared errors instead of saying what was missing.
+    if (spendInfo.spendTargets.length === 0) {
+      throw engineError(
+        'BAD_REQUEST',
+        'A destination is required: pass `to`, or `spendTargets`.',
+        400
+      )
+    }
+    if (useMax) {
+      const nativeAmount = await wallet.getMaxSpendable(spendInfo)
+      spendInfo.spendTargets[0].nativeAmount = nativeAmount
+    }
+
+    const unsignedTx = await wallet.makeSpend(spendInfo)
+    const dryRun = ctx.body.dryRun ?? false
+    if (dryRun) {
+      // Dry-run returns a handle so the caller can inspect fees, then the
+      // object expires (or they delete it) — nothing is signed/broadcast.
+      return storeTransaction(ctx, {
+        sessionId: ctx.params.sessionId,
+        walletId: wallet.id,
+        transaction: unsignedTx
+      })
+    }
+
+    const signedTx = await wallet.signTx(unsignedTx)
+
+    let finalTx: EdgeTransaction = signedTx
+    if (broadcast) finalTx = await wallet.broadcastTx(signedTx)
+
+    let saveError: string | undefined
+    if (save) {
+      const txToSave: EdgeTransaction = {
+        ...finalTx,
+        metadata: {
+          ...spendInfo.metadata,
+          ...finalTx.metadata
+        }
+      }
+      try {
+        await saveTxAndMetadata(wallet, txToSave)
+        finalTx = txToSave
+      } catch (error: unknown) {
+        // Once broadcast, the spend is real. Throwing here would deny the
+        // caller the txid of money that already left the wallet, so report
+        // the failure alongside the transaction instead.
+        if (!broadcast) throw error
+        saveError = error instanceof Error ? error.message : String(error)
+        ctx.state.logger.warn('saveTx failed after broadcast', {
+          walletId: wallet.id,
+          txid: finalTx.txid,
+          error: saveError
+        })
+      }
+    }
+
+    // Completed spends do not leave an engine-side handle.
+    return saveError == null
+      ? { transaction: finalTx }
+      : { transaction: finalTx, saveError }
+  }
+})
+
+/**
+ * Build an unsigned transaction.
+ *
+ * First step of the staged workflow: nothing is signed and no funds move.
+ * Inspect `transaction.networkFee` on the result before signing.
+ */
+export const makeSpend = route({
+  core: 'wallet.makeSpend',
+  // Inline, not shared. `scripts/extractRoutes.ts` reads `coreExtra` with
+  // the TypeScript checker as an object literal, so a reference to an
+  // imported const is invisible to it and `checkCoreAlignment` then reports
+  // every shorthand field as unexplained. The body above *can* be shared,
+  // because that is a type the checker resolves.
+  coreExtra: {
+    to:
+      'Shorthand the engine expands into `spendTargets`, so a one-output ' +
+      'send needs no nested JSON.',
+    nativeAmount: 'Amount for the `to` shorthand, in the smallest unit.',
+    amount:
+      'Alias of `nativeAmount` for the `to` shorthand: the chain\u2019s smallest unit, not whole coins.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/make-spend',
+  cli: 'make-spend',
+  body: asSpendShorthandBody.withRest,
+  returns: asTransactionHandle,
+  errors: [
+    'TOKEN_NOT_FOUND',
+    'INSUFFICIENT_FUNDS',
+    'DUST_SPEND',
+    'NO_AMOUNT_SPECIFIED',
+    'BAD_REQUEST',
+    ...WALLET_ERRORS
+  ],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    const spendInfo = await buildSpendInfo(wallet, ctx.body, {
+      requireAmount: true
+    })
+    const transaction = await wallet.makeSpend(spendInfo)
+    return storeTransaction(ctx, {
+      sessionId: ctx.params.sessionId,
+      walletId: wallet.id,
+      transaction
+    })
+  }
+})
+
+/**
+ * Sign a staged transaction.
+ *
+ * Keeps the same handle and pushes its expiry out another five minutes.
+ */
+export const signTx = route({
+  core: 'wallet.signTx',
+  method: 'POST',
+  path: '/account/{sessionId}/sign-tx',
+  cli: { command: 'sign-tx', positional: 'objectId' },
+  body: asObject({
+    objectId: doc(asString, 'From `make-spend`.')
+  }).withRest,
+  returns: asTransactionHandle,
+  errors: ['BAD_REQUEST', ...HANDLE_ERRORS],
+
+  async handler(ctx) {
+    const {
+      objectId,
+      wallet,
+      transaction: unsigned,
+      record
+    } = stagedTx(ctx, ctx.body.objectId)
+    const transaction = await ctx.state.objects.hold(
+      record,
+      async () => await wallet.signTx(unsigned)
+    )
+    return txHandleResponse(ctx, objectId, transaction)
+  }
+})
+
+/**
+ * Broadcast a signed transaction.
+ *
+ * The irreversible step: once this returns, the funds have left the wallet.
+ *
+ * @note Broadcasting does not record the transaction locally. Follow with
+ *   `save-tx`, or it stays missing from history until a sync finds it.
+ */
+export const broadcastTx = route({
+  core: 'wallet.broadcastTx',
+  method: 'POST',
+  path: '/account/{sessionId}/broadcast-tx',
+  cli: { command: 'broadcast-tx', positional: 'objectId' },
+  body: asObject({
+    objectId: doc(asString, 'From `sign-tx`.')
+  }).withRest,
+  returns: doc(
+    asTransactionHandle,
+    'The handle survives, so `save-tx` can still run.'
+  ),
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR', ...HANDLE_ERRORS],
+
+  async handler(ctx) {
+    const {
+      objectId,
+      wallet,
+      transaction: signed,
+      record
+    } = stagedTx(ctx, ctx.body.objectId)
+    const transaction = await ctx.state.objects.hold(
+      record,
+      async () => await wallet.broadcastTx(signed)
+    )
+    return txHandleResponse(ctx, objectId, transaction)
+  }
+})
+
+/**
+ * Record a transaction and release its handle.
+ *
+ * Final step. The handle is gone afterwards, so a second call is a 404.
+ */
+export const saveTx = route({
+  core: 'wallet.saveTx',
+  method: 'POST',
+  path: '/account/{sessionId}/save-tx',
+  cli: { command: 'save-tx', positional: 'objectId' },
+  body: asObject({
+    objectId: doc(asString, 'The handle to persist and release.')
+  }).withRest,
+  returns: asOkObject,
+  errors: ['BAD_REQUEST', ...HANDLE_ERRORS],
+
+  async handler(ctx) {
+    const { objectId, wallet, transaction } = stagedTx(ctx, ctx.body.objectId)
+    await saveTxAndMetadata(wallet, transaction)
+    await ctx.state.objects.delete(objectId)
+    return { ok: true, objectId }
+  }
+})
+
+/**
+ * Fee-bump a pending transaction.
+ *
+ * Replace-by-fee, where the plugin supports it. Returns a new unsigned
+ * transaction to sign and broadcast.
+ *
+ * @note A plugin that cannot accelerate returns 400 rather than a null
+ *   transaction.
+ */
+export const accelerate = route({
+  core: 'wallet.accelerate',
+  coreExtra: {
+    transaction:
+      'Core names the parameter `tx`. Spelled out here to match the ' +
+      '`transaction` field every staged-transaction response returns.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/accelerate',
+  cli: 'accelerate',
+  body: asObject({
+    walletId: asWalletId,
+    objectId: asOptional(doc(asString, 'Handle of the transaction to bump.')),
+    transaction: asOptional(
+      doc(asTransactionInput, 'Or the transaction itself.')
+    )
+  }).withRest,
+  returns: doc(
+    asTransactionHandle,
+    'Given objectId the same handle is updated; given a transaction a new one is created.'
+  ),
+  errors: ['BAD_REQUEST', ...HANDLE_ERRORS, ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    const objectId = ctx.body.objectId
+    let transaction: EdgeTransaction | null
+    if (objectId != null) {
+      // `hold`, like `sign-tx` and `broadcast-tx`. The expiry is checked on
+      // the way *out*, through `update`, so an unguarded plugin call that
+      // crossed the five-minute boundary had its handle collected by the
+      // 15-second sweeper and the accelerated transaction was then thrown
+      // away with a 404 the caller cannot tell from "wrong id".
+      const staged = requireTxHandle(ctx, ctx.body, wallet.id)
+      transaction = await ctx.state.objects.hold(
+        staged.record,
+        async () => await wallet.accelerate(staged.transaction)
+      )
+    } else if (ctx.body.transaction != null) {
+      transaction = await wallet.accelerate(
+        ctx.body.transaction as unknown as EdgeTransaction
+      )
+    } else {
+      throw engineError(
+        'BAD_REQUEST',
+        'Missing required field "objectId" or "transaction"',
+        400
+      )
+    }
+    if (transaction == null) {
+      throw engineError(
+        'BAD_REQUEST',
+        'Wallet could not accelerate this transaction',
+        400
+      )
+    }
+    if (objectId != null) {
+      return txHandleResponse(ctx, objectId, transaction)
+    }
+    return storeTransaction(ctx, {
+      sessionId: ctx.params.sessionId,
+      walletId: wallet.id,
+      transaction
+    })
+  }
+})
+
+/**
+ * Sweep private keys into this wallet.
+ *
+ * Builds a transaction moving everything from an external key. Returns an
+ * unsigned handle: sign, broadcast and save it like any staged spend.
+ */
+export const sweepPrivateKeys = route({
+  core: 'wallet.sweepPrivateKeys',
+  coreExtra: {
+    spendInfo:
+      'Core names this one `edgeSpendInfo` while `makeSpend` names the same ' +
+      'type `spendInfo`. Both are `spendInfo` here.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/sweep-private-keys',
+  cli: 'sweep-private-keys',
+  body: asObject({
+    walletId: asWalletId,
+    spendInfo: doc(
+      asSweepSpendInfo,
+      'The keys to sweep in `privateKeys`, plus the optional `spendTargets`, `tokenId`, `metadata` and `memos` of a spend.'
+    )
+  }).withRest,
+  returns: asTransactionHandle,
+  errors: [
+    'BAD_REQUEST',
+    'INSUFFICIENT_FUNDS',
+    'NETWORK_ERROR',
+    'TOKEN_NOT_FOUND',
+    ...WALLET_ERRORS
+  ],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    // The declaration requires `spendInfo` and names its fields, so a
+    // missing or malformed one is the 400 this route publishes rather than a
+    // plain `Error` from the plugin surfacing as 500.
+    assertTokenId(wallet, ctx.body.spendInfo.tokenId)
+    const transaction = await wallet.sweepPrivateKeys(
+      ctx.body.spendInfo as unknown as EdgeSpendInfo
+    )
+    return storeTransaction(ctx, {
+      sessionId: ctx.params.sessionId,
+      walletId: wallet.id,
+      transaction
+    })
+  }
+})
+
+/**
+ * Sign arbitrary bytes.
+ *
+ * Message signing and proof-of-ownership, for plugins that support it.
+ *
+ * @note Invalid base64 is refused with `BAD_REQUEST` rather than signed.
+ * @note Support is per plugin, and failures surface as `500 INTERNAL_ERROR`
+ *   from the plugin rather than as a typed error: litecoin answers
+ *   "litecoin doesn't support signBytes", and bitcoin requires
+ *   `otherParams.publicAddress` naming which address to sign with.
+ */
+export const signBytes = route({
+  core: 'wallet.signBytes',
+  coreExtra: {
+    bytes:
+      'Core takes a Uint8Array named `buf`. JSON cannot carry bytes, so this ' +
+      'is base64 text.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/sign-bytes',
+  cli: 'sign-bytes',
+  body: asObject({
+    walletId: asWalletId,
+    bytes: asOptional(doc(asString, 'Base64. Defaults to empty when absent.')),
+    // `asObject(asUnknown)`, so a non-object is a 400 naming the field. As
+    // `asCoreValue` it passed the declaration and was then *dropped* by the
+    // handler, so `--other-params='"x"'` signed with no options at all and
+    // produced a confusing plugin failure instead of saying what was wrong —
+    // and on bitcoin that is where `publicAddress` lives.
+    otherParams: asOptional(
+      doc(
+        asObject(asUnknown),
+        'Plugin-specific options. Bitcoin needs `{ publicAddress }`; other ' +
+          'plugins take nothing, or refuse the call entirely.'
+      )
+    )
+  }).withRest,
+  returns: asObject({ signature: doc(asString, 'Base64.') }),
+  errors: ['BAD_REQUEST', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    // `Buffer.from(.., 'base64')` scrubs anything it cannot decode and hands
+    // back short or empty bytes, so a typo produced a valid signature over the
+    // wrong payload. `base64.parse` rejects instead.
+    let bytes: Uint8Array
+    try {
+      bytes = base64.parse(ctx.body.bytes ?? '')
+    } catch (error) {
+      throw engineError(
+        'BAD_REQUEST',
+        `bytes must be valid base64: ${String(
+          error instanceof Error ? error.message : error
+        )}`,
+        400
+      )
+    }
+    const signature = await wallet.signBytes(bytes, {
+      otherParams: ctx.body.otherParams
+    })
+    return { signature }
+  }
+})
+
+/**
+ * Fetch a BIP70 payment request.
+ *
+ * Feed `spendTargets` from the result into `make-spend` to pay it.
+ */
+export const getPaymentProtocolInfo = route({
+  core: 'wallet.getPaymentProtocolInfo',
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/get-payment-protocol-info',
+  cli: 'get-payment-protocol-info',
+  query: asObject({
+    walletId: asWalletId,
+    paymentProtocolUrl: doc(asString, 'The payment-request URL.')
+  }).withRest,
+  returns: doc(
+    asCoreValue,
+    '`EdgePaymentProtocolInfo`: domain, memo, merchant, nativeAmount, spendTargets.'
+  ),
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    try {
+      return await wallet.getPaymentProtocolInfo(
+        ctx.query.valid.paymentProtocolUrl
+      )
+    } catch (error: unknown) {
+      // core surfaces an unreachable or non-BIP70 URL as a plain Error, which
+      // would otherwise be reported as an engine fault.
+      throw engineError(
+        'NETWORK_ERROR',
+        `Could not fetch the payment request: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        503
+      )
+    }
+  }
+})
diff --git a/src/cli/engine/routes/swap.ts b/src/cli/engine/routes/swap.ts
new file mode 100644
index 00000000000..bc3cd8fdee3
--- /dev/null
+++ b/src/cli/engine/routes/swap.ts
@@ -0,0 +1,305 @@
+/**
+ * Swap quote / execute routes.
+ *
+ * Quotes are ephemeral object handles (`swap_` prefix, 5 min TTL). Approve
+ * consumes the handle; close/delete releases it early.
+ */
+import {
+  asArray,
+  asNumber,
+  asObject,
+  asOptional,
+  asString,
+  asValue
+} from 'cleaners'
+import type { EdgeSwapQuote, EdgeSwapRequest } from 'edge-core-js'
+
+import { doc } from '../doc'
+import { TOKEN_ID_DOC } from '../fieldDocs'
+import { findWallet } from '../resolve'
+import { route } from '../route'
+import {
+  asCoreValue,
+  asOkObject,
+  asRequestTokenId,
+  asSwapQuote
+} from '../schemas'
+import { getAccount, requireOwnedHandle } from './helpers'
+
+function summarizeQuote(
+  objectId: string,
+  expiresAt: string,
+  quote: EdgeSwapQuote
+): Record<string, unknown> {
+  return {
+    objectId,
+    kind: 'swap',
+    expiresAt,
+    pluginId: quote.pluginId,
+    isEstimate: quote.isEstimate,
+    canBePartial: quote.canBePartial ?? null,
+    maxFulfillmentSeconds: quote.maxFulfillmentSeconds ?? null,
+    minReceiveAmount: quote.minReceiveAmount ?? null,
+    fromNativeAmount: quote.fromNativeAmount,
+    toNativeAmount: quote.toNativeAmount,
+    networkFee: {
+      nativeAmount: quote.networkFee.nativeAmount,
+      tokenId: quote.networkFee.tokenId
+    },
+    quoteExpirationDate: quote.expirationDate?.toISOString() ?? null,
+    swapInfo: {
+      pluginId: quote.swapInfo.pluginId,
+      displayName: quote.swapInfo.displayName,
+      supportEmail: quote.swapInfo.supportEmail,
+      isDex: quote.swapInfo.isDex ?? null
+    },
+    request: {
+      fromTokenId: quote.request.fromTokenId,
+      toTokenId: quote.request.toTokenId,
+      nativeAmount: quote.request.nativeAmount,
+      quoteFor: quote.request.quoteFor,
+      fromWalletId: quote.request.fromWallet.id,
+      toWalletId: quote.request.toWallet.id
+    }
+  }
+}
+
+/**
+ * Fetch swap quotes.
+ *
+ * Polls every enabled swap plugin and parks each result under its own `swap_`
+ * handle with a 5 minute TTL.
+ *
+ * @note Every returned quote holds an open plugin object. Approving one
+ *   releases only that handle; close the rest, or let them expire.
+ * @note An empty `quotes` array with `quoteCount: 0` is a success, not an
+ *   error — no plugin could serve the pair.
+ */
+export const fetchSwapQuotes = route({
+  core: 'account.fetchSwapQuotes',
+  coreExtra: {
+    fromWalletId: 'Core takes the wallet object; over HTTP it is an id.',
+    toWalletId: 'Core takes the wallet object; over HTTP it is an id.'
+  },
+  method: 'POST',
+  path: '/account/{sessionId}/fetch-swap-quotes',
+  cli: {
+    command: 'fetch-swap-quotes',
+    flags: { pluginId: { maps: 'preferPluginId' } }
+  },
+  body: asObject({
+    fromWalletId: doc(asString, 'Source wallet. Accepts a unique prefix.'),
+    toWalletId: doc(asString, 'Destination wallet.'),
+    nativeAmount: doc(asString, 'How much, in native units.'),
+    // `asRequestTokenId`, like the ten other request-position tokenIds: the
+    // CLI sends every tokenId as text, so `--from-token-id=null` — the
+    // spelling the guide documents — arrived as the four characters "null"
+    // and `asTokenId` accepted it verbatim, asking every swap plugin to
+    // price a token literally named `null`.
+    fromTokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    toTokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    quoteFor: asOptional(
+      doc(
+        // The same enum `schemas.ts`'s response cleaner already spells. It
+        // was `asString` plus a three-way `!==` chain in the handler, so the
+        // branch disagreed with itself about one field and the generated
+        // reference documented a free-form string.
+        asValue<Array<'from' | 'to' | 'max'>>('from', 'to', 'max'),
+        '`from` spends this much of the source, `to` receives this much at the destination, `max` sends everything. Defaults to `from`.'
+      ),
+      'from'
+    ),
+    preferPluginId: asOptional(doc(asString, 'Restrict to one exchange.'))
+  }).withRest,
+  returns: asObject({
+    quoteCount: doc(asNumber, 'How many plugins answered.'),
+    quotes: doc(
+      asArray(asSwapQuote),
+      'One quote per plugin that answered, each already parked under its own ' +
+        'handle. Plugins that failed or had nothing to offer are simply absent.'
+    )
+  }),
+  errors: [
+    'BAD_REQUEST',
+    'SWAP_BELOW_LIMIT',
+    'SWAP_ABOVE_LIMIT',
+    'SWAP_CURRENCY',
+    'SWAP_PERMISSION',
+    'SWAP_ADDRESS',
+    'SAME_CURRENCY',
+    'INSUFFICIENT_FUNDS',
+    'WALLET_NOT_FOUND',
+    'NETWORK_ERROR'
+  ],
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    const fromWallet = findWallet(account, ctx.body.fromWalletId)
+    const toWallet = findWallet(account, ctx.body.toWalletId)
+    // `asOptional(asTokenId, null)` already yields null for both an absent
+    // and an explicitly null tokenId, so the post-hoc `parseTokenId` the
+    // handlers used to call could never change the value.
+    const { fromTokenId, toTokenId } = ctx.body
+    const { nativeAmount } = ctx.body
+    const { preferPluginId, quoteFor } = ctx.body
+
+    const request: EdgeSwapRequest = {
+      fromWallet,
+      toWallet,
+      fromTokenId,
+      toTokenId,
+      nativeAmount,
+      quoteFor
+    }
+
+    const opts = preferPluginId != null ? { preferPluginId } : undefined
+
+    const quotes: EdgeSwapQuote[] = await account.fetchSwapQuotes(request, opts)
+
+    const results = []
+    for (const quote of quotes) {
+      const handle = ctx.state.objects.create({
+        kind: 'swap',
+        prefix: 'swap_',
+        value: quote,
+        sessionId: ctx.params.sessionId,
+        onExpire: async value => {
+          try {
+            await value.close()
+          } catch {
+            // best effort
+          }
+        }
+      })
+      results.push(summarizeQuote(handle.objectId, handle.expiresAt, quote))
+    }
+
+    return {
+      quoteCount: results.length,
+      quotes: results
+    }
+  }
+})
+
+/**
+ * Re-read a quote.
+ *
+ * @note Check `quoteExpirationDate` as well as `expiresAt`: the plugin's price
+ *   can go stale before the handle does.
+ * @coreNote Engine handle store; the quote is a live EdgeSwapQuote held
+ *   server-side.
+ */
+export const getSwapQuote = route({
+  core: null,
+  method: 'GET',
+  path: '/account/{sessionId}/swap-quote',
+  cli: { command: 'swap-quote-get', positional: 'objectId' },
+  returns: asSwapQuote,
+  errors: [
+    'OBJECT_NOT_FOUND',
+    'OBJECT_EXPIRED',
+    'OBJECT_KIND_MISMATCH',
+    'OBJECT_SESSION_MISMATCH'
+  ],
+
+  async handler(ctx) {
+    const record = requireOwnedHandle<EdgeSwapQuote>(
+      ctx,
+      ctx.params.objectId,
+      'swap'
+    )
+    const info = ctx.state.objects.toInfo(record)
+    return summarizeQuote(info.objectId, info.expiresAt, record.value)
+  }
+})
+
+/**
+ * Execute a quote.
+ *
+ * Moves funds. The handle is released afterwards whether or not the response
+ * is read, so record `orderId` from it.
+ *
+ * @note A failure releases the handle too, and a retry answers
+ *   `OBJECT_NOT_FOUND`. `approve()` signs, broadcasts and then does its own
+ *   bookkeeping, and from outside the plugin an error after the money moved
+ *   cannot be told from one before it — so a retry has to start from a fresh
+ *   quote rather than risk a second broadcast.
+ * @note The plugin attaches its own savedAction and assetAction metadata; the
+ *   engine adds none.
+ */
+export const approveSwapQuote = route({
+  core: 'EdgeSwapQuote.approve',
+  method: 'POST',
+  path: '/account/{sessionId}/swap-quote/approve',
+  cli: { command: 'approve-swap-quote', positional: 'objectId' },
+  returns: asObject({
+    ok: doc(
+      asCoreValue,
+      'True once the swap is submitted and the send broadcast.'
+    ),
+    objectId: doc(asString, 'The handle that was consumed.'),
+    orderId: doc(
+      asCoreValue,
+      'The exchange’s order reference, when it gives one.'
+    ),
+    destinationAddress: doc(
+      asCoreValue,
+      'Address the funds were sent to, when the exchange reports one.'
+    ),
+    transaction: doc(asCoreValue, 'The on-chain send to the exchange.')
+  }),
+  errors: [
+    'OBJECT_NOT_FOUND',
+    'OBJECT_EXPIRED',
+    'OBJECT_KIND_MISMATCH',
+    'OBJECT_SESSION_MISMATCH',
+    'OBJECT_IN_USE',
+    'INSUFFICIENT_FUNDS',
+    'NETWORK_ERROR'
+  ],
+
+  async handler(ctx) {
+    const record = requireOwnedHandle<EdgeSwapQuote>(
+      ctx,
+      ctx.params.objectId,
+      'swap'
+    )
+    const result = await ctx.state.objects.consume(
+      record,
+      async quote => await quote.approve()
+    )
+    return {
+      ok: true,
+      objectId: ctx.params.objectId,
+      orderId: result.orderId ?? null,
+      destinationAddress: result.destinationAddress ?? null,
+      transaction: result.transaction
+    }
+  }
+})
+
+/**
+ * Discard a quote.
+ *
+ * Closes the plugin object without executing, freeing whatever the exchange
+ * was holding.
+ */
+export const closeSwapQuote = route({
+  core: 'EdgeSwapQuote.close',
+  method: 'POST',
+  path: '/account/{sessionId}/swap-quote/close',
+  cli: { command: 'close-swap-quote', positional: 'objectId' },
+  returns: asOkObject,
+  errors: [
+    'OBJECT_NOT_FOUND',
+    'OBJECT_EXPIRED',
+    'OBJECT_KIND_MISMATCH',
+    'OBJECT_SESSION_MISMATCH'
+  ],
+
+  async handler(ctx) {
+    requireOwnedHandle<EdgeSwapQuote>(ctx, ctx.params.objectId, 'swap')
+    await ctx.state.objects.delete(ctx.params.objectId)
+    return { ok: true, objectId: ctx.params.objectId }
+  }
+})
diff --git a/src/cli/engine/routes/tokens.ts b/src/cli/engine/routes/tokens.ts
new file mode 100644
index 00000000000..b003d575822
--- /dev/null
+++ b/src/cli/engine/routes/tokens.ts
@@ -0,0 +1,94 @@
+import { asArray, asObject, asString } from 'cleaners'
+
+import { doc } from '../doc'
+import { findWallet } from '../resolve'
+import { route } from '../route'
+import { asCoreValue, asEnabledTokens, asWalletId } from '../schemas'
+import { getAccount } from './helpers'
+
+/**
+ * List a wallet's tokens.
+ *
+ * "Enabled" tokens are the ones the wallet syncs balances for; "detected" ones
+ * were seen on-chain but are not yet enabled.
+ *
+ * @coreNote Engine composite of the EdgeCurrencyConfig token maps plus
+ *   wallet.enabledTokenIds and wallet.detectedTokenIds.
+ */
+export const walletTokens = route({
+  core: null,
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/tokens',
+  cli: 'wallet-tokens',
+  query: asObject({ walletId: asWalletId }).withRest,
+  returns: asObject({
+    allTokens: doc(
+      asObject(asCoreValue),
+      '`EdgeToken` by tokenId: everything the plugin ships with, plus this account\u2019s own. `builtinTokens` is not returned separately — it is this map minus `customTokens`, and sending both wrote the whole built-in list down the socket twice.'
+    ),
+    customTokens: doc(
+      asObject(asCoreValue),
+      '`EdgeToken` by tokenId: tokens this account added by hand.'
+    ),
+    enabledTokenIds: doc(
+      asArray(asString),
+      'Which of the above the wallet is actually tracking.'
+    ),
+    detectedTokenIds: doc(
+      asArray(asString),
+      'Seen on-chain but not enabled, so their balances are not synced.'
+    )
+  }),
+  errors: ['WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    return {
+      allTokens: wallet.currencyConfig.allTokens,
+      customTokens: wallet.currencyConfig.customTokens,
+      enabledTokenIds: wallet.enabledTokenIds,
+      detectedTokenIds: wallet.detectedTokenIds
+    }
+  }
+})
+
+/**
+ * Set the enabled token set.
+ *
+ * Absolute: anything missing from `tokenIds` is disabled. Core has only this
+ * setter, so there is no add or remove call.
+ *
+ * @note The command's `--add` and `--remove` are client-side sugar over this
+ *   one route, and cost an extra read first.
+ */
+export const changeEnabledTokenIds = route({
+  core: 'wallet.changeEnabledTokenIds',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/change-enabled-token-ids',
+  cli: {
+    command: 'change-enabled-token-ids',
+    custom: true,
+    extra: {
+      add: {
+        kind: 'repeat',
+        doc: 'Read the current set, add this id, write it back.'
+      },
+      remove: {
+        kind: 'repeat',
+        doc: 'Read the current set, drop this id, write it back.'
+      }
+    }
+  },
+  body: asObject({
+    walletId: asWalletId,
+    tokenIds: doc(asArray(asString), 'The complete desired set.')
+  }).withRest,
+  returns: asEnabledTokens,
+  errors: ['BAD_REQUEST', 'WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    await wallet.changeEnabledTokenIds(ctx.body.tokenIds)
+    return { enabledTokenIds: wallet.enabledTokenIds }
+  }
+})
diff --git a/src/cli/engine/routes/transactions.ts b/src/cli/engine/routes/transactions.ts
new file mode 100644
index 00000000000..ccddfaba829
--- /dev/null
+++ b/src/cli/engine/routes/transactions.ts
@@ -0,0 +1,500 @@
+import { asNumber, asObject, asOptional, asString } from 'cleaners'
+import type {
+  EdgeAccount,
+  EdgeCurrencyWallet,
+  EdgeTransaction
+} from 'edge-core-js'
+
+import { getExchangeDenom } from '../../../util/exchangeDenom'
+import {
+  exportTxInfoKey,
+  mergeExportTxInfo,
+  readExportTxInfoMap
+} from '../../../util/exportTxInfo'
+import { fillTxsFiat, toIsoFiatCode } from '../../../util/fillTxsFiat'
+import {
+  readDefaultIsoFiat,
+  resolveListSpamThreshold
+} from '../../../util/spamThreshold'
+import {
+  fillTxMetadataForDisplay,
+  getTxActionDisplayInfo,
+  splitCategory
+} from '../../../util/txDisplay'
+import {
+  exportTransactionsToBitwave,
+  exportTransactionsToCSVInner,
+  exportTransactionsToQBO,
+  parseExportFormats,
+  type TxExportFormat
+} from '../../../util/txExport'
+import { doc } from '../doc'
+import { engineError } from '../errors'
+import { TOKEN_ID_DOC } from '../fieldDocs'
+import { assertTokenId, findWallet } from '../resolve'
+import { route } from '../route'
+import {
+  asCoreValue,
+  asEdgeAssetAction,
+  asEdgeMetadataChange,
+  asEdgeTxAction,
+  asQueryBoolean,
+  asQueryDate,
+  asQueryNonNegativeInteger,
+  asRequestTokenId,
+  asWalletId
+} from '../schemas'
+import { getAccount } from './helpers'
+
+/**
+ * Attach the display metadata the GUI shows, plus the structured values it
+ * was derived from.
+ *
+ * Response-only: it does not call `saveTxMetadata`.
+ *
+ * `metadata.name`, `metadata.category` and `metadata.notes` carry **localized
+ * prose**, built from the engine's boot locale — an API layer handing the
+ * caller translated text. `displayInfo` is returned beside them so a caller
+ * can render its own: `assetActionType` and `direction` are machine values,
+ * and `category` is the `EdgeCategory` split, whose `category` member is one
+ * of four untranslated tokens where `metadata.category` glues an English
+ * prefix to a translated subcategory and can be parsed as neither.
+ */
+function overlayDisplayMetadata(
+  tx: EdgeTransaction,
+  account: EdgeAccount,
+  wallet: EdgeCurrencyWallet
+): EdgeTransaction & { displayInfo: unknown } {
+  const info = getTxActionDisplayInfo(tx, account, wallet)
+  return {
+    ...fillTxMetadataForDisplay(tx, info.mergedData),
+    displayInfo: {
+      direction: info.direction,
+      iconPluginId: info.iconPluginId,
+      assetActionType: info.assetAction?.assetActionType,
+      actionType: info.action?.actionType,
+      category: splitCategory(info.mergedData.category ?? '')
+    }
+  }
+}
+
+/**
+ * `get-transactions` page size when the caller does not ask for one.
+ *
+ * 99, not 100: the rates batcher stops *before* crossing
+ * RATES_SERVER_MAX_QUERY_SIZE, so 99 unpriced transactions cost one upstream
+ * request and 100 cost two. The point of the default is that a page prices
+ * in a single request, which 100 did not deliver.
+ */
+const DEFAULT_TX_LIMIT = 99
+
+/**
+ * List or export a wallet's transactions.
+ *
+ * Reads history, overlays the display metadata the GUI shows, fills historical
+ * fiat, and optionally formats the result — all on this one call.
+ *
+ * @note The metadata overlay and the fiat fill are response-only. Neither
+ *   writes to disk.
+ * @note `limit` and `offset` apply before the fiat fill, so a large page asks
+ *   the rates server about more dates. Unpriced dates are batched into one
+ *   request per 100, and every rate is cached for the life of the engine, so
+ *   a second listing of the same range needs none.
+ * @note This is the one GET that can write: passing `bitwaveAccountId`
+ *   persists it to `exportTxInfo.json` on the wallet disklet.
+ * @returns Without `exportFormat`, the transactions themselves. With it, the
+ *   formatted files instead — the two shapes are mutually exclusive.
+ */
+export const getTransactions = route({
+  core: 'wallet.getTransactions',
+  coreExtra: {
+    limit: 'Engine-side paging; core returns every match.',
+    offset: 'Engine-side paging; core returns every match.',
+    fiat: 'Selects the currency the engine values each transaction in.',
+    exportFormat: 'Engine-side rendering to CSV, QBO or Bitwave.',
+    bitwaveAccountId: 'Required by the Bitwave export format.',
+    saveExportPrefs:
+      'Opt-in write of the wallet\u2019s synced exportTxInfo.json, the record the GUI export scene reads back.'
+  },
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/get-transactions',
+  cli: {
+    command: 'get-transactions',
+    custom: true,
+    flags: { bitwaveAccount: { maps: 'bitwaveAccountId' } },
+    extra: {
+      out: {
+        kind: 'string',
+        requiredWith: 'exportFormat',
+        doc: 'Where to write the returned files. One format: the path. Several: a stem, plus .csv / .qbo / .bitwave.csv.'
+      }
+    }
+  },
+  query: asObject({
+    walletId: asWalletId,
+    tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    limit: asOptional(
+      doc(
+        asQueryNonNegativeInteger,
+        'How many to return. Defaults to 100; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.'
+      ),
+      DEFAULT_TX_LIMIT
+    ),
+    offset: asOptional(
+      doc(asQueryNonNegativeInteger, 'Where to start. Defaults to 0.'),
+      0
+    ),
+    saveExportPrefs: asOptional(
+      doc(
+        asQueryBoolean,
+        'Save `bitwaveAccountId` and the chosen formats into the wallet\u2019s synced `exportTxInfo.json`, which the GUI export scene reads back. Off by default: a read does not change saved preferences.'
+      ),
+      false
+    ),
+    startDate: asOptional(doc(asQueryDate, 'ISO-8601, or epoch milliseconds.')),
+    endDate: asOptional(doc(asQueryDate, 'ISO-8601, or epoch milliseconds.')),
+    searchString: asOptional(
+      doc(asString, 'Matches payee, category, notes and txid.')
+    ),
+    spamThreshold: asOptional(
+      doc(
+        asString,
+        'Native-amount floor. Omitted, the account spam-filter setting applies; a value always overrides it, and `0` shows everything. An empty value reads as omitted, like every other query parameter.'
+      )
+    ),
+    fiat: asOptional(
+      doc(
+        asString,
+        'Three-letter ISO 4217 code. Defaults to the account defaultIsoFiat.'
+      )
+    ),
+    exportFormat: asOptional(
+      doc(asString, 'Comma list of `csv`, `qbo`, `bitwave`.')
+    ),
+    bitwaveAccountId: asOptional(
+      doc(asString, 'A 400 unless `exportFormat` includes `bitwave`.')
+    )
+  }).withRest,
+  returns: doc(
+    asCoreValue,
+    '`{ transactions, total, isoFiat }`, or `{ ok, isoFiat, total, files }` when exportFormat is set. Each transaction carries `metadata.name`, `metadata.category` and `metadata.notes` as **localized prose** in the engine\u2019s boot locale \u2014 the engine has no per-request locale, so a second shell with a different `LANG` reuses the first engine and gets its language. `displayInfo` beside them carries the machine values the prose was derived from (`direction`, `assetActionType`, `actionType`, and the `category` split whose `category` member is one of `transfer`, `exchange`, `expense`, `income`), so a caller can render its own text.'
+  ),
+  errors: [
+    'BAD_REQUEST',
+    'MISSING_BITWAVE_ACCOUNT_ID',
+    'TOKEN_NOT_FOUND',
+    'WALLET_NOT_FOUND',
+    'AMBIGUOUS_WALLET_ID'
+  ],
+
+  async handler(ctx) {
+    const account = getAccount(ctx)
+    const wallet = findWallet(account, ctx.query.valid.walletId)
+    const { tokenId, startDate, endDate, searchString, limit, offset } =
+      ctx.query.valid
+    // `isoFiat` first, and passed in: the default path read and parsed the
+    // account's *synced* `Settings.json` twice for the identical answer,
+    // once here and once inside `resolveListSpamThreshold` — both through
+    // `syncedSettingsFile.readSyncedSettings`, which deliberately has no
+    // process-wide cache to absorb the repeat. (The local disklet's file has
+    // the same basename, which is the confusion `spamThreshold.ts` warns
+    // about; `localAccountSettings` is the one that reads *that*.)
+    const fiatRaw = ctx.query.valid.fiat
+    let isoFiat: string
+    if (fiatRaw != null) {
+      const parsed = toIsoFiatCode(fiatRaw)
+      if (parsed == null) {
+        throw engineError(
+          'BAD_REQUEST',
+          'Query "fiat" must be a 3-letter currency code (e.g. USD)',
+          400
+        )
+      }
+      isoFiat = parsed
+    } else {
+      isoFiat = await readDefaultIsoFiat(account)
+    }
+
+    const spamThreshold = await resolveListSpamThreshold({
+      account,
+      wallet,
+      tokenId,
+      isoFiat,
+      queryOverride: ctx.query.valid.spamThreshold
+    })
+
+    assertTokenId(wallet, tokenId)
+    const transactions = await wallet.getTransactions({
+      tokenId,
+      startDate,
+      endDate,
+      searchString,
+      spamThreshold
+    })
+
+    // Parsed before the page is cut, because an export ignores the page.
+    const exportRaw = ctx.query.valid.exportFormat
+    let formats: TxExportFormat[]
+    try {
+      formats = parseExportFormats(exportRaw)
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw engineError('BAD_REQUEST', message, 400)
+    }
+
+    const bitwaveAccountIdQuery = ctx.query.valid.bitwaveAccountId
+    if (bitwaveAccountIdQuery != null && !formats.includes('bitwave')) {
+      throw engineError(
+        'BAD_REQUEST',
+        'Query "bitwaveAccountId" requires exportFormat to include bitwave',
+        400
+      )
+    }
+
+    // `0` is the explicit opt-out. An unbounded default meant one call could
+    // price and serialise an entire wallet's history, which on an old BTC or
+    // ETH wallet ran past the client's own socket timeout.
+    //
+    // An export ignores the page entirely. The default was applied *before*
+    // the formatters, so `--export-format=csv` wrote a file holding only the
+    // first page while the response reported `total` as the real count — a
+    // silently truncated accounting export, which is worse than a slow one.
+    // The reason the default exists at all is to bound the rates work, and
+    // `fillTxsFiat` now queues a whole page in one batch either way.
+    const wholeRange = limit === 0 || formats.length > 0
+    const sliced = wholeRange
+      ? transactions.slice(offset)
+      : transactions.slice(offset, offset + limit)
+
+    const overlayed = sliced.map(tx =>
+      overlayDisplayMetadata(tx, account, wallet)
+    )
+    await fillTxsFiat({
+      wallet,
+      tokenId,
+      isoFiat,
+      txs: overlayed
+    })
+
+    if (formats.length === 0) {
+      return {
+        transactions: overlayed,
+        total: transactions.length,
+        isoFiat
+      }
+    }
+
+    const denom = getExchangeDenom(wallet.currencyConfig, tokenId)
+    const currencyCode =
+      tokenId == null
+        ? wallet.currencyInfo.currencyCode
+        : wallet.currencyConfig.allTokens[tokenId]?.currencyCode ?? tokenId
+
+    let bitwaveAccountId: string | undefined
+    if (formats.includes('bitwave')) {
+      if (bitwaveAccountIdQuery != null && bitwaveAccountIdQuery !== '') {
+        bitwaveAccountId = bitwaveAccountIdQuery
+        // Persisting is opt-in. This writes `exportTxInfo.json` on the
+        // wallet's *synced* disklet, which is the record the GUI's export
+        // scene reads back to pre-set its three switches — so doing it
+        // unasked turned a one-off `--bitwave-account-id` into the user's
+        // saved account id and flipped "Export to Bitwave" on for them.
+        if (ctx.query.valid.saveExportPrefs) {
+          await mergeExportTxInfo(wallet, tokenId, {
+            bitwaveAccountId,
+            // The same field set the GUI writes, so one record keeps one
+            // meaning: a partial patch left isExportCsv/isExportQbo at
+            // `false` on a first write and the record no longer described
+            // the last export either tool ran.
+            isExportBitwave: formats.includes('bitwave'),
+            isExportCsv: formats.includes('csv'),
+            isExportQbo: formats.includes('qbo')
+          })
+        }
+      } else {
+        let saved: string | undefined
+        try {
+          const map = await readExportTxInfoMap(wallet)
+          saved = map[exportTxInfoKey(wallet, tokenId)]?.bitwaveAccountId
+        } catch {
+          saved = undefined
+        }
+        if (saved == null || saved === '') {
+          throw engineError(
+            'MISSING_BITWAVE_ACCOUNT_ID',
+            'Bitwave export requires bitwaveAccountId (query or exportTxInfo.json)',
+            400
+          )
+        }
+        bitwaveAccountId = saved
+      }
+    }
+
+    const files: Array<{ format: TxExportFormat; contents: string }> = []
+    for (const format of formats) {
+      if (format === 'csv') {
+        files.push({
+          format,
+          contents: exportTransactionsToCSVInner(
+            overlayed,
+            currencyCode,
+            isoFiat,
+            denom.multiplier,
+            denom.name
+          )
+        })
+      } else if (format === 'qbo') {
+        files.push({
+          format,
+          contents: exportTransactionsToQBO(
+            overlayed,
+            isoFiat,
+            denom.multiplier
+          )
+        })
+      } else {
+        files.push({
+          format,
+          contents: await exportTransactionsToBitwave(
+            bitwaveAccountId!,
+            overlayed,
+            currencyCode,
+            denom.multiplier
+          )
+        })
+      }
+    }
+
+    return {
+      ok: true,
+      isoFiat,
+      total: transactions.length,
+      files
+    }
+  }
+})
+
+/**
+ * Count transactions in a wallet.
+ *
+ * Cheaper than listing when only the total matters.
+ *
+ * @note Unfiltered: `spamThreshold`, dates and `searchString` do not apply, so
+ *   this can exceed `total` from `get-transactions`.
+ */
+export const getNumTransactions = route({
+  core: 'wallet.getNumTransactions',
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/get-num-transactions',
+  cli: 'get-num-transactions',
+  query: asObject({
+    walletId: asWalletId,
+    tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null)
+  }).withRest,
+  returns: asObject({
+    numTransactions: doc(asNumber, 'Every transaction the wallet knows of.')
+  }),
+  errors: ['TOKEN_NOT_FOUND', 'WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    const { tokenId } = ctx.query.valid
+    assertTokenId(wallet, tokenId)
+    // Typed as returning a number, but plugins resolve a promise here, so
+    // awaiting is what actually yields a serializable value.
+    const numTransactions = await wallet.getNumTransactions({ tokenId })
+    return { numTransactions }
+  }
+})
+
+/**
+ * Save transaction metadata.
+ *
+ * One of the paths that write transaction metadata to disk. The others are
+ * `save-tx-action`, which writes `savedAction` and `assetAction` to the same
+ * file, and `save-tx` and `spend`, both of which re-apply the caller's
+ * metadata through `saveTxAndMetadata` after the transaction is saved.
+ *
+ * @note `metadata` is an `EdgeMetadataChange`, so an explicit null clears a
+ *   field while an omitted one is left alone.
+ */
+export const saveTxMetadata = route({
+  core: 'wallet.saveTxMetadata',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/save-tx-metadata',
+  cli: 'save-tx-metadata',
+  body: asObject({
+    walletId: asWalletId,
+    txid: doc(asString, 'Which transaction to tag.'),
+    tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    metadata: doc(
+      asEdgeMetadataChange,
+      '`EdgeMetadataChange`: name, category, notes, exchangeAmount, bizId. `null` on a field deletes it; omitting the field leaves it unchanged.'
+    )
+  }).withRest,
+  errors: [
+    'BAD_REQUEST',
+    'TOKEN_NOT_FOUND',
+    'WALLET_NOT_FOUND',
+    'AMBIGUOUS_WALLET_ID'
+  ],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    // Core reads `allTokens[tokenId]` and destructures it, so an unknown
+    // token was a `TypeError` — `500 INTERNAL_ERROR` with no field name —
+    // where the reference now publishes `TOKEN_NOT_FOUND`.
+    assertTokenId(wallet, ctx.body.tokenId)
+    await wallet.saveTxMetadata({
+      txid: ctx.body.txid,
+      tokenId: ctx.body.tokenId,
+      metadata: ctx.body.metadata
+    })
+    return undefined
+  }
+})
+
+/**
+ * Save a transaction action.
+ *
+ * Records what a transaction *was* — a swap, a stake — beyond its metadata.
+ *
+ * @note When `assetAction` is omitted it defaults to
+ *   `{ assetActionType: 'transfer' }`.
+ */
+export const saveTxAction = route({
+  core: 'wallet.saveTxAction',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/save-tx-action',
+  cli: 'save-tx-action',
+  body: asObject({
+    walletId: asWalletId,
+    txid: doc(asString, 'Which transaction to annotate.'),
+    tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    savedAction: doc(
+      asEdgeTxAction,
+      '`EdgeTxAction` describing what happened, discriminated on `actionType`: swap, stake, fiat, tokenApproval or giftCard.'
+    ),
+    assetAction: asOptional(
+      doc(asEdgeAssetAction, '`EdgeAssetAction`: one `assetActionType`.')
+    )
+  }).withRest,
+  errors: [
+    'BAD_REQUEST',
+    'TOKEN_NOT_FOUND',
+    'WALLET_NOT_FOUND',
+    'AMBIGUOUS_WALLET_ID'
+  ],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    assertTokenId(wallet, ctx.body.tokenId)
+    await wallet.saveTxAction({
+      txid: ctx.body.txid,
+      tokenId: ctx.body.tokenId,
+      assetAction: ctx.body.assetAction ?? { assetActionType: 'transfer' },
+      savedAction: ctx.body.savedAction
+    })
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/uri.ts b/src/cli/engine/routes/uri.ts
new file mode 100644
index 00000000000..aba123d354e
--- /dev/null
+++ b/src/cli/engine/routes/uri.ts
@@ -0,0 +1,84 @@
+import { asObject, asOptional, asString } from 'cleaners'
+import type { EdgeEncodeUri } from 'edge-core-js'
+
+import { doc } from '../doc'
+import { findWallet } from '../resolve'
+import { route } from '../route'
+import { asCoreValue, asWalletId } from '../schemas'
+import { getAccount } from './helpers'
+
+const CURRENCY_CODE_DOC = 'Disambiguates on chains that carry several assets.'
+
+/**
+ * Parse a payment URI or address.
+ *
+ * What the GUI address tile does when you paste or scan something.
+ *
+ * @note `spend` and `make-spend` run their `to` field through this same call,
+ *   so parsing separately is only needed to inspect or confirm first.
+ */
+export const parseUri = route({
+  core: 'wallet.parseUri',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/parse-uri',
+  cli: 'parse-uri',
+  body: asObject({
+    walletId: asWalletId,
+    uri: doc(asString, 'A payment URI or a bare address.'),
+    currencyCode: asOptional(doc(asString, CURRENCY_CODE_DOC))
+  }).withRest,
+  returns: doc(
+    asCoreValue,
+    '`EdgeParsedUri`: publicAddress, nativeAmount, currencyCode, metadata, paymentProtocolUrl, …'
+  ),
+  errors: ['BAD_REQUEST', 'WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    return await wallet.parseUri(ctx.body.uri, ctx.body.currencyCode)
+  }
+})
+
+/**
+ * Build a payment URI.
+ *
+ * For a receive screen or a QR code.
+ *
+ * @note Only these five fields are read; a fuller `EdgeEncodeUri` has its
+ *   extras ignored.
+ */
+export const encodeUri = route({
+  core: 'wallet.encodeUri',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/encode-uri',
+  cli: 'encode-uri',
+  body: asObject({
+    walletId: asWalletId,
+    publicAddress: doc(asString, 'Where the payment should go.'),
+    nativeAmount: asOptional(doc(asString, 'Amount, in the native unit.')),
+    label: asOptional(
+      doc(asString, 'BIP21 `label`; becomes `metadata.name` when parsed back.')
+    ),
+    message: asOptional(
+      doc(asString, 'BIP21 `message`; becomes `metadata.notes`.')
+    ),
+    currencyCode: asOptional(doc(asString, CURRENCY_CODE_DOC))
+  }).withRest,
+  returns: asObject({
+    uri: doc(asString, 'The encoded URI, ready for a QR code.')
+  }),
+  errors: ['BAD_REQUEST', 'WALLET_NOT_FOUND', 'AMBIGUOUS_WALLET_ID'],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    const obj: EdgeEncodeUri = {
+      publicAddress: ctx.body.publicAddress,
+      nativeAmount: ctx.body.nativeAmount,
+      label: ctx.body.label,
+      message: ctx.body.message,
+      currencyCode: ctx.body.currencyCode
+    }
+    const uri = await wallet.encodeUri(obj)
+    return { uri }
+  }
+})
diff --git a/src/cli/engine/routes/vouchers.ts b/src/cli/engine/routes/vouchers.ts
new file mode 100644
index 00000000000..fb0e946e8e4
--- /dev/null
+++ b/src/cli/engine/routes/vouchers.ts
@@ -0,0 +1,76 @@
+import { asArray, asObject, asString } from 'cleaners'
+
+import { doc } from '../doc'
+import { route } from '../route'
+import { asCoreValue } from '../schemas'
+import { getAccount } from './helpers'
+
+const VOUCHER_ID_DOC =
+  'From `pending-vouchers`, or an `OTP_REQUIRED` error’s `details.voucherId`.'
+
+const asVoucherBody = asObject({
+  voucherId: doc(asString, VOUCHER_ID_DOC)
+}).withRest
+
+/**
+ * List pending 2FA vouchers.
+ *
+ * When 2FA blocks a login, the login server issues a voucher that an
+ * already-trusted device can approve or reject.
+ */
+export const pendingVouchers = route({
+  core: 'account.pendingVouchers',
+  method: 'GET',
+  path: '/account/{sessionId}/pending-vouchers',
+  cli: 'pending-vouchers',
+  returns: asObject({
+    pendingVouchers: doc(
+      asArray(asCoreValue),
+      '`EdgePendingVoucher[]`: voucherId, activates, created, deviceDescription, ipDescription.'
+    )
+  }),
+
+  handler(ctx) {
+    // Core leaves this undefined until the login server has reported on it,
+    // and the documented type is an array either way.
+    return { pendingVouchers: getAccount(ctx).pendingVouchers ?? [] }
+  }
+})
+
+/**
+ * Approve a voucher.
+ *
+ * Lets the waiting device finish logging in.
+ */
+export const approveVoucher = route({
+  core: 'account.approveVoucher',
+  method: 'POST',
+  path: '/account/{sessionId}/approve-voucher',
+  cli: 'approve-voucher',
+  body: asVoucherBody,
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).approveVoucher(ctx.body.voucherId)
+    return undefined
+  }
+})
+
+/**
+ * Reject a voucher.
+ *
+ * Denies the waiting device. The login it was issued for cannot complete.
+ */
+export const rejectVoucher = route({
+  core: 'account.rejectVoucher',
+  method: 'POST',
+  path: '/account/{sessionId}/reject-voucher',
+  cli: 'reject-voucher',
+  body: asVoucherBody,
+  errors: ['BAD_REQUEST', 'NETWORK_ERROR'],
+
+  async handler(ctx) {
+    await getAccount(ctx).rejectVoucher(ctx.body.voucherId)
+    return undefined
+  }
+})
diff --git a/src/cli/engine/routes/wallets.ts b/src/cli/engine/routes/wallets.ts
new file mode 100644
index 00000000000..9de5489f9d6
--- /dev/null
+++ b/src/cli/engine/routes/wallets.ts
@@ -0,0 +1,323 @@
+import { div } from 'biggystring'
+import { asArray, asBoolean, asObject, asOptional, asString } from 'cleaners'
+
+import { doc } from '../doc'
+import { WALLET_ERRORS } from '../errorGroups'
+import { TOKEN_ID_DOC } from '../fieldDocs'
+import { assertTokenId, findWallet, getMultiplier } from '../resolve'
+import { route } from '../route'
+import {
+  asBalance,
+  asCoreValue,
+  asCreateCurrencyWallet,
+  asQueryNonNegativeInteger,
+  asRequestTokenId,
+  asWalletId
+} from '../schemas'
+import { getAccount, summarizeWallet } from './helpers'
+
+/**
+ * Wallet detail.
+ *
+ * @coreNote Engine composite of EdgeCurrencyWallet properties plus its
+ *   EdgeCurrencyConfig token map.
+ */
+export const walletInfo = route({
+  core: null,
+  method: 'GET',
+  path: '/account/{sessionId}/wallet',
+  cli: 'wallet-info',
+  query: asObject({ walletId: asWalletId }).withRest,
+  returns: doc(
+    asCoreValue,
+    'Every WalletSummary field, plus denominations and walletSettings. `allTokens` is not here \u2014 `wallet-tokens` exists to carry it, and returning it from both sent the same map twice in a session that calls both.'
+  ),
+  errors: WALLET_ERRORS,
+
+  handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    return {
+      ...summarizeWallet(wallet),
+      denominations: wallet.currencyInfo.denominations,
+      walletSettings: wallet.walletSettings
+    }
+  }
+})
+
+/**
+ * Rename a wallet.
+ */
+export const renameWallet = route({
+  core: 'wallet.renameWallet',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/rename-wallet',
+  cli: 'rename-wallet',
+  body: asObject({
+    walletId: asWalletId,
+    name: doc(asString, 'The new display name.')
+  }).withRest,
+  errors: ['BAD_REQUEST', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    await wallet.renameWallet(ctx.body.name)
+    return undefined
+  }
+})
+
+/**
+ * Change a wallet's fiat currency.
+ *
+ * Affects how balances and history are priced, not the asset itself.
+ */
+export const setFiatCurrencyCode = route({
+  core: 'wallet.setFiatCurrencyCode',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/set-fiat-currency-code',
+  cli: 'set-fiat-currency-code',
+  body: asObject({
+    walletId: asWalletId,
+    fiatCurrencyCode: doc(asString, 'e.g. `iso:EUR`.')
+  }).withRest,
+  errors: ['BAD_REQUEST', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    await wallet.setFiatCurrencyCode(ctx.body.fiatCurrencyCode)
+    return undefined
+  }
+})
+
+/**
+ * Pause or resume a wallet engine.
+ *
+ * A paused wallet stops syncing, which is how a caller quiets a chain it does
+ * not currently care about.
+ */
+export const changePaused = route({
+  core: 'wallet.changePaused',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/change-paused',
+  cli: 'change-paused',
+  body: asObject({
+    walletId: asWalletId,
+    paused: doc(asBoolean, 'True to stop syncing.')
+  }).withRest,
+  errors: ['BAD_REQUEST', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    await wallet.changePaused(ctx.body.paused)
+    return undefined
+  }
+})
+
+/**
+ * Nudge one wallet to sync.
+ *
+ * @note Named `wallet-sync` on the CLI because `sync` is `account.sync`.
+ */
+export const walletSync = route({
+  core: 'wallet.sync',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/sync',
+  cli: 'wallet-sync',
+  body: asObject({ walletId: asWalletId }).withRest,
+  errors: WALLET_ERRORS,
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    await wallet.sync()
+    return undefined
+  }
+})
+
+/**
+ * Rescan the blockchain from scratch.
+ *
+ * Drops cached chain state and re-scans. Expensive, and the wallet reports an
+ * incomplete balance until it finishes.
+ *
+ * @note Returns when the resync is requested, not when it completes. Watch
+ *   `syncRatio` for progress.
+ */
+export const resyncBlockchain = route({
+  core: 'wallet.resyncBlockchain',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/resync-blockchain',
+  cli: 'resync-blockchain',
+  body: asObject({ walletId: asWalletId }).withRest,
+  errors: WALLET_ERRORS,
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    await wallet.resyncBlockchain()
+    return undefined
+  }
+})
+
+/**
+ * Split a wallet into another chain.
+ *
+ * Forked-chain support: derive a wallet of a different type from the same
+ * keys. `list-splittable-wallet-types` says which are valid.
+ */
+export const splitWallet = route({
+  core: 'wallet.split',
+  method: 'POST',
+  path: '/account/{sessionId}/wallet/split',
+  cli: 'split',
+  body: asObject({
+    walletId: asWalletId,
+    splitWallets: doc(
+      asArray(asCreateCurrencyWallet),
+      '`EdgeSplitCurrencyWallet[]`: walletType, plus optional name and fiatCurrencyCode.'
+    )
+  }).withRest,
+  returns: asObject({
+    results: doc(asArray(asCoreValue), 'Per-entry outcomes, like batch create.')
+  }),
+  errors: ['BAD_REQUEST', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.body.walletId)
+    const results = await wallet.split(ctx.body.splitWallets)
+    return {
+      results: results.map(result =>
+        result.ok
+          ? { ok: true, wallet: summarizeWallet(result.result) }
+          : {
+              ok: false,
+              error:
+                result.error instanceof Error
+                  ? result.error.message
+                  : String(result.error)
+            }
+      )
+    }
+  }
+})
+
+/**
+ * Dump wallet engine state.
+ *
+ * Plugin-defined debug output. Shape varies by plugin and can be very large.
+ */
+export const dumpData = route({
+  core: 'wallet.dumpData',
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/dump-data',
+  cli: 'dump-data',
+  query: asObject({ walletId: asWalletId }).withRest,
+  returns: doc(asCoreValue, '`EdgeDataDump`, straight from the plugin.'),
+  errors: WALLET_ERRORS,
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    return await wallet.dumpData()
+  }
+})
+
+/**
+ * Balances for every asset in the wallet.
+ *
+ * The native currency plus every enabled token.
+ *
+ * @note On the CLI, omit `--token-id` for the native asset rather than passing
+ *   the literal `null`.
+ * @coreNote Rendered as an array, with currencyCode and displayAmount added
+ *   from the wallet's denominations.
+ */
+export const balanceMap = route({
+  core: 'wallet.balanceMap',
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/balance-map',
+  cli: {
+    command: 'balance-map',
+    custom: true,
+    extra: {
+      tokenId: {
+        kind: 'string',
+        doc: 'Client-side filter; core has no single-balance accessor.'
+      }
+    }
+  },
+  query: asObject({ walletId: asWalletId }).withRest,
+  returns: asObject({
+    balances: doc(
+      asArray(asBalance),
+      'One entry per asset the wallet holds, native coin first: `tokenId`, `currencyCode`, `nativeAmount`, `displayAmount` and `unknownToken`. A token the plugin reports a balance for but whose config it no longer carries is listed with `unknownToken: true` and a null `displayAmount`, rather than failing the whole wallet.'
+    )
+  }),
+  errors: WALLET_ERRORS,
+
+  handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    // One rule per entry, and the listing stays alive. Two adjacent lines
+    // used to disagree: `getMultiplier` threw TOKEN_NOT_FOUND for an absent
+    // token while the line below it tolerated the same absence with
+    // `?? tokenId`. `wallet.balanceMap` is not filtered against `allTokens`,
+    // so a token deleted from the config while the engine ran made
+    // `balance-map` answer 404 for the *whole wallet*, naming a token the
+    // caller never asked about, until the engine restarted.
+    const balances = []
+    for (const [tokenId, nativeAmount] of wallet.balanceMap.entries()) {
+      const token =
+        tokenId == null ? null : wallet.currencyConfig.allTokens[tokenId]
+      if (tokenId != null && token == null) {
+        // The plugin still reports a balance for an asset its config no
+        // longer describes. Nothing here can price or name it, so report it
+        // as unknown rather than failing the wallet.
+        balances.push({
+          tokenId,
+          currencyCode: tokenId,
+          nativeAmount,
+          displayAmount: null,
+          unknownToken: true
+        })
+        continue
+      }
+      const multiplier = getMultiplier(wallet, tokenId)
+      balances.push({
+        tokenId,
+        currencyCode: token?.currencyCode ?? wallet.currencyInfo.currencyCode,
+        nativeAmount,
+        displayAmount: div(nativeAmount, multiplier, 18),
+        unknownToken: false
+      })
+    }
+    return { balances }
+  }
+})
+
+/**
+ * Receive addresses.
+ */
+export const getAddresses = route({
+  core: 'wallet.getAddresses',
+  method: 'GET',
+  path: '/account/{sessionId}/wallet/get-addresses',
+  cli: 'get-addresses',
+  query: asObject({
+    walletId: asWalletId,
+    tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
+    forceIndex: asOptional(
+      doc(asQueryNonNegativeInteger, 'Derive at a specific index.')
+    )
+  }).withRest,
+  returns: asObject({
+    addresses: doc(
+      asArray(asCoreValue),
+      '`EdgeAddress[]`: addressType, publicAddress, nativeBalance.'
+    )
+  }),
+  errors: ['TOKEN_NOT_FOUND', ...WALLET_ERRORS],
+
+  async handler(ctx) {
+    const wallet = findWallet(getAccount(ctx), ctx.query.valid.walletId)
+    const { tokenId, forceIndex } = ctx.query.valid
+    assertTokenId(wallet, tokenId)
+    const addresses = await wallet.getAddresses({ tokenId, forceIndex })
+    return { addresses }
+  }
+})

From 66cdf19bd360efb8dfe78a9c7e87f44be2791189 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 11:44:17 -0700
Subject: [PATCH 12/24] Publish the CLI as its own npm package
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The CLI is built from this repository but is not this repository: rollup
inlines every module it reaches under `src/`, so a published package is the
two bundles, the native HMAC addon, the CLI document as its README and
`LICENSE`. Nothing about it needs the CLI to move to a workspace or a
submodule, and the app's own `package.json` stays `private: true` — what is
published is a separate manifest assembled in a temporary directory, so the
app itself cannot reach npm by accident.

`src/cli/npmMeta.ts` holds the decisions: the scoped name, the bin name, the
licence, and the per-platform native packages, which become
`optionalDependencies` once they exist. The version is not among them. The
CLI ships in lockstep with the app, so the manifest takes it from the app's
`package.json`: there is no second number to bump, and a published CLI says
which app release it corresponds to. Lockstep costs one thing worth knowing
before a release — npm will not replace an existing version, so a CLI-only
fix goes out on the next app version bump rather than on its own.

The dependency list is derived, not written down. `rollup.config.cli.mjs`
externalises every key of the app's `dependencies` — its whole runtime set —
so the bundles leave all of them as bare `require`s while needing fifteen,
and anything the app does not declare is inlined instead.
`buildCliManifest.ts` walks the module graph from both entry points, keeps
the bare specifiers the app declares as dependencies, drops builtins and
type-only imports, and treats the rest as bundled. Checked against the
bundles' own `require` calls: fifteen declared, fifteen required, none
missing and none spare. Hand-maintaining that list fails as an `npm install`
that succeeds and a CLI that cannot resolve a module on first run, so
`cli:manifest:check` gates it in `verify` and in CI — where, unlike the five
documentation gates, `npm run prepare` does not regenerate it first.

`publishCli.ts` builds, stages and publishes. With `edgeKey.json` it runs
`build:cli:all`, so a build server needs that one file to produce a CLI with
full native signing; without it the addon cannot be built, so publishing
takes an explicit `--allow-unsigned` and the staged README says the build
cannot sign. A dirty tree is refused, since the registry copy could not then
be re-derived from any commit. `--dry-run` packs without publishing and
`--out` stages for inspection.

Verified end to end: the staged tarball is 924 kB over six files, and
installed into an empty project the client answers `--help` and the engine
boots and serves `engine-status`.

Two things the exercise surfaced, neither fixed here. `uuid` is imported by
`src/util/utils.ts` and declared nowhere, resolved only because other
packages happen to depend on it; rollup inlines it, so the published CLI is
unaffected, but the build rests on a transitive resolution. And installing
the package costs 2.3 GB across 69,756 files, of which about 1.3 GB is
React Native mobile binaries — iOS simulator slices and Android libraries
for the privacy coins — reached through `edge-currency-accountbased`, which
also brings `react-native` itself. A Node CLI can load none of it.
---
 .travis.yml                       |   6 +
 docs/EDGE_CLI.md                  |  52 ++++++
 package.json                      |   5 +-
 scripts/buildCliManifest.ts       | 253 ++++++++++++++++++++++++++++++
 scripts/publishCli.ts             | 221 ++++++++++++++++++++++++++
 scripts/writeIfChanged.ts         |  18 ++-
 src/cli/generated/npmPackage.json |  52 ++++++
 src/cli/npmMeta.ts                |  90 +++++++++++
 8 files changed, 692 insertions(+), 5 deletions(-)
 create mode 100644 scripts/buildCliManifest.ts
 create mode 100644 scripts/publishCli.ts
 create mode 100644 src/cli/generated/npmPackage.json
 create mode 100644 src/cli/npmMeta.ts

diff --git a/.travis.yml b/.travis.yml
index bdd0ffb8816..0c179f20fd8 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -20,6 +20,12 @@ script:
   # artifacts, so without this nothing anywhere notices a stale
   # `commands.json` — and that file is the table the CLI parses argv against.
   - npm run docs:api:gates
+  # Not regenerated by `npm run prepare` above, so unlike the gates above this
+  # one does fail on a stale committed artifact: the published CLI's
+  # dependency list is derived from the module graph, and a new import that
+  # did not reach the manifest is an `npm install` that succeeds and a CLI
+  # that cannot resolve a module.
+  - npm run cli:manifest:check
   - npm run test:cli:node-safe
   - npm test
   - npm run test:cli:offline
diff --git a/docs/EDGE_CLI.md b/docs/EDGE_CLI.md
index de427311d75..3440b2fdcfa 100644
--- a/docs/EDGE_CLI.md
+++ b/docs/EDGE_CLI.md
@@ -497,3 +497,55 @@ Full method/path/body/error documentation is generated:
 **[docs/api/dist/index.html](./api/dist/index.html)**, with an OpenAPI 3.1
 document beside it at `docs/api/dist/openapi.json`. The source of truth is
 `docs/api/`; see [docs/api/README.md](./api/README.md).
+
+## Publishing to npm
+
+The CLI ships as its own scoped package, built from this repository but not
+containing it: rollup inlines every module the CLI reaches from `src/`, so the
+published package is the two bundles, the native addon, this document as its
+README, and `LICENSE`. The app's `package.json` stays `private: true` and is
+never the thing published — `scripts/publishCli.ts` assembles a separate
+manifest in a temporary directory.
+
+| File | Role |
+| --- | --- |
+| `src/cli/npmMeta.ts` | The decisions: package name, bin name, licence, the per-platform native packages. |
+| `src/cli/generated/npmPackage.json` | The manifest, generated. `npm run cli:manifest` writes it; `cli:manifest:check` is the gate. |
+| `scripts/buildCliManifest.ts` | Derives the dependency list from the module graph. |
+| `scripts/publishCli.ts` | Builds, stages and publishes. |
+
+The version is not a decision: the CLI ships in lockstep with the app, so the
+manifest takes it from the app's own `package.json`. There is no second number
+to bump, and a published CLI says which app release it corresponds to. The
+cost is that each version can be published once, since npm will not replace an
+existing one — so a CLI-only fix goes out on the next app version bump rather
+than on its own.
+
+The dependency list is derived rather than written down. `rollup.config.cli.mjs`
+externalises every key of the app's `dependencies`, so the bundles leave all of
+them as bare `require`s while needing about a dozen; anything the app does not
+declare is inlined instead. The generator walks the module graph from both
+entry points, keeps the bare specifiers the app declares as dependencies,
+skips builtins and type-only imports, and treats the rest as bundled. The
+result is checked against the built bundles' own `require` calls.
+
+A build server needs `edgeKey.json` and nothing else:
+
+```sh
+npm run publish:cli -- --dry-run      # build, stage, pack, publish nothing
+npm run publish:cli -- --out /tmp/pkg # stage for inspection, then stop
+npm run publish:cli                   # publish
+```
+
+With `edgeKey.json` present the script runs `build:cli:all`, which generates
+the XOR-split secret shards, compiles the Node HMAC addon and copies it beside
+the bundles. Without the key the addon cannot be built, so publishing requires
+`--allow-unsigned` and the staged README says the build cannot sign. A publish
+from a dirty tree is refused, because the registry copy could not then be
+re-derived from any commit.
+
+The addon is compiled for the build machine's platform and Node ABI.
+`loadNodeApiSignerNative` answers `null` when it cannot load one, so a CLI on
+another platform still runs with unsigned info-server requests.
+`CliPackageMeta.nativePackages` is where per-platform packages are declared
+once they are published; it is empty until then.
diff --git a/package.json b/package.json
index d5adb1c1c4b..760b840bf93 100644
--- a/package.json
+++ b/package.json
@@ -60,7 +60,7 @@
     "theme": "node -r sucrase/register ./scripts/themeServer.ts",
     "updateVersion": "node -r sucrase/register scripts/updateVersion.ts",
     "updot": "EDGE_MODE=development updot",
-    "verify": "npm run lint && npm run typechain && tsc && npm run docs:api:gates && npm run test:cli:node-safe && npm run test:all",
+    "verify": "npm run lint && npm run typechain && tsc && npm run docs:api:gates && npm run cli:manifest:check && npm run test:cli:node-safe && npm run test:all",
     "watch": "npm test -- --watch",
     "update-eslint-warnings": "node -r sucrase/register ./scripts/updateEslintWarnings.ts",
     "cli": "node -r sucrase/register src/cli/index.ts",
@@ -70,6 +70,9 @@
     "build:cli:all": "npm run build:cli:native && npm run build:cli && npm run build:cli:copy-native",
     "build:cli:native": "bash ./scripts/buildNodeApiSigner.sh",
     "build:cli:copy-native": "mkdir -p lib && cp -f native/edge-api-signer/node/build/Release/edge_api_signer.node lib/edge_api_signer.node",
+    "cli:manifest": "node -r sucrase/register scripts/buildCliManifest.ts",
+    "cli:manifest:check": "node -r sucrase/register scripts/buildCliManifest.ts --check",
+    "publish:cli": "node -r sucrase/register scripts/publishCli.ts",
     "docs:api": "npm run docs:api:cli && node -r sucrase/register scripts/buildApiDocs.ts",
     "docs:api:cli": "node -r sucrase/register scripts/buildCliCommands.ts && node -r sucrase/register scripts/buildCliHelp.ts",
     "docs:api:check": "node -r sucrase/register scripts/buildCliCommands.ts --check && node -r sucrase/register scripts/buildCliHelp.ts --check && node -r sucrase/register scripts/buildApiDocs.ts --check",
diff --git a/scripts/buildCliManifest.ts b/scripts/buildCliManifest.ts
new file mode 100644
index 00000000000..f514ba241c5
--- /dev/null
+++ b/scripts/buildCliManifest.ts
@@ -0,0 +1,253 @@
+/**
+ * Generates `src/cli/generated/npmPackage.json`, the manifest the published
+ * CLI package ships.
+ *
+ * The dependency list is the whole reason this exists. `rollup.config.cli.mjs`
+ * externalises `Object.keys(packageJson.dependencies)` — the app's entire
+ * runtime dependency set — so the bundles leave every one of them as a bare
+ * `require`, while actually needing about a dozen. A hand-written list would
+ * be wrong the first time a module gained an import, and the failure mode is
+ * the worst kind: `npm install` succeeds and the CLI dies on first run with
+ * `Cannot find module`.
+ *
+ * So the list is read off the module graph, from both entry points, the same
+ * way rollup decides what to externalise:
+ *
+ *   - a bare specifier reachable from either entry, that the app declares in
+ *     `dependencies`, is declared: that is exactly the set rollup
+ *     externalises, so the bundle will `require` it
+ *   - a Node builtin needs no declaration
+ *   - anything else rollup resolves and inlines, so declaring it would
+ *     install a package the bundle does not load
+ *
+ * Type-only imports are skipped, because Babel strips them before rollup sees
+ * them and a package imported only for its types is not a runtime dependency.
+ *
+ * The graph over-approximates, deliberately. It does not tree-shake at the
+ * symbol level, so it sees imports whose bindings rollup goes on to drop —
+ * `uuid`, reached through `src/util/utils.ts`, is in neither bundle. Erring
+ * that way is the safe direction: an extra declared package installs and sits
+ * unused, where a missing one is an `npm install` that succeeds and a CLI that
+ * dies on first run.
+ *
+ * `--check` turns this into a staleness gate, like the documentation
+ * generators: a new import cannot reach a commit while the manifest still
+ * describes the old dependency set.
+ */
+import fs from 'fs'
+import { builtinModules } from 'module'
+import path from 'path'
+import ts from 'typescript'
+
+import { CLI_PACKAGE_FILES, CLI_PACKAGE_META } from '../src/cli/npmMeta'
+import { writeIfChanged } from './writeIfChanged'
+
+const ROOT = path.resolve(__dirname, '..')
+const OUT = path.join(ROOT, 'src/cli/generated/npmPackage.json')
+const ENTRIES = ['src/cli/index.ts', 'src/cli/engine/index.ts']
+
+/** Extensions tried when resolving a relative specifier, in order. */
+const EXTENSIONS = [
+  '',
+  '.ts',
+  '.tsx',
+  '.js',
+  '.mjs',
+  '.json',
+  '/index.ts',
+  '/index.tsx',
+  '/index.js'
+]
+
+const BUILTINS = new Set([
+  ...builtinModules,
+  ...builtinModules.map(m => `node:${m}`)
+])
+
+/**
+ * The package a specifier belongs to.
+ *
+ * `csv-stringify/lib/browser/sync` is a subpath of `csv-stringify`, and a
+ * scoped package keeps two segments. Declaring the subpath instead of the
+ * package would be an unresolvable dependency name.
+ */
+function packageOf(specifier: string): string {
+  const parts = specifier.split('/')
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]
+}
+
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const base = path.resolve(path.dirname(fromFile), specifier)
+  for (const extension of EXTENSIONS) {
+    const candidate = base + extension
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate
+    }
+  }
+  return null
+}
+
+/** Every module specifier a file imports *as a value*. */
+function valueSpecifiers(file: string): string[] {
+  const text = fs.readFileSync(file, 'utf8')
+  const source = ts.createSourceFile(
+    file,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  )
+  const out: string[] = []
+
+  const add = (node: ts.Expression | undefined): void => {
+    if (node != null && ts.isStringLiteral(node)) out.push(node.text)
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isImportDeclaration(node)) {
+      const clause = node.importClause
+      // No clause at all is a side-effect import, which is a value import:
+      // `import './commands/all'` is how every command registers itself.
+      const typeOnly =
+        clause != null &&
+        (clause.isTypeOnly ||
+          (clause.name == null &&
+            clause.namedBindings != null &&
+            ts.isNamedImports(clause.namedBindings) &&
+            clause.namedBindings.elements.every(e => e.isTypeOnly)))
+      if (!typeOnly) add(node.moduleSpecifier)
+    } else if (ts.isExportDeclaration(node) && node.moduleSpecifier != null) {
+      if (!node.isTypeOnly) add(node.moduleSpecifier)
+    } else if (
+      ts.isCallExpression(node) &&
+      (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) &&
+          node.expression.text === 'require'))
+    ) {
+      add(node.arguments[0])
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return out
+}
+
+/** Walk the graph from the entry points, collecting bare specifiers. */
+function collectBarePackages(): { packages: Set<string>; files: number } {
+  const seen = new Set<string>()
+  const bare = new Set<string>()
+  const queue = ENTRIES.map(e => path.join(ROOT, e))
+
+  while (queue.length > 0) {
+    const file = queue.pop()
+    if (file == null || seen.has(file)) continue
+    seen.add(file)
+    // A `.json` import is inlined by `@rollup/plugin-json`, and a `.js` file
+    // in this graph is a hand-written shim with no further imports worth
+    // following through the TypeScript parser.
+    if (!file.endsWith('.ts') && !file.endsWith('.tsx')) continue
+
+    for (const specifier of valueSpecifiers(file)) {
+      if (specifier.startsWith('.')) {
+        const resolved = resolveRelative(file, specifier)
+        if (resolved == null) {
+          throw new Error(
+            `${path.relative(ROOT, file)} imports "${specifier}", ` +
+              'which does not resolve to a file.'
+          )
+        }
+        queue.push(resolved)
+      } else if (!BUILTINS.has(specifier)) {
+        bare.add(packageOf(specifier))
+      }
+    }
+  }
+  return { packages: bare, files: seen.size }
+}
+
+const appPackage = JSON.parse(
+  fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')
+) as {
+  version: string
+  dependencies: Record<string, string>
+  devDependencies: Record<string, string>
+}
+
+const { packages, files } = collectBarePackages()
+
+const dependencies: Record<string, string> = {}
+const bundled: string[] = []
+const undeclared: string[] = []
+for (const name of [...packages].sort()) {
+  if (appPackage.dependencies[name] != null) {
+    // The app's own range, so the CLI installs against what the app is tested
+    // with rather than a range nobody has run.
+    dependencies[name] = appPackage.dependencies[name]
+  } else if (appPackage.devDependencies[name] != null) {
+    bundled.push(name)
+  } else {
+    undeclared.push(name)
+  }
+}
+
+const meta = CLI_PACKAGE_META
+// Lockstep with the app, so there is no second version to bump and a reader
+// can tell at a glance which app release a published CLI corresponds to.
+const version = appPackage.version
+const optionalDependencies: Record<string, string> = {}
+for (const native of meta.nativePackages) {
+  optionalDependencies[native.name] = version
+}
+
+const manifest = {
+  $comment:
+    'GENERATED FILE — DO NOT EDIT. Produced by scripts/buildCliManifest.ts ' +
+    'from src/cli/npmMeta.ts and the module graph under src/cli. ' +
+    '`scripts/publishCli.ts` strips this key before publishing. ' +
+    'Run `npm run cli:manifest` to regenerate.',
+  name: meta.name,
+  version,
+  description: meta.description,
+  keywords: meta.keywords,
+  homepage: meta.homepage,
+  repository: {
+    type: 'git',
+    url: meta.repositoryUrl,
+    directory: meta.repositoryDirectory
+  },
+  license: meta.license,
+  author: meta.author,
+  engines: meta.engines,
+  bin: { [meta.binName]: 'edgeCli.js' },
+  files: CLI_PACKAGE_FILES,
+  dependencies,
+  ...(Object.keys(optionalDependencies).length > 0
+    ? { optionalDependencies }
+    : {})
+}
+
+const changed = writeIfChanged(OUT, JSON.stringify(manifest, null, 2) + '\n', {
+  why: 'The CLI gained or lost an import, so its npm dependencies moved.',
+  run: 'npm run cli:manifest'
+})
+console.log(
+  `${changed ? '✓ wrote' : '· unchanged'} src/cli/generated/npmPackage.json ` +
+    `(${
+      Object.keys(dependencies).length
+    } dependencies from ${files} modules, ` +
+    `${bundled.length} bundled)`
+)
+if (bundled.length > 0) {
+  console.log(`  bundled, not declared: ${bundled.join(', ')}`)
+}
+if (undeclared.length > 0) {
+  // Not fatal: rollup inlines them, so the published package is fine. It is
+  // the *build* that rests on a package nobody declared, resolved only
+  // because something else happens to depend on it — so a dependency bump
+  // elsewhere can break this bundle with no change here. Worth a line every
+  // time rather than a silent pass.
+  console.log(
+    `  resolved only transitively (declare these if the build should not ` +
+      `depend on luck): ${undeclared.join(', ')}`
+  )
+}
diff --git a/scripts/publishCli.ts b/scripts/publishCli.ts
new file mode 100644
index 00000000000..3d6b2df13cb
--- /dev/null
+++ b/scripts/publishCli.ts
@@ -0,0 +1,221 @@
+/**
+ * Stages and publishes the CLI as its own npm package.
+ *
+ * Nothing about this needs the CLI to move out of this repository. Rollup has
+ * already inlined every module it uses from `src/`, so the published package
+ * is two bundles, an optional native addon, a README and a licence — the app's
+ * sources are not part of it and the published manifest is not the app's.
+ * That is also why the app's own `package.json` stays `private: true`: the
+ * thing published here is assembled in a temporary directory and the app
+ * itself can never be pushed to npm by accident.
+ *
+ * Usage:
+ *
+ *   npm run publish:cli -- --dry-run         # pack and report, publish nothing
+ *   npm run publish:cli -- --out /tmp/pkg    # stage for inspection, then stop
+ *   npm run publish:cli                      # publish
+ *   npm run publish:cli -- --tag next        # publish under a dist-tag
+ *
+ * A build server needs `edgeKey.json` and nothing else: with it,
+ * `build:cli:all` generates the XOR-split secret shards, compiles the Node
+ * HMAC addon and rolls up both bundles. Without it the addon cannot be built
+ * at all, so publishing then needs `--allow-unsigned` said out loud rather
+ * than quietly shipping a CLI that cannot sign.
+ */
+import { spawnSync } from 'child_process'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { CLI_PACKAGE_META } from '../src/cli/npmMeta'
+
+const ROOT = path.resolve(__dirname, '..')
+const MANIFEST = path.join(ROOT, 'src/cli/generated/npmPackage.json')
+const SIGNER = 'edge_api_signer.node'
+
+const argv = process.argv.slice(2)
+const has = (flag: string): boolean => argv.includes(flag)
+const valueOf = (flag: string): string | undefined => {
+  const i = argv.indexOf(flag)
+  return i === -1 ? undefined : argv[i + 1]
+}
+
+const dryRun = has('--dry-run')
+const stageOnly = valueOf('--out')
+const allowUnsigned = has('--allow-unsigned')
+const allowDirty = has('--allow-dirty')
+const skipBuild = has('--no-build')
+const tag = valueOf('--tag')
+
+function run(command: string, args: string[], cwd = ROOT): void {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit' })
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed (${result.status})`)
+  }
+}
+
+function capture(command: string, args: string[]): string {
+  const result = spawnSync(command, args, { cwd: ROOT, encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : ''
+}
+
+// ------------------------------------------------------------ preconditions
+
+// A publish from a dirty tree cannot be reproduced from any commit, and the
+// one artifact nobody can re-derive later is the one in the registry.
+if (!allowDirty && capture('git', ['status', '--porcelain']) !== '') {
+  throw new Error(
+    'The working tree has uncommitted changes. Commit them, or pass ' +
+      '--allow-dirty if this is deliberate.'
+  )
+}
+
+// The manifest is generated and committed, so a stale one would publish the
+// wrong dependency list. `--check` is the same gate CI runs.
+run('node', [
+  '-r',
+  'sucrase/register',
+  'scripts/buildCliManifest.ts',
+  '--check'
+])
+
+const hasKey = fs.existsSync(path.join(ROOT, 'edgeKey.json'))
+if (!skipBuild) {
+  if (hasKey) {
+    run('npm', ['run', 'build:cli:all'])
+  } else {
+    if (!allowUnsigned) {
+      throw new Error(
+        'edgeKey.json is absent, so the Node HMAC addon cannot be built and ' +
+          'the published CLI could not sign info-server requests. Put the key ' +
+          'in place, or pass --allow-unsigned to publish without it.'
+      )
+    }
+    console.warn(
+      '! edgeKey.json absent: building without the native signer. The ' +
+        'published CLI will fall back to unsigned info-server requests.'
+    )
+    run('npm', ['run', 'build:cli'])
+  }
+}
+
+// ----------------------------------------------------------------- staging
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST, 'utf8')) as Record<
+  string,
+  unknown
+>
+// The in-repo copy carries a "generated, do not edit" marker. Published
+// manifests should not.
+delete manifest.$comment
+
+const stage =
+  stageOnly ?? fs.mkdtempSync(path.join(os.tmpdir(), 'edge-cli-publish-'))
+fs.mkdirSync(stage, { recursive: true })
+
+interface Staged {
+  from: string
+  to: string
+  required: boolean
+}
+const files: Staged[] = [
+  { from: 'lib/edgeCli.js', to: 'edgeCli.js', required: true },
+  { from: 'lib/edgeEngine.js', to: 'edgeEngine.js', required: true },
+  { from: `lib/${SIGNER}`, to: SIGNER, required: false },
+  { from: 'LICENSE', to: 'LICENSE', required: true }
+]
+
+for (const file of files) {
+  const source = path.join(ROOT, file.from)
+  if (!fs.existsSync(source)) {
+    if (file.required) {
+      throw new Error(`${file.from} is missing. Run \`npm run build:cli\`.`)
+    }
+    continue
+  }
+  fs.copyFileSync(source, path.join(stage, file.to))
+}
+
+// The bin needs the execute bit. npm infers it from the shebang on install,
+// but a packed tarball that already has it behaves the same way everywhere.
+fs.chmodSync(path.join(stage, 'edgeCli.js'), 0o755)
+
+const signed = fs.existsSync(path.join(stage, SIGNER))
+
+// `docs/EDGE_CLI.md` is the CLI's documentation, so it is the README rather
+// than a second description written to drift from it. The header is the part
+// that only makes sense once the thing has a package name.
+const header = [
+  `# ${CLI_PACKAGE_META.name}`,
+  '',
+  CLI_PACKAGE_META.description,
+  '',
+  '```sh',
+  `npm install -g ${CLI_PACKAGE_META.name}`,
+  `${CLI_PACKAGE_META.binName} --help`,
+  '```',
+  '',
+  'Or without installing:',
+  '',
+  '```sh',
+  `npx ${CLI_PACKAGE_META.name} --help`,
+  '```',
+  '',
+  signed
+    ? ''
+    : 'This build has no native HMAC signer, so it makes unsigned ' +
+      'info-server requests and cannot read gated plugin keys.\n',
+  '---',
+  ''
+].join('\n')
+fs.writeFileSync(
+  path.join(stage, 'README.md'),
+  header + fs.readFileSync(path.join(ROOT, 'docs/EDGE_CLI.md'), 'utf8')
+)
+
+fs.writeFileSync(
+  path.join(stage, 'package.json'),
+  JSON.stringify(manifest, null, 2) + '\n'
+)
+
+// ----------------------------------------------------------------- report
+
+const staged = fs.readdirSync(stage).sort()
+console.log(`\nStaged ${manifest.name as string}@${manifest.version as string}`)
+console.log(`  ${stage}`)
+let total = 0
+for (const name of staged) {
+  const size = fs.statSync(path.join(stage, name)).size
+  total += size
+  console.log(`  ${(size / 1024).toFixed(0).padStart(7)} KB  ${name}`)
+}
+console.log(`  ${(total / 1024).toFixed(0).padStart(7)} KB  total (unpacked)`)
+console.log(
+  `  native signer: ${
+    signed ? `included (${process.platform}-${process.arch})` : 'ABSENT'
+  }`
+)
+
+if (stageOnly != null) {
+  console.log('\n--out given, so stopping before publish.')
+  process.exit(0)
+}
+
+// ---------------------------------------------------------------- publish
+
+const publishArgs = ['publish']
+// A scoped package is restricted unless this says otherwise, and the first
+// publish is the one that decides.
+publishArgs.push('--access', 'public')
+if (tag != null) publishArgs.push('--tag', tag)
+if (dryRun) publishArgs.push('--dry-run')
+console.log(`\n$ npm ${publishArgs.join(' ')}\n`)
+run('npm', publishArgs, stage)
+
+if (dryRun) {
+  console.log('\nDry run: nothing was published.')
+} else {
+  console.log(
+    `\nPublished ${manifest.name as string}@${manifest.version as string}.`
+  )
+}
diff --git a/scripts/writeIfChanged.ts b/scripts/writeIfChanged.ts
index c70f668e214..247cdc69a8e 100644
--- a/scripts/writeIfChanged.ts
+++ b/scripts/writeIfChanged.ts
@@ -19,9 +19,19 @@ const CHECK_ONLY = process.argv.includes('--check')
  * nothing about the source moved. Returns true when something was written.
  *
  * Under `--check` nothing is written; a file that would have changed throws
- * instead.
+ * instead. `hint` names the command that regenerates this particular
+ * artifact: the route generators are not the only callers any more, and
+ * telling someone to run `npm run docs:api` when the stale file is the npm
+ * manifest sends them somewhere that cannot fix it.
  */
-export function writeIfChanged(file: string, contents: string): boolean {
+export function writeIfChanged(
+  file: string,
+  contents: string,
+  hint = {
+    why: 'A route declaration changed without regenerating it.',
+    run: 'npm run docs:api'
+  }
+): boolean {
   if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === contents) {
     return false
   }
@@ -29,8 +39,8 @@ export function writeIfChanged(file: string, contents: string): boolean {
     // A stack trace would bury the one line that matters.
     console.error(
       `✗ ${path.relative(process.cwd(), file)} is out of date.\n` +
-        '  A route declaration changed without regenerating it.\n' +
-        '  Run `npm run docs:api` and commit the result.'
+        `  ${hint.why}\n` +
+        `  Run \`${hint.run}\` and commit the result.`
     )
     process.exit(1)
   }
diff --git a/src/cli/generated/npmPackage.json b/src/cli/generated/npmPackage.json
new file mode 100644
index 00000000000..f0de89195fe
--- /dev/null
+++ b/src/cli/generated/npmPackage.json
@@ -0,0 +1,52 @@
+{
+  "$comment": "GENERATED FILE — DO NOT EDIT. Produced by scripts/buildCliManifest.ts from src/cli/npmMeta.ts and the module graph under src/cli. `scripts/publishCli.ts` strips this key before publishing. Run `npm run cli:manifest` to regenerate.",
+  "name": "@edgeapp/cli",
+  "version": "4.51.2",
+  "description": "Command-line access to an Edge account: wallets, balances, transactions and swaps.",
+  "keywords": [
+    "edge",
+    "cryptocurrency",
+    "wallet",
+    "cli",
+    "bitcoin",
+    "ethereum"
+  ],
+  "homepage": "https://edge.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EdgeApp/edge-react-gui.git",
+    "directory": "src/cli"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Edge, Inc.",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "edge-cli": "edgeCli.js"
+  },
+  "files": [
+    "edgeCli.js",
+    "edgeEngine.js",
+    "edge_api_signer.node",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "base-x": "^4.0.0",
+    "biggystring": "^4.3.0",
+    "cleaners": "^0.3.17",
+    "csv-stringify": "^5.6.2",
+    "date-fns": "^2.22.1",
+    "edge-core-js": "^2.50.0",
+    "edge-currency-accountbased": "^4.97.0",
+    "edge-currency-plugins": "^3.14.0",
+    "edge-exchange-plugins": "^2.57.4",
+    "edge-info-server": "^3.12.0",
+    "hash.js": "^1.1.7",
+    "lib-cmdparse": "^0.1.0",
+    "rfc4648": "^1.5.4",
+    "sha.js": "^2.4.11",
+    "sprintf-js": "^1.1.1"
+  }
+}
diff --git a/src/cli/npmMeta.ts b/src/cli/npmMeta.ts
new file mode 100644
index 00000000000..44785ea7f71
--- /dev/null
+++ b/src/cli/npmMeta.ts
@@ -0,0 +1,90 @@
+/**
+ * The published CLI package's hand-written metadata.
+ *
+ * Everything here is a decision. Everything derivable — the dependency list
+ * above all — is generated into `src/cli/generated/npmPackage.json` by
+ * `scripts/buildCliManifest.ts`, because the dependencies a published CLI
+ * needs are not the app's: `rollup.config.cli.mjs` externalises every key of
+ * the app's `dependencies`, so what the bundles actually require can only be
+ * read off the module graph. Hand-maintaining that list is how a published
+ * package ends up missing a package it requires at runtime.
+ *
+ * The version is not here either: the CLI ships in lockstep with the app, so
+ * `buildCliManifest.ts` takes it from the app's own `package.json` and there
+ * is no second number to forget to bump. The cost of lockstep is that a
+ * version can be published once — npm refuses to replace an existing one — so
+ * a CLI-only fix rides on the next app version bump rather than going out on
+ * its own.
+ *
+ * This module is imported by the generator and by nothing the bundles reach,
+ * so it adds nothing to either bundle.
+ */
+
+/** One native addon shipped as its own per-platform package. */
+export interface NativePackage {
+  /** The npm package name, e.g. `@edgeapp/cli-darwin-arm64`. */
+  name: string
+  /** `process.platform` values it is built for. */
+  os: string[]
+  /** `process.arch` values it is built for. */
+  cpu: string[]
+}
+
+export interface CliPackageMeta {
+  name: string
+  description: string
+  /** The command name `npm install -g` and `npx` expose. */
+  binName: string
+  keywords: string[]
+  license: string
+  author: string
+  homepage: string
+  repositoryUrl: string
+  /** Where the sources live inside the repository, for npm's provenance UI. */
+  repositoryDirectory: string
+  /** The floor the rollup build targets; see `babelOpts` in the config. */
+  engines: { node: string }
+  /**
+   * Per-platform native packages, published separately and declared as
+   * `optionalDependencies`.
+   *
+   * Each is published at the app's version too, so a platform package and
+   * the CLI that looks for it can never disagree.
+   *
+   * Empty until the fan-out exists. An `optionalDependency` that fails to
+   * install is not an install failure, which is what makes the pattern work:
+   * npm skips the ones whose `os`/`cpu` do not match and installs only the
+   * one that does. Until then the addon rides inside the main package for
+   * whichever platform the build server ran on, and
+   * `loadNodeApiSignerNative` answers `null` elsewhere — the CLI still runs,
+   * unsigned.
+   */
+  nativePackages: NativePackage[]
+}
+
+export const CLI_PACKAGE_META: CliPackageMeta = {
+  name: '@edgeapp/cli',
+  description:
+    'Command-line access to an Edge account: wallets, balances, transactions and swaps.',
+  binName: 'edge-cli',
+  keywords: ['edge', 'cryptocurrency', 'wallet', 'cli', 'bitcoin', 'ethereum'],
+  license: 'SEE LICENSE IN LICENSE',
+  author: 'Edge, Inc.',
+  homepage: 'https://edge.app',
+  // The https form, not the app's `git@` one: npm rewrites an scp-style URL
+  // on publish and warns about it, and a public package should be clonable by
+  // anyone reading its registry page.
+  repositoryUrl: 'git+https://github.com/EdgeApp/edge-react-gui.git',
+  repositoryDirectory: 'src/cli',
+  engines: { node: '>=18' },
+  nativePackages: []
+}
+
+/** Files the published package contains, relative to its root. */
+export const CLI_PACKAGE_FILES = [
+  'edgeCli.js',
+  'edgeEngine.js',
+  'edge_api_signer.node',
+  'README.md',
+  'LICENSE'
+]

From ef9130de65f3c7cfe0a23351c28c7b18c4e35a8a Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 21:24:44 -0700
Subject: [PATCH 13/24] Validate caller-supplied amounts and action types
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-errors.2, with 3.engine-routes.1 and 3.engine-infra.2.

Five request-position amount fields were declared `asString` and handed to
biggystring, which throws a plain `Error` that `toErrorBody` has no arm
for — so `spend --native-amount=abc` and
`get-transactions --spam-threshold=abc` answered 500 on routes declaring
400. A fractional value was worse than an error: the UTXO plugin sums fees
with biggystring but builds the output with `parseInt`, so "1.5" funded
the fee math at 1.5 and paid out 1, under a field documented as the
chain's smallest unit. `asIntegerString` already existed for exactly this
and is now exported and used by `asSpendTarget`, the spend shorthand's
`nativeAmount` and `amount`, `swap-quote`, `encode-uri` and
`spamThreshold`, where zero stays legal. Response-position amounts keep
`asString`: a transaction's `nativeAmount` is negative for a send, and
core's own values are already valid.

`asEdgeTxAction` dispatched through a plain object literal, so
`actionType: "toString"` resolved `Object.prototype.toString` — not null,
so the unknown-actionType guard was skipped and a string was returned as an
`EdgeTxAction`; `"constructor"` handed back the unvalidated body. Both
reached `wallet.saveTxAction`, where core dispatches
`CURRENCY_WALLET_FILE_CHANGED` before its own uncleaner rejects. Guarded
with the shared `hasOwn`, as `util/exchangeDenom.ts` already does.

Seven offline checks cover the new rejections, including both prototype
names.
---
 scripts/testCliFake.ts                | 49 +++++++++++++++++++++++++++
 src/cli/engine/routes/swap.ts         |  3 +-
 src/cli/engine/routes/transactions.ts |  3 +-
 src/cli/engine/routes/uri.ts          |  6 ++--
 src/cli/engine/schemas.ts             | 27 ++++++++++++---
 5 files changed, 79 insertions(+), 9 deletions(-)

diff --git a/scripts/testCliFake.ts b/scripts/testCliFake.ts
index e5bca144b9e..e380f61b62a 100644
--- a/scripts/testCliFake.ts
+++ b/scripts/testCliFake.ts
@@ -616,6 +616,41 @@ function main(): void {
       w,
       '--spend-info={"tokenId":null,"spendTargets":[{"publicAdress":"bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7","nativeAmount":"1"}]}'
     )
+    // Declared `asString`, these reached biggystring, which throws a plain
+    // `Error` that `toErrorBody` has no arm for — so a mistyped amount
+    // answered 500 on routes declaring 400. A fractional one was worse: the
+    // UTXO plugin sums fees with biggystring but builds the output with
+    // `parseInt`, so "1.5" funded the fee math at 1.5 and paid out 1.
+    for (const [label, amount] of [
+      ['non-numeric', 'abc'],
+      ['fractional', '1.5'],
+      ['negative', '-1000']
+    ]) {
+      refuses(
+        `make-spend with a ${label} native amount`,
+        'BAD_REQUEST',
+        'make-spend',
+        w,
+        '--to=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7',
+        `--native-amount=${amount}`
+      )
+    }
+    refuses(
+      'get-transactions with a non-numeric spam threshold',
+      'BAD_REQUEST',
+      'get-transactions',
+      w,
+      '--spam-threshold=abc'
+    )
+    refuses(
+      'encode-uri with a fractional native amount',
+      'BAD_REQUEST',
+      'encode-uri',
+      w,
+      '--public-address=bc1q0qsagl9n0lrsutam6zncd6vf07rq3mekn3phl7',
+      '--native-amount=0.5'
+    )
+
     refuses(
       'spend with a target missing nativeAmount',
       'BAD_REQUEST',
@@ -677,6 +712,20 @@ function main(): void {
       '--txid=deadbeef',
       '--saved-action={"actionType":"swap"}'
     )
+    // `actionType` is dispatched through a plain object literal, so these two
+    // names resolved `Object.prototype.toString` and `Object` rather than
+    // missing: the "unknown actionType" guard was skipped and a string, or
+    // the unvalidated body, was returned as an `EdgeTxAction`.
+    for (const actionType of ['toString', 'constructor']) {
+      refuses(
+        `save-tx-action with actionType "${actionType}"`,
+        'BAD_REQUEST',
+        'save-tx-action',
+        w,
+        '--txid=deadbeef',
+        `--saved-action={"actionType":"${actionType}"}`
+      )
+    }
     refuses(
       'save-tx-metadata with a non-object metadata',
       'BAD_REQUEST',
diff --git a/src/cli/engine/routes/swap.ts b/src/cli/engine/routes/swap.ts
index bc3cd8fdee3..5a5eb458372 100644
--- a/src/cli/engine/routes/swap.ts
+++ b/src/cli/engine/routes/swap.ts
@@ -20,6 +20,7 @@ import { findWallet } from '../resolve'
 import { route } from '../route'
 import {
   asCoreValue,
+  asIntegerString,
   asOkObject,
   asRequestTokenId,
   asSwapQuote
@@ -90,7 +91,7 @@ export const fetchSwapQuotes = route({
   body: asObject({
     fromWalletId: doc(asString, 'Source wallet. Accepts a unique prefix.'),
     toWalletId: doc(asString, 'Destination wallet.'),
-    nativeAmount: doc(asString, 'How much, in native units.'),
+    nativeAmount: doc(asIntegerString, 'How much, in native units.'),
     // `asRequestTokenId`, like the ten other request-position tokenIds: the
     // CLI sends every tokenId as text, so `--from-token-id=null` — the
     // spelling the guide documents — arrived as the four characters "null"
diff --git a/src/cli/engine/routes/transactions.ts b/src/cli/engine/routes/transactions.ts
index ccddfaba829..94cef61269f 100644
--- a/src/cli/engine/routes/transactions.ts
+++ b/src/cli/engine/routes/transactions.ts
@@ -38,6 +38,7 @@ import {
   asEdgeAssetAction,
   asEdgeMetadataChange,
   asEdgeTxAction,
+  asIntegerString,
   asQueryBoolean,
   asQueryDate,
   asQueryNonNegativeInteger,
@@ -158,7 +159,7 @@ export const getTransactions = route({
     ),
     spamThreshold: asOptional(
       doc(
-        asString,
+        asIntegerString,
         'Native-amount floor. Omitted, the account spam-filter setting applies; a value always overrides it, and `0` shows everything. An empty value reads as omitted, like every other query parameter.'
       )
     ),
diff --git a/src/cli/engine/routes/uri.ts b/src/cli/engine/routes/uri.ts
index aba123d354e..70b14079b9a 100644
--- a/src/cli/engine/routes/uri.ts
+++ b/src/cli/engine/routes/uri.ts
@@ -4,7 +4,7 @@ import type { EdgeEncodeUri } from 'edge-core-js'
 import { doc } from '../doc'
 import { findWallet } from '../resolve'
 import { route } from '../route'
-import { asCoreValue, asWalletId } from '../schemas'
+import { asCoreValue, asIntegerString, asWalletId } from '../schemas'
 import { getAccount } from './helpers'
 
 const CURRENCY_CODE_DOC = 'Disambiguates on chains that carry several assets.'
@@ -55,7 +55,9 @@ export const encodeUri = route({
   body: asObject({
     walletId: asWalletId,
     publicAddress: doc(asString, 'Where the payment should go.'),
-    nativeAmount: asOptional(doc(asString, 'Amount, in the native unit.')),
+    nativeAmount: asOptional(
+      doc(asIntegerString, 'Amount, in the native unit.')
+    ),
     label: asOptional(
       doc(asString, 'BIP21 `label`; becomes `metadata.name` when parsed back.')
     ),
diff --git a/src/cli/engine/schemas.ts b/src/cli/engine/schemas.ts
index acbcbf172ec..aeb42ddc904 100644
--- a/src/cli/engine/schemas.ts
+++ b/src/cli/engine/schemas.ts
@@ -35,6 +35,7 @@ import type {
 } from 'edge-core-js'
 
 import { asBiggystring } from '../../util/cleaners'
+import { hasOwn } from '../../util/predicates'
 import { doc } from './doc'
 import {
   SPEND_AMOUNT_ALIAS_DOC,
@@ -606,6 +607,11 @@ export const asEdgeMetadata: Cleaner<EdgeMetadata> = asNotArray(
 /**
  * Native units as core stores them: digits only.
  *
+ * The cleaner for every `nativeAmount`, `amount` or threshold a *caller*
+ * sends. Response-position amounts stay `asString`: a transaction's
+ * `nativeAmount` is negative for a send, and core's own values are already
+ * valid, so tightening those would reject legitimate output.
+ *
  * `asString` here was the one field of the five `asEdgeTxAction*` cleaners
  * looser than core's own, and it re-opened the hole those cleaners exist to
  * close. `save-tx-action` with `"nativeAmount":"1.5"` passed this route,
@@ -614,7 +620,7 @@ export const asEdgeMetadata: Cleaner<EdgeMetadata> = asNotArray(
  * engine served a `savedAction` the disk did not have for the life of the
  * daemon, and the caller got a 500 on a route declaring only 400 and 404.
  */
-const asIntegerString: Cleaner<string> = raw => {
+export const asIntegerString: Cleaner<string> = raw => {
   const value = asString(raw)
   if (!/^\d+$/.test(value)) {
     throw new TypeError(`"${value}" is not an integer string`)
@@ -751,7 +757,18 @@ const txActionCleaners: Record<string, Cleaner<EdgeTxAction>> = {
  */
 export const asEdgeTxAction: Cleaner<EdgeTxAction> = asNotArray(raw => {
   const { actionType } = asObject({ actionType: asString }).withRest(raw)
-  const cleaner = txActionCleaners[actionType]
+  // `hasOwn`, not a truthiness test on the lookup: `txActionCleaners` is a
+  // plain object literal, so `actionType: "toString"` resolved
+  // `Object.prototype.toString` — not null, so the guard below was skipped
+  // and this returned a string as an `EdgeTxAction`. `"constructor"` was
+  // worse: `Object(raw)` handed back the unvalidated body. Either reached
+  // `wallet.saveTxAction`, where core dispatches
+  // `CURRENCY_WALLET_FILE_CHANGED` before its own uncleaner rejects, so the
+  // caller got a 500 from a route promising only 400 and 404. Same guard
+  // `util/exchangeDenom.ts` uses for the same reason.
+  const cleaner = hasOwn(txActionCleaners, actionType)
+    ? txActionCleaners[actionType]
+    : null
   if (cleaner == null) {
     throw new TypeError(
       `Unknown actionType "${actionType}": expected one of ${Object.keys(
@@ -796,7 +813,7 @@ export const asCreateCurrencyWallet = asObject({
 /** A spend target: where the money goes and how much. */
 export const asSpendTarget = asObject({
   publicAddress: asOptional(asString),
-  nativeAmount: asOptional(asString),
+  nativeAmount: asOptional(asIntegerString),
   uniqueIdentifier: asOptional(asString),
   memo: asOptional(asString),
   otherParams: asOptional(asObject(asUnknown))
@@ -880,8 +897,8 @@ export const asSpendShorthandBody = asObject({
     )
   ),
   to: asOptional(doc(asString, SPEND_TO_DOC)),
-  nativeAmount: asOptional(doc(asString, SPEND_AMOUNT_DOC)),
-  amount: asOptional(doc(asString, SPEND_AMOUNT_ALIAS_DOC)),
+  nativeAmount: asOptional(doc(asIntegerString, SPEND_AMOUNT_DOC)),
+  amount: asOptional(doc(asIntegerString, SPEND_AMOUNT_ALIAS_DOC)),
   tokenId: asOptional(doc(asRequestTokenId, TOKEN_ID_DOC), null),
   metadata: asOptional(doc(asEdgeMetadata, SPEND_METADATA_DOC))
 })

From 5c1c1a7fc6234535721968f6b7417b1b43c5683b Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 21:34:27 -0700
Subject: [PATCH 14/24] Honour save-export-prefs and publish the real page size
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-state.6, and 3.review-state.7 with 3.harness-review.8.

`--save-export-prefs` was honoured on one branch of three: the
`mergeExportTxInfo` call sat inside `if (formats.includes('bitwave'))` and
again inside the explicit-account-id test, so
`--export-format=csv,qbo --save-export-prefs` answered `ok` and wrote
nothing. The caller asked for their format choice to be remembered and the
GUI export scene's switches were untouched. The write now runs once for
every format combination, still only when the flag is given — writing
unasked turned a one-off `--bitwave-account-id` into the user's saved id.
Passing an absent id is safe because `mergeExportTxInfo` reads each field
as `patch.x ?? prev?.x`, which is what keeps a saved bitwave id through a
csv-only save.

`limit`'s published description said "Defaults to 100" while
`DEFAULT_TX_LIMIT` is 99 — deliberately, so a page prices in one rates
request. The wrong number ships in `openapi.json`, the HTML reference and
`edge-cli help`, so a caller paging on the documented default walks
`offset` 0, 100, 200 and skips one transaction per page, which `total`
cannot reveal because it is the match count. The description cannot
interpolate the constant: `extractRoutes` reads it through the checker as a
string literal, and a template literal drops the description from the
reference altogether. A test holds the two in step instead.
---
 docs/api/dist/index.html              |  2 +-
 docs/api/dist/openapi.json            |  2 +-
 scripts/testCliFake.ts                | 22 ++++++++++++
 src/__tests__/cli/txLimitDoc.test.ts  | 31 +++++++++++++++++
 src/cli/engine/routes/transactions.ts | 50 +++++++++++++++++----------
 src/cli/generated/helpDocs.json       |  2 +-
 6 files changed, 87 insertions(+), 22 deletions(-)
 create mode 100644 src/__tests__/cli/txLimitDoc.test.ts

diff --git a/docs/api/dist/index.html b/docs/api/dist/index.html
index 135ddf76e8c..65a7c2617e3 100644
--- a/docs/api/dist/index.html
+++ b/docs/api/dist/index.html
@@ -5813,7 +5813,7 @@ <h5>Path</h5><table class="fields"><tbody><tr><td class="k"><code>sessionId</cod
 <tr>
   <td class="k"><code>limit</code></td>
   <td class="ty"><span class="t">number</span> <span class="flag opt">optional</span></td>
-  <td class="doc">How many to return. Defaults to 100; pass <code>0</code> for every transaction from <code>offset</code> on. <code>total</code> in the response says how many matched, so a caller can page with <code>offset</code>.</td>
+  <td class="doc">How many to return. Defaults to 99; pass <code>0</code> for every transaction from <code>offset</code> on. <code>total</code> in the response says how many matched, so a caller can page with <code>offset</code>.</td>
 </tr>
 <tr>
   <td class="k"><code>offset</code></td>
diff --git a/docs/api/dist/openapi.json b/docs/api/dist/openapi.json
index 8ceaceeb8e9..1899bec7379 100644
--- a/docs/api/dist/openapi.json
+++ b/docs/api/dist/openapi.json
@@ -6194,7 +6194,7 @@
             "name": "limit",
             "in": "query",
             "required": false,
-            "description": "How many to return. Defaults to 100; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.",
+            "description": "How many to return. Defaults to 99; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.",
             "schema": {
               "type": "number"
             }
diff --git a/scripts/testCliFake.ts b/scripts/testCliFake.ts
index e380f61b62a..8be938de94c 100644
--- a/scripts/testCliFake.ts
+++ b/scripts/testCliFake.ts
@@ -538,6 +538,28 @@ function main(): void {
       '--export-format=bitwave',
       `--out=${path.join(exportDir, 'bw2.csv')}`
     )
+    // `--save-export-prefs` used to be honoured only inside the bitwave
+    // branches, so this combination answered `ok` and wrote nothing. The
+    // write now runs for every format. The bitwave call after it checks that
+    // the saved id survived a write that did not mention one — it has no
+    // `--bitwave-account` of its own, so it can only succeed from the
+    // record. `mergeExportTxInfo` is what preserves it, by reading each
+    // field as `patch.x ?? prev?.x`.
+    ok(
+      'csv and qbo preferences are saved',
+      'get-transactions',
+      w,
+      '--export-format=csv,qbo',
+      '--save-export-prefs',
+      `--out=${path.join(exportDir, 'prefs')}`
+    )
+    ok(
+      'saving csv preferences keeps the bitwave account id',
+      'get-transactions',
+      w,
+      '--export-format=bitwave',
+      `--out=${path.join(exportDir, 'bw3.csv')}`
+    )
     fs.rmSync(exportDir, { recursive: true, force: true })
     // A tokenId is free-form caller input over REST, where in the GUI it
     // always came from a real token. Unvalidated, each of these destructured
diff --git a/src/__tests__/cli/txLimitDoc.test.ts b/src/__tests__/cli/txLimitDoc.test.ts
new file mode 100644
index 00000000000..58f5690ed81
--- /dev/null
+++ b/src/__tests__/cli/txLimitDoc.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { DEFAULT_TX_LIMIT } from '../../cli/engine/routes/transactions'
+import helpDocs from '../../cli/generated/helpDocs.json'
+import { asHelpDocs } from '../../cli/generatedSchemas'
+
+/**
+ * The published default page size must be the one the route actually uses.
+ *
+ * They disagreed: the description said 100 while `DEFAULT_TX_LIMIT` is 99,
+ * deliberately, so the rates batcher stops before crossing its 100-asset
+ * limit. The wrong number reaches `openapi.json`, the HTML reference and
+ * `edge-cli help get-transactions`, so a caller paging on the documented
+ * default walks `offset` 0, 100, 200 and skips one transaction per page —
+ * and `total` does not reveal it, because `total` is the match count, not
+ * the page size. An accounting export built that way is short and looks
+ * complete.
+ *
+ * The description cannot interpolate the constant: `extractRoutes` reads it
+ * through the TypeScript checker as a string literal, and a template literal
+ * drops it from the reference entirely. So the two are kept in step here.
+ */
+describe('get-transactions limit', () => {
+  it('publishes the default the route actually applies', () => {
+    const limit =
+      asHelpDocs(helpDocs).commands['get-transactions'].params?.limit
+    expect(limit).not.toBeUndefined()
+    const prose = limit?.doc ?? ''
+    expect(prose).toContain(`Defaults to ${DEFAULT_TX_LIMIT}`)
+  })
+})
diff --git a/src/cli/engine/routes/transactions.ts b/src/cli/engine/routes/transactions.ts
index 94cef61269f..96b7fd447e5 100644
--- a/src/cli/engine/routes/transactions.ts
+++ b/src/cli/engine/routes/transactions.ts
@@ -87,7 +87,7 @@ function overlayDisplayMetadata(
  * request and 100 cost two. The point of the default is that a page prices
  * in a single request, which 100 did not deliver.
  */
-const DEFAULT_TX_LIMIT = 99
+export const DEFAULT_TX_LIMIT = 99
 
 /**
  * List or export a wallet's transactions.
@@ -137,7 +137,12 @@ export const getTransactions = route({
     limit: asOptional(
       doc(
         asQueryNonNegativeInteger,
-        'How many to return. Defaults to 100; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.'
+        // The number has to match `DEFAULT_TX_LIMIT`, and a template literal
+        // cannot say so: `extractRoutes` reads this through the checker as a
+        // string *literal*, and interpolating dropped the description from
+        // the reference altogether. `txLimitDoc.test.ts` asserts the two
+        // agree instead.
+        'How many to return. Defaults to 99; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.'
       ),
       DEFAULT_TX_LIMIT
     ),
@@ -295,23 +300,6 @@ export const getTransactions = route({
     if (formats.includes('bitwave')) {
       if (bitwaveAccountIdQuery != null && bitwaveAccountIdQuery !== '') {
         bitwaveAccountId = bitwaveAccountIdQuery
-        // Persisting is opt-in. This writes `exportTxInfo.json` on the
-        // wallet's *synced* disklet, which is the record the GUI's export
-        // scene reads back to pre-set its three switches — so doing it
-        // unasked turned a one-off `--bitwave-account-id` into the user's
-        // saved account id and flipped "Export to Bitwave" on for them.
-        if (ctx.query.valid.saveExportPrefs) {
-          await mergeExportTxInfo(wallet, tokenId, {
-            bitwaveAccountId,
-            // The same field set the GUI writes, so one record keeps one
-            // meaning: a partial patch left isExportCsv/isExportQbo at
-            // `false` on a first write and the record no longer described
-            // the last export either tool ran.
-            isExportBitwave: formats.includes('bitwave'),
-            isExportCsv: formats.includes('csv'),
-            isExportQbo: formats.includes('qbo')
-          })
-        }
       } else {
         let saved: string | undefined
         try {
@@ -331,6 +319,30 @@ export const getTransactions = route({
       }
     }
 
+    // Outside the bitwave branches, because the flag is documented as saving
+    // "`bitwaveAccountId` **and** the chosen formats" and it used to be
+    // honoured only when the caller asked for bitwave *and* passed an
+    // explicit account id. So `--export-format=csv,qbo --save-export-prefs`
+    // answered `ok` and wrote nothing, leaving the GUI export scene's
+    // switches untouched. Persisting is still opt-in: writing unasked turned
+    // a one-off `--bitwave-account-id` into the user's saved account id and
+    // flipped "Export to Bitwave" on for them.
+    if (ctx.query.valid.saveExportPrefs) {
+      await mergeExportTxInfo(wallet, tokenId, {
+        // Safe to pass when absent: `mergeExportTxInfo` reads every field as
+        // `patch.x ?? prev?.x`, so an undefined id keeps whatever was saved
+        // rather than clearing it for a caller who never mentioned bitwave.
+        bitwaveAccountId,
+        // The same field set the GUI writes, so one record keeps one
+        // meaning: a partial patch left isExportCsv/isExportQbo at `false`
+        // on a first write and the record no longer described the last
+        // export either tool ran.
+        isExportBitwave: formats.includes('bitwave'),
+        isExportCsv: formats.includes('csv'),
+        isExportQbo: formats.includes('qbo')
+      })
+    }
+
     const files: Array<{ format: TxExportFormat; contents: string }> = []
     for (const format of formats) {
       if (format === 'csv') {
diff --git a/src/cli/generated/helpDocs.json b/src/cli/generated/helpDocs.json
index d4cb3922434..05b59bc7f0e 100644
--- a/src/cli/generated/helpDocs.json
+++ b/src/cli/generated/helpDocs.json
@@ -1847,7 +1847,7 @@
         },
         "limit": {
           "pass": "[--limit=<limit>]",
-          "doc": "How many to return. Defaults to 100; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.",
+          "doc": "How many to return. Defaults to 99; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.",
           "optional": true
         },
         "offset": {

From feec94c2b4efe32ea5414951147f571976624a8d Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 21:43:24 -0700
Subject: [PATCH 15/24] Reach every wallet a key export names, and guard
 save-tx
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.engine-routes.3, 3.engine-routes.2, 3.harness-review.4 and
3.review-state.5 — four routes whose declared reach and real reach differed.

The key-export calls resolved through `findWallet`, which searches
`account.currencyWallets`: core builds that only from `activeWalletIds` and
only for wallets whose api exists. So `all-keys` listed an archived wallet
and `get-raw-private-key` answered `WALLET_NOT_FOUND` for the exact id it
had just printed — on the disaster-recovery path a CLI key export is for.
Core's `getRawPrivateKey`, `getDisplayPrivateKey`, `getRawPublicKey` and
`listSplittableWalletTypes` all work off `allKeys`, so `findWalletId`
resolves there, with the same prefix contract and the same errors.

`change-wallet-states` validated nothing. Core treats an id it has never
seen as new and writes a state file for it without complaint, so a typo or
a prefix answered 204 while nothing changed, and left a bogus
`Keys/<hash>.json` in the account repo to sync to every device. It was also
the one wallet route that ignored the prefix contract `walletId` is
documented with. Every key now resolves over `allKeys` first.

`save-tx` was the only handle-advancing route setting neither `consuming`
nor `hold`, so `OBJECT_IN_USE`, the sweeper's skip and a bulk release's
bounded wait were all blind to it. A slow save overlapping a `broadcast-tx`
for the same handle removed the record under the in-flight broadcast, which
then answered `OBJECT_NOT_FOUND` after the funds had left. It runs under
`consume` now, which also does the delete the handler did by hand.

`object-get` and `object-delete` published a reach they lost: only
`transaction` and `swap` are created with a `sessionId`, so `pendingLogin`
and `lobby` can only answer `OBJECT_SESSION_MISMATCH` there. Both
descriptions say so, and the two dead arms of `projectHandleValue` are
explicit about being unreachable and point at `pendingSummary`, which is
where a pending login is really projected — the reasoning worth keeping,
since serialising one walks into `otpKey` and `recoveryKey` getters.
---
 docs/api/dist/index.html         |  6 ++---
 docs/api/dist/openapi.json       |  6 ++---
 scripts/testCliFake.ts           | 11 ++++++++
 src/cli/engine/resolve.ts        | 43 +++++++++++++++++++++++++++++
 src/cli/engine/routes/keys.ts    | 23 ++++++++++++----
 src/cli/engine/routes/objects.ts | 46 ++++++++++++++++----------------
 src/cli/engine/routes/spend.ts   | 18 ++++++++++---
 src/cli/generated/helpDocs.json  |  6 ++---
 8 files changed, 119 insertions(+), 40 deletions(-)

diff --git a/docs/api/dist/index.html b/docs/api/dist/index.html
index 65a7c2617e3..32ffc2ad34c 100644
--- a/docs/api/dist/index.html
+++ b/docs/api/dist/index.html
@@ -7626,7 +7626,7 @@ <h3><a href="#getObject">Inspect an object handle.</a></h3>
       <div class="ids"><code class="cmdname">object-get</code><span class="src" title="Declared in">src/cli/engine/routes/objects.ts</span></div>
     </header>
     <p class="core none"><span class="lbl">core</span><em>Engine handle store; core identifies these values by object reference.</em></p>
-    <div class="desc"><p>Works for every kind: transactions, pending logins, swap quotes and lobbies.</p>
+    <div class="desc"><p>For the session-scoped kinds: a staged transaction or a swap quote.</p>
 </div>
     <div class="panes"><div class="pane cli">
     <h4>Command line</h4>
@@ -7647,7 +7647,7 @@ <h5>Example</h5>
   </div></div>
     <div class="pane resp">
     <h4>Response <span class="st ok">200</span></h4>
-    <div class="note"><p>The handle fields, plus a <code>value</code> holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports <code>value: null</code>.</p>
+    <div class="note"><p>The handle fields, plus a <code>value</code> holding a JSON-safe view of the object. A staged transaction is returned whole; a swap quote is summarised, because the value behind it is a live core object whose properties are getters.</p>
 </div><div class="shape">
     <div class="shape-h">Response body</div>
     <pre class="ts"><code>{
@@ -7706,7 +7706,7 @@ <h3><a href="#deleteObject">Release an object handle.</a></h3>
       <div class="ids"><code class="cmdname">object-delete</code><span class="src" title="Declared in">src/cli/engine/routes/objects.ts</span></div>
     </header>
     <p class="core none"><span class="lbl">core</span><em>Engine handle store.</em></p>
-    <div class="desc"><p>Runs the handle&#39;s cleanup — closing a swap quote, cancelling a pending login — instead of waiting out the TTL.</p>
+    <div class="desc"><p>Runs the handle&#39;s cleanup — closing a swap quote, discarding a staged transaction — instead of waiting out the TTL.</p>
 </div>
     <div class="panes"><div class="pane cli">
     <h4>Command line</h4>
diff --git a/docs/api/dist/openapi.json b/docs/api/dist/openapi.json
index 1899bec7379..22dd1f10989 100644
--- a/docs/api/dist/openapi.json
+++ b/docs/api/dist/openapi.json
@@ -6581,7 +6581,7 @@
       "get": {
         "operationId": "getObject",
         "summary": "Inspect an object handle.",
-        "description": "**Core call:** _none — Engine handle store; core identifies these values by object reference._\n\n**Command line**\n\n```\nobject-get <objectId>\n```\n\nWorks for every kind: transactions, pending logins, swap quotes and lobbies.",
+        "description": "**Core call:** _none — Engine handle store; core identifies these values by object reference._\n\n**Command line**\n\n```\nobject-get <objectId>\n```\n\nFor the session-scoped kinds: a staged transaction or a swap quote.",
         "tags": [
           "Object handles"
         ],
@@ -6618,7 +6618,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports `value: null`.",
+            "description": "The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; a swap quote is summarised, because the value behind it is a live core object whose properties are getters.",
             "content": {
               "application/json": {
                 "schema": {
@@ -6676,7 +6676,7 @@
       "post": {
         "operationId": "deleteObject",
         "summary": "Release an object handle.",
-        "description": "**Core call:** _none — Engine handle store._\n\n**Command line**\n\n```\nobject-delete <objectId>\n```\n\nRuns the handle's cleanup — closing a swap quote, cancelling a pending login — instead of waiting out the TTL.",
+        "description": "**Core call:** _none — Engine handle store._\n\n**Command line**\n\n```\nobject-delete <objectId>\n```\n\nRuns the handle's cleanup — closing a swap quote, discarding a staged transaction — instead of waiting out the TTL.",
         "tags": [
           "Object handles"
         ],
diff --git a/scripts/testCliFake.ts b/scripts/testCliFake.ts
index 8be938de94c..3932b0a55ff 100644
--- a/scripts/testCliFake.ts
+++ b/scripts/testCliFake.ts
@@ -748,6 +748,17 @@ function main(): void {
         `--saved-action={"actionType":"${actionType}"}`
       )
     }
+    // Core treats an unknown wallet id as new and writes a state file for it
+    // without error, so these answered 204 while changing nothing and left a
+    // bogus record to sync to every device.
+    refuses(
+      'change-wallet-states with an unknown wallet id',
+      'WALLET_NOT_FOUND',
+      'change-wallet-states',
+      '--wallet-id=nosuchwalletid',
+      '--archived=true'
+    )
+
     refuses(
       'save-tx-metadata with a non-object metadata',
       'BAD_REQUEST',
diff --git a/src/cli/engine/resolve.ts b/src/cli/engine/resolve.ts
index 462d9c32a94..dcedfa321ef 100644
--- a/src/cli/engine/resolve.ts
+++ b/src/cli/engine/resolve.ts
@@ -47,6 +47,49 @@ export function findWallet(
   return wallets[matches[0]]
 }
 
+/**
+ * Resolve a wallet id over `allKeys`, not the loaded wallets.
+ *
+ * `findWallet` searches `account.currencyWallets`, which core builds only
+ * from `activeWalletIds` and only for wallets whose api exists — so an
+ * archived wallet, or one whose currency plugin this engine did not load, is
+ * absent from it. That is right for anything that needs a live
+ * `EdgeCurrencyWallet`, and wrong for the calls that only need an id:
+ * `getRawPrivateKey`, `getDisplayPrivateKey`, `getRawPublicKey`,
+ * `listSplittableWalletTypes` and `changeWalletStates` all work off
+ * `allKeys`. Resolving those through the loaded set made key export answer
+ * `WALLET_NOT_FOUND` for a wallet `all-keys` had just listed — on the
+ * disaster-recovery path a CLI key export exists for.
+ *
+ * Same prefix contract and same errors as `findWallet`, so a caller cannot
+ * tell the two apart except by which wallets they can reach.
+ */
+export function findWalletId(account: EdgeAccount, prefix: string): string {
+  if (prefix === '') {
+    throw engineError('BAD_REQUEST', 'walletId must not be empty', 400)
+  }
+  const ids = account.allKeys.map(info => info.id)
+  if (ids.includes(prefix)) return prefix
+
+  const matches = ids.filter(id => id.startsWith(prefix))
+  if (matches.length === 0) {
+    throw engineError(
+      'WALLET_NOT_FOUND',
+      `No wallet found matching: ${prefix}`,
+      404
+    )
+  }
+  if (matches.length > 1) {
+    throw engineError(
+      'AMBIGUOUS_WALLET_ID',
+      `Ambiguous wallet ID "${prefix}"`,
+      409,
+      { candidates: matches }
+    )
+  }
+  return matches[0]
+}
+
 /**
  * Refuse a tokenId the wallet's plugin does not know.
  *
diff --git a/src/cli/engine/routes/keys.ts b/src/cli/engine/routes/keys.ts
index c6049cfe956..152065e51d8 100644
--- a/src/cli/engine/routes/keys.ts
+++ b/src/cli/engine/routes/keys.ts
@@ -10,7 +10,7 @@ import type { EdgeWalletStates } from 'edge-core-js'
 
 import { doc } from '../doc'
 import { engineError } from '../errors'
-import { findWallet } from '../resolve'
+import { findWalletId } from '../resolve'
 import { route } from '../route'
 import type { RouteContext } from '../router'
 import { asCoreValue, asWalletId, asWalletKeys } from '../schemas'
@@ -28,7 +28,7 @@ function walletIdFor(
     query: { valid: { walletId: string } }
   }
 ): string {
-  return findWallet(getAccount(ctx), ctx.query.valid.walletId).id
+  return findWalletId(getAccount(ctx), ctx.query.valid.walletId)
 }
 
 const asWalletIdQuery = asObject({ walletId: asWalletId }).withRest
@@ -265,9 +265,22 @@ export const changeWalletStates = route({
   errors: ['BAD_REQUEST'],
 
   async handler(ctx) {
-    await getAccount(ctx).changeWalletStates(
-      ctx.body.walletStates as unknown as EdgeWalletStates
-    )
+    const account = getAccount(ctx)
+    // Every key resolved first. Core treats an id it has never seen as new
+    // and writes a state file for it without complaint, so a typo or a
+    // prefix answered 204 while nothing changed — and left a bogus
+    // `Keys/<hash>.json` record in the account repo to sync to every device.
+    // This was also the one wallet route that did not honour the prefix
+    // contract `walletId` is documented with everywhere else, so an id that
+    // worked with `rename-wallet` silently did nothing here. Resolved over
+    // `allKeys`, because archiving and deleting are exactly the states an
+    // already-archived wallet has.
+    const resolved: EdgeWalletStates = {}
+    for (const [prefix, states] of Object.entries(ctx.body.walletStates)) {
+      resolved[findWalletId(account, prefix)] =
+        states as unknown as EdgeWalletStates[string]
+    }
+    await account.changeWalletStates(resolved)
     return undefined
   }
 })
diff --git a/src/cli/engine/routes/objects.ts b/src/cli/engine/routes/objects.ts
index 0d5ad2b26cd..c83d37fff3c 100644
--- a/src/cli/engine/routes/objects.ts
+++ b/src/cli/engine/routes/objects.ts
@@ -3,8 +3,16 @@
  *
  * Core values with methods on them — a staged transaction, a swap quote, a
  * pending login, an edge-login lobby — cannot cross JSON, so the engine keeps
- * them and hands back an id. These two calls read and release any of them,
- * whatever kind it is.
+ * them and hands back an id.
+ *
+ * These two calls reach the session-scoped kinds only. A handle is owned by a
+ * session when it is created with one, and of the four kinds only
+ * `transaction` (`spend.ts`) and `swap` (`swap.ts`) are; `pendingLogin`
+ * (`login.ts`) and `lobby` (`admin.ts`) are deliberately not, because they
+ * exist before there is a session to own them. `requireOwnedHandle` refuses
+ * an owner-less handle, so those two can only ever answer
+ * `OBJECT_SESSION_MISMATCH` here and are read and released through their own
+ * routes instead.
  */
 import type { EdgeSwapQuote, EdgeTransaction } from 'edge-core-js'
 
@@ -31,21 +39,6 @@ function projectHandleValue(kind: ObjectHandleKind, value: unknown): unknown {
     case 'transaction':
       return value as EdgeTransaction
 
-    case 'pendingLogin': {
-      const record = value as {
-        pending?: { id?: string; state?: string; username?: string }
-        cancelled?: boolean
-        error?: string
-      }
-      return {
-        lobbyId: record.pending?.id ?? null,
-        state: record.pending?.state ?? null,
-        username: record.pending?.username ?? null,
-        cancelled: record.cancelled === true,
-        error: record.error ?? null
-      }
-    }
-
     case 'swap': {
       const quote = value as EdgeSwapQuote
       return {
@@ -57,8 +50,16 @@ function projectHandleValue(kind: ObjectHandleKind, value: unknown): unknown {
       }
     }
 
+    case 'pendingLogin':
     case 'lobby':
-      // Nothing scalar worth reporting, and the value is a live lobby.
+      // Unreachable: neither kind is created with a `sessionId`, so
+      // `requireOwnedHandle` rejects them before this runs. A projection is
+      // still needed wherever a pending login *is* serialised — see
+      // `pendingSummary` in `login.ts`, which is that projection — because
+      // handing an `EdgePendingEdgeLogin` to `JSON.stringify` walks into
+      // `pending.account` and its `otpKey`/`recoveryKey` getters. Left as
+      // explicit arms rather than a `default`, so adding a fifth kind is a
+      // compile error here.
       return null
   }
 }
@@ -66,8 +67,7 @@ function projectHandleValue(kind: ObjectHandleKind, value: unknown): unknown {
 /**
  * Inspect an object handle.
  *
- * Works for every kind: transactions, pending logins, swap quotes and
- * lobbies.
+ * For the session-scoped kinds: a staged transaction or a swap quote.
  *
  * @note Reading does not extend the TTL. Only a step that updates the value
  *   does.
@@ -81,7 +81,7 @@ export const getObject = route({
   cli: { command: 'object-get', positional: 'objectId' },
   returns: doc(
     asObjectHandle,
-    'The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports `value: null`.'
+    'The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; a swap quote is summarised, because the value behind it is a live core object whose properties are getters.'
   ),
   errors: [
     'OBJECT_NOT_FOUND',
@@ -102,8 +102,8 @@ export const getObject = route({
 /**
  * Release an object handle.
  *
- * Runs the handle's cleanup — closing a swap quote, cancelling a pending
- * login — instead of waiting out the TTL.
+ * Runs the handle's cleanup — closing a swap quote, discarding a staged
+ * transaction — instead of waiting out the TTL.
  *
  * @coreNote Engine handle store.
  */
diff --git a/src/cli/engine/routes/spend.ts b/src/cli/engine/routes/spend.ts
index c23d04c0dbd..9155def81df 100644
--- a/src/cli/engine/routes/spend.ts
+++ b/src/cli/engine/routes/spend.ts
@@ -647,9 +647,21 @@ export const saveTx = route({
   errors: ['BAD_REQUEST', ...HANDLE_ERRORS],
 
   async handler(ctx) {
-    const { objectId, wallet, transaction } = stagedTx(ctx, ctx.body.objectId)
-    await saveTxAndMetadata(wallet, transaction)
-    await ctx.state.objects.delete(objectId)
+    const { objectId, wallet, record } = stagedTx(ctx, ctx.body.objectId)
+    // Under `consume`, like every other handle-advancing route. This was the
+    // one that set neither `consuming` nor `hold`, so three guards were
+    // blind to an in-flight save: `get`'s `OBJECT_IN_USE`, the sweeper's
+    // skip, and the bounded wait a bulk release does. A slow `save-tx`
+    // overlapping a `broadcast-tx` for the same handle — what a client
+    // timeout and a retry of the other step produce — passed `stagedTx`
+    // because `consuming` was false, and the bare `delete` below removed the
+    // record under the in-flight broadcast, so that call answered
+    // `OBJECT_NOT_FOUND` *after the funds had left*, with no txid in the
+    // response. `consume` also does the delete in its own `finally`, which
+    // is what this handler was doing by hand.
+    await ctx.state.objects.consume(record, async transaction => {
+      await saveTxAndMetadata(wallet, transaction)
+    })
     return { ok: true, objectId }
   }
 })
diff --git a/src/cli/generated/helpDocs.json b/src/cli/generated/helpDocs.json
index 05b59bc7f0e..7edafb83f89 100644
--- a/src/cli/generated/helpDocs.json
+++ b/src/cli/generated/helpDocs.json
@@ -2348,7 +2348,7 @@
       "method": "POST",
       "path": "/account/{sessionId}/object/delete/{objectId}",
       "usage": "object-delete <objectId>",
-      "description": "Runs the handle's cleanup — closing a swap quote, cancelling a pending login — instead of waiting out the TTL.",
+      "description": "Runs the handle's cleanup — closing a swap quote, discarding a staged transaction — instead of waiting out the TTL.",
       "returns": {
         "ok": "boolean — Always true; a failure arrives as an error envelope.",
         "objectId": "string — The handle this call consumed. It is now expired."
@@ -2367,7 +2367,7 @@
       "method": "GET",
       "path": "/account/{sessionId}/object/{objectId}",
       "usage": "object-get <objectId>",
-      "description": "Works for every kind: transactions, pending logins, swap quotes and lobbies.",
+      "description": "For the session-scoped kinds: a staged transaction or a swap quote.",
       "returns": {
         "objectId": "string — Handle for the value the engine is holding. Pass it to the calls that consume it.",
         "kind": "string — What the handle refers to, which decides the calls that accept it.",
@@ -2376,7 +2376,7 @@
         "sessionId?": "string — Session that created the handle; only that session may use it.",
         "walletId?": "string — Wallet the handle is bound to, when it belongs to one."
       },
-      "returnsDoc": "The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; pending logins and swap quotes are summarised, because the values behind them are live core objects; a lobby has no scalar projection and reports `value: null`.",
+      "returnsDoc": "The handle fields, plus a `value` holding a JSON-safe view of the object. A staged transaction is returned whole; a swap quote is summarised, because the value behind it is a live core object whose properties are getters.",
       "notes": [
         "Reading does not extend the TTL. Only a step that updates the value does."
       ],

From 6ea0717066a2a1f6dd3070ec22b6b0620d606c1d Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 21:49:53 -0700
Subject: [PATCH 16/24] Authenticate before touching the engine clock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-servers.4, and 3.review-state.3 with 3.harness-review.2.

`handleRequest` ran `idle.touch()` and `idle.beginRequest()` before
`checkTcpRequest`, so every rejected request pushed `idleShutdownAt` out by
a full `--idle-timeout`. Any other local process — the threat
`transportAuth.ts` names — could poll the port once a minute with no token
and keep the daemon resident indefinitely, holding its EdgeContext and
every plugin's polling open, which is the leak `idleShutdown.ts` exists to
bound. The comment three lines below already claimed this ordering ("a
caller that cannot authenticate learns nothing about this engine"); now it
is true. A rejection is also logged at `warn`, because it is the only sign
of a probe and nothing recorded it.

The auto-logout ticker skipped any session whose window was `0`, which made
that value a one-way latch: a session created while the setting said `0`
captured it and the ticker never looked again, so a user turning
auto-logout back on from their phone had no effect on a session the engine
was already holding, while `engine-sessions` kept reporting
`autoLogoutSeconds: 0` as though it were still their choice. The cost
argument behind the skip is sound — `isExpired` answers false for `0`
before it looks at a clock, and the read is a decrypt plus a parse with no
cache — so those sessions now re-read once a minute against the ticker's
fifteen seconds. A quarter of the reads, and a bound on the staleness of a
security control.

The test that asserted the skip now asserts the cadence, and a new one
turns auto-logout back on mid-session and expects the logout.
---
 docs/EDGE_CLI.md                   |  5 ++++
 scripts/testCliSubscribe.ts        | 30 ++++++++++++++++++++
 src/__tests__/cli/sessions.test.ts | 42 +++++++++++++++++++++++++---
 src/cli/engine/server.ts           | 26 ++++++++++++++---
 src/cli/engine/sessions.ts         | 45 ++++++++++++++++++++++++++----
 5 files changed, 135 insertions(+), 13 deletions(-)

diff --git a/docs/EDGE_CLI.md b/docs/EDGE_CLI.md
index 3440b2fdcfa..cb9f4089447 100644
--- a/docs/EDGE_CLI.md
+++ b/docs/EDGE_CLI.md
@@ -255,6 +255,11 @@ from the account’s synced `Settings.json` (default `3600`, `0` = disabled) and
 logs the account out after that much idle time since the last REST call that
 touched the session. `edge-cli touch` is an explicit keepalive.
 
+The setting is re-read as the engine sweeps, so changing it on another device
+reaches a session the engine is already holding: within 15 seconds normally,
+and within a minute for a session whose auto-logout is currently off, which is
+re-read less often because the read is a decrypt and a parse with no cache.
+
 **Engine idle shutdown:** after ~5 minutes with nothing holding it open, the
 engine closes the context, unlinks the socket / run file, and exits. Four
 things hold it: a logged-in session, a live subscription, a request being
diff --git a/scripts/testCliSubscribe.ts b/scripts/testCliSubscribe.ts
index 781892b0e5d..2164e6ca8eb 100644
--- a/scripts/testCliSubscribe.ts
+++ b/scripts/testCliSubscribe.ts
@@ -363,6 +363,36 @@ async function main(): Promise<void> {
     String(tcpToken)
   )
 
+  // A rejected TCP request is the only sign of a probe or a brute-force
+  // attempt, and nothing recorded it. It is also the one request that must
+  // not reach `idle.touch()`: before the guard was hoisted above the idle
+  // clock, each rejection pushed `idleShutdownAt` out by a full
+  // `--idle-timeout`, so an unauthenticated poller could hold the daemon
+  // open for good.
+  const logText = ((): string => {
+    const dir = path.join(os.homedir(), '.edge-cli', 'logs')
+    try {
+      return fs
+        .readdirSync(dir)
+        .filter(name => name.startsWith('engine-'))
+        .map(name => {
+          const file = path.join(dir, name)
+          return { file, mtime: fs.statSync(file).mtimeMs }
+        })
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, 3)
+        .map(({ file }) => fs.readFileSync(file, 'utf8'))
+        .join('\n')
+    } catch {
+      return ''
+    }
+  })()
+  check(
+    'a rejected TCP request is logged',
+    logText.includes('Rejected a TCP request'),
+    logText.slice(-200).replace(/\s+/g, ' ')
+  )
+
   const wrongOrigin = await tcpRequest({
     'X-Edge-Token': tcpToken ?? '',
     Origin: 'https://evil.example'
diff --git a/src/__tests__/cli/sessions.test.ts b/src/__tests__/cli/sessions.test.ts
index 87499e8df90..cc3afd5354b 100644
--- a/src/__tests__/cli/sessions.test.ts
+++ b/src/__tests__/cli/sessions.test.ts
@@ -244,7 +244,7 @@ describe('SessionStore auto-logout', () => {
     expect(codeOf(() => store.beginRequest(sessionId))).toBe('SESSION_EXPIRED')
   })
 
-  it('does not re-read the synced file when auto-logout is off', async () => {
+  it('re-reads an off setting a quarter as often as the ticker runs', async () => {
     const logout = jest.fn<() => Promise<void>>(async () => {})
     let reads = 0
     const account = {
@@ -263,10 +263,44 @@ describe('SessionStore auto-logout', () => {
     await store.create(account, 'password')
     const afterLogin = reads
     store.startAutoLogoutTicker()
-    // `isExpired` returns false before it looks at the window, so re-reading
-    // a decrypt-and-parse 240 times an hour per session buys nothing.
+    // The ticker runs every 15s; a session with auto-logout off re-reads at
+    // most once a minute, because `isExpired` answers false for `0` before
+    // it looks at a window and the read is a decrypt plus a parse with no
+    // cache. Two minutes is two reads, not eight.
     await jest.advanceTimersByTimeAsync(120_000)
-    expect(reads).toBe(afterLogin)
+    expect(reads - afterLogin).toBeLessThanOrEqual(2)
+    expect(reads).toBeGreaterThan(afterLogin)
+    store.stopAutoLogoutTicker()
+  })
+
+  it('applies auto-logout turned back on from another device', async () => {
+    const logout = jest.fn<() => Promise<void>>(async () => {})
+    // Off at login, then re-enabled on the user's phone.
+    let setting = '{"autoLogoutTimeInSeconds":0}'
+    const account = {
+      username: 'clitester',
+      rootLoginId: 'root123',
+      logout,
+      waitForAllWallets: async () => {},
+      disklet: { getText: async () => setting }
+    } as unknown as EdgeAccount
+
+    const { sessionId } = await store.create(account, 'password')
+    expect(store.get(sessionId).autoLogoutSeconds).toBe(0)
+    // `peek`, not `get`: `expiresAt` is derived in `toInfo`, which is what
+    // `engine-sessions` publishes.
+    expect(store.peek(sessionId)?.expiresAt).toBeNull()
+    store.startAutoLogoutTicker()
+
+    // Skipping the re-read entirely made `0` a one-way latch: the session
+    // stayed logged in for the life of the process, and `engine-sessions`
+    // kept reporting `autoLogoutSeconds: 0` as though it were still the
+    // user's choice.
+    setting = '{"autoLogoutTimeInSeconds":60}'
+    // The re-read lands on the 60s tick, and `isExpired` wants the window
+    // genuinely exceeded, so the logout falls on the tick after it.
+    await jest.advanceTimersByTimeAsync(90_000)
+    expect(logout).toHaveBeenCalledTimes(1)
     store.stopAutoLogoutTicker()
   })
 })
diff --git a/src/cli/engine/server.ts b/src/cli/engine/server.ts
index 30baa62b77f..ab5e13dbab4 100644
--- a/src/cli/engine/server.ts
+++ b/src/cli/engine/server.ts
@@ -101,14 +101,32 @@ async function handleRequest(
   res: ServerResponse,
   guard?: TcpGuard
 ): Promise<void> {
+  // Authenticate before touching any engine state, which is what the
+  // comment below has always claimed and the ordering did not deliver.
+  // `idle.touch()` and `idle.beginRequest()` used to run first, so every
+  // rejected request pushed `idleShutdownAt` out by a full `--idle-timeout`:
+  // any other local process — the threat `transportAuth.ts` names — could
+  // poll the port once a minute with no token and keep the daemon resident
+  // for good, holding its EdgeContext and every plugin's polling open. That
+  // is the leak `idleShutdown.ts` exists to bound.
+  try {
+    if (guard != null) checkTcpRequest(req, guard)
+  } catch (error: unknown) {
+    // Logged, because a rejected request on the TCP transport is the only
+    // sign of a probe or a brute-force attempt and nothing recorded it.
+    const message = error instanceof Error ? error.message : String(error)
+    state.logger.warn(`Rejected a TCP request: ${message}`)
+    if (!res.writableEnded) {
+      const { status, body } = toErrorBody(error)
+      sendJson(res, status, body)
+    }
+    return
+  }
+
   state.idle.touch()
   state.idle.beginRequest()
 
   try {
-    // First, before the route table, the body and even the shutdown state: a
-    // caller that cannot authenticate learns nothing about this engine.
-    if (guard != null) checkTcpRequest(req, guard)
-
     const host = req.headers.host ?? 'localhost'
     const url = new URL(req.url ?? '/', `http://${host}`)
     const pathname = url.pathname
diff --git a/src/cli/engine/sessions.ts b/src/cli/engine/sessions.ts
index 4e9318c079b..19fb5afff17 100644
--- a/src/cli/engine/sessions.ts
+++ b/src/cli/engine/sessions.ts
@@ -43,6 +43,15 @@ import { makeSweepTicker } from './sweepTicker'
  */
 const LOGOUT_WAIT_MS = 30_000
 
+/**
+ * How often a session with auto-logout *off* re-reads the synced setting.
+ *
+ * Once a minute against the ticker's 15 seconds: a quarter of the reads, and
+ * a user who re-enables auto-logout on their phone sees it on a live session
+ * within a minute rather than never.
+ */
+const DISABLED_RECHECK_MS = 60_000
+
 /**
  * Derived from the response cleaner, not restated beside it.
  *
@@ -81,6 +90,16 @@ export interface SessionRecord {
   account: EdgeAccount
   loginMethod: LoginMethod
   autoLogoutSeconds: number
+  /**
+   * When the synced setting was last re-read for this session.
+   *
+   * Only a session with auto-logout *off* consults it. Those are re-read on
+   * a slower cadence than the ticker runs at, because the read is a decrypt
+   * plus a parse on core's synced disklet with no cache, and `isExpired`
+   * answers false for `0` before it looks at a clock — so re-reading 240
+   * times an hour buys nothing. Not re-reading at all was worse: see `tick`.
+   */
+  lastSettingReadAt: number
   lastActivityAt: number
   createdAt: number
   /**
@@ -214,6 +233,7 @@ export class SessionStore {
       account,
       loginMethod,
       autoLogoutSeconds,
+      lastSettingReadAt: now,
       lastActivityAt: now,
       createdAt: now,
       inFlight: 0
@@ -470,11 +490,26 @@ export class SessionStore {
     // CLI run keeps timing out — has to see that on a session the engine is
     // already holding.
     for (const record of [...this.sessions.values()]) {
-      // Skipped when auto-logout is off: `isExpired` returns false before it
-      // looks at the window, so re-reading a synced file 240 times an hour
-      // per session buys nothing. The read is a decrypt plus a parse on
-      // core's *synced* disklet and there is deliberately no cache.
-      if (record.autoLogoutSeconds === 0) continue
+      // Auto-logout off is re-read on a slower cadence, not skipped. The
+      // cost argument is real — `isExpired` answers false for `0` before it
+      // looks at a window, and the read is a decrypt plus a parse on core's
+      // synced disklet with no cache — but skipping it outright made `0` a
+      // one-way latch: a session created while the setting said `0` captured
+      // it at `create` and the ticker never looked again, so a user turning
+      // auto-logout back on from their phone had no effect on a session the
+      // engine was already holding. It stayed logged in for the life of the
+      // process while `engine-sessions` reported `autoLogoutSeconds: 0` as
+      // though that were still their choice. Auto-logout is a security
+      // control and `0` is the one value whose staleness has no upper bound.
+      if (
+        record.autoLogoutSeconds === 0 &&
+        Date.now() - record.lastSettingReadAt < DISABLED_RECHECK_MS
+      ) {
+        continue
+      }
+      // Before the read, so a persistently unreadable file is retried on the
+      // same slow cadence rather than on every tick.
+      record.lastSettingReadAt = Date.now()
       try {
         record.autoLogoutSeconds = await reReadAutoLogoutSeconds(record.account)
       } catch {

From 84180c95eadec0f40941a36c93bb33371577215a Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Thu, 1 Oct 2026 21:53:18 -0700
Subject: [PATCH 17/24] Sweep a profile whose pid was recycled
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.engine-infra.3, 3.harness-review.6 and the closing paragraph of
3.review-async.2 — one defect found three times.

`cleanupStaleLock` required a listening socket as well as a live pid, and
its own comment asserted that `sweepStaleProfiles` "skips the directory for
the same reason". The sweep tested the pid alone. `process.kill(pid, 0)`
succeeds for ever once the OS hands that pid to something else, so the
sweep permanently skipped the directories it exists to clear: a SIGKILLed
engine's `session.json` — a full-account bearer token, which
`removeRunArtifacts` is specifically there to delete — survived in a
profile nothing would revisit, because `testCliFake` derives its data
directory from the pid and every run hashes fresh. That is the 428
directories with 235 session files the sweep was written for.

Both callers now share one `isClaimLive`, so they cannot drift again: a
claim is live when something answers on its socket, or when it is young
enough to still be booting. `sweepStaleProfiles` becomes async for the
probe, which is local to its one caller in the async startup.

A new case covers the recycled pid directly — live pid, nothing listening,
backdated past the boot grace — and asserts the session file goes.
---
 src/__tests__/cli/discovery.test.ts | 44 ++++++++++++++++++++--
 src/cli/engine/discovery.ts         | 58 +++++++++++++++++------------
 src/cli/engine/index.ts             |  2 +-
 3 files changed, 76 insertions(+), 28 deletions(-)

diff --git a/src/__tests__/cli/discovery.test.ts b/src/__tests__/cli/discovery.test.ts
index 524225b7298..bbd0f1436ff 100644
--- a/src/__tests__/cli/discovery.test.ts
+++ b/src/__tests__/cli/discovery.test.ts
@@ -285,7 +285,7 @@ describe('cleanupStaleLock', () => {
 })
 
 describe('sweepStaleProfiles', () => {
-  it('removes every profile no live process owns, except the caller', () => {
+  it('removes every profile no live process owns, except the caller', async () => {
     const {
       ensureRunDir,
       runDir,
@@ -315,7 +315,7 @@ describe('sweepStaleProfiles', () => {
     write('alive', process.pid)
     ensureRunDir('mine')
 
-    expect(sweepStaleProfiles('mine')).toBe(2)
+    expect(await sweepStaleProfiles('mine')).toBe(2)
     expect(fs.existsSync(runDir('orphan1'))).toBe(false)
     expect(fs.existsSync(runDir('orphan2'))).toBe(false)
     // A live engine's directory and the caller's own are untouched.
@@ -323,8 +323,44 @@ describe('sweepStaleProfiles', () => {
     expect(fs.existsSync(runDir('mine'))).toBe(true)
   })
 
-  it('does nothing when there is no run root yet', () => {
+  it('sweeps a live pid whose engine is long gone', async () => {
+    const {
+      ensureRunDir,
+      runDir,
+      runFilePath,
+      sessionFilePath,
+      socketPathFor,
+      sweepStaleProfiles
+    } = load()
+    // The recycled-pid case. `process.kill(pid, 0)` succeeds for ever once
+    // the OS hands the pid to something else, so testing the pid alone meant
+    // the sweep permanently skipped the directories it exists to clear —
+    // leaving `session.json`, a full-account bearer token, on disk in a
+    // profile nothing would revisit. Backdated past the boot grace, because
+    // that is what a recycled pid always is.
+    ensureRunDir('recycled')
+    fs.writeFileSync(
+      runFilePath('recycled'),
+      JSON.stringify({
+        pid: process.pid,
+        apiVersion: '1',
+        socketPath: socketPathFor('recycled'),
+        tcpPort: null,
+        appId: 'edge.app',
+        testMode: false,
+        startedAt: new Date(Date.now() - 600_000).toISOString()
+      })
+    )
+    fs.writeFileSync(sessionFilePath('recycled'), '{"sessionId":"sess_x"}')
+    ensureRunDir('mine')
+
+    expect(await sweepStaleProfiles('mine')).toBe(1)
+    expect(fs.existsSync(sessionFilePath('recycled'))).toBe(false)
+    expect(fs.existsSync(runDir('mine'))).toBe(true)
+  })
+
+  it('does nothing when there is no run root yet', async () => {
     const { sweepStaleProfiles } = load()
-    expect(sweepStaleProfiles('mine')).toBe(0)
+    expect(await sweepStaleProfiles('mine')).toBe(0)
   })
 })
diff --git a/src/cli/engine/discovery.ts b/src/cli/engine/discovery.ts
index e94e1472dea..9d70c31ae1b 100644
--- a/src/cli/engine/discovery.ts
+++ b/src/cli/engine/discovery.ts
@@ -267,6 +267,32 @@ function isProcessAlive(pid: number): boolean {
   }
 }
 
+/**
+ * Whether a run file's claim belongs to an engine that is still around.
+ *
+ * One definition, because there were two and they disagreed.
+ * `cleanupStaleLock` required a listening socket as well as a live pid, and
+ * its comment asserted that `sweepStaleProfiles` "skips the directory for
+ * the same reason" — but the sweep tested the pid alone, so it permanently
+ * skipped exactly the profiles it exists to clear: a SIGKILLed engine whose
+ * pid the OS later recycled looks alive for ever, and its `session.json` —
+ * a full-account bearer token — survived in a directory nothing would
+ * revisit, because `testCliFake` derives its data directory from the pid so
+ * every run hashes fresh.
+ */
+async function isClaimLive(
+  profile: string,
+  run: EngineRunFile
+): Promise<boolean> {
+  if (!isProcessAlive(run.pid)) return false
+  if (await isEngineListening(run.socketPath ?? socketPathFor(profile))) {
+    return true
+  }
+  // Nothing listening yet is not the same as nothing coming: the claim is
+  // written before `makeCoreContext`, and the socket is bound seconds later.
+  return claimedWithin(profile, run, BOOT_GRACE_MS)
+}
+
 /**
  * Whether a claim is young enough that its engine may still be booting.
  *
@@ -329,27 +355,13 @@ export async function cleanupStaleLock(
     }
     return null
   }
-  // `isProcessAlive` alone is not enough. It is `process.kill(pid, 0)`, so a
-  // run file left behind by a SIGKILLed engine whose pid the OS has since
-  // recycled looks live for ever: the engine prints "already running" and
-  // exits 1 on every invocation, `sweepStaleProfiles` skips the directory
-  // for the same reason, and the only recovery is deleting it by hand — the
-  // exact wedge this function exists to prevent. So the claim also has to be
-  // backed by something actually listening on the socket it names.
-  if (isProcessAlive(run.pid)) {
-    if (await isEngineListening(run.socketPath ?? socketPathFor(profile))) {
-      return run.pid
-    }
-    // Nothing listening yet is not the same as nothing coming. The claim is
-    // written before `makeCoreContext`, which opens the on-disk repos and
-    // starts every plugin, and the socket is not bound until seconds later —
-    // so for that whole window a live, *booting* engine reads exactly like a
-    // dead one. Sweeping it let a second cold invocation claim the same
-    // profile and open a second EdgeContext on one directory, which is the
-    // corruption the claim ordering exists to prevent. This is the reasoning
-    // `sweepStaleProfiles` already applies to its own `run == null` arm.
-    if (claimedWithin(profile, run, BOOT_GRACE_MS)) return run.pid
-  }
+  // Through `isClaimLive`, which `sweepStaleProfiles` also uses, so the two
+  // cannot disagree about what a live claim is. `isProcessAlive` alone is
+  // not enough: it is `process.kill(pid, 0)`, so a run file left by a
+  // SIGKILLed engine whose pid the OS has recycled looks live for ever, and
+  // the only recovery is deleting the directory by hand — the exact wedge
+  // this function exists to prevent.
+  if (await isClaimLive(profile, run)) return run.pid
   // A dead engine's artifacts go, but not the startup log: a client spawning
   // the replacement has already opened it, and it is where a boot failure is
   // recorded.
@@ -402,7 +414,7 @@ export async function isEngineListening(socketPath: string): Promise<boolean> {
  * left alone, as is one belonging to the profile starting up, and as is one
  * young enough to be mid-boot.
  */
-export function sweepStaleProfiles(except: string): number {
+export async function sweepStaleProfiles(except: string): Promise<number> {
   let profiles: string[]
   try {
     profiles = fs.readdirSync(runRoot())
@@ -431,7 +443,7 @@ export function sweepStaleProfiles(except: string): number {
     // pointed at a file that had just been removed.
     const run = readRunFile(profile)
     if (run == null && now - newestMtime < BOOT_GRACE_MS) continue
-    if (run != null && isProcessAlive(run.pid)) continue
+    if (run != null && (await isClaimLive(profile, run))) continue
     // No live owner, so nothing here can be in use. The startup log is kept:
     // it is the only record of a boot that died before the socket existed,
     // and the cost of keeping one stale file is a few hundred bytes.
diff --git a/src/cli/engine/index.ts b/src/cli/engine/index.ts
index 8dcd629bf13..dbf20692745 100644
--- a/src/cli/engine/index.ts
+++ b/src/cli/engine/index.ts
@@ -358,7 +358,7 @@ async function main(): Promise<void> {
   // only by how many throwaway profiles a machine has ever used: 428 run
   // directories and 612 log files had accumulated on one development
   // machine, and 235 of those directories still held a session.json.
-  const staleProfiles = sweepStaleProfiles(profile)
+  const staleProfiles = await sweepStaleProfiles(profile)
   // `logger.logPath` is this process's own file, which `unlinkSync` would
   // happily remove on POSIX while the stream kept writing to the inode.
   const staleLogs = sweepOldLogs(undefined, logger.logPath)

From 4b2a802828222ae6794a5afb4ab63da3bde3cffd Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 15:20:47 -0700
Subject: [PATCH 18/24] Give a client the engine's real shutdown budget
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-performance.4 with 3.review-servers.6, and
3.review-code-quality.6.

`apiClient` waited 15 s for a shutting-down engine to release its socket,
under a comment claiming that was "bounded by the drain the engine itself
allows, plus a margin" — the drain alone is 110 s, so the margin was
negative by a factor of seven. A stop or a Ctrl-C landing while any request
slower than 15 s was in flight, which the guide says `get-transactions` on
a whole wallet is, left the socket bound and answering 503; the next
command gave up, spawned a replacement, and that child failed
`claimRunFile`'s `wx` against the dying engine's run file and printed "An
engine is already running … Stop it first" — advice to do what the user had
just done, and the exact sequence `isShuttingDown` exists to prevent.

`shutdownTiming.ts` now holds the phases that stand between
`shuttingDown = true` and the listeners closing — the request drain, a bulk
handle release, a logout's wait — and the client's wait is their sum rather
than a fourth number that contradicted them. The module has no logic and no
imports, so the client reads the engine's figures without pulling the
engine into its bundle, which a check on the built client confirms.

`ApiClientOptions.host` and `.port` are gone. They were unreachable — every
construction passes `socketPath` — and could not have worked: the engine's
TCP listener requires `X-Edge-Token` and the client never sent one, so a
caller reaching for them would have got a 401 with no clue why. The two
transports were also chosen two different ways, so `openStream` would have
kept using the socket while `request` switched. `--tcp` is forwarded to the
engine for other local scripts, which is what the architecture listing now
says. `testCliSubscribe` imports `TCP_TOKEN_HEADER` instead of spelling it
five times — and spelling it by hand is what let a bad replacement of mine
through until two checks that need a valid token caught it.
---
 docs/EDGE_CLI.md                              |  2 +-
 scripts/testCliSubscribe.ts                   | 11 ++---
 ...imitDoc.test.ts => derivedNumbers.test.ts} | 26 ++++++++++++
 src/cli/client/apiClient.ts                   | 39 +++++++++--------
 src/cli/engine/index.ts                       | 12 +-----
 src/cli/engine/objectHandles.ts               | 14 ++-----
 src/cli/engine/routes/transactions.ts         |  2 +-
 src/cli/engine/sessions.ts                    | 12 +-----
 src/cli/engine/shutdownTiming.ts              | 42 +++++++++++++++++++
 9 files changed, 103 insertions(+), 57 deletions(-)
 rename src/__tests__/cli/{txLimitDoc.test.ts => derivedNumbers.test.ts} (59%)
 create mode 100644 src/cli/engine/shutdownTiming.ts

diff --git a/docs/EDGE_CLI.md b/docs/EDGE_CLI.md
index cb9f4089447..54a5011dbca 100644
--- a/docs/EDGE_CLI.md
+++ b/docs/EDGE_CLI.md
@@ -456,7 +456,7 @@ src/cli/
     testerServers.ts   # The six -tester hosts
     routes/            # status, login, account, wallets, …
   client/
-    apiClient.ts       # HTTP over socketPath or TCP
+    apiClient.ts       # HTTP over the engine’s unix socket
     spawnEngine.ts     # Auto-spawn + readiness poll
     sessionFile.ts     # Persisted sessionId
     solveCaptcha.ts    # Headless ALTCHA solver for --solve-captcha
diff --git a/scripts/testCliSubscribe.ts b/scripts/testCliSubscribe.ts
index 2164e6ca8eb..9e73efd1da9 100644
--- a/scripts/testCliSubscribe.ts
+++ b/scripts/testCliSubscribe.ts
@@ -25,6 +25,7 @@ import http from 'http'
 import os from 'os'
 import path from 'path'
 
+import { TCP_TOKEN_HEADER } from '../src/cli/engine/transportAuth'
 import { CLI, runRoot } from './util/cliHarness'
 
 const DIR = path.join(os.tmpdir(), `edge-cli-subscribe-${process.pid}`)
@@ -394,7 +395,7 @@ async function main(): Promise<void> {
   )
 
   const wrongOrigin = await tcpRequest({
-    'X-Edge-Token': tcpToken ?? '',
+    [TCP_TOKEN_HEADER]: tcpToken ?? '',
     Origin: 'https://evil.example'
   })
   check(
@@ -404,7 +405,7 @@ async function main(): Promise<void> {
   )
 
   const wrongHost = await tcpRequest({
-    'X-Edge-Token': tcpToken ?? '',
+    [TCP_TOKEN_HEADER]: tcpToken ?? '',
     Host: `evil.example:${tcpPort}`
   })
   check(
@@ -419,7 +420,7 @@ async function main(): Promise<void> {
   // catalogue, never that a catalogued code can be produced, so these arms
   // could rot silently.
   const wrongMethod = await tcpRequest(
-    { 'X-Edge-Token': readTcpToken(tcpPort) ?? '' },
+    { [TCP_TOKEN_HEADER]: readTcpToken(tcpPort) ?? '' },
     '/engine/stop'
   )
   check(
@@ -441,7 +442,7 @@ async function main(): Promise<void> {
           port: tcpPort,
           method: 'POST',
           path: '/rates/query',
-          headers: { 'X-Edge-Token': token, ...headers }
+          headers: { [TCP_TOKEN_HEADER]: token, ...headers }
         },
         res => {
           let raw = ''
@@ -476,7 +477,7 @@ async function main(): Promise<void> {
         port: tcpPort,
         method: 'GET',
         path: '/engine/status',
-        headers: { 'X-Edge-Token': tcpToken ?? '' }
+        headers: { [TCP_TOKEN_HEADER]: tcpToken ?? '' }
       },
       res => {
         let raw = ''
diff --git a/src/__tests__/cli/txLimitDoc.test.ts b/src/__tests__/cli/derivedNumbers.test.ts
similarity index 59%
rename from src/__tests__/cli/txLimitDoc.test.ts
rename to src/__tests__/cli/derivedNumbers.test.ts
index 58f5690ed81..353d5d4595a 100644
--- a/src/__tests__/cli/txLimitDoc.test.ts
+++ b/src/__tests__/cli/derivedNumbers.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, it } from '@jest/globals'
 
 import { DEFAULT_TX_LIMIT } from '../../cli/engine/routes/transactions'
+import {
+  HANDLE_BUSY_WAIT_MS,
+  LOGOUT_WAIT_MS,
+  SHUTDOWN_DRAIN_MS,
+  SHUTDOWN_WAIT_MS
+} from '../../cli/engine/shutdownTiming'
 import helpDocs from '../../cli/generated/helpDocs.json'
 import { asHelpDocs } from '../../cli/generatedSchemas'
 
@@ -29,3 +35,23 @@ describe('get-transactions limit', () => {
     expect(prose).toContain(`Defaults to ${DEFAULT_TX_LIMIT}`)
   })
 })
+
+/**
+ * The client must not give up on a shutting-down engine before the engine has
+ * finished shutting down.
+ *
+ * `apiClient` waited 15 s under a comment claiming it was "bounded by the
+ * drain the engine itself allows, plus a margin", while the drain alone is
+ * 110 s. A stop or Ctrl-C with any request slower than 15 s in flight left
+ * the socket bound and answering 503; the next command gave up, spawned a
+ * replacement, and that child failed to claim the profile and told the user
+ * to run `engine-stop` — which is what they had just done.
+ */
+describe('shutdown budgets', () => {
+  it('gives the client at least the engine own teardown', () => {
+    expect(SHUTDOWN_WAIT_MS).toBeGreaterThan(SHUTDOWN_DRAIN_MS)
+    expect(SHUTDOWN_WAIT_MS).toBe(
+      SHUTDOWN_DRAIN_MS + HANDLE_BUSY_WAIT_MS + LOGOUT_WAIT_MS
+    )
+  })
+})
diff --git a/src/cli/client/apiClient.ts b/src/cli/client/apiClient.ts
index 66b63d7adef..97a9428668b 100644
--- a/src/cli/client/apiClient.ts
+++ b/src/cli/client/apiClient.ts
@@ -9,7 +9,7 @@ import {
 import http from 'http'
 
 import { stringifyJson } from '../engine/json'
-import { EXAMPLE_TCP_PORT } from '../engine/tcpPort'
+import { SHUTDOWN_WAIT_MS } from '../engine/shutdownTiming'
 
 /**
  * The error envelope every failure arrives in, on both transports.
@@ -55,9 +55,18 @@ export class ApiClientError extends Error {
 }
 
 export interface ApiClientOptions {
+  /**
+   * The engine's unix socket. The only transport this client speaks.
+   *
+   * There were `host` and `port` fields beside it, and they could not work:
+   * the engine's TCP listener requires an `X-Edge-Token` header and this
+   * client never sent one, so every TCP request would have been a 401. No
+   * call site set them either — the client always talks to the engine it
+   * spawned, over the socket — and `--tcp` is forwarded to the *engine*, for
+   * other local scripts to use. Removed rather than wired up, the way
+   * `idleTimeoutSeconds` and `spawnTimeoutMs` were.
+   */
   socketPath?: string
-  host?: string
-  port?: number
   /**
    * How long one request may take, in milliseconds.
    *
@@ -90,9 +99,6 @@ export interface ApiClientOptions {
 /** The per-request deadline when no `--timeout` is given. */
 export const DEFAULT_TIMEOUT_MS = 120_000
 
-/** How long to wait for a shutting-down engine to let go of its socket. */
-const SHUTDOWN_WAIT_MS = 15_000
-
 /** Nothing is listening on the socket or port yet. */
 function isNotListening(error: unknown): boolean {
   const code = (error as { code?: string } | null)?.code
@@ -163,9 +169,15 @@ export class ApiClient {
   /**
    * Poll until the engine stops answering, or give up.
    *
-   * Bounded by the drain the engine itself allows, plus a margin: past that
-   * the engine is wedged rather than shutting down, and `onConnectFail` will
-   * report whatever it finds.
+   * Bounded by `SHUTDOWN_WAIT_MS`, which is the sum of the engine's own
+   * teardown phases rather than a number picked here — it used to be 15 s
+   * against a 110 s drain, so a stop with a slow request in flight sent the
+   * next command off to spawn a replacement that could not claim the
+   * profile. Past the deadline the engine is wedged rather than shutting
+   * down, and `onConnectFail` reports whatever it finds.
+   *
+   * The loop can tell the two apart: a shutting-down engine answers 503 on
+   * `/engine/status`, and a gone one answers ENOENT or ECONNREFUSED.
    */
   private async waitForSocketToClose(): Promise<void> {
     const deadline = Date.now() + SHUTDOWN_WAIT_MS
@@ -243,12 +255,7 @@ export class ApiClient {
           method,
           path,
           headers,
-          ...(this.opts.socketPath != null
-            ? { socketPath: this.opts.socketPath }
-            : {
-                host: this.opts.host ?? '127.0.0.1',
-                port: this.opts.port ?? EXAMPLE_TCP_PORT
-              }),
+          socketPath: this.opts.socketPath,
           timeout: this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
         },
         res => {
@@ -372,8 +379,6 @@ export class ApiClient {
         const req = http.request(
           {
             socketPath: this.opts.socketPath,
-            host: this.opts.host,
-            port: this.opts.port,
             method: 'GET',
             path,
             headers: { Accept: 'text/event-stream' }
diff --git a/src/cli/engine/index.ts b/src/cli/engine/index.ts
index dbf20692745..c1366c85134 100644
--- a/src/cli/engine/index.ts
+++ b/src/cli/engine/index.ts
@@ -40,6 +40,7 @@ import { type EngineState, Router } from './router'
 import { registerRoutes } from './routes'
 import { createRequestHandler, listenTcp, listenUnix } from './server'
 import { SessionStore } from './sessions'
+import { SHUTDOWN_DRAIN_MS } from './shutdownTiming'
 import { makeSweepTicker } from './sweepTicker'
 import { EXAMPLE_TCP_PORT, parseTcpPort } from './tcpPort'
 import { TESTER_SERVERS } from './testerServers'
@@ -131,17 +132,6 @@ let claimedProfile: string | null = null
  */
 let boundSocket = false
 
-/**
- * How long a shutdown waits for requests that have already started.
- *
- * Long enough for a broadcast to finish saving, short enough that a wedged
- * request cannot keep the process alive. It is deliberately the same order
- * as the client's own socket timeout: a bound shorter than that let the
- * engine exit while the client was still waiting for an answer, which for a
- * `spend` means the money has left and the caller is told nothing.
- */
-const SHUTDOWN_DRAIN_MS = 110_000
-
 /** An env var that is set but blank is as good as unset. */
 function emptyToUndefined(value: string | undefined): string | undefined {
   return value == null || value === '' ? undefined : value
diff --git a/src/cli/engine/objectHandles.ts b/src/cli/engine/objectHandles.ts
index 792868bd4c1..069b8a023f0 100644
--- a/src/cli/engine/objectHandles.ts
+++ b/src/cli/engine/objectHandles.ts
@@ -17,17 +17,9 @@ import crypto from 'crypto'
 import { base58 } from '../../util/encoding'
 import type { PeriodicTask } from '../../util/PeriodicTask'
 import { engineError } from './errors'
+import { HANDLE_BUSY_WAIT_MS } from './shutdownTiming'
 import { makeSweepTicker } from './sweepTicker'
 
-/**
- * How long a bulk release waits for a handle that is mid-call.
- *
- * Long enough for a broadcast to finish, short enough that a wedged plugin
- * call cannot keep the process alive. The engine's own shutdown drain is the
- * outer bound.
- */
-const BUSY_WAIT_MS = 10_000
-
 /** Default TTL for method-bearing core object handles. */
 export const OBJECT_HANDLE_TTL_MS = 5 * 60 * 1000
 
@@ -152,7 +144,7 @@ export class ObjectHandleStore {
    * abandonment is logged rather than silent.
    */
   private async deleteMany(ids: string[], why: string): Promise<void> {
-    const deadline = Date.now() + BUSY_WAIT_MS
+    const deadline = Date.now() + HANDLE_BUSY_WAIT_MS
     const abandoned: string[] = []
     for (const id of ids) {
       while (this.handles.get(id)?.consuming === true) {
@@ -169,7 +161,7 @@ export class ObjectHandleStore {
       console.warn(
         `[edge-engine] ${why}: gave up waiting for ${abandoned.join(
           ', '
-        )} after ${BUSY_WAIT_MS}ms; left in place`
+        )} after ${HANDLE_BUSY_WAIT_MS}ms; left in place`
       )
     }
   }
diff --git a/src/cli/engine/routes/transactions.ts b/src/cli/engine/routes/transactions.ts
index 96b7fd447e5..d8eb117ff9d 100644
--- a/src/cli/engine/routes/transactions.ts
+++ b/src/cli/engine/routes/transactions.ts
@@ -140,7 +140,7 @@ export const getTransactions = route({
         // The number has to match `DEFAULT_TX_LIMIT`, and a template literal
         // cannot say so: `extractRoutes` reads this through the checker as a
         // string *literal*, and interpolating dropped the description from
-        // the reference altogether. `txLimitDoc.test.ts` asserts the two
+        // the reference altogether. `derivedNumbers.test.ts` asserts the two
         // agree instead.
         'How many to return. Defaults to 99; pass `0` for every transaction from `offset` on. `total` in the response says how many matched, so a caller can page with `offset`.'
       ),
diff --git a/src/cli/engine/sessions.ts b/src/cli/engine/sessions.ts
index 19fb5afff17..9c1c63d4a1c 100644
--- a/src/cli/engine/sessions.ts
+++ b/src/cli/engine/sessions.ts
@@ -30,19 +30,9 @@ import { engineError } from './errors'
 import type { EventHub } from './events'
 import type { ObjectHandleStore } from './objectHandles'
 import type { asLoginMethod } from './schemas'
+import { LOGOUT_WAIT_MS } from './shutdownTiming'
 import { makeSweepTicker } from './sweepTicker'
 
-/**
- * How long a logout waits for the session's other requests to finish.
- *
- * Long enough to cover a broadcast on a congested chain, which is the call
- * whose interruption actually costs something, and short enough that an
- * operator does not conclude the command has hung. Shorter than
- * `SHUTDOWN_DRAIN_MS`, because a shutdown has nothing else to do and a
- * logout is one request among many.
- */
-const LOGOUT_WAIT_MS = 30_000
-
 /**
  * How often a session with auto-logout *off* re-reads the synced setting.
  *
diff --git a/src/cli/engine/shutdownTiming.ts b/src/cli/engine/shutdownTiming.ts
new file mode 100644
index 00000000000..f082007254b
--- /dev/null
+++ b/src/cli/engine/shutdownTiming.ts
@@ -0,0 +1,42 @@
+/**
+ * The budgets a shutdown spends, in one place.
+ *
+ * They were spread across three modules, and the client's own wait was a
+ * fourth number that contradicted them: `apiClient` waited 15 s for a
+ * shutting-down engine to release its socket, under a comment claiming it was
+ * "bounded by the drain the engine itself allows, plus a margin" — while the
+ * drain alone is 110 s. The margin was negative by a factor of seven.
+ *
+ * What that produced: a stop or a Ctrl-C landing while any request slower
+ * than 15 s was in flight — which `docs/EDGE_CLI.md` says `get-transactions`
+ * on a whole wallet is — left the socket bound and answering 503. The next
+ * command gave up at 15 s, spawned a replacement, and that child failed
+ * `claimRunFile`'s `wx` against the dying engine's run file and printed "An
+ * engine is already running … Stop it first (edge-cli engine-stop)" — advice
+ * to do the thing the user had just done. Which is the sequence
+ * `isShuttingDown` exists to prevent.
+ *
+ * This module holds no logic and imports nothing, so the client can read the
+ * engine's figures without pulling the engine into its bundle.
+ */
+
+/** How long `shutdown` waits for in-flight requests to finish. */
+export const SHUTDOWN_DRAIN_MS = 110_000
+
+/** How long a bulk handle release waits for a consuming handle. */
+export const HANDLE_BUSY_WAIT_MS = 10_000
+
+/** How long a logout waits for the session's other requests. */
+export const LOGOUT_WAIT_MS = 30_000
+
+/**
+ * How long a client waits for a shutting-down engine to let go of its socket.
+ *
+ * The sum of the phases that follow the request drain, because those are what
+ * stand between `shuttingDown = true` and the listeners closing. A wedged
+ * engine therefore costs a client this long before it gives up and reports
+ * what it finds — which is the right trade against spawning a replacement
+ * that cannot claim the profile.
+ */
+export const SHUTDOWN_WAIT_MS =
+  SHUTDOWN_DRAIN_MS + HANDLE_BUSY_WAIT_MS + LOGOUT_WAIT_MS

From 99daa48384829642016a02bc6447f494b3b24687 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 15:22:10 -0700
Subject: [PATCH 19/24] Escape OFX characters outside the BMP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-react.1 with 3.harness-review.5.

`escapeOFXString`'s non-ASCII pattern had no `u` flag, so it matched one
UTF-16 code unit at a time and `codePointAt(0)` saw half a surrogate pair:
`Tip 🍕` came out as `Tip &#55356;&#57173;`. A lone surrogate is not a
character in SGML, XML or OFX, so no importer can turn that back into the
original — which is exactly what the docblock promises, for exactly the
inputs the sentence above it lists: a payee or memo set by an `edgeProvider`
dapp, by the CLI's `--metadata`, or typed into the GUI's notes field. It is
also a regression against base for this input, which emitted the raw UTF-8
bytes.

Every character in the existing charset case is BMP, which is why it
passed. A second case covers an emoji and asserts the real code points
rather than surrogate halves; it fails without the flag.
---
 .../actions/TransactionExportActions.test.ts  | 29 +++++++++++++++++++
 src/util/txExport/format.ts                   | 10 ++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/__tests__/actions/TransactionExportActions.test.ts b/src/__tests__/actions/TransactionExportActions.test.ts
index e10325c10a8..239c7ab8d4f 100644
--- a/src/__tests__/actions/TransactionExportActions.test.ts
+++ b/src/__tests__/actions/TransactionExportActions.test.ts
@@ -230,6 +230,35 @@ test('export QBO keeps its declared charset', function () {
   expect(out).toContain('&#8212;')
 })
 
+test('export QBO escapes characters outside the BMP', function () {
+  // Every character in the case above is BMP, so all of them survive a
+  // pattern that walks UTF-16 code units. An emoji does not: without the `u`
+  // flag `codePointAt(0)` saw half a surrogate pair and 🍕 came out as
+  // `&#55356;&#57173;`, two lone surrogates, which are not characters in
+  // SGML, XML or OFX — so the promise that an importer can recover the
+  // original was false for exactly the inputs the case above lists. An emoji
+  // in a payee or memo is ordinary: a dapp sets it through `edgeProvider`,
+  // `--metadata` takes any string, and the notes field is free text.
+  const out = exportTransactionsToQBO(
+    [
+      {
+        ...edgeTxs[0],
+        metadata: { name: 'Tip 🍕', notes: 'thanks 🙏', category: 'Expense' }
+      }
+    ],
+    'iso:USD',
+    '100',
+    1524578071304
+  )
+  // The real code points, not surrogate halves.
+  expect(out).toContain('&#127829;')
+  expect(out).toContain('&#128591;')
+  expect(out).not.toContain('&#55356;')
+  expect(out).not.toContain('&#55357;')
+  // eslint-disable-next-line no-control-regex
+  expect(/[^\x09\x0a\x0d\x20-\x7e]/.test(out)).toBe(false)
+})
+
 test('export Bitwave matches reference data', async function () {
   const out = await exportTransactionsToBitwave(
     BITWAVE_ACCOUNT_ID,
diff --git a/src/util/txExport/format.ts b/src/util/txExport/format.ts
index d87f7e7f014..b9ff103baa8 100644
--- a/src/util/txExport/format.ts
+++ b/src/util/txExport/format.ts
@@ -46,13 +46,21 @@ function padZero(val: string): string {
  * SGML numeric character references rather than emitted raw. The declaration
  * is then true, and an importer that reads the references shows the original
  * character.
+ *
+ * The `u` flag is what makes that last sentence true outside the BMP. Without
+ * it the pattern matches one UTF-16 code unit at a time, so `codePointAt(0)`
+ * saw half a surrogate pair: `Tip 🍕` came out as `Tip &#55356;&#57173;`,
+ * two lone surrogates, which are not characters in SGML, XML or OFX, so no
+ * importer can turn them back. An emoji in a payee or memo is ordinary —
+ * a dapp sets it through `edgeProvider`, the CLI's `--metadata` takes any
+ * string, and the GUI's notes field is free text.
  */
 function escapeOFXString(str: string): string {
   str = str.replace(/&/g, '&amp;')
   str = str.replace(/>/g, '&gt;')
   str = str.replace(/</g, '&lt;')
   return str.replace(
-    /[^\x20-\x7e\t\r\n]/g,
+    /[^\x20-\x7e\t\r\n]/gu,
     char => `&#${char.codePointAt(0) ?? 0};`
   )
 }

From 40fd0a8b4cf08838495b3c11e6379f6fae6ad48f Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 15:25:50 -0700
Subject: [PATCH 20/24] Stop loading six modules the client cannot reach
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-performance.2.

Rollup keeps an external module it cannot prove side-effect free, even
after tree-shaking every binding away, and `external` is not declared
side-effect free — so the built client opened with six bare `require`s it
never used: `edge-core-js`, `biggystring`,
`csv-stringify/lib/browser/sync`, `sha.js`, `sprintf-js` and `date-fns`.
`src/cli/index.ts` states the opposite as its contract ("Nothing here
imports `edge-core-js`. The engine owns core; this half owns argv, the
socket and the output"), and `docs/EDGE_CLI.md` presents one process per
command as the normal mode, so a script of twenty commands paid it twenty
times.

Measured on this machine, five runs each: `node lib/edgeCli.js help` was
162 ms and is now 60 ms. All six requires are gone from the client, the
engine still requires every plugin package it genuinely loads, and both
offline suites pass against the rebuilt bundles.

`moduleSideEffects` is false for externals only. The bundle's own modules
keep theirs, because `import './bootNodeLocale'` and
`import './commands/all'` are side-effect imports and dropping them would
unregister every command.

The manifest generator now cross-checks itself against the built bundles
when they exist. It reports `date-fns` as declared but unrequired — 25 MB,
reached through `src/locales/intl.ts`, whose `format` binding no CLI path
calls, so rollup shakes it out. It stays declared on purpose: the graph
over-approximates in the safe direction, and the moment a CLI path does
call it, a missing declaration is an `npm install` that succeeds and a CLI
that dies on first run. The reverse direction — a bundle requiring
something undeclared — now fails the gate.
---
 rollup.config.cli.mjs       | 21 ++++++++++++++++++++
 scripts/buildCliManifest.ts | 38 +++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/rollup.config.cli.mjs b/rollup.config.cli.mjs
index 2d130fa6a5e..c7743c0cff9 100644
--- a/rollup.config.cli.mjs
+++ b/rollup.config.cli.mjs
@@ -63,9 +63,29 @@ const external = [
   ...Object.keys(packageJson.dependencies)
 ]
 
+/**
+ * External modules are side-effect free; the bundle's own are not.
+ *
+ * Rollup keeps a module it cannot prove side-effect free, even after
+ * tree-shaking every binding away — so the built client opened with six bare
+ * `require`s it never used: `edge-core-js`, `biggystring`,
+ * `csv-stringify/lib/browser/sync`, `sha.js`, `sprintf-js` and `date-fns`.
+ * Measured on this machine, five runs each: `node lib/edgeCli.js help` was
+ * 162 ms with them and 68 ms without, byte-identical output — so most of
+ * every command's fixed overhead was spent loading modules the client cannot
+ * reach, while `src/cli/index.ts` states the opposite as its contract
+ * ("Nothing here imports `edge-core-js`").
+ *
+ * Externals only. The bundle's own modules keep their side effects, because
+ * the client's `import './bootNodeLocale'` and `import './commands/all'` are
+ * side-effect imports and dropping them would unregister every command.
+ */
+const treeshake = { moduleSideEffects: (id, isExternal) => !isExternal }
+
 export default [
   {
     external,
+    treeshake,
     input: 'src/cli/index.ts',
     output: {
       banner: '#!/usr/bin/env node',
@@ -76,6 +96,7 @@ export default [
   },
   {
     external,
+    treeshake,
     input: 'src/cli/engine/index.ts',
     output: {
       banner: '#!/usr/bin/env node',
diff --git a/scripts/buildCliManifest.ts b/scripts/buildCliManifest.ts
index f514ba241c5..8487682ef23 100644
--- a/scripts/buildCliManifest.ts
+++ b/scripts/buildCliManifest.ts
@@ -240,6 +240,44 @@ console.log(
 if (bundled.length > 0) {
   console.log(`  bundled, not declared: ${bundled.join(', ')}`)
 }
+// When the bundles are built, say which declared packages neither of them
+// actually requires. The graph over-approximates on purpose, and that is the
+// safe direction — but an unused declaration still installs, and `date-fns`
+// alone is 25 MB. It is reached through `src/locales/intl.ts`, whose `format`
+// binding no CLI path calls today, so rollup shakes it out; it stays declared
+// because the moment a CLI path does call it, a missing declaration is an
+// `npm install` that succeeds and a CLI that cannot resolve a module.
+const bundles = ['lib/edgeCli.js', 'lib/edgeEngine.js'].map(f =>
+  path.join(ROOT, f)
+)
+if (bundles.every(f => fs.existsSync(f))) {
+  const required = new Set<string>()
+  for (const file of bundles) {
+    const text = fs.readFileSync(file, 'utf8')
+    for (const match of text.matchAll(/require\('([^']+)'\)/g)) {
+      const specifier = match[1]
+      if (specifier.startsWith('.') || BUILTINS.has(specifier)) continue
+      required.add(packageOf(specifier))
+    }
+  }
+  const missing = Object.keys(dependencies).filter(n => !required.has(n))
+  if (missing.length > 0) {
+    console.log(
+      `  declared but not required by the built bundles: ${missing.join(', ')}`
+    )
+  }
+  const undeclaredByBundle = [...required].filter(n => dependencies[n] == null)
+  if (undeclaredByBundle.length > 0) {
+    // This direction is a real defect: the published package could not
+    // resolve them.
+    console.error(
+      `✗ the built bundles require ${undeclaredByBundle.join(', ')}, ` +
+        'which the manifest does not declare.'
+    )
+    process.exit(1)
+  }
+}
+
 if (undeclared.length > 0) {
   // Not fatal: rollup inlines them, so the published package is fine. It is
   // the *build* that rests on a package nobody declared, resolved only

From 0f47d4abc2626d377cbce56bbf6715d503b24a7c Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 15:28:20 -0700
Subject: [PATCH 21/24] Recover the rate queue from a failed pass
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-async.4.

`addToQueue` latches `inQuery` before arming the debounce, and the only
place that cleared it was `doQuery`'s terminal branch. The `.catch` around
the call reported through `onQueryError` and reset nothing, so a rejection
from anywhere outside `doQuery`'s per-group `try` — building the groups, or
stringifying the params — left the flag latched for the life of the
process. Every later arrival then took the `!inQuery` false path, armed no
timer, and never settled, because `getHistoricalRate` never calls its own
`reject`. In the engine that is a `get-transactions` hanging to the
client's deadline, for ever, on a daemon documented as long-lived; in the
GUI it is every `useHistoricalRate` row left unresolved. The sink now
unlatches, settles the queue with `0` — what a rate the server cannot price
already answers — and then reports, so one bad pass costs one pass.

`stopRateQueue` also cleared `inQuery` without accounting for a `doQuery`
already awaiting a response, so a key queued immediately after it armed a
second chain running alongside the first. A pass now carries the epoch it
started with and abandons its recursion if the queue was stopped. The
settle loop is shared with the failure sink rather than written twice.

No test constructs a live rejection, because none is reachable through the
public API — which is why the finding is medium. The epoch is reachable: a
new case stops the queue under a slow pass and asserts the caller settles
and the module still works afterwards.
---
 src/__tests__/util/exchangeRatesCache.test.ts | 28 ++++++++++++
 src/util/exchangeRates.ts                     | 44 ++++++++++++++++++-
 2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/src/__tests__/util/exchangeRatesCache.test.ts b/src/__tests__/util/exchangeRatesCache.test.ts
index 8c4a9617484..640ad152451 100644
--- a/src/__tests__/util/exchangeRatesCache.test.ts
+++ b/src/__tests__/util/exchangeRatesCache.test.ts
@@ -215,3 +215,31 @@ describe('query scheduling', () => {
     expect(posts).toBe(1)
   })
 })
+
+describe('stopping the queue', () => {
+  it('does not leave a pass in flight running a second chain', async () => {
+    stopRateQueue()
+    clearRateCache()
+    posts = 0
+
+    // A server slow enough that the first pass is still awaiting when the
+    // queue is stopped underneath it. `stopRateQueue` clears `inQuery` but
+    // cannot cancel that pass, so without an epoch the key queued below
+    // armed a second chain that ran alongside the first.
+    const slowFetch: any = async (uri: string, opts: any) => {
+      await new Promise(resolve => setTimeout(resolve, 200))
+      return await fakeFetch(uri, opts)
+    }
+
+    const first = rateFor('2024-03-01T00:00:00.000Z', slowFetch)
+    await new Promise(resolve => setTimeout(resolve, 50))
+    stopRateQueue()
+    // Settled rather than hanging: a stopped queue answers 0, which is what
+    // every caller of these helpers treats as "no rate".
+    expect(await first).toBe(0)
+
+    // And the module still works afterwards.
+    const second = await rateFor('2024-03-02T00:00:00.000Z')
+    expect(second).toBe(30000)
+  })
+})
diff --git a/src/util/exchangeRates.ts b/src/util/exchangeRates.ts
index 44b0351a0e3..3dd7747b0f8 100644
--- a/src/util/exchangeRates.ts
+++ b/src/util/exchangeRates.ts
@@ -109,6 +109,14 @@ let inQuery = false
  * independent of page size, and ~1s even when every rate was already cached.
  */
 let lastQueryEndedAt = 0
+/**
+ * Bumped by `stopRateQueue`, so a pass in flight can tell it is unwanted.
+ *
+ * Stopping the queue clears `inQuery` but cannot cancel a `doQuery` already
+ * awaiting a response. Without this, a key queued immediately after a stop
+ * armed a second chain that ran concurrently with the first.
+ */
+let queueEpoch = 0
 let queryTimer: ReturnType<typeof setTimeout> | undefined
 
 /**
@@ -138,6 +146,7 @@ interface RateQueryGroup {
 let numDoQuery = 0
 const doQuery = async (doFetch?: EdgeFetchFunction): Promise<void> => {
   const n = numDoQuery++
+  const epoch = queueEpoch
   clog(`${n} doQuery enter`)
 
   const groups = new Map<string, RateQueryGroup>()
@@ -260,7 +269,12 @@ const doQuery = async (doFetch?: EdgeFetchFunction): Promise<void> => {
   // during the round trip, which `addToQueue` deliberately does not arm a
   // second timer for. Each pass therefore removes at least the keys it asked
   // about, so this terminates.
-  if (resolverMap.size > 0) {
+  if (epoch !== queueEpoch) {
+    // The queue was stopped while this pass was in flight. Whatever is left
+    // was settled by `stopRateQueue`, and recursing would run a second chain
+    // alongside a queue that no longer wants one.
+    clog(`${n} doQuery abandoned: queue stopped`)
+  } else if (resolverMap.size > 0) {
     clog(`${n} Calling doQuery again`)
     await doQuery(doFetch)
   } else {
@@ -304,6 +318,19 @@ const addToQueue = (
     queryTimer = setTimeout(() => {
       queryTimer = undefined
       doQuery(doFetch).catch((error: unknown) => {
+        // Unlatch before reporting. `inQuery` is set above and the only
+        // place that cleared it was `doQuery`'s own terminal branch, so a
+        // rejection from anywhere outside its per-group `try` — building the
+        // groups, or stringifying the params — left it latched for the life
+        // of the process: every later arrival took the `!inQuery` false
+        // path, armed no timer, and never settled, because
+        // `getHistoricalRate` never calls its own `reject`. In the engine
+        // that is a `get-transactions` that hangs to the client's deadline,
+        // for ever, on a daemon documented as long-lived. One bad pass now
+        // costs one pass.
+        inQuery = false
+        lastQueryEndedAt = Date.now()
+        settleQueuedWithZero()
         onQueryError(error)
       })
     }, delay)
@@ -355,10 +382,25 @@ export function stopRateQueue(): void {
     queryTimer = undefined
   }
   inQuery = false
+  // So a pass already in flight does not recurse into another one after the
+  // queue has been stopped. It cannot be cancelled, but it can be told its
+  // work is no longer wanted: `doQuery` compares the epoch it started with.
+  queueEpoch++
   // So the next query after a stop is not throttled against a pass that
   // never ran. A test that stops the queue between cases wants the same
   // starting point each time.
   lastQueryEndedAt = 0
+  settleQueuedWithZero()
+}
+
+/**
+ * Settle every queued caller with `0` and empty the queue.
+ *
+ * `0` is what `getHistoricalRate` already answers for a rate the server
+ * cannot price, and what every caller of these helpers treats as "no rate",
+ * so it is the one value that cannot leave a promise hanging.
+ */
+function settleQueuedWithZero(): void {
   for (const [key, { resolvers }] of [...resolverMap.entries()]) {
     resolverMap.delete(key)
     resolvers.forEach(resolve => resolve(0))

From 4d9e25b69a3ed2460642020df86a5ab9038f1291 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 15:33:31 -0700
Subject: [PATCH 22/24] Remember an unpriced rate key for a few minutes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-performance.3.

A key the server answers for but cannot price is deliberately not cached:
storing `0` would answer `0` for the life of the process, long after the
rates server recovered. But nothing absorbed the repeat either, and the
engine does not persist `metadata.exchangeAmount`, so an asset with no feed
re-paid the entire fiat fill on every listing — measured against a stub
answering 200 with `rate` absent, a 1,200-transaction wallet cost 13
upstream requests and about a second on the first, second and third
listing alike, with the cache staying empty. Reachable on a hand-added
custom token, a long-tail token the server has no feed for, and dates
predating an asset's market, none of them rare on an old wallet.

Those keys now go in a short-lived negative cache instead, bounded and
cleared the same way as the rate cache. Five minutes is far longer than a
listing loop and far shorter than an outage, so a repeated listing is free
and a recovered server is still picked up. `engine-status` publishes
`rateUnpricedCount` beside `rateCachedCount`, so an asset with no feed is
visible rather than silent.

The test that asserted a zero is never cached now asserts what actually
matters: the zero never enters the rate cache, the repeat costs no request,
the TTL is minutes rather than hours, and clearing the cache forgets it.
---
 docs/api/dist/index.html                      |  7 ++
 docs/api/dist/openapi.json                    |  5 ++
 src/__tests__/util/exchangeRatesCache.test.ts | 26 ++++++-
 src/cli/engine/routes/status.ts               |  7 +-
 src/cli/generated/helpDocs.json               |  1 +
 src/util/exchangeRates.ts                     | 73 ++++++++++++++++++-
 6 files changed, 111 insertions(+), 8 deletions(-)

diff --git a/docs/api/dist/index.html b/docs/api/dist/index.html
index 32ffc2ad34c..7c9b903d922 100644
--- a/docs/api/dist/index.html
+++ b/docs/api/dist/index.html
@@ -220,6 +220,7 @@ <h4>Response <span class="st ok">200</span></h4>
   tcpPort: number | null
   socketPath: string
   rateCachedCount: number
+  rateUnpricedCount: number
   locale: string
   localeMatched: boolean
   decimalSeparator: string
@@ -235,6 +236,7 @@ <h4>Response <span class="st ok">200</span></h4>
   &quot;tcpPort&quot;: 0,
   &quot;socketPath&quot;: &quot;string&quot;,
   &quot;rateCachedCount&quot;: 1,
+  &quot;rateUnpricedCount&quot;: 1,
   &quot;locale&quot;: &quot;string&quot;,
   &quot;localeMatched&quot;: true,
   &quot;decimalSeparator&quot;: &quot;string&quot;,
@@ -285,6 +287,11 @@ <h4>Response <span class="st ok">200</span></h4>
   <td class="ty"><span class="t">number</span></td>
   <td class="doc">Exchange rates held in the engine’s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it.</td>
 </tr>
+<tr>
+  <td class="k"><code>rateUnpricedCount</code></td>
+  <td class="ty"><span class="t">number</span></td>
+  <td class="doc">Rate keys the server answered without a price, remembered for a few minutes so a repeated listing does not re-ask for every date. A number that stays high means an asset with no feed on the rates server — a hand-added custom token, a long-tail token, or dates predating its market.</td>
+</tr>
 <tr>
   <td class="k"><code>locale</code></td>
   <td class="ty"><span class="t">string</span></td>
diff --git a/docs/api/dist/openapi.json b/docs/api/dist/openapi.json
index 22dd1f10989..baa27aad2ad 100644
--- a/docs/api/dist/openapi.json
+++ b/docs/api/dist/openapi.json
@@ -185,6 +185,10 @@
                       "type": "number",
                       "description": "Exchange rates held in the engine’s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it."
                     },
+                    "rateUnpricedCount": {
+                      "type": "number",
+                      "description": "Rate keys the server answered without a price, remembered for a few minutes so a repeated listing does not re-ask for every date. A number that stays high means an asset with no feed on the rates server — a hand-added custom token, a long-tail token, or dates predating its market."
+                    },
                     "locale": {
                       "type": "string",
                       "description": "Language tag the engine resolved at boot."
@@ -212,6 +216,7 @@
                     "tcpPort",
                     "socketPath",
                     "rateCachedCount",
+                    "rateUnpricedCount",
                     "locale",
                     "localeMatched",
                     "decimalSeparator",
diff --git a/src/__tests__/util/exchangeRatesCache.test.ts b/src/__tests__/util/exchangeRatesCache.test.ts
index 640ad152451..166449e7e95 100644
--- a/src/__tests__/util/exchangeRatesCache.test.ts
+++ b/src/__tests__/util/exchangeRatesCache.test.ts
@@ -4,7 +4,8 @@ import {
   clearRateCache,
   getHistoricalCryptoRate,
   rateCacheSize,
-  stopRateQueue
+  stopRateQueue,
+  UNPRICED_TTL_MS
 } from '../../util/exchangeRates'
 
 // Real timers: the queue debounces by FETCH_FREQUENCY before it fetches.
@@ -95,15 +96,32 @@ describe('the module-level rate cache', () => {
     expect(rateCacheSize()).toBe(0)
   })
 
-  it('does not cache a zero, so one unpriced response is not permanent', async () => {
+  it('remembers an unpriced key briefly rather than for ever', async () => {
     clearRateCache()
     const date = '2019-03-03T04:00:00.000Z'
+    posts = 0
 
-    // The route publishes `0` for a rate the server cannot supply.
+    // The route publishes `0` for a rate the server cannot supply, and that
+    // never enters the rate cache: answering `0` for the life of the process
+    // would outlast any server outage.
     expect(await rateFor(date, unpricedFetch)).toBe(0)
     expect(rateCacheSize()).toBe(0)
+    expect(posts).toBe(1)
 
-    // A later pass against a recovered server therefore prices it.
+    // But the repeat is free. Nothing absorbed it before, so an asset the
+    // server has no feed for re-paid the whole fill on every listing — 13
+    // requests and about a second per listing on a 1,200-transaction wallet,
+    // for ever.
+    expect(await rateFor(date, unpricedFetch)).toBe(0)
+    expect(posts).toBe(1)
+
+    // Short enough to be a cache rather than an answer: minutes, so a
+    // recovered server is picked up well inside any session.
+    expect(UNPRICED_TTL_MS).toBeLessThanOrEqual(15 * 60_000)
+
+    // And forgotten with the rest of the cache, which the engine clears when
+    // the last session logs out.
+    clearRateCache()
     expect(await rateFor(date)).toBe(30000)
     expect(rateCacheSize()).toBe(1)
   })
diff --git a/src/cli/engine/routes/status.ts b/src/cli/engine/routes/status.ts
index c57da7feff0..a20cefa2623 100644
--- a/src/cli/engine/routes/status.ts
+++ b/src/cli/engine/routes/status.ts
@@ -9,7 +9,7 @@ import {
 } from 'cleaners'
 
 import { getAppliedLocale } from '../../../locales/bootLocale'
-import { rateCacheSize } from '../../../util/exchangeRates'
+import { rateCacheSize, rateUnpricedCount } from '../../../util/exchangeRates'
 import { API_VERSION } from '../apiVersion'
 import { doc } from '../doc'
 import { route } from '../route'
@@ -44,6 +44,10 @@ const asEngineStatus = asObject({
     asNumber,
     'Exchange rates held in the engine\u2019s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it.'
   ),
+  rateUnpricedCount: doc(
+    asNumber,
+    'Rate keys the server answered without a price, remembered for a few minutes so a repeated listing does not re-ask for every date. A number that stays high means an asset with no feed on the rates server \u2014 a hand-added custom token, a long-tail token, or dates predating its market.'
+  ),
   locale: doc(asString, 'Language tag the engine resolved at boot.'),
   localeMatched: doc(
     asBoolean,
@@ -98,6 +102,7 @@ export const engineStatus = route({
       tcpPort: state.tcpPort,
       socketPath: state.socketPath,
       rateCachedCount: rateCacheSize(),
+      rateUnpricedCount: rateUnpricedCount(),
       locale: applied.languageTag,
       localeMatched: applied.matched,
       decimalSeparator: applied.decimalSeparator,
diff --git a/src/cli/generated/helpDocs.json b/src/cli/generated/helpDocs.json
index 7edafb83f89..3f5a0e95e5f 100644
--- a/src/cli/generated/helpDocs.json
+++ b/src/cli/generated/helpDocs.json
@@ -1318,6 +1318,7 @@
         "tcpPort": "number | null — The loopback port, null unless started with `--tcp`.",
         "socketPath": "string — Unix socket the CLI connects to.",
         "rateCachedCount": "number — Exchange rates held in the engine’s process cache. It is bounded and cleared when the last session goes away, and this is how an operator sees it.",
+        "rateUnpricedCount": "number — Rate keys the server answered without a price, remembered for a few minutes so a repeated listing does not re-ask for every date. A number that stays high means an asset with no feed on the rates server — a hand-added custom token, a long-tail token, or dates predating its market.",
         "locale": "string — Language tag the engine resolved at boot.",
         "localeMatched": "boolean — Whether a translation table for that tag was actually found. False means the tag was accepted but the engine is answering in English, which is otherwise indistinguishable from a build that has the language.",
         "decimalSeparator": "string — Decimal mark for that locale.",
diff --git a/src/util/exchangeRates.ts b/src/util/exchangeRates.ts
index 3dd7747b0f8..74e64fa3c34 100644
--- a/src/util/exchangeRates.ts
+++ b/src/util/exchangeRates.ts
@@ -91,6 +91,27 @@ const RATE_CACHE_MAX = 20_000
 
 // A Map, for insertion-ordered eviction and a real `size`.
 const rateMap = new Map<string, number>()
+
+/**
+ * How long a key the server answered but could not price stays unpriceable.
+ *
+ * Not caching `0` is right — it would answer `0` for the life of the process,
+ * long after the rates server recovered — but nothing absorbed the repeat
+ * either, so an asset the server has no feed for re-paid the whole fill on
+ * every listing. Measured against a stub answering 200 with `rate` absent: a
+ * 1,200-transaction wallet cost 13 upstream requests and about a second on
+ * listing one, two and three alike, with the cache staying empty.
+ *
+ * Reachable on a hand-added custom token, a long-tail token with no feed, and
+ * dates predating an asset's market — none of them rare on an old wallet.
+ * Minutes is far longer than a listing loop and far shorter than a server
+ * outage, so a repeated listing is free and a recovered server is still
+ * picked up.
+ */
+export const UNPRICED_TTL_MS = 5 * 60_000
+
+/** Keys the server answered without a price, and when it said so. */
+const unpricedMap = new Map<string, number>()
 const resolverMap = new Map<
   string,
   {
@@ -239,10 +260,12 @@ const doQuery = async (doFetch?: EdgeFetchFunction): Promise<void> => {
           }
         }
 
-        // `0` means "the server could not price this", not a rate. Caching it
-        // would answer `0` for that key for the life of the process, long
-        // after the rates server recovered.
+        // `0` means "the server could not price this", not a rate, so it does
+        // not go in the rate cache — that would answer `0` for the life of
+        // the process. It goes in a short-lived negative cache instead, so a
+        // second listing of the same wallet does not re-ask for every date.
         if (rate !== 0) cacheRate(key, rate)
+        else noteUnpriced(key)
         clog(`${n} deleting ${key}`)
         resolverMap.delete(key)
         resolvers.forEach(r => r(rate))
@@ -345,6 +368,31 @@ const addToQueue = (
  * listing pages through dates in order, and the earliest are the ones least
  * likely to be asked for again.
  */
+/** Remember that the server answered this key without a price. */
+function noteUnpriced(key: string): void {
+  // Bounded like the rate cache, and by the same reasoning: a daemon that
+  // never exits would otherwise accumulate one entry per unpriceable date.
+  if (unpricedMap.size >= RATE_CACHE_MAX) {
+    for (const victim of [...unpricedMap.keys()].slice(
+      0,
+      RATE_CACHE_MAX >> 2
+    )) {
+      unpricedMap.delete(victim)
+    }
+  }
+  unpricedMap.set(key, Date.now())
+}
+
+/** Whether the server said recently that it cannot price this key. */
+function isRecentlyUnpriced(key: string): boolean {
+  const at = unpricedMap.get(key)
+  if (at == null) return false
+  if (Date.now() - at < UNPRICED_TTL_MS) return true
+  // Expired, so forget it rather than leaving it to the size bound.
+  unpricedMap.delete(key)
+  return false
+}
+
 function cacheRate(key: string, rate: number): void {
   if (!rateMap.has(key) && rateMap.size >= RATE_CACHE_MAX) {
     // A quarter at a time rather than one per insert, so a long listing does
@@ -365,6 +413,7 @@ function cacheRate(key: string, rate: number): void {
  */
 export function clearRateCache(): void {
   rateMap.clear()
+  unpricedMap.clear()
 }
 
 /**
@@ -412,6 +461,18 @@ export function rateCacheSize(): number {
   return rateMap.size
 }
 
+/**
+ * How many keys the server answered without a price.
+ *
+ * `engine-status` reports it as `rateUnpricedCount`. Worth publishing beside
+ * the cached count: an asset with no feed used to cost a full re-query on
+ * every listing with nothing to show for it, and the number is what makes
+ * that visible rather than silent.
+ */
+export function rateUnpricedCount(): number {
+  return unpricedMap.size
+}
+
 const createRateKey = (
   asset: { pluginId: string; tokenId?: EdgeTokenId } | string,
   targetFiat: string,
@@ -506,6 +567,12 @@ const getHistoricalRate = async (
   return await new Promise((resolve, reject) => {
     const rate = rateMap.get(rateKey)
     if (rate == null) {
+      if (isRecentlyUnpriced(rateKey)) {
+        // Answered already: the server has said it cannot price this key
+        // within the TTL, and asking again costs a round trip per date.
+        resolve(0)
+        return
+      }
       addToQueue(RatesParams, rateKey, resolve, maxQuerySize, doFetch)
       return
     }

From df4edb7763a40b5d19cf8ff7e436190ae770d163 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 22:43:58 -0700
Subject: [PATCH 23/24] Log a failed request, and bind the host a caller names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-servers.5 and 3.review-state.9.

The in-band error path never touched the logger. Anything `mapCoreError`
does not recognise becomes `500 INTERNAL_ERROR` carrying only
`error.message`, and `handleRequest`'s catch sent that and returned — no
stack, no route, no method. `server.ts` logged only what escaped
`handleRequest` itself, and `route.ts` logs response-shape drift, so the
daemon recorded a documentation bug but not an actual exception. For a
detached process whose one diagnostic surface is
`~/.edge-cli/logs/engine-<profile>.log`, a plugin or core fault was
unreproducible afterwards: the operator had the line the client printed,
and the client is often a script that discarded it. A 5xx now logs the
route, the code and the stack; a 4xx logs a line without one, since it is
the caller's doing. The response body is unchanged.

`--tcp-host=[::1]` was accepted and then answered nothing.
`allowedHostnamesFor` seeded its set from the raw string, so the set held
`[::1]`, while `hostnameOf` strips the brackets `URL` keeps — a caller's
`Host: [::1]:9008` arrived as `::1`, missed the set, and every request was
refused 403 with a message about DNS rebinding. `server.listen(port,
'[::1]')` would not have bound it as an address either. The unbracketed
form worked, which is what made the bracketed one a trap rather than an
obvious failure.

The validator moves to `tcpPort.ts`, beside the port one that exists for
the same "one spelling, both entries" reason, and canonicalises once. That
also makes it testable: `index.ts` runs `main()` at import, so the old
private function could not be reached from a test. The new suite pins the
pair that disagreed — whatever is bound must be in the allowed set under
the name a real `Host` header reduces to, which for IPv6 is always
bracketed.
---
 src/__tests__/cli/tcpHost.test.ts | 49 +++++++++++++++++++++++++++++++
 src/cli/engine/index.ts           | 40 ++++++++-----------------
 src/cli/engine/server.ts          | 21 +++++++++++++
 src/cli/engine/tcpPort.ts         | 32 ++++++++++++++++++++
 src/cli/engine/transportAuth.ts   |  2 +-
 5 files changed, 116 insertions(+), 28 deletions(-)
 create mode 100644 src/__tests__/cli/tcpHost.test.ts

diff --git a/src/__tests__/cli/tcpHost.test.ts b/src/__tests__/cli/tcpHost.test.ts
new file mode 100644
index 00000000000..0a2c8d3517d
--- /dev/null
+++ b/src/__tests__/cli/tcpHost.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { parseTcpHost } from '../../cli/engine/tcpPort'
+import { allowedHostnamesFor, hostnameOf } from '../../cli/engine/transportAuth'
+
+/**
+ * One spelling, everywhere.
+ *
+ * `--tcp-host=[::1]` was accepted and then answered nothing.
+ * `allowedHostnamesFor` seeded its set from the raw string, so the set held
+ * `[::1]`, while the `Host` header comparison strips the brackets `URL`
+ * keeps — so a caller's `Host: [::1]:9008` arrived as `::1`, missed the set,
+ * and every request was refused 403 with a message about DNS rebinding. The
+ * unbracketed form worked, which is what made the bracketed one a trap.
+ */
+describe('parseTcpHost', () => {
+  it('canonicalises a bracketed IPv6 literal', () => {
+    expect(parseTcpHost('[::1]')).toBe('::1')
+    expect(parseTcpHost('::1')).toBe('::1')
+  })
+
+  it('accepts the other loopback spellings unchanged', () => {
+    expect(parseTcpHost('localhost')).toBe('localhost')
+    expect(parseTcpHost('127.0.0.1')).toBe('127.0.0.1')
+    expect(parseTcpHost('127.0.0.53')).toBe('127.0.0.53')
+  })
+
+  it('refuses anything not loopback', () => {
+    // An engine reachable from the LAN exposes `get-raw-private-key` and
+    // `spend` to it, which no token makes safe to offer by accident.
+    for (const host of ['0.0.0.0', '10.0.0.1', '192.168.1.5', 'example.com']) {
+      expect(() => parseTcpHost(host)).toThrow(/loopback/)
+    }
+  })
+
+  it('agrees with what the Host header will look like', () => {
+    // The pair that disagreed. Whatever `parseTcpHost` returns has to be in
+    // the allowed set under the name a caller's `Host` header reduces to —
+    // and an IPv6 `Host` is always bracketed, whichever spelling was typed
+    // on the command line.
+    for (const typed of ['[::1]', '::1', 'localhost', '127.0.0.1']) {
+      const bound = parseTcpHost(typed)
+      const header = bound.includes(':') ? `[${bound}]:9008` : `${bound}:9008`
+      const allowed = allowedHostnamesFor(bound)
+      expect(hostnameOf(header)).not.toBeNull()
+      expect(allowed.has(hostnameOf(header) ?? '')).toBe(true)
+    }
+  })
+})
diff --git a/src/cli/engine/index.ts b/src/cli/engine/index.ts
index c1366c85134..92ec9048c9c 100644
--- a/src/cli/engine/index.ts
+++ b/src/cli/engine/index.ts
@@ -42,7 +42,7 @@ import { createRequestHandler, listenTcp, listenUnix } from './server'
 import { SessionStore } from './sessions'
 import { SHUTDOWN_DRAIN_MS } from './shutdownTiming'
 import { makeSweepTicker } from './sweepTicker'
-import { EXAMPLE_TCP_PORT, parseTcpPort } from './tcpPort'
+import { EXAMPLE_TCP_PORT, parseTcpHost, parseTcpPort } from './tcpPort'
 import { TESTER_SERVERS } from './testerServers'
 import {
   allowedHostnamesFor,
@@ -70,29 +70,6 @@ function requireNonEmpty(value: string, flag: string): string {
   return value
 }
 
-/**
- * Refuse a TCP bind address that is not loopback.
- *
- * `--tcp` opens an authenticated port for local scripts, and every surface
- * that describes it — the help text, `docs/EDGE_CLI.md`, the comment on the
- * listener — says `127.0.0.1`. Binding elsewhere publishes
- * `get-raw-private-key`, `get-pin` and `spend` to whatever network the host
- * is on, which no token makes safe to offer by accident.
- */
-function requireLoopback(host: string): string {
-  const loopback =
-    host === 'localhost' ||
-    host === '::1' ||
-    host === '[::1]' ||
-    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
-  if (!loopback) {
-    throw new EngineUsageError(
-      `--tcp-host must be a loopback address (127.0.0.0/8, ::1 or localhost), not "${host}": the TCP transport is for local scripts`
-    )
-  }
-  return host
-}
-
 /**
  * The `--idle-timeout` value, validated once for both spellings.
  *
@@ -258,9 +235,18 @@ function parseArgs(argv: string[]): EngineArgs {
       // same thing and was the bigger hole: the help text, the guide and this
       // code's own intent all say loopback, and an engine reachable from the
       // LAN exposes `get-raw-private-key` and `spend` to it.
-      args.tcpHost = requireLoopback(
-        requireNonEmpty(a.slice('--tcp-host='.length), '--tcp-host')
-      )
+      // The one place the spelling is canonicalised, shared with the port
+      // validator so neither entry can disagree about what is accepted.
+      try {
+        args.tcpHost = parseTcpHost(
+          requireNonEmpty(a.slice('--tcp-host='.length), '--tcp-host')
+        )
+      } catch (error: unknown) {
+        if (error instanceof RangeError) {
+          throw new EngineUsageError(error.message)
+        }
+        throw error
+      }
     } else if (a.startsWith('--idle-timeout=')) {
       args.idleTimeoutSeconds = parseIdleTimeout(
         a.slice('--idle-timeout='.length)
diff --git a/src/cli/engine/server.ts b/src/cli/engine/server.ts
index ab5e13dbab4..f72a3b60eb1 100644
--- a/src/cli/engine/server.ts
+++ b/src/cli/engine/server.ts
@@ -267,6 +267,27 @@ async function handleRequest(
   } catch (error: unknown) {
     if (res.writableEnded) return
     const { status, body } = toErrorBody(error)
+    // Logged before it is sent, because this path never touched the logger.
+    // Anything `mapCoreError` does not recognise becomes `500
+    // INTERNAL_ERROR` carrying only `error.message`, and for a detached
+    // daemon whose one diagnostic surface is
+    // `~/.edge-cli/logs/engine-<profile>.log` that made a plugin or core
+    // fault unreproducible after the fact: the operator had the single line
+    // the client printed, and the client is often a script that discarded
+    // it. The response body is unchanged.
+    const where = `${req.method ?? 'GET'} ${req.url ?? '/'}`
+    if (status >= 500) {
+      state.logger.error(`Request failed: ${where}`, {
+        code: body.error.code,
+        message: body.error.message,
+        stack: error instanceof Error ? error.stack : undefined
+      })
+    } else {
+      // A 4xx is the caller's doing, so it is worth seeing without a stack.
+      state.logger.warn(
+        `Request refused: ${where} ${body.error.code} ${body.error.message}`
+      )
+    }
     sendJson(res, status, body)
   } finally {
     state.idle.endRequest()
diff --git a/src/cli/engine/tcpPort.ts b/src/cli/engine/tcpPort.ts
index 98076a044f0..82ae34b5b37 100644
--- a/src/cli/engine/tcpPort.ts
+++ b/src/cli/engine/tcpPort.ts
@@ -39,3 +39,35 @@ export function parseTcpPort(raw: string | undefined): number | null {
   }
   return port
 }
+
+/**
+ * A `--tcp-host` value, canonicalised.
+ *
+ * Normalised here and nowhere else, so the bind address, the allowed-name set
+ * in `transportAuth` and the `Host` header comparison all speak one
+ * spelling. `--tcp-host=[::1]` used to be accepted and then answer nothing:
+ * `allowedHostnamesFor` seeded its set from the raw string, so the set held
+ * `[::1]`, while `hostnameOf` strips the brackets `URL` keeps — so a
+ * caller's `Host: [::1]:9008` arrived as `::1`, missed the set, and every
+ * request was refused 403 with a message about DNS rebinding.
+ * `server.listen(port, '[::1]')` would not have bound it as an address
+ * either, sending a bracketed literal through DNS resolution instead. The
+ * unbracketed form worked, which is what made the bracketed one a trap
+ * rather than an obvious failure.
+ *
+ * Loopback only: the TCP transport is for local scripts, and an engine
+ * reachable from the LAN exposes `get-raw-private-key` and `spend` to it.
+ */
+export function parseTcpHost(host: string): string {
+  const canonical = host.replace(/^\[|\]$/g, '')
+  const loopback =
+    canonical === 'localhost' ||
+    canonical === '::1' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(canonical)
+  if (!loopback) {
+    throw new RangeError(
+      `--tcp-host must be a loopback address (127.0.0.0/8, ::1 or localhost), not "${host}": the TCP transport is for local scripts`
+    )
+  }
+  return canonical
+}
diff --git a/src/cli/engine/transportAuth.ts b/src/cli/engine/transportAuth.ts
index 765bd371b01..8540811d02c 100644
--- a/src/cli/engine/transportAuth.ts
+++ b/src/cli/engine/transportAuth.ts
@@ -77,7 +77,7 @@ export function allowedHostnamesFor(host: string): Set<string> {
  * `::1` and a header with a path, userinfo or whitespace in it is refused
  * rather than partially matched.
  */
-function hostnameOf(hostHeader: string): string | null {
+export function hostnameOf(hostHeader: string): string | null {
   try {
     const url = new URL(`http://${hostHeader}`)
     if (url.hostname === '' || url.pathname !== '/' || url.username !== '') {

From 8be053a42837efeeaea3f5bc4989d6748c6ba052 Mon Sep 17 00:00:00 2001
From: Paul Puey <paul@edge.app>
Date: Fri, 2 Oct 2026 22:49:27 -0700
Subject: [PATCH 24/24] Make the export and error-detail checks able to fail
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3.review-tests.2 and 3.review-tests.3.

Seven export checks never opened a file. `ok()` asserts only `status === 0`
and the absence of an error body, and the client returns early when
`result.files == null`, so an engine that stopped assembling `files`, or a
`writeExportFiles` whose write were deleted, would have kept all seven
green. Four checks now read what was written: that `csv,qbo` produces
exactly `tx.csv` and `tx.qbo` and no extensionless `tx` — the only coverage
`exportFilePath`'s multi-format stem logic can get — that the QBO carries
`OFXHEADER:100` and is not trivially short, and that an empty wallet
exports an empty CSV.

That last one is asserted rather than fixed, deliberately. The CSV exporter
ends in `csvStringify(items, { header: true })`, and csv-stringify takes
its header from the first record's keys — so no records means no header and
a zero-byte file. It is the shared exporter the GUI uses, so emitting a
header row for an empty range would change the app's output and needs
explicit columns to do at all. Worth a decision, not a drive-by change.

The `details` half of the error-contract table could not fail.
`toHaveProperty(key)` passes for a key whose value is `undefined`, and
every arm builds `details` as a fixed object literal, so the key is always
there — the table held for a projection gutted to
`{ challengeId: undefined, challengeUri: undefined }`, which is the one
thing it existed to catch. It now carries the values core supplied and
asserts them with `toMatchObject`. `OTP_REQUIRED` listed three of its seven
fields and omitted `voucherAuth`, the second credential whose redaction
`redaction.test.ts` exists to pin, so the two halves of that guard never
met; the error is now constructed with all seven populated. Two swap-limit
cases listed one field each and in fact publish three.

`redaction.test.ts` reads its field list back out of `toErrorBody` instead
of copying it, so renaming a field in the arm fails one test or the other
rather than leaving both asserting a key nothing emits.
---
 scripts/testCliFake.ts              | 56 ++++++++++++++++++++++++++++
 src/__tests__/cli/errors.test.ts    | 57 ++++++++++++++++++++++-------
 src/__tests__/cli/redaction.test.ts | 34 +++++++++++------
 3 files changed, 122 insertions(+), 25 deletions(-)

diff --git a/scripts/testCliFake.ts b/scripts/testCliFake.ts
index 3932b0a55ff..60f4d2b3fed 100644
--- a/scripts/testCliFake.ts
+++ b/scripts/testCliFake.ts
@@ -120,6 +120,23 @@ function ok(label: string, ...args: string[]): Run {
  * pinned "the command failed" and nothing else, and a regression from
  * `INSUFFICIENT_FUNDS`/422 to `INTERNAL_ERROR`/500 kept the suite green.
  */
+/**
+ * Assert something the harness worked out for itself.
+ *
+ * `ok` and `refuses` both run a command and judge its output. Some checks
+ * are about what a command *left behind* — a file on disk, its first line —
+ * and those need an assertion of their own rather than another invocation.
+ */
+function check(label: string, condition: boolean, detail = ''): void {
+  if (condition) {
+    passes++
+    console.log(`OK   ${label}`)
+  } else {
+    failures++
+    console.error(`FAIL ${label}${detail !== '' ? ` — ${detail}` : ''}`)
+  }
+}
+
 function refuses(label: string, code: string, ...args: string[]): void {
   refusesInner(label, code, undefined, args)
 }
@@ -496,6 +513,45 @@ function main(): void {
       '--export-format=csv,qbo',
       `--out=${path.join(exportDir, 'tx')}`
     )
+    // Seven export checks and not one of them opened a file, so an engine
+    // that stopped assembling `files`, or a `writeExportFiles` whose
+    // `fs.writeFile` were deleted, would have kept all seven green: `ok()`
+    // asserts only `status === 0` and the absence of an error, and the
+    // client returns early when `result.files == null`.
+    //
+    // The wallet is empty in the fake world, which is what makes the two
+    // formats differ here: QBO always writes its envelope, and the CSV
+    // exporter ends in `csvStringify(items, { header: true })`, which takes
+    // its header from the first record's keys — so no records means no
+    // header and a zero-byte file. That is inherited from the shared
+    // exporter the GUI uses, not from the CLI, and is asserted rather than
+    // changed.
+    const exported = (name: string): string => {
+      const file = path.join(exportDir, name)
+      return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '<absent>'
+    }
+    check(
+      'a multi-format export writes exactly one file per format',
+      fs.existsSync(path.join(exportDir, 'tx.csv')) &&
+        fs.existsSync(path.join(exportDir, 'tx.qbo')) &&
+        !fs.existsSync(path.join(exportDir, 'tx')),
+      fs.readdirSync(exportDir).join(', ')
+    )
+    check(
+      'the QBO file carries its OFX header',
+      exported('tx.qbo').startsWith('OFXHEADER:100'),
+      exported('tx.qbo').slice(0, 60)
+    )
+    check(
+      'the QBO file is not empty',
+      exported('tx.qbo').length > 100,
+      String(exported('tx.qbo').length)
+    )
+    check(
+      'an empty wallet exports an empty CSV',
+      exported('tx.csv') === '',
+      JSON.stringify(exported('tx.csv').slice(0, 60))
+    )
     refuses(
       'an unknown export format',
       'USAGE',
diff --git a/src/__tests__/cli/errors.test.ts b/src/__tests__/cli/errors.test.ts
index e3d49aea53f..9c4f58f4748 100644
--- a/src/__tests__/cli/errors.test.ts
+++ b/src/__tests__/cli/errors.test.ts
@@ -58,8 +58,17 @@ const cases: Array<{
   code: string
   status: number
   error: unknown
-  /** Keys the arm promises in `details`. */
-  details?: string[]
+  /**
+   * The `details` the arm promises, with the values core supplied.
+   *
+   * Values rather than key names, because `toHaveProperty(key)` passes for a
+   * key whose value is `undefined` — and every arm builds `details` as a
+   * fixed object literal, so the key is always present. The old assertion
+   * therefore held for a projection gutted to
+   * `{ challengeId: undefined, challengeUri: undefined }`, which is the one
+   * thing it existed to catch.
+   */
+  details?: Record<string, unknown>
 }> = [
   {
     code: 'CHALLENGE_REQUIRED',
@@ -68,22 +77,41 @@ const cases: Array<{
       challengeId: 'cid',
       challengeUri: 'https://example.com/c'
     }),
-    details: ['challengeId', 'challengeUri']
+    details: { challengeId: 'cid', challengeUri: 'https://example.com/c' }
   },
   {
     code: 'PASSWORD_ERROR',
     status: 401,
     error: new PasswordError({ wait_seconds: 30 }),
     // The caller needs the wait to know when to retry.
-    details: ['wait']
+    details: { wait: 30 }
   },
   {
     code: 'OTP_REQUIRED',
     status: 401,
-    error: new OtpError({ otp_reset_auth: 'token', voucher_id: 'v' }),
-    // Seven fields, two of which are credentials the client redacts — see
-    // `redaction.test.ts`. The arm has to emit them for that to be possible.
-    details: ['reason', 'resetToken', 'voucherId']
+    // Every field populated, so all seven can be asserted by value. Three
+    // of them were listed before and four were not, and the one that
+    // mattered most was absent: `voucherAuth`, the second credential whose
+    // redaction `redaction.test.ts` exists to pin. The two halves of that
+    // guard did not meet.
+    error: new OtpError({
+      login_id: 'ZGVhZGJlZWY=',
+      otp_reset_auth: 'reset-token',
+      reason: 'ip',
+      otp_timeout_date: '2026-01-01T00:00:00.000Z',
+      voucher_activates: '2026-01-02T00:00:00.000Z',
+      voucher_auth: 'dm91Y2hlcg==',
+      voucher_id: 'v-1'
+    }),
+    details: {
+      reason: 'ip',
+      loginId: 'ZGVhZGJlZWY=',
+      resetDate: '2026-01-01T00:00:00.000Z',
+      resetToken: 'reset-token',
+      voucherId: 'v-1',
+      voucherAuth: 'dm91Y2hlcg==',
+      voucherActivates: '2026-01-02T00:00:00.000Z'
+    }
   },
   { code: 'USERNAME_ERROR', status: 400, error: new UsernameError() },
   {
@@ -110,13 +138,15 @@ const cases: Array<{
     code: 'SWAP_ABOVE_LIMIT',
     status: 422,
     error: new SwapAboveLimitError(swapInfo, '999'),
-    details: ['nativeMax']
+    // All three, not just the limit: a caller deciding what to do next needs
+    // to know which side of the trade and which plugin imposed it.
+    details: { direction: 'from', nativeMax: '999', swapPluginId: 'fakeswap' }
   },
   {
     code: 'SWAP_BELOW_LIMIT',
     status: 422,
     error: new SwapBelowLimitError(swapInfo, '1'),
-    details: ['nativeMin']
+    details: { direction: 'from', nativeMin: '1', swapPluginId: 'fakeswap' }
   },
   {
     code: 'SWAP_CURRENCY',
@@ -151,9 +181,10 @@ describe('toErrorBody', () => {
     '$code carries the details it promises',
     ({ details, error }) => {
       const { body } = toErrorBody(error)
-      for (const key of details ?? []) {
-        expect(body.error.details).toHaveProperty(key)
-      }
+      // `toMatchObject`, so a value core supplied has to arrive. `details`
+      // is published per code in the generated reference, and a caller
+      // branching on `resetToken` or `wait` needs the value, not the key.
+      expect(body.error.details).toMatchObject(details ?? {})
     }
   )
 
diff --git a/src/__tests__/cli/redaction.test.ts b/src/__tests__/cli/redaction.test.ts
index ee61e367fe1..5356c8fee47 100644
--- a/src/__tests__/cli/redaction.test.ts
+++ b/src/__tests__/cli/redaction.test.ts
@@ -6,10 +6,12 @@ import {
   it,
   jest
 } from '@jest/globals'
+import { OtpError } from 'edge-core-js'
 
 import { ApiClientError } from '../../cli/client/apiClient'
 import { EXIT } from '../../cli/client/exitCodes'
 import { printError } from '../../cli/client/output'
+import { toErrorBody } from '../../cli/engine/errors'
 
 let errors: string[]
 let spy: jest.SpiedFunction<typeof console.error>
@@ -67,18 +69,26 @@ describe('printError redaction', () => {
   })
 
   it('redacts every field OTP_REQUIRED carries that is a credential', () => {
-    // So the two sides cannot drift: each key the OTP arm emits is either
-    // redacted here or deliberately not. The list comes from
-    // `errors.ts`'s OTP_REQUIRED details projection.
-    const emitted = [
-      'reason',
-      'loginId',
-      'resetDate',
-      'resetToken',
-      'voucherId',
-      'voucherAuth',
-      'voucherActivates'
-    ]
+    // Derived from the arm itself, not copied from it. A hand-written list
+    // drifts silently: renaming a field in `errors.ts` would leave this
+    // asserting a key nothing emits any more, and the test would still
+    // pass. Reading the keys back out of `toErrorBody` means a rename fails
+    // here or in `errors.test.ts`, which is the point of having both.
+    const { body: emittedBody } = toErrorBody(
+      new OtpError({
+        login_id: 'ZGVhZGJlZWY=',
+        otp_reset_auth: 'reset-token',
+        reason: 'ip',
+        otp_timeout_date: '2026-01-01T00:00:00.000Z',
+        voucher_activates: '2026-01-02T00:00:00.000Z',
+        voucher_auth: 'dm91Y2hlcg==',
+        voucher_id: 'v-1'
+      })
+    )
+    const emitted = Object.keys(emittedBody.error.details ?? {})
+    // Seven today. Asserted so a projection that loses a field is a failure
+    // here rather than a quietly shorter loop below.
+    expect(emitted).toHaveLength(7)
     const secrets = ['resetToken', 'voucherAuth']
     const details: Record<string, unknown> = {}
     for (const key of emitted) details[key] = `value-of-${key}`