@zeroxyz/sdk 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@zeroxyz/sdk` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — with the pre-1.0 caveat that minor versions may include breaking changes.
 
+## 0.14.0
+
+### Added
+
+- **Explicit payment-protocol selection** — `client.fetch(url, { paymentProtocol: "x402" | "mpp" })` forces one advertised rail instead of using the default x402-first negotiation order. Selection is strict: when the requested protocol is absent, the fetch fails without silently falling back. The CLI exposes the same control as `zero fetch --protocol x402|mpp`. (#785)
+
+### Fixed
+
+- **ZeroClick-style x402 identity-then-charge flows** — `client.fetch()` now handles one zero-value identity challenge before exactly one positive-value payment attempt, reparsing the fresh post-identity 402 instead of signing the stale `$0` challenge. `maxPay` still gates the real charge before signing, and any second positive-value challenge is refused before another payment authorization is created. (#785)
+
+## 0.13.0
+
+### Added
+
+- **Pay and sign from a non-primary wallet** — `client.fetch()`, `payments.pay()` / `payMpp()`, and `client.auth.signMessage/signTransaction/signTypedData` accept an optional `walletAddress` (session mode). The SDK resolves the named profile wallet for the payment intent's `from`, the managed signature, and the recorded run's attribution (`runs.create` gained the same optional `walletAddress`), so per-wallet run filters reflect which wallet acted. The wallet must be on the caller's profile. Default behavior (primary wallet) is unchanged. (ZERO-488)
+- **`client.runs.list({ walletAddress })`** — narrow session run reads to specific profile wallets (string or string[]). Default remains all profile wallets; an address not on the profile is a server-side 400, never a silent intersection. (ZERO-488)
+- **Wallet nicknames** — `client.wallet.setNickname({ walletAddress, nickname })` (null clears), optional `nickname` on `client.wallet.import()`, and `UserWalletDto.nickname`. Nicknames are private to the authenticated user. New export `SetNicknameOptions`. (ZERO-488)
+- **`client.wallet.revokeDelegation()` / `client.wallet.reauthorizeDelegation()`** — per-wallet delegation lifecycle (default: the primary wallet). New export `DelegationOptions`. (ZERO-488)
+
 ## 0.12.0
 
 ### Added

package/README.md

@@ -95,7 +95,7 @@ The SDK refreshes the access token automatically after a `401`, and every refres
 `client.fetch()` is the call you'll reach for most. Given a URL, it:
 
 1. Sends the request.
-2. If the server answers `402 Payment Required` (x402 or MPP), reads the payment challenge and pays it.
+2. If the server answers `402 Payment Required` (x402 or MPP), reads the payment challenge and pays it. For x402 endpoints that use a zero-dollar identity challenge before the real charge, it handles one free identity stage followed by exactly one positive-value payment attempt.
 3. Replays the request with proof of payment.
 4. Returns the body, status, and payment metadata together.
 5. Records a run on Zero when you pass a `capabilityId`, so the capability's reliability signal stays current and the call stays reviewable.
@@ -131,8 +131,10 @@ const result = await client.fetch(url, {
   method: "POST",
   headers: { "content-type": "application/json" },
   body: JSON.stringify({ city: "tokyo" }),
-  maxPay: "0.01",          // USDC ceiling; an over-cap challenge aborts before signing
+	maxPay: "0.01",          // USDC ceiling; an over-cap challenge aborts before signing
+	paymentProtocol: "mpp",  // optional: force "x402" or "mpp" when both are offered
   capabilityId: "cap_abc", // attribute the run to a known capability
+  walletAddress: "0x…",    // session mode: pay from this profile wallet (default: primary)
   signal: controller.signal,
 });
 
@@ -194,7 +196,7 @@ for (const warning of result.warnings ?? []) {
 
 ### `maxPay`
 
-`maxPay` is your hard per-call ceiling, in USDC. The challenge amount is checked against it **before** anything is signed; an over-cap challenge aborts with `outcome: "payment_failed"` and no on-chain spend. Set it on every paid call — it's the guardrail that keeps a mispriced or hostile endpoint from draining the wallet.
+`maxPay` is your hard per-call ceiling, in USDC. The single positive-value challenge is checked **before** it is signed; a preceding zero-value identity handshake does not consume the cap. An over-cap challenge aborts with `outcome: "payment_failed"`, and a second positive-value challenge is refused before signing. Set `maxPay` on every paid call — it's the guardrail that keeps a mispriced or hostile endpoint from draining the wallet.
 
 To put a human in the loop before any spend, read the price up front, show it to your user, and only call `fetch()` with `maxPay` once they approve. Prefer `capabilities.get()`'s **`pricing`** object when present: `pricing.summary` is the server-resolved display string (render it verbatim — don't re-derive from raw fields), `pricing.kind` classifies the shape (`static | dynamic | session | metered | subscription | free | unknown`), and `pricing.primary.amountUsd` / `depositUsd` give the structured numbers for sizing `maxPay`. `cost.amount` remains on every search result as the raw advertised scalar, but it flattens usage-priced caps — a `dynamic` cap's real cost scales with input.
 
@@ -230,20 +232,32 @@ await client.wallet.list();      // every wallet linked to the session user
 await client.wallet.provision(); // create the user's managed wallet (idempotent)
 
 // Link an existing self-custody wallet by private key (0x prefix optional).
-// Pass makePrimary to have it pay for the user's calls from now on.
+// Pass makePrimary to have it pay for the user's calls from now on, and an
+// optional nickname (owner-private display name, max 64 chars).
 const imported = await client.wallet.import({
   privateKey: "0x…",
   makePrimary: true,
+  nickname: "Trading bot",
 });
 
 // Switch which linked wallet is primary, or unlink one. remove() rejects the
 // primary wallet and any wallet holding a balance — reassign / drain first.
 await client.wallet.setPrimary({ walletAddress: imported.walletAddress });
 await client.wallet.remove({ walletAddress: "0x…" });
+
+// Nickname a wallet (or clear with null). Nicknames are private to the
+// authenticated user — they never appear on reviews or public surfaces.
+await client.wallet.setNickname({ walletAddress: "0x…", nickname: "Cold storage" });
+
+// Revoke / re-grant Zero's signing delegation per wallet (default: primary).
+await client.wallet.revokeDelegation({ walletAddress: "0x…" });
+await client.wallet.reauthorizeDelegation({ walletAddress: "0x…" });
 ```
 
 `wallet.address()` covers the common case (resolve — or provision — the primary managed wallet); reach for the methods above when you need the full wallet objects, explicit provisioning, or multi-wallet management. Imported wallets carry an `importedAt` timestamp on the returned wallet objects.
 
