@agether/sdk 1.7.0 → 1.9.0

package/README.md

@@ -106,6 +106,90 @@ await vault.withdraw(parseUnits('5000', 6));
 
 ---
 
+## 🔐 Signing Modes
+
+Both `MorphoClient` (ethers) and `X402Client` (viem) support two mutually exclusive signing modes: **private key** (SDK-managed wallet) and **external signer/wallet** (custody-agnostic).
+
+### MorphoClient — Private Key
+
+```typescript
+import { MorphoClient } from '@agether/sdk';
+
+const client = new MorphoClient({
+  privateKey: process.env.AGENT_PRIVATE_KEY!,
+  rpcUrl: 'https://mainnet.base.org',
+  agentId: '42',
+});
+```
+
+### MorphoClient — External Signer (ethers.AbstractSigner)
+
+```typescript
+import { MorphoClient, AgetherSigner } from '@agether/sdk';
+
+// Any ethers.AbstractSigner works:
+// - ethers.Wallet
+// - Privy embedded wallet signer
+// - Bankr custodial signer
+// - Turnkey / MPC wallet signer
+// - MetaMask via BrowserProvider.getSigner()
+const signer: AgetherSigner = getSignerFromCustodyProvider();
+
+const client = new MorphoClient({
+  signer,
+  rpcUrl: 'https://mainnet.base.org',
+  agentId: '42',
+});
+
+// All operations work identically regardless of signing mode
+const status = await client.getStatus();
+await client.supplyCollateral('WETH', '0.1');
+await client.borrow('100');
+```
+
+> **Note:** When using an external signer, the SDK treats it as immutable — it will never
+> recreate or reconnect the signer. Nonce management is the caller's responsibility.
+
+### X402Client — Private Key
+
+```typescript
+import { X402Client } from '@agether/sdk';
+
+const client = new X402Client({
+  privateKey: process.env.AGENT_PRIVATE_KEY!,
+  rpcUrl: 'https://mainnet.base.org',
+  backendUrl: 'https://api.agether.ai',
+  agentId: '42',
+});
+```
+
+### X402Client — viem WalletClient (Privy, Turnkey, etc.)
+
+```typescript
+import { X402Client, AgetherViemWallet } from '@agether/sdk';
+
+// Any viem WalletClient with an attached account works:
+// - Privy embedded wallet → createWalletClient(...)
+// - Turnkey signer → turnkeyToViemAccount(...)
+// - MetaMask → createWalletClient({ transport: custom(window.ethereum) })
+const walletClient: AgetherViemWallet = privyWalletClient;
+
+const client = new X402Client({
+  walletClient,
+  rpcUrl: 'https://mainnet.base.org',
+  backendUrl: 'https://api.agether.ai',
+  agentId: '42',
+});
+
+// All x402 operations work identically regardless of signing mode
+const result = await client.get('https://paid-api.example.com/data');
+```
+
+> **Note:** The `walletClient` must have an `account` property set (i.e. created with
+> `createWalletClient({ account: ... })`). The SDK will never recreate or reconnect the client.
+
+---
+
 ## 📚 API Reference
 
 ### AgetherClient
@@ -215,6 +299,29 @@ Client for ERC-8004 agent identity management via ag0 SDK.
 
 ---
 
+## 🔒 KYA (Know Your Agent) Gate
+
+The protocol includes an optional **KYA code verification gate**. When enabled, agents must have their code approved by a validator in the `ValidationRegistry` before they can call `execute()` or `executeBatch()` on their `AgentAccount`.
+
+**When is it active?**
+- If the `AccountFactory` was deployed with a non-zero `validationRegistry` address, KYA is **enabled**
+- If `validationRegistry = address(0)`, KYA is **disabled** — agents can transact immediately after registration
+
+**Checking from the SDK:**
+
+```typescript
+const kyaRequired = await client.isKyaRequired();
+if (kyaRequired) {
+  console.log('KYA gate is active — agent code must be approved before executing');
+} else {
+  console.log('KYA gate is disabled — agents can execute immediately');
+}
+```
+
+The `register()` method also returns `kyaRequired: boolean` so consumers know the state at registration time.
+
+---
+
 ## 📝 Types
 
 ### CreditStatus

