@agentwonderland/mcp 0.1.45 → 0.1.47

package/src/core/link-cli.ts

@@ -0,0 +1,300 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const LINK_CLI_PACKAGE = "@stripe/link-cli";
+const LINK_CLI_TIMEOUT_MS = 10 * 60 * 1000;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface LinkCliAuthStatus {
+  authenticated: boolean;
+  credentialsPath?: string;
+  pending?: boolean;
+}
+
+export interface LinkCliPaymentMethod {
+  id: string;
+  label?: string;
+  searchText?: string;
+}
+
+export interface LinkCliLogin {
+  verificationUrl: string;
+  phrase: string;
+  instruction?: string;
+}
+
+async function runLinkCli(args: string[], timeout = LINK_CLI_TIMEOUT_MS): Promise<unknown> {
+  try {
+    const { stdout } = await execFileAsync(
+      "npx",
+      ["--yes", LINK_CLI_PACKAGE, ...args, "--format", "json"],
+      {
+        maxBuffer: 1024 * 1024,
+        timeout,
+      },
+    );
+    const trimmed = stdout.trim();
+    return trimmed ? JSON.parse(trimmed) : null;
+  } catch (err) {
+    const error = err as Error & { stdout?: string; stderr?: string };
+    const output = error.stdout?.trim() || error.stderr?.trim();
+    if (output) {
+      try {
+        const parsed = JSON.parse(output) as { message?: string; code?: string };
+        const message = parsed.message ?? output;
+        throw new Error(parsed.code ? `${parsed.code}: ${message}` : message);
+      } catch (parseErr) {
+        if (parseErr instanceof SyntaxError) {
+          throw new Error(output);
+        }
+        throw parseErr;
+      }
+    }
+    throw error;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function walk(value: unknown, visit: (value: unknown, key?: string) => string | null, key?: string): string | null {
+  const direct = visit(value, key);
+  if (direct) return direct;
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = walk(item, visit);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  const record = asRecord(value);
+  if (record) {
+    for (const [childKey, childValue] of Object.entries(record)) {
+      const found = walk(childValue, visit, childKey);
+      if (found) return found;
+    }
+  }
+
+  return null;
+}
+
+function extractSharedPaymentToken(output: unknown): string | null {
+  return walk(output, (value, key) => {
+    if (typeof value !== "string") return null;
+    if (value.startsWith("spt_")) return value;
+    if (key && /shared.*payment.*token|spt/i.test(key) && value.includes("spt_")) {
+      return value.match(/spt_[A-Za-z0-9_]+/)?.[0] ?? null;
+    }
+    return null;
+  });
+}
+
+function extractSpendRequestApproval(output: unknown): { id: string; approvalUrl?: string; status?: string } | null {
+  const values = Array.isArray(output) ? output : [output];
+  for (const value of values) {
+    const record = asRecord(value);
+    if (!record) continue;
+    const id = typeof record.id === "string" && record.id.startsWith("lsrq_")
+      ? record.id
+      : null;
+    if (!id) continue;
+    return {
+      id,
+      approvalUrl: typeof record.approval_url === "string" ? record.approval_url : undefined,
+      status: typeof record.status === "string" ? record.status : undefined,
+    };
+  }
+  return null;
+}
+
+function normalizePaymentMethods(output: unknown): LinkCliPaymentMethod[] {
+  const values = Array.isArray(output)
+    ? output
+    : Array.isArray(asRecord(output)?.data)
+      ? asRecord(output)?.data as unknown[]
+      : Array.isArray(asRecord(output)?.payment_methods)
+        ? asRecord(output)?.payment_methods as unknown[]
+        : [];
+
+  return values
+    .map<LinkCliPaymentMethod | null>((value) => {
+      const record = asRecord(value);
+      if (!record) return null;
+      const id = typeof record.id === "string"
+        ? record.id
+        : typeof record.payment_method_id === "string"
+          ? record.payment_method_id
+          : null;
+      if (!id) return null;
+      const name = typeof record.name === "string" ? record.name : undefined;
+      const type = typeof record.type === "string" ? record.type : undefined;
+      const cardDetails = asRecord(record.card_details);
+      const bankDetails = asRecord(record.bank_account_details);
+      const brand = typeof cardDetails?.brand === "string"
+        ? cardDetails.brand
+        : typeof record.brand === "string"
+          ? record.brand
+          : undefined;
+      const last4 = typeof cardDetails?.last4 === "string"
+        ? cardDetails.last4
+        : typeof bankDetails?.last4 === "string"
+          ? bankDetails.last4
+          : typeof record.last4 === "string"
+            ? record.last4
+            : undefined;
+      const bankName = typeof bankDetails?.bank_name === "string" ? bankDetails.bank_name : undefined;
+      const typeLabel = type === "BANK_ACCOUNT" ? "bank" : type === "CARD" ? "card" : type?.toLowerCase();
+      const labelParts = [
+        name ?? bankName ?? brand ?? typeLabel,
+        brand && name?.toLowerCase().includes(brand.toLowerCase()) !== true ? brand : undefined,
+        last4 ? `****${last4}` : undefined,
+      ];
+      const label = labelParts.filter(Boolean).join(" ");
+      const searchText = [id, label, name, type, brand, bankName, last4].filter(Boolean).join(" ").toLowerCase();
+      return { id, ...(label ? { label } : {}), searchText };
+    })
+    .filter((value): value is LinkCliPaymentMethod => Boolean(value));
+}
+
+export async function getLinkCliAuthStatus(): Promise<LinkCliAuthStatus> {
+  try {
+    const output = await runLinkCli(["auth", "status"], 30_000);
+    const status = Array.isArray(output) ? asRecord(output[0]) : asRecord(output);
+    return {
+      authenticated: status?.authenticated === true,
+      credentialsPath: typeof status?.credentials_path === "string" ? status.credentials_path : undefined,
+      pending: status?.pending === true,
+    };
+  } catch {
+    return { authenticated: false };
+  }
+}
+
+export async function startLinkCliLogin(): Promise<LinkCliLogin> {
+  const output = await runLinkCli(["auth", "login", "--client-name", "Agent Wonderland MCP"]);
+  const login = Array.isArray(output) ? asRecord(output[0]) : asRecord(output);
+  const verificationUrl = typeof login?.verification_url === "string"
+    ? login.verification_url
+    : typeof login?.verificationUrl === "string"
+      ? login.verificationUrl
+      : null;
+  const phrase = typeof login?.phrase === "string" ? login.phrase : null;
+  if (!verificationUrl || !phrase) {
+    throw new Error("Link CLI did not return a verification URL.");
+  }
+  return {
+    verificationUrl,
+    phrase,
+    instruction: typeof login?.instruction === "string" ? login.instruction : undefined,
+  };
+}
+
+export async function openLinkPaymentMethodAdd(): Promise<void> {
+  await runLinkCli(["payment-methods", "add"]);
+}
+
+export async function listLinkPaymentMethods(): Promise<LinkCliPaymentMethod[]> {
+  const output = await runLinkCli(["payment-methods", "list"], 60_000);
+  return normalizePaymentMethods(output);
+}
+
+export async function createLinkSharedPaymentToken(params: {
+  amount: string;
+  currency: string;
+  context: string;
+  expiresAt: number;
+  networkId: string;
+  paymentMethodId: string;
+}): Promise<string> {
+  const args = [
+    "spend-request",
+    "create",
+    "--credential-type",
+    "shared_payment_token",
+    "--network-id",
+    params.networkId,
+    "--amount",
+    params.amount,
+    "--currency",
+    params.currency,
+    "--payment-method-id",
+    params.paymentMethodId,
+    "--context",
+    params.context,
+    "--request-approval",
+  ];
+
+  if (process.env.AGENTWONDERLAND_LINK_TEST_MODE === "1") {
+    args.push("--test");
+  }
+
+  let output: unknown;
+  try {
+    output = await runLinkCli(args);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/invalid network_id|could not retrieve merchant information/i.test(message)) {
+      throw new Error(
+        [
+          message,
+          "",
+          `Link CLI rejected the merchant network_id "${params.networkId}".`,
+          "For local Agent Wonderland testing, restart the gateway with a Stripe key whose live/test mode matches STRIPE_PROFILE_ID. If the modes already match, the Stripe profile likely is not provisioned for Link Agentic Commerce/SPT yet or Stripe needs to provide a different network id.",
+        ].join("\n"),
+      );
+    }
+    throw err;
+  }
+  const spt = extractSharedPaymentToken(output);
+  if (spt) {
+    return spt;
+  }
+
+  const approval = extractSpendRequestApproval(output);
+  if (approval?.id && approval.status === "pending_approval") {
+    if (approval.approvalUrl) {
+      console.error(`Link approval required: ${approval.approvalUrl}`);
+    }
+    let retrieved = await runLinkCli([
+      "spend-request",
+      "retrieve",
+      approval.id,
+      "--interval",
+      "2",
+      "--max-attempts",
+      "150",
+    ]);
+    let retrievedSpt = extractSharedPaymentToken(retrieved);
+    for (let attempt = 0; !retrievedSpt && attempt < 30; attempt += 1) {
+      await sleep(2_000);
+      retrieved = await runLinkCli([
+        "spend-request",
+        "retrieve",
+        approval.id,
+      ]);
+      retrievedSpt = extractSharedPaymentToken(retrieved);
+    }
+    if (retrievedSpt) {
+      return retrievedSpt;
+    }
+    throw new Error(
+      [
+        "Link spend request finished without a shared payment token.",
+        approval.approvalUrl ? `Approval URL: ${approval.approvalUrl}` : undefined,
+      ].filter(Boolean).join("\n"),
+    );
+  }
+
+  {
+    throw new Error("Link spend request completed without a shared payment token in the CLI response.");
+  }
+}

package/src/core/mpp-client.ts

@@ -93,8 +93,75 @@ export const Mppx = {
   },
 };
 