+To **pay from a non-primary wallet**, pass `walletAddress` on the call itself — `client.fetch(url, { walletAddress })` (or `payments.pay` / `payMpp`) resolves the named profile wallet for the payment intent's `from`, the managed signature, and the recorded run's attribution, and `client.auth.sign*` accept `{ walletAddress }` too. The wallet must be a delegated Privy-embedded wallet on the session user's profile. Runs can likewise be filtered per wallet: `client.runs.list({ walletAddress: ["0x…"] })` (default remains all profile wallets; an address not on the profile is a 400).
+
 ## Namespaces
 
 Beyond `search()` and `fetch()`, the client groups the rest of the API into resource namespaces:
@@ -262,8 +276,8 @@ const cap = await client.capabilities.get("cap_abc");     // by uid
 const cap2 = await client.capabilities.get("z_Ab12cd.1"); // by search token
 
 // Wallet — balance, one-time funding URL, and (session mode) multi-wallet
-// management: list / provision / import / setPrimary / remove. See
-// "Wallet & funding" above.
+// management: list / provision / import / setPrimary / remove / setNickname /
+// revokeDelegation / reauthorizeDelegation. See "Wallet & funding" above.
 const { amount } = await client.wallet.balance();
 const fundUrl    = await client.wallet.fundingUrl({ amount: "10" });
 

package/dist/{chunk-O7424YAR.cjs → chunk-AM5RDERD.cjs}

@@ -8,43 +8,46 @@ var client$1 = require('@x402/core/client');
 var http = require('@x402/core/http');
 var client = require('@x402/evm/exact/client');
 var signInWithX = require('@x402/extensions/sign-in-with-x');
-var fetch = require('@x402/fetch');
 var mppx = require('mppx');
 var client$2 = require('mppx/client');
 var crypto$1 = require('crypto');
 var zod = require('zod');
 
 // src/auth/managed-account.ts
