@subly_fi/pay 0.6.2 → 0.7.1

package/dist/mcp-server.js

@@ -1,24 +1,367 @@
-// src/mcp-server.ts
-import { homedir } from "node:os";
-import { join as join2 } from "node:path";
+// ../../src/config/vault-catalog.ts
+import { readFileSync } from "node:fs";
+import { z } from "zod";
 
-// ../../src/client/mcp-payment-server.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
+// ../../src/lib/solana-address.ts
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var BASE58_LOOKUP = new Map(
+  [...BASE58_ALPHABET].map((character, index) => [character, BigInt(index)])
+);
+function assertSolanaAddress(value, fieldName) {
+  if (value.length < 32 || value.length > 44) {
+    throw new Error(`${fieldName} must be a valid Solana public key`);
+  }
+  if (decodeBase58(value).length !== 32) {
+    throw new Error(`${fieldName} must be a valid Solana public key`);
+  }
+  return value;
+}
+function decodeBase58(value) {
+  if (value.length === 0) {
+    return new Uint8Array();
+  }
+  let decoded = 0n;
+  for (const character of value) {
+    const digit = BASE58_LOOKUP.get(character);
+    if (digit === void 0) {
+      return new Uint8Array();
+    }
+    decoded = decoded * 58n + digit;
+  }
+  const bytes = [];
+  while (decoded > 0n) {
+    bytes.push(Number(decoded & 0xffn));
+    decoded >>= 8n;
+  }
+  for (const character of value) {
+    if (character !== "1") {
+      break;
+    }
+    bytes.push(0);
+  }
+  return Uint8Array.from(bytes.reverse());
+}
 
