@reefclaw/openclaw-plugin 0.1.21 → 0.1.23

package/bridge/bridge.js

@@ -505,6 +505,44 @@ export class Bridge {
                 }
                 return;
             }
+            if (method === 'hl_submit_agent_approval') {
+                const provider = this.provider;
+                if (!provider.submitHlAgentApproval) {
+                    this.connector.sendResponse(id, true, {
+                        ok: false,
+                        message: 'Provider does not support hl_submit_agent_approval (likely mock provider)',
+                    });
+                    return;
+                }
+                const action = params?.action;
+                const nonce = params?.nonce;
+                const signature = params?.signature;
+                if (!action || typeof action !== 'object' ||
+                    typeof nonce !== 'number' ||
+                    !signature || typeof signature.r !== 'string' || typeof signature.s !== 'string' ||
+                    typeof signature.v !== 'number') {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 400,
+                        message: 'hl_submit_agent_approval requires { action, nonce, signature:{r,s,v} }',
+                    });
+                    return;
+                }
+                // The plugin re-validates strictly (approveAgent only, own agent
+                // address only) — this layer just shape-checks and forwards.
+                audit('hl_submit_agent_approval.start', {
+                    id,
+                    chain: action.hyperliquidChain,
+                    agentAddress: action.agentAddress,
+                });
+                const outcome = await provider.submitHlAgentApproval({
+                    action: action,
+                    nonce,
+                    signature: { r: signature.r, s: signature.s, v: signature.v },
+                });
+                audit('hl_submit_agent_approval.complete', { id, ok: outcome.ok, hlStatus: outcome.hlStatus });
+                this.connector.sendResponse(id, true, outcome);
+                return;
+            }
             if (method === 'hl_agent_wallet_status') {
                 const provider = this.provider;
                 if (!provider.getHlAgentWalletStatus) {
@@ -712,7 +750,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 +761,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 +919,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/gateway/tool-discovery.d.ts

@@ -3,7 +3,7 @@ import { GatewayHttpClient, GatewayHttpError } from './gateway-http-client.js';
  * Logical tool names used by ReefClaw internally.
  * Each maps to one or more candidate actual tool names on the gateway.
  */
-export type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | 'set_trading_mode' | 'set_exchange_credentials' | 'test_exchange_credentials' | 'clear_exchange_credentials' | 'hl_provision_agent_wallet' | 'hl_agent_wallet_status' | 'get_bracket_config' | 'set_bracket_requirement';
+export type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | 'set_trading_mode' | 'set_exchange_credentials' | 'test_exchange_credentials' | 'clear_exchange_credentials' | 'hl_provision_agent_wallet' | 'hl_agent_wallet_status' | 'hl_submit_agent_approval' | 'get_bracket_config' | 'set_bracket_requirement';
 /**
  * Build the test args used when probing each logical tool.
  *

package/bridge/gateway/tool-discovery.js

@@ -22,6 +22,7 @@ const OPTIONAL_TOOLS = [
     'clear_exchange_credentials',
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
 ];
@@ -48,6 +49,7 @@ const CANDIDATES = {
     clear_exchange_credentials: ['clear_exchange_credentials'],
     hl_provision_agent_wallet: ['hl_provision_agent_wallet'],
     hl_agent_wallet_status: ['hl_agent_wallet_status'],
+    hl_submit_agent_approval: ['hl_submit_agent_approval'],
     get_bracket_config: ['get_bracket_config'],
     set_bracket_requirement: ['set_bracket_requirement'],
 };
@@ -119,6 +121,8 @@ export function buildProbeArgs(symbol = DEFAULT_PROBE_SYMBOL) {
         // timeout and mark the tool missing forever).
         hl_provision_agent_wallet: { walletAddress: '' },
         hl_agent_wallet_status: { probe: true },
+        // Same dedicated probe path: a real submit would POST to Hyperliquid.
+        hl_submit_agent_approval: { probe: true },
         // Bracket-config probes: no-arg read; set with an invalid flag triggers early-return.
         get_bracket_config: {},
         set_bracket_requirement: { flag: '__probe__', value: false },

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,18 @@ export interface HlProvisionOutcome {
     masterMatches?: boolean;
     restartRequired?: boolean;
     mode: string;
+    requiresVenueSwitchConfirm?: boolean;
+    currentVenue?: string;
+    currentMode?: string;
+}
+/** Result of hl_submit_agent_approval — the box relays the wallet-signed
+ *  approveAgent action to Hyperliquid (browsers are often blocked). */
+export interface HlSubmitApprovalOutcome {
+    ok: boolean;
+    message: string;
+    hlStatus?: string;
+    chain?: string;
+    agentAddress?: string;
 }
 /** Result of hl_agent_wallet_status — approval polling for the guided flow. */
 export interface HlAgentWalletStatusOutcome {
@@ -156,6 +171,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,10 +200,23 @@ 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). */
     getHlAgentWalletStatus?(): Promise<HlAgentWalletStatusOutcome>;
+    /** Operator-only: submit the wallet-signed approveAgent action to
+     *  Hyperliquid FROM THE BOX. Carries no secret — only a signature the
+     *  operator's wallet already produced. */
+    submitHlAgentApproval?(args: {
+        action: Record<string, unknown>;
+        nonce: number;
+        signature: {
+            r: string;
+            s: string;
+            v: number;
+        };
+    }): Promise<HlSubmitApprovalOutcome>;
     /** Operator-only: remove stored credentials from the plugin config and
      *  de-escalate to PAPER mode if currently running in a live mode. */
     clearExchangeCredentials?(): Promise<{

package/bridge/providers/gateway.d.ts

@@ -1,4 +1,4 @@
-import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome } from '../provider.js';
+import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome, HlSubmitApprovalOutcome } from '../provider.js';
 import type { EmergencyAction, ReconciliationSnapshot, TradingMode } from '../types.js';
 import type { GatewayConfig } from '../gateway/gateway-config.js';
 import { type GetBracketConfigOutcome, type SetBracketRequirementOutcome, type BracketRequirementFlag, type SetTradingModeOutcome, type SetExchangeCredentialsOutcome, type TestExchangeCredentialsOutcome, type ClearExchangeCredentialsOutcome } from './onboarding-commands.js';
@@ -227,7 +227,18 @@ export declare class GatewayProvider implements OpenClawProvider {
         walletAddress: string;
         testnet?: boolean;
         regenerate?: boolean;
+        confirm_venue_switch?: boolean;
     }): Promise<HlProvisionOutcome>;
