@reefclaw/openclaw-plugin 0.1.21 → 0.1.22

package/bridge/bridge.js

@@ -712,7 +712,10 @@ export class Bridge {
             }
             const kid = sealed.kid;
             return {
-                req: { sealed: sealed },
+                req: {
+                    sealed: sealed,
+                    ...(params?.confirm_venue_switch === true ? { confirm_venue_switch: true } : {}),
+                },
                 fp: `sealed:${typeof kid === 'string' ? kid.slice(0, 16) : 'unknown'}`,
             };
         }
@@ -720,35 +723,55 @@ export class Bridge {
         if (params?.venue === 'hyperliquid') {
             const walletAddress = typeof params?.walletAddress === 'string' ? params.walletAddress.trim() : '';
             const agentPrivateKey = typeof params?.agentPrivateKey === 'string' ? params.agentPrivateKey.trim() : '';
-            if (!/^0x[0-9a-fA-F]{40}$/.test(walletAddress)) {
-                this.connector.sendResponse(id, false, undefined, {
-                    code: 400,
-                    message: 'walletAddress must be your MASTER account address: 0x followed by 40 hex characters',
-                });
-                return null;
-            }
-            if (!/^(0x)?[0-9a-fA-F]{64}$/.test(agentPrivateKey)) {
-                this.connector.sendResponse(id, false, undefined, {
-                    code: 400,
-                    message: 'agentPrivateKey must be an agent (API) wallet private key: 64 hex characters (0x prefix optional)',
-                });
-                return null;
+            // Activation-only (both fields absent) = "switch back to Hyperliquid,
+            // my credentials are already stored" — the plugin resolves it against
+            // what is on disk and errors if nothing is stored.
+            const activationOnly = walletAddress === '' && agentPrivateKey === '';
+            if (!activationOnly) {
+                if (!/^0x[0-9a-fA-F]{40}$/.test(walletAddress)) {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 400,
+                        message: 'walletAddress must be your MASTER account address: 0x followed by 40 hex characters',
+                    });
+                    return null;
+                }
+                if (!/^(0x)?[0-9a-fA-F]{64}$/.test(agentPrivateKey)) {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 400,
+                        message: 'agentPrivateKey must be an agent (API) wallet private key: 64 hex characters (0x prefix optional)',
+                    });
+                    return null;
+                }
             }
             return {
-                req: { venue: 'hyperliquid', walletAddress, agentPrivateKey, testnet },
-                fp: fingerprint(walletAddress),
+                req: {
+                    venue: 'hyperliquid',
+                    ...(activationOnly ? {} : { walletAddress, agentPrivateKey }),
+                    testnet,
+                    ...(params?.confirm_venue_switch === true ? { confirm_venue_switch: true } : {}),
+                },
+                fp: activationOnly ? '(stored)' : fingerprint(walletAddress),
             };
         }
         const apiKey = typeof params?.apiKey === 'string' ? params.apiKey : '';
         const secret = typeof params?.secret === 'string' ? params.secret : '';