-// ../../src/api/wallet-auth.ts
+// ../../src/config/vault.ts
+var MAINNET_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+var KAMINO_VAULT_PROGRAM_ID = "KvauGMspG5k6rtzrqqn7WNn3oZdyKqLKwK2XWQ8FLjd";
+var NO_VAULT_FARM = "11111111111111111111111111111111";
+var DEFAULT_VAULT_CONFIG = Object.freeze({
+  address: "5kfkpQZ6AkQgizHVThqkxD4J3db2i7pE3mHdPNRbx7jr",
+  programId: KAMINO_VAULT_PROGRAM_ID,
+  usdcMint: MAINNET_USDC_MINT,
+  shareMint: "7hGX49So539MU9Rrah8nBNVYXswWVwEJvgWNYeBDYq3a",
+  farm: "E2Ct77LowkDAH1T9ubwPpb84pU2GSGrUdgH3KeTTpLX"
+});
+function vaultConfigFromEnv(env = process.env) {
+  const value = (name) => env[name]?.trim() || void 0;
+  const vaultAddress = value("SUBLY_VAULT_ADDRESS") ?? DEFAULT_VAULT_CONFIG.address;
+  const customVault = vaultAddress !== DEFAULT_VAULT_CONFIG.address;
+  const anchor = (name, fallback) => {
+    const configured = value(name);
+    if (customVault && configured === void 0) {
+      throw new Error(
+        `${name} is required for a custom vault. Generate its settings with npm run configure:vault -- <vault-address>; use ${NO_VAULT_FARM} for a vault without a farm.`
+      );
+    }
+    return assertSolanaAddress(configured ?? fallback, name);
+  };
+  const usdcMint = value("SUBLY_VAULT_USDC_MINT") ?? MAINNET_USDC_MINT;
+  if (usdcMint !== MAINNET_USDC_MINT) {
+    throw new Error(
+      "SUBLY_VAULT_USDC_MINT must be mainnet USDC; other deposit assets are not supported"
+    );
+  }
+  return Object.freeze({
+    address: assertSolanaAddress(vaultAddress, "SUBLY_VAULT_ADDRESS"),
+    programId: KAMINO_VAULT_PROGRAM_ID,
+    usdcMint,
+    shareMint: anchor("SUBLY_VAULT_SHARE_MINT", DEFAULT_VAULT_CONFIG.shareMint),
+    farm: anchor("SUBLY_VAULT_FARM", DEFAULT_VAULT_CONFIG.farm)
+  });
+}
+
+// ../../src/config/vault-catalog.ts
+var publicKey = z.string().refine((value) => {
+  try {
+    assertSolanaAddress(value, "vault catalog address");
+    return true;
+  } catch {
+    return false;
+  }
+}, "Invalid Solana public key");
+var catalogSchema = z.object({
+  version: z.literal(1),
+  defaultVault: publicKey,
+  vaults: z.array(z.object({
+    address: publicKey,
+    programId: z.literal(KAMINO_VAULT_PROGRAM_ID),
+    usdcMint: z.literal(MAINNET_USDC_MINT),
+    shareMint: publicKey,
+    farm: publicKey,
+    name: z.string().min(1).max(128).optional(),
+    depositsEnabled: z.boolean().optional(),
+    extraLookupTables: z.array(publicKey).max(16).optional()
+  }).strict()).min(1).max(100)
+}).strict();
+function parseVaultCatalog(value) {
+  const catalog2 = catalogSchema.parse(value);
+  const addresses = new Set(catalog2.vaults.map((vault) => vault.address));
+  if (addresses.size !== catalog2.vaults.length) throw new Error("Duplicate vault in catalog");
+  if (!addresses.has(catalog2.defaultVault)) throw new Error("defaultVault must be in the vault catalog");
+  return { ...catalog2, vaults: catalog2.vaults.map((vault) => Object.freeze(vault)) };
+}
+function vaultCatalogFromEnv(env = process.env) {
+  const path = env.SUBLY_VAULTS_FILE?.trim();
+  if (!path) {
+    const vault = vaultConfigFromEnv(env);
+    return { version: 1, defaultVault: vault.address, vaults: [vault] };
+  }
+  const catalog2 = parseVaultCatalog(JSON.parse(readFileSync(path, "utf8")));
+  const selected2 = env.SUBLY_VAULT_ADDRESS?.trim() || catalog2.defaultVault;
+  if (!catalog2.vaults.some((vault) => vault.address === selected2)) {
+    throw new Error("SUBLY_VAULT_ADDRESS must be in SUBLY_VAULTS_FILE");
+  }
+  return { ...catalog2, defaultVault: selected2 };
+}
+function defaultCatalogVault(catalog2) {
+  return catalog2.vaults.find((vault) => vault.address === catalog2.defaultVault);
+}
+
+// ../../src/client/vault-selection.ts
+var McpVaultSelection = class {
+  selectedAddress;
+  sessions;
+  constructor(sessions2, defaultVault) {
+    this.sessions = new Map(sessions2.map((session) => [session.vault.address, session]));
+    if (this.sessions.size !== sessions2.length || !this.sessions.has(defaultVault)) {
+      throw new Error("MCP vault sessions must be unique and include the default vault");
+    }
+    this.selectedAddress = defaultVault;
+  }
+  current() {
+    return this.sessions.get(this.selectedAddress);
+  }
+  list() {
+    return {
+      selectedVault: this.selectedAddress,
+      vaults: [...this.sessions.values()].map(({ vault }) => vault)
+    };
+  }
+  /** The relayer only confirms support; addresses/mints are always pinned locally. */
+  async select(address3, relayerBaseUrl2, fetchImpl = fetch) {
+    const session = this.sessions.get(address3);
+    if (!session) throw new Error("Vault is not in this MCP client's local catalog");
+    const response = await fetchImpl(`${relayerBaseUrl2.replace(/\/$/, "")}/v1/vaults`, {
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) throw new Error(`Relayer vault list returned ${response.status}`);
+    const body = await response.json();
+    const remote = Array.isArray(body.vaults) ? body.vaults.find((vault) => vault?.address === address3) : void 0;
+    if (!remote) throw new Error("Vault is not configured on this relayer");
+    for (const field of ["programId", "usdcMint", "shareMint", "farm"]) {
+      if (remote[field] !== session.vault[field]) {
+        throw new Error(`Relayer ${field} differs from the local vault catalog`);
+      }
+    }
+    this.selectedAddress = address3;
+    return {
+      selectedVault: address3,
+      name: session.vault.name ?? null,
+      depositsEnabled: session.vault.depositsEnabled !== false && remote.depositsEnabled !== false,
+      instructions: "Subsequent tools use this vault. Existing funds stay in their original vault. Each vault needs its own owner setup and spending limits. Selection lasts until changed or this MCP process restarts."
+    };
+  }
+};
+
+// ../../src/config/constants.ts
+var PAYMENT_SCHEME = "subly-yield-exact";
+var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+var SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+var ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+var SUBLY_VAULT = defaultCatalogVault(vaultCatalogFromEnv());
+var USDC_DECIMALS = 6;
+
+// ../../src/lib/associated-token-account.ts
 import { createHash } from "node:crypto";
 import bs58 from "bs58";
+var PDA_MARKER = Buffer.from("ProgramDerivedAddress", "utf8");
+var ED25519_P = (1n << 255n) - 19n;
+var ED25519_D = mod(-121665n * modPow(121666n, ED25519_P - 2n, ED25519_P), ED25519_P);
+function deriveAssociatedTokenAddress(params) {
+  const owner = decodePublicKey(params.owner, "owner");
+  const mint = decodePublicKey(params.mint ?? SUBLY_VAULT.usdcMint, "mint");
+  const tokenProgramId = decodePublicKey(
+    params.tokenProgramId ?? SPL_TOKEN_PROGRAM_ID,
+    "tokenProgramId"
+  );
+  const associatedTokenProgramId = decodePublicKey(
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+    "associatedTokenProgramId"
+  );
+  for (let bump = 255; bump >= 0; bump -= 1) {
+    const address3 = createProgramAddress(
+      [owner, tokenProgramId, mint, Uint8Array.of(bump)],
+      associatedTokenProgramId
+    );
+    if (address3 !== null) {
+      return bs58.encode(address3);
+    }
+  }
+  throw new Error("Unable to derive associated token account address");
+}
+function createProgramAddress(seeds, programId) {
+  const hash = createHash("sha256");
+  for (const seed of seeds) {
+    hash.update(seed);
+  }
+  hash.update(programId);
+  hash.update(PDA_MARKER);
+  const digest = hash.digest();
+  return isEd25519Point(digest) ? null : new Uint8Array(digest);
+}
+function decodePublicKey(value, fieldName) {
+  const decoded = bs58.decode(value);
+  if (decoded.length !== 32) {
+    throw new Error(`${fieldName} must be a 32-byte public key`);
+  }
+  return decoded;
+}
+function isEd25519Point(bytes) {
+  if (bytes.length !== 32) {
+    return false;
+  }
+  const yBytes = Uint8Array.from(bytes);
+  yBytes[31] = yBytes[31] & 127;
+  const y = littleEndianToBigInt(yBytes);
+  if (y >= ED25519_P) {
+    return false;
+  }
+  const ySquared = mod(y * y, ED25519_P);
+  const numerator = mod(ySquared - 1n, ED25519_P);
+  const denominator = mod(ED25519_D * ySquared + 1n, ED25519_P);
+  if (denominator === 0n) {
+    return false;
+  }
+  const xSquared = mod(
+    numerator * modPow(denominator, ED25519_P - 2n, ED25519_P),
+    ED25519_P
+  );
+  return xSquared === 0n || modPow(xSquared, (ED25519_P - 1n) / 2n, ED25519_P) === 1n;
+}
+function littleEndianToBigInt(bytes) {
+  let value = 0n;
+  for (let index = bytes.length - 1; index >= 0; index -= 1) {
+    value = (value << 8n) + BigInt(bytes[index]);
+  }
+  return value;
+}
+function mod(value, modulus) {
+  const result = value % modulus;
+  return result >= 0n ? result : result + modulus;
+}
+function modPow(base, exponent, modulus) {
+  let result = 1n;
+  let nextBase = mod(base, modulus);
+  let nextExponent = exponent;
+  while (nextExponent > 0n) {
+    if ((nextExponent & 1n) === 1n) {
+      result = mod(result * nextBase, modulus);
+    }
+    nextBase = mod(nextBase * nextBase, modulus);
+    nextExponent >>= 1n;
+  }
+  return result;
+}
+
+// ../../src/client/withdrawal-preview.ts
+var ROUNDING_RAW_USDC = 10n;
+async function assertWithdrawalPreview(input) {
+  const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
+  const simulation = await input.rpc.simulateTransaction(
+    input.serializedTransaction,
+    {
+      encoding: "base64",
+      commitment: "confirmed",
+      sigVerify: false,
+      replaceRecentBlockhash: false,
+      innerInstructions: true
+    }
+  ).send({ abortSignal: AbortSignal.timeout(15e3) });
+  if (simulation.value.err !== null) {
+    throw new Error("Withdrawal preview failed on the client RPC; no transaction was signed. Check liquidity, RPC and blockhash, then prepare again.");
+  }
+  let received = 0n;
+  for (const group of simulation.value.innerInstructions ?? []) {
+    for (const instruction of group.instructions) {
+      if (!("parsed" in instruction) || instruction.programId !== SPL_TOKEN_PROGRAM_ID) continue;
+      const parsed = instruction.parsed;
+      if (parsed.type !== "transfer" && parsed.type !== "transferChecked") continue;
+      const info = parsed.info;
+      if (!info || info.destination !== destination && info.source !== destination) continue;
+      const raw = parsed.type === "transferChecked" ? info.tokenAmount?.amount : info.amount;
+      if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
+        throw new Error("Withdrawal preview returned an invalid token amount");
+      }
+      const amount = BigInt(raw);
+      if (info.destination === destination) received += amount;
+      if (info.source === destination) received -= amount;
+    }
+  }
+  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+    throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
+  }
+}
+
+// ../../src/client/lookup-tables.ts
+import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
+import { address, getCompiledTransactionMessageDecoder } from "@solana/kit";
+function lookupTableAddressesForTransaction(serializedTransaction) {
+  const wire = Buffer.from(serializedTransaction, "base64");
+  let offset = 0;
+  let signatureCount = 0;
+  let shift = 0;
+  while (offset < wire.length) {
+    const byte = wire[offset];
+    signatureCount |= (byte & 127) << shift;
+    offset += 1;
+    if ((byte & 128) === 0) {
+      break;
+    }
+    shift += 7;
+  }
+  const messageBytes = wire.subarray(offset + signatureCount * 64);
+  const compiled = getCompiledTransactionMessageDecoder().decode(messageBytes);
+  const lookups = compiled.addressTableLookups ?? [];
+  return lookups.map((lookup) => String(lookup.lookupTableAddress));
+}
+async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
+  const addresses = lookupTableAddressesForTransaction(serializedTransaction);
+  if (addresses.length === 0) {
+    return {};
+  }
+  const tables = await fetchAllMaybeAddressLookupTable(
+    rpc2,
+    addresses.map((value) => address(value))
+  );
+  const result = {};
+  for (const table of tables) {
+    if (table.exists) {
+      result[table.address] = table.data.addresses.map(String);
+    }
+  }
+  return result;
+}
+
+// ../../src/api/wallet-auth.ts
+import { createHash as createHash2 } from "node:crypto";
+import bs582 from "bs58";
 import nacl from "tweetnacl";
 var WALLET_AUTH_WALLET_HEADER = "x-subly-wallet";
 var WALLET_AUTH_SIGNED_AT_HEADER = "x-subly-signed-at";
 var WALLET_AUTH_SIGNATURE_HEADER = "x-subly-signature";
 function sha256Hex(data) {
-  return createHash("sha256").update(data, "utf8").digest("hex");
+  return createHash2("sha256").update(data, "utf8").digest("hex");
 }
 function walletAuthMessage(params) {
   return new TextEncoder().encode(
@@ -47,1054 +390,1165 @@ async function walletAuthHeaders(params) {
   };
 }
 
-// ../../src/client/onboarding.ts
-var SELF_SERVE_POLICY_ID = "self-serve";
-var OnboardingError = class extends Error {
-  constructor(step, message, detail = null) {
+// ../../src/client/vault-flows.ts
+var VaultFlowClientError = class extends Error {
+  constructor(step, message, detail = null, code = null, errorDetails = null) {
     super(message);
     this.step = step;
     this.detail = detail;
-    this.name = "OnboardingError";
+    this.code = code;
+    this.errorDetails = errorDetails;
+    this.name = "VaultFlowClientError";
   }
   step;
   detail;
+  code;
+  errorDetails;
 };
-async function ensureWalletOnboarded(params) {
-  const fetchImpl = params.fetchImpl ?? fetch;
-  const baseUrl = params.relayerBaseUrl.replace(/\/$/, "");
-  const post = async (step, path, body) => {
-    const url = `${baseUrl}${path}`;
-    const serialized = JSON.stringify(body);
-    const response = await fetchImpl(url, {
-      method: "POST",
-      headers: {
-        ...await walletAuthHeaders({
-          signer: params.signer,
-          method: "POST",
-          url,
-          body: serialized
-        }),
-        "content-type": "application/json"
-      },
-      body: serialized
-    });
-    if (response.status !== 200) {
-      let detail = null;
-      try {
-        detail = await response.json();
-      } catch {
-        detail = null;
-      }
-      throw new OnboardingError(
-        step,
-        `wallet onboarding ${step} failed with ${response.status}`,
-        detail
-      );
+var VaultFlowClient = class {
+  vault;
+  rpc;
+  baseUrl;
+  signer;
+  fetchImpl;
+  lookupTablesFor;
+  pollTimeoutMs;
+  pollIntervalMs;
+  constructor(config) {
+    this.rpc = config.rpc;
+    this.vault = config.vault ?? config.signer.vault ?? SUBLY_VAULT;
+    if (config.signer.vault && config.signer.vault.address !== this.vault.address) {
+      throw new Error("Vault flow client and signer must select the same vault");
     }
-  };
-  const wallet = params.signer.walletAddress;
-  await post("register", "/v1/wallets/agent", {
-    wallet,
-    signingPolicyId: SELF_SERVE_POLICY_ID,
-    signingMode: "non_interactive",
-    signerValidationMode: params.signer.validationMode,
-    signerProvider: params.signer.provider ?? "local-keypair",
-    activateForPayments: true
-  });
-  await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain" });
-}
-
-// ../../src/x402/headers.ts
-import { z } from "zod";
-
-// ../../src/config/constants.ts
-var PAYMENT_SCHEME = "subly-yield-exact";
-var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
-var SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
-var ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
-var envOr = (name, fallback) => {
-  const value = process.env[name]?.trim();
-  return value ? value : fallback;
-};
-var SUBLY_VAULT = {
-  name: "Subly USDC Payment Vault Alpha",
-  address: envOr(
-    "SUBLY_VAULT_ADDRESS",
-    "5kfkpQZ6AkQgizHVThqkxD4J3db2i7pE3mHdPNRbx7jr"
-  ),
-  programId: "KvauGMspG5k6rtzrqqn7WNn3oZdyKqLKwK2XWQ8FLjd",
-  usdcMint: envOr(
-    "SUBLY_VAULT_USDC_MINT",
-    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
-  ),
-  shareMint: envOr(
-    "SUBLY_VAULT_SHARE_MINT",
-    "7hGX49So539MU9Rrah8nBNVYXswWVwEJvgWNYeBDYq3a"
-  ),
-  lookupTable: "7UbXhDnpK7WVnwsfivzQRENoqKqAULQ5s19gS1xJrQEo",
-  farm: envOr(
-    "SUBLY_VAULT_FARM",
-    "E2Ct77LowkDAH1T9ubwPpb84pU2GSGrUdgH3KeTTpLX"
-  )
-};
-var USDC_DECIMALS = 6;
-
-// ../../src/lib/hash.ts
-import { createHash as createHash2 } from "node:crypto";
-var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
-function sha256TaggedHex(data) {
-  return `sha256-${createHash2("sha256").update(data).digest("hex")}`;
-}
-function stableStringify(value) {
-  if (value === null) {
-    return "null";
-  }
-  if (typeof value === "bigint") {
-    return JSON.stringify(value.toString());
-  }
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    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;
   }
-  const keys = Object.keys(value).filter((key) => value[key] !== void 0).sort();
-  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
-}
-function hashStableJson(value) {
-  return sha256TaggedHex(stableStringify(value));
-}
-
-// ../../src/x402/headers.ts
-var PAYMENT_REQUIRED_HEADER = "payment-required";
-var MAX_HEADER_JSON_BYTES = 16384;
-var X402HeaderError = class extends Error {
-  reason;
-  constructor(reason, message) {
-    super(message);
-    this.name = "X402HeaderError";
-    this.reason = reason;
+  /**
+   * 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) {
+    let approvalId = input.approvalId;
+    let prepared;
+    try {
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        vault: this.vault.address,
+        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,
+        vault: this.vault.address,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        approvalId
+      });
+    }
+    if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.signingIntent.amountRawUsdc !== input.amountRawUsdc.toString()) {
+      throw new VaultFlowClientError("prepare", "Prepared deposit differs from the requested wallet, vault or amount");
+    }
+    const signed = await this.signer.signDeposit({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
+    });
+    let outcome = await this.postJson("submit", "/v1/deposits/submit", {
+      depositId: prepared.depositId,
+      serializedTransaction: signed.serializedTransaction,
+      agentSignature: signed.agentSignature
+    });
+    if (outcome.status === "submitted") {
+      outcome = await this.pollUntilTerminal(
+        `/v1/deposits/${prepared.depositId}`,
+        outcome
+      );
+    }
+    return {
+      depositId: prepared.depositId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      actualDepositRawUsdc: outcome.actualDepositRawUsdc ?? null,
+      sharesMintedRaw: outcome.sharesMintedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
+    };
   }
-};
-var sublyPaymentRequirementsSchema = z.object({
-  scheme: z.literal(PAYMENT_SCHEME),
-  network: z.string().min(1),
-  asset: z.string().min(32),
-  /** Exact seller amount in raw USDC; the scheme settles exactly this. */
-  amountRawUsdc: z.string().regex(/^[1-9]\d*$/),
-  resource: z.string().url(),
-  description: z.string().optional(),
-  mimeType: z.string().optional(),
-  payTo: z.string().min(32),
-  maxTimeoutSeconds: z.number().int().positive(),
-  extra: z.object({
-    sellerRequestId: z.string().min(1),
-    seller: z.string().min(32),
-    sellerUsdcAta: z.string().min(32),
-    vault: z.string().min(32),
-    shareMint: z.string().min(32)
-  })
-}).loose();
-var paymentRequiredSchema = z.object({
-  x402Version: z.number().int(),
-  accepts: z.array(z.unknown()),
-  error: z.string().optional()
-}).loose();
-var sublyPaymentPayloadSchema = z.object({
-  x402Version: z.number().int(),
-  scheme: z.literal(PAYMENT_SCHEME),
-  network: z.string().min(1),
-  payload: z.object({
-    paymentId: z.string().min(1),
-    requestBindingHash: z.string().min(1),
-    preparedMessageHash: z.string().min(1),
-    serializedTransaction: z.string().min(1).max(4096),
-    agentSignature: z.string().min(1).max(128),
-    temporarySettlementSignature: z.string().min(1).max(128)
-  })
-}).loose();
-function decodeX402Header(headerValue) {
-  if (headerValue.length > Math.ceil(MAX_HEADER_JSON_BYTES * 4 / 3) + 4) {
-    throw new X402HeaderError(
-      "header_too_large",
-      `x402 header exceeds ${MAX_HEADER_JSON_BYTES} encoded bytes`
+  /**
+   * Moves USDC from the vault back to the agent wallet's USDC ATA (fee
+   * sponsored). A plain withdrawal is the exit path and MAY spend principal;
+   * with purpose "yield_realize" the relayer refuses anything beyond the
+   * spendable yield (the payment path, via RelayerYieldRealizer).
+   */
+  async withdraw(input) {
+    const prepared = await this.postJson(
+      "prepare",
+      "/v1/withdrawals/prepare",
+      {
+        wallet: this.signer.walletAddress,
+        vault: this.vault.address,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
+      }
     );
+    if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || prepared.purpose !== (input.purpose ?? "normal") || input.purpose === "yield_realize" && prepared.signingIntent.allowFullExit) {
+      throw new VaultFlowClientError("prepare", "Prepared withdrawal differs from the requested operation");
+    }
+    await assertWithdrawalPreview({
+      rpc: this.rpc,
+      serializedTransaction: prepared.serializedTransaction,
+      wallet: this.signer.walletAddress,
+      vault: this.vault,
+      amountRawUsdc: input.amountRawUsdc
+    });
+    const signed = await this.signer.signWithdrawal({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
+    });
+    let outcome = await this.postJson("submit", "/v1/withdrawals/submit", {
+      withdrawalId: prepared.withdrawalId,
+      serializedTransaction: signed.serializedTransaction,
+      agentSignature: signed.agentSignature
+    });
+    if (outcome.status === "submitted") {
+      outcome = await this.pollUntilTerminal(
+        `/v1/withdrawals/${prepared.withdrawalId}`,
+        outcome
+      );
+    }
+    return {
+      withdrawalId: prepared.withdrawalId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      destinationUsdcAta: prepared.destinationUsdcAta,
+      actualWithdrawRawUsdc: outcome.actualWithdrawRawUsdc ?? null,
+      actualSharesBurnedRaw: outcome.actualSharesBurnedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
+    };
   }
-  const json = Buffer.from(headerValue, "base64").toString("utf8");
-  try {
-    return JSON.parse(json);
-  } catch {
-    throw new X402HeaderError(
-      "invalid_header_encoding",
-      "x402 header is not base64-encoded JSON"
-    );
+  /**
+   * Reads the yield budget. Syncs the relayer's ledger from chain first (so
+   * yield accrued since the last sync shows up); the sync is best-effort and
+   * on failure the last-synced view is returned.
+   */
+  async getBudget(options = {}) {
+    if (options.refreshFromChain !== false) {
+      try {
+        await this.postJson(
+          "sync",
+          `/v1/wallets/${this.signer.walletAddress}/sync`,
+          { source: "chain", vault: this.vault.address }
+        );
+      } catch {
+      }
+    }
+    const url = `${this.baseUrl}/v1/wallets/${this.signer.walletAddress}/budget?vault=${this.vault.address}`;
+    const response = await this.fetchImpl(url, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      throw new VaultFlowClientError(
+        "budget",
+        `budget endpoint returned ${response.status}: ${text}`
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "budget",
+        "budget endpoint returned 200 with a non-JSON body",
+        text
+      );
+    }
+    const body = parsed;
+    if (body.position?.vault !== void 0 && body.position.vault !== this.vault.address) {
+      throw new VaultFlowClientError("budget", "Relayer returned the budget for a different vault");
+    }
+    return {
+      wallet: this.signer.walletAddress,
+      vault: this.vault.address,
+      principalBasisRawUsdc: body.position?.principalBasisRawUsdc ?? "0",
+      positionValueRawUsdc: body.budget?.positionValueRawUsdc ?? "0",
+      grossYieldRawUsdc: body.budget?.grossYieldRawUsdc ?? "0",
+      spendableYieldRawUsdc: body.budget?.spendableYieldRawUsdc ?? "0"
+    };
   }
-}
-function requestBodyHashFor(body) {
-  if (body === null || body === void 0 || body.length === 0) {
-    return EMPTY_BODY_HASH;
+  /** 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
+    });
   }
-  return sha256TaggedHex(
-    typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body)
-  );
-}
-
-// ../../src/client/paid-fetch.ts
-function formatRawUsdcAmount(raw) {
-  const value = BigInt(raw);
-  const negative = value < 0n;
-  const abs = negative ? -value : value;
-  const whole = abs / 1000000n;
-  const frac = (abs % 1000000n).toString().padStart(6, "0");
-  return `${negative ? "-" : ""}${whole}.${frac}`;
-}
-
-// ../../src/lib/canonical-json.ts
-import { createHash as createHash3 } from "node:crypto";
-function sha256HexOf(data) {
-  return createHash3("sha256").update(data, "utf8").digest("hex");
-}
-
-// ../../src/x402/standard-requirements.ts
-import { z as z2 } from "zod";
-var STANDARD_EXACT_SCHEME = "exact";
-var standardExactRequirementSchema = z2.object({
-  scheme: z2.literal(STANDARD_EXACT_SCHEME),
-  /** CAIP-2 chain id, e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". */
-  network: z2.string().min(1),
-  /** SPL mint (Solana) or token contract (EVM); Subly only pays USDC/Solana. */
-  asset: z2.string().min(1),
-  /** Exact price in the asset's atomic units, as a decimal string. */
-  amount: z2.string().regex(/^[1-9]\d*$/),
-  /** Recipient wallet; the transfer destination ATA is derived from it. */
-  payTo: z2.string().min(1),
-  maxTimeoutSeconds: z2.number().int().positive().optional(),
-  extra: z2.object({
-    /** Facilitator address that pays the tx fee (gas sponsorship). */
-    feePayer: z2.string().min(1).optional()
-  }).loose().optional()
-}).loose();
-var standardPaymentRequiredSchema = z2.object({
-  x402Version: z2.number().int(),
-  accepts: z2.array(z2.unknown()),
-  error: z2.string().optional(),
-  resource: z2.object({ url: z2.string().optional() }).loose().optional()
-}).loose();
-var StandardX402ChallengeError = class extends Error {
-  reason;
-  constructor(reason, message) {
-    super(message);
-    this.name = "StandardX402ChallengeError";
-    this.reason = reason;
+  /** 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${`?vault=${this.vault.address}${status === void 0 ? "" : `&status=${encodeURIComponent(status)}`}`}`
+    );
+    return body.approvals ?? [];
   }
-};
-function parseStandardChallenge(challenge) {
-  const parsed = standardPaymentRequiredSchema.safeParse(challenge);
-  if (!parsed.success) {
-    throw new StandardX402ChallengeError(
-      "invalid_payment_required",
-      "Response is not a valid x402 PaymentRequired object"
+  /**
+   * Creates the owner-onboarding setup link (wallet-auth pins the agreed
+   * policy + initial deposit). Paste `setupUrl` into the chat verbatim.
+   */
+  async createSetupSession(input) {
+    const session = await this.postJson(
+      "prepare",
+      `/v1/wallets/${this.signer.walletAddress}/setup-sessions`,
+      {
+        vault: this.vault.address,
+        ...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 }
+      }
     );
+    if (session.vault !== this.vault.address || session.wallet !== this.signer.walletAddress) {
+      throw new VaultFlowClientError("prepare", "Relayer returned a setup session for a different wallet or vault");
+    }
+    return session;
   }
-  const solanaExactRequirements = parsed.data.accepts.flatMap((candidate) => {
-    const requirement = standardExactRequirementSchema.safeParse(candidate);
-    if (!requirement.success) {
-      return [];
+  /** 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 requirement.data.network.startsWith("solana:") ? [requirement.data] : [];
-  });
-  return { paymentRequired: parsed.data, solanaExactRequirements };
-}
-function decodeStandardPaymentRequiredHeader(headerValue) {
-  let decoded;
-  try {
-    decoded = decodeX402Header(headerValue);
-  } catch (error) {
-    throw new StandardX402ChallengeError(
-      error instanceof X402HeaderError ? error.reason : "invalid_header",
-      "Cannot decode the payment-required header"
-    );
+    return JSON.parse(text);
   }
-  return parseStandardChallenge(decoded);
-}
-function selectPayableSolanaRequirement(requirements, options) {
-  const network = options?.network ?? SOLANA_MAINNET_NETWORK;
-  const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
-  const matchingRequirements = requirements.filter(
-    (candidate) => candidate.network === network && candidate.asset === usdcMint
-  );
-  if (matchingRequirements.length === 0) {
-    throw new StandardX402ChallengeError(
-      "no_payable_requirement",
-      `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
-    );
+  /**
+   * 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;
+    }
   }
-  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"
-    );
+  /**
+   * Polls the reconciling GET endpoint until the intent leaves "submitted"
+   * (each read looks the tx up on-chain) or the timeout elapses.
+   */
+  async pollUntilTerminal(path, last) {
+    const deadline = Date.now() + this.pollTimeoutMs;
+    let latest = last;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
+      const url = `${this.baseUrl}${path}`;
+      const response = await this.fetchImpl(url, {
+        headers: await walletAuthHeaders({
+          signer: this.signer,
+          method: "GET",
+          url
+        })
+      });
+      if (response.status !== 200) {
+        continue;
+      }
+      try {
+        latest = await response.json();
+      } catch {
+        continue;
+      }
+      if (latest.status !== "submitted") {
+        return latest;
+      }
+    }
+    return latest;
   }
-  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"
-    );
+  async postJson(step, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const serialized = JSON.stringify(body);
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...await walletAuthHeaders({
+          signer: this.signer,
+          method: "POST",
+          url,
+          body: serialized
+        }),
+        "content-type": "application/json"
+      },
+      body: serialized
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        step,
+        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(
+        step,
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
+    }
   }
-  return {
-    requirement,
-    amountRawUsdc: BigInt(requirement.amount),
-    payTo: requirement.payTo,
-    feePayer
-  };
-}
-function standardRequirementMatchesSelected(candidate, selected) {
-  const parsed = standardExactRequirementSchema.safeParse(candidate);
-  return parsed.success && stableJson(parsed.data) === stableJson(selected.requirement);
-}
-function stableJson(value) {
-  return JSON.stringify(sortJson(value));
-}
-function sortJson(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJson);
+  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
+      );
+    }
   }
-  if (value !== null && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, sortJson(entry)])
-    );
+};
+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 };
   }