package/dist/cli.js

@@ -66,7 +66,10 @@ var init_abis = __esm({
       "function totalAccounts() view returns (uint256)",
       "function getAgentId(address account) view returns (uint256)",
       "function createAccount(uint256 agentId) returns (address account)",
-      "event AccountCreated(uint256 indexed agentId, address indexed account, address indexed owner)"
+      "function validationRegistry() view returns (address)",
+      "function setValidationRegistry(address newRegistry)",
+      "event AccountCreated(uint256 indexed agentId, address indexed account, address indexed owner)",
+      "event ValidationRegistryUpdated(address indexed oldRegistry, address indexed newRegistry)"
     ];
     AGENT_ACCOUNT_ABI = [
       "function agentId() view returns (uint256)",
@@ -228,14 +231,44 @@ var init_MorphoClient = __esm({
         this.config = defaultCfg;
         this.agentId = config.agentId;
         this._rpcUrl = config.rpcUrl || defaultCfg.rpcUrl;
-        this._privateKey = config.privateKey;
-        this.provider = new import_ethers.ethers.JsonRpcProvider(this._rpcUrl);
-        this.wallet = new import_ethers.ethers.Wallet(this._privateKey, this.provider);
+        if ("signer" in config && config.signer) {
+          this._useExternalSigner = true;
+          const signerProvider = config.signer.provider;
+          if (signerProvider) {
+            this.provider = signerProvider;
+            this._signer = config.signer;
+          } else {
+            this.provider = new import_ethers.ethers.JsonRpcProvider(this._rpcUrl);
+            this._signer = config.signer.connect(this.provider);
+          }
+          if ("address" in config.signer && typeof config.signer.address === "string") {
+            this._eoaAddress = config.signer.address;
+          }
+        } else {
+          this._privateKey = config.privateKey;
+          this._useExternalSigner = false;
+          this.provider = new import_ethers.ethers.JsonRpcProvider(this._rpcUrl);
+          const wallet = new import_ethers.ethers.Wallet(this._privateKey, this.provider);
+          this._signer = wallet;
+          this._eoaAddress = wallet.address;
+        }
         const addrs = { ...defaultCfg.contracts, ...config.contracts };
-        this.accountFactory = new import_ethers.Contract(addrs.accountFactory, ACCOUNT_FACTORY_ABI, this.wallet);
+        this.accountFactory = new import_ethers.Contract(addrs.accountFactory, ACCOUNT_FACTORY_ABI, this._signer);
         this.morphoBlue = new import_ethers.Contract(addrs.morphoBlue, MORPHO_BLUE_ABI, this.provider);
-        this.agentReputation = new import_ethers.Contract(addrs.agentReputation, AGENT_REPUTATION_ABI, this.wallet);
-        this.identityRegistry = new import_ethers.Contract(addrs.identityRegistry, IDENTITY_REGISTRY_ABI, this.wallet);
+        this.agentReputation = new import_ethers.Contract(addrs.agentReputation, AGENT_REPUTATION_ABI, this._signer);
+        this.identityRegistry = new import_ethers.Contract(addrs.identityRegistry, IDENTITY_REGISTRY_ABI, this._signer);
+      }
+      // ════════════════════════════════════════════════════════
+      //  KYA Gate Check
+      // ════════════════════════════════════════════════════════
+      /**
+       * Check whether the KYA (Know Your Agent) code verification gate is active.
+       * When validationRegistry is address(0), KYA is disabled — agents can use
+       * execute/executeBatch without prior code approval.
+       */
+      async isKyaRequired() {
+        const registryAddr = await this.accountFactory.validationRegistry();
+        return registryAddr !== import_ethers.ethers.ZeroAddress;
       }
       // ════════════════════════════════════════════════════════
       //  Account Management
@@ -255,8 +288,35 @@ var init_MorphoClient = __esm({
         if (!this.agentId) throw new AgetherError("agentId not set", "NO_AGENT_ID");
         return this.agentId;
       }
+      /**
+       * Get the EOA wallet address (synchronous, best-effort).
+       *
+       * For the `privateKey` path this always works. For the `signer` path
+       * it works if the signer exposes `.address` synchronously (e.g. ethers.Wallet).
+       * If the address has not been resolved yet, throws — call `getSignerAddress()` first.
+       */
       getWalletAddress() {
-        return this.wallet.address;
+        if (this._eoaAddress) return this._eoaAddress;
+        const signer = this._signer;
+        if (signer.address && typeof signer.address === "string") {
+          const addr = signer.address;
+          this._eoaAddress = addr;
+          return addr;
+        }
+        throw new AgetherError(
+          "EOA address not yet resolved. Call getSignerAddress() (async) first, or use a signer that exposes .address synchronously.",
+          "ADDRESS_NOT_RESOLVED"
+        );
+      }
+      /**
+       * Resolve the EOA signer address (async, works with all signer types).
+       * Result is cached after the first call.
+       */
+      async getSignerAddress() {
+        if (!this._eoaAddress) {
+          this._eoaAddress = await this._signer.getAddress();
+        }
+        return this._eoaAddress;
       }
       /** Mint a new ERC-8004 identity and return the agentId. */
       async _mintNewIdentity() {
@@ -283,13 +343,14 @@ var init_MorphoClient = __esm({
        * If already registered, returns existing state.
        */
       async register(_name) {
-        const eoaAddr = this.wallet.address;
+        const eoaAddr = await this.getSignerAddress();
         if (this.agentId) {
           const exists = await this.accountFactory.accountExists(BigInt(this.agentId));
           if (exists) {
             const acct = await this.accountFactory.getAccount(BigInt(this.agentId));
             this._accountAddress = acct;
-            return { agentId: this.agentId, address: eoaAddr, agentAccount: acct, alreadyRegistered: true };
+            const kyaRequired2 = await this.isKyaRequired();
+            return { agentId: this.agentId, address: eoaAddr, agentAccount: acct, alreadyRegistered: true, kyaRequired: kyaRequired2 };
           }
         }
         let agentId;
@@ -314,17 +375,19 @@ var init_MorphoClient = __esm({
         }
         const acctAddr = await this.accountFactory.getAccount(agentId);
         this._accountAddress = acctAddr;
+        const kyaRequired = await this.isKyaRequired();
         return {
           agentId: this.agentId,
           address: eoaAddr,
           agentAccount: acctAddr,
           alreadyRegistered: acctExists,
+          kyaRequired,
           tx: txHash
         };
       }
       /** Get ETH / USDC / collateral balances for EOA and AgentAccount. */
       async getBalances() {
-        const eoaAddr = this.wallet.address;
+        const eoaAddr = await this.getSignerAddress();
         const usdc = new import_ethers.Contract(this.config.contracts.usdc, ERC20_ABI, this.provider);
         const ethBal = await this.provider.getBalance(eoaAddr);
         const usdcBal = await usdc.balanceOf(eoaAddr);
@@ -372,7 +435,7 @@ var init_MorphoClient = __esm({
       /** Transfer USDC from EOA to AgentAccount. */
       async fundAccount(usdcAmount) {
         const acctAddr = await this.getAccountAddress();
-        const usdc = new import_ethers.Contract(this.config.contracts.usdc, ERC20_ABI, this.wallet);
+        const usdc = new import_ethers.Contract(this.config.contracts.usdc, ERC20_ABI, this._signer);
         const amount = import_ethers.ethers.parseUnits(usdcAmount, 6);
         const tx = await usdc.transfer(acctAddr, amount);
         const receipt = await tx.wait();
@@ -720,7 +783,7 @@ var init_MorphoClient = __esm({
         const params = marketParams ?? await this.findMarketForCollateral(tokenSymbol);
         const weiAmount = import_ethers.ethers.parseUnits(amount, colInfo.decimals);
         const morphoAddr = this.config.contracts.morphoBlue;
-        const colToken = new import_ethers.Contract(colInfo.address, ERC20_ABI, this.wallet);
+        const colToken = new import_ethers.Contract(colInfo.address, ERC20_ABI, this._signer);
         const transferTx = await colToken.transfer(acctAddr, weiAmount);
         await transferTx.wait();
         this._refreshSigner();
@@ -797,7 +860,7 @@ var init_MorphoClient = __esm({
         const colWei = import_ethers.ethers.parseUnits(collateralAmount, colInfo.decimals);
         const borrowWei = import_ethers.ethers.parseUnits(borrowUsdcAmount, 6);
         const morphoAddr = this.config.contracts.morphoBlue;
-        const colToken = new import_ethers.Contract(colInfo.address, ERC20_ABI, this.wallet);
+        const colToken = new import_ethers.Contract(colInfo.address, ERC20_ABI, this._signer);
         const transferTx = await colToken.transfer(acctAddr, colWei);
         await transferTx.wait();
         this._refreshSigner();
@@ -927,7 +990,7 @@ var init_MorphoClient = __esm({
         if (!colInfo) throw new AgetherError(`Unknown collateral: ${tokenSymbol}`, "UNKNOWN_COLLATERAL");
         const params = marketParams ?? await this.findMarketForCollateral(tokenSymbol);
         const morphoAddr = this.config.contracts.morphoBlue;
-        const dest = receiver || this.wallet.address;
+        const dest = receiver || await this.getSignerAddress();
         let weiAmount;
         if (amount === "all") {
           const markets = await this.getMarkets();
@@ -985,7 +1048,7 @@ var init_MorphoClient = __esm({
           throw new AgetherError("Provide agentId or address", "INVALID_TARGET");
         }
         const weiAmount = import_ethers.ethers.parseUnits(amount, colInfo.decimals);
-        const colToken = new import_ethers.Contract(colInfo.address, ERC20_ABI, this.wallet);
+        const colToken = new import_ethers.Contract(colInfo.address, ERC20_ABI, this._signer);
         const tx = await colToken.transfer(targetAddr, weiAmount);
         const receipt = await tx.wait();
         this._refreshSigner();
@@ -1017,24 +1080,41 @@ var init_MorphoClient = __esm({
       //  Internal Helpers
       // ════════════════════════════════════════════════════════
       /**
-       * Recreate provider + wallet so the next tx fetches a fresh nonce from chain.
-       * Anvil (and some RPC providers) return a stale `eth_getTransactionCount`
-       * right after a block is mined, causing "nonce too low" on the follow-up tx.
+       * Refresh the signer and re-bind contract instances.
+       *
+       * For the **privateKey** path: recreates provider + wallet so the next tx
+       * fetches a fresh nonce from chain. Anvil (and some RPC providers) return a
+       * stale `eth_getTransactionCount` right after a block is mined, causing
+       * "nonce too low" on the follow-up tx.
+       *
+       * For the **external signer** path: the signer is immutable and owned by the
+       * caller (e.g. custody provider). We only re-bind contract instances to
+       * ensure they reference the current signer. Nonce management is the caller's
+       * responsibility.
        */
       _refreshSigner() {
-        this.provider = new import_ethers.ethers.JsonRpcProvider(this._rpcUrl);
-        this.wallet = new import_ethers.ethers.Wallet(this._privateKey, this.provider);
-        const addrs = this.config.contracts;
-        this.accountFactory = new import_ethers.Contract(addrs.accountFactory, ACCOUNT_FACTORY_ABI, this.wallet);
-        this.agentReputation = new import_ethers.Contract(addrs.agentReputation, AGENT_REPUTATION_ABI, this.wallet);
-        this.identityRegistry = new import_ethers.Contract(addrs.identityRegistry, IDENTITY_REGISTRY_ABI, this.wallet);
+        if (this._useExternalSigner) {
+          const addrs = this.config.contracts;
+          this.accountFactory = new import_ethers.Contract(addrs.accountFactory, ACCOUNT_FACTORY_ABI, this._signer);
+          this.agentReputation = new import_ethers.Contract(addrs.agentReputation, AGENT_REPUTATION_ABI, this._signer);
+          this.identityRegistry = new import_ethers.Contract(addrs.identityRegistry, IDENTITY_REGISTRY_ABI, this._signer);
+        } else {
+          this.provider = new import_ethers.ethers.JsonRpcProvider(this._rpcUrl);
+          const wallet = new import_ethers.ethers.Wallet(this._privateKey, this.provider);
+          this._signer = wallet;
+          this._eoaAddress = wallet.address;
+          const addrs = this.config.contracts;
+          this.accountFactory = new import_ethers.Contract(addrs.accountFactory, ACCOUNT_FACTORY_ABI, this._signer);
+          this.agentReputation = new import_ethers.Contract(addrs.agentReputation, AGENT_REPUTATION_ABI, this._signer);
+          this.identityRegistry = new import_ethers.Contract(addrs.identityRegistry, IDENTITY_REGISTRY_ABI, this._signer);
+        }
       }
       /**
        * Execute a single call via AgentAccount.execute.
        */
       async exec(target, data, value = 0n) {
         const acctAddr = await this.getAccountAddress();
-        const account = new import_ethers.Contract(acctAddr, AGENT_ACCOUNT_ABI, this.wallet);
+        const account = new import_ethers.Contract(acctAddr, AGENT_ACCOUNT_ABI, this._signer);
         let gasLimit;
         try {
           const estimate = await account.execute.estimateGas(target, value, data);
@@ -1052,7 +1132,7 @@ var init_MorphoClient = __esm({
        */
       async batch(targets, values, datas) {
         const acctAddr = await this.getAccountAddress();
-        const account = new import_ethers.Contract(acctAddr, AGENT_ACCOUNT_ABI, this.wallet);
+        const account = new import_ethers.Contract(acctAddr, AGENT_ACCOUNT_ABI, this._signer);
         let gasLimit;
         try {
           const estimate = await account.executeBatch.estimateGas(targets, values, datas);
@@ -1116,9 +1196,63 @@ var init_X402Client = __esm({
     X402Client = class {
       constructor(config) {
         this.config = config;
-        const privateKey = config.privateKey.startsWith("0x") ? config.privateKey : `0x${config.privateKey}`;
-        const signer = (0, import_accounts.privateKeyToAccount)(privateKey);
-        this.address = signer.address;
+        let baseSigner;
+        if ("walletClient" in config && config.walletClient) {
+          const wc = config.walletClient;
+          const account = wc.account;
+          if (!account) {
+            throw new Error(
+              "X402Client: walletClient must have an attached account. Pass an account when creating the WalletClient or use privateKey mode instead."
+            );
+          }
+          this.address = account.address;
+          baseSigner = {
+            address: account.address,
+            signTypedData: (msg) => wc.signTypedData({
+              account,
+              domain: msg.domain,
+              types: msg.types,
+              primaryType: msg.primaryType,
+              message: msg.message
+            })
+          };
+        } else if ("privateKey" in config && config.privateKey) {
+          const privateKey = config.privateKey.startsWith("0x") ? config.privateKey : `0x${config.privateKey}`;
+          const account = (0, import_accounts.privateKeyToAccount)(privateKey);
+          this.address = account.address;
+          baseSigner = account;
+        } else {
+          throw new Error(
+            "X402Client: provide either privateKey or walletClient in config."
+          );
+        }
+        let signer;
+        if (config.accountAddress) {
+          const accountAddr = config.accountAddress;
+          const inner = baseSigner;
+          signer = (0, import_accounts.toAccount)({
+            address: accountAddr,
+            async signMessage({ message }) {
+              if ("signMessage" in inner && typeof inner.signMessage === "function") {
+                return inner.signMessage({ message });
+              }
+              throw new Error("signMessage not supported by underlying signer");
+            },
+            async signTransaction(tx) {
+              if ("signTransaction" in inner && typeof inner.signTransaction === "function") {
+                return inner.signTransaction(tx);
+              }
+              throw new Error("signTransaction not supported by underlying signer");
+            },
+            async signTypedData(typedData) {
+              const sig = await inner.signTypedData(typedData);
+              return `${sig}00`;
+            }
+          });
+          this.address = accountAddr;
+        } else {
+          signer = baseSigner;
+        }
         const client = new import_client.x402Client();
         (0, import_client2.registerExactEvmScheme)(client, { signer });
         this.paidFetch = (0, import_fetch.wrapFetchWithPayment)(fetch, client);

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { Signer } from 'ethers';
+import { Signer, ethers } from 'ethers';
+import { WalletClient } from 'viem';
 
 /**
  * Agether SDK Types
@@ -186,10 +187,20 @@ declare class AgetherClient {
  *   - supplyCollateral:  [ERC20.approve, Morpho.supplyCollateral]
  *
  * Market discovery via Morpho GraphQL API (https://api.morpho.org/graphql)
+ *
+ * Supports two signing modes:
+ *   - `privateKey`: SDK manages wallet lifecycle (existing behavior)
+ *   - `signer`: external signer (Bankr, Privy, Turnkey, MetaMask, etc.)
  */
 
-interface MorphoClientConfig {
-    privateKey: string;
+/**
+ * Convenience type alias for any ethers-compatible signer.
+ * Use this when declaring variables or parameters that accept
+ * ethers.Wallet, Privy signer, Bankr signer, Turnkey signer, etc.
+ */
+type AgetherSigner = ethers.AbstractSigner;
+/** Base configuration fields shared by both signing modes. */
+interface MorphoClientBaseConfig {
     rpcUrl: string;
     agentId?: string;
     chainId?: ChainId;
@@ -201,6 +212,44 @@ interface MorphoClientConfig {
         identityRegistry: string;
     }>;
 }
+/**
+ * MorphoClient configuration.
+ *
+ * Provide **either** `privateKey` (SDK manages wallet) **or** `signer`
+ * (external custody provider). The two fields are mutually exclusive.
+ *
+ * @example
+ * ```ts
+ * // Private key (existing behavior — fully backward compatible):
+ * new MorphoClient({ privateKey: '0x...', rpcUrl, agentId: '42' })
+ *
+ * // External signer (Bankr, Privy, Turnkey, MetaMask, etc.):
+ * new MorphoClient({ signer: privySigner, rpcUrl, agentId: '42' })
+ * ```
+ */
+type MorphoClientConfig = MorphoClientBaseConfig & ({
+    /** Raw private key hex string. SDK creates an ethers.Wallet internally. */
+    privateKey: string;
+    signer?: never;
+} | {
+    /**
+     * Any `ethers.AbstractSigner` instance for transaction signing.
+     *
+     * Accepts:
+     * - `ethers.Wallet` (local key)
+     * - Privy embedded wallet signer
+     * - Bankr custodial signer
+     * - Turnkey / MPC wallet signer
+     * - Hardware wallet adapter (Ledger, Trezor)
+     * - MetaMask `BrowserProvider.getSigner()`
+     * - Any object implementing `ethers.AbstractSigner`
+     *
+     * The signer is treated as **immutable** by the SDK — it will never be
+     * recreated or reconnected. Nonce management is the caller's responsibility.
+     */
+    signer: ethers.AbstractSigner;
+    privateKey?: never;
+});
 interface BalancesResult {
     agentId: string;
     address: string;
@@ -219,6 +268,8 @@ interface RegisterResult {
     address: string;
     agentAccount: string;
     alreadyRegistered: boolean;
+    /** Whether the KYA (code verification) gate is active on this factory */
+    kyaRequired: boolean;
     tx?: string;
 }
 interface PositionResult {
@@ -272,12 +323,14 @@ interface FundResult {
     agentAccount: string;
 }
 declare class MorphoClient {
-    private wallet;
+    private _signer;
     private provider;
     private config;
     private agentId;
     private _rpcUrl;
-    private _privateKey;
+    private _privateKey?;
+    private _useExternalSigner;
+    private _eoaAddress?;
     private accountFactory;
     private morphoBlue;
     private agentReputation;
@@ -287,10 +340,28 @@ declare class MorphoClient {
     private _discoveredMarkets?;
     private _discoveredAt;
     constructor(config: MorphoClientConfig);
+    /**
+     * Check whether the KYA (Know Your Agent) code verification gate is active.
+     * When validationRegistry is address(0), KYA is disabled — agents can use
+     * execute/executeBatch without prior code approval.
+     */
+    isKyaRequired(): Promise<boolean>;
     /** Resolve the AgentAccount address (cached). */
     getAccountAddress(): Promise<string>;
     getAgentId(): string;
+    /**
+     * Get the EOA wallet address (synchronous, best-effort).
+     *
+     * For the `privateKey` path this always works. For the `signer` path
+     * it works if the signer exposes `.address` synchronously (e.g. ethers.Wallet).
+     * If the address has not been resolved yet, throws — call `getSignerAddress()` first.
+     */
     getWalletAddress(): string;
+    /**
+     * Resolve the EOA signer address (async, works with all signer types).
+     * Result is cached after the first call.
+     */
+    getSignerAddress(): Promise<string>;
     /** Mint a new ERC-8004 identity and return the agentId. */
     private _mintNewIdentity;
     /**
@@ -450,9 +521,17 @@ declare class MorphoClient {
         age: bigint;
     }>;
     /**
-     * Recreate provider + wallet so the next tx fetches a fresh nonce from chain.
-     * Anvil (and some RPC providers) return a stale `eth_getTransactionCount`
-     * right after a block is mined, causing "nonce too low" on the follow-up tx.
+     * Refresh the signer and re-bind contract instances.
+     *
+     * For the **privateKey** path: recreates provider + wallet so the next tx
+     * fetches a fresh nonce from chain. Anvil (and some RPC providers) return a
+     * stale `eth_getTransactionCount` right after a block is mined, causing
+     * "nonce too low" on the follow-up tx.
+     *
+     * For the **external signer** path: the signer is immutable and owned by the
+     * caller (e.g. custody provider). We only re-bind contract instances to
+     * ensure they reference the current signer. Nonce management is the caller's
+     * responsibility.
      */
     private _refreshSigner;
     /**
@@ -491,8 +570,15 @@ declare class MorphoClient {
  *
  * Chain support: Base (8453), Base Sepolia (84532), Ethereum (1).
  */
-interface X402Config {
-    privateKey: string;
+
+/**
+ * Convenience type alias for any viem-compatible WalletClient.
+ * Use this when declaring variables or parameters that accept
+ * viem WalletClient instances from Privy, Turnkey, MetaMask, etc.
+ */
+type AgetherViemWallet = WalletClient;
+/** Base configuration fields shared by both signing modes. */
+interface X402BaseConfig {
     rpcUrl: string;
     backendUrl: string;
     agentId?: string;
@@ -519,6 +605,29 @@ interface X402Config {
      */
     autoDrawBuffer?: string;
 }
+/** Config with SDK-managed private key (existing behavior). */
+interface X402PrivateKeyConfig extends X402BaseConfig {
+    /** Raw hex private key (with or without '0x' prefix). SDK creates the wallet internally. */
+    privateKey: string;
+    walletClient?: never;
+}
+/** Config with caller-provided viem WalletClient (custody-agnostic). */
+interface X402WalletClientConfig extends X402BaseConfig {
+    /**
+     * A viem WalletClient with an attached account (e.g. from Privy, Turnkey, MetaMask).
+     * The client **must** have an `account` property set. The SDK will use it for
+     * EIP-712 typed-data signing and will never recreate or reconnect the client.
+     */
+    walletClient: WalletClient;
+    privateKey?: never;
+}
+/**
+ * X402Client configuration.
+ *
+ * Provide **either** `privateKey` (SDK manages wallet) **or** `walletClient`
+ * (external custody provider). The two fields are mutually exclusive.
+ */
+type X402Config = X402PrivateKeyConfig | X402WalletClientConfig;
 interface X402Response<T = unknown> {
     success: boolean;
     data?: T;
@@ -954,4 +1063,4 @@ declare function getDefaultConfig(chainId: ChainId): AgetherConfig;
  */
 declare function createConfig(chainId: ChainId, options?: Partial<AgetherConfig>): AgetherConfig;
 
-export { ACCOUNT_FACTORY_ABI, AGENT_ACCOUNT_ABI, AGENT_REPUTATION_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ERC20_ABI, type FundResult, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getDefaultConfig, parseUnits, rateToBps };
+export { ACCOUNT_FACTORY_ABI, AGENT_ACCOUNT_ABI, AGENT_REPUTATION_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ERC20_ABI, type FundResult, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getDefaultConfig, parseUnits, rateToBps };