-        if (apiKey.length < 8 || secret.length < 8) {
+        const activationOnly = apiKey === '' && secret === '' && params?.venue === 'binance';
+        if (!activationOnly && (apiKey.length < 8 || secret.length < 8)) {
             this.connector.sendResponse(id, false, undefined, {
                 code: 400,
                 message: 'apiKey and secret must be at least 8 characters each',
             });
             return null;
         }
-        return { req: { venue: 'binance', apiKey, secret, testnet }, fp: fingerprint(apiKey) };
+        return {
+            req: {
+                venue: 'binance',
+                ...(activationOnly ? {} : { apiKey, secret }),
+                testnet,
+                ...(params?.confirm_venue_switch === true ? { confirm_venue_switch: true } : {}),
+            },
+            fp: activationOnly ? '(stored)' : fingerprint(apiKey),
+        };
     }
     /** Handle a set_exchange_credentials request. The secret value passes
      *  through once and is never cached or logged; only a redacted fingerprint
@@ -858,6 +881,7 @@ export class Bridge {
             walletAddress,
             testnet: params?.testnet === true,
             regenerate: params?.regenerate === true,
+            confirm_venue_switch: params?.confirm_venue_switch === true,
         });
         audit('hl_provision_agent_wallet.complete', {
             id,

package/bridge/provider.d.ts

@@ -9,16 +9,19 @@ import type { TradingMode } from '@reefclaw/shared';
  *  decryption. A discriminated union so a caller can never mix the shapes. */
 export type ExchangeCredentialsRequest = {
     venue: 'binance';
-    apiKey: string;
-    secret: string;
+    apiKey?: string;
+    secret?: string;
     testnet?: boolean;
+    confirm_venue_switch?: boolean;
 } | {
     venue: 'hyperliquid';
-    walletAddress: string;
-    agentPrivateKey: string;
+    walletAddress?: string;
+    agentPrivateKey?: string;
     testnet?: boolean;
+    confirm_venue_switch?: boolean;
 } | {
     sealed: Record<string, unknown>;
+    confirm_venue_switch?: boolean;
 };
 /** Result of hl_provision_agent_wallet — the box-generated agent wallet. */
 export interface HlProvisionOutcome {
@@ -32,6 +35,9 @@ export interface HlProvisionOutcome {
     masterMatches?: boolean;
     restartRequired?: boolean;
     mode: string;
+    requiresVenueSwitchConfirm?: boolean;
+    currentVenue?: string;
+    currentMode?: string;
 }
 /** Result of hl_agent_wallet_status — approval polling for the guided flow. */
 export interface HlAgentWalletStatusOutcome {
@@ -156,6 +162,11 @@ export interface OpenClawProvider {
         /** True when the stored venue differs from the booted venue — the
          *  operator must restart the agent before the change takes effect. */
         restartRequired?: boolean;
+        /** ok:false + this ⇒ the venue switch needs acknowledgement; retry with
+         *  confirm_venue_switch:true. */
+        requiresVenueSwitchConfirm?: boolean;
+        currentVenue?: string;
+        currentMode?: string;
     }>;
     /** Operator-only: verify exchange credentials with transient read-only
      *  calls, per venue. Nothing is persisted. */
@@ -180,6 +191,7 @@ export interface OpenClawProvider {
         walletAddress: string;
         testnet?: boolean;
         regenerate?: boolean;
+        confirm_venue_switch?: boolean;
     }): Promise<HlProvisionOutcome>;
     /** Operator-only: approval/balance status of the box's provisioned HL agent
      *  wallet (polled by the dashboard's guided flow after the wallet signature). */

package/bridge/providers/gateway.d.ts

@@ -227,6 +227,7 @@ export declare class GatewayProvider implements OpenClawProvider {
         walletAddress: string;
         testnet?: boolean;
         regenerate?: boolean;
+        confirm_venue_switch?: boolean;
     }): Promise<HlProvisionOutcome>;
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     getHlAgentWalletStatus(): Promise<HlAgentWalletStatusOutcome>;

package/bridge/providers/onboarding-commands.d.ts

@@ -22,6 +22,10 @@ export interface SetExchangeCredentialsOutcome {
     /** True when the stored venue differs from the booted venue — the operator
      *  must restart the agent before the change takes effect. */
     restartRequired?: boolean;
+    /** ok:false + this ⇒ retry with confirm_venue_switch:true after warning. */
+    requiresVenueSwitchConfirm?: boolean;
+    currentVenue?: string;
+    currentMode?: string;
 }
 export interface TestExchangeCredentialsOutcome {
     ok: boolean;
@@ -110,6 +114,7 @@ export declare function executeProvisionHlAgentWallet(ctx: OnboardingContext, ar
     walletAddress: string;
     testnet?: boolean;
     regenerate?: boolean;
+    confirm_venue_switch?: boolean;
 }): Promise<HlProvisionOutcome>;
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export declare function executeHlAgentWalletStatus(ctx: OnboardingContext): Promise<HlAgentWalletStatusOutcome>;

package/bridge/providers/onboarding-commands.js

