@reefclaw/openclaw-plugin 0.1.20 → 0.1.22

package/bridge/providers/onboarding-commands.js

@@ -38,11 +38,57 @@ export async function executeSetTradingMode(ctx, mode, acknowledged) {
         };
     }
 }
+/** Build the plugin-tool payload for a per-venue credential request. The
+ *  secret material (Binance secret / HL agent key) passes through verbatim
+ *  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, ...confirm, operator_token: ctx.operatorToken },
+            scrub: '',
+        };
+    }
+    if (req.venue === 'hyperliquid') {
+        return {
+            payload: {
+                venue: 'hyperliquid',
+                walletAddress: req.walletAddress,
+                agentPrivateKey: req.agentPrivateKey,
+                testnet: req.testnet,
+                ...confirm,
+                operator_token: ctx.operatorToken,
+            },
+            scrub: req.agentPrivateKey ?? '',
+        };
+    }
+    return {
+        payload: {
+            venue: 'binance',
+            apiKey: req.apiKey,
+            secret: req.secret,
+            testnet: req.testnet,
+            ...confirm,
+            operator_token: ctx.operatorToken,
+        },
+        scrub: req.secret ?? '',
+    };
+}
+function scrubError(reason, scrub) {
+    if (!scrub)
+        return reason;
+    return reason.replace(new RegExp(escapeRegex(scrub), 'g'), '***');
+}
 /** 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 async function executeTestExchangeCredentials(ctx, apiKey, secret, testnet) {
+ *  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 async function executeTestExchangeCredentials(ctx, req) {
+    const testnet = ('testnet' in req ? req.testnet : undefined) ?? false;
     const tool = ctx.toolMap.test_exchange_credentials;
     if (!tool || !ctx.http) {
         return {
@@ -52,17 +98,18 @@ export async function executeTestExchangeCredentials(ctx, apiKey, secret, testne
             canReadBalance: false,
             canReadPositions: false,
             balanceUSDT: null,
-            testnet: testnet ?? false,
+            testnet,
             errors: ['tool-not-available'],
         };
     }
+    const { payload, scrub } = credentialPayload(ctx, req);
     try {
-        const result = await ctx.http.invoke(tool, { apiKey, secret, testnet, operator_token: ctx.operatorToken });
+        const result = await ctx.http.invoke(tool, payload);
         return result.data;
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        const sanitized = reason.replace(new RegExp(escapeRegex(secret), 'g'), '***');
+        const sanitized = scrubError(reason, scrub);
         logger.error(TAG, `test_exchange_credentials failed: ${sanitized}`);
         return {
             ok: false,
@@ -71,7 +118,7 @@ export async function executeTestExchangeCredentials(ctx, apiKey, secret, testne
             canReadBalance: false,
             canReadPositions: false,
             balanceUSDT: null,
-            testnet: testnet ?? false,
+            testnet,
             errors: [sanitized],
         };
     }
@@ -177,11 +224,63 @@ export async function executeSetBracketRequirement(ctx, flag, value) {
         };
     }
 }
+/** 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 async function executeProvisionHlAgentWallet(ctx, args) {
+    const tool = ctx.toolMap.hl_provision_agent_wallet;
+    if (!tool || !ctx.http) {
+        return {
+            ok: false,
+            message: 'hl_provision_agent_wallet tool not available on gateway — update the ReefClaw plugin (npx @reefclaw/connect@latest)',
+            venue: 'hyperliquid',
+            mode: 'PAPER',
+        };
+    }
+    try {
+        const result = await ctx.http.invoke(tool, {
+            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;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `hl_provision_agent_wallet failed: ${reason}`);
+        return { ok: false, message: reason, venue: 'hyperliquid', mode: 'PAPER' };
+    }
+}
+/** 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;
+    if (!tool || !ctx.http) {
+        return {
+            ok: false,
+            message: 'hl_agent_wallet_status tool not available on gateway — update the ReefClaw plugin (npx @reefclaw/connect@latest)',
+            configured: false,
+        };
+    }
+    try {
+        const result = await ctx.http.invoke(tool, {
+            operator_token: ctx.operatorToken,
+        });
+        return result.data;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `hl_agent_wallet_status failed: ${reason}`);
+        return { ok: false, message: reason, configured: false };
+    }
+}
 /** 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 async function executeSetExchangeCredentials(ctx, apiKey, secret, testnet) {
+export async function executeSetExchangeCredentials(ctx, req) {
     const tool = ctx.toolMap.set_exchange_credentials;
     if (!tool || !ctx.http) {
         return {
@@ -193,13 +292,14 @@ export async function executeSetExchangeCredentials(ctx, apiKey, secret, testnet
             readiness: 'UNKNOWN',
         };
     }
+    const { payload, scrub } = credentialPayload(ctx, req);
     try {
-        const result = await ctx.http.invoke(tool, { apiKey, secret, testnet, operator_token: ctx.operatorToken });
+        const result = await ctx.http.invoke(tool, payload);
         return result.data;
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        const sanitized = reason.replace(new RegExp(escapeRegex(secret), 'g'), '***');
+        const sanitized = scrubError(reason, scrub);
         logger.error(TAG, `set_exchange_credentials failed: ${sanitized}`);
         return {
             ok: false,

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", "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", "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

@@ -18,6 +18,9 @@ export const ALLOWED_METHODS = [
     'set_exchange_credentials',
     'test_exchange_credentials',
     'clear_exchange_credentials',
+    // Hyperliquid guided onboarding (box-generated agent wallet) — operator.write-gated.
+    'hl_provision_agent_wallet',
+    'hl_agent_wallet_status',
     // Bracket-orders config (Phase 3.5b) — operator.write-gated.
     'get_bracket_config',
     'set_bracket_requirement',
@@ -33,6 +36,8 @@ export const OPERATOR_WRITE_METHODS = new Set([
     'set_exchange_credentials',
     'test_exchange_credentials',
     'clear_exchange_credentials',
+    'hl_provision_agent_wallet',
+    'hl_agent_wallet_status',
     'get_bracket_config',
     'set_bracket_requirement',
     'emergency.kill',

package/ccxt/binance-private.js

@@ -73,6 +73,12 @@ export class BinancePrivateApi {
     exchange;
     testnet;
     constructor(credentials) {
+        // apiKey/secret are optional on ExchangeConfig (an HL block carries a
+        // wallet pair instead) — this class is Binance-only and must never be
+        // constructed without the HMAC pair (mirrors HyperliquidPrivateApi's guard).
+        if (!credentials.apiKey || !credentials.secret) {
+            throw new Error('BinancePrivateApi requires exchange.apiKey + exchange.secret');
+        }
         this.testnet = credentials.testnet ?? false;
         const BinanceClass = ccxtCjs.binance ?? ccxtCjs.default?.binance;
         if (!BinanceClass) {

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

@@ -31,6 +31,10 @@ export const UNGOVERNABLE_TOOLS = new Set([
     'set_trading_mode',
     'get_bracket_config',
     'set_bracket_requirement',
+    // Hyperliquid guided onboarding (box-generated agent wallet) — same
+    // operator-only channel; disabling them would strand the HL setup flow.
+    'hl_provision_agent_wallet',
+    'hl_agent_wallet_status',
 ]);
 /** RC_TOOL_GATE: 'off' = kill-switch (gate never blocks), 'shadow' = log
  *  would-be blocks but execute anyway, anything else/default = 'enforce'.

package/index.js

@@ -66,6 +66,9 @@ import { getBracketConfigTool } from './tools/get-bracket-config.js';
 import { setBracketRequirementTool } from './tools/set-bracket-requirement.js';
 import { testExchangeCredentialsTool } from './tools/test-exchange-credentials.js';
 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 { ensureCredentialTransportKey } from './security/sealed-credentials.js';
 // Tool implementations
 import { fetchTickerTool } from './tools/fetch-ticker.js';
 import { fetchOhlcvTool } from './tools/fetch-ohlcv.js';
@@ -798,11 +801,15 @@ const TOOL_PARAMS = {
         type: 'object',
         properties: {
             operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
-            apiKey: { type: 'string', description: 'Binance API key' },
-            secret: { type: 'string', description: 'Binance API secret' },
-            testnet: { type: 'boolean', description: 'Use Binance testnet (default: false)' },
+            venue: { type: 'string', enum: ['binance', 'hyperliquid'], description: "Trading venue the credentials are for (default 'binance')" },
+            apiKey: { type: 'string', description: 'Binance API key (venue=binance)' },
+            secret: { type: 'string', description: 'Binance API secret (venue=binance)' },
+            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)' },
         },
-        required: ['apiKey', 'secret'],
     },
     set_trading_mode: {
         type: 'object',
@@ -817,11 +824,31 @@ const TOOL_PARAMS = {
         type: 'object',
         properties: {
             operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
-            apiKey: { type: 'string', description: 'Binance API key to verify (not persisted)' },
-            secret: { type: 'string', description: 'Binance API secret to verify (not persisted)' },
-            testnet: { type: 'boolean', description: 'Test against Binance testnet' },
+            venue: { type: 'string', enum: ['binance', 'hyperliquid'], description: "Trading venue to verify against (default 'binance')" },
+            apiKey: { type: 'string', description: 'Binance API key to verify (venue=binance; not persisted)' },
+            secret: { type: 'string', description: 'Binance API secret to verify (venue=binance; not persisted)' },
+            walletAddress: { type: 'string', description: 'Hyperliquid MASTER account address 0x… to verify (venue=hyperliquid; not persisted)' },
+            agentPrivateKey: { type: 'string', description: 'Hyperliquid AGENT wallet private key to verify (venue=hyperliquid; not persisted)' },
+            testnet: { type: 'boolean', description: 'Test against the venue testnet' },
+            sealed: { type: 'object', description: 'End-to-end encrypted credential envelope from the dashboard (replaces the plaintext fields; only this box can open it)' },
+        },
+    },
+    hl_provision_agent_wallet: {
+        type: 'object',
+        properties: {
+            operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
+            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: {
+        type: 'object',
+        properties: {
+            operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
+            probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
         },
-        required: ['apiKey', 'secret'],
     },
     clear_exchange_credentials: {
         type: 'object',
@@ -2639,13 +2666,13 @@ const paperTradingPlugin = {
             {
                 name: 'set_exchange_credentials',
                 label: 'Set Exchange Credentials',
-                description: 'Operator-only. Store Binance API key + secret in ~/.reefclaw/plugin-config.json. If current mode is live, reconnects the adapter. Refused without dashboard operator provenance.',
+                description: 'Operator-only. Store exchange credentials in ~/.reefclaw/plugin-config.json — Binance API key + secret, or Hyperliquid master address + agent wallet key (venue-selected). Same-venue live modes reconnect the adapter; a venue CHANGE is stored but requires an agent restart. Refused without dashboard operator provenance.',
                 parameters: TOOL_PARAMS.set_exchange_credentials,
                 execute: async (_id, params) => {
                     const prov = verifyOperatorProvenance(params.operator_token);
                     if (!prov.ok)
                         return jsonResult({ error: prov.error });
-                    return jsonResult(await setExchangeCredentialsTool(params, { runtime, adapterDeps }));
+                    return jsonResult(await setExchangeCredentialsTool(params, { runtime, adapterDeps, bootVenue: venue }));
                 },
             },
             {
@@ -2657,13 +2684,13 @@ const paperTradingPlugin = {
                     const prov = verifyOperatorProvenance(params.operator_token);
                     if (!prov.ok)
                         return jsonResult({ error: prov.error });
-                    return jsonResult(await setTradingModeTool(params, { runtime, adapterDeps }));
+                    return jsonResult(await setTradingModeTool(params, { runtime, adapterDeps, bootVenue: venue }));
                 },
             },
             {
                 name: 'test_exchange_credentials',
                 label: 'Test Exchange Credentials',
-                description: 'Operator-only. Verify a Binance API key + secret with a read-only call (fetchBalance) without persisting anything. Used by the dashboard pre-flight check before set_exchange_credentials. Refused without dashboard operator provenance.',
+                description: 'Operator-only. Verify candidate exchange credentials with read-only calls, per venue (Binance: fetchBalance permissions; Hyperliquid: master account state + agent-approval check), without persisting anything. Used by the dashboard pre-flight check before set_exchange_credentials. Refused without dashboard operator provenance.',
                 parameters: TOOL_PARAMS.test_exchange_credentials,
                 // Read-only, but provenance-gated anyway: it makes a live authenticated
                 // exchange call with caller-supplied keys, which would otherwise hand a
@@ -2687,6 +2714,35 @@ const paperTradingPlugin = {
                     return jsonResult(await clearExchangeCredentialsTool(params, { runtime, adapterDeps }));
                 },
             },
+            {
+                name: 'hl_provision_agent_wallet',
+                label: 'Provision Hyperliquid Agent Wallet',
+                description: 'Operator-only. Generate a Hyperliquid agent-wallet keypair ON THIS MACHINE (the private key never leaves it, nobody ever sees it) and return only the public address for the operator to approve on Hyperliquid. Idempotent — an existing wallet is returned, not replaced, unless {regenerate: true} (PAPER mode only). Refused without dashboard operator provenance.',
+                parameters: TOOL_PARAMS.hl_provision_agent_wallet,
+                execute: async (_id, params) => {
+                    const prov = verifyOperatorProvenance(params.operator_token);
+                    if (!prov.ok)
+                        return jsonResult({ error: prov.error });
+                    return jsonResult(await hlProvisionAgentWalletTool(params, { runtime, bootVenue: venue }));
+                },
+            },
+            {
+                name: 'hl_agent_wallet_status',
+                label: 'Hyperliquid Agent Wallet Status',
+                description: 'Operator-only. Report the provisioned Hyperliquid agent wallet (public address, approval status via extraAgents, expiry, master balance). The dashboard polls this after the operator signs the approval. Read-only, keyless exchange queries. Refused without dashboard operator provenance.',
+                parameters: TOOL_PARAMS.hl_agent_wallet_status,
+                execute: async (_id, params) => {
+                    // The probe path must answer BEFORE the provenance gate — tool
+                    // discovery has no operator token, and a provenance refusal is an
+                    // envelope-level error the prober can't tell apart from execution.
+                    if (params?.probe === true)
+                        return jsonResult(await hlAgentWalletStatusTool(params, {}));
+                    const prov = verifyOperatorProvenance(params.operator_token);
+                    if (!prov.ok)
+                        return jsonResult({ error: prov.error });
+                    return jsonResult(await hlAgentWalletStatusTool(params, { bootVenue: venue }));
+                },
+            },
             {
                 name: 'get_bracket_config',
                 label: 'Get Bracket Config',
@@ -2778,6 +2834,17 @@ const paperTradingPlugin = {
         // instead of a false green. Probes ONLY the configured venue — on a
         // Binance-451 host trading Hyperliquid a Binance probe would be a
         // permanent false alarm. Advisory + fire-and-forget; no token → no-op.
+        // Sealed credential transport (security/sealed-credentials.ts): make sure
+        // this box's static keypair exists BEFORE the first readiness report goes
+        // out — the report carries the PUBLIC half so the dashboard can encrypt
+        // credential payloads that only this box can open. Non-fatal: without a
+        // key the dashboard falls back to the legacy plaintext-over-TLS path.
+        try {
+            ensureCredentialTransportKey();
+        }
+        catch (err) {
+            logger.warn(TAG, `credential transport key setup failed (plaintext fallback stays available): ${formatError(err)}`);
+        }
         // Runs here once (guarded by the pluginInitialised early-return → once per
         // process) + on an unref'd interval inside the reporter.
         startReadinessReporter({

package/ingest/readiness-reporter.js

@@ -214,12 +214,36 @@ export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
         checks.push(makeReadinessCheck(reachId, 'unknown', { checkedAt: now }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
+    // Credential transport PUBLIC key (security/sealed-credentials.ts): riding
+    // the readiness report is what lets the dashboard encrypt credential
+    // payloads that only this box can open. Publishing the public half is the
+    // key's entire purpose — this is NOT an egress of secret material. Absent
+    // key (setup failed) → field omitted → dashboard falls back to plaintext.
+    let credentialPublicKey;
+    let credentialKeyId;
+    try {
+        const { getCredentialTransportPublicKey } = await import('../security/sealed-credentials.js');
+        const info = getCredentialTransportPublicKey();
+        if (info) {
+            credentialPublicKey = info.publicKeyBase64;
+            credentialKeyId = info.keyId;
+        }
+    }
+    catch {
+        // Best-effort — readiness must never fail on the transport key.
+    }
     return {
         schemaVersion: 1,
         generatedAt: now,
         overall: deriveOverallReadiness(checks),
         checks,
-        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount, venue: opts.venue },
+        agent: {
+            pluginVersion: PLUGIN_VERSION,
+            toolCount: opts.toolCount,
+            venue: opts.venue,
+            ...(credentialPublicKey ? { credentialPublicKey } : {}),
+            ...(credentialKeyId ? { credentialKeyId } : {}),
+        },
     };
 }
 async function postReadiness(apiBaseUrl, token, report, fetchImpl, timeoutMs) {

package/openclaw.plugin.json

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

package/package.json

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

package/security/sealed-credentials.d.ts

@@ -0,0 +1,38 @@
+export declare class SealedEnvelopeError extends Error {
+    /** 'key_mismatch' → the browser sealed to a stale/foreign key (refresh the
+     *  dashboard so it refetches this box's current key); 'malformed' → not a
+     *  v1 envelope; 'decrypt_failed' → tampered or corrupted in transit. */
+    readonly reason: 'key_mismatch' | 'malformed' | 'decrypt_failed';
+    constructor(message: string, 
+    /** 'key_mismatch' → the browser sealed to a stale/foreign key (refresh the
+     *  dashboard so it refetches this box's current key); 'malformed' → not a
+     *  v1 envelope; 'decrypt_failed' → tampered or corrupted in transit. */
+    reason: 'key_mismatch' | 'malformed' | 'decrypt_failed');
+}
+export interface SealedEnvelope {
+    v: 1;
+    /** First 16 hex chars of SHA-256(recipient public key, 65-byte uncompressed). */
+    kid: string;
+    /** Sender's ephemeral public key — base64, 65-byte uncompressed point. */
+    epk: string;
+    /** base64, 12 bytes. */
+    iv: string;
+    /** base64, ciphertext with the 16-byte GCM tag appended. */
+    ct: string;
+}
+export declare function computeKeyId(publicKeyRaw: Buffer): string;
+export interface TransportKeyInfo {
+    publicKeyBase64: string;
+    keyId: string;
+}
+/** Ensure the box's static transport keypair exists (generate + persist 0600 on
+ *  first run) and return the PUBLIC half for the readiness report. Never
+ *  returns or logs the private half. */
+export declare function ensureCredentialTransportKey(dir?: string): TransportKeyInfo;
+/** The PUBLIC half for the readiness report, or null when no key exists yet
+ *  (never generates — boot calls ensureCredentialTransportKey first). */
+export declare function getCredentialTransportPublicKey(dir?: string): TransportKeyInfo | null;
+/** Open a sealed credential envelope with this box's private transport key.
+ *  Returns the decrypted JSON payload (plain object). Throws
+ *  SealedEnvelopeError with a caller-renderable reason on any failure. */
+export declare function unsealCredentials(envelope: unknown, dir?: string): Record<string, unknown>;