-var createManagedAccount = (client, address) => accounts.toAccount({
-  address,
-  async signMessage({ message }) {
-    return await client.auth.signMessage(
-      { message },
-      { expectedAddress: address }
-    );
-  },
-  async signTypedData(typedData) {
-    const td = typedData;
-    return await client.auth.signTypedData(
-      {
-        domain: td.domain,
-        types: td.types,
-        primaryType: td.primaryType,
-        message: td.message
-      },
-      { expectedAddress: address }
-    );
-  },
-  async signTransaction(transaction, options) {
-    const serialize = options?.serializer ?? viem.serializeTransaction;
-    const unsigned = await serialize(transaction);
-    const signature = await client.auth.signTransaction(
-      { unsignedTransaction: unsigned },
-      { expectedAddress: address }
-    );
-    return await serialize(transaction, viem.parseSignature(signature));
-  }
-});
+var createManagedAccount = (client, address, opts = {}) => {
+  const signOptions = {
+    // expectedAddress pins verification to this adapter's frozen address.
+    expectedAddress: address,
+    ...opts.explicitWallet ? { walletAddress: address } : {}
+  };
+  return accounts.toAccount({
+    address,
+    async signMessage({ message }) {
+      return await client.auth.signMessage({ message }, signOptions);
+    },
+    async signTypedData(typedData) {
+      const td = typedData;
+      return await client.auth.signTypedData(
+        {
+          domain: td.domain,
+          types: td.types,
+          primaryType: td.primaryType,
+          message: td.message
+        },
+        signOptions
+      );
+    },
+    async signTransaction(transaction, options) {
+      const serialize = options?.serializer ?? viem.serializeTransaction;
+      const unsigned = await serialize(transaction);
+      const signature = await client.auth.signTransaction(
+        { unsignedTransaction: unsigned },
+        signOptions
+      );
+      return await serialize(transaction, viem.parseSignature(signature));
+    }
+  });
+};
 var USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 var USDC_TEMPO = "0x20c000000000000000000000b9537d11c60e8b50";
 var TEMPO_CHAIN_ID = 4217;
@@ -641,12 +644,12 @@ var cancelBody = (response) => {
   } catch {
   }
 };