@@ -43,12 +43,13 @@ export async function executeSetTradingMode(ctx, mode, acknowledged) {
  *  exactly once; the second return value is what must be scrubbed from any
  *  error text before it can be logged. */
 function credentialPayload(ctx, req) {
+    const confirm = req.confirm_venue_switch === true ? { confirm_venue_switch: true } : {};
     if ('sealed' in req) {
         // End-to-end encrypted envelope — forwarded opaquely; there is no
         // plaintext here to scrub (the empty scrub token never matches anything:
         // executeSet/Test guard on it before building a scrub regex).
         return {
-            payload: { sealed: req.sealed, operator_token: ctx.operatorToken },
+            payload: { sealed: req.sealed, ...confirm, operator_token: ctx.operatorToken },
             scrub: '',
         };
     }
@@ -59,9 +60,10 @@ function credentialPayload(ctx, req) {
                 walletAddress: req.walletAddress,
                 agentPrivateKey: req.agentPrivateKey,
                 testnet: req.testnet,
+                ...confirm,
                 operator_token: ctx.operatorToken,
             },
-            scrub: req.agentPrivateKey,
+            scrub: req.agentPrivateKey ?? '',
         };
     }
     return {
@@ -70,9 +72,10 @@ function credentialPayload(ctx, req) {
             apiKey: req.apiKey,
             secret: req.secret,
             testnet: req.testnet,
+            ...confirm,
             operator_token: ctx.operatorToken,
         },
-        scrub: req.secret,
+        scrub: req.secret ?? '',
     };
 }
 function scrubError(reason, scrub) {
@@ -240,6 +243,7 @@ export async function executeProvisionHlAgentWallet(ctx, args) {
             walletAddress: args.walletAddress,
             testnet: args.testnet,
             regenerate: args.regenerate,
+            ...(args.confirm_venue_switch === true ? { confirm_venue_switch: true } : {}),
             operator_token: ctx.operatorToken,
         });
         return result.data;

package/config/plugin-config-io.d.ts

@@ -1,4 +1,5 @@
 import type { TradingMode, ExchangeConfig } from '../types.js';
+type VenueId = 'binance' | 'hyperliquid';
 /** The connection the AGENT saves during onboarding lives in OpenClaw's own
  *  config (`skills.entries.reefclaw.config` in ~/.openclaw/openclaw.json) —
  *  the connector reads it there, and since the chat-install flow never writes
@@ -231,6 +232,31 @@ export declare function readPluginConfig(path?: string): PluginConfigFile;
  *  on the next successful write.
  */
 export declare function updatePluginConfig(patch: Partial<PluginConfigFile>, path?: string): PluginConfigFile;
+/** Which credential fields belong to which venue. They do NOT collide, so one
+ *  flat `exchange` block can hold both venues at once and `venue` selects the
+ *  active one (every reader — boot, set_trading_mode, the adapters — already
+ *  reads only the active venue's fields). */
+export declare const VENUE_CREDENTIAL_FIELDS: Readonly<Record<VenueId, readonly (keyof ExchangeConfig)[]>>;
+/** True when `exchange` holds a usable credential set for `venue`. */
+export declare function hasCredentialsForVenue(exchange: ExchangeConfig | undefined, venue: VenueId): boolean;
+/**
+ * Build the `exchange` block for activating `venue`, PRESERVING every setting
+ * already configured for the other venue.
+ *
+ * ★ Why this exists: `updatePluginConfig` replaces `exchange` wholesale (its
+ * documented contract — `exchange: null` is how credentials are cleared), so
+ * storing Hyperliquid credentials used to DELETE the Binance key/secret and
+ * vice versa. A trader who runs both venues then had to re-enter keys on every
+ * switch, and a live Binance box could silently lose its credentials while
+ * setting up Hyperliquid. Operator decision (2026-08-02): switching venues
+ * must be a warn-and-confirm, never a data-losing action.
+ *
+ * `credentials` carries only the incoming venue's fields; omit them entirely to
+ * ACTIVATE a venue whose credentials are already stored (the one-click
+ * switch-back). `testnet` falls back to that venue's remembered flag.
+ */
+export declare function buildVenueExchangeConfig(existing: ExchangeConfig | undefined, venue: VenueId, credentials: Partial<ExchangeConfig>, testnet?: boolean): ExchangeConfig;
 /** Redact a credential for logging — keeps first 4 and last 2 chars.
  *  Never log the full key/secret. */
 export declare function redactCredential(value: string | undefined | null): string;