+    /** Operator-only. Relay the wallet-signed approveAgent action from the box. */
+    submitHlAgentApproval(args: {
+        action: Record<string, unknown>;
+        nonce: number;
+        signature: {
+            r: string;
+            s: string;
+            v: number;
+        };
+    }): Promise<HlSubmitApprovalOutcome>;
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     getHlAgentWalletStatus(): Promise<HlAgentWalletStatusOutcome>;
     /** Operator-only. Read the current bracket-orders config from the plugin. */

package/bridge/providers/gateway.js

@@ -17,7 +17,7 @@ import { ensureHeartbeatCron, isHeartbeatLikeName } from '../gateway/heartbeat-c
 import { parseIdentityName } from '../utils/identity-name.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, DRAWDOWN_ZONE_THRESHOLDS, TENANT_LIMIT_BOUNDS, boundedNum, validateDrawdownLadder, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
-import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, } from './onboarding-commands.js';
+import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, executeSubmitHlAgentApproval, } from './onboarding-commands.js';
 const TAG = 'gateway';
 // ---- Day-start NAV persistence ----
 // Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
@@ -705,6 +705,10 @@ export class GatewayProvider {
     async provisionHlAgentWallet(args) {
         return executeProvisionHlAgentWallet({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, args);
     }
+    /** Operator-only. Relay the wallet-signed approveAgent action from the box. */
+    async submitHlAgentApproval(args) {
+        return executeSubmitHlAgentApproval({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, args);
+    }
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     async getHlAgentWalletStatus() {
         return executeHlAgentWalletStatus({

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

@@ -1,6 +1,6 @@
 import type { GatewayHttpClient } from '../gateway/gateway-http-client.js';
 import type { ToolMap } from '../gateway/tool-discovery.js';
-import type { ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome } from '../provider.js';
+import type { ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome, HlSubmitApprovalOutcome } from '../provider.js';
 import type { TradingMode } from '@reefclaw/shared';
 export interface SetTradingModeOutcome {
     ok: boolean;
@@ -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,7 +114,19 @@ export declare function executeProvisionHlAgentWallet(ctx: OnboardingContext, ar
     walletAddress: string;
     testnet?: boolean;
     regenerate?: boolean;
+    confirm_venue_switch?: boolean;
 }): Promise<HlProvisionOutcome>;
+/** Forward an hl_submit_agent_approval invocation to the plugin. The payload
+ *  is a signature the operator's wallet produced — no secret material. */
+export declare function executeSubmitHlAgentApproval(ctx: OnboardingContext, args: {
+    action: Record<string, unknown>;
+    nonce: number;
+    signature: {
+        r: string;
+        s: string;
+        v: number;
+    };
+}): Promise<HlSubmitApprovalOutcome>;
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export declare function executeHlAgentWalletStatus(ctx: OnboardingContext): Promise<HlAgentWalletStatusOutcome>;
 /** Forward a set_exchange_credentials invocation to the plugin via HTTP.

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;
@@ -250,6 +254,31 @@ export async function executeProvisionHlAgentWallet(ctx, args) {
         return { ok: false, message: reason, venue: 'hyperliquid', mode: 'PAPER' };
     }
 }
+/** Forward an hl_submit_agent_approval invocation to the plugin. The payload
+ *  is a signature the operator's wallet produced — no secret material. */
+export async function executeSubmitHlAgentApproval(ctx, args) {
+    const tool = ctx.toolMap.hl_submit_agent_approval;
+    if (!tool || !ctx.http) {
+        return {
+            ok: false,
+            message: 'hl_submit_agent_approval tool not available on gateway — update the ReefClaw plugin (npx @reefclaw/connect@latest)',
+        };
+    }
+    try {
+        const result = await ctx.http.invoke(tool, {
+            action: args.action,
+            nonce: args.nonce,
+            signature: args.signature,
+            operator_token: ctx.operatorToken,
+        });
+        return result.data;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `hl_submit_agent_approval failed: ${reason}`);
+        return { ok: false, message: reason };
+    }
+}
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export async function executeHlAgentWalletStatus(ctx) {
     const tool = ctx.toolMap.hl_agent_wallet_status;

package/bridge/types.d.ts

@@ -3,7 +3,7 @@ export type { Channel, RequestFrame, ResponseFrame, EventFrame, Frame, Emergency
 export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
 type EventFrame = _EventFrame;
 /** Methods the skill accepts from the relay (browser → skill) */
-export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "get_bracket_config", "set_bracket_requirement"];
+export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement"];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
  *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk

package/bridge/types.js

@@ -21,6 +21,7 @@ export const ALLOWED_METHODS = [
     // Hyperliquid guided onboarding (box-generated agent wallet) — operator.write-gated.
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     // Bracket-orders config (Phase 3.5b) — operator.write-gated.
     'get_bracket_config',
     'set_bracket_requirement',
@@ -38,6 +39,7 @@ export const OPERATOR_WRITE_METHODS = new Set([
     'clear_exchange_credentials',
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
     'emergency.kill',

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/config/tool-gate.js

@@ -35,6 +35,7 @@ export const UNGOVERNABLE_TOOLS = new Set([
     // operator-only channel; disabling them would strand the HL setup flow.
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
 ]);
 /** RC_TOOL_GATE: 'off' = kill-switch (gate never blocks), 'shadow' = log
  *  would-be blocks but execute anyway, anything else/default = 'enforce'.

package/index.js

@@ -68,6 +68,7 @@ import { testExchangeCredentialsTool } from './tools/test-exchange-credentials.j
 import { clearExchangeCredentialsTool } from './tools/clear-exchange-credentials.js';
 import { hlProvisionAgentWalletTool } from './tools/hl-provision-agent-wallet.js';
 import { hlAgentWalletStatusTool } from './tools/hl-agent-wallet-status.js';
+import { hlSubmitAgentApprovalTool } from './tools/hl-submit-agent-approval.js';
 import { ensureCredentialTransportKey } from './security/sealed-credentials.js';
 // Tool implementations
 import { fetchTickerTool } from './tools/fetch-ticker.js';
@@ -807,6 +808,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 +841,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: {
@@ -848,6 +851,16 @@ const TOOL_PARAMS = {
             probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
         },
     },
+    hl_submit_agent_approval: {
+        type: 'object',
+        properties: {
+            operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
+            action: { type: 'object', description: "The wallet-signed approveAgent action, verbatim. Only type='approveAgent' is accepted." },
+            nonce: { type: 'number', description: 'Outer nonce — must equal action.nonce (user-signed actions carry one nonce)' },
+            signature: { type: 'object', description: 'Wallet signature { r, s, v } over the approveAgent typed data' },
+            probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
+        },
+    },
     clear_exchange_credentials: {
         type: 'object',
         properties: {
@@ -2724,6 +2737,20 @@ const paperTradingPlugin = {
                     return jsonResult(await hlProvisionAgentWalletTool(params, { runtime, bootVenue: venue }));
                 },
             },
+            {
+                name: 'hl_submit_agent_approval',
+                label: 'Submit Hyperliquid Agent Approval',
+                description: "Operator-only. Submit the operator's wallet-signed approveAgent action to Hyperliquid FROM THIS MACHINE (the dashboard browser is often blocked from reaching the exchange API by ad-blockers/shields). Strictly limited to type='approveAgent' targeting this box's own provisioned agent wallet — it is not a general signed-action relay. Refused without dashboard operator provenance.",
+                parameters: TOOL_PARAMS.hl_submit_agent_approval,
+                execute: async (_id, params) => {
+                    if (params?.probe === true)
+                        return jsonResult(await hlSubmitAgentApprovalTool(params));
+                    const prov = verifyOperatorProvenance(params.operator_token);
+                    if (!prov.ok)
+                        return jsonResult({ error: prov.error });
+                    return jsonResult(await hlSubmitAgentApprovalTool(params));
+                },
+            },
             {
                 name: 'hl_agent_wallet_status',
                 label: 'Hyperliquid 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.23",
   "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": {
@@ -72,6 +72,7 @@
       "clear_exchange_credentials",
       "hl_provision_agent_wallet",
       "hl_agent_wallet_status",
+      "hl_submit_agent_approval",
       "get_bracket_config",
       "set_bracket_requirement"
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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,21 +50,70 @@ 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) {
             const masterMatches = existingMaster != null && existingMaster.toLowerCase() === walletAddress.toLowerCase();
+            // ★ Honour a CHANGED network on the resume path. The same keypair is
+            // valid on both Hyperliquid networks, so switching mainnet<->testnet
+            // must not require regenerating the wallet — but the stored flag has to
+            // follow, or the box boots against the network the operator did NOT
+            // pick. Before this, unticking "Use Hyperliquid testnet" after
+            // provisioning silently kept testnet:true, and the approval was signed
+            // for Testnet while the operator believed they were on mainnet
+            // (observed live 2026-08-03).
+            if (masterMatches && existingTestnet !== testnet) {
+                try {
+                    updatePluginConfig({ exchange: buildVenueExchangeConfig(existingExchange, 'hyperliquid', {}, testnet) }, deps.configPath);
+                    existingTestnet = testnet;
+                    logger.info(TAG, `network switched to ${testnet ? 'TESTNET' : 'MAINNET'} (same agent wallet)`);
+                }
+                catch (err) {
+                    logger.warn(TAG, `could not persist network change: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             return {
                 ok: true,
                 message: masterMatches
@@ -107,12 +157,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/hl-submit-agent-approval.d.ts

@@ -0,0 +1,27 @@
+export interface HlSubmitAgentApprovalArgs {
+    /** The approveAgent action, byte-identical to what the wallet signed. */
+    action?: Record<string, unknown>;
+    /** Outer nonce — for user-signed actions it must equal action.nonce. */
+    nonce?: number;
+    signature?: {
+        r?: unknown;
+        s?: unknown;
+        v?: unknown;
+    };
+    /** Tool-discovery probe — returns immediately, no config or network. */
+    probe?: boolean;
+}
+export interface HlSubmitAgentApprovalResult {
+    ok: boolean;
+    message: string;
+    /** Hyperliquid's own status string when it answered ('ok' | 'err'). */
+    hlStatus?: string;
+    /** Which network the SIGNED action targeted. */
+    chain?: 'Mainnet' | 'Testnet';
+    agentAddress?: string;
+}
+export interface HlSubmitAgentApprovalDeps {
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function hlSubmitAgentApprovalTool(args: HlSubmitAgentApprovalArgs, deps?: HlSubmitAgentApprovalDeps): Promise<HlSubmitAgentApprovalResult>;

package/tools/hl-submit-agent-approval.js

@@ -0,0 +1,140 @@
+// hl_submit_agent_approval — operator-only plugin tool.
+//
+// Submits the operator's WALLET-SIGNED `approveAgent` action to Hyperliquid
+// from THIS BOX, instead of from the dashboard's browser.
+//
+// ★ Why the box and not the browser (real failure, 2026-08-03): the guided
+// flow POSTed to api.hyperliquid*.xyz directly from the dashboard page and an
+// operator hit "Failed to fetch" twice. The endpoint was fine (CORS is `*`,
+// POSTs answer normally) and the box reached it in 0.49s — the request was
+// blocked INSIDE the browser (ad-blocker / shield / DNS policy; crypto API
+// domains are routinely blocked). Making a required onboarding step depend on
+// the operator's browser extensions is the wrong architecture: the box is
+// already the Hyperliquid client (every read and every future order goes
+// through it), so it submits. The browser's only irreplaceable job is holding
+// the wallet and producing the signature. ReefClaw's servers stay out of the
+// path — the signed action travels over the existing relay to the user's own
+// machine.
+//
+// ★ SECURITY — this is deliberately NOT a generic signed-action relay.
+// A tool that forwarded any {action, signature} pair to /exchange would be a
+// capability escalation: HL's withdraw / usdSend / usdClassTransfer are all
+// user-signed actions in the same envelope shape. If a signature for one of
+// those ever existed, a generic relay would happily submit it. So:
+//   1. `action.type` MUST be exactly 'approveAgent' — nothing else is accepted.
+//   2. `action.agentAddress` MUST be the address THIS box's provisioned agent
+//      key controls, so the tool can only ever authorize our own wallet.
+//   3. The endpoint is chosen from the SIGNED action's `hyperliquidChain`, so
+//      it cannot be pointed at a different network than the one signed for.
+// The signature itself is produced and validated by Hyperliquid; we never
+// touch key material here (the agent key is only used to DERIVE its public
+// address for check 2).
+import { readPluginConfig } from '../config/plugin-config-io.js';
+import { deriveAddressFromPrivateKey, isHexAddress, sameAddress } from '../venues/hyperliquid/hl-agent-wallet.js';
+import { hlApiBase } from '../venues/hyperliquid/hl-preflight.js';
+import { logger } from '../logger.js';
+const TAG = 'hl-submit-agent-approval';
+function fail(message, extra = {}) {
+    return { ok: false, message, ...extra };
+}
+export async function hlSubmitAgentApprovalTool(args, deps = {}) {
+    if (args?.probe === true) {
+        return { ok: false, message: 'probe' };
+    }
+    const action = args?.action;
+    if (!action || typeof action !== 'object') {
+        return fail('action is required (the approveAgent object the wallet signed)');
+    }
+    // 1. Only ever approveAgent — never a generic relay (see header).
+    if (action.type !== 'approveAgent') {
+        logger.warn(TAG, `refused non-approveAgent action type: ${String(action.type)}`);
+        return fail(`Refused: this tool only submits 'approveAgent' actions, not '${String(action.type)}'.`);
+    }
+    const chain = action.hyperliquidChain;
+    if (chain !== 'Mainnet' && chain !== 'Testnet') {
+        return fail("action.hyperliquidChain must be 'Mainnet' or 'Testnet'");
+    }
+    const agentAddress = action.agentAddress;
+    if (!isHexAddress(agentAddress)) {
+        return fail('action.agentAddress must be a 0x… address', { chain });
+    }
+    const sig = args?.signature;
+    const r = sig?.r;
+    const s = sig?.s;
+    const v = sig?.v;
+    if (typeof r !== 'string' || typeof s !== 'string' || typeof v !== 'number') {
+        return fail('signature must be { r: string, s: string, v: number }', { chain });
+    }
+    const nonce = args?.nonce;
+    // User-signed actions carry ONE nonce — the outer value must match the one
+    // inside the signed payload, or HL verifies a different message than we send.
+    if (typeof nonce !== 'number' || nonce !== action.nonce) {
+        return fail('nonce must be a number equal to action.nonce', { chain });
+    }
+    // 2. The agent being approved must be OUR provisioned wallet.
+    let storedKey;
+    try {
+        const cfg = readPluginConfig(deps.configPath);
+        if (typeof cfg.exchange?.agentPrivateKey === 'string')
+            storedKey = cfg.exchange.agentPrivateKey;
+    }
+    catch {
+        // fall through to the not-provisioned error
+    }
+    if (!storedKey) {
+        return fail('No Hyperliquid agent wallet is provisioned on this machine — run the guided setup first.', { chain });
+    }
+    const derived = await deriveAddressFromPrivateKey(storedKey);
+    if (!derived.ok) {
+        return fail('Could not derive this machine’s agent wallet address — cannot verify what is being approved.', { chain });
+    }
+    if (!sameAddress(derived.address, agentAddress)) {
+        logger.warn(TAG, 'refused: action.agentAddress is not this box’s provisioned agent');
+        return fail('Refused: the approval targets a different agent wallet than the one provisioned on this machine.', { chain, agentAddress: derived.address });
+    }
+    // 3. Submit — endpoint from the SIGNED chain, never from local config.
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = `${hlApiBase(chain === 'Testnet')}/exchange`;
+    logger.info(TAG, `submitting approveAgent for ${agentAddress} to ${chain}`);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ action, nonce, signature: { r, s, v } }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        const text = await res.text();
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // non-JSON — surfaced verbatim below
+        }
+        if (!res.ok || body?.status !== 'ok') {
+            const detail = typeof body?.response === 'string' ? body.response : text.slice(0, 300) || `HTTP ${res.status}`;
+            logger.warn(TAG, `Hyperliquid rejected the approval: ${detail}`);
+            return fail(`Hyperliquid rejected the approval: ${detail}`, {
+                hlStatus: body?.status,
+                chain,
+                agentAddress: derived.address,
+            });
+        }
+        logger.info(TAG, `approveAgent accepted by Hyperliquid (${chain})`);
+        return {
+            ok: true,
+            message: `Approval submitted and accepted by Hyperliquid (${chain}).`,
+            hlStatus: 'ok',
+            chain,
+            agentAddress: derived.address,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `submit failed: ${msg}`);
+        return fail(`Could not reach Hyperliquid from this machine: ${msg}`, {
+            chain,
+            agentAddress: derived.address,
+        });
+    }
+}

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>>;
 }