@agentlayer.tech/wallet 0.1.12 → 0.1.14

package/.openclaw/AGENTS.md

@@ -4,17 +4,25 @@
 These instructions apply to the entire `.openclaw/` tree.
 
 ## Purpose
-This tree contains local OpenClaw host-side workspace assets. In the current repo, its primary responsibility is the `agent-wallet` extension that bridges OpenClaw to the authoritative Python `agent-wallet` backend.
+This tree contains local OpenClaw host-side workspace assets. In the current repo, its main responsibilities are:
+
+- the `agent-wallet` extension that bridges OpenClaw to the authoritative Python `agent-wallet` backend
+- the `pay-bridge` extension that bridges OpenClaw to the local `pay` CLI for paid API discovery and execution
 
 ## Current structure
 - `.openclaw/extensions/agent-wallet/index.ts` — TypeScript extension entrypoint registered by OpenClaw.
 - `.openclaw/extensions/agent-wallet/openclaw.plugin.json` — plugin manifest and config schema.
 - `.openclaw/extensions/agent-wallet/package.json` — extension package metadata.
 - `.openclaw/extensions/agent-wallet/skills/wallet-operator/SKILL.md` — user-facing operational wallet safety guidance.
+- `.openclaw/extensions/pay-bridge/index.ts` — TypeScript entrypoint for the local `pay` CLI bridge.
+- `.openclaw/extensions/pay-bridge/openclaw.plugin.json` — plugin manifest and config schema for pay tools.
+- `.openclaw/extensions/pay-bridge/core.mjs` — local `pay` command execution and output shaping.
+- `.openclaw/extensions/pay-bridge/skills/pay-operator/SKILL.md` — user-facing operational guidance for paid API usage.
 
 ## Design intent
 - Keep the TypeScript extension thin and host-oriented.
 - Let Python own wallet logic, policy, approvals, signing rules, and Solana implementation details.
+- Let `pay` remain the source of truth for paid API wallet/account behavior.
 - Let the extension focus on:
   - resolving config
   - locating the Python package
@@ -27,6 +35,7 @@ This tree contains local OpenClaw host-side workspace assets. In the current rep
 
 ### Keep bridge logic thin
 - Do not duplicate business logic from Python unless OpenClaw requires it at registration time.
+- Do not duplicate payment protocol logic from `pay`; prefer invoking the local CLI and shaping its output.
 - Do not reimplement approval validation, transaction policy, wallet derivation, or Solana-specific rules in TypeScript.
 - Prefer forwarding config into the CLI bridge and letting Python decide runtime behavior.
 - Treat this layer as a transport and schema bridge, not an execution authority.

package/.openclaw/extensions/agent-wallet/index.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -10,6 +11,182 @@ let selectedWalletBackend = null;
 let selectedSolanaNetwork = null;
 let selectedEvmNetwork = null;
 let selectedBtcNetwork = null;
