@reefclaw/openclaw-plugin 0.1.19 → 0.1.21

package/tools/set-exchange-credentials.js

@@ -1,19 +1,66 @@
 // set_exchange_credentials — operator-only plugin tool.
 //
-// Writes Binance API key + secret to ~/.reefclaw/plugin-config.json and
-// triggers an adapter reconnect if the current mode is live. The agent
-// should NOT call this tool; it's registered for the skill's operator RPC
-// path only. PR2 will enforce that via a skill-side scope gate (operator.write).
+// Writes exchange credentials to ~/.reefclaw/plugin-config.json — per VENUE:
+//   binance (default when `venue` is absent — every legacy caller byte-identical):
+//     apiKey + secret (HMAC pair).
+//   hyperliquid: walletAddress (MASTER, 0x… — queries/funds; NEVER its private
+//     key) + agentPrivateKey (an approved agent/API wallet key — signs only).
+//
+// The `exchange` block is replaced WHOLESALE (the documented contract in
+// plugin-config-io.ts) — storing credentials for one venue deliberately removes
+// the other venue's keys from disk, and `venue` is always carried through so
+// the historical footgun (a Binance-shaped write silently reverting an HL box
+// to the binance default) is impossible from the venue-tabbed dashboard.
+//
+// Venue CHANGE is restart-required: the paper market feed, symbols, quote
+// currency, and readiness prober are venue-wired at register() (plan §5.2).
+// When the requested venue differs from the venue this process booted with, the
+// credentials are written but NO reconnect happens — the result carries
+// `restartRequired: true` and the dashboard tells the operator to restart the
+// agent (`/restart` in chat). Same-venue behavior is unchanged: PAPER stores
+// without activating; live modes hot-reconnect the adapter.
 //
 // Security:
-//   - The secret is NEVER logged. Only a redacted fingerprint (first 4 + last 2
-//     chars of the apiKey) goes to logs / audit.
-//   - If the current mode is PAPER, credentials are written but NOT activated —
-//     the operator must explicitly call set_trading_mode to move up the ladder.
+//   - Secrets (Binance secret / HL agent key) are NEVER logged. Only a redacted
+//     fingerprint (Binance apiKey prefix, or the PUBLIC master address for HL)
+//     goes to logs / audit.
+//   - The HL arm derives the address the pasted agent key controls and REFUSES
+//     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 { 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';
 import { logger } from '../logger.js';
 const TAG = 'set-exchange-credentials';
