warpmetal 0.5.0 → 0.7.0

package/README.md

@@ -2,14 +2,13 @@
 
 The official command-line client and portable Agent Skill for WarpMetal.
 
-The CLI uses the public API at `https://api.warpmetal.com`, stores generated
-WarpMetal credentials in a user-private state file, and never reads or stores
-wallet private keys or SSH private-key contents. Version 0.5 adds dedicated
-hostname-based VPS identities, bounded autonomous renewal, verified lifecycle
-email, and signed refill requests through the x402api Agent Wallet. WarpMetal
-writes the exact credential-free payment request, explains the next commands to
-an agent, validates the returned payment artifact, and submits it without
-absorbing wallet custody.
+The CLI uses `https://api.warpmetal.com` as the API root; endpoints begin at
+`/health`, `/catalog`, `/orders`, and so on, without a second `/api` prefix. It
+stores generated WarpMetal credentials in a user-private state file and never
+reads or stores wallet private keys or SSH private-key contents. Version 0.6
+adopts this canonical root-path API. WarpMetal writes the exact credential-free
+payment request, explains the next commands to an agent, validates the returned
+payment artifact, and submits it without absorbing wallet custody.
 
 ## Distribution
 
@@ -33,7 +32,7 @@ published wallet CLI with the exact version WarpMetal reports:
 npm install --global warpmetal
 warpmetal --help
 
-npm install --global @x402api/agent-wallet-cli@0.2.1
+npm install --global @x402api/agent-wallet-cli@0.2.2
 x402api help --json
 ```
 
@@ -86,10 +85,13 @@ After preparing an order, request its live payment challenge:
 warpmetal checkout challenge --task <taskId> --json
 ```
 
-On HTTP 402 the CLI returns exact `paymentTerms`, the pinned
+On HTTP 402 the CLI returns exact `paymentTerms`, the opaque `challengeHandle`
+that WarpMetal uses for merchant-side reconciliation, the pinned
 `@x402api/agent-wallet-cli` package contract, and argv arrays under
 `paymentWorkflow`. It also writes an owner-only request envelope that contains
-the exact checkout URL and body but no WarpMetal credential. The published
+the exact checkout URL and body but no WarpMetal credential or challenge
+handle. The handle is not a buyer payment identifier and is never a wallet
+signing input. The published
 launch wallet accepts sponsored Base USDC and sponsored Solana USDC/USDT only;
 the returned terms identify compatible alternatives and confirm that the buyer
 does not need ETH or SOL. Payment authority depends on execution context:
@@ -142,11 +144,13 @@ after authorization.
 
 If funding is short in an interactive conversation, tell the human the exact
 top-up in normal and atomic units, the network, stablecoin and contract/mint,
-and the payer wallet's public receiving address. The human sends the token to
-that wallet address, never to the token contract/mint or WarpMetal's payment
-recipient, and never sends ETH or SOL for a sponsored payment. In an unattended
-run, use a preconfigured refill or escalation mechanism or stop with
-`funding_required`.
+and the payer wallet's public receiving address. The returned
+`paymentWorkflow.fundingWorkflow` provides safe address and balance argv plus a
+presentation contract: render that public address as both a QR code and
+copyable text. The human sends the token to that wallet address, never to the
+token contract/mint or WarpMetal's payment recipient, and never sends ETH or
+SOL for a sponsored payment. In an unattended run, use a preconfigured refill
+or escalation mechanism or stop with `funding_required`.
 
 ## Autonomous renewal and refill
 
@@ -169,7 +173,11 @@ warpmetal renewal configure \
 ```
 
 The recipient must follow the one-time verification link before lifecycle or
-refill mail is sent. A recurring unattended agent can then run:
+refill mail is sent. If no verified notification email exists, `renewal
+configure` returns `email_required` before changing policy. Supply `--email`,
+or deliberately continue with `--without-email-notifications`; the latter does
+not enable signed refill-email workflows. A recurring unattended agent can then
+run:
 
 ```sh
 warpmetal renewal due --all --json
@@ -177,14 +185,16 @@ warpmetal renewal run --all-due --json
 ```
 
 Inside policy, the CLI returns the exact Agent Wallet authorization and submit
-argv. If balance is insufficient, run the returned `refillWorkflow.argv` with
-its `X402API_NOTIFICATION_URL` environment value. `x402api wallet
+argv. If balance is insufficient, `refillWorkflow` is returned only when the
+server has an active verified notification subscription. Run its argv with the
+returned `X402API_NOTIFICATION_URL` environment value. `x402api wallet
 notify-refill` signs an opaque subscription reference and wallet-produced
 balance fields; it cannot choose an email address. WarpMetal verifies the
 wallet signature and current on-chain balance before emailing the verified
