@reefclaw/openclaw-plugin 0.1.20 → 0.1.22

package/bridge/bridge.d.ts

@@ -92,6 +92,12 @@ export declare class Bridge {
      *  frame. Ladder validation runs here for fast dashboard feedback and
      *  again in the plugin (defense in depth). */
     private handleSetTradingMode;
+    /** Parse + validate the per-venue credential fields shared by the set/test
+     *  handlers. Secrets (Binance secret / HL agent key) pass through once and
+     *  are never cached or logged — the returned fingerprint is the Binance
+     *  apiKey prefix or the PUBLIC HL master address, never secret material.
+     *  Returns null after writing a 400 response when validation fails. */
+    private parseExchangeCredentialParams;
     /** Handle a set_exchange_credentials request. The secret value passes
      *  through once and is never cached or logged; only a redacted fingerprint
      *  appears in the audit trail. */
@@ -100,6 +106,10 @@ export declare class Bridge {
      *  verification, nothing persisted. Same input validation + secret
      *  redaction rules as set_exchange_credentials. */
     private handleTestExchangeCredentials;
+    /** Handle an hl_provision_agent_wallet request — the guided HL onboarding's
+     *  key-minting step. Nothing secret transits in either direction: request =
+     *  public master address, response = public agent address. */
+    private handleProvisionHlAgentWallet;
     /** Handle a clear_exchange_credentials request. No input — the method
      *  itself is the "yes I want this" signal; the webapp is expected to
      *  gate this behind a confirmation dialog before calling. */

package/bridge/bridge.js

@@ -498,6 +498,27 @@ export class Bridge {
                 this.connector.sendResponse(id, true, result);
                 return;
             }
+            if (method === 'hl_provision_agent_wallet') {
+                const result = await this.handleProvisionHlAgentWallet(id, params);
+                if (result !== 'responded') {
+                    this.connector.sendResponse(id, true, result);
+                }
+                return;
+            }
+            if (method === 'hl_agent_wallet_status') {
+                const provider = this.provider;
+                if (!provider.getHlAgentWalletStatus) {
+                    this.connector.sendResponse(id, true, {
+                        ok: false,
+                        message: 'Provider does not support hl_agent_wallet_status (likely mock provider)',
+                        configured: false,
+                    });
+                    return;
+                }
+                const result = await provider.getHlAgentWalletStatus();
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
             if (method === 'get_bracket_config') {
                 if (!this.provider.getBracketConfig) {
                     this.connector.sendResponse(id, false, undefined, {
@@ -671,21 +692,95 @@ export class Bridge {
         }
         return outcome;
     }
-    /** Handle a set_exchange_credentials request. The secret value passes
-     *  through once and is never cached or logged; only a redacted fingerprint
-     *  appears in the audit trail. */
-    async handleSetExchangeCredentials(id, params) {
+    /** Parse + validate the per-venue credential fields shared by the set/test
+     *  handlers. Secrets (Binance secret / HL agent key) pass through once and
+     *  are never cached or logged — the returned fingerprint is the Binance
+     *  apiKey prefix or the PUBLIC HL master address, never secret material.
+     *  Returns null after writing a 400 response when validation fails. */
+    parseExchangeCredentialParams(id, params) {
+        // Sealed envelope: the browser encrypted the credential payload to the
+        // BOX's transport key — the bridge cannot read it and must not try.
+        // Forward opaquely; the plugin decrypts and runs the full validation.
+        if (params?.sealed != null) {
+            const sealed = params.sealed;
+            if (typeof sealed !== 'object' || Array.isArray(sealed)) {
+                this.connector.sendResponse(id, false, undefined, {
+                    code: 400,
+                    message: 'sealed must be an envelope object',
+                });
+                return null;
+            }
+            const kid = sealed.kid;
+            return {
+                req: {
+                    sealed: sealed,
+                    ...(params?.confirm_venue_switch === true ? { confirm_venue_switch: true } : {}),
+                },
+                fp: `sealed:${typeof kid === 'string' ? kid.slice(0, 16) : 'unknown'}`,
+            };
+        }
+        const testnet = params?.testnet === true;
+        if (params?.venue === 'hyperliquid') {
+            const walletAddress = typeof params?.walletAddress === 'string' ? params.walletAddress.trim() : '';
+            const agentPrivateKey = typeof params?.agentPrivateKey === 'string' ? params.agentPrivateKey.trim() : '';
+            // 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',
+                    ...(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 : '';
-        const testnet = params?.testnet === true;
-        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 'responded';
+            return null;
         }
-        const 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
+     *  appears in the audit trail. */
+    async handleSetExchangeCredentials(id, params) {
+        const parsed = this.parseExchangeCredentialParams(id, params);
+        if (!parsed)
+            return 'responded';
+        const { req, fp } = parsed;
         const provider = this.provider;
         if (!provider.setExchangeCredentials) {
             return {
@@ -697,13 +792,20 @@ export class Bridge {
                 readiness: 'UNKNOWN',
             };
         }
-        audit('set_exchange_credentials.start', { id, fingerprint: fp, testnet });
-        const outcome = await provider.setExchangeCredentials(apiKey, secret, testnet);
+        audit('set_exchange_credentials.start', {
+            id,
+            venue: 'sealed' in req ? 'sealed' : req.venue,
+            fingerprint: fp,
+            testnet: 'testnet' in req ? req.testnet === true : undefined,
+        });
+        const outcome = await provider.setExchangeCredentials(req);
         audit('set_exchange_credentials.complete', {
             id,
             ok: outcome.ok,
+            venue: outcome.venue,
             fingerprint: outcome.fingerprint,
             reconnected: outcome.reconnected,
+            restartRequired: outcome.restartRequired === true,
             mode: outcome.mode,
         });
         return outcome;
@@ -712,17 +814,10 @@ export class Bridge {
      *  verification, nothing persisted. Same input validation + secret
      *  redaction rules as set_exchange_credentials. */
     async handleTestExchangeCredentials(id, params) {
-        const apiKey = typeof params?.apiKey === 'string' ? params.apiKey : '';
-        const secret = typeof params?.secret === 'string' ? params.secret : '';
-        const testnet = params?.testnet === true;
-        if (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',
-            });
+        const parsed = this.parseExchangeCredentialParams(id, params);
+        if (!parsed)
             return 'responded';
-        }
-        const fp = fingerprint(apiKey);
+        const { req, fp } = parsed;
         const provider = this.provider;
         if (!provider.testExchangeCredentials) {
             return {
@@ -732,19 +827,68 @@ export class Bridge {
                 canReadBalance: false,
                 canReadPositions: false,
                 balanceUSDT: null,
-                testnet,
+                testnet: 'testnet' in req ? req.testnet === true : false,
                 errors: ['provider-unsupported'],
             };
         }
-        audit('test_exchange_credentials.start', { id, fingerprint: fp, testnet });
-        const outcome = await provider.testExchangeCredentials(apiKey, secret, testnet);
+        audit('test_exchange_credentials.start', {
+            id,
+            venue: 'sealed' in req ? 'sealed' : req.venue,
+            fingerprint: fp,
+            testnet: 'testnet' in req ? req.testnet === true : undefined,
+        });
+        const outcome = await provider.testExchangeCredentials(req);
         audit('test_exchange_credentials.complete', {
             id,
             ok: outcome.ok,
+            venue: outcome.venue,
             fingerprint: outcome.fingerprint,
             canReadBalance: outcome.canReadBalance,
             canReadPositions: outcome.canReadPositions,
             balanceUSDT: outcome.balanceUSDT,
+            agentApproved: outcome.agentApproved,
+        });
+        return outcome;
+    }
+    /** Handle an hl_provision_agent_wallet request — the guided HL onboarding's
+     *  key-minting step. Nothing secret transits in either direction: request =
+     *  public master address, response = public agent address. */
+    async handleProvisionHlAgentWallet(id, params) {
+        const walletAddress = typeof params?.walletAddress === 'string' ? params.walletAddress.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 'responded';
+        }
+        const provider = this.provider;
+        if (!provider.provisionHlAgentWallet) {
+            return {
+                ok: false,
+                message: 'Provider does not support hl_provision_agent_wallet (likely mock provider)',
+                venue: 'hyperliquid',
+                mode: this.lastKnownTradingMode ?? 'PAPER',
+            };
+        }
+        audit('hl_provision_agent_wallet.start', {
+            id,
+            master: fingerprint(walletAddress),
+            testnet: params?.testnet === true,
+            regenerate: params?.regenerate === true,
+        });
+        const outcome = await provider.provisionHlAgentWallet({
+            walletAddress,
+            testnet: params?.testnet === true,
+            regenerate: params?.regenerate === true,
+            confirm_venue_switch: params?.confirm_venue_switch === true,
+        });
+        audit('hl_provision_agent_wallet.complete', {
+            id,
+            ok: outcome.ok,
+            agentAddress: outcome.agentAddress, // public — the point of the flow
+            existing: outcome.existing === true,
+            restartRequired: outcome.restartRequired === true,
         });
         return outcome;
     }

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' | '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' | 'get_bracket_config' | 'set_bracket_requirement';
 /**
  * Build the test args used when probing each logical tool.
  *

package/bridge/gateway/tool-discovery.js

@@ -20,6 +20,8 @@ const OPTIONAL_TOOLS = [
     'set_exchange_credentials',
     'test_exchange_credentials',
     'clear_exchange_credentials',
+    'hl_provision_agent_wallet',
+    'hl_agent_wallet_status',
     'get_bracket_config',
     'set_bracket_requirement',
 ];
@@ -44,6 +46,8 @@ const CANDIDATES = {
     set_exchange_credentials: ['set_exchange_credentials'],
     test_exchange_credentials: ['test_exchange_credentials'],
     clear_exchange_credentials: ['clear_exchange_credentials'],
+    hl_provision_agent_wallet: ['hl_provision_agent_wallet'],
+    hl_agent_wallet_status: ['hl_agent_wallet_status'],
     get_bracket_config: ['get_bracket_config'],
     set_bracket_requirement: ['set_bracket_requirement'],
 };
@@ -108,6 +112,13 @@ export function buildProbeArgs(symbol = DEFAULT_PROBE_SYMBOL) {
         // clear_exchange_credentials: tool requires confirm:true. Probing without
         // it triggers the safety gate early-return — tool exists, nothing wiped.
         clear_exchange_credentials: {},
+        // Provision: empty walletAddress fails the 0x-hex validator before any
+        // key is minted or written. Status: `probe:true` is the tool's dedicated
+        // discovery path — it returns before touching config or the network (a
+        // real status call runs HL /info reads that could outlive the 8s probe
+        // timeout and mark the tool missing forever).
+        hl_provision_agent_wallet: { walletAddress: '' },
+        hl_agent_wallet_status: { 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

@@ -1,5 +1,58 @@
 import type { EmergencyAction, ReconciliationSnapshot, TickerData, CandleData, OrderUpdatePayload, AgentStateData, RiskUpdatePayload, ChatMessage, MarketStructureData, CryptoMetricsData, VolumeAnalysisData, TradeJournalEntry, RegimeData, SignalData, MissionData, AnalyticsData, ShadowComparisonData, TradingModeData, DecisionTraceData } from './types.js';
 import type { TradingMode } from '@reefclaw/shared';
+/** Per-venue credential shapes for the operator set/test RPCs. Binance is an
+ *  HMAC key pair; Hyperliquid is a MASTER account address (public — queries)
+ *  plus an approved AGENT wallet private key (signs only, cannot withdraw).
+ *  The `sealed` variant carries an end-to-end encrypted envelope the browser
+ *  sealed to the box's transport key — the bridge forwards it OPAQUELY (it
+ *  cannot and must not read it); all validation happens plugin-side after
+ *  decryption. A discriminated union so a caller can never mix the shapes. */
+export type ExchangeCredentialsRequest = {
+    venue: 'binance';
+    apiKey?: string;
+    secret?: string;
+    testnet?: boolean;
+    confirm_venue_switch?: boolean;
+} | {
+    venue: 'hyperliquid';
+    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 {
+    ok: boolean;
+    message: string;
+    venue: 'hyperliquid';
+    agentAddress?: string;
+    masterAddress?: string;
+    testnet?: boolean;
+    existing?: boolean;
+    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 {
+    ok: boolean;
+    message: string;
+    configured: boolean;
+    masterAddress?: string;
+    agentAddress?: string;
+    testnet?: boolean;
+    approved?: boolean | null;
+    validUntil?: number | null;
+    balanceUSDC?: number | null;
+    warnings?: string[];
+    restartRequired?: boolean;
+}
 /** Fill error data emitted when a limit fill fails */
 export interface FillErrorData {
     orderId: string;
@@ -95,19 +148,29 @@ export interface OpenClawProvider {
         readiness: string;
         reason?: string;
     }>;
-    /** Operator-only: set Binance API credentials. The raw secret is written
-     *  to the plugin-local config file and never retained by the skill. */
-    setExchangeCredentials?(apiKey: string, secret: string, testnet?: boolean): Promise<{
+    /** Operator-only: set exchange credentials, per venue. The raw secret /
+     *  agent key is written to the plugin-local config file and never retained
+     *  by the skill. */
+    setExchangeCredentials?(req: ExchangeCredentialsRequest): Promise<{
         ok: boolean;
         message: string;
         fingerprint: string;
         reconnected: boolean;
         mode: TradingMode;
         readiness: string;
+        venue?: string;
+        /** 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 Binance API credentials with a transient
-     *  read-only call. Nothing is persisted. */
-    testExchangeCredentials?(apiKey: string, secret: string, testnet?: boolean): Promise<{
+    /** Operator-only: verify exchange credentials with transient read-only
+     *  calls, per venue. Nothing is persisted. */
+    testExchangeCredentials?(req: ExchangeCredentialsRequest): Promise<{
         ok: boolean;
         message: string;
         fingerprint: string;
@@ -116,7 +179,23 @@ export interface OpenClawProvider {
         balanceUSDT: number | null;
         testnet: boolean;
         errors: string[];
+        venue?: string;
+        agentAddress?: string;
+        agentApproved?: boolean | null;
+        agentValidUntil?: number | null;
+        warnings?: string[];
     }>;
+    /** Operator-only: generate a Hyperliquid agent wallet ON the trader's box
+     *  (the private key never leaves it) and return the public address. */
+    provisionHlAgentWallet?(args: {
+        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: 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 } from '../provider.js';
+import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome } 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';
@@ -218,9 +218,19 @@ export declare class GatewayProvider implements OpenClawProvider {
         error?: string;
     }>;
     setTradingMode(mode: TradingMode, acknowledged?: boolean): Promise<SetTradingModeOutcome>;
-    setExchangeCredentials(apiKey: string, secret: string, testnet?: boolean): Promise<SetExchangeCredentialsOutcome>;
-    testExchangeCredentials(apiKey: string, secret: string, testnet?: boolean): Promise<TestExchangeCredentialsOutcome>;
+    setExchangeCredentials(req: ExchangeCredentialsRequest): Promise<SetExchangeCredentialsOutcome>;
+    testExchangeCredentials(req: ExchangeCredentialsRequest): Promise<TestExchangeCredentialsOutcome>;
     clearExchangeCredentials(): Promise<ClearExchangeCredentialsOutcome>;
+    /** Operator-only. Mint an HL agent wallet on the box; returns the public
+     *  address only (guided onboarding). */
+    provisionHlAgentWallet(args: {
+        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>;
     /** Operator-only. Read the current bracket-orders config from the plugin. */
     getBracketConfig(): Promise<GetBracketConfigOutcome>;
     /** Operator-only. Flip requireStopLoss or requireTakeProfit. */

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, } from './onboarding-commands.js';
+import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, } 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
@@ -684,14 +684,14 @@ export class GatewayProvider {
         // four state-mutating operator tools without it (audit F12).
         { http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, mode, acknowledged);
     }
-    async setExchangeCredentials(apiKey, secret, testnet) {
-        return executeSetExchangeCredentials({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, apiKey, secret, testnet);
+    async setExchangeCredentials(req) {
+        return executeSetExchangeCredentials({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, req);
     }
-    async testExchangeCredentials(apiKey, secret, testnet) {
+    async testExchangeCredentials(req) {
         return executeTestExchangeCredentials(
         // operatorToken required since the SkillSpector hardening: the plugin
         // refuses the credential-validation call without dashboard provenance.
-        { http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, apiKey, secret, testnet);
+        { http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, req);
     }
     async clearExchangeCredentials() {
         return executeClearExchangeCredentials({
@@ -700,6 +700,19 @@ export class GatewayProvider {
             operatorToken: this.config.connectionToken,
         });
     }
+    /** Operator-only. Mint an HL agent wallet on the box; returns the public
+     *  address only (guided onboarding). */
+    async provisionHlAgentWallet(args) {
+        return executeProvisionHlAgentWallet({ 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({
+            http: this.http,
+            toolMap: this.toolMap,
+            operatorToken: this.config.connectionToken,
+        });
+    }
     /** Operator-only. Read the current bracket-orders config from the plugin. */
     async getBracketConfig() {
         return executeGetBracketConfig({ http: this.http, toolMap: this.toolMap });

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

@@ -1,5 +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 { TradingMode } from '@reefclaw/shared';
 export interface SetTradingModeOutcome {
     ok: boolean;
@@ -16,6 +17,15 @@ export interface SetExchangeCredentialsOutcome {
     reconnected: boolean;
     mode: TradingMode;
     readiness: string;
+    /** Venue the credentials were stored for (plugin ≥ HL product surface). */
+    venue?: string;
+    /** 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;
@@ -23,9 +33,18 @@ export interface TestExchangeCredentialsOutcome {
     fingerprint: string;
     canReadBalance: boolean;
     canReadPositions: boolean;
+    /** Quote-currency balance (USDT on Binance, USDC on HL); name is historical. */
     balanceUSDT: number | null;
     testnet: boolean;
     errors: string[];
+    venue?: string;
+    /** HL only: address the tested agent key controls (public). */
+    agentAddress?: string;
+    /** HL only: definitive approval verdict, or null when unverifiable. */
+    agentApproved?: boolean | null;
+    /** HL only: approval expiry (epoch ms) when the exchange reports one. */
+    agentValidUntil?: number | null;
+    warnings?: string[];
 }
 export interface ClearExchangeCredentialsOutcome {
     ok: boolean;
@@ -71,10 +90,10 @@ export interface SetBracketRequirementOutcome {
 /** Forward a set_trading_mode invocation to the plugin via HTTP. */
 export declare function executeSetTradingMode(ctx: OnboardingContext, mode: TradingMode, acknowledged: boolean | undefined): Promise<SetTradingModeOutcome>;
 /** Forward a test_exchange_credentials invocation to the plugin. The plugin
- *  does a throwaway read-only call to verify permissions without persisting
- *  the keys. Error messages are scrubbed of the raw secret before logging
- *  (same approach as the set path). */
-export declare function executeTestExchangeCredentials(ctx: OnboardingContext, apiKey: string, secret: string, testnet: boolean | undefined): Promise<TestExchangeCredentialsOutcome>;
+ *  does throwaway read-only calls to verify the credentials without
+ *  persisting them. Error messages are scrubbed of the raw secret / agent key
+ *  before logging (same approach as the set path). */
+export declare function executeTestExchangeCredentials(ctx: OnboardingContext, req: ExchangeCredentialsRequest): Promise<TestExchangeCredentialsOutcome>;
 /** Forward a clear_exchange_credentials invocation to the plugin. Sends
  *  `confirm: true` unconditionally — the skill RPC only accepts the call
  *  at all when the bridge has decided it's legitimate, so the plugin-side
@@ -87,8 +106,20 @@ export declare function executeGetBracketConfig(ctx: OnboardingContext): Promise
 /** Forward a set_bracket_requirement invocation to the plugin. The plugin
  *  side enforces flag + boolean validation; the skill layer just forwards. */
 export declare function executeSetBracketRequirement(ctx: OnboardingContext, flag: BracketRequirementFlag, value: boolean): Promise<SetBracketRequirementOutcome>;
+/** Forward an hl_provision_agent_wallet invocation to the plugin. No secrets
+ *  transit this path in EITHER direction — the request carries a public
+ *  master address; the response carries a public agent address (the private
+ *  key is minted and stays on the box). */
+export declare function executeProvisionHlAgentWallet(ctx: OnboardingContext, args: {
+    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>;
 /** Forward a set_exchange_credentials invocation to the plugin via HTTP.
- *  The raw secret is sent once over TLS and never retained here — no
- *  caching, no log lines with the raw value. Errors are scrubbed of the
+ *  The raw secret / agent key is sent once over TLS and never retained here —
+ *  no caching, no log lines with the raw value. Errors are scrubbed of the
  *  secret before logging in case it ever appears in an error chain. */
-export declare function executeSetExchangeCredentials(ctx: OnboardingContext, apiKey: string, secret: string, testnet: boolean | undefined): Promise<SetExchangeCredentialsOutcome>;
+export declare function executeSetExchangeCredentials(ctx: OnboardingContext, req: ExchangeCredentialsRequest): Promise<SetExchangeCredentialsOutcome>;