+export {};

package/config/plugin-config-io.js

@@ -144,6 +144,53 @@ export function updatePluginConfig(patch, path = defaultConfigPath()) {
     renameSync(tmpPath, path);
     return merged;
 }
+/** Which credential fields belong to which venue. They do NOT collide, so one
+ *  flat `exchange` block can hold both venues at once and `venue` selects the
+ *  active one (every reader — boot, set_trading_mode, the adapters — already
+ *  reads only the active venue's fields). */
+export const VENUE_CREDENTIAL_FIELDS = {
+    binance: ['apiKey', 'secret'],
+    hyperliquid: ['walletAddress', 'agentPrivateKey'],
+};
+/** True when `exchange` holds a usable credential set for `venue`. */
+export function hasCredentialsForVenue(exchange, venue) {
+    if (!exchange)
+        return false;
+    return VENUE_CREDENTIAL_FIELDS[venue].every((f) => {
+        const v = exchange[f];
+        return typeof v === 'string' && v.length > 0;
+    });
+}
+/**
+ * Build the `exchange` block for activating `venue`, PRESERVING every setting
+ * already configured for the other venue.
+ *
+ * ★ Why this exists: `updatePluginConfig` replaces `exchange` wholesale (its
+ * documented contract — `exchange: null` is how credentials are cleared), so
+ * storing Hyperliquid credentials used to DELETE the Binance key/secret and
+ * vice versa. A trader who runs both venues then had to re-enter keys on every
+ * switch, and a live Binance box could silently lose its credentials while
+ * setting up Hyperliquid. Operator decision (2026-08-02): switching venues
+ * must be a warn-and-confirm, never a data-losing action.
+ *
+ * `credentials` carries only the incoming venue's fields; omit them entirely to
+ * ACTIVATE a venue whose credentials are already stored (the one-click
+ * switch-back). `testnet` falls back to that venue's remembered flag.
+ */
+export function buildVenueExchangeConfig(existing, venue, credentials, testnet) {
+    const next = { ...(existing ?? {}), venue };
+    for (const field of VENUE_CREDENTIAL_FIELDS[venue]) {
+        const incoming = credentials[field];
+        if (typeof incoming === 'string' && incoming.length > 0) {
+            // Assigning through the union needs a cast; every field is string-typed.
+            next[field] = incoming;
+        }
+    }
+    const resolvedTestnet = testnet ?? existing?.testnetByVenue?.[venue] ?? (existing?.venue === venue ? existing?.testnet : undefined) ?? false;
+    next.testnet = resolvedTestnet;
+    next.testnetByVenue = { ...(existing?.testnetByVenue ?? {}), [venue]: resolvedTestnet };
+    return next;
+}
 /** Redact a credential for logging — keeps first 4 and last 2 chars.
  *  Never log the full key/secret. */
 export function redactCredential(value) {

package/index.js

@@ -807,6 +807,7 @@ const TOOL_PARAMS = {
             walletAddress: { type: 'string', description: 'Hyperliquid MASTER account address 0x… (venue=hyperliquid; never a private key)' },
             agentPrivateKey: { type: 'string', description: 'Hyperliquid AGENT (API) wallet private key — signs only, cannot withdraw (venue=hyperliquid)' },
             testnet: { type: 'boolean', description: 'Use the venue testnet (default: false)' },
+            confirm_venue_switch: { type: 'boolean', description: 'Acknowledge switching this agent to another venue while it is configured live on the current one. Credentials for both venues are kept either way.' },
             sealed: { type: 'object', description: 'End-to-end encrypted credential envelope from the dashboard (replaces the plaintext fields; only this box can open it)' },
         },
     },
