@subly_fi/pay 0.4.0 → 0.5.0

package/dist/mcp-server.js

@@ -1006,7 +1006,7 @@ var OnboardingError = class extends Error {
 };
 async function ensureWalletOnboarded(params) {
   const fetchImpl = params.fetchImpl ?? fetch;
-  const baseUrl = params.facilitatorBaseUrl.replace(/\/$/, "");
+  const baseUrl = params.relayerBaseUrl.replace(/\/$/, "");
   const post = async (step, path, body) => {
     const url = `${baseUrl}${path}`;
     const serialized = JSON.stringify(body);
@@ -1134,6 +1134,12 @@ function formatRawUsdcAmount(raw) {
   return `${negative ? "-" : ""}${whole}.${frac}`;
 }
 
+// ../../src/lib/canonical-json.ts
+import { createHash as createHash4 } from "node:crypto";
+function sha256HexOf(data) {
+  return createHash4("sha256").update(data, "utf8").digest("hex");
+}
+
 // ../../src/x402/standard-requirements.ts
 import { z as z2 } from "zod";
 var STANDARD_EXACT_SCHEME = "exact";
@@ -1199,20 +1205,36 @@ function decodeStandardPaymentRequiredHeader(headerValue) {
 function selectPayableSolanaRequirement(requirements, options) {
   const network = options?.network ?? SOLANA_MAINNET_NETWORK;
   const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
-  const requirement = requirements.find(
+  const matchingRequirements = requirements.filter(
     (candidate) => candidate.network === network && candidate.asset === usdcMint
-  ) ?? null;
-  if (requirement === null) {
+  );
+  if (matchingRequirements.length === 0) {
     throw new StandardX402ChallengeError(
       "no_payable_requirement",
       `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
     );
   }
+  const requirement = matchingRequirements.find(
+    (candidate) => candidate.extra?.feePayer !== void 0
+  ) ?? null;
+  if (requirement === null) {
+    throw new StandardX402ChallengeError(
+      "missing_svm_fee_payer",
+      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
+    );
+  }
+  const feePayer = requirement.extra?.feePayer;
+  if (feePayer === void 0) {
+    throw new StandardX402ChallengeError(
+      "missing_svm_fee_payer",
+      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
+    );
+  }
   return {
     requirement,
     amountRawUsdc: BigInt(requirement.amount),
     payTo: requirement.payTo,
-    feePayer: requirement.extra?.feePayer ?? null
+    feePayer
   };
 }
 function standardRequirementMatchesSelected(candidate, selected) {
@@ -1335,9 +1357,23 @@ var StandardX402Payer = class {
     let realized;
     try {
       realized = await this.realizer.ensureUsdcAvailable({
-        amountRawUsdc: selected.amountRawUsdc
+        amountRawUsdc: selected.amountRawUsdc,
+        payment: {
+          payTo: selected.payTo,
+          amountRawUsdc: selected.amountRawUsdc.toString(),
+          resourceUrlHash: sha256HexOf(input.url),
+          method
+        },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       });
     } catch (error) {
+      if (error.code === "approval_required") {
+        throw new StandardX402PayError(
+          "approval_required",
+          "this payment exceeds the owner-approval threshold; NOTHING was paid. Ask the owner to open the approveUrl, then retry the same call with the approvalId",
+          error.detail ?? null
+        );
+      }
       throw new StandardX402PayError(
         "realize_failed",
         `could not realize yield to cover ${selected.amountRawUsdc} raw USDC: ${error instanceof Error ? error.message : String(error)}`,
@@ -1393,6 +1429,19 @@ var StandardX402Payer = class {
       );
     }
     this.clearDelivered(pendingKey);
+    const paymentTxSignature = extractSettledPaymentTxSignature(response);
+    if (paymentTxSignature !== null && typeof realized.withdrawalId === "string" && this.realizer.reportPayment !== void 0) {
+      try {
+        await this.realizer.reportPayment({
+          withdrawalId: realized.withdrawalId,
+          paymentTxSignature
+        });
+      } catch (error) {
+        console.error(
+          `[subly-x402] payment report-back failed (audit only, payment ok): ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
     return {
       paid: true,
       status: response.status,
@@ -1402,7 +1451,8 @@ var StandardX402Payer = class {
         payTo: selected.payTo,
         feePayer: selected.feePayer,
         realizedRawUsdc: realized.realizedRawUsdc.toString(),
-        realizeTxSignature: realized.txSignature
+        realizeTxSignature: realized.txSignature,
+        paymentTxSignature
       }
     };
   }
@@ -1516,6 +1566,26 @@ var StandardX402Payer = class {
 function pendingPaymentKey(input) {
   return `${input.method}:${input.url}:${input.requestBodyHash}`;
 }
+function extractSettledPaymentTxSignature(response) {
+  const header = response.headers.get("x-payment-response");
+  if (header === null || header.length === 0) {
+    return null;
+  }
+  try {
+    const decoded = JSON.parse(
+      Buffer.from(header, "base64").toString("utf8")
+    );
+    if (typeof decoded.transaction === "string" && decoded.transaction.length > 0) {
+      return decoded.transaction;
+    }
+    if (typeof decoded.txHash === "string" && decoded.txHash.length > 0) {
+      return decoded.txHash;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 
 // ../../src/client/lookup-tables.ts
 import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
@@ -1559,14 +1629,18 @@ async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
 
 // ../../src/client/vault-flows.ts
 var VaultFlowClientError = class extends Error {
-  constructor(step, message, detail = null) {
+  constructor(step, message, detail = null, code = null, errorDetails = null) {
     super(message);
     this.step = step;
     this.detail = detail;
+    this.code = code;
+    this.errorDetails = errorDetails;
     this.name = "VaultFlowClientError";
   }
   step;
   detail;
+  code;
+  errorDetails;
 };
 var VaultFlowClient = class {
   baseUrl;
@@ -1576,19 +1650,44 @@ var VaultFlowClient = class {
   pollTimeoutMs;
   pollIntervalMs;
   constructor(config) {
-    this.baseUrl = config.facilitatorBaseUrl.replace(/\/$/, "");
+    this.baseUrl = config.relayerBaseUrl.replace(/\/$/, "");
     this.signer = config.signer;
     this.fetchImpl = config.fetchImpl ?? fetch;
     this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(config.rpc, serializedTransaction));
     this.pollTimeoutMs = config.pollTimeoutMs ?? 9e4;
     this.pollIntervalMs = config.pollIntervalMs ?? 2500;
   }
-  /** Moves USDC from the agent wallet into the vault (fee sponsored). */
+  /**
+   * Moves USDC from the agent wallet into the vault (fee sponsored). Under
+   * depositPolicy "owner_approval_required" the relayer refuses to prepare
+   * without an owner approval; when the caller passes none, an already
+   * APPROVED deposit approval for this exact amount (e.g. the mandate's
+   * initialDeposit — "one Face ID covers mandate + first deposit") is looked
+   * up and used automatically before surfacing deposit_approval_required.
+   */
   async deposit(input) {
-    const prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
-      wallet: this.signer.walletAddress,
-      amountRawUsdc: input.amountRawUsdc.toString()
-    });
+    let approvalId = input.approvalId;
+    let prepared;
+    try {
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...approvalId === void 0 ? {} : { approvalId }
+      });
+    } catch (error) {
+      if (!(error instanceof VaultFlowClientError) || error.code !== "deposit_approval_required" || approvalId !== void 0) {
+        throw error;
+      }
+      approvalId = await this.findApprovedDepositApproval(input.amountRawUsdc);
+      if (approvalId === void 0) {
+        throw error;
+      }
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        approvalId
+      });
+    }
     const signed = await this.signer.signDeposit({
       intent: prepared.signingIntent,
       serializedTransaction: prepared.serializedTransaction,
@@ -1627,7 +1726,9 @@ var VaultFlowClient = class {
       {
         wallet: this.signer.walletAddress,
         amountRawUsdc: input.amountRawUsdc.toString(),
-        ...input.purpose === void 0 ? {} : { purpose: input.purpose }
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       }
     );
     const signed = await this.signer.signWithdrawal({
@@ -1706,6 +1807,70 @@ var VaultFlowClient = class {
       spendableYieldRawUsdc: body.budget?.spendableYieldRawUsdc ?? "0"
     };
   }
+  /** Best-effort audit link: reports the x402 payment tx a realize funded. */
+  async reportPayment(input) {
+    await this.postJson("submit", "/v1/payments/report", {
+      wallet: this.signer.walletAddress,
+      withdrawalId: input.withdrawalId,
+      paymentTxSignature: input.paymentTxSignature
+    });
+  }
+  /** Wallet's approvals as the relayer sees them (optionally by status). */
+  async listApprovals(status) {
+    const body = await this.getJson(
+      `/v1/wallets/${this.signer.walletAddress}/approvals${status === void 0 ? "" : `?status=${encodeURIComponent(status)}`}`
+    );
+    return body.approvals ?? [];
+  }
+  /**
+   * Creates the owner-onboarding setup link (wallet-auth pins the agreed
+   * policy + initial deposit). Paste `setupUrl` into the chat verbatim.
+   */
+  async createSetupSession(input) {
+    return await this.postJson(
+      "prepare",
+      `/v1/wallets/${this.signer.walletAddress}/setup-sessions`,
+      {
+        ...input.policy === void 0 ? {} : { policy: input.policy },
+        ...input.enforcementMode === void 0 ? {} : { enforcementMode: input.enforcementMode },
+        ...input.mandateTtlDays === void 0 ? {} : { mandateTtlDays: input.mandateTtlDays },
+        ...input.initialDepositRawUsdc === void 0 ? {} : { initialDepositRawUsdc: input.initialDepositRawUsdc }
+      }
+    );
+  }
+  /** Polls a setup session (public capability URL — no auth needed). */
+  async getSetupSession(sessionId) {
+    const url = `${this.baseUrl}/v1/setup-sessions/${encodeURIComponent(sessionId)}`;
+    const response = await this.fetchImpl(url);
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message ?? `setup session read failed with ${response.status}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
+    return JSON.parse(text);
+  }
+  /**
+   * Finds an APPROVED, unconsumed deposit approval bound to exactly this
+   * amount — the shape the mandate's initialDeposit approval has.
+   */
+  async findApprovedDepositApproval(amountRawUsdc) {
+    try {
+      const approvals = await this.listApprovals("approved");
+      const match = approvals.find((approval) => {
+        const binding = approval.binding;
+        return binding?.kind === "deposit" && binding.amountRawUsdc === amountRawUsdc.toString();
+      });
+      return match?.approvalId;
+    } catch {
+      return void 0;
+    }
+  }
   /**
    * Polls the reconciling GET endpoint until the intent leaves "submitted"
    * (each read looks the tx up on-chain) or the timeout elapses.
@@ -1755,10 +1920,13 @@ var VaultFlowClient = class {
     });
     const text = await response.text();
     if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
       throw new VaultFlowClientError(
         step,
-        `${path} failed with ${response.status}: ${text}`,
-        text
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
       );
     }
     try {
@@ -1771,39 +1939,150 @@ var VaultFlowClient = class {
       );
     }
   }
+  async getJson(path) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await this.fetchImpl(url, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "read",
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
+    }
+  }
 };
+function parseRelayerError(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return {
+      code: typeof parsed.error?.code === "string" ? parsed.error.code : null,
+      message: typeof parsed.error?.message === "string" ? parsed.error.message : null,
+      details: parsed.error?.details ?? null
+    };
+  } catch {
+    return { code: null, message: null, details: null };
+  }
+}
 
 // ../../src/client/mcp-payment-server.ts
 var TOOL_NAME = "fetch_with_subly_payment";
 var DEPOSIT_TOOL_NAME = "deposit_to_subly_vault";
 var WITHDRAW_TOOL_NAME = "withdraw_from_subly_vault";
 var BUDGET_TOOL_NAME = "get_subly_yield_budget";
-var SERVER_INSTRUCTIONS = `Subly lets an agent pay for ANY standard x402 (HTTP 402) paid API from its wallet's Kamino vault YIELD \u2014 the deposited principal is never spent, and the seller needs no Subly integration.
+var SETUP_TOOL_NAME = "create_subly_setup_link";
+var SETUP_STATUS_TOOL_NAME = "check_subly_setup";
+var SERVER_INSTRUCTIONS = `Subly lets an agent pay standard x402 (HTTP 402) paid APIs that offer a Solana USDC exact rail with facilitator feePayer support from its wallet's Kamino vault YIELD \u2014 the deposited principal is never spent, and the seller needs no Subly integration.
 
 One-time setup: the operator needs a Solana keypair for the agent wallet. Subly does NOT create wallets; make one with \`solana-keygen new -o agent.json\` (or export a keypair from an existing wallet) and point SUBLY_DEMO_AGENT_KEYPAIR_PATH at it. The private key never leaves that file; this server only signs locally with it. Then fund the wallet with USDC on Solana mainnet \u2014 no SOL is ever needed, all vault transaction fees are sponsored.
 
+Owner (human) onboarding: deposits require the human owner's approval (Face ID / wallet signature). During the first deposit conversation, agree the spending limits and the first deposit amount in chat, then call create_subly_setup_link and paste the returned setupUrl to the user AS IS (it expires in 10 minutes). The human opens it on their phone, reviews, and confirms once \u2014 that single confirmation activates the spending mandate AND pre-approves the first deposit. Poll check_subly_setup(sessionId) after the user says they finished, then call deposit_to_subly_vault (the pre-approved first deposit is picked up automatically).
+
 From there the agent can do everything with these tools:
-1. deposit_to_subly_vault(amountRawUsdc) puts wallet USDC into the vault (minimum 1 USDC = 1000000 raw) so it starts earning yield.
+1. deposit_to_subly_vault(amountRawUsdc) puts wallet USDC into the vault (minimum just over 1 USDC, e.g. 1010000 raw) so it starts earning yield. If it returns approvalRequired, paste the approveUrl to the user and retry with the approvalId after they approve; if it returns setupRequired, run the owner onboarding above first.
 2. get_subly_yield_budget() shows the principal, position value, and the spendable yield a payment can use right now.
-3. fetch_with_subly_payment(url) GETs or POSTs a paid resource from any x402 seller (e.g. Nansen): it realizes just enough yield to the agent's USDC ATA and pays the seller's standard x402 challenge, returning the body plus the payment details. If it returns insufficient_yield, that is expected \u2014 yield accrues over time; wait, do not loop.
-4. withdraw_from_subly_vault(amountRawUsdc) exits: moves vault funds (principal included) back to the agent wallet's USDC account.`;
+3. fetch_with_subly_payment(url) GETs or POSTs a paid resource from a compatible x402 seller (e.g. Nansen): it realizes just enough yield to the agent's USDC ATA and pays the seller's Solana USDC exact challenge, returning the body plus the payment details. If it returns insufficient_yield, that is expected \u2014 yield accrues over time; wait, do not loop. If it returns approvalRequired (payment above the owner's threshold; NOTHING was paid), paste the approveUrl to the user, and once they say they approved, repeat the SAME call adding the approvalId.
+4. withdraw_from_subly_vault(amountRawUsdc) exits: moves vault funds (principal included) back to the agent wallet's USDC account. If the owner's mandate requires withdrawal approval it returns approvalRequired \u2014 same paste-approveUrl-then-retry flow as deposits.`;
 async function runMcpPaymentServer(config) {
-  const { payer: payer2, signer: signer2, facilitatorBaseUrl, defaultMaxAmountRawUsdc: defaultMaxAmountRawUsdc2 } = config;
+  const { payer: payer2, signer: signer2, relayerBaseUrl: relayerBaseUrl2, defaultMaxAmountRawUsdc: defaultMaxAmountRawUsdc2 } = config;
   const vaultFlows = config.vaultFlows ?? null;
   const server = new Server(
     { name: "subly-payments", version: config.serverVersion ?? "0.3.0" },
     { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
   );
   const vaultTools = vaultFlows === null ? [] : [
+    {
+      name: SETUP_TOOL_NAME,
+      description: "Create the one-time owner setup link for this agent wallet's Subly spending mandate. Use during onboarding (the first deposit conversation): agree the limits and first deposit in chat, call this, and paste the returned setupUrl to the user verbatim \u2014 it expires in 10 minutes and works once. The human opens it on their phone and confirms with Face ID (passkey) or a Solana wallet signature; that single confirmation activates the mandate AND pre-approves the initial deposit. The page is confirm-only: to change values, agree in chat and create a new link.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          initialDepositRawUsdc: {
+            type: "string",
+            description: `First deposit bundled into the owner's single Face ID (raw USDC, 6 decimals; just over 1 USDC minimum, e.g. "1010000"). Strongly recommended: without it the first deposit needs a separate approval.`
+          },
+          approvalThresholdRawUsdc: {
+            type: "string",
+            description: 'Payments at or below this run without asking (raw USDC). Default "1000000" (1 USDC).'
+          },
+          perPaymentCapRawUsdc: {
+            type: "string",
+            description: 'Absolute per-payment cap even with approval (raw USDC). Default "10000000" (10 USDC).'
+          },
+          dailyApiSpendCapRawUsdc: {
+            type: "string",
+            description: 'Rolling 24h API spend cap (raw USDC). Default "100000000" (100 USDC).'
+          },
+          dailyDepositCapRawUsdc: {
+            type: "string",
+            description: 'Rolling 24h deposit cap (raw USDC). Default "3000000000" (3,000 USDC).'
+          },
+          mandateTtlDays: {
+            type: "number",
+            description: "Mandate lifetime in days (default 365)."
+          }
+        }
+      },
+      annotations: {
+        title: "Create Subly owner setup link",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    {
+      name: SETUP_STATUS_TOOL_NAME,
+      description: "Check whether the human completed a Subly setup link. Call after the user says they finished (or to verify before depositing). Returns pending / completed / expired; on completed it includes the mandateHash and, when an initial deposit was bundled, its pre-approved approvalId (valid ~15 minutes \u2014 deposit promptly).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          sessionId: {
+            type: "string",
+            description: "The sessionId returned by create_subly_setup_link."
+          }
+        },
+        required: ["sessionId"]
+      },
+      annotations: {
+        title: "Check Subly setup status",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     {
       name: DEPOSIT_TOOL_NAME,
-      description: "Deposit USDC from the agent wallet into the Subly/Kamino vault so it starts earning the yield that funds x402 payments. The transaction fee is sponsored \u2014 the agent wallet needs USDC only, never SOL. The vault minimum deposit is 1 USDC (1000000 raw). The deposited amount becomes protected principal: payments can only ever spend the yield on top of it.",
+      description: "Deposit USDC from the agent wallet into the Subly/Kamino vault so it starts earning the yield that funds x402 payments. The transaction fee is sponsored \u2014 the agent wallet needs USDC only, never SOL. The vault minimum is just over 1 USDC: share rounding refuses exactly 1000000 raw, so deposit e.g. 1010000 (1.01 USDC) or more. The deposited amount becomes protected principal: payments can only ever spend the yield on top of it. Deposits require the human owner's approval: a pre-approved amount (e.g. the setup link's initial deposit) is used automatically; otherwise the result contains an approveUrl \u2014 paste it to the user and retry with the approvalId once they approve. setupRequired means the owner onboarding (create_subly_setup_link) must happen first.",
       inputSchema: {
         type: "object",
         properties: {
           amountRawUsdc: {
             type: "string",
-            description: 'Amount to deposit in raw USDC units (6 decimals, e.g. "1000000" = 1 USDC). Must be at least 1000000.'
+            description: 'Amount to deposit in raw USDC units (6 decimals, e.g. "1010000" = 1.01 USDC). Must exceed the 1 USDC vault minimum by a small rounding margin.'
+          },
+          approvalId: {
+            type: "string",
+            description: "Owner approval id (apr_...) from a previous approvalRequired result or check_subly_setup, after the human approved."
           }
         },
         required: ["amountRawUsdc"]
@@ -1818,13 +2097,17 @@ async function runMcpPaymentServer(config) {
     },
     {
       name: WITHDRAW_TOOL_NAME,
-      description: "Withdraw USDC from the Subly/Kamino vault back to the agent wallet's USDC account (fee sponsored, no SOL needed). This is the exit path and may spend PRINCIPAL \u2014 it reduces the deposit that earns yield. Limited to the vault's instant liquidity.",
+      description: "Withdraw USDC from the Subly/Kamino vault back to the agent wallet's USDC account (fee sponsored, no SOL needed). This is the exit path and may spend PRINCIPAL \u2014 it reduces the deposit that earns yield. Limited to the vault's instant liquidity. If the owner's mandate requires withdrawal approval, the result contains an approveUrl \u2014 paste it to the user and retry with the approvalId once they approve.",
       inputSchema: {
         type: "object",
         properties: {
           amountRawUsdc: {
             type: "string",
             description: 'Amount to withdraw in raw USDC units (6 decimals, e.g. "1000000" = 1 USDC).'
+          },
+          approvalId: {
+            type: "string",
+            description: "Owner approval id (apr_...) from a previous approvalRequired result, after the human approved."
           }
         },
         required: ["amountRawUsdc"]
@@ -1855,7 +2138,7 @@ async function runMcpPaymentServer(config) {
       ...vaultTools,
       {
         name: TOOL_NAME,
-        description: `Fetch a URL (GET or POST), automatically paying a standard x402 (HTTP 402) challenge from any x402-compatible seller (Nansen, etc.) out of the agent wallet's Kamino vault yield. Subly realizes just enough yield to the agent's USDC ATA (sponsored) and pays the seller's Solana USDC \`exact\` challenge; the seller needs no Subly integration. Returns the response body and, when a payment was made, the payment details (amount, payee, realize tx). Challenges above maxAmountRawUsdc (default ${defaultMaxAmountRawUsdc2} raw = ${formatRawUsdcAmount(
+        description: `Fetch a URL (GET or POST), automatically paying a standard x402 (HTTP 402) challenge from a seller that offers Solana USDC \`exact\` with \`extra.feePayer\` (Nansen, etc.) out of the agent wallet's Kamino vault yield. Subly realizes just enough yield to the agent's USDC ATA (sponsored) and pays the seller's challenge; the seller needs no Subly integration. Returns the response body and, when a payment was made, the payment details (amount, payee, realize tx). Challenges above maxAmountRawUsdc (default ${defaultMaxAmountRawUsdc2} raw = ${formatRawUsdcAmount(
           defaultMaxAmountRawUsdc2
         )} USDC) are refused without paying. Payments are refused when the spendable yield budget cannot cover them \u2014 the principal is never spent. Use only for URLs you intend to purchase access to.`,
         inputSchema: {
@@ -1885,6 +2168,10 @@ async function runMcpPaymentServer(config) {
             forceNewPayment: {
               type: "boolean",
               description: "Pay again even if a previous external x402 attempt for the same URL/method/body has an unknown outcome. This may pay twice for the same resource."
+            },
+            approvalId: {
+              type: "string",
+              description: "Owner approval id (apr_...) from a previous approvalRequired result. After the human approves via the approveUrl, repeat the SAME call with this added."
             }
           },
           required: ["url"]
@@ -1954,13 +2241,19 @@ async function runMcpPaymentServer(config) {
     const vaultToolNames = [
       BUDGET_TOOL_NAME,
       DEPOSIT_TOOL_NAME,
-      WITHDRAW_TOOL_NAME
+      WITHDRAW_TOOL_NAME,
+      SETUP_TOOL_NAME,
+      SETUP_STATUS_TOOL_NAME
     ];
     if (vaultFlows !== null && vaultToolNames.includes(request.params.name)) {
-      try {
-        await ensureWalletOnboarded({ facilitatorBaseUrl, signer: signer2 });
-      } catch {
+      const needsChainSync = request.params.name !== SETUP_TOOL_NAME && request.params.name !== SETUP_STATUS_TOOL_NAME;
+      if (needsChainSync) {
+        try {
+          await ensureWalletOnboarded({ relayerBaseUrl: relayerBaseUrl2, signer: signer2 });
+        } catch {
+        }
       }
+      const args2 = request.params.arguments ?? {};
       if (request.params.name === BUDGET_TOOL_NAME) {
         try {
           const budget = await vaultFlows.getBudget();
@@ -1980,9 +2273,48 @@ async function runMcpPaymentServer(config) {
           return vaultFlowFailure(error);
         }
       }
-      const amountRawUsdc = parseRawAmount(
-        (request.params.arguments ?? {}).amountRawUsdc
-      );
+      if (request.params.name === SETUP_TOOL_NAME) {
+        try {
+          const policy = {};
+          for (const key of [
+            "approvalThresholdRawUsdc",
+            "perPaymentCapRawUsdc",
+            "dailyApiSpendCapRawUsdc",
+            "dailyDepositCapRawUsdc"
+          ]) {
+            const value = args2[key];
+            if (typeof value === "string" && value.length > 0) {
+              policy[key] = value;
+            }
+          }
+          const created = await vaultFlows.createSetupSession({
+            ...Object.keys(policy).length === 0 ? {} : { policy },
+            ...typeof args2.mandateTtlDays === "number" ? { mandateTtlDays: args2.mandateTtlDays } : {},
+            ...typeof args2.initialDepositRawUsdc === "string" ? { initialDepositRawUsdc: args2.initialDepositRawUsdc } : {}
+          });
+          return textResult({
+            ...created,
+            instructions: `Paste setupUrl to the user verbatim (expires in 10 minutes, single-use). After they confirm on their device, call ${SETUP_STATUS_TOOL_NAME} with this sessionId; when completed, run the first deposit \u2014 its approval is picked up automatically.`
+          });
+        } catch (error) {
+          return vaultFlowFailure(error);
+        }
+      }
+      if (request.params.name === SETUP_STATUS_TOOL_NAME) {
+        const sessionId = args2.sessionId;
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+          return textResult(
+            { ok: false, message: "missing required argument: sessionId" },
+            true
+          );
+        }
+        try {
+          return textResult(await vaultFlows.getSetupSession(sessionId));
+        } catch (error) {
+          return vaultFlowFailure(error);
+        }
+      }
+      const amountRawUsdc = parseRawAmount(args2.amountRawUsdc);
       if (amountRawUsdc === null) {
         return textResult(
           {
@@ -1992,22 +2324,50 @@ async function runMcpPaymentServer(config) {
           true
         );
       }
+      const flowApprovalId = typeof args2.approvalId === "string" && args2.approvalId.length > 0 ? args2.approvalId : void 0;
       try {
         if (request.params.name === DEPOSIT_TOOL_NAME) {
-          const outcome2 = await vaultFlows.deposit({ amountRawUsdc });
+          const outcome2 = await vaultFlows.deposit({
+            amountRawUsdc,
+            ...flowApprovalId === void 0 ? {} : { approvalId: flowApprovalId }
+          });
           return vaultFlowOutcome(outcome2, {
             depositedUsdc: formatRawUsdcAmount(
               BigInt(outcome2.actualDepositRawUsdc ?? "0")
             )
           });
         }
-        const outcome = await vaultFlows.withdraw({ amountRawUsdc });
+        const outcome = await vaultFlows.withdraw({
+          amountRawUsdc,
+          ...flowApprovalId === void 0 ? {} : { approvalId: flowApprovalId }
+        });
         return vaultFlowOutcome(outcome, {
           withdrawnUsdc: formatRawUsdcAmount(
             BigInt(outcome.actualWithdrawRawUsdc ?? "0")
           )
         });
       } catch (error) {
+        if (error instanceof VaultFlowClientError) {
+          const details = error.errorDetails ?? {};
+          if (error.code === "deposit_approval_required" || error.code === "withdrawal_approval_required") {
+            const op = error.code === "deposit_approval_required" ? "deposit" : "withdrawal";
+            return textResult({
+              ok: false,
+              approvalRequired: true,
+              approvalId: details.approvalId ?? null,
+              approveUrl: details.approveUrl ?? null,
+              expiresAtMs: details.expiresAtMs ?? null,
+              message: `This ${op} needs the owner's approval. Paste approveUrl to the user; once they approve (Face ID / wallet sign), retry the same ${op} adding the approvalId.`
+            });
+          }
+          if (error.code === "mandate_required_for_deposit") {
+            return textResult({
+              ok: false,
+              setupRequired: true,
+              message: `Deposits require a registered owner. Run the onboarding: agree limits + first deposit in chat, call ${SETUP_TOOL_NAME}, and paste the setupUrl to the user. The setup's initial deposit is pre-approved with the same single Face ID.`
+            });
+          }
+        }
         return vaultFlowFailure(error);
       }
     }
@@ -2048,6 +2408,7 @@ async function runMcpPaymentServer(config) {
     const method = typeof args.method === "string" ? args.method : void 0;
     const body = typeof args.body === "string" ? args.body : void 0;
     const forceNewPayment = args.forceNewPayment === true;
+    const approvalId = typeof args.approvalId === "string" && args.approvalId.length > 0 ? args.approvalId : void 0;
     const headers = args.headers !== null && typeof args.headers === "object" && !Array.isArray(args.headers) ? Object.fromEntries(
       Object.entries(args.headers).filter(([, v]) => typeof v === "string").map(([k, v]) => [k, v])
     ) : void 0;
@@ -2059,12 +2420,24 @@ async function runMcpPaymentServer(config) {
         ...body === void 0 ? {} : { body },
         ...mergedHeaders === void 0 ? {} : { headers: mergedHeaders },
         ...maxAmountRawUsdc === void 0 ? {} : { maxAmountRawUsdc },
-        ...forceNewPayment ? { forceNewPayment } : {}
+        ...forceNewPayment ? { forceNewPayment } : {},
+        ...approvalId === void 0 ? {} : { approvalId }
       });
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };
     } catch (error) {
+      if (error instanceof StandardX402PayError && error.reason === "approval_required") {
+        const details = error.detail ?? {};
+        return textResult({
+          paid: false,
+          approvalRequired: true,
+          approvalId: details.approvalId ?? null,
+          approveUrl: details.approveUrl ?? null,
+          expiresAtMs: details.expiresAtMs ?? null,
+          message: "This payment exceeds the owner's approval threshold \u2014 NOTHING was paid. Paste approveUrl to the user; once they approve, repeat the SAME call adding the approvalId."
+        });
+      }
       if (error instanceof StandardX402PayError) {
         return {
           content: [
@@ -2098,7 +2471,7 @@ async function runMcpPaymentServer(config) {
     }
   });
   try {
-    await ensureWalletOnboarded({ facilitatorBaseUrl, signer: signer2 });
+    await ensureWalletOnboarded({ relayerBaseUrl: relayerBaseUrl2, signer: signer2 });
     console.error("[subly-mcp] wallet registered and synced at the relayer");
   } catch (error) {
     console.error(
@@ -2108,7 +2481,7 @@ async function runMcpPaymentServer(config) {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `[subly-mcp] ready: agent wallet ${signer2.walletAddress}, relayer ${facilitatorBaseUrl}, default cap ${formatRawUsdcAmount(defaultMaxAmountRawUsdc2)} USDC`
+    `[subly-mcp] ready: agent wallet ${signer2.walletAddress}, relayer ${relayerBaseUrl2}, default cap ${formatRawUsdcAmount(defaultMaxAmountRawUsdc2)} USDC`
   );
 }
 
@@ -2128,7 +2501,7 @@ var RelayerYieldRealizer = class {
   vaultFlows;
   constructor(config) {
     this.vaultFlows = new VaultFlowClient({
-      facilitatorBaseUrl: config.facilitatorBaseUrl,
+      relayerBaseUrl: config.relayerBaseUrl,
       signer: config.signer,
       rpc: config.rpc,
       ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
@@ -2144,7 +2517,11 @@ var RelayerYieldRealizer = class {
         amountRawUsdc: shortfallRawUsdc,
         // The relayer refuses to prepare this withdrawal beyond the spendable
         // yield — the principal-protection guard the client cannot bypass.
-        purpose: "yield_realize"
+        purpose: "yield_realize",
+        // Declares what is being paid so the relayer's spending-mandate layer
+        // can enforce caps/payee and keep the mandate → payment audit chain.
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       });
     } catch (error) {
       throw this.mapWithdrawError(error);
@@ -2158,9 +2535,18 @@ var RelayerYieldRealizer = class {
     }
     return {
       realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
-      txSignature: outcome.txSignature
+      txSignature: outcome.txSignature,
+      withdrawalId: outcome.withdrawalId
     };
   }
+  /**
+   * Best-effort report-back of the x402 payment tx this realize funded —
+   * closes the relayer's mandate → realize → payment audit chain. Callers
+   * must never let a failure here affect the payment result.
+   */
+  async reportPayment(input) {
+    await this.vaultFlows.reportPayment(input);
+  }
   /**
    * Refuses to realize more than the ledger's spendable yield (principal).
    * getBudget syncs the relayer's ledger from chain first (best-effort), so a
@@ -2195,7 +2581,14 @@ var RelayerYieldRealizer = class {
         error
       );
     }
-    const serverCode = errorCodeFrom(error.detail);
+    const serverCode = error.code ?? errorCodeFrom(error.detail);
+    if (serverCode === "approval_required") {
+      return new RelayerRealizeError(
+        "approval_required",
+        "this payment exceeds the owner-approval threshold; nothing was realized or paid. Ask the owner to approve, then retry with the approvalId",
+        error.errorDetails ?? error.detail
+      );
+    }
     if (serverCode === "insufficient_yield" || serverCode === "post_state_principal_invariant_failed") {
       return new RelayerRealizeError(
         "insufficient_yield",
@@ -2225,7 +2618,7 @@ function errorCodeFrom(detail) {
 // ../../src/client/relayer-payer.ts
 function createRelayerX402Payer(config) {
   const realizer = new RelayerYieldRealizer({
-    facilitatorBaseUrl: config.facilitatorBaseUrl,
+    relayerBaseUrl: config.relayerBaseUrl,
     signer: config.signer,
     rpc: config.rpc
   });
@@ -2388,7 +2781,7 @@ var agentSecretKey = loadSecretKeyBytes({
 var signer = new LocalKeypairAgentWalletSigner(keyPairSigner);
 var rpc = createRpc(rpcUrl);
 var payer = createRelayerX402Payer({
-  facilitatorBaseUrl: relayerBaseUrl,
+  relayerBaseUrl,
   signer,
   rpc,
   x402Fetch: await createSvmX402Fetch({ agentSecretKey, rpcUrl }),
@@ -2398,10 +2791,10 @@ var payer = createRelayerX402Payer({
 await runMcpPaymentServer({
   payer,
   signer,
-  facilitatorBaseUrl: relayerBaseUrl,
+  relayerBaseUrl,
   defaultMaxAmountRawUsdc,
   vaultFlows: new VaultFlowClient({
-    facilitatorBaseUrl: relayerBaseUrl,
+    relayerBaseUrl,
     signer,
     rpc
   })