-var resolveAccount = async (client, overrideAccount, signal) => {
+var resolveAccount = async (client, overrideAccount, signal, walletAddress) => {
   if (overrideAccount) return overrideAccount;
   const credentials = client.getCredentials();
   if (credentials.kind === "account") return credentials.account;
   if (credentials.kind === "session") {
-    return await client.resolveManagedAccount(signal);
+    return await client.resolveManagedAccount(signal, walletAddress);
   }
   throw new ZeroAuthError(
     "auth_no_credentials",
@@ -692,9 +695,13 @@ var Payments = class {
     const account = await resolveAccount(
       this.client,
       input.account,
-      input.signal
+      input.signal,
+      input.walletAddress
     );
     let capturedAmount = null;
+    let pendingAmountUnits = 0n;
+    let identityChallengeHandled = false;
+    let paidChallengeHandled = false;
     let capturedNetwork;
     let preflightError = null;
     const x402 = client.registerExactEvmScheme(new client$1.x402Client(), { signer: account });
@@ -723,11 +730,25 @@ var Payments = class {
         };
       }
       const rawAmountUnits = BigInt(rawAmount);
-      capturedAmount = viem.formatUnits(rawAmountUnits, 6);
+      pendingAmountUnits = rawAmountUnits;
+      const challengeAmount = viem.formatUnits(rawAmountUnits, 6);
+      if (rawAmountUnits === 0n) {
+        if (identityChallengeHandled || paidChallengeHandled) {
+          return {
+            abort: true,
+            reason: "Only one zero-value identity challenge is allowed, and it must precede payment."
+          };
+        }
+      } else if (paidChallengeHandled) {
+        return {
+          abort: true,
+          reason: "A positive-value x402 payment was already attempted for this fetch; refusing a second charge."
+        };
+      }
       if (maxPayUnits !== null && rawAmountUnits > maxPayUnits) {
         return {
           abort: true,
-          reason: `Payment of ${capturedAmount} USDC exceeds maxPay ${input.maxPay}`
+          reason: `Payment of ${challengeAmount} USDC exceeds maxPay ${input.maxPay}`
         };
       }
       const detected = networkToChain(capturedNetwork);
@@ -747,9 +768,10 @@ var Payments = class {
       }
       if (balance !== null && balance < rawAmountUnits) {
         const have = viem.formatUnits(balance, 6);
+        const requiredAmount = viem.formatUnits(rawAmountUnits, 6);
         preflightError = new ZeroInsufficientFundsError(
-          `wallet has ${have} USDC on Base, needs ${capturedAmount}.`,
-          { have, need: capturedAmount }
+          `wallet has ${have} USDC on Base, needs ${requiredAmount}.`,
+          { have, need: requiredAmount }
         );
         return { abort: true, reason: preflightError.message };
       }
@@ -760,18 +782,64 @@ var Payments = class {
     const httpClient = new http.x402HTTPClient(x402).onPaymentRequired(
       signInWithX.createSIWxClientHook(account)
     );
-    const wrappedFetch = fetch.wrapFetchWithPayment(
-      withSynthesizedX402Header(configuredFetch),
-      httpClient
-    );
+    const paymentFetch = withSynthesizedX402Header(configuredFetch);
     let response;
     try {
-      response = await wrappedFetch(input.url, {
+      const request2 = new Request(input.url, {
         method: input.method ?? "GET",
         headers: input.headers,
         body: input.body,
         signal: input.signal
       });
+      response = await paymentFetch(request2.clone());
+      for (let paymentStage = 0; paymentStage < 2; paymentStage++) {
+        if (response.status !== 402) break;
+        const parseChallenge = async (challengeResponse) => {
+          let body;
+          try {
+            const text = await challengeResponse.clone().text();
+            if (text) body = JSON.parse(text);
+          } catch {
+          }
+          return httpClient.getPaymentRequiredResponse(
+            (name) => challengeResponse.headers.get(name),
+            body
+          );
+        };
+        let paymentRequired = await parseChallenge(response);
+        const hookHeaders = await httpClient.handlePaymentRequired(paymentRequired);
+        if (hookHeaders) {
+          const hookRequest = request2.clone();
+          for (const [key, value] of Object.entries(hookHeaders)) {
+            hookRequest.headers.set(key, value);
+          }
+          response = await paymentFetch(hookRequest);
+          if (response.status === 402) {
+            paymentRequired = await parseChallenge(response);
+          } else {
+            break;
+          }
+        }
+        pendingAmountUnits = 0n;
+        const paymentPayload = await x402.createPaymentPayload(paymentRequired);
+        if (pendingAmountUnits === 0n) {
+          identityChallengeHandled = true;
+          capturedAmount = "0";
+        } else {
+          paidChallengeHandled = true;
+          capturedAmount = viem.formatUnits(pendingAmountUnits, 6);
+        }
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+        const paidRequest = request2.clone();
+        for (const [key, value] of Object.entries(paymentHeaders)) {
+          paidRequest.headers.set(key, value);
+        }
+        paidRequest.headers.set(
+          "Access-Control-Expose-Headers",
+          "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
+        );
+        response = await paymentFetch(paidRequest);
+      }
     } catch (err) {
       if (preflightError) throw preflightError;
       if (err instanceof ZeroError) throw err;
@@ -827,7 +895,8 @@ var Payments = class {
     const account = await resolveAccount(
       this.client,
       input.account,
-      input.signal
+      input.signal,
+      input.walletAddress
     );
     const configuredFetch = buildConfiguredFetch(this.client, {
       timeoutMs: input.timeoutMs
@@ -1338,8 +1407,17 @@ var cancelBody2 = (response) => {
   } catch {
   }
 };
-var detectPaymentRequirement = async (response) => {
+var detectPaymentRequirement = async (response, preferredProtocol) => {
   if (response.status !== 402) return null;
+  const wwwAuth = response.headers.get("www-authenticate");
+  const advertisesMpp = wwwAuth ? splitWwwAuthenticateChallenges(wwwAuth).some((challenge) => {
+    const scheme = challenge.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    return MPP_SCHEME_TOKENS.has(scheme);
+  }) : false;
+  if (preferredProtocol === "mpp") {
+    cancelBody2(response);
+    return advertisesMpp ? { protocol: "mpp", raw: { "www-authenticate": wwwAuth } } : { protocol: "unknown", raw: { requestedProtocol: "mpp" } };
+  }
   const x402Header = response.headers.get("payment-required") ?? response.headers.get("x-payment-required");
   if (x402Header) {
     cancelBody2(response);
@@ -1369,15 +1447,13 @@ var detectPaymentRequirement = async (response) => {
     } catch {
     }
   }
-  const wwwAuth = response.headers.get("www-authenticate");
-  if (wwwAuth) {
-    const schemes = splitWwwAuthenticateChallenges(wwwAuth).map(
-      (challenge) => challenge.trim().split(/\s+/)[0]?.toLowerCase() ?? ""
-    );
-    if (schemes.some((scheme) => MPP_SCHEME_TOKENS.has(scheme))) {
-      cancelBody2(response);
-      return { protocol: "mpp", raw: { "www-authenticate": wwwAuth } };
-    }
+  if (preferredProtocol === "x402") {
+    cancelBody2(response);
+    return { protocol: "unknown", raw: { requestedProtocol: "x402" } };
+  }
+  if (advertisesMpp) {
+    cancelBody2(response);
+    return { protocol: "mpp", raw: { "www-authenticate": wwwAuth } };
   }
   cancelBody2(response);
   return { protocol: "unknown", raw: {} };
@@ -1607,7 +1683,8 @@ var recordErrorFetchRun = async (client, opts, result, capabilityIdOverride) =>
       ...fetchOriginForRecord && { fetchOrigin: fetchOriginForRecord },
       ...result.status !== null && { status: result.status },
       latencyMs: result.latencyMs,
-      ...opts.requestSchema && { requestSchema: opts.requestSchema }
+      ...opts.requestSchema && { requestSchema: opts.requestSchema },
+      ...opts.walletAddress && !opts.account && { walletAddress: opts.walletAddress }
     });
     result.runId = created.runId;
     delete result.runTrackingSkipped;
@@ -1702,7 +1779,10 @@ var clientFetch = async (client, url, opts = {}) => {
     return result2;
   }
   if (response.status === 402) {
-    const requirement = await detectPaymentRequirement(response);
+    const requirement = await detectPaymentRequirement(
+      response,
+      opts.paymentProtocol
+    );
     if (requirement?.protocol === "x402" || requirement?.protocol === "mpp") {
       const payCall = requirement.protocol === "x402" ? client.payments.pay : client.payments.payMpp;
       try {
@@ -1716,6 +1796,7 @@ var clientFetch = async (client, url, opts = {}) => {
           body: requestBody,
           maxPay: opts.maxPay,
           account: opts.account,
+          ...opts.walletAddress && { walletAddress: opts.walletAddress },
           signal: opts.signal,
           timeoutMs: opts.timeoutMs,
           ...opts.displayCostAmount && {
@@ -1773,7 +1854,7 @@ var clientFetch = async (client, url, opts = {}) => {
     } else if (requirement?.protocol === "unknown") {
       const result2 = errorFetchResult(
         startedAt,
-        "Capability returned 402 with an unrecognized payment protocol. Neither x402 nor MPP markers were detected in the response headers or body.",
+        opts.paymentProtocol ? `Capability did not advertise the requested ${opts.paymentProtocol} payment protocol.` : "Capability returned 402 with an unrecognized payment protocol. Neither x402 nor MPP markers were detected in the response headers or body.",
         "unrecognized_402_protocol",
         capabilityIdRequested,
         "payment_failed",
@@ -1888,6 +1969,10 @@ var clientFetch = async (client, url, opts = {}) => {
           ...opts.capabilityId === void 0 ? { fetchOrigin: "direct_url" } : opts.fetchOrigin && { fetchOrigin: opts.fetchOrigin },
           status: response.status,
           latencyMs,
+          // Attribute to the selected wallet in session mode. Skipped when a
+          // per-call `account` override records the run — that account's own
+          // EIP-191 identity is the attribution.
+          ...opts.walletAddress && !opts.account && { walletAddress: opts.walletAddress },
           ...opts.requestSchema && { requestSchema: opts.requestSchema },
           ...derived?.responseSchema && {
             responseSchema: derived.responseSchema
@@ -1953,7 +2038,7 @@ var clientFetch = async (client, url, opts = {}) => {
 
 // package.json
 var package_default = {
-  version: "0.12.0"};
+  version: "0.14.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -2443,6 +2528,9 @@ var userWalletDtoSchema = zod.z.object({
   walletAddress: zod.z.string(),
   source: zod.z.enum(["self_custody", "privy_embedded"]),
   isPrimary: zod.z.boolean(),
+  // Owner-chosen display name; null/absent = unnamed (show the address).
+  // Optional so the SDK tolerates servers that predate nicknames.
+  nickname: zod.z.string().nullable().optional(),
   linkedAt: zod.z.union([zod.z.string(), zod.z.date()]).nullable().optional(),
   importedAt: zod.z.union([zod.z.string(), zod.z.date()]).nullable().optional(),
   delegationGranted: zod.z.boolean(),
@@ -2660,7 +2748,10 @@ var Auth = class {
           {
             method: "POST",
             path: "/v1/users/me/sign-message",
-            body: { message: normalizeMessage(input.message) }
+            body: {
+              message: normalizeMessage(input.message),
+              ...opts.walletAddress ? { walletAddress: opts.walletAddress } : {}
+            }
           },
           signResponseSchema
         );
@@ -2685,7 +2776,10 @@ var Auth = class {
           {
             method: "POST",
             path: "/v1/users/me/sign-transaction",
-            body: { unsignedTransaction: input.unsignedTransaction }
+            body: {
+              unsignedTransaction: input.unsignedTransaction,
+              ...opts.walletAddress ? { walletAddress: opts.walletAddress } : {}
+            }
           },
           signResponseSchema
         );
@@ -2724,7 +2818,10 @@ var Auth = class {
           {
             method: "POST",
             path: "/v1/users/me/sign-typed-data",
-            body: { typedData: input }
+            body: {
+              typedData: input,
+              ...opts.walletAddress ? { walletAddress: opts.walletAddress } : {}
+            }
           },
           signResponseSchema
         );
@@ -3101,6 +3198,9 @@ var Runs = class {
     if (params.unreviewed !== void 0) query.unreviewed = params.unreviewed;
     if (params.limit !== void 0) query.limit = params.limit;
     if (params.cursor !== void 0) query.cursor = params.cursor;
+    if (params.walletAddress !== void 0) {
+      query.walletAddress = Array.isArray(params.walletAddress) ? params.walletAddress.join(",") : params.walletAddress;
+    }
     return request(
       this.client,
       {
@@ -3236,6 +3336,50 @@ var Wallet = class {
     },
     userWalletDtoSchema
   );
+  // Re-stamp Zero's signing delegation on a profile wallet (default: the
+  // primary). Session-only. Naming a wallet re-authorizes THAT wallet and
+  // never provisions; the server 404s an address not on the profile.
+  reauthorizeDelegation = (opts = {}) => request(
+    this.client,
+    {
+      method: "POST",
+      path: "/v1/users/me/wallets/provision",
+      ...opts.walletAddress ? { body: { walletAddress: opts.walletAddress } } : {},
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Revoke Zero's signing delegation on a profile wallet (default: the
+  // primary). Session-only. Managed signing on that wallet 403s until it is
+  // re-authorized. Note: this stamps the server-side gate — removing Zero's
+  // signer cryptographically is owner-authorized and happens in the user's
+  // Privy session (the web profile page does both).
+  revokeDelegation = (opts = {}) => request(
+    this.client,
+    {
+      method: "DELETE",
+      path: "/v1/users/me/wallets/delegation",
+      ...opts.walletAddress ? { query: { walletAddress: opts.walletAddress } } : {},
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Set, change, or clear (null / empty string) the owner-chosen nickname on
+  // a profile wallet. Session-only. Nicknames are private to the
+  // authenticated user — they never appear on reviews or public surfaces.
+  setNickname = (opts) => request(
+    this.client,
+    {
+      method: "PATCH",
+      path: "/v1/users/me/wallets/nickname",
+      body: {
+        walletAddress: opts.walletAddress,
+        nickname: opts.nickname
+      },
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
   // Link an existing self-custody wallet to the session user by private key.
   // Session-only. 409s when the wallet is already linked (to this or another
   // profile — the error message says which).
@@ -3246,7 +3390,8 @@ var Wallet = class {
       path: "/v1/users/me/wallets/import",
       body: {
         privateKey: opts.privateKey,
-        ...opts.makePrimary !== void 0 ? { makePrimary: opts.makePrimary } : {}
+        ...opts.makePrimary !== void 0 ? { makePrimary: opts.makePrimary } : {},
+        ...opts.nickname !== void 0 ? { nickname: opts.nickname } : {}
       },
       signal: opts.signal
     },
@@ -3449,6 +3594,9 @@ var ZeroClient = class _ZeroClient {
   managedAccountInFlight = null;
   managedAccountAC = null;
   managedAccountGen = 0;
+  // Explicitly-selected (non-default) managed wallets, keyed by lowercased
+  // address. Same lifecycle as managedAccount: cleared on clearManagedAccount.
+  managedAccountByAddress = /* @__PURE__ */ new Map();
   // Multi-tenant servers calling `client.fetch(url, { account: tenantAccount })`
   // on every request would otherwise construct a new ZeroClient (with
   // five namespace instances) per call. Keyed by lowercased account
@@ -3670,8 +3818,16 @@ var ZeroClient = class _ZeroClient {
     }
     this.withAccountCache.clear();
   };
-  /** @internal — used by payments.pay() in session mode. Cached, dedupes concurrent lookups. */
-  resolveManagedAccount = (signal) => {
+  /**
+   * @internal — used by payments.pay() in session mode. Cached, dedupes
+   * concurrent lookups. Pass `walletAddress` to sign as a specific profile
+   * wallet instead of the primary; explicit wallets are cached per address
+   * and their sign requests carry the address so intent and signer agree.
+   */
+  resolveManagedAccount = (signal, walletAddress) => {
+    if (walletAddress) {
+      return this.resolveManagedAccountByAddress(walletAddress, signal);
+    }
     if (this.managedAccount) return Promise.resolve(this.managedAccount);
     if (this.managedAccountInFlight) {
       return this.raceWithSignal(this.managedAccountInFlight, signal);
@@ -3713,6 +3869,42 @@ var ZeroClient = class _ZeroClient {
     });
     return this.raceWithSignal(this.managedAccountInFlight, signal);
   };
+  // Explicit-wallet variant of resolveManagedAccount. No in-flight dedupe:
+  // this is the rare path (per-wallet pay), the resolution is idempotent, and
+  // the per-address cache absorbs repeat calls.
+  resolveManagedAccountByAddress = async (walletAddress, signal) => {
+    if (this.credentials.kind !== "session") {
+      throw new ZeroAuthError(
+        "auth_no_credentials",
+        "resolveManagedAccount() requires session credentials."
+      );
+    }
+    const canonical = viem.getAddress(walletAddress);
+    const cached = this.managedAccountByAddress.get(canonical.toLowerCase());
+    if (cached) return cached;
+    const startedAtGen = this.managedAccountGen;
+    const wallets = await this.auth.wallets({ signal });
+    const match = wallets.find(
+      (w) => w.walletAddress.toLowerCase() === canonical.toLowerCase()
+    );
+    if (!match || match.source !== "privy_embedded") {
+      throw new ZeroAuthError(
+        "auth_error",
+        `Wallet ${canonical} is not a Privy-embedded wallet on this profile. Managed signing can only use profile wallets (see client.wallet.list()).`
+      );
+    }
+    if (this.managedAccountGen !== startedAtGen) {
+      throw new ZeroAuthError(
+        "auth_session_expired",
+        "Session cleared during managed-account resolution. Retry to rebuild against the current session."
+      );
+    }
+    const acc = createManagedAccount(this, canonical, {
+      explicitWallet: true
+    });
+    this.managedAccountByAddress.set(canonical.toLowerCase(), acc);
+    return acc;
+  };
   // Per-caller signal gate: each caller can reject on their own abort
   // without cancelling the shared underlying promise.
   raceWithSignal = (p, signal) => {
@@ -3743,6 +3935,7 @@ var ZeroClient = class _ZeroClient {
     this.managedAccountAC?.abort();
     this.managedAccountInFlight = null;
     this.managedAccountAC = null;
+    this.managedAccountByAddress.clear();
     this.managedAccountGen++;
   };
   /** @internal — Read cached managed account without triggering resolution. */
@@ -3835,5 +4028,5 @@ exports.normalizeTransportEnvelopeRequest = normalizeTransportEnvelopeRequest;
 exports.paymentHasAnchor = paymentHasAnchor;
 exports.tempoChainLabelFromId = tempoChainLabelFromId;
 exports.unwrapTransportEnvelope = unwrapTransportEnvelope;
-//# sourceMappingURL=chunk-O7424YAR.cjs.map
-//# sourceMappingURL=chunk-O7424YAR.cjs.map
+//# sourceMappingURL=chunk-AM5RDERD.cjs.map
+//# sourceMappingURL=chunk-AM5RDERD.cjs.map