-human the network, stablecoin, public wallet address, and required minimum
-top-up. The human may transfer more than that minimum; the renewal policy—not
-the refill target—remains the spending authority.
+human the network, stablecoin, public wallet address, required minimum top-up,
+and a locally generated QR encoding only that wallet address. The address is
+also repeated as copyable text. The human may transfer more than that minimum;
+the renewal policy—not the refill target—remains the spending authority.
 
 The agent never sends a partial x402 payment. If no verified refill path
 exists, it reports `funding_required`. If a previous payment is pending or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {

package/skills/warpmetal/SKILL.md

@@ -111,7 +111,9 @@ task or operator limit.
 After interactive confirmation or autonomous policy validation, invoke the
 returned authorize argv once. The separate
 `x402api` executable owns the wallet, validates the envelope, and writes the
-payment artifact. Then invoke the returned submit argv, equivalent to:
+payment artifact. The returned `challengeHandle` is opaque merchant
+reconciliation metadata; never copy it into the request envelope or treat it as
+the buyer payment identifier. Then invoke the returned submit argv, equivalent to:
 
 ```sh
 warpmetal checkout submit \
@@ -152,9 +154,12 @@ price, asset, network, count, horizon, or total-budget mismatch.
 Run `warpmetal renewal prepare --server <serverId> --json`, then invoke only
 the returned `paymentWorkflow.authorize.argv` and
 `paymentWorkflow.submit.argv`. If authorization reports insufficient balance,
-set the returned `refillWorkflow.environment`, invoke its exact argv once, and
-stop until funding arrives. The signed refill intent resolves to a verified
-human contact; never add an email address to it. Never make a partial payment.
+use `paymentWorkflow.fundingWorkflow` to obtain the public address and balance,
+then show the address as both a QR code and copyable text. Only when
+`refillNotification.available` is true, set the returned
+`refillWorkflow.environment`, invoke its exact argv once, and stop until
+funding arrives. The signed refill intent resolves to a verified human contact;
+never add an email address to it. Never make a partial payment.
 
 After funding, prepare again, authorize exactly once, submit with WarpMetal,
 and confirm the returned `termEndsAt`. On `reconcile_pending` or

package/skills/warpmetal/references/cli-reference.md

@@ -53,14 +53,16 @@ warpmetal order status \
 ```
 
 On HTTP 402, `checkout challenge` validates and displays exact payment terms,
-writes a credential-free x402api V1 request envelope with owner-only
+writes the opaque x402api `challengeHandle` to private WarpMetal state for
+merchant reconciliation, and writes a credential-free x402api V1 request envelope with owner-only
 permissions, and returns the exact pinned wallet package, V1 contract probe,
 matching wallet-skill install, authorization, and WarpMetal submission argv
 arrays. The default envelope and suggested artifact paths live under the
 private WarpMetal state directory. An explicit output path must not already
-contain different content.
+contain different content. `challengeHandle` is intentionally absent from the
+wallet envelope: it is neither a buyer payment identifier nor signing input.
 
-The current integration targets `@x402api/agent-wallet-cli@0.2.1`. A compatible
+The current integration targets `@x402api/agent-wallet-cli@0.2.2`. A compatible
 live term is marked `agentWalletSupported: true` and must use the sponsored
 Base USDC or Solana USDC/USDT launch profile with buyer native fees disabled.
 WarpMetal rejects a challenge with no compatible sponsored term. Because the
@@ -101,7 +103,8 @@ warpmetal renewal configure \
   (--maximum-renewals <n> | --renew-through <UTC>) \
   [--maximum-total-spend-atomic <amount>] \
   --allowed-network <network> --allowed-asset <asset> \
-  --wallet <name> [--refill-target-atomic <amount>] [--email <address>] --json
+  --wallet <name> [--refill-target-atomic <amount>] \
+  [--email <address> | --without-email-notifications] --json
 warpmetal renewal status --server <serverId> --json
 warpmetal renewal due (--server <serverId> | --all) --json
 warpmetal renewal prepare --server <serverId> --json
@@ -113,9 +116,12 @@ warpmetal notifications configure --server <serverId> --email <address> \
 warpmetal notifications status --server <serverId> --json
 ```
 
-`renewal prepare` returns exact payment and refill argv arrays. `renewal run`
-is an agent-facing state machine, not a wallet-signing daemon. See
-[renewals.md](renewals.md).
+Without a verified notification email, renewal configuration asks for an email
+before mutating policy unless `--without-email-notifications` explicitly opts
+out. `renewal prepare` always returns safe funding address/balance argv and
+returns signed refill-email argv only for a verified active subscription.
+`renewal run` is an agent-facing state machine, not a wallet-signing daemon.
+See [renewals.md](renewals.md).
 
 ## Server management
 

package/skills/warpmetal/references/payments.md

@@ -19,7 +19,7 @@ files or pass a WarpMetal credential to `x402api`.
 WarpMetal runs on Node.js 20 or 22. The x402api Agent Wallet currently requires
 Node.js 22. Use the exact published package reported by
 `paymentWorkflow.signerPackage.spec`; the current contract is
-`@x402api/agent-wallet-cli@0.2.1`. Do not add it as a WarpMetal dependency,
+`@x402api/agent-wallet-cli@0.2.2`. Do not add it as a WarpMetal dependency,
 install executable wallet code from an unpinned repository URL, or substitute
 a similarly named package.
 
@@ -66,10 +66,12 @@ skill automatically.
 
 6. If funding is short in an interactive conversation, show the exact deficit
    in normal token units and atomic units, the exact network, token symbol and
-   contract/mint, and the payer wallet's public receiving address. Tell the
-   human to transfer the token to the payer wallet address, never to the token
-   contract/mint or `paymentTerms.recipient`. Sponsored launch payments never
-   ask the buyer to fund ETH or SOL. Recheck the balance after the transfer.
+   contract/mint, and the payer wallet's public receiving address. Render only
+   that public address as a QR code and repeat the full address as copyable
+   text. Tell the human to transfer the token to the payer wallet address,
+   never to the token contract/mint or `paymentTerms.recipient`. Sponsored
+   launch payments never ask the buyer to fund ETH or SOL. Recheck the balance
+   after the transfer.
 7. If funding is short in an unattended run, use only a preconfigured refill
    mechanism returned by WarpMetal. For a configured renewal, set the returned
    `refillWorkflow.environment`, invoke `refillWorkflow.argv` once, and stop
@@ -114,7 +116,11 @@ paymentWorkflow.submit.argv
 Replace only `<wallet-name>` after selecting the wallet for the advertised
 network. Do not parse, rewrite, copy, or display the request envelope or payment
 artifact. The envelope excludes the WarpMetal owner token; the artifact holds
-the complete payment signature and remains owner-only.
+the complete payment signature and remains owner-only. The safe challenge JSON
+also contains `challengeHandle`, an opaque value retained by WarpMetal for
+merchant reconciliation. It is deliberately excluded from the x402api V1
+request envelope and must not be confused with the wallet-created buyer payment
+identifier.
 
 Choose only a term marked `agentWalletSupported: true`,
 `sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false`. The supported

package/skills/warpmetal/references/renewals.md

@@ -23,15 +23,18 @@ warpmetal renewal configure \
   --allowed-asset <exact-contract-or-mint> \
   --wallet <agent-wallet-name> \
   [--refill-target-atomic <target>] \
-  [--email <human-address>] \
+  [--email <human-address> | --without-email-notifications] \
   --json
 ```
 
-`--email` queues verification; refill and expanded lifecycle notices remain
-disabled until the human opens the verification link. A refill target is a
-funding target, not spend permission, and cannot exceed the per-renewal cap.
-The human may transfer more than the displayed deficit. The agent may spend
-only the exact renewal amount allowed by policy.
+Without an active verified notification email, configuration asks for one
+before changing policy. `--email` queues verification; refill and expanded
+lifecycle notices remain disabled until the human opens the verification link.
+Use `--without-email-notifications` only as an explicit opt-out; no signed
+refill-email workflow is returned in that state. A refill target is a funding
+target, not spend permission, and cannot exceed the per-renewal cap. The human
+may transfer more than the displayed deficit. The agent may spend only the
+exact renewal amount allowed by policy.
 
 The WarpMetal CLI stores only the local wallet name. The backend stores
 non-secret limits, counters, payment rail, time horizon, and an opaque
@@ -70,8 +73,10 @@ one policy-compatible rail, and returns:
 ```text
 paymentWorkflow.authorize.argv
 paymentWorkflow.submit.argv
-refillWorkflow.environment
-refillWorkflow.argv
+paymentWorkflow.fundingWorkflow
+refillNotification
+refillWorkflow.environment (verified email only)
+refillWorkflow.argv (verified email only)
 ```
 
 Invoke the authorize argv once. It writes an owner-only artifact. Then invoke
@@ -112,10 +117,12 @@ authoritative balance before queuing email. The intent cannot name a recipient
 email, tenant, or product.
 
 In a human conversation, also display the exact deficit, network, token symbol,
-contract or mint, and payer wallet address. Tell the human to fund the payer
+contract or mint, and payer wallet address. Render only that public address as
+a QR code and repeat it as copyable text. Tell the human to fund the payer
 wallet address—not the token contract/mint and not WarpMetal's merchant
 recipient. Do not ask for ETH or SOL because supported network fees are
-sponsored.
+sponsored. A refill email repeats the address as text and includes a locally
+generated QR encoding only that address.
 
 ## Stop and recovery states
 

package/src/api.js

@@ -128,19 +128,19 @@ export class WarpMetalClient {
   }
 
   health() {
-    return this.request("GET", "/api/health");
+    return this.request("GET", "/health");
   }
 
   catalog() {
-    return this.request("GET", "/api/catalog");
+    return this.request("GET", "/catalog");
   }
 
   prepareOrder(body, idempotencyKey) {
-    return this.request("POST", "/api/orders", { body, idempotencyKey });
+    return this.request("POST", "/orders", { body, idempotencyKey });
   }
 
   getTask(taskId, token) {
-    return this.request("GET", `/api/tasks/${encodeURIComponent(taskId)}`, {
+    return this.request("GET", `/tasks/${encodeURIComponent(taskId)}`, {
       token,
     });
   }
@@ -157,7 +157,7 @@ export class WarpMetalClient {
   issueSshChallenge(serverId) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/auth/challenges`,
+      `/servers/${encodeURIComponent(serverId)}/auth/challenges`,
       { body: {} },
     );
   }
@@ -165,13 +165,13 @@ export class WarpMetalClient {
   exchangeSshChallenge(serverId, challengeId, signature) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/auth/tokens`,
+      `/servers/${encodeURIComponent(serverId)}/auth/tokens`,
       { body: { challengeId, signature } },
     );
   }
 
   getServer(serverId, token) {
-    return this.request("GET", `/api/servers/${encodeURIComponent(serverId)}`, {
+    return this.request("GET", `/servers/${encodeURIComponent(serverId)}`, {
       token,
     });
   }
@@ -179,7 +179,7 @@ export class WarpMetalClient {
   getRenewalPolicy(serverId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/renewal-policy`,
+      `/servers/${encodeURIComponent(serverId)}/renewal-policy`,
       { token },
     );
   }
@@ -187,7 +187,7 @@ export class WarpMetalClient {
   putRenewalPolicy(serverId, body, token) {
     return this.request(
       "PUT",
-      `/api/servers/${encodeURIComponent(serverId)}/renewal-policy`,
+      `/servers/${encodeURIComponent(serverId)}/renewal-policy`,
       { body, token },
     );
   }
@@ -195,7 +195,7 @@ export class WarpMetalClient {
   deleteRenewalPolicy(serverId, token) {
     return this.request(
       "DELETE",
-      `/api/servers/${encodeURIComponent(serverId)}/renewal-policy`,
+      `/servers/${encodeURIComponent(serverId)}/renewal-policy`,
       { token },
     );
   }
@@ -203,7 +203,7 @@ export class WarpMetalClient {
   getNotifications(serverId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/notifications`,
+      `/servers/${encodeURIComponent(serverId)}/notifications`,
       { token },
     );
   }
@@ -211,13 +211,21 @@ export class WarpMetalClient {
   putNotifications(serverId, body, token) {
     return this.request(
       "PUT",
-      `/api/servers/${encodeURIComponent(serverId)}/notifications`,
+      `/servers/${encodeURIComponent(serverId)}/notifications`,
       { body, token },
     );
   }
 
+  deleteNotifications(serverId, token) {
+    return this.request(
+      "DELETE",
+      `/servers/${encodeURIComponent(serverId)}/notifications`,
+      { token },
+    );
+  }
+
   renewalCheckout(planId, { bodyText, token, paymentSignature }) {
-    return this.checkout(`/api/checkout/${encodeURIComponent(planId)}/renew`, {
+    return this.checkout(`/checkout/${encodeURIComponent(planId)}/renew`, {
       bodyText,
       token,
       paymentSignature,
@@ -227,7 +235,7 @@ export class WarpMetalClient {
   powerServer(serverId, action, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/power`,
+      `/servers/${encodeURIComponent(serverId)}/power`,
       {
         body: { action },
         token,
@@ -239,7 +247,7 @@ export class WarpMetalClient {
   reloadServer(serverId, body, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/reload`,
+      `/servers/${encodeURIComponent(serverId)}/reload`,
       {
         body,
         token,
@@ -251,7 +259,7 @@ export class WarpMetalClient {
   getOperation(operationId, token) {
     return this.request(
       "GET",
-      `/api/operations/${encodeURIComponent(operationId)}`,
+      `/operations/${encodeURIComponent(operationId)}`,
       {
         token,
       },
@@ -261,7 +269,7 @@ export class WarpMetalClient {
   enableRuntime(serverId, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/runtime/enable`,
+      `/servers/${encodeURIComponent(serverId)}/runtime/enable`,
       {
         body: {},
         token,
@@ -273,7 +281,7 @@ export class WarpMetalClient {
   getRuntime(serverId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/runtime`,
+      `/servers/${encodeURIComponent(serverId)}/runtime`,
       { token },
     );
   }
@@ -281,7 +289,7 @@ export class WarpMetalClient {
   bootstrapRuntime(serverId, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/runtime/bootstrap`,
+      `/servers/${encodeURIComponent(serverId)}/runtime/bootstrap`,
       { body: {}, token, idempotencyKey },
     );
   }
@@ -289,7 +297,7 @@ export class WarpMetalClient {
   listSandboxes(serverId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes`,
       { token },
     );
   }
@@ -297,7 +305,7 @@ export class WarpMetalClient {
   createSandboxes(serverId, sandboxes, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes`,
       {
         body: { sandboxes },
         token,
@@ -309,7 +317,7 @@ export class WarpMetalClient {
   getSandbox(serverId, sandboxId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}`,
       { token },
     );
   }
@@ -317,7 +325,7 @@ export class WarpMetalClient {
   sandboxAction(serverId, sandboxId, action, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/actions`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/actions`,
       { body: { action }, token, idempotencyKey },
     );
   }
@@ -325,7 +333,7 @@ export class WarpMetalClient {
   deleteSandbox(serverId, sandboxId, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/delete`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/delete`,
       { body: { confirm: "DELETE" }, token, idempotencyKey },
     );
   }
@@ -333,7 +341,7 @@ export class WarpMetalClient {
   listAccessGrants(serverId, sandboxId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants`,
       { token },
     );
   }
@@ -341,7 +349,7 @@ export class WarpMetalClient {
   createAccessGrant(serverId, sandboxId, body, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants`,
       { body, token, idempotencyKey },
     );
   }
@@ -349,7 +357,7 @@ export class WarpMetalClient {
   getAccessGrant(serverId, sandboxId, grantId, token) {
     return this.request(
       "GET",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants/${encodeURIComponent(grantId)}`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants/${encodeURIComponent(grantId)}`,
       { token },
     );
   }
@@ -357,7 +365,7 @@ export class WarpMetalClient {
   revokeAccessGrant(serverId, sandboxId, grantId, token, idempotencyKey) {
     return this.request(
       "POST",
-      `/api/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants/${encodeURIComponent(grantId)}/revoke`,
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/access-grants/${encodeURIComponent(grantId)}/revoke`,
       { body: { confirm: "REVOKE" }, token, idempotencyKey },
     );
   }

package/src/cli.js

@@ -84,6 +84,7 @@ Usage:
   warpmetal renewal configure --server <serverId> --renew-before-days <n>
     --maximum-payment-atomic <amount> (--maximum-renewals <n> | --renew-through <UTC>)
     --allowed-network <CAIP-2> --allowed-asset <asset> --wallet <name>
+    [--email <address> | --without-email-notifications]
   warpmetal renewal status|prepare|submit|run ...
   warpmetal renewal due (--server <serverId> | --all)
   warpmetal notifications configure --server <serverId> --email <address>
@@ -364,9 +365,15 @@ async function pollGrant(
 
 function challengeResult(taskId, checkoutBody, response) {
   const paymentRequired = response.headers["payment-required"];
+  const challengeHandle = response.headers["x-x402api-challenge-handle"];
   if (response.status === 402 && !paymentRequired) {
     throw new CliError("WarpMetal returned HTTP 402 without PAYMENT-REQUIRED.");
   }
+  if (response.status === 402 && !challengeHandle) {
+    throw new CliError(
+      "WarpMetal returned HTTP 402 without X-X402API-Challenge-Handle.",
+    );
+  }
   return {
     status: response.data?.status,
     taskId,
@@ -374,6 +381,7 @@ function challengeResult(taskId, checkoutBody, response) {
       response.data?.paymentAttemptId ||
       response.headers["x-warpmetal-payment-attempt"],
     paymentRequired,
+    challengeHandle,
     checkoutBodySha256: createHash("sha256").update(checkoutBody).digest("hex"),
   };
 }
@@ -645,7 +653,7 @@ async function handleCheckoutChallenge(client, store, options, context) {
     stringOption(options, "request-envelope-out"),
   );
   const paymentInstructions = safe.paymentWorkflow
-    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
+    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nIf funding is short, run ${shellCommand(safe.paymentWorkflow.fundingWorkflow.address.argv)} and ${shellCommand(safe.paymentWorkflow.fundingWorkflow.balance.argv)}, then show the payer address as both a QR code and copyable text.\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
     : "";
   emit(
     context.stdout,
@@ -775,6 +783,44 @@ export function refillRenewBy(termEndsAt, currentTime = Date.now()) {
   return new Date(Number.isFinite(parsed) && parsed > minimum ? parsed : minimum).toISOString();
 }
 
+function activeNotificationSubscription(notifications) {
+  const subscription = notifications?.subscription;
+  return Boolean(
+    notifications?.configured &&
+      subscription?.verified &&
+      !subscription?.disabled,
+  );
+}
+
+function refillNotificationState(notifications, policy) {
+  const subscription = notifications?.subscription;
+  if (!notifications?.configured || !subscription || subscription.disabled) {
+    return {
+      available: false,
+      reason: "verified_email_required",
+      subscription: subscription || null,
+    };
+  }
+  if (!subscription.verified) {
+    return {
+      available: false,
+      reason: "email_verification_required",
+      subscription,
+    };
+  }
+  if (
+    policy?.notificationReference &&
+    subscription.reference !== policy.notificationReference
+  ) {
+    return {
+      available: false,
+      reason: "notification_reference_mismatch",
+      subscription,
+    };
+  }
+  return { available: true, reason: null, subscription };
+}
+
 async function handleRenewalConfigure(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const wallet = stringOption(options, "wallet", { required: true });
@@ -818,7 +864,72 @@ async function handleRenewalConfigure(client, store, options, context) {
   for (const [key, value] of Object.entries(body)) {
     if (value === undefined) delete body[key];
   }
+  const email = stringOption(options, "email");
+  const withoutEmailNotifications = booleanOption(
+    options,
+    "without-email-notifications",
+  );
+  if (email && withoutEmailNotifications) {
+    throw new CliError(
+      "Use either --email or --without-email-notifications, not both.",
+      { exitCode: 2 },
+    );
+  }
   const token = await requireServerToken(store, serverId, options, context.env);
+  let notifications = (await client.getNotifications(serverId, token)).data;
+  if (
+    body.enabled &&
+    !email &&
+    !withoutEmailNotifications &&
+    !activeNotificationSubscription(notifications)
+  ) {
+    const verificationPending = Boolean(
+      notifications.configured &&
+        notifications.subscription &&
+        !notifications.subscription.disabled,
+    );
+    const action = verificationPending
+      ? "email_verification_required"
+      : "email_required";
+    const output = {
+      action,
+      serverId,
+      reason: verificationPending
+        ? "Verify the existing notification email or resend verification with --email."
+        : "A verified email enables renewal and wallet-refill notifications.",
+      notifications,
+      next: {
+        configureEmail: `warpmetal renewal configure ... --email <address>`,
+        continueWithoutEmail:
+          "warpmetal renewal configure ... --without-email-notifications",
+      },
+    };
+    emit(
+      context.stdout,
+      output,
+      context.json,
+      verificationPending
+        ? `Verify the notification email for ${serverId}, or rerun with --email to resend verification. To opt out explicitly, rerun with --without-email-notifications.`
+        : `An email is needed for renewal and wallet-refill notifications. Rerun with --email <address>, or opt out explicitly with --without-email-notifications.`,
+    );
+    return 6;
+  }
+  if (email) {
+    notifications = (
+      await client.putNotifications(serverId, { email }, token)
+    ).data;
+  } else if (
+    withoutEmailNotifications &&
+    notifications.configured &&
+    notifications.subscription &&
+    !notifications.subscription.disabled
+  ) {
+    await client.deleteNotifications(serverId, token);
+    notifications = {
+      ...notifications,
+      subscription: { ...notifications.subscription, disabled: true },
+    };
+  }
   const result = await client.putRenewalPolicy(serverId, body, token);
   await store.saveRenewalPolicy(
     serverId,
@@ -826,19 +937,27 @@ async function handleRenewalConfigure(client, store, options, context) {
     wallet,
     refillTargetAtomic,
   );
-  const email = stringOption(options, "email");
-  let notifications;
-  if (email) {
-    notifications = (
-      await client.putNotifications(serverId, { email }, token)
-    ).data;
-  }
-  const output = { ...result.data, wallet, refillTargetAtomic, notifications };
+  const notificationState = {
+    optedOut: withoutEmailNotifications,
+    refillAvailable: activeNotificationSubscription(notifications),
+    status: withoutEmailNotifications
+      ? "opted_out"
+      : activeNotificationSubscription(notifications)
+        ? "verified"
+        : "verification_required",
+  };
+  const output = {
+    ...result.data,
+    wallet,
+    refillTargetAtomic,
+    notifications,
+    notificationState,
+  };
   emit(
     context.stdout,
     output,
     context.json,
-    `Configured bounded renewal for ${serverId} with wallet ${wallet}.${email ? " Check the email verification link." : ""}`,
+    `Configured bounded renewal for ${serverId} with wallet ${wallet}.${email && !notificationState.refillAvailable ? " Check the email verification link." : withoutEmailNotifications ? " Email and wallet-refill notifications were explicitly skipped." : ""}`,
   );
   return 0;
 }
@@ -866,11 +985,12 @@ async function attachRenewalPaymentWorkflow(
   serverId,
   server,
   renewal,
+  notifications,
   response,
   requestedEnvelopePath,
 ) {
   const bodyText = JSON.stringify({ serverId });
-  const checkoutPath = `/api/checkout/${server.planId}/renew`;
+  const checkoutPath = `/checkout/${server.planId}/renew`;
   const safe = challengeResult(serverId, bodyText, response);
   if (!safe.paymentRequired) return safe;
   const request = createPaymentRequestEnvelope({
@@ -924,6 +1044,7 @@ async function attachRenewalPaymentWorkflow(
     taskId: server.id,
     serverId,
     kind: "renewal",
+    wallet: renewal.wallet,
     requestEnvelopePath,
     paymentArtifactPath: defaults.paymentArtifactPath,
   });
@@ -932,27 +1053,39 @@ async function attachRenewalPaymentWorkflow(
     BigInt(renewal.refillTargetAtomic) >= BigInt(term.amountAtomic)
       ? renewal.refillTargetAtomic
       : term.amountAtomic;
-  const refillWorkflow = {
-    environment: {
-      X402API_NOTIFICATION_URL: `${client.baseUrl}/api/notifications/x402api/refill`,
-    },
-    argv: [
-      "x402api",
-      "wallet",
-      "notify-refill",
-      "--wallet",
-      renewal.wallet,
-      "--subscription-reference",
-      renewal.policy.notificationReference,
-      "--renew-by",
-      refillRenewBy(server.termEndsAt),
-      "--target-balance-atomic",
-      refillTarget,
-      "--reason",
-      "renewal",
-      "--json",
-    ],
-  };
+  Object.assign(workflow.fundingWorkflow, {
+    network: term.network,
+    asset: term.asset,
+    requiredPaymentAtomic: term.amountAtomic,
+    targetBalanceAtomic: refillTarget,
+  });
+  const refillNotification = refillNotificationState(
+    notifications,
+    renewal.policy,
+  );
+  const refillWorkflow = refillNotification.available
+    ? {
+        environment: {
+          X402API_NOTIFICATION_URL: `${client.baseUrl}/notifications/x402api/refill`,
+        },
+        argv: [
+          "x402api",
+          "wallet",
+          "notify-refill",
+          "--wallet",
+          renewal.wallet,
+          "--subscription-reference",
+          refillNotification.subscription.reference,
+          "--renew-by",
+          refillRenewBy(server.termEndsAt),
+          "--target-balance-atomic",
+          refillTarget,
+          "--reason",
+          "renewal",
+          "--json",
+        ],
+      }
+    : undefined;
   Object.assign(safe, {
     serverId,
     paymentTerms: request.terms,
@@ -960,6 +1093,7 @@ async function attachRenewalPaymentWorkflow(
     paymentRequestDigest: request.requestDigest,
     paymentChallengeDigest: request.challengeDigest,
     paymentWorkflow: workflow,
+    refillNotification,
     refillWorkflow,
   });
   await store.saveRenewalChallenge(serverId, {
@@ -968,6 +1102,7 @@ async function attachRenewalPaymentWorkflow(
     termEndsAt: server.termEndsAt,
     paymentRequired: safe.paymentRequired,
     paymentAttemptId: safe.paymentAttemptId,
+    challengeHandle: safe.challengeHandle,
     paymentRequestDigest: safe.paymentRequestDigest,
     paymentChallengeDigest: safe.paymentChallengeDigest,
     paymentRequestEnvelopePath: requestEnvelopePath,
@@ -988,9 +1123,10 @@ function renewalActionExitCode(action) {
 
 async function prepareRenewal(client, store, serverId, options, context) {
   const token = await requireServerToken(store, serverId, options, context.env);
-  const [serverResult, policyResult] = await Promise.all([
+  const [serverResult, policyResult, notificationsResult] = await Promise.all([
     client.getServer(serverId, token),
     client.getRenewalPolicy(serverId, token),
+    client.getNotifications(serverId, token),
   ]);
   if (!policyResult.data.configured) {
     return {
@@ -1032,6 +1168,7 @@ async function prepareRenewal(client, store, serverId, options, context) {
     serverId,
     serverResult.data.task,
     local,
+    notificationsResult.data,
     response,
     stringOption(options, "request-envelope-out"),
   );
@@ -1053,8 +1190,16 @@ async function prepareRenewal(client, store, serverId, options, context) {
 async function handleRenewalPrepare(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const safe = await prepareRenewal(client, store, serverId, options, context);
+  const fundingInstructions = safe.paymentWorkflow
+    ? `\nIf funding is short, run ${shellCommand(safe.paymentWorkflow.fundingWorkflow.address.argv)} and ${shellCommand(safe.paymentWorkflow.fundingWorkflow.balance.argv)}. Show the returned payer address as both a QR code and copyable text, with the exact network, asset, and deficit.`
+    : "";
+  const refillInstructions = safe.refillWorkflow
+    ? `\nFor verified email refill, set ${Object.entries(safe.refillWorkflow.environment).map(([key, value]) => `${key}=${value}`).join(" ")} and run: ${shellCommand(safe.refillWorkflow.argv)}`
+    : safe.paymentWorkflow
+      ? `\nVerified email refill is unavailable (${safe.refillNotification.reason}). Configure and verify notifications, or fund the displayed payer address directly.`
+      : "";
   const instructions = safe.paymentWorkflow
-    ? `\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nIf the wallet is short of funds, set ${Object.entries(safe.refillWorkflow.environment).map(([key, value]) => `${key}=${value}`).join(" ")} and run: ${shellCommand(safe.refillWorkflow.argv)}\nSubmit: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
+    ? `\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}${fundingInstructions}${refillInstructions}\nSubmit: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
     : "";
   emit(
     context.stdout,
@@ -2325,6 +2470,7 @@ async function dispatch(positionals, options, passthrough, context) {
         "allowed-asset",
         "refill-target-atomic",
         "email",
+        "without-email-notifications",
         "disabled",
       ]);
       return handleRenewalConfigure(client, store, options, context);

package/src/payment.js

@@ -15,7 +15,7 @@ const MAX_ARTIFACT_BYTES = 1024 * 1024;
 const MAX_SIGNATURE_BYTES = 512 * 1024;
 
 export const AGENT_WALLET_PACKAGE = "@x402api/agent-wallet-cli";
-export const AGENT_WALLET_VERSION = "0.2.1";
+export const AGENT_WALLET_VERSION = "0.2.2";
 const AGENT_WALLET_SPEC = `${AGENT_WALLET_PACKAGE}@${AGENT_WALLET_VERSION}`;
 const GAS_SPONSORSHIP_EXTENSION = "com.x402api.gas-sponsorship";
 const BASE_NETWORK = "eip155:8453";
@@ -696,6 +696,7 @@ export function paymentWorkflow({
   taskId,
   serverId,
   kind = "checkout",
+  wallet = "<wallet-name>",
   requestEnvelopePath,
   paymentArtifactPath,
 }) {
@@ -739,7 +740,7 @@ export function paymentWorkflow({
         "payment",
         "authorize",
         "--wallet",
-        "<wallet-name>",
+        wallet,
         "--request-envelope",
         requestEnvelopePath,
         "--artifact-out",
@@ -747,6 +748,27 @@ export function paymentWorkflow({
         "--json",
       ],
     },
+    fundingWorkflow: {
+      action: "fund_wallet",
+      trigger: "insufficient_asset_balance",
+      wallet,
+      address: {
+        argv: ["x402api", "wallet", "address", "--wallet", wallet, "--json"],
+      },
+      balance: {
+        argv: ["x402api", "wallet", "balance", "--wallet", wallet, "--json"],
+      },
+      presentation: {
+        qrPayloadField: "address",
+        textPayloadField: "address",
+        showQr: true,
+        showAddressString: true,
+        showExactDeficit: true,
+        showNetworkAndAsset: true,
+      },
+      safety:
+        "Encode and fund only the payer wallet public address. Never fund the token contract, mint, or WarpMetal merchant recipient; sponsored payments do not require ETH or SOL.",
+    },
     submit: {
       argv:
         kind === "renewal"

package/src/state.js

@@ -280,6 +280,7 @@ export class StateStore {
     {
       paymentRequired,
       paymentAttemptId,
+      challengeHandle,
       paymentRequestDigest,
       paymentChallengeDigest,
       paymentWorkflow,
@@ -293,6 +294,7 @@ export class StateStore {
         });
       order.paymentRequired = paymentRequired;
       order.paymentAttemptId = paymentAttemptId;
+      order.challengeHandle = challengeHandle;
       order.paymentRequestDigest = paymentRequestDigest;
       order.paymentChallengeDigest = paymentChallengeDigest;
       order.paymentRequestEnvelopePath = paymentWorkflow?.requestEnvelopePath;
@@ -465,6 +467,7 @@ export class StateStore {
         serverId: order.serverId,
         planId: order.planId,
         paymentAttemptId: order.paymentAttemptId,
+        challengeHandle: order.challengeHandle,
         walletPaymentAttemptId: order.walletPaymentAttemptId,
         walletName: order.walletName,
         payerAddress: order.walletPayerAddress,
@@ -499,6 +502,7 @@ export class StateStore {
         refillTargetAtomic: renewal.refillTargetAtomic,
         policy: renewal.policy,
         paymentAttemptId: renewal.paymentAttemptId,
+        challengeHandle: renewal.challengeHandle,
         paymentArtifactExpiresAt: renewal.paymentArtifactExpiresAt,
       })),
     };