@@ -839,6 +840,7 @@ const TOOL_PARAMS = {
             walletAddress: { type: 'string', description: 'Hyperliquid MASTER account address 0x… the agent wallet will trade for (public; never a private key)' },
             testnet: { type: 'boolean', description: 'Provision for the Hyperliquid testnet (default: false)' },
             regenerate: { type: 'boolean', description: 'Replace an existing agent wallet with a fresh key (PAPER mode only; the old approval is orphaned)' },
+            confirm_venue_switch: { type: 'boolean', description: 'Acknowledge switching this agent to Hyperliquid while it is configured live on another venue. Credentials for both venues are kept either way.' },
         },
     },
     hl_agent_wallet_status: {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "ReefClaw supervised trading plugin for OpenClaw. Runs entirely on YOUR machine and starts in PAPER mode \u00e2\u20ac\u201d it cannot trade real funds until you supply exchange credentials and walk the PAPER\u00e2\u2020\u2019MICRO_LIVE\u00e2\u2020\u2019LIVE ladder yourself from the ReefClaw dashboard (the agent cannot make that change; it is refused without operator provenance). Your exchange API keys stay on your machine to sign requests to the exchange and are NEVER sent to ReefClaw \u00e2\u20ac\u201d a test in the package asserts this. What does reach ReefClaw is trading telemetry for the dashboard (positions, fills, decision journal). Live trading always carries exchange-native protective stops. Trading instructions can be updated remotely, and every update must carry a valid Ed25519 signature verified against a key pinned in this build before it is applied. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",

package/tools/hl-provision-agent-wallet.d.ts

@@ -1,12 +1,15 @@
 import type { PluginRuntime } from '../onboarding/runtime.js';
 import type { TradingMode } from '../types.js';
-import type { VenueId } from '../venues/registry.js';
+import { type VenueId } from '../venues/registry.js';
 export interface HlProvisionAgentWalletArgs {
     /** MASTER account address (public, 0x…) the agent wallet will trade for. */
     walletAddress?: string;
     testnet?: boolean;
     /** Mint a fresh key even when one exists (PAPER mode only). */
     regenerate?: boolean;
+    /** Acknowledges switching this agent away from a live venue (Binance
+     *  credentials are PRESERVED either way — see buildVenueExchangeConfig). */
+    confirm_venue_switch?: boolean;
 }
 export interface HlProvisionAgentWalletResult {
     ok: boolean;
@@ -24,6 +27,11 @@ export interface HlProvisionAgentWalletResult {
     /** True when the boot venue differs — restart applies the venue. */
     restartRequired?: boolean;
     mode: TradingMode;
+    /** Set with ok:false when switching away from a live venue needs explicit
+     *  acknowledgement. Retry with confirm_venue_switch:true. */
+    requiresVenueSwitchConfirm?: boolean;
+    currentVenue?: VenueId;
+    currentMode?: TradingMode;
 }
 export interface HlProvisionAgentWalletDeps {
     runtime: PluginRuntime;

package/tools/hl-provision-agent-wallet.js

@@ -27,8 +27,9 @@
 // Security: the private key exists only in this process's memory between
 // generation and the config write. It is never logged, never in the result,
 // never egressed (credential-no-egress.test.ts pins this module).
-import { readPluginConfig, updatePluginConfig, redactCredential } from '../config/plugin-config-io.js';
+import { buildVenueExchangeConfig, hasCredentialsForVenue, readPluginConfig, redactCredential, updatePluginConfig, } from '../config/plugin-config-io.js';
 import { deriveAddressFromPrivateKey, generateAgentPrivateKey, isHexAddress, } from '../venues/hyperliquid/hl-agent-wallet.js';
+import { parseVenue } from '../venues/registry.js';
 import { logger } from '../logger.js';
 const TAG = 'hl-provision-agent-wallet';
 export async function hlProvisionAgentWalletTool(args, deps) {
@@ -49,17 +50,48 @@ export async function hlProvisionAgentWalletTool(args, deps) {
     let existingKey = null;
     let existingMaster = null;
     let existingTestnet = false;
+    let existingExchange;
+    let existingMode;
     try {
         const cfg = readPluginConfig(deps.configPath);
-        if (cfg.exchange?.venue === 'hyperliquid' && typeof cfg.exchange.agentPrivateKey === 'string') {
+        existingExchange = cfg.exchange;
+        existingMode = cfg.tradingMode;
+        // An HL wallet counts as provisioned whenever the key is present — even if
+        // the ACTIVE venue is binance (both venues' credentials coexist now), so a
+        // trader who set up HL, switched back to Binance, and returns resumes their
+        // existing agent wallet instead of silently minting a second one.
+        if (typeof cfg.exchange?.agentPrivateKey === 'string') {
             existingKey = cfg.exchange.agentPrivateKey;
             existingMaster = typeof cfg.exchange.walletAddress === 'string' ? cfg.exchange.walletAddress : null;
-            existingTestnet = cfg.exchange.testnet === true;
+            existingTestnet = cfg.exchange.testnetByVenue?.hyperliquid ?? cfg.exchange.testnet === true;
         }
     }
     catch {
         // Unreadable config — treat as fresh.
     }
+    // Warn-and-confirm before switching a live Binance box onto Hyperliquid.
+    // Credentials are preserved either way; what needs acknowledging is that
+    // after the restart this agent stops managing the other venue's book.
+    const fromVenue = parseVenue(existingExchange?.venue).venue;
+    const persistedMode = existingMode ?? 'PAPER';
+    if (fromVenue !== 'hyperliquid' &&
+        hasCredentialsForVenue(existingExchange, fromVenue) &&
+        persistedMode !== 'PAPER' &&
+        args.confirm_venue_switch !== true) {
+        return {
+            ok: false,
+            message: `This agent is configured for ${fromVenue} in ${persistedMode} mode. Setting up Hyperliquid means ` +
+                `that after the restart it will trade Hyperliquid and STOP managing anything open on ${fromVenue} — ` +
+                `positions there stay open on the exchange with their protective stops, but this agent will not ` +
+                `monitor or close them. Your ${fromVenue} credentials are KEPT, so you can switch back at any time. ` +
+                `Confirm to proceed.`,
+            venue: 'hyperliquid',
+            mode,
+            requiresVenueSwitchConfirm: true,
+            currentVenue: fromVenue,
+            currentMode: persistedMode,
+        };
+    }
     if (existingKey && args.regenerate !== true) {
         const derived = await deriveAddressFromPrivateKey(existingKey);
         if (derived.ok) {
@@ -107,12 +139,9 @@ export async function hlProvisionAgentWalletTool(args, deps) {
             mode,
         };
     }
-    const exchange = {
-        venue: 'hyperliquid',
-        walletAddress,
-        agentPrivateKey,
-        testnet,
-    };
+    // Merge, never replace: a Binance key/secret already on this box survives
+    // (the trader can switch back without re-entering anything).
+    const exchange = buildVenueExchangeConfig(existingExchange, 'hyperliquid', { walletAddress, agentPrivateKey }, testnet);
     try {
         updatePluginConfig({ exchange }, deps.configPath);
     }

package/tools/set-exchange-credentials.d.ts

@@ -10,6 +10,9 @@ export interface SetExchangeCredentialsArgs {
     walletAddress?: string;
     agentPrivateKey?: string;
     testnet?: boolean;
+    /** Acknowledges a consequential venue switch (see venueSwitchNeedsConfirm).
+     *  The dashboard sets this after showing the operator what changes. */
+    confirm_venue_switch?: boolean;
     /** End-to-end encrypted envelope from the dashboard (sealed-credentials.ts).
      *  When present it is the SOLE source of the credential fields — any
      *  plaintext siblings are ignored, so a mixed payload can't smuggle values
@@ -37,6 +40,13 @@ export interface SetExchangeCredentialsResult {
     /** True when the stored venue differs from the booted venue — the operator
      *  must restart the agent before the change takes effect. */
     restartRequired?: boolean;
+    /** Set with ok:false when a venue switch needs explicit acknowledgement.
+     *  Retry the same call with confirm_venue_switch:true to proceed. */
+    requiresVenueSwitchConfirm?: boolean;
+    /** Venue currently configured on the box (only with the confirm request). */
+    currentVenue?: VenueId;
+    /** Trading mode currently persisted (only with the confirm request). */
+    currentMode?: TradingMode;
 }
 export interface SetExchangeCredentialsDeps {
     runtime: PluginRuntime;

package/tools/set-exchange-credentials.js

@@ -28,7 +28,7 @@
 //     to store it when it equals the master walletAddress — that means the user
 //     pasted their MASTER private key, the one mistake that must never reach
 //     disk. Fail-open when derivation infra is unavailable (never block on it).
-import { updatePluginConfig, redactCredential } from '../config/plugin-config-io.js';
+import { buildVenueExchangeConfig, hasCredentialsForVenue, readPluginConfig, redactCredential, updatePluginConfig, } from '../config/plugin-config-io.js';
 import { deriveAddressFromPrivateKey, isHexAddress, isHexPrivateKey, normalizeHexPrivateKey, sameAddress, } from '../venues/hyperliquid/hl-agent-wallet.js';
 import { parseVenue } from '../venues/registry.js';
 import { unsealCredentials, SealedEnvelopeError } from '../security/sealed-credentials.js';
@@ -84,6 +84,28 @@ function validateHyperliquid(args) {
     }
     return null;
 }
+/** True when the caller supplied no credential fields for `venue` — the
+ *  "just switch me back, my keys are already saved" path. */
+function isActivationOnly(args, venue) {
+    const fields = venue === 'hyperliquid'
+        ? [args.walletAddress, args.agentPrivateKey]
+        : [args.apiKey, args.secret];
+    return fields.every((f) => f === undefined || (typeof f === 'string' && f.trim().length === 0));
+}
+/**
+ * Venue switches are a warn-and-confirm, never a block (operator decision
+ * 2026-08-02: traders run both venues and must be able to move between them).
+ * We ask for confirmation only when the switch has real consequences: the box
+ * holds credentials for the venue being left AND is configured for a live
+ * mode, i.e. there may be a real book on the other exchange that this agent
+ * will stop managing after the restart. PAPER→anything switches silently.
+ */
+function venueSwitchNeedsConfirm(cfg, target) {
+    const from = parseVenue(cfg.exchange?.venue).venue;
+    const mode = cfg.tradingMode ?? 'PAPER';
+    const needed = from !== target && hasCredentialsForVenue(cfg.exchange, from) && mode !== 'PAPER';
+    return { needed, from, mode };
+}
 export async function setExchangeCredentialsTool(rawArgs, deps) {
     const resolved = resolveSealedArgs(rawArgs, deps.transportKeyDir);
     if ('error' in resolved) {
@@ -92,13 +114,61 @@ export async function setExchangeCredentialsTool(rawArgs, deps) {
     const args = resolved.args;
     const venue = parseVenue(args.venue).venue;
     const bootVenue = deps.bootVenue ?? 'binance';
-    const validationError = venue === 'hyperliquid' ? validateHyperliquid(args) : validateBinance(args);
+    // Read once: needed for the switch gate AND to preserve the other venue's
+    // settings (the block is merged, never replaced — see buildVenueExchangeConfig).
+    let existing;
+    let existingMode;
+    try {
+        const cfg = readPluginConfig(deps.configPath);
+        existing = cfg.exchange;
+        existingMode = cfg.tradingMode;
+    }
+    catch {
+        // Unreadable/absent config — treat as a fresh box.
+    }
+    // Activation-only: no credentials supplied, but this venue already has some
+    // stored → the operator is switching back to a venue they configured before.
+    const activationOnly = isActivationOnly(args, venue);
+    if (activationOnly && !hasCredentialsForVenue(existing, venue)) {
+        return fail(venue === 'hyperliquid'
+            ? 'No Hyperliquid credentials are stored yet — provide walletAddress + agentPrivateKey (or use the guided setup).'
+            : 'No Binance credentials are stored yet — provide apiKey + secret.', '(not-set)', deps, venue);
+    }
+    const validationError = activationOnly
+        ? null
+        : venue === 'hyperliquid'
+            ? validateHyperliquid(args)
+            : validateBinance(args);
     if (validationError) {
         return fail(validationError, '(not-set)', deps, venue);
     }
+    // Warn-and-confirm on a consequential venue switch (never a hard block).
+    const gate = venueSwitchNeedsConfirm({ exchange: existing, tradingMode: existingMode }, venue);
+    if (gate.needed && args.confirm_venue_switch !== true) {
+        return {
+            ok: false,
+            message: `This agent is configured for ${gate.from} in ${gate.mode} mode. Switching it to ${venue} means ` +
+                `that after the restart it will trade ${venue} and STOP managing anything open on ${gate.from} — ` +
+                `positions there stay open on the exchange with their protective stops, but this agent will not ` +
+                `monitor or close them. Your ${gate.from} credentials are KEPT, so you can switch back at any time. ` +
+                `Confirm to proceed.`,
+            fingerprint: '(not-set)',
+            reconnected: false,
+            mode: deps.runtime.mode,
+            readiness: deps.runtime.adapter.readiness,
+            venue,
+            requiresVenueSwitchConfirm: true,
+            currentVenue: gate.from,
+            currentMode: gate.mode,
+        };
+    }
     let exchange;
     let fingerprint;
-    if (venue === 'hyperliquid') {
+    if (activationOnly) {
+        exchange = buildVenueExchangeConfig(existing, venue, {}, args.testnet);
+        fingerprint = redactCredential(venue === 'hyperliquid' ? (exchange.walletAddress ?? '') : (exchange.apiKey ?? ''));
+    }
+    else if (venue === 'hyperliquid') {
         const walletAddress = args.walletAddress.trim();
         const agentPrivateKey = normalizeHexPrivateKey(args.agentPrivateKey);
         // The one unrecoverable mistake: the pasted "agent key" controls the MASTER
@@ -113,26 +183,25 @@ export async function setExchangeCredentialsTool(rawArgs, deps) {
         if (!derived.ok && derived.reason === 'invalid_key') {
             return fail('agentPrivateKey is not a valid secp256k1 private key — re-copy it from the Hyperliquid API page', redactCredential(walletAddress), deps, venue);
         }
-        exchange = {
-            venue: 'hyperliquid',
-            walletAddress,
-            agentPrivateKey,
-            testnet: args.testnet ?? false,
-        };
+        exchange = buildVenueExchangeConfig(existing, 'hyperliquid', { walletAddress, agentPrivateKey }, args.testnet);
         // The master ADDRESS is public (it identifies the account on-chain) — safe
         // as a fingerprint; the agent key never appears anywhere.
         fingerprint = redactCredential(walletAddress);
     }
-    else {
+    else if (args.venue === undefined && existing === undefined) {
+        // Legacy caller on a fresh box: keep the historical on-disk shape exactly
+        // (no `venue`, no `testnetByVenue`) so pre-venue installs are byte-identical.
         exchange = {
-            // Legacy callers omit `venue`; keep their on-disk shape byte-identical.
-            ...(args.venue !== undefined ? { venue: 'binance' } : {}),
             apiKey: args.apiKey.trim(),
             secret: args.secret.trim(),
             testnet: args.testnet ?? false,
         };
         fingerprint = redactCredential(exchange.apiKey);
     }
+    else {
+        exchange = buildVenueExchangeConfig(existing, 'binance', { apiKey: args.apiKey.trim(), secret: args.secret.trim() }, args.testnet);
+        fingerprint = redactCredential(exchange.apiKey);
+    }
     try {
         updatePluginConfig({ exchange }, deps.configPath);
     }

package/types.d.ts

@@ -130,4 +130,10 @@ export interface ExchangeConfig {
     testnet?: boolean;
     walletAddress?: string;
     agentPrivateKey?: string;
+    /** Per-venue testnet memo. `testnet` above is the ACTIVE venue's flag (what
+     *  boot reads); this remembers the OTHER venue's setting so switching back
+     *  restores it instead of inheriting the flag from whichever venue was
+     *  configured last. Traders run both venues and switch between them — a
+     *  switch must never lose a configured setting. */
+    testnetByVenue?: Partial<Record<'binance' | 'hyperliquid', boolean>>;
 }