-function validate(args) {
+/** Open a sealed envelope into plain args, or return a renderable error. */
+export function resolveSealedArgs(args, configDir) {
+    if (args?.sealed == null)
+        return { args, sealed: false };
+    try {
+        const plain = unsealCredentials(args.sealed, configDir);
+        return { args: plain, sealed: true };
+    }
+    catch (err) {
+        const message = err instanceof SealedEnvelopeError
+            ? `Encrypted credentials could not be opened: ${err.message}`
+            : 'Encrypted credentials could not be opened — try again';
+        return { error: message };
+    }
+}
+function fail(message, fingerprint, deps, venue) {
+    return {
+        ok: false,
+        message,
+        fingerprint,
+        reconnected: false,
+        mode: deps.runtime.mode,
+        readiness: deps.runtime.adapter.readiness,
+        ...(venue ? { venue } : {}),
+    };
+}
+function validateBinance(args) {
     if (typeof args.apiKey !== 'string' || args.apiKey.trim().length < 8) {
         return 'apiKey must be a string of at least 8 characters';
     }
@@ -25,56 +72,121 @@ function validate(args) {
     }
     return null;
 }
-export async function setExchangeCredentialsTool(args, deps) {
-    const validationError = validate(args);
+function validateHyperliquid(args) {
+    if (!isHexAddress(args.walletAddress)) {
+        return 'walletAddress must be your MASTER account address: 0x followed by 40 hex characters';
+    }
+    if (!isHexPrivateKey(args.agentPrivateKey)) {
+        return 'agentPrivateKey must be an agent (API) wallet private key: 64 hex characters (0x prefix optional)';
+    }
+    if (args.testnet !== undefined && typeof args.testnet !== 'boolean') {
+        return 'testnet must be a boolean when provided';
+    }
+    return null;
+}
+export async function setExchangeCredentialsTool(rawArgs, deps) {
+    const resolved = resolveSealedArgs(rawArgs, deps.transportKeyDir);
+    if ('error' in resolved) {
+        return fail(resolved.error, '(sealed)', deps);
+    }
+    const args = resolved.args;
+    const venue = parseVenue(args.venue).venue;
+    const bootVenue = deps.bootVenue ?? 'binance';
+    const validationError = venue === 'hyperliquid' ? validateHyperliquid(args) : validateBinance(args);
     if (validationError) {
-        return {
-            ok: false,
-            message: validationError,
-            fingerprint: '(not-set)',
-            reconnected: false,
-            mode: deps.runtime.mode,
-            readiness: deps.runtime.adapter.readiness,
+        return fail(validationError, '(not-set)', deps, venue);
+    }
+    let exchange;
+    let fingerprint;
+    if (venue === 'hyperliquid') {
+        const walletAddress = args.walletAddress.trim();
+        const agentPrivateKey = normalizeHexPrivateKey(args.agentPrivateKey);
+        // The one unrecoverable mistake: the pasted "agent key" controls the MASTER
+        // address ⇒ the user pasted their master wallet's private key. Refuse to
+        // persist it. Derivation-unavailable fails OPEN (store proceeds).
+        const derived = await deriveAddressFromPrivateKey(agentPrivateKey);
+        if (derived.ok && sameAddress(derived.address, walletAddress)) {
+            return fail('REFUSED: that private key controls the master wallet address you entered — you pasted your ' +
+                'MASTER wallet key, which can withdraw funds. Never share it. In the Hyperliquid app open ' +
+                'More → API, generate an agent wallet, approve it, and paste the AGENT key instead.', redactCredential(walletAddress), deps, venue);
+        }
+        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,
         };
+        // 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 {
+        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);
     }
-    const exchange = {
-        apiKey: args.apiKey.trim(),
-        secret: args.secret.trim(),
-        testnet: args.testnet ?? false,
-    };
-    const fingerprint = redactCredential(exchange.apiKey);
     try {
         updatePluginConfig({ exchange }, deps.configPath);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         logger.error(TAG, `Failed to write credentials: ${msg}`);
+        return fail(`Failed to persist credentials: ${msg}`, fingerprint, deps, venue);
+    }
+    logger.info(TAG, `Stored ${venue} credentials (fingerprint: ${fingerprint}, testnet: ${exchange.testnet === true})`);
+    // Venue change: the paper feed / symbols / quote currency / readiness prober
+    // are wired to the BOOT venue — hot-reconnecting a live adapter into a
+    // different venue would run it on top of the old venue's paper stack. Write,
+    // don't activate; the restart applies everything coherently.
+    if (venue !== bootVenue) {
         return {
-            ok: false,
-            message: `Failed to persist credentials: ${msg}`,
+            ok: true,
+            message: `Credentials stored and venue set to ${venue} — restart your agent to apply ` +
+                `(send /restart to your agent in chat, or restart the OpenClaw service)`,
             fingerprint,
             reconnected: false,
             mode: deps.runtime.mode,
             readiness: deps.runtime.adapter.readiness,
+            venue,
+            restartRequired: true,
         };
     }
-    logger.info(TAG, `Stored credentials (fingerprint: ${fingerprint}, testnet: ${exchange.testnet})`);
-    // Only reconnect if we're already in a live mode — if the operator is still
-    // in PAPER, activating the keys is a separate deliberate step via
-    // set_trading_mode. This prevents accidentally going live by saving keys.
+    // Same venue: only reconnect if we're already in a live mode — if the
+    // operator is still in PAPER, activating the keys is a separate deliberate
+    // step via set_trading_mode. This prevents accidentally going live by saving
+    // keys.
     let reconnected = false;
     if (deps.runtime.mode !== 'PAPER') {
-        await deps.runtime.reconnect({ mode: deps.runtime.mode, exchange }, { adapterDeps: deps.adapterDeps });
+        const hlCredentials = venue === 'hyperliquid'
+            ? {
+                walletAddress: exchange.walletAddress,
+                agentPrivateKey: exchange.agentPrivateKey,
+                testnet: exchange.testnet === true,
+            }
+            : null;
+        await deps.runtime.reconnect(venue === 'hyperliquid'
+            ? { mode: deps.runtime.mode, exchange: null, venue, hlCredentials }
+            : { mode: deps.runtime.mode, exchange }, { adapterDeps: deps.adapterDeps });
         reconnected = true;
     }
     return {
         ok: true,
         message: reconnected
             ? `Credentials updated and ${deps.runtime.mode} adapter reconnected`
-            : `Credentials stored (mode is PAPER — run set_trading_mode SHADOW to activate)`,
+            : `Credentials stored (mode is PAPER — run set_trading_mode to activate)`,
         fingerprint,
         reconnected,
         mode: deps.runtime.mode,
         readiness: deps.runtime.adapter.readiness,
+        venue,
+        restartRequired: false,
     };
 }

package/tools/set-trading-mode.d.ts

@@ -1,6 +1,7 @@
 import type { PluginRuntime } from '../onboarding/runtime.js';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { TradingMode } from '../types.js';
+import { type VenueId } from '../venues/registry.js';
 export interface SetTradingModeArgs {
     mode: TradingMode;
     /** Optional acknowledgment flag for going live. The skill layer will set
@@ -20,6 +21,12 @@ export interface SetTradingModeDeps {
     adapterDeps: {
         adapter: IExchangeAdapter;
     };
+    /** The venue this process booted with. When the CONFIG venue differs (the
+     *  operator stored credentials for another venue but hasn't restarted), a
+     *  live flip is refused — the paper feed/symbols/readiness stack is still
+     *  wired to the boot venue and a mixed-venue runtime is not a valid state.
+     *  Absent (legacy tests) → guard skipped. */
+    bootVenue?: VenueId;
     /** Override the config file path — tests use this. */
     configPath?: string;
 }

package/tools/set-trading-mode.js

@@ -92,6 +92,21 @@ export async function setTradingModeTool(args, deps) {
                 reason: 'config_read_error',
             };
         }