-export function stripe(_parameters?: unknown): ClientMethod {
-  throw new Error("Stripe card payments are temporarily unavailable.");
+export function stripe(parameters: {
+  createToken: (parameters: {
+    amount: string;
+    challenge: Challenge;
+    currency: string;
+    expiresAt: number;
+    metadata?: Record<string, string>;
+    networkId: string;
+    paymentMethod?: string;
+  }) => Promise<string>;
+  externalId?: string;
+  paymentMethod?: string;
+}): ClientMethod[] {
+  const { createToken, externalId, paymentMethod: defaultPaymentMethod } = parameters;
+
+  return [
+    Method.toClient(
+      {
+        name: "stripe",
+        intent: "charge",
+      },
+      {
+        async createCredential({ challenge }) {
+          const paymentMethod = defaultPaymentMethod;
+          if (!paymentMethod) {
+            throw new Error("paymentMethod is required");
+          }
+
+          const amount = String(challenge.request.amount ?? "");
+          const currency = String(challenge.request.currency ?? "");
+          const methodDetails = challenge.request.methodDetails as {
+            networkId?: string;
+            metadata?: Record<string, string>;
+          } | undefined;
+          const networkId = methodDetails?.networkId;
+          if (!networkId) {
+            throw new Error("networkId is required in stripe payment challenge");
+          }
+
+          const metadata = methodDetails?.metadata;
+          if (metadata?.externalId) {
+            throw new Error("methodDetails.metadata.externalId is reserved");
+          }
+
+          const expiresAt = challenge.expires
+            ? Math.floor(new Date(challenge.expires).getTime() / 1000)
+            : Math.floor(Date.now() / 1000) + 3600;
+
+          const spt = await createToken({
+            amount,
+            challenge,
+            currency,
+            expiresAt,
+            metadata,
+            networkId,
+            paymentMethod,
+          });
+
+          return Credential.serialize({
+            challenge,
+            payload: {
+              spt,
+              ...(externalId ? { externalId } : {}),
+            },
+          });
+        },
+      },
+    ),
+  ];
 }
 
 function createPaymentFetch(baseFetch: typeof fetch, methods: ClientMethod[]): typeof fetch {

package/src/core/payments.ts

@@ -15,6 +15,7 @@ import {
   getWallets,
   getDefaultWallet,
   getCardConfig,
+  getLinkConfig,
   resolveWalletAndChain,
   getApiUrl,
   type WalletEntry,
@@ -37,6 +38,25 @@ const REGISTRY_METHOD_MAP: Record<string, string> = {
   base: "base_usdc",
   solana: "solana_usdc",
   card: "stripe_card",
+  link: "stripe_card",
+};
+
+const DEFAULT_LINK_APPROVAL_LIMIT_CENTS = 10_000;
+
+const ACCEPTED_PAYMENT_ALIASES: Record<string, string[]> = {
+  tempo: ["tempo_usdc", "tempo"],
+  base: ["base_usdc", "base"],
+  solana: ["solana_usdc", "solana"],
+  card: ["stripe_card", "card"],
+  link: ["stripe_card", "card", "link"],
+};
+
+const DISCOVERY_PAYMENT_ALIASES: Record<string, string[]> = {
+  tempo: ["tempo_usdc"],
+  base: ["base_usdc"],
+  solana: ["solana_usdc"],
+  card: ["stripe_card", "card"],
+  link: ["stripe_card", "card"],
 };
 
 const METHOD_REGISTRY_MAP: Record<string, string> = {
@@ -44,6 +64,8 @@ const METHOD_REGISTRY_MAP: Record<string, string> = {
   base_usdc: "base",
   solana_usdc: "solana",
   stripe_card: "card",
+  card: "card",
+  link: "link",
 };
 
 // ── Helpers ─────────────────────────────────────────────────────
@@ -62,6 +84,12 @@ function cardCacheKey(): string | null {
   return `card:${getApiUrl()}:${card.consumerToken}:${card.paymentMethodId ?? ""}`;
 }
 
+function linkCacheKey(): string | null {
+  const link = getLinkConfig();
+  if (!link) return null;
+  return `link:${getApiUrl()}:${link.paymentMethodId}`;
+}
+
 function clearStaleCardCache(activeKey?: string): void {
   for (const key of fetchCache.keys()) {
     if (key.startsWith("card:") && key !== activeKey) {
@@ -70,6 +98,14 @@ function clearStaleCardCache(activeKey?: string): void {
   }
 }
 
+function clearStaleLinkCache(activeKey?: string): void {
+  for (const key of fetchCache.keys()) {
+    if (key.startsWith("link:") && key !== activeKey) {
+      fetchCache.delete(key);
+    }
+  }
+}
+
 // ── Per-protocol initializers ───────────────────────────────────
 
 async function initEvmMppForChain(
@@ -157,6 +193,76 @@ async function initCard(): Promise<typeof fetch | null> {
   }
 }
 
+function formatMinorCurrencyAmount(currency: string, amount: string): string {
+  return `${currency.toUpperCase()} ${(Number(amount) / 100).toFixed(2)}`;
+}
+
+function getLinkApprovalLimitAmount(actualAmount: string): string {
+  const actualAmountCents = Number(actualAmount);
+  const configuredLimit = Number(process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS);
+  const defaultLimit = Number.isFinite(configuredLimit) && configuredLimit > 0
+    ? Math.floor(configuredLimit)
+    : DEFAULT_LINK_APPROVAL_LIMIT_CENTS;
+  return String(Math.max(actualAmountCents, defaultLimit));
+}
+
+function buildLinkApprovalContext(params: {
+  amount: string;
+  approvalAmount: string;
+  currency: string;
+  metadata?: Record<string, string>;
+}): string {
+  const amountText = formatMinorCurrencyAmount(params.currency, params.amount);
+  const approvalAmountText = formatMinorCurrencyAmount(params.currency, params.approvalAmount);
+  const agent = params.metadata?.agent_id ? ` Agent ID: ${params.metadata.agent_id}.` : "";
+  const job = params.metadata?.job_id ? ` Job ID: ${params.metadata.job_id}.` : "";
+  return (
+    `Approve up to ${approvalAmountText} for Agent Wonderland machine payments. ` +
+    `This specific user-confirmed agent run is quoted at ${amountText}; the Agent Wonderland gateway will charge the exact quote for this request, not the full approval limit unless the quote itself is that amount.${agent}${job}`
+  );
+}
+
+async function initLink(): Promise<typeof fetch | null> {
+  const linkConfig = getLinkConfig();
+  if (!linkConfig) return null;
+
+  try {
+    const { Mppx, stripe } = await import("./mpp-client.js");
+    const { createLinkSharedPaymentToken } = await import("./link-cli.js");
+    const mppx = Mppx.create({
+      methods: [stripe({
+        paymentMethod: linkConfig.paymentMethodId,
+        createToken: async (params: {
+          amount: string;
+          currency: string;
+          networkId: string;
+          expiresAt: number;
+          metadata?: Record<string, string>;
+        }) => {
+          const approvalAmount = getLinkApprovalLimitAmount(params.amount);
+          return createLinkSharedPaymentToken({
+            amount: approvalAmount,
+            currency: params.currency,
+            context: buildLinkApprovalContext({
+              amount: params.amount,
+              approvalAmount,
+              currency: params.currency,
+              metadata: params.metadata,
+            }),
+            expiresAt: params.expiresAt,
+            networkId: params.networkId,
+            paymentMethodId: linkConfig.paymentMethodId,
+          });
+        },
+      })] as any,
+      polyfill: false,
+    });
+    return mppx.fetch.bind(mppx) as typeof fetch;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Initialize a payment-aware fetch for a given wallet + chain.
  */
@@ -184,6 +290,21 @@ function initFailureMessage(method: string, wallet: WalletEntry, chain: string,
  * @param method - wallet ID, chain name, or "card". Omit for auto-detection.
  */
 export async function getPaymentFetch(method?: string): Promise<typeof fetch> {
+  if (method === "link") {
+    const ck = linkCacheKey();
+    clearStaleLinkCache(ck ?? undefined);
+    if (!ck) {
+      throw new Error('Payment method "link" is not configured. Run wallet_setup({ action: "add-link" }) after logging into Link.');
+    }
+    if (fetchCache.has(ck)) return fetchCache.get(ck)!;
+    const pf = await initLink();
+    if (pf) {
+      fetchCache.set(ck, pf);
+      return pf;
+    }
+    throw new Error('Payment method "link" failed to initialize. Check Link CLI auth with: npx @stripe/link-cli auth status');
+  }
+
   // Card payment
   if (method === "card") {
     if (!ENABLE_CARD_PAYMENT) {
@@ -229,6 +350,24 @@ export async function getPaymentFetch(method?: string): Promise<typeof fetch> {
   const defaultMethod = getConfig().defaultPaymentMethod;
 
   for (const m of configured) {
+    if (m === "link") {
+      const ck = linkCacheKey();
+      clearStaleLinkCache(ck ?? undefined);
+      if (!ck) continue;
+      if (fetchCache.has(ck)) return fetchCache.get(ck)!;
+      const pf = await initLink();
+      if (pf) {
+        fetchCache.set(ck, pf);
+        return pf;
+      }
+      if (m === defaultMethod) {
+        const others = configured.filter((x) => x !== m);
+        const altText = others.length > 0 ? ` Available alternatives: ${others.join(", ")}` : "";
+        throw new Error(`Link payment failed to initialize. Check Link CLI auth with wallet_status.${altText}`);
+      }
+      continue;
+    }
+
     if (m === "card") {
       const ck = cardCacheKey();
       clearStaleCardCache(ck ?? undefined);
@@ -317,6 +456,9 @@ export function getConfiguredMethods(): string[] {
   if (ENABLE_CARD_PAYMENT && getCardConfig()) {
     methods.push("card");
   }
+  if (getLinkConfig()) {
+    methods.push("link");
+  }
 
   // Respect defaultPaymentMethod — move it to front of list (ignore card when disabled)
   const defaultMethod = getConfig().defaultPaymentMethod;
@@ -337,6 +479,7 @@ export function getConfiguredMethods(): string[] {
  */
 export function normalizePaymentMethod(method: string): string | null {
   if (method === "card") return "card";
+  if (method === "link") return "link";
   const resolved = resolveWalletAndChain(method);
   return resolved?.chain ?? null;
 }
@@ -350,6 +493,7 @@ export function paymentMethodDisplayName(method: string): string {
     case "base": return "Base USDC";
     case "solana": return "Solana USDC";
     case "card": return "Card";
+    case "link": return "Link";
     default: return method;
   }
 }
@@ -361,9 +505,8 @@ export function paymentMethodDisplayName(method: string): string {
  */
 export function getAcceptedPaymentMethods(): string[] {
   const methods = getConfiguredMethods();
-  return methods
-    .map((m) => REGISTRY_METHOD_MAP[m])
-    .filter(Boolean);
+  return [...new Set(methods
+    .flatMap((m) => DISCOVERY_PAYMENT_ALIASES[m] ?? [REGISTRY_METHOD_MAP[m]].filter(Boolean)))];
 }
 
 export function toRegistryPaymentMethod(method: string): string | null {
@@ -381,20 +524,19 @@ export function getCompatiblePaymentMethods(
     return [...configuredMethods];
   }
 
-  const acceptedMethods = new Set(
-    acceptedPayments
-      .map((payment) => METHOD_REGISTRY_MAP[payment])
-      .filter(Boolean),
-  );
+  const acceptedRegistryMethods = new Set(acceptedPayments);
 
-  return configuredMethods.filter((method) => acceptedMethods.has(method));
+  return configuredMethods.filter((method) => {
+    const aliases = ACCEPTED_PAYMENT_ALIASES[method] ?? [REGISTRY_METHOD_MAP[method]].filter(Boolean);
+    return aliases.some((alias) => acceptedRegistryMethods.has(alias));
+  });
 }
 
 /**
  * Check whether any payment method is configured.
  */
 export function hasWalletConfigured(): boolean {
-  return getWallets().length > 0 || getCardConfig() !== null;
+  return getWallets().length > 0 || getCardConfig() !== null || getLinkConfig() !== null;
 }
 
 /**
@@ -404,7 +546,7 @@ export async function getWalletAddress(method?: string): Promise<string | null>
   let chain: string | undefined;
   let wallet: WalletEntry | undefined;
 
-  if (method && method !== "card") {
+  if (method && method !== "card" && method !== "link") {
     const resolved = resolveWalletAndChain(method);
     wallet = resolved?.wallet;
     chain = resolved?.chain;

package/src/core/principal.ts

@@ -132,7 +132,7 @@ export async function getBaseRebatePrincipal(): Promise<string | null> {
 }
 
 export async function getConsumerPrincipalForMethod(method?: string): Promise<string | null> {
-  if (!method || method === "card") {
+  if (!method || method === "card" || method === "link") {
     return getConsumerPrincipal();
   }
 
@@ -158,7 +158,7 @@ export async function ensureConsumerPrincipalForMethod(method?: string): Promise
   const existing = await getConsumerPrincipalForMethod(method);
   if (existing) return existing;
 
-  if (method && method !== "card") {
+  if (method && method !== "card" && method !== "link") {
     throw new Error(
       `Could not derive a consumer principal for payment method "${method}". ` +
       "Check wallet_status and confirm that chain is configured for the active wallet.",

package/src/core/version.ts

@@ -1 +1 @@
-export const MCP_PACKAGE_VERSION = "0.1.44";
+export const MCP_PACKAGE_VERSION = "0.1.47";

package/src/index.ts

@@ -51,11 +51,12 @@ export async function startMcpServer(): Promise<void> {
         "3. After a successful run, rate_agent() and optionally tip_agent() if the result was useful.",
         "4. Use list_jobs() to recover state across sessions (it checks every configured wallet).",
         "",
-        "PAYMENT (crypto-only right now):",
-        "- Supported rails: Tempo USDC, Base USDC, Solana USDC. Card is temporarily disabled pending Stripe SPT approval.",
+        "PAYMENT:",
+        "- Supported rails: Tempo USDC, Base USDC, Solana USDC, and local Link SPT via @stripe/link-cli.",
+        "- Card is temporarily disabled pending Stripe SPT approval.",
         "- Tempo and Base share one EVM wallet key. Solana uses a separate ed25519 key. One OWS wallet can manage both.",
         "- If pay_with is omitted, the MCP auto-selects a compatible configured rail. Pass pay_with explicitly",
-        "  (tempo | base | solana | wallet-id) for deterministic behavior.",
+        "  (tempo | base | solana | link | wallet-id) for deterministic behavior.",
         "- Payment is automatic: on a 402 challenge the MCP signs on-chain, submits, then retries. Failed runs are refunded.",
         "- If a specific rail fails, surface the real reason — do NOT silently retry with a different method.",
         "- Headless/automation: set wallet_set_policy() to cap max_per_tx and max_per_day so a runaway loop can't drain funds.",
@@ -70,7 +71,8 @@ export async function startMcpServer(): Promise<void> {
         "",
         "WALLET HYGIENE:",
         "- wallet_status shows per-chain USDC balance and the active network (mainnet vs testnet).",
-        "- To create or import a crypto wallet: wallet_setup({ action: \"create\" }) or { action: \"import\", key }.",
+        "- To set up payments: wallet_setup({ action: \"start\" }). Link card/bank is recommended for most users.",
+        "- To create or import a crypto wallet directly: wallet_setup({ action: \"create\" }) or { action: \"import\", key }.",
         "- NEVER delete or rotate keys programmatically. Direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.",
       ].join("\n"),
     },