+const PREVIEW_CACHE_TTL_MS = 15 * 60 * 1000;
+const PRIVATE_SWAP_CACHE_TTL_MS = 35 * 60 * 1000;
+const PREVIEW_BOUND_SWAP_TOOLS = new Set(["swap_solana_tokens", "swap_solana_privately"]);
+const PRIVATE_SWAP_APPROVAL_TOOL_NAME = "swap_solana_privately";
+const approvalPreviewCache = new Map();
+const privateSwapOrderCache = new Map();
+const WALLET_TOOL_ONLY_GUIDANCE =
+  "Use this wallet tool instead of shelling out to solana CLI, spl-token CLI, curl, or exec. If it fails, surface the wallet-tool error and stop rather than falling back to terminal commands.";
+
+function canonicalJsonText(payload) {
+  const normalize = (value) => {
+    if (Array.isArray(value)) {
+      return value.map(normalize);
+    }
+    if (value && typeof value === "object") {
+      return Object.fromEntries(
+        Object.keys(value)
+          .sort()
+          .map((key) => [key, normalize(value[key])])
+      );
+    }
+    return value;
+  };
+  return JSON.stringify(normalize(payload));
+}
+
+function previewDigest(preview) {
+  return crypto.createHash("sha256").update(canonicalJsonText(preview), "utf8").digest("hex");
+}
+
+function approvalCacheKey(userId, toolName) {
+  return `${userId}::${toolName}`;
+}
+
+function pruneApprovalPreviewCache() {
+  const now = Date.now();
+  for (const [key, value] of approvalPreviewCache.entries()) {
+    if (!value || typeof value !== "object" || Number(value.expiresAt || 0) <= now) {
+      approvalPreviewCache.delete(key);
+    }
+  }
+}
+
+function cachePreviewForApproval(userId, toolName, payload) {
+  if (!payload || payload.ok !== true || !payload.data || typeof payload.data !== "object") return;
+  const preview = payload.data;
+  if (preview.mode !== "preview") return;
+  if (!preview.confirmation_summary || typeof preview.confirmation_summary !== "object") return;
+  pruneApprovalPreviewCache();
+  const digest = previewDigest(preview);
+  approvalPreviewCache.set(approvalCacheKey(userId, toolName), {
+    digest,
+    expiresAt:
+      toolName === "swap_solana_privately"
+        ? Date.now() + PRIVATE_SWAP_CACHE_TTL_MS
+        : Date.now() + PREVIEW_CACHE_TTL_MS,
+    preview,
+    summary: preview.confirmation_summary,
+  });
+  if (toolName === "swap_solana_privately") {
+    privateSwapOrderCache.delete(approvalCacheKey(userId, toolName));
+  }
+}
+
+function latestCachedPreview(userId, toolName) {
+  pruneApprovalPreviewCache();
+  return approvalPreviewCache.get(approvalCacheKey(userId, toolName)) || null;
+}
+
+function approvalTokenPreviewDigest(token) {
+  if (typeof token !== "string" || !token.includes(".")) return "";
+  try {
+    const encoded = token.split(".", 1)[0];
+    const payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    const summary = payload?.binding?.summary;
+    return summary && typeof summary._preview_digest === "string" ? summary._preview_digest : "";
+  } catch {
+    return "";
+  }
+}
+
+function cachedPreviewForToken(userId, toolName, token) {
+  const digest = approvalTokenPreviewDigest(token);
+  if (!digest) return null;
+  const cached = latestCachedPreview(userId, toolName);
+  if (!cached || cached.digest !== digest) return null;
+  return cached.preview && typeof cached.preview === "object" ? cached.preview : null;
+}
+
+function cachePendingPrivateSwapOrder(userId, toolName, preview, details) {
+  if (toolName !== "swap_solana_privately") return;
+  if (!preview || typeof preview !== "object") return;
+  if (!details || typeof details !== "object") return;
+  const houdiniId = typeof details.houdini_id === "string" ? details.houdini_id.trim() : "";
+  const depositAddress =
+    typeof details.deposit_address === "string" ? details.deposit_address.trim() : "";
+  if (!houdiniId || !depositAddress) return;
+  privateSwapOrderCache.set(approvalCacheKey(userId, toolName), {
+    digest: previewDigest(preview),
+    expiresAt: Date.now() + PRIVATE_SWAP_CACHE_TTL_MS,
+    order: {
+      multi_id: typeof details.multi_id === "string" ? details.multi_id.trim() : null,
+      houdini_id: houdiniId,
+      deposit_address: depositAddress,
+      order: details.order && typeof details.order === "object" ? details.order : {},
+    },
+  });
+}
+
+function latestPendingPrivateSwapOrder(userId, toolName, preview) {
+  if (toolName !== "swap_solana_privately") return null;
+  const cached = privateSwapOrderCache.get(approvalCacheKey(userId, toolName));
+  if (!cached || typeof cached !== "object") return null;
+  if (Number(cached.expiresAt || 0) <= Date.now()) {
+    privateSwapOrderCache.delete(approvalCacheKey(userId, toolName));
+    return null;
+  }
+  if (!preview || typeof preview !== "object") return null;
+  if (cached.digest !== previewDigest(preview)) return null;
+  return cached.order && typeof cached.order === "object" ? cached.order : null;
+}
+
+function clearPendingPrivateSwapOrder(userId, toolName) {
+  if (toolName !== "swap_solana_privately") return;
+  privateSwapOrderCache.delete(approvalCacheKey(userId, toolName));
+}
+
+function formatPrivateSwapPendingOrderError(details) {
+  const houdiniId = typeof details?.houdini_id === "string" ? details.houdini_id.trim() : "";
+  const multiId = typeof details?.multi_id === "string" ? details.multi_id.trim() : "";
+  const depositAddress =
+    typeof details?.deposit_address === "string" ? details.deposit_address.trim() : "";
+  const orderStatus =
+    typeof details?.order_status === "string" ? details.order_status.trim() : "";
+  const parts = [
+    "Houdini order was created, but the Solana deposit account is not ready yet.",
+  ];
+  if (houdiniId) parts.push(`houdini_id=${houdiniId}`);
+  if (multiId) parts.push(`multi_id=${multiId}`);
+  if (depositAddress) parts.push(`deposit_address=${depositAddress}`);
+  if (orderStatus) parts.push(`status=${orderStatus}`);
+  parts.push("Retry execute for this existing order instead of generating a new preview.");
+  return parts.join(" ");
+}
+
+function formatPrivateSwapRateLimitError(details) {
+  const retryAfter =
+    typeof details?.retry_after === "number"
+      ? details.retry_after
+      : typeof details?.retry_after === "string"
+        ? details.retry_after
+        : "";
+  const quoteId = typeof details?.quote_id === "string" ? details.quote_id.trim() : "";
+  const parts = [
+    "Houdini exchange create is rate-limited right now.",
+  ];
+  if (retryAfter !== "") parts.push(`retry_after=${retryAfter}s`);
+  if (quoteId) parts.push(`quote_id=${quoteId}`);
+  parts.push("Do not generate a new preview yet; wait, then retry execute.");
+  return parts.join(" ");
+}
+
+function listPendingPrivateSwapOrders(userId) {
+  const key = approvalCacheKey(userId, PRIVATE_SWAP_APPROVAL_TOOL_NAME);
+  const pending = privateSwapOrderCache.get(key);
+  if (!pending || typeof pending !== "object" || Number(pending.expiresAt || 0) <= Date.now()) {
+    privateSwapOrderCache.delete(key);
+    return [];
+  }
+  return [
+    {
+      ...(pending.order && typeof pending.order === "object" ? pending.order : {}),
+      expires_at_ms: Number(pending.expiresAt || 0),
+    },
+  ];
+}
 
 function resolvePluginConfig(api) {
   const globalConfig = api?.config ?? {};
@@ -183,9 +360,21 @@ function networkForBackend(api, backend) {
     return selectedEvmNetwork || defaultSelectableEvmNetwork(api) || "ethereum";
   }
   if (backend === "wdk_btc_local") {
-    return selectedBtcNetwork || defaultBtcNetwork(api);
+    try {
+      return selectedBtcNetwork || defaultBtcNetwork(api);
+    } catch {
+      return "bitcoin";
+    }
+  }
+  try {
+    return (
+      selectedSolanaNetwork ||
+      normalizeSolanaNetwork(config.network || process.env.SOLANA_NETWORK) ||
+      "mainnet"
+    );
+  } catch {
+    return "mainnet";
   }
-  return selectedSolanaNetwork || normalizeSolanaNetwork(config.network || process.env.SOLANA_NETWORK) || "mainnet";
 }
 
 function effectiveConfigForBackend(api, backend) {
@@ -244,11 +433,37 @@ async function callWalletCli(api, command, extraArgs = [], configOverride = null
     ...extraArgs,
   ];
 
-  const { stdout, stderr } = await execFileAsync(pythonBin, args, {
-    cwd: packageRoot,
-    env: buildCliEnv(packageRoot),
-    maxBuffer: 1024 * 1024 * 8,
-  });
+  let stdout = "";
+  let stderr = "";
+  try {
+    const result = await execFileAsync(pythonBin, args, {
+      cwd: packageRoot,
+      env: buildCliEnv(packageRoot),
+      maxBuffer: 1024 * 1024 * 8,
+    });
+    stdout = result.stdout;
+    stderr = result.stderr;
+  } catch (error) {
+    stdout = typeof error?.stdout === "string" ? error.stdout : "";
+    stderr = typeof error?.stderr === "string" ? error.stderr : "";
+    const stderrText = String(stderr || "").trim();
+    if (stderrText) {
+      try {
+        const payload = JSON.parse(stderrText);
+        const wrapped = new Error(payload?.error || "agent-wallet CLI failed");
+        if (payload?.code) wrapped.code = payload.code;
+        if (payload?.details && typeof payload.details === "object") {
+          wrapped.details = payload.details;
+        }
+        throw wrapped;
+      } catch (parseError) {
+        if (parseError instanceof Error && parseError !== error) {
+          throw parseError;
+        }
+      }
+    }
+    throw error;
+  }
 
   if (stderr && stderr.trim()) {
     api?.logger?.debug?.(`[agent-wallet] stderr: ${stderr.trim()}`);
@@ -256,11 +471,43 @@ async function callWalletCli(api, command, extraArgs = [], configOverride = null
 
   const payload = JSON.parse(stdout.trim() || "{}");
   if (payload?.ok === false && payload?.error) {
-    throw new Error(payload.error);
+    const wrapped = new Error(payload.error);
+    if (payload?.error_code) wrapped.code = payload.error_code;
+    if (payload?.error_details && typeof payload.error_details === "object") {
+      wrapped.details = payload.error_details;
+    }
+    throw wrapped;
   }
   return payload;
 }
 
+async function issueApprovalToken(api, config, userId, toolName, previewPayload) {
+  const summary = previewPayload?.confirmation_summary;
+  if (!summary || typeof summary !== "object") {
+    throw new Error(`No confirmation_summary available for ${toolName}.`);
+  }
+  const digest = previewDigest(previewPayload);
+  const summaryForToken = { ...summary, _preview_digest: digest };
+  const extraArgs = [
+    "--tool",
+    toolName,
+    "--summary-json",
+    JSON.stringify(summaryForToken),
+  ];
+  if (previewPayload?.is_mainnet === true) {
+    extraArgs.push("--mainnet-confirmed");
+  }
+  if (toolName === "swap_solana_privately") {
+    extraArgs.push("--ttl-seconds", "1800");
+  }
+  const payload = await callWalletCli(api, "issue-approval", extraArgs, config);
+  const token = String(payload?.approval_token || "").trim();
+  if (!token) {
+    throw new Error(`issue-approval did not return an approval_token for ${toolName}.`);
+  }
+  return token;
+}
+
 function asContent(data) {
   return {
     content: [
@@ -374,8 +621,15 @@ function registerTool(api, definition) {
         });
       }
 
+      if (definition.name === "list_pending_solana_private_swaps") {
+        return asContent({
+          orders: listPendingPrivateSwapOrders(resolveUserId(api, resolvePluginConfig(api))),
+        });
+      }
+
       const effectiveParams = { ...(params ?? {}) };
       const activeBackend = activeBackendForTool(api, definition.name);
+      const userId = resolveUserId(api, resolvePluginConfig(api));
       if (
         activeBackend === "wdk_evm_local" &&
         selectedEvmNetwork &&
@@ -388,12 +642,138 @@ function registerTool(api, definition) {
       if (activeBackend === "wdk_evm_local" && effectiveParams.network !== undefined) {
         configOverride.network = normalizeSelectableEvmNetwork(effectiveParams.network);
       }
-      const payload = await callWalletCli(api, "invoke", [
-        "--tool",
-        definition.name,
-        "--arguments-json",
-        JSON.stringify(effectiveParams),
-      ], configOverride);
+      if (String(effectiveParams.mode || "") === "execute") {
+        if (
+          PREVIEW_BOUND_SWAP_TOOLS.has(definition.name) &&
+          typeof effectiveParams.approval_token === "string" &&
+          effectiveParams.approval_token.trim() &&
+          effectiveParams._approved_preview === undefined
+        ) {
+          const cachedPreview = cachedPreviewForToken(userId, definition.name, effectiveParams.approval_token);
+          if (cachedPreview) {
+            effectiveParams._approved_preview = cachedPreview;
+          }
+        }
+        if (!effectiveParams.approval_token) {
+          const cached = latestCachedPreview(userId, definition.name);
+          if (cached?.preview && cached?.summary) {
+            effectiveParams.approval_token = await issueApprovalToken(
+              api,
+              configOverride,
+              userId,
+              definition.name,
+              cached.preview
+            );
+            if (PREVIEW_BOUND_SWAP_TOOLS.has(definition.name) && effectiveParams._approved_preview === undefined) {
+              effectiveParams._approved_preview = cached.preview;
+            }
+          }
+        }
+      }
+      if (definition.name === "continue_solana_private_swap") {
+        const cached = latestCachedPreview(userId, PRIVATE_SWAP_APPROVAL_TOOL_NAME);
+        if (cached?.preview && effectiveParams._approved_preview === undefined) {
+          effectiveParams._approved_preview = cached.preview;
+        }
+        if (!effectiveParams.approval_token && cached?.preview && cached?.summary) {
+          effectiveParams.approval_token = await issueApprovalToken(
+            api,
+            configOverride,
+            userId,
+            PRIVATE_SWAP_APPROVAL_TOOL_NAME,
+            cached.preview
+          );
+        }
+        if (effectiveParams._resume_private_swap_order === undefined && cached?.preview) {
+          const pendingOrder = latestPendingPrivateSwapOrder(
+            userId,
+            PRIVATE_SWAP_APPROVAL_TOOL_NAME,
+            cached.preview
+          );
+          if (pendingOrder) {
+            if (
+              effectiveParams.houdini_id &&
+              pendingOrder.houdini_id &&
+              String(effectiveParams.houdini_id).trim() !== String(pendingOrder.houdini_id).trim()
+            ) {
+              throw new Error("The requested houdini_id does not match the cached pending private swap order.");
+            }
+            effectiveParams._resume_private_swap_order = pendingOrder;
+          }
+        }
+      }
+      const executeWalletTool = async () =>
+        callWalletCli(api, "invoke", [
+          "--tool",
+          definition.name,
+          "--arguments-json",
+          JSON.stringify(effectiveParams),
+        ], configOverride);
+
+      let payload;
+      if (definition.name === "swap_solana_privately" && String(effectiveParams.mode || "") === "execute") {
+        const approvedPreview =
+          effectiveParams._approved_preview && typeof effectiveParams._approved_preview === "object"
+            ? effectiveParams._approved_preview
+            : null;
+        const pendingOrder = approvedPreview
+          ? latestPendingPrivateSwapOrder(userId, definition.name, approvedPreview)
+          : null;
+        if (pendingOrder && effectiveParams._resume_private_swap_order === undefined) {
+          effectiveParams._resume_private_swap_order = pendingOrder;
+        }
+
+        let remainingRetries = 3;
+        while (true) {
+          try {
+            payload = await executeWalletTool();
+            const executionState = payload?.data?.execution_state;
+            if (executionState === "awaiting_deposit_funding" && approvedPreview) {
+              cachePendingPrivateSwapOrder(userId, definition.name, approvedPreview, payload.data);
+            } else {
+              clearPendingPrivateSwapOrder(userId, definition.name);
+            }
+            break;
+          } catch (error) {
+            const errorCode = typeof error?.code === "string" ? error.code : "";
+            const errorDetails =
+              error?.details && typeof error.details === "object" ? error.details : null;
+            if (
+              (errorCode === "houdini_deposit_not_ready" ||
+                errorCode === "houdini_order_initializing_timeout") &&
+              approvedPreview &&
+              errorDetails &&
+              remainingRetries > 0
+            ) {
+              cachePendingPrivateSwapOrder(userId, definition.name, approvedPreview, errorDetails);
+              effectiveParams._resume_private_swap_order =
+                latestPendingPrivateSwapOrder(userId, definition.name, approvedPreview) || undefined;
+              remainingRetries -= 1;
+              continue;
+            }
+            if (
+              (errorCode === "houdini_deposit_not_ready" ||
+                errorCode === "houdini_order_initializing_timeout") &&
+              errorDetails
+            ) {
+              cachePendingPrivateSwapOrder(userId, definition.name, approvedPreview, errorDetails);
+              throw new Error(formatPrivateSwapPendingOrderError(errorDetails));
+            }
+            if (errorCode === "houdini_exchange_rate_limited" && errorDetails) {
+              throw new Error(formatPrivateSwapRateLimitError(errorDetails));
+            }
+            throw error;
+          }
+        }
+      } else if (definition.name === "continue_solana_private_swap") {
+        payload = await executeWalletTool();
+        if (payload?.data?.execution_state === "funding_submitted") {
+          clearPendingPrivateSwapOrder(userId, PRIVATE_SWAP_APPROVAL_TOOL_NAME);
+        }
+      } else {
+        payload = await executeWalletTool();
+      }
+      cachePreviewForApproval(userId, definition.name, payload);
       if (payload?.ok === false) {
         throw new Error(payload?.error || `${definition.name} failed`);
       }
@@ -415,7 +795,7 @@ const walletSessionToolDefinitions = [
   },
   {
     name: "get_wallet_balance",
-    description: "Get the active wallet overview. Solana and EVM return native assets, discovered token balances, per-asset USD values when available, and total_value_usd. Use set_wallet_backend first when the user asks to switch wallets.",
+    description: `Get the active wallet overview. Solana and EVM return native assets, discovered token balances, per-asset USD values when available, and total_value_usd. Use set_wallet_backend first when the user asks to switch wallets. ${WALLET_TOOL_ONLY_GUIDANCE}`,
     parameters: {
       type: "object",
       properties: {
@@ -456,6 +836,12 @@ const walletSessionToolDefinitions = [
 ];
 
 const solanaToolDefinitions = [
+  {
+    name: "list_pending_solana_private_swaps",
+    description:
+      "List cached pending Houdini private Solana orders from this OpenClaw session, including houdini_id, multi_id, deposit_address, and the last known order payload.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+  },
   {
     name: "get_wallet_capabilities",
     description: "Describe the connected wallet backend, chain, and safety limits.",
@@ -468,7 +854,7 @@ const solanaToolDefinitions = [
   },
   {
     name: "get_wallet_balance",
-    description: "Get the wallet overview: native balance, discovered token balances, per-asset USD values when available, and total_value_usd. Solana token discovery uses RPC; pricing uses Jupiter rather than RPC.",
+    description: `Get the wallet overview: native balance, discovered token balances, per-asset USD values when available, and total_value_usd. Solana token discovery uses RPC; pricing uses Jupiter rather than RPC. ${WALLET_TOOL_ONLY_GUIDANCE}`,
     parameters: {
       type: "object",
       properties: {
@@ -524,7 +910,7 @@ const solanaToolDefinitions = [
   },
   {
     name: "get_wallet_portfolio",
-    description: "Get the Solana wallet portfolio. This is the detailed equivalent of get_wallet_balance and includes native SOL, non-zero SPL token accounts, USD pricing when available, and total_value_usd.",
+    description: `Get the Solana wallet portfolio. This is the detailed equivalent of get_wallet_balance and includes native SOL, non-zero SPL token accounts, USD pricing when available, and total_value_usd. ${WALLET_TOOL_ONLY_GUIDANCE}`,
     parameters: {
       type: "object",
       properties: {
@@ -741,7 +1127,7 @@ const solanaToolDefinitions = [
   },
   {
     name: "swap_solana_tokens",
-    description: "Preview, prepare, or execute a Solana token swap via Jupiter. Prepare returns an execution plan only, and execute requires a host-issued approval token bound to the previewed operation.",
+    description: `Preview, prepare, or execute a Solana token swap via Jupiter. Prepare returns an execution plan only, and execute requires a host-issued approval token bound to the previewed operation. ${WALLET_TOOL_ONLY_GUIDANCE}`,
     optional: true,
     parameters: {
       type: "object",
@@ -759,6 +1145,56 @@ const solanaToolDefinitions = [
       additionalProperties: false,
     },
   },
+  {
+    name: "swap_solana_privately",
+    description: `Preview or create a Solana private payout through Houdini's anonymous routing. The initial implementation supports same-token private payouts only, such as SOL->SOL or USDC->USDC. Use preview first, then execute after explicit approval. The first execute creates the Houdini order and returns its deposit address; use continue_solana_private_swap to submit the funding transfer. ${WALLET_TOOL_ONLY_GUIDANCE}`,
+    optional: true,
+    parameters: {
+      type: "object",
+      properties: {
+        input_token: { type: "string" },
+        output_token: { type: "string" },
+        destination_address: { type: "string" },
+        amount: { type: "number" },
+        use_xmr: { type: "boolean" },
+        mode: { type: "string", enum: ["preview", "execute"] },
+        purpose: { type: "string" },
+        user_intent: { type: "boolean" },
+        approval_token: { type: "string" },
+      },
+      required: ["input_token", "output_token", "destination_address", "amount", "mode", "purpose"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "continue_solana_private_swap",
+    description:
+      "Continue a previously created Houdini private Solana payout and submit the funding transfer to the cached deposit address. Use this after swap_solana_privately execute has returned a pending order.",
+    optional: true,
+    parameters: {
+      type: "object",
+      properties: {
+        houdini_id: { type: "string" },
+        approval_token: { type: "string" },
+      },
+      required: ["approval_token"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_solana_private_swap_status",
+    description: "Check Houdini status for a Solana private payout created by swap_solana_privately. Prefer houdini_id from the execute result; multi_id is only needed for legacy multi-order flows.",
+    optional: true,
+    parameters: {
+      type: "object",
+      properties: {
+        multi_id: { type: "string" },
+        houdini_id: { type: "string" },
+      },
+      anyOf: [{ required: ["multi_id"] }, { required: ["houdini_id"] }],
+      additionalProperties: false,
+    },
+  },
   {
     name: "swap_solana_lifi_cross_chain_tokens",
     description: "Preview, prepare, or execute a Solana-origin cross-chain swap through LI.FI. This currently supports Solana as the source chain and ethereum/base as the destination chain. Prepare returns an execution plan only, and execute requires a host-issued approval token bound to the previewed operation.",