-  return value;
 }
 
-// ../../src/client/standard-x402-payer.ts
-var StandardX402PayError = class extends Error {
-  constructor(reason, message, detail = null) {
+// ../../src/client/relayer-yield-realizer.ts
+var REALIZE_OVERHEAD_RAW_USDC = 2500n;
+var RelayerRealizeError = class extends Error {
+  constructor(code, message, detail = null) {
     super(message);
-    this.reason = reason;
+    this.code = code;
     this.detail = detail;
-    this.name = "StandardX402PayError";
+    this.name = "RelayerRealizeError";
   }
-  reason;
+  code;
   detail;
 };
-var StandardX402Payer = class {
-  realizer;
-  x402Fetch;
-  probeFetch;
-  defaultMaxAmountRawUsdc;
-  network;
-  usdcMint;
-  stateStore;
-  pending = /* @__PURE__ */ new Map();
-  inFlight = /* @__PURE__ */ new Map();
-  nowMs;
-  constructor(config) {
-    this.realizer = config.realizer;
-    this.x402Fetch = config.x402Fetch;
-    this.probeFetch = config.probeFetch ?? fetch;
-    this.defaultMaxAmountRawUsdc = config.defaultMaxAmountRawUsdc;
-    this.network = config.network ?? SOLANA_MAINNET_NETWORK;
-    this.usdcMint = config.usdcMint ?? SUBLY_VAULT.usdcMint;
-    this.stateStore = config.stateStore ?? null;
-    this.nowMs = config.nowMs ?? (() => Date.now());
-    if (this.stateStore !== null) {
-      for (const record of this.stateStore.load()) {
-        this.pending.set(record.key, record);
-      }
-    }
+var RelayerYieldRealizer = class {
+  get vault() {
+    return this.vaultFlows.vault.address;
   }
-  pay(input) {
-    const method = (input.method ?? "GET").toUpperCase();
-    const requestBodyHash = requestBodyHashFor(input.body ?? null);
-    const pendingKey = pendingPaymentKey({
-      url: input.url,
-      method,
-      requestBodyHash
-    });
-    const existingFlow = this.inFlight.get(pendingKey);
-    if (existingFlow !== void 0) {
-      return existingFlow;
-    }
-    const flow = this.run(input, {
-      method,
-      requestBodyHash,
-      pendingKey
-    }).finally(() => {
-      this.inFlight.delete(pendingKey);
+  vaultFlows;
+  constructor(config) {
+    this.vaultFlows = new VaultFlowClient({
+      relayerBaseUrl: config.relayerBaseUrl,
+      signer: config.signer,
+      rpc: config.rpc,
+      ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
+      ...config.lookupTablesFor === void 0 ? {} : { lookupTablesFor: config.lookupTablesFor }
     });
-    this.inFlight.set(pendingKey, flow);
-    return flow;
   }
-  async run(input, computed) {
-    const { method, requestBodyHash, pendingKey } = computed;
-    const existingPending = this.pending.get(pendingKey);
-    if (existingPending !== void 0 && input.forceNewPayment !== true) {
-      throw new StandardX402PayError(
-        "payment_outcome_unknown",
-        "a previous external x402 payment for this request has an unknown outcome. Verify whether it settled before purchasing again; to pay again anyway, call with forceNewPayment=true.",
-        existingPending
-      );
-    }
-    if (existingPending !== void 0 && input.forceNewPayment === true) {
-      try {
-        this.untrack(pendingKey);
-      } catch (error) {
-        throw new StandardX402PayError(
-          "state_persist_failed",
-          "could not clear the previous pending x402 marker before forcing a new payment",
-          error
-        );
-      }
-    }
-    const init = {
-      method,
-      ...input.body === void 0 ? {} : { body: input.body },
-      ...input.headers === void 0 ? {} : { headers: input.headers }
-    };
-    const probe = await this.probeFetch(input.url, init);
-    if (probe.status !== 402) {
-      return { paid: false, status: probe.status, body: await probe.text() };
-    }
-    const selected = await this.selectRequirement(probe);
-    const cap = input.maxAmountRawUsdc ?? this.defaultMaxAmountRawUsdc;
-    if (selected.amountRawUsdc > cap) {
-      throw new StandardX402PayError(
-        "amount_exceeds_client_cap",
-        `the challenge demands ${selected.amountRawUsdc} raw USDC, above the client cap of ${cap}; nothing was paid`,
-        { amountRawUsdc: selected.amountRawUsdc.toString(), payTo: selected.payTo }
-      );
-    }
-    let realized;
+  async ensureUsdcAvailable(input) {
+    const shortfallRawUsdc = input.amountRawUsdc;
+    await this.assertSpendableYield(shortfallRawUsdc);
+    let outcome;
     try {
-      realized = await this.realizer.ensureUsdcAvailable({
-        amountRawUsdc: selected.amountRawUsdc,
-        payment: {
-          payTo: selected.payTo,
-          amountRawUsdc: selected.amountRawUsdc.toString(),
-          resourceUrlHash: sha256HexOf(input.url),
-          method
-        },
+      outcome = await this.vaultFlows.withdraw({
+        amountRawUsdc: shortfallRawUsdc,
+        // The relayer refuses to prepare this withdrawal beyond the spendable
+        // yield — the principal-protection guard the client cannot bypass.
+        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) {
-      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)}`,
-        error
-      );
-    }
-    const pendingRecord = {
-      key: pendingKey,
-      url: input.url,
-      method,
-      requestBodyHash,
-      amountRawUsdc: selected.amountRawUsdc.toString(),
-      payTo: selected.payTo,
-      feePayer: selected.feePayer,
-      realizedRawUsdc: realized.realizedRawUsdc.toString(),
-      realizeTxSignature: realized.txSignature,
-      status: "realized",
-      createdAtMs: this.nowMs(),
-      updatedAtMs: this.nowMs()
-    };
-    try {
-      this.track(pendingRecord);
-    } catch (error) {
-      throw new StandardX402PayError(
-        "state_persist_failed",
-        "could not persist the pending x402 marker; refusing to attempt the external payment because a restart would not be double-payment safe",
-        { error, pendingPayment: pendingRecord }
-      );
-    }
-    let response;
-    try {
-      response = await this.x402Fetch(input.url, init, selected);
-    } catch (error) {
-      const persistError = this.tryMarkUnknown(pendingKey, {
-        message: error instanceof Error ? error.message : String(error)
-      });
-      throw new StandardX402PayError(
-        "payment_outcome_unknown",
-        `the x402 payment attempt failed after yield was realized; verify whether it settled before paying again: ${error instanceof Error ? error.message : String(error)}`,
-        { error, persistError }
-      );
-    }
-    const bodyText = await response.text();
-    if (response.status !== 200) {
-      const persistError = this.tryMarkUnknown(pendingKey, {
-        status: response.status,
-        body: bodyText
-      });
-      throw new StandardX402PayError(
-        "payment_outcome_unknown",
-        `the x402 payment attempt returned ${response.status} after yield was realized; verify whether it settled before paying again`,
-        { status: response.status, body: bodyText, persistError }
-      );
-    }
-    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)}`
-        );
-      }
+      throw this.mapWithdrawError(error);
     }
-    return {
-      paid: true,
-      status: response.status,
-      body: bodyText,
-      payment: {
-        amountRawUsdc: selected.amountRawUsdc.toString(),
-        payTo: selected.payTo,
-        feePayer: selected.feePayer,
-        realizedRawUsdc: realized.realizedRawUsdc.toString(),
-        realizeTxSignature: realized.txSignature,
-        paymentTxSignature
-      }
+    if (outcome.status !== "confirmed" || outcome.txSignature === null) {
+      throw new RelayerRealizeError(
+        "realize_not_confirmed",
+        `yield realize withdrawal did not confirm (status=${outcome.status})`,
+        outcome
+      );
+    }
+    return {
+      realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
+      txSignature: outcome.txSignature,
+      withdrawalId: outcome.withdrawalId
     };
   }
-  /** Reads the challenge from the header (preferred) or the JSON body. */
-  async selectRequirement(probe) {
-    const header = probe.headers.get(PAYMENT_REQUIRED_HEADER);
-    let requirements;
+  /**
+   * 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
+   * long-running client sees yield as it accrues instead of a frozen view.
+   */
+  async assertSpendableYield(shortfallRawUsdc) {
+    let spendable;
     try {
-      if (header !== null) {
-        requirements = decodeStandardPaymentRequiredHeader(header).solanaExactRequirements;
-      } else {
-        requirements = parseStandardChallenge(
-          await probe.json()
-        ).solanaExactRequirements;
-      }
+      const budget = await this.vaultFlows.getBudget();
+      spendable = BigInt(budget.spendableYieldRawUsdc);
     } catch (error) {
-      throw new StandardX402PayError(
-        error instanceof StandardX402ChallengeError ? error.reason : "invalid_challenge",
-        "could not parse the x402 402 challenge",
+      throw new RelayerRealizeError(
+        "budget_unavailable",
+        "could not read the spendable-yield budget",
         error
       );
     }
-    try {
-      return selectPayableSolanaRequirement(requirements, {
-        network: this.network,
-        usdcMint: this.usdcMint
-      });
-    } catch (error) {
-      throw new StandardX402PayError(
-        "no_payable_requirement",
-        error instanceof Error ? error.message : String(error),
+    const requiredRawUsdc = shortfallRawUsdc + REALIZE_OVERHEAD_RAW_USDC;
+    if (spendable < requiredRawUsdc) {
+      throw new RelayerRealizeError(
+        "insufficient_yield",
+        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC plus the ${REALIZE_OVERHEAD_RAW_USDC} raw fee headroom; the principal is never spent \u2014 wait for more yield`,
+        { spendableYieldRawUsdc: spendable.toString() }
+      );
+    }
+  }
+  mapWithdrawError(error) {
+    if (!(error instanceof VaultFlowClientError)) {
+      return new RelayerRealizeError(
+        "prepare_failed",
+        `yield realize failed: ${error instanceof Error ? error.message : String(error)}`,
         error
       );
     }
+    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",
+        "the relayer refused to realize beyond the spendable yield; the principal is never spent \u2014 wait for more yield",
+        error.detail
+      );
+    }
+    return new RelayerRealizeError(
+      error.step === "submit" ? "submit_failed" : "prepare_failed",
+      error.message,
+      error.detail
+    );
   }
-  track(record) {
-    const previous = this.pending.get(record.key);
-    this.pending.set(record.key, record);
-    try {
-      this.persist();
-    } catch (error) {
-      if (previous === void 0) {
-        this.pending.delete(record.key);
-      } else {
-        this.pending.set(record.key, previous);
+};
+function errorCodeFrom(detail) {
+  if (typeof detail !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(detail);
+    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/mcp-server.ts
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// ../../src/client/mcp-payment-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ../../src/client/onboarding.ts
+var SELF_SERVE_POLICY_ID = "self-serve";
+var OnboardingError = class extends Error {
+  constructor(step, message, detail = null) {
+    super(message);
+    this.step = step;
+    this.detail = detail;
+    this.name = "OnboardingError";
+  }
+  step;
+  detail;
+};
+async function ensureWalletOnboarded(params) {
+  const fetchImpl = params.fetchImpl ?? fetch;
+  const baseUrl = params.relayerBaseUrl.replace(/\/$/, "");
+  const post = async (step, path, body) => {
+    const url = `${baseUrl}${path}`;
+    const serialized = JSON.stringify(body);
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...await walletAuthHeaders({
+          signer: params.signer,
+          method: "POST",
+          url,
+          body: serialized
+        }),
+        "content-type": "application/json"
+      },
+      body: serialized
+    });
+    if (response.status !== 200) {
+      let detail = null;
+      try {
+        detail = await response.json();
+      } catch {
+        detail = null;
       }
-      throw error;
+      throw new OnboardingError(
+        step,
+        `wallet onboarding ${step} failed with ${response.status}`,
+        detail
+      );
     }
+  };
+  const wallet = params.signer.walletAddress;
+  const vault = params.vault ?? params.signer.vault?.address ?? SUBLY_VAULT.address;
+  await post("register", "/v1/wallets/agent", {
+    wallet,
+    vault,
+    signingPolicyId: SELF_SERVE_POLICY_ID,
+    signingMode: "non_interactive",
+    signerValidationMode: params.signer.validationMode,
+    signerProvider: params.signer.provider ?? "local-keypair",
+    activateForPayments: true
+  });
+  await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain", vault });
+}
+
+// ../../src/x402/headers.ts
+import { z as z2 } from "zod";
+
+// ../../src/lib/hash.ts
+import { createHash as createHash3 } from "node:crypto";
+var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+function sha256TaggedHex(data) {
+  return `sha256-${createHash3("sha256").update(data).digest("hex")}`;
+}
+function stableStringify(value) {
+  if (value === null) {
+    return "null";
   }
-  markUnknown(key, detail) {
-    const current = this.pending.get(key);
-    if (current === void 0) {
-      return;
-    }
-    const next = {
-      ...current,
-      status: "external_outcome_unknown",
-      updatedAtMs: this.nowMs(),
-      detail
-    };
-    this.pending.set(key, next);
-    try {
-      this.persist();
-    } catch (error) {
-      this.pending.set(key, current);
-      throw error;
-    }
+  if (typeof value === "bigint") {
+    return JSON.stringify(value.toString());
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const keys = Object.keys(value).filter((key) => value[key] !== void 0).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+}
+function hashStableJson(value) {
+  return sha256TaggedHex(stableStringify(value));
+}
+
+// ../../src/x402/headers.ts
+var PAYMENT_REQUIRED_HEADER = "payment-required";
+var MAX_HEADER_JSON_BYTES = 16384;
+var X402HeaderError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "X402HeaderError";
+    this.reason = reason;
+  }
+};
+var sublyPaymentRequirementsSchema = z2.object({
+  scheme: z2.literal(PAYMENT_SCHEME),
+  network: z2.string().min(1),
+  asset: z2.string().min(32),
+  /** Exact seller amount in raw USDC; the scheme settles exactly this. */
+  amountRawUsdc: z2.string().regex(/^[1-9]\d*$/),
+  resource: z2.string().url(),
+  description: z2.string().optional(),
+  mimeType: z2.string().optional(),
+  payTo: z2.string().min(32),
+  maxTimeoutSeconds: z2.number().int().positive(),
+  extra: z2.object({
+    sellerRequestId: z2.string().min(1),
+    seller: z2.string().min(32),
+    sellerUsdcAta: z2.string().min(32),
+    vault: z2.string().min(32),
+    shareMint: z2.string().min(32)
+  })
+}).loose();
+var paymentRequiredSchema = z2.object({
+  x402Version: z2.number().int(),
+  accepts: z2.array(z2.unknown()),
+  error: z2.string().optional()
+}).loose();
+var sublyPaymentPayloadSchema = z2.object({
+  x402Version: z2.number().int(),
+  scheme: z2.literal(PAYMENT_SCHEME),
+  network: z2.string().min(1),
+  payload: z2.object({
+    paymentId: z2.string().min(1),
+    requestBindingHash: z2.string().min(1),
+    preparedMessageHash: z2.string().min(1),
+    serializedTransaction: z2.string().min(1).max(4096),
+    agentSignature: z2.string().min(1).max(128),
+    temporarySettlementSignature: z2.string().min(1).max(128)
+  })
+}).loose();
+function decodeX402Header(headerValue) {
+  if (headerValue.length > Math.ceil(MAX_HEADER_JSON_BYTES * 4 / 3) + 4) {
+    throw new X402HeaderError(
+      "header_too_large",
+      `x402 header exceeds ${MAX_HEADER_JSON_BYTES} encoded bytes`
+    );
+  }
+  const json = Buffer.from(headerValue, "base64").toString("utf8");
+  try {
+    return JSON.parse(json);
+  } catch {
+    throw new X402HeaderError(
+      "invalid_header_encoding",
+      "x402 header is not base64-encoded JSON"
+    );
   }
-  tryMarkUnknown(key, detail) {
-    try {
-      this.markUnknown(key, detail);
-      return null;
-    } catch (error) {
-      return error;
-    }
+}
+function requestBodyHashFor(body) {
+  if (body === null || body === void 0 || body.length === 0) {
+    return EMPTY_BODY_HASH;
   }
-  untrack(key) {
-    const previous = this.pending.get(key);
-    const existed = previous !== void 0;
-    this.pending.delete(key);
-    try {
-      this.persist();
-    } catch (error) {
-      if (existed) {
-        this.pending.set(key, previous);
-      }
-      throw error;
-    }
+  return sha256TaggedHex(
+    typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body)
+  );
+}
+
+// ../../src/client/paid-fetch.ts
+function formatRawUsdcAmount(raw) {
+  const value = BigInt(raw);
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const whole = abs / 1000000n;
+  const frac = (abs % 1000000n).toString().padStart(6, "0");
+  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 z3 } from "zod";
+var STANDARD_EXACT_SCHEME = "exact";
+var standardExactRequirementSchema = z3.object({
+  scheme: z3.literal(STANDARD_EXACT_SCHEME),
+  /** CAIP-2 chain id, e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". */
+  network: z3.string().min(1),
+  /** SPL mint (Solana) or token contract (EVM); Subly only pays USDC/Solana. */
+  asset: z3.string().min(1),
+  /** Exact price in the asset's atomic units, as a decimal string. */
+  amount: z3.string().regex(/^[1-9]\d*$/),
+  /** Recipient wallet; the transfer destination ATA is derived from it. */
+  payTo: z3.string().min(1),
+  maxTimeoutSeconds: z3.number().int().positive().optional(),
+  extra: z3.object({
+    /** Facilitator address that pays the tx fee (gas sponsorship). */
+    feePayer: z3.string().min(1).optional()
+  }).loose().optional()
+}).loose();
+var standardPaymentRequiredSchema = z3.object({
+  x402Version: z3.number().int(),
+  accepts: z3.array(z3.unknown()),
+  error: z3.string().optional(),
+  resource: z3.object({ url: z3.string().optional() }).loose().optional()
+}).loose();
+var StandardX402ChallengeError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "StandardX402ChallengeError";
+    this.reason = reason;
   }
-  clearDelivered(key) {
-    const previous = this.pending.get(key);
-    this.pending.delete(key);
-    try {
-      this.persist();
-    } catch (error) {
-      if (previous !== void 0) {
-        this.pending.set(key, previous);
-      }
-      console.error(
-        `[subly-x402] payment delivered but pending marker could not be cleared: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
+};
+function parseStandardChallenge(challenge) {
+  const parsed = standardPaymentRequiredSchema.safeParse(challenge);
+  if (!parsed.success) {
+    throw new StandardX402ChallengeError(
+      "invalid_payment_required",
+      "Response is not a valid x402 PaymentRequired object"
+    );
   }
-  persist() {
-    if (this.stateStore === null) {
-      return;
+  const solanaExactRequirements = parsed.data.accepts.flatMap((candidate) => {
+    const requirement = standardExactRequirementSchema.safeParse(candidate);
+    if (!requirement.success) {
+      return [];
     }
-    this.stateStore.save([...this.pending.values()]);
-  }
-};
-function pendingPaymentKey(input) {
-  return `${input.method}:${input.url}:${input.requestBodyHash}`;
+    return requirement.data.network.startsWith("solana:") ? [requirement.data] : [];
+  });
+  return { paymentRequired: parsed.data, solanaExactRequirements };
 }
-function extractSettledPaymentTxSignature(response) {
-  const header = response.headers.get("x-payment-response");
-  if (header === null || header.length === 0) {
-    return null;
-  }
+function decodeStandardPaymentRequiredHeader(headerValue) {
+  let decoded;
   try {
-    const decoded = JSON.parse(
-      Buffer.from(header, "base64").toString("utf8")
+    decoded = decodeX402Header(headerValue);
+  } catch (error) {
+    throw new StandardX402ChallengeError(
+      error instanceof X402HeaderError ? error.reason : "invalid_header",
+      "Cannot decode the payment-required header"
     );
-    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;
   }
+  return parseStandardChallenge(decoded);
 }
-
-// ../../src/client/lookup-tables.ts
-import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
-import { address, getCompiledTransactionMessageDecoder } from "@solana/kit";
-function lookupTableAddressesForTransaction(serializedTransaction) {
-  const wire = Buffer.from(serializedTransaction, "base64");
-  let offset = 0;
-  let signatureCount = 0;
-  let shift = 0;
-  while (offset < wire.length) {
-    const byte = wire[offset];
-    signatureCount |= (byte & 127) << shift;
-    offset += 1;
-    if ((byte & 128) === 0) {
-      break;
-    }
-    shift += 7;
+function selectPayableSolanaRequirement(requirements, options) {
+  const network = options?.network ?? SOLANA_MAINNET_NETWORK;
+  const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
+  const matchingRequirements = requirements.filter(
+    (candidate) => candidate.network === network && candidate.asset === usdcMint
+  );
+  if (matchingRequirements.length === 0) {
+    throw new StandardX402ChallengeError(
+      "no_payable_requirement",
+      `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
+    );
   }
-  const messageBytes = wire.subarray(offset + signatureCount * 64);
-  const compiled = getCompiledTransactionMessageDecoder().decode(messageBytes);
-  const lookups = compiled.addressTableLookups ?? [];
-  return lookups.map((lookup) => String(lookup.lookupTableAddress));
+  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
+  };
 }
-async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
-  const addresses = lookupTableAddressesForTransaction(serializedTransaction);
-  if (addresses.length === 0) {
-    return {};
+function standardRequirementMatchesSelected(candidate, selected2) {
+  const parsed = standardExactRequirementSchema.safeParse(candidate);
+  return parsed.success && stableJson(parsed.data) === stableJson(selected2.requirement);
+}
+function stableJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
   }
-  const tables = await fetchAllMaybeAddressLookupTable(
-    rpc2,
-    addresses.map((value) => address(value))
-  );
-  const result = {};
-  for (const table of tables) {
-    if (table.exists) {
-      result[table.address] = table.data.addresses.map(String);
-    }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, sortJson(entry)])
+    );
   }
-  return result;
+  return value;
 }
 
-// ../../src/client/vault-flows.ts
-var VaultFlowClientError = class extends Error {
-  constructor(step, message, detail = null, code = null, errorDetails = null) {
+// ../../src/client/standard-x402-payer.ts
+var StandardX402PayError = class extends Error {
+  constructor(reason, message, detail = 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;
-  signer;
-  fetchImpl;
-  lookupTablesFor;
-  pollTimeoutMs;
-  pollIntervalMs;
-  constructor(config) {
-    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). 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) {
-    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;
+    this.reason = reason;
+    this.detail = detail;
+    this.name = "StandardX402PayError";
+  }
+  reason;
+  detail;
+};
+var StandardX402Payer = class {
+  realizer;
+  x402Fetch;
+  probeFetch;
+  defaultMaxAmountRawUsdc;
+  network;
+  usdcMint;
+  stateStore;
+  pending = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  nowMs;
+  constructor(config) {
+    this.realizer = config.realizer;
+    this.x402Fetch = config.x402Fetch;
+    this.probeFetch = config.probeFetch ?? fetch;
+    this.defaultMaxAmountRawUsdc = config.defaultMaxAmountRawUsdc;
+    this.network = config.network ?? SOLANA_MAINNET_NETWORK;
+    this.usdcMint = config.usdcMint ?? SUBLY_VAULT.usdcMint;
+    this.stateStore = config.stateStore ?? null;
+    this.nowMs = config.nowMs ?? (() => Date.now());
+    if (this.stateStore !== null) {
+      for (const record of this.stateStore.load()) {
+        this.pending.set(record.key, record);
       }
-      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,
-      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
+  }
+  pay(input, realizer = this.realizer) {
+    const method = (input.method ?? "GET").toUpperCase();
+    const requestBodyHash = requestBodyHashFor(input.body ?? null);
+    const pendingKey = pendingPaymentKey({
+      url: input.url,
+      method,
+      requestBodyHash
     });
-    let outcome = await this.postJson("submit", "/v1/deposits/submit", {
-      depositId: prepared.depositId,
-      serializedTransaction: signed.serializedTransaction,
-      agentSignature: signed.agentSignature
+    const existingFlow = this.inFlight.get(pendingKey);
+    if (existingFlow !== void 0) {
+      return existingFlow;
+    }
+    const run = async () => {
+      if (this.stateStore?.withExclusiveLock) {
+        this.pending.clear();
+        for (const record of this.stateStore.load()) this.pending.set(record.key, record);
+      }
+      return this.run(input, { method, requestBodyHash, pendingKey }, realizer);
+    };
+    const flow = (this.stateStore?.withExclusiveLock ? this.stateStore.withExclusiveLock(run) : run()).finally(() => {
+      this.inFlight.delete(pendingKey);
     });
-    if (outcome.status === "submitted") {
-      outcome = await this.pollUntilTerminal(
-        `/v1/deposits/${prepared.depositId}`,
-        outcome
+    this.inFlight.set(pendingKey, flow);
+    return flow;
+  }
+  async run(input, computed, realizer) {
+    const { method, requestBodyHash, pendingKey } = computed;
+    const existingPending = this.pending.get(pendingKey);
+    if (existingPending !== void 0 && input.forceNewPayment !== true) {
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        "a previous external x402 payment for this request has an unknown outcome. Verify whether it settled before purchasing again; to pay again anyway, call with forceNewPayment=true.",
+        existingPending
       );
     }
-    return {
-      depositId: prepared.depositId,
-      status: outcome.status,
-      txSignature: outcome.txSignature ?? null,
-      actualDepositRawUsdc: outcome.actualDepositRawUsdc ?? null,
-      sharesMintedRaw: outcome.sharesMintedRaw ?? null,
-      errorCode: outcome.errorCode ?? null
+    if (existingPending !== void 0 && input.forceNewPayment === true) {
+      try {
+        this.untrack(pendingKey);
+      } catch (error) {
+        throw new StandardX402PayError(
+          "state_persist_failed",
+          "could not clear the previous pending x402 marker before forcing a new payment",
+          error
+        );
+      }
+    }
+    const init = {
+      method,
+      ...input.body === void 0 ? {} : { body: input.body },
+      ...input.headers === void 0 ? {} : { headers: input.headers }
     };
-  }
-  /**
-   * Moves USDC from the vault back to the agent wallet's USDC ATA (fee
-   * sponsored). A plain withdrawal is the exit path and MAY spend principal;
-   * with purpose "yield_realize" the relayer refuses anything beyond the
-   * spendable yield (the payment path, via RelayerYieldRealizer).
-   */
-  async withdraw(input) {
-    const prepared = await this.postJson(
-      "prepare",
-      "/v1/withdrawals/prepare",
-      {
-        wallet: this.signer.walletAddress,
-        amountRawUsdc: input.amountRawUsdc.toString(),
-        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
-        ...input.payment === void 0 ? {} : { payment: input.payment },
+    const probe = await this.probeFetch(input.url, init);
+    if (probe.status !== 402) {
+      return { paid: false, status: probe.status, body: await probe.text() };
+    }
+    const selected2 = await this.selectRequirement(probe);
+    const cap = input.maxAmountRawUsdc ?? this.defaultMaxAmountRawUsdc;
+    if (selected2.amountRawUsdc > cap) {
+      throw new StandardX402PayError(
+        "amount_exceeds_client_cap",
+        `the challenge demands ${selected2.amountRawUsdc} raw USDC, above the client cap of ${cap}; nothing was paid`,
+        { amountRawUsdc: selected2.amountRawUsdc.toString(), payTo: selected2.payTo }
+      );
+    }
+    let realized;
+    try {
+      realized = await realizer.ensureUsdcAvailable({
+        amountRawUsdc: selected2.amountRawUsdc,
+        payment: {
+          payTo: selected2.payTo,
+          amountRawUsdc: selected2.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
+        );
       }
-    );
-    const signed = await this.signer.signWithdrawal({
-      intent: prepared.signingIntent,
-      serializedTransaction: prepared.serializedTransaction,
-      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
-    });
-    let outcome = await this.postJson("submit", "/v1/withdrawals/submit", {
-      withdrawalId: prepared.withdrawalId,
-      serializedTransaction: signed.serializedTransaction,
-      agentSignature: signed.agentSignature
-    });
-    if (outcome.status === "submitted") {
-      outcome = await this.pollUntilTerminal(
-        `/v1/withdrawals/${prepared.withdrawalId}`,
-        outcome
+      throw new StandardX402PayError(
+        "realize_failed",
+        `could not realize yield to cover ${selected2.amountRawUsdc} raw USDC: ${error instanceof Error ? error.message : String(error)}`,
+        error
       );
     }
-    return {
-      withdrawalId: prepared.withdrawalId,
-      status: outcome.status,
-      txSignature: outcome.txSignature ?? null,
-      destinationUsdcAta: prepared.destinationUsdcAta,
-      actualWithdrawRawUsdc: outcome.actualWithdrawRawUsdc ?? null,
-      actualSharesBurnedRaw: outcome.actualSharesBurnedRaw ?? null,
-      errorCode: outcome.errorCode ?? null
+    const pendingRecord = {
+      key: pendingKey,
+      url: input.url,
+      method,
+      requestBodyHash,
+      amountRawUsdc: selected2.amountRawUsdc.toString(),
+      payTo: selected2.payTo,
+      feePayer: selected2.feePayer,
+      realizedRawUsdc: realized.realizedRawUsdc.toString(),
+      realizeTxSignature: realized.txSignature,
+      status: "realized",
+      createdAtMs: this.nowMs(),
+      updatedAtMs: this.nowMs()
     };
-  }
-  /**
-   * Reads the yield budget. Syncs the relayer's ledger from chain first (so
-   * yield accrued since the last sync shows up); the sync is best-effort and
-   * on failure the last-synced view is returned.
-   */
-  async getBudget(options = {}) {
-    if (options.refreshFromChain !== false) {
+    try {
+      this.track(pendingRecord);
+    } catch (error) {
+      throw new StandardX402PayError(
+        "state_persist_failed",
+        "could not persist the pending x402 marker; refusing to attempt the external payment because a restart would not be double-payment safe",
+        { error, pendingPayment: pendingRecord }
+      );
+    }
+    let response;
+    try {
+      response = await this.x402Fetch(input.url, init, selected2);
+    } catch (error) {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        `the x402 payment attempt failed after yield was realized; verify whether it settled before paying again: ${error instanceof Error ? error.message : String(error)}`,
+        { error, persistError }
+      );
+    }
+    const bodyText = await response.text();
+    if (response.status !== 200) {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        status: response.status,
+        body: bodyText
+      });
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        `the x402 payment attempt returned ${response.status} after yield was realized; verify whether it settled before paying again`,
+        { status: response.status, body: bodyText, persistError }
+      );
+    }
+    this.clearDelivered(pendingKey);
+    const paymentTxSignature = extractSettledPaymentTxSignature(response);
+    if (paymentTxSignature !== null && typeof realized.withdrawalId === "string" && realizer.reportPayment !== void 0) {
       try {
-        await this.postJson(
-          "sync",
-          `/v1/wallets/${this.signer.walletAddress}/sync`,
-          { source: "chain" }
+        await 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)}`
         );
-      } catch {
       }
     }
-    const url = `${this.baseUrl}/v1/wallets/${this.signer.walletAddress}/budget`;
-    const response = await this.fetchImpl(url, {
-      headers: await walletAuthHeaders({
-        signer: this.signer,
-        method: "GET",
-        url
-      })
-    });
-    const text = await response.text();
-    if (response.status !== 200) {
-      throw new VaultFlowClientError(
-        "budget",
-        `budget endpoint returned ${response.status}: ${text}`
+    return {
+      paid: true,
+      ...realizer.vault === void 0 ? {} : { fundingVault: realizer.vault },
+      status: response.status,
+      body: bodyText,
+      payment: {
+        amountRawUsdc: selected2.amountRawUsdc.toString(),
+        payTo: selected2.payTo,
+        feePayer: selected2.feePayer,
+        realizedRawUsdc: realized.realizedRawUsdc.toString(),
+        realizeTxSignature: realized.txSignature,
+        paymentTxSignature
+      }
+    };
+  }
+  /** Reads the challenge from the header (preferred) or the JSON body. */
+  async selectRequirement(probe) {
+    const header = probe.headers.get(PAYMENT_REQUIRED_HEADER);
+    let requirements;
+    try {
+      if (header !== null) {
+        requirements = decodeStandardPaymentRequiredHeader(header).solanaExactRequirements;
+      } else {
+        requirements = parseStandardChallenge(
+          await probe.json()
+        ).solanaExactRequirements;
+      }
+    } catch (error) {
+      throw new StandardX402PayError(
+        error instanceof StandardX402ChallengeError ? error.reason : "invalid_challenge",
+        "could not parse the x402 402 challenge",
+        error
       );
     }
-    let parsed;
     try {
-      parsed = JSON.parse(text);
-    } catch {
-      throw new VaultFlowClientError(
-        "budget",
-        "budget endpoint returned 200 with a non-JSON body",
-        text
+      return selectPayableSolanaRequirement(requirements, {
+        network: this.network,
+        usdcMint: this.usdcMint
+      });
+    } catch (error) {
+      throw new StandardX402PayError(
+        "no_payable_requirement",
+        error instanceof Error ? error.message : String(error),
+        error
       );
     }
-    const body = parsed;
-    return {
-      wallet: this.signer.walletAddress,
-      principalBasisRawUsdc: body.position?.principalBasisRawUsdc ?? "0",
-      positionValueRawUsdc: body.budget?.positionValueRawUsdc ?? "0",
-      grossYieldRawUsdc: body.budget?.grossYieldRawUsdc ?? "0",
-      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 }
+  track(record) {
+    const previous = this.pending.get(record.key);
+    this.pending.set(record.key, record);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous === void 0) {
+        this.pending.delete(record.key);
+      } else {
+        this.pending.set(record.key, previous);
       }
-    );
+      throw error;
+    }
   }
-  /** 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
-      );
+  markUnknown(key, detail) {
+    const current = this.pending.get(key);
+    if (current === void 0) {
+      return;
+    }
+    const next = {
+      ...current,
+      status: "external_outcome_unknown",
+      updatedAtMs: this.nowMs(),
+      detail
+    };
+    this.pending.set(key, next);
+    try {
+      this.persist();
+    } catch (error) {
+      this.pending.set(key, current);
+      throw error;
     }
-    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) {
+  tryMarkUnknown(key, detail) {
     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;
+      this.markUnknown(key, detail);
+      return null;
+    } catch (error) {
+      return error;
     }
   }
-  /**
-   * Polls the reconciling GET endpoint until the intent leaves "submitted"
-   * (each read looks the tx up on-chain) or the timeout elapses.
-   */
-  async pollUntilTerminal(path, last) {
-    const deadline = Date.now() + this.pollTimeoutMs;
-    let latest = last;
-    while (Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
-      const url = `${this.baseUrl}${path}`;
-      const response = await this.fetchImpl(url, {
-        headers: await walletAuthHeaders({
-          signer: this.signer,
-          method: "GET",
-          url
-        })
-      });
-      if (response.status !== 200) {
-        continue;
-      }
-      try {
-        latest = await response.json();
-      } catch {
-        continue;
-      }
-      if (latest.status !== "submitted") {
-        return latest;
+  untrack(key) {
+    const previous = this.pending.get(key);
+    const existed = previous !== void 0;
+    this.pending.delete(key);
+    try {
+      this.persist();
+    } catch (error) {
+      if (existed) {
+        this.pending.set(key, previous);
       }
+      throw error;
     }
-    return latest;
   }
-  async postJson(step, path, body) {
-    const url = `${this.baseUrl}${path}`;
-    const serialized = JSON.stringify(body);
-    const response = await this.fetchImpl(url, {
-      method: "POST",
-      headers: {
-        ...await walletAuthHeaders({
-          signer: this.signer,
-          method: "POST",
-          url,
-          body: serialized
-        }),
-        "content-type": "application/json"
-      },
-      body: serialized
-    });
-    const text = await response.text();
-    if (response.status !== 200) {
-      const parsed = parseRelayerError(text);
-      throw new VaultFlowClientError(
-        step,
-        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
-        text,
-        parsed.code,
-        parsed.details
-      );
-    }
+  clearDelivered(key) {
+    const previous = this.pending.get(key);
+    this.pending.delete(key);
     try {
-      return JSON.parse(text);
-    } catch {
-      throw new VaultFlowClientError(
-        step,
-        `${path} returned 200 with a non-JSON body`,
-        text
+      this.persist();
+    } catch (error) {
+      if (previous !== void 0) {
+        this.pending.set(key, previous);
+      }
+      console.error(
+        `[subly-x402] payment delivered but pending marker could not be cleared: ${error instanceof Error ? error.message : String(error)}`
       );
     }
   }
-  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
-      );
+  persist() {
+    if (this.stateStore === null) {
+      return;
     }
+    this.stateStore.save([...this.pending.values()]);
   }
 };
-function parseRelayerError(text) {
+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 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
-    };
+    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 { code: null, message: null, details: null };
+    return null;
   }
 }
 
@@ -1105,19 +1559,19 @@ var WITHDRAW_TOOL_NAME = "withdraw_from_subly_vault";
 var BUDGET_TOOL_NAME = "get_subly_yield_budget";
 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.
+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 relayer limits API spending to recorded yield, and the seller needs no Subly integration. With a configured vault catalog, call list_subly_vaults and select_subly_vault(vaultAddress) for the user's choice before owner setup. All subsequent tools use that vault until changed. Selection never moves existing funds; set up a separate mandate for each vault. Never select or switch vaults automatically based on APY.
 
-One-time setup: the operator needs a Solana agent wallet. Subly does NOT create wallets; either make a local keypair with \`solana-keygen new -o agent.json\` (or export one from an existing wallet) and point SUBLY_DEMO_AGENT_KEYPAIR_PATH at it, or use a custody wallet \u2014 set SUBLY_SIGNER_PROVIDER=circle (Circle developer-controlled wallet: CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET, CIRCLE_WALLET_ID) or =privy (Privy server wallet incl. agentic/owner-key wallets: PRIVY_APP_ID, PRIVY_APP_SECRET, PRIVY_WALLET_ID, plus PRIVY_AUTHORIZATION_KEY for owner-key wallets). With a local keypair the private key never leaves that file; with a custody provider it never enters this machine at all. Then fund the wallet with USDC on Solana mainnet \u2014 no SOL is ever needed, all vault transaction fees are sponsored.
+One-time setup: the operator needs a Solana agent wallet. Subly does NOT create wallets; either make a local keypair with \`solana-keygen new -o agent.json\` (or export one from an existing wallet) and point SUBLY_DEMO_AGENT_KEYPAIR_PATH at it, or use a custody wallet \u2014 set SUBLY_SIGNER_PROVIDER=circle (Circle developer-controlled wallet: CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET, CIRCLE_WALLET_ID) or =privy (Privy server wallet incl. agentic/owner-key wallets: PRIVY_APP_ID, PRIVY_APP_SECRET, PRIVY_WALLET_ID, plus PRIVY_AUTHORIZATION_KEY for owner-key wallets). With a local keypair the private key never leaves that file; with a custody provider it never enters this machine at all. Then fund the wallet with USDC on Solana mainnet \u2014 a funded relayer sponsors vault transaction fees, which do not require agent SOL.
 
 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 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.
+1. deposit_to_subly_vault(amountRawUsdc) puts wallet USDC into the vault (the minimum depends on the selected vault) 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 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, relayerBaseUrl: relayerBaseUrl2, defaultMaxAmountRawUsdc: defaultMaxAmountRawUsdc2 } = config;
+function createMcpPaymentServer(config) {
+  const { 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" },
@@ -1132,7 +1586,7 @@ async function runMcpPaymentServer(config) {
         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.`
+            description: `First deposit bundled into the owner's single Face ID (raw USDC, 6 decimals; the minimum depends on the vault, e.g. "1010000"). Strongly recommended: without it the first deposit needs a separate approval.`
           },
           approvalThresholdRawUsdc: {
             type: "string",
@@ -1250,12 +1704,26 @@ async function runMcpPaymentServer(config) {
   ];
   server.setRequestHandler(ListToolsRequestSchema, () => ({
     tools: [
+      ...config.vaultSelection === void 0 ? [] : [
+        {
+          name: "list_subly_vaults",
+          description: "List locally configured USDC Kamino vaults and the currently selected vault. Names come from on-chain metadata and may differ from Kamino's website.",
+          inputSchema: { type: "object", properties: {} },
+          annotations: { readOnlyHint: true, destructiveHint: false }
+        },
+        {
+          name: "select_subly_vault",
+          description: "Choose a vault from the local catalog for subsequent setup, deposit, budget, withdrawal, and payment tools. Checks the relayer supports the same vault. Does not move existing funds. Use the vault the user chose; never switch automatically based on APY.",
+          inputSchema: { type: "object", properties: { vaultAddress: { type: "string" } }, required: ["vaultAddress"] },
+          annotations: { readOnlyHint: false, destructiveHint: false }
+        }
+      ],
       ...vaultTools,
       {
         name: TOOL_NAME,
         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.`,
+        )} USDC) are refused without paying. Payments are refused when the spendable yield budget cannot cover them \u2014 principal is excluded by the relayer policy. Use only for URLs you intend to purchase access to.`,
         inputSchema: {
           type: "object",
           properties: {
@@ -1353,6 +1821,22 @@ async function runMcpPaymentServer(config) {
     );
   };
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (config.vaultSelection && request.params.name === "list_subly_vaults") {
+      return textResult(config.vaultSelection.list());
+    }
+    if (config.vaultSelection && request.params.name === "select_subly_vault") {
+      const address3 = request.params.arguments?.vaultAddress;
+      if (typeof address3 !== "string") return textResult({ message: "vaultAddress is required" }, true);
+      try {
+        return textResult(await config.vaultSelection.select(address3, relayerBaseUrl2));
+      } catch (error) {
+        return vaultFlowFailure(error);
+      }
+    }
+    const session = config.vaultSelection?.current();
+    const signer3 = session?.signer ?? config.signer;
+    const vaultFlows2 = session?.vaultFlows ?? config.vaultFlows ?? null;
+    const payer2 = session?.payer ?? config.payer;
     const vaultToolNames = [
       BUDGET_TOOL_NAME,
       DEPOSIT_TOOL_NAME,
@@ -1360,18 +1844,18 @@ async function runMcpPaymentServer(config) {
       SETUP_TOOL_NAME,
       SETUP_STATUS_TOOL_NAME
     ];
-    if (vaultFlows !== null && vaultToolNames.includes(request.params.name)) {
+    if (vaultFlows2 !== null && vaultToolNames.includes(request.params.name)) {
       const needsChainSync = request.params.name !== SETUP_TOOL_NAME && request.params.name !== SETUP_STATUS_TOOL_NAME;
       if (needsChainSync) {
         try {
-          await ensureWalletOnboarded({ relayerBaseUrl: relayerBaseUrl2, signer: signer2 });
+          await ensureWalletOnboarded({ relayerBaseUrl: relayerBaseUrl2, signer: signer3 });
         } catch {
         }
       }
       const args2 = request.params.arguments ?? {};
       if (request.params.name === BUDGET_TOOL_NAME) {
         try {
-          const budget = await vaultFlows.getBudget();
+          const budget = await vaultFlows2.getBudget();
           return textResult({
             ...budget,
             principalUsdc: formatRawUsdcAmount(
@@ -1402,7 +1886,7 @@ async function runMcpPaymentServer(config) {
               policy[key] = value;
             }
           }
-          const created = await vaultFlows.createSetupSession({
+          const created = await vaultFlows2.createSetupSession({
             ...Object.keys(policy).length === 0 ? {} : { policy },
             ...typeof args2.mandateTtlDays === "number" ? { mandateTtlDays: args2.mandateTtlDays } : {},
             ...typeof args2.initialDepositRawUsdc === "string" ? { initialDepositRawUsdc: args2.initialDepositRawUsdc } : {}
@@ -1424,7 +1908,7 @@ async function runMcpPaymentServer(config) {
           );
         }
         try {
-          return textResult(await vaultFlows.getSetupSession(sessionId));
+          return textResult(await vaultFlows2.getSetupSession(sessionId));
         } catch (error) {
           return vaultFlowFailure(error);
         }
@@ -1442,7 +1926,7 @@ async function runMcpPaymentServer(config) {
       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({
+          const outcome2 = await vaultFlows2.deposit({
             amountRawUsdc,
             ...flowApprovalId === void 0 ? {} : { approvalId: flowApprovalId }
           });
@@ -1452,7 +1936,7 @@ async function runMcpPaymentServer(config) {
             )
           });
         }
-        const outcome = await vaultFlows.withdraw({
+        const outcome = await vaultFlows2.withdraw({
           amountRawUsdc,
           ...flowApprovalId === void 0 ? {} : { approvalId: flowApprovalId }
         });
@@ -1585,6 +2069,11 @@ async function runMcpPaymentServer(config) {
       };
     }
   });
+  return server;
+}
+async function runMcpPaymentServer(config) {
+  const server = createMcpPaymentServer(config);
+  const { signer: signer2, relayerBaseUrl: relayerBaseUrl2, defaultMaxAmountRawUsdc: defaultMaxAmountRawUsdc2 } = config;
   try {
     await ensureWalletOnboarded({ relayerBaseUrl: relayerBaseUrl2, signer: signer2 });
     console.error("[subly-mcp] wallet registered and synced at the relayer");
@@ -1600,136 +2089,6 @@ async function runMcpPaymentServer(config) {
   );
 }
 
-// ../../src/client/relayer-yield-realizer.ts
-var REALIZE_OVERHEAD_RAW_USDC = 2500n;
-var RelayerRealizeError = class extends Error {
-  constructor(code, message, detail = null) {
-    super(message);
-    this.code = code;
-    this.detail = detail;
-    this.name = "RelayerRealizeError";
-  }
-  code;
-  detail;
-};
-var RelayerYieldRealizer = class {
-  vaultFlows;
-  constructor(config) {
-    this.vaultFlows = new VaultFlowClient({
-      relayerBaseUrl: config.relayerBaseUrl,
-      signer: config.signer,
-      rpc: config.rpc,
-      ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
-      ...config.lookupTablesFor === void 0 ? {} : { lookupTablesFor: config.lookupTablesFor }
-    });
-  }
-  async ensureUsdcAvailable(input) {
-    const shortfallRawUsdc = input.amountRawUsdc;
-    await this.assertSpendableYield(shortfallRawUsdc);
-    let outcome;
-    try {
-      outcome = await this.vaultFlows.withdraw({
-        amountRawUsdc: shortfallRawUsdc,
-        // The relayer refuses to prepare this withdrawal beyond the spendable
-        // yield — the principal-protection guard the client cannot bypass.
-        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);
-    }
-    if (outcome.status !== "confirmed" || outcome.txSignature === null) {
-      throw new RelayerRealizeError(
-        "realize_not_confirmed",
-        `yield realize withdrawal did not confirm (status=${outcome.status})`,
-        outcome
-      );
-    }
-    return {
-      realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
-      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
-   * long-running client sees yield as it accrues instead of a frozen view.
-   */
-  async assertSpendableYield(shortfallRawUsdc) {
-    let spendable;
-    try {
-      const budget = await this.vaultFlows.getBudget();
-      spendable = BigInt(budget.spendableYieldRawUsdc);
-    } catch (error) {
-      throw new RelayerRealizeError(
-        "budget_unavailable",
-        "could not read the spendable-yield budget",
-        error
-      );
-    }
-    const requiredRawUsdc = shortfallRawUsdc + REALIZE_OVERHEAD_RAW_USDC;
-    if (spendable < requiredRawUsdc) {
-      throw new RelayerRealizeError(
-        "insufficient_yield",
-        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC plus the ${REALIZE_OVERHEAD_RAW_USDC} raw fee headroom; the principal is never spent \u2014 wait for more yield`,
-        { spendableYieldRawUsdc: spendable.toString() }
-      );
-    }
-  }
-  mapWithdrawError(error) {
-    if (!(error instanceof VaultFlowClientError)) {
-      return new RelayerRealizeError(
-        "prepare_failed",
-        `yield realize failed: ${error instanceof Error ? error.message : String(error)}`,
-        error
-      );
-    }
-    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",
-        "the relayer refused to realize beyond the spendable yield; the principal is never spent \u2014 wait for more yield",
-        error.detail
-      );
-    }
-    return new RelayerRealizeError(
-      error.step === "submit" ? "submit_failed" : "prepare_failed",
-      error.message,
-      error.detail
-    );
-  }
-};
-function errorCodeFrom(detail) {
-  if (typeof detail !== "string") {
-    return null;
-  }
-  try {
-    const parsed = JSON.parse(detail);
-    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
-  } catch {
-    return null;
-  }
-}
-
 // ../../src/client/relayer-payer.ts
 function createRelayerX402Payer(config) {
   const realizer = new RelayerYieldRealizer({
@@ -1749,22 +2108,22 @@ function createRelayerX402Payer(config) {
 import { createKeyPairSignerFromBytes as createKeyPairSignerFromBytes2 } from "@solana/kit";
 
 // ../../src/solana/keys.ts
-import { readFileSync } from "node:fs";
-import bs582 from "bs58";
+import { readFileSync as readFileSync2 } from "node:fs";
+import bs583 from "bs58";
 import {
   createKeyPairSignerFromBytes
 } from "@solana/kit";
 function loadSecretKeyBytes(params) {
   const { base58Secret, jsonFilePath, label } = params;
   if (base58Secret !== void 0 && base58Secret.length > 0) {
-    const bytes = bs582.decode(base58Secret);
+    const bytes = bs583.decode(base58Secret);
     if (bytes.length !== 64) {
       throw new Error(`${label} base58 secret must decode to 64 bytes`);
     }
     return bytes;
   }
   if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
-    const raw = JSON.parse(readFileSync(jsonFilePath, "utf8"));
+    const raw = JSON.parse(readFileSync2(jsonFilePath, "utf8"));
     if (!Array.isArray(raw) || raw.length !== 64) {
       throw new Error(`${label} keypair file must be a 64-byte JSON array`);
     }
@@ -1779,7 +2138,7 @@ import bs587 from "bs58";
 import nacl3 from "tweetnacl";
 
 // ../../src/solana/tx.ts
-import bs583 from "bs58";
+import bs584 from "bs58";
 import {
   appendTransactionMessageInstructions,
   compileTransaction,
@@ -1826,11 +2185,11 @@ function signatureBase58ForSigner(transaction, signer2) {
   if (signature === null || signature === void 0) {
     return null;
   }
-  return bs583.encode(signature);
+  return bs584.encode(signature);
 }
 
 // ../../src/client/remote-signer-transport.ts
-import bs584 from "bs58";
+import bs585 from "bs58";
 import nacl2 from "tweetnacl";
 var RemoteSigningError = class extends Error {
   constructor(provider, message, detail = null) {
@@ -1845,7 +2204,7 @@ var RemoteSigningError = class extends Error {
 function ed25519PublicKeyBytes(provider, walletAddress) {
   let bytes;
   try {
-    bytes = bs584.decode(walletAddress);
+    bytes = bs585.decode(walletAddress);
   } catch {
     throw new RemoteSigningError(
       provider,
@@ -1861,10 +2220,10 @@ function ed25519PublicKeyBytes(provider, walletAddress) {
   return bytes;
 }
 function verifiedEd25519Signature(params) {
-  const publicKey = ed25519PublicKeyBytes(params.provider, params.walletAddress);
+  const publicKey2 = ed25519PublicKeyBytes(params.provider, params.walletAddress);
   const encoded = params.encodedSignature.trim();
   for (const candidate of decodeSignatureCandidates(encoded)) {
-    if (nacl2.sign.detached.verify(params.message, candidate, publicKey)) {
+    if (nacl2.sign.detached.verify(params.message, candidate, publicKey2)) {
       return candidate;
     }
   }
@@ -1880,7 +2239,7 @@ function decodeSignatureCandidates(encoded) {
     candidates.push(Uint8Array.from(Buffer.from(hex, "hex")));
   }
   try {
-    const fromBase58 = bs584.decode(encoded);
+    const fromBase58 = bs585.decode(encoded);
     if (fromBase58.length === 64) {
       candidates.push(fromBase58);
     }
@@ -1918,8 +2277,8 @@ async function requestVerifiedTransactionSignature(params) {
       `signed transaction is missing the signature for ${transport.walletAddress}`
     );
   }
-  const publicKey = params.publicKey ?? ed25519PublicKeyBytes(transport.provider, transport.walletAddress);
-  if (!nacl2.sign.detached.verify(params.messageBytes, signature, publicKey)) {
+  const publicKey2 = params.publicKey ?? ed25519PublicKeyBytes(transport.provider, transport.walletAddress);
+  if (!nacl2.sign.detached.verify(params.messageBytes, signature, publicKey2)) {
     throw new RemoteSigningError(
       transport.provider,
       "returned signature does not verify over the requested transaction"
@@ -1941,7 +2300,7 @@ async function externallySignedAgentTransaction(params) {
   });
   return {
     serializedTransaction: attached.serializedBase64,
-    agentSignature: bs584.encode(signature)
+    agentSignature: bs585.encode(signature)
   };
 }
 async function providerJsonRequest(params) {
@@ -1985,98 +2344,6 @@ function computeRequestBindingHash(fields) {
   });
 }
 
-// ../../src/lib/associated-token-account.ts
-import { createHash as createHash4 } from "node:crypto";
-import bs585 from "bs58";
-var PDA_MARKER = Buffer.from("ProgramDerivedAddress", "utf8");
-var ED25519_P = (1n << 255n) - 19n;
-var ED25519_D = mod(-121665n * modPow(121666n, ED25519_P - 2n, ED25519_P), ED25519_P);
-function deriveAssociatedTokenAddress(params) {
-  const owner = decodePublicKey(params.owner, "owner");
-  const mint = decodePublicKey(params.mint ?? SUBLY_VAULT.usdcMint, "mint");
-  const tokenProgramId = decodePublicKey(
-    params.tokenProgramId ?? SPL_TOKEN_PROGRAM_ID,
-    "tokenProgramId"
-  );
-  const associatedTokenProgramId = decodePublicKey(
-    ASSOCIATED_TOKEN_PROGRAM_ID,
-    "associatedTokenProgramId"
-  );
-  for (let bump = 255; bump >= 0; bump -= 1) {
-    const address3 = createProgramAddress(
-      [owner, tokenProgramId, mint, Uint8Array.of(bump)],
-      associatedTokenProgramId
-    );
-    if (address3 !== null) {
-      return bs585.encode(address3);
-    }
-  }
-  throw new Error("Unable to derive associated token account address");
-}
-function createProgramAddress(seeds, programId) {
-  const hash = createHash4("sha256");
-  for (const seed of seeds) {
-    hash.update(seed);
-  }
-  hash.update(programId);
-  hash.update(PDA_MARKER);
-  const digest = hash.digest();
-  return isEd25519Point(digest) ? null : new Uint8Array(digest);
-}
-function decodePublicKey(value, fieldName) {
-  const decoded = bs585.decode(value);
-  if (decoded.length !== 32) {
-    throw new Error(`${fieldName} must be a 32-byte public key`);
-  }
-  return decoded;
-}
-function isEd25519Point(bytes) {
-  if (bytes.length !== 32) {
-    return false;
-  }
-  const yBytes = Uint8Array.from(bytes);
-  yBytes[31] = yBytes[31] & 127;
-  const y = littleEndianToBigInt(yBytes);
-  if (y >= ED25519_P) {
-    return false;
-  }
-  const ySquared = mod(y * y, ED25519_P);
-  const numerator = mod(ySquared - 1n, ED25519_P);
-  const denominator = mod(ED25519_D * ySquared + 1n, ED25519_P);
-  if (denominator === 0n) {
-    return false;
-  }
-  const xSquared = mod(
-    numerator * modPow(denominator, ED25519_P - 2n, ED25519_P),
-    ED25519_P
-  );
-  return xSquared === 0n || modPow(xSquared, (ED25519_P - 1n) / 2n, ED25519_P) === 1n;
-}
-function littleEndianToBigInt(bytes) {
-  let value = 0n;
-  for (let index = bytes.length - 1; index >= 0; index -= 1) {
-    value = (value << 8n) + BigInt(bytes[index]);
-  }
-  return value;
-}
-function mod(value, modulus) {
-  const result = value % modulus;
-  return result >= 0n ? result : result + modulus;
-}
-function modPow(base, exponent, modulus) {
-  let result = 1n;
-  let nextBase = mod(base, modulus);
-  let nextExponent = exponent;
-  while (nextExponent > 0n) {
-    if ((nextExponent & 1n) === 1n) {
-      result = mod(result * nextBase, modulus);
-    }
-    nextBase = mod(nextBase * nextBase, modulus);
-    nextExponent >>= 1n;
-  }
-  return result;
-}
-
 // ../../src/client/transaction-intent-validator.ts
 var COMPUTE_BUDGET_PROGRAM_ID = "ComputeBudget111111111111111111111111111111";
 var SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
@@ -2219,16 +2486,16 @@ function validatePaymentIntentTransaction(params) {
   if (intent.network !== SOLANA_MAINNET_NETWORK) {
     reject("network_mismatch", "Unsupported network");
   }
-  if (intent.vault !== SUBLY_VAULT.address) {
+  if (intent.vault !== policy.vault.address) {
     reject("vault_mismatch", "Unsupported vault");
   }
-  if (intent.shareMint !== SUBLY_VAULT.shareMint) {
+  if (intent.shareMint !== policy.vault.shareMint) {
     reject("share_mint_mismatch", "Unsupported share mint");
   }
-  if (intent.farm !== SUBLY_VAULT.farm) {
+  if (intent.farm !== policy.vault.farm) {
     reject("farm_mismatch", "Unsupported Kamino farm");
   }
-  if (intent.asset !== SUBLY_VAULT.usdcMint) {
+  if (intent.asset !== policy.vault.usdcMint) {
     reject("asset_mismatch", "Only USDC payments are supported");
   }
   if (intent.memo !== intent.paymentId) {
@@ -2344,7 +2611,7 @@ function validateDepositIntentTransaction(params) {
   if (new Date(intent.expiresAt).getTime() <= now) {
     reject("expired", "Deposit intent has expired");
   }
-  assertVaultIntentTargets(intent);
+  assertVaultIntentTargets(intent, policy.vault);
   const decoded = decodeIntentTransaction({
     serializedTransaction: params.serializedTransaction,
     ...params.lookupTables === void 0 ? {} : { lookupTables: params.lookupTables }
@@ -2367,6 +2634,9 @@ function validateDepositIntentTransaction(params) {
       case MEMO_PROGRAM_ID:
         break;
       case KVAULT_PROGRAM_ID: {
+        if (sawDeposit) {
+          reject("duplicate_deposit", "A deposit intent authorizes exactly one KVault deposit");
+        }
         if (!bytesStartWith(ix.data, KVAULT_DEPOSIT_DISCRIMINATOR)) {
           reject("unexpected_instruction", "Unexpected KVault instruction in deposit");
         }
@@ -2417,7 +2687,7 @@ function validateWithdrawalIntentTransaction(params) {
   if (new Date(intent.expiresAt).getTime() <= now) {
     reject("expired", "Withdrawal intent has expired");
   }
-  assertVaultIntentTargets(intent);
+  assertVaultIntentTargets(intent, policy.vault);
   const expectedDestination = deriveAssociatedTokenAddress({
     owner: intent.wallet,
     mint: intent.asset
@@ -2515,22 +2785,23 @@ function validateWithdrawalIntentTransaction(params) {
     );
   }
 }
-function assertVaultIntentTargets(intent) {
-  if (intent.vault !== SUBLY_VAULT.address) {
+function assertVaultIntentTargets(intent, vault) {
+  if (intent.vault !== vault.address) {
     reject("vault_mismatch", "Unsupported vault");
   }
-  if (intent.shareMint !== SUBLY_VAULT.shareMint) {
+  if (intent.shareMint !== vault.shareMint) {
     reject("share_mint_mismatch", "Unsupported share mint");
   }
-  if (intent.farm !== SUBLY_VAULT.farm) {
+  if (intent.farm !== vault.farm) {
     reject("farm_mismatch", "Unsupported Kamino farm");
   }
-  if (intent.asset !== SUBLY_VAULT.usdcMint) {
+  if (intent.asset !== vault.usdcMint) {
     reject("asset_mismatch", "Only USDC is supported");
   }
 }
 function resolveIntentValidationPolicy(policy) {
   const resolved = {
+    vault: policy?.vault ?? SUBLY_VAULT,
     maxComputeUnitLimit: policy?.maxComputeUnitLimit ?? DEFAULT_MAX_COMPUTE_UNIT_LIMIT,
     maxComputeUnitPriceMicroLamports: policy?.maxComputeUnitPriceMicroLamports ?? DEFAULT_MAX_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS,
     maxTemporaryAccountLamports: policy?.maxTemporaryAccountLamports ?? MAX_TEMP_ACCOUNT_LAMPORTS
@@ -2882,10 +3153,12 @@ function readShortVec(bytes, startOffset) {
 
 // ../../src/client/agent-wallet-signer.ts
 var IntentValidatingAgentWalletSigner = class {
+  vault;
   validationMode = "structured_intent_transaction";
   validationPolicy;
   constructor(validationPolicy) {
-    this.validationPolicy = validationPolicy;
+    this.vault = Object.freeze({ ...validationPolicy?.vault ?? SUBLY_VAULT });
+    this.validationPolicy = { ...validationPolicy, vault: this.vault };
   }
   async signPayment(params) {
     this.assertIntentWallet(params.intent.wallet);
@@ -3043,15 +3316,15 @@ async function createCircleSignerTransport(config) {
   const entitySecretCiphertext = async () => {
     if (entityPublicKey === null) {
       const data = await request("GET", "/v1/w3s/config/entity/publicKey");
-      const publicKey = data.publicKey;
-      if (typeof publicKey !== "string") {
+      const publicKey2 = data.publicKey;
+      if (typeof publicKey2 !== "string") {
         throw new RemoteSigningError(
           PROVIDER,
           "entity public key response has no publicKey",
           data
         );
       }
-      entityPublicKey = createPublicKey(publicKey);
+      entityPublicKey = createPublicKey(publicKey2);
     }
     return publicEncrypt(
       {
@@ -3322,16 +3595,40 @@ async function agentWalletSignerFromEnv(env = process.env) {
     `unknown SUBLY_SIGNER_PROVIDER "${provider}" (expected local, circle, or privy)`
   );
 }
+async function signerBundleForVault(bundle2, vault) {
+  const signer2 = bundle2.provider === "local" ? new LocalKeypairAgentWalletSigner(await createKeyPairSignerFromBytes2(bundle2.localSecretKey), { vault }) : new RemoteAgentWalletSigner(bundle2.transport, { vault });
+  return { ...bundle2, signer: signer2 };
+}
 
 // ../../src/client/standard-x402-state-store.ts
-import { mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync as readFileSync3, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 function fileStandardX402StateStore(path) {
   return {
+    async withExclusiveLock(operation) {
+      mkdirSync(dirname(path), { recursive: true, mode: 448 });
+      const lockPath = `${path}.lock`;
+      let fd;
+      try {
+        fd = openSync(lockPath, "wx", 384);
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+          throw new Error(`Payment state is locked: ${lockPath}. Another client may be paying. After a crash, stop all clients before removing only this .lock file; preserve the payment state JSON.`);
+        }
+        throw error;
+      }
+      try {
+        writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() }));
+        return await operation();
+      } finally {
+        closeSync(fd);
+        unlinkSync(lockPath);
+      }
+    },
     load() {
       let text;
       try {
-        text = readFileSync2(path, "utf8");
+        text = readFileSync3(path, "utf8");
       } catch (error) {
         if (isMissingFileError(error)) {
           return [];
@@ -3353,12 +3650,12 @@ function fileStandardX402StateStore(path) {
     },
     save(records) {
       const directory = dirname(path);
-      mkdirSync(directory, { recursive: true });
+      mkdirSync(directory, { recursive: true, mode: 448 });
       const tempPath = join(
         directory,
         `.${basename(path)}.${process.pid}.${Date.now()}.tmp`
       );
-      writeFileSync(tempPath, JSON.stringify(records, null, 2));
+      writeFileSync(tempPath, JSON.stringify(records, null, 2), { mode: 384, flag: "wx" });
       renameSync(tempPath, path);
     }
   };
@@ -3394,7 +3691,7 @@ async function svmTransactionSignerFromBundle(bundle2) {
 }
 function remoteSvmTransactionSigner(transport) {
   const signerAddress = address2(transport.walletAddress);
-  const publicKey = ed25519PublicKeyBytes(
+  const publicKey2 = ed25519PublicKeyBytes(
     transport.provider,
     transport.walletAddress
   );
@@ -3407,7 +3704,7 @@ function remoteSvmTransactionSigner(transport) {
           transport,
           serializedTransactionBase64: getBase64EncodedWireTransaction2(transaction),
           messageBytes: transaction.messageBytes,
-          publicKey
+          publicKey: publicKey2
         });
         dictionaries.push(
           Object.freeze({ [signerAddress]: signature })
@@ -3467,14 +3764,27 @@ var payer = createRelayerX402Payer({
   defaultMaxAmountRawUsdc,
   stateStore: fileStandardX402StateStore(pendingStatePath)
 });
+var catalog = vaultCatalogFromEnv();
+var sessions = [];
+for (const vault of catalog.vaults) {
+  const selectedBundle = await signerBundleForVault(bundle, vault);
+  const vaultSigner = selectedBundle.signer;
+  const realizer = new RelayerYieldRealizer({ relayerBaseUrl, signer: vaultSigner, rpc });
+  sessions.push({
+    vault,
+    signer: vaultSigner,
+    // One payer owns deduplication and pending state across ALL vault selections.
+    payer: { pay: (input) => payer.pay(input, realizer) },
+    vaultFlows: new VaultFlowClient({ relayerBaseUrl, signer: vaultSigner, rpc })
+  });
+}
+var vaultSelection = new McpVaultSelection(sessions, catalog.defaultVault);
+var selected = vaultSelection.current();
 await runMcpPaymentServer({
-  payer,
-  signer,
+  payer: selected.payer,
+  signer: selected.signer,
   relayerBaseUrl,
   defaultMaxAmountRawUsdc,
-  vaultFlows: new VaultFlowClient({
-    relayerBaseUrl,
-    signer,
-    rpc
-  })
+  vaultFlows: selected.vaultFlows,
+  vaultSelection
 });