+        // Venue-change-pending guard: credentials for a NEW venue were stored but
+        // the gateway hasn't restarted, so the paper/readiness stack is still on
+        // the boot venue. Refuse the live flip rather than build a mixed stack.
+        if (deps.bootVenue && venue !== deps.bootVenue) {
+            recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'venue_restart_required' });
+            return {
+                ok: false,
+                message: `The configured venue (${venue}) differs from the venue this agent booted with (${deps.bootVenue}). ` +
+                    `Restart your agent first (send /restart to your agent in chat, or restart the OpenClaw service), then go ${target}.`,
+                previousMode,
+                mode: previousMode,
+                readiness: deps.runtime.adapter.readiness,
+                reason: 'venue_restart_required',
+            };
+        }
         if (!exchange && !hlCredentials) {
             recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'missing_credentials' });
             return {

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

@@ -1,7 +1,14 @@
+import { type VenueId } from '../venues/registry.js';
 export interface TestExchangeCredentialsArgs {
-    apiKey: string;
-    secret: string;
+    /** Absent → 'binance' (legacy callers unchanged). */
+    venue?: string;
+    apiKey?: string;
+    secret?: string;
+    walletAddress?: string;
+    agentPrivateKey?: string;
     testnet?: boolean;
+    /** End-to-end encrypted envelope — sole source of fields when present. */
+    sealed?: unknown;
 }
 export interface TestExchangeCredentialsResult {
     ok: boolean;
@@ -9,8 +16,28 @@ export interface TestExchangeCredentialsResult {
     fingerprint: string;
     canReadBalance: boolean;
     canReadPositions: boolean;
+    /** Account balance in the venue's quote currency (USDT on Binance, USDC on
+     *  Hyperliquid — perp equity + spot USDC). Field name is historical. */
     balanceUSDT: number | null;
     testnet: boolean;
     errors: string[];
+    /** Venue the credentials were tested against. */
+    venue?: VenueId;
+    /** HL only: the address the pasted agent key controls (public). */
+    agentAddress?: string;
+    /** HL only: true/false when extraAgents answered definitively; null when the
+     *  approval list could not be checked (derivation or endpoint unavailable). */
+    agentApproved?: boolean | null;
+    /** HL only: approval expiry (epoch ms) when the exchange reports one. */
+    agentValidUntil?: number | null;
+    /** Non-fatal findings the dashboard should surface (expiring approval,
+     *  unfunded account, unverifiable approval, …). */
+    warnings?: string[];
 }
-export declare function testExchangeCredentialsTool(args: TestExchangeCredentialsArgs): Promise<TestExchangeCredentialsResult>;
+/** Injectable for tests; production uses global fetch. */
+export interface TestExchangeCredentialsDeps {
+    fetchImpl?: typeof fetch;
+    /** Override the transport-key directory (sealed envelopes) — tests use this. */
+    transportKeyDir?: string;
+}
+export declare function testExchangeCredentialsTool(rawArgs: TestExchangeCredentialsArgs, deps?: TestExchangeCredentialsDeps): Promise<TestExchangeCredentialsResult>;

package/tools/test-exchange-credentials.js

@@ -1,21 +1,38 @@
 // test_exchange_credentials — operator-only plugin tool.
 //
-// Takes a candidate Binance API key + secret and verifies them with a
-// transient, read-only call to the exchange (fetchBalance via
-// validatePermissions). Nothing is written to disk. Nothing is retained
-// after the call returns. This is the "pre-flight" check that lets the
-// dashboard say "yes these keys work, you can now click Store" before
-// the operator commits the credentials via set_exchange_credentials.
+// Pre-flight verification of candidate credentials, per VENUE. Nothing is
+// written to disk; nothing is retained after the call returns. This is what
+// lets the dashboard say "yes these credentials work, you can now click Store"
+// before the operator commits them via set_exchange_credentials.
+//
+//   binance (default when `venue` is absent — legacy callers byte-identical):
+//     transient BinancePrivateApi, read-only validatePermissions + fetchBalance.
+//   hyperliquid: entirely UNSIGNED verification (HL /info reads are keyless):
+//     1. derive the address the pasted agent key controls — if it equals the
+//        master walletAddress the user pasted their MASTER key: hard refuse.
+//     2. clearinghouseState(master) → the account's perp equity (+ spot USDC
+//        via spotClearinghouseState — the unified account collateralizes perps
+//        from spot, verified live on testnet 2026-07-12).
+//     3. extraAgents(master) → is the derived agent address APPROVED, and when
+//        does the approval expire (named agents carry validUntil, max 180d —
+//        plan §3.2)? extraAgents shape verified against Chainstack/QuickNode
+//        HL API references 2026-08-01: [{ name, address, validUntil(ms) }].
+//     Endpoint failures degrade to warnings (fail-open on infra); a definitive
+//     "agent not in the approved list" is a hard fail with guidance.
 //
 // Security:
-//   - Builds a throwaway BinancePrivateApi instance scoped to one call.
-//   - Never logs the secret — only a redacted fingerprint.
+//   - Never logs the secret / agent key — only a redacted fingerprint (the
+//     PUBLIC master address for HL).
 //   - Does not touch plugin-config.json at all.
 import { BinancePrivateApi } from '../ccxt/binance-private.js';
 import { redactCredential } from '../config/plugin-config-io.js';
+import { deriveAddressFromPrivateKey, isHexAddress, isHexPrivateKey, normalizeHexPrivateKey, sameAddress, } from '../venues/hyperliquid/hl-agent-wallet.js';
+import { hlPreflight } from '../venues/hyperliquid/hl-preflight.js';
+import { parseVenue } from '../venues/registry.js';
+import { resolveSealedArgs } from './set-exchange-credentials.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'test-exchange-credentials';
-function validate(args) {
+function validateBinance(args) {
     if (typeof args.apiKey !== 'string' || args.apiKey.trim().length < 8) {
         return 'apiKey must be a string of at least 8 characters';
     }
@@ -24,43 +41,49 @@ function validate(args) {
     }
     return null;
 }
-export async function testExchangeCredentialsTool(args) {
-    const fingerprint = redactCredential(args.apiKey);
-    const err = validate(args);
+function baseResult(overrides, testnet) {
+    return {
+        canReadBalance: false,
+        canReadPositions: false,
+        balanceUSDT: null,
+        testnet,
+        errors: overrides.ok ? [] : [overrides.message],
+        ...overrides,
+    };
+}
+export async function testExchangeCredentialsTool(rawArgs, deps = {}) {
+    const resolved = resolveSealedArgs(rawArgs, deps.transportKeyDir);
+    if ('error' in resolved) {
+        return baseResult({ ok: false, message: resolved.error, fingerprint: '(sealed)' }, rawArgs?.testnet === true);
+    }
+    const args = resolved.args;
+    const venue = parseVenue(args.venue).venue;
+    if (venue === 'hyperliquid') {
+        return testHyperliquid(args, deps);
+    }
+    return testBinance(args);
+}
+// ---- Binance arm (unchanged behavior) ----
+async function testBinance(args) {
+    const fingerprint = redactCredential(typeof args.apiKey === 'string' ? args.apiKey : '');
+    const testnet = args.testnet ?? false;
+    const err = validateBinance(args);
     if (err) {
-        return {
-            ok: false,
-            message: err,
-            fingerprint,
-            canReadBalance: false,
-            canReadPositions: false,
-            balanceUSDT: null,
-            testnet: args.testnet ?? false,
-            errors: [err],
-        };
+        return baseResult({ ok: false, message: err, fingerprint, venue: 'binance' }, testnet);
     }
     const config = {
         apiKey: args.apiKey.trim(),
         secret: args.secret.trim(),
-        testnet: args.testnet ?? false,
+        testnet,
     };
-    logger.info(TAG, `Testing credentials (fingerprint: ${fingerprint}, testnet: ${config.testnet})`);
+    logger.info(TAG, `Testing binance credentials (fingerprint: ${fingerprint}, testnet: ${testnet})`);
     let api;
     try {
         api = new BinancePrivateApi(config);
     }
     catch (e) {
         const msg = formatError(e);
-        return {
-            ok: false,
-            message: `Could not initialize exchange client: ${msg}`,
-            fingerprint,
-            canReadBalance: false,
-            canReadPositions: false,
-            balanceUSDT: null,
-            testnet: config.testnet ?? false,
-            errors: [msg],
-        };
+        return baseResult({ ok: false, message: `Could not initialize exchange client: ${msg}`, fingerprint, errors: [msg], venue: 'binance' }, testnet);
     }
     const perms = await api.validatePermissions();
     // Opportunistically read the balance for the result payload — if
@@ -94,7 +117,122 @@ export async function testExchangeCredentialsTool(args) {
         canReadBalance: perms.canReadBalance,
         canReadPositions: perms.canReadPositions,
         balanceUSDT,
-        testnet: config.testnet ?? false,
+        testnet,
         errors: perms.errors,
+        venue: 'binance',
+    };
+}
+// ---- Hyperliquid arm ----
+async function testHyperliquid(args, deps) {
+    const testnet = args.testnet ?? false;
+    const fingerprint = isHexAddress(args.walletAddress)
+        ? redactCredential(args.walletAddress.trim())
+        : '(not-set)';
+    if (!isHexAddress(args.walletAddress)) {
+        return baseResult({
+            ok: false,
+            message: 'walletAddress must be your MASTER account address: 0x followed by 40 hex characters',
+            fingerprint,
+            venue: 'hyperliquid',
+        }, testnet);
+    }
+    if (!isHexPrivateKey(args.agentPrivateKey)) {
+        return baseResult({
+            ok: false,
+            message: 'agentPrivateKey must be an agent (API) wallet private key: 64 hex characters (0x prefix optional)',
+            fingerprint,
+            venue: 'hyperliquid',
+        }, testnet);
+    }
+    const walletAddress = args.walletAddress.trim();
+    const agentPrivateKey = normalizeHexPrivateKey(args.agentPrivateKey);
+    const warnings = [];
+    logger.info(TAG, `Testing hyperliquid credentials (master: ${fingerprint}, testnet: ${testnet})`);
+    // 1. Master-key-pasted refusal + agent address for the approval check.
+    let agentAddress;
+    const derived = await deriveAddressFromPrivateKey(agentPrivateKey);
+    if (derived.ok) {
+        if (sameAddress(derived.address, walletAddress)) {
+            return baseResult({
+                ok: false,
+                message: 'REFUSED: that private key controls the master wallet address you entered — you pasted your ' +
+                    'MASTER wallet key, which can withdraw funds. Never share it. In the Hyperliquid app open ' +
+                    'More → API, generate an agent wallet, approve it, and paste the AGENT key instead.',
+                fingerprint,
+                venue: 'hyperliquid',
+            }, testnet);
+        }
+        agentAddress = derived.address;
+    }
+    else if (derived.reason === 'invalid_key') {
+        return baseResult({
+            ok: false,
+            message: 'agentPrivateKey is not a valid secp256k1 private key — re-copy it from the Hyperliquid API page',
+            fingerprint,
+            venue: 'hyperliquid',
+        }, testnet);
+    }
+    else {
+        warnings.push('Could not derive the agent wallet address on this host — approval not verified.');
+    }
+    // 2+3. Master account state + agent approval — the shared unsigned preflight
+    // (hl-preflight.ts, also used by hl_agent_wallet_status).
+    const pre = await hlPreflight({
+        walletAddress,
+        agentAddress: agentAddress ?? null,
+        testnet,
+        fetchImpl: deps.fetchImpl,
+    });
+    warnings.push(...pre.warnings);
+    if (!pre.reachable) {
+        const msg = pre.unreachableError ?? 'unknown error';
+        return baseResult({
+            ok: false,
+            message: `Could not reach Hyperliquid to verify the master account: ${msg}`,
+            fingerprint,
+            venue: 'hyperliquid',
+            agentAddress,
+            errors: [msg],
+        }, testnet);
+    }
+    const canReadBalance = pre.balanceUSDC != null;
+    const balanceUSDC = pre.balanceUSDC;
+    const agentApproved = pre.agentApproved;
+    const agentValidUntil = pre.agentValidUntil;
+    if (agentApproved === false) {
+        const msg = 'This agent key is NOT approved for the master account (or the approval expired). ' +
+            'In the Hyperliquid app open More → API and approve the agent wallet, then test again.';
+        return {
+            ok: false,
+            message: msg,
+            fingerprint,
+            canReadBalance,
+            canReadPositions: canReadBalance,
+            balanceUSDT: balanceUSDC,
+            testnet,
+            errors: [msg],
+            venue: 'hyperliquid',
+            agentAddress,
+            agentApproved,
+            agentValidUntil,
+            warnings,
+        };
+    }
+    const balanceText = balanceUSDC != null ? balanceUSDC.toFixed(2) : 'unknown';
+    const approvalText = agentApproved === true ? 'agent wallet approved' : 'agent approval not verified';
+    return {
+        ok: true,
+        message: `Connection verified — USDC balance: ${balanceText}, ${approvalText}`,
+        fingerprint,
+        canReadBalance,
+        canReadPositions: canReadBalance,
+        balanceUSDT: balanceUSDC,
+        testnet,
+        errors: [],
+        venue: 'hyperliquid',
+        agentAddress,
+        agentApproved,
+        agentValidUntil,
+        warnings,
     };
 }

package/types.d.ts

@@ -111,23 +111,22 @@ export declare const DEFAULT_CONFIG: PluginConfig;
  *  `exchange` block (openclaw.json legacy fallback). Which fields matter
  *  depends on `venue` (docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.2):
  *
- *    binance (default, and the only live-supported venue until Phase 3) —
- *      apiKey + secret (HMAC pair) are required; walletAddress/agentPrivateKey
- *      are ignored.
+ *    binance (default) — apiKey + secret (HMAC pair) are required;
+ *      walletAddress/agentPrivateKey are ignored.
  *    hyperliquid — walletAddress (MASTER wallet address, 0x…, used for
  *      queries; never its private key) + agentPrivateKey (an approved
  *      agent/API wallet's key — signs orders, cannot withdraw). apiKey/secret
- *      are meaningless. Boot falls back to PAPER for this venue until the
- *      Phase 3 adapter ships.
+ *      are absent — an HL block never carries a Binance HMAC pair.
  *
- *  apiKey/secret stay required at the type level because every constructed
- *  instance today feeds BinancePrivateApi; the on-disk JSON is parsed, not
- *  type-constructed, so an HL block without them is readable. Phase 3
- *  restructures this into a per-venue discriminated union. */
+ *  apiKey/secret are optional at the type level because the on-disk shape is
+ *  per-venue: every Binance consumer (index.ts boot, set_trading_mode,
+ *  set_exchange_credentials) truthiness-guards the pair before constructing a
+ *  BinancePrivateApi, so an HL block without them is both readable AND
+ *  writable. */
 export interface ExchangeConfig {
     venue?: 'binance' | 'hyperliquid';
-    apiKey: string;
-    secret: string;
+    apiKey?: string;
+    secret?: string;
     testnet?: boolean;
     walletAddress?: string;
     agentPrivateKey?: string;

package/venues/hyperliquid/hl-agent-wallet.d.ts

@@ -0,0 +1,29 @@
+/** Generate a fresh secp256k1 private key (0x-prefixed, 64 hex chars) from
+ *  CSPRNG bytes, rejection-sampled into the valid scalar range. This is how
+ *  the box mints its own HL agent wallet — the key is BORN here and never
+ *  leaves the machine (the caller persists it to plugin-config and surfaces
+ *  only the derived PUBLIC address). */
+export declare function generateAgentPrivateKey(): string;
+/** Master/agent wallet address: 0x + 40 hex chars. */
+export declare function isHexAddress(value: unknown): value is string;
+/** Agent private key: 32 bytes of hex, 0x prefix optional (the HL app shows it
+ *  with the prefix; some wallets export without). */
+export declare function isHexPrivateKey(value: unknown): value is string;
+/** Canonical stored form: trimmed, 0x-prefixed, original casing preserved. */
+export declare function normalizeHexPrivateKey(value: string): string;
+export type DeriveAddressResult = {
+    ok: true;
+    address: string;
+} | {
+    ok: false;
+    reason: 'invalid_key' | 'unavailable';
+};
+/** Test seam: reset the memoized keccak loader (unit tests only). */
+export declare function __resetKeccakCacheForTests(): void;
+/** Derive the Ethereum address a private key controls (lowercase 0x…40 hex).
+ *  'invalid_key' = the key is malformed or outside the secp256k1 range;
+ *  'unavailable' = the keccak dependency could not be loaded (callers must
+ *  fail OPEN — skip the check, never block credential entry on infra). */
+export declare function deriveAddressFromPrivateKey(privateKey: string): Promise<DeriveAddressResult>;
+/** Case-insensitive address equality (addresses may arrive checksummed). */
+export declare function sameAddress(a: string, b: string): boolean;