@barzkit/sdk 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project 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).
 
+## [0.1.4] - 2026-03-01
+
+### Added
+
+- x402 payment protocol support: machine-to-machine HTTP 402 payments
+- `enableX402()` method on `BarzAgent` — configure payment limits and domain whitelist
+- `fetchWithPayment()` method on `BarzAgent` — auto-pay 402 responses and retry with proof
+- `X402Config` and `X402PaymentRequest` interfaces
+- `X402Manager` — per-request and daily spend limit enforcement with 24h rolling window
+- `parsePaymentRequired()` — parse 402 response headers into structured payment request
+- `validateDomain()` — domain whitelist check for payment endpoints
+- `buildPaymentTransaction()` — build ERC-20 transfer for x402 payment
+- `X402Error` error class
+- Unit tests for x402 parsing, validation, manager, and fetch flow
+
+## [0.1.3] - 2026-03-01
+
+### Added
+
+- `swap()` method on `BarzAgent` — swap tokens via Uniswap V3 (Sepolia)
+- `lend()` method on `BarzAgent` — supply tokens to Aave V3 (Sepolia)
+- `SwapParams` and `LendParams` interfaces
+- `src/actions/tokens.ts` — `resolveToken()`, `getTokenDecimals()`, `isNativeETH()`, `ETH_SENTINEL`
+- `src/actions/swap.ts` — `buildSwapTransactions()`, `getSwapTokenAddresses()`, `UNISWAP_V3_ROUTER`
+- `src/actions/lend.ts` — `buildLendTransactions()`, `getLendTokenAddresses()`, `AAVE_V3_POOL`
+- Token permission validation for DeFi actions (`allowedTokens` check)
+- Unit tests for tokens, swap, and lend calldata builders
+- `defi-agent` example
+- DeFi actions guide (`docs/guides/defi-actions.md`)
+
+### Changed
+
+- Extracted `executeBatch()` helper in `account.ts` (reused by `batchTransactions`, `swap`, `lend`)
+
 ## [0.1.2] - 2026-03-01
 
 ### Added
@@ -67,6 +101,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `AgentEvent` type definitions for future event hooks
 - Dual-package build: ESM (`.mjs`) + CJS (`.js`) + DTS (`.d.ts`)
 
+[0.1.4]: https://github.com/barzkit/sdk/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/barzkit/sdk/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/barzkit/sdk/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/barzkit/sdk/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/barzkit/sdk/releases/tag/v0.1.0

package/README.md

@@ -156,11 +156,11 @@ See [examples](https://github.com/barzkit/examples) for complete working example
 
 - [x] Core SDK: createWallet, sendTransaction, permissions, freeze
 - [x] Batch transactions: atomic multi-call in one UserOperation
-- [ ] Multi-chain: Base Sepolia, Base mainnet
-- [ ] DeFi actions: swap, lend (Uniswap, Aave)
+- [x] Multi-chain: Base Sepolia, Base mainnet
+- [x] DeFi actions: swap, lend (Uniswap, Aave)
+- [x] x402 payment handler
 - [ ] ElizaOS plugin
 - [ ] LangChain tool
-- [ ] x402 payment handler
 - [ ] On-chain permission enforcement via Diamond Facets
 
 ## Contributing
@@ -173,4 +173,4 @@ MIT
 
 ---
 
-[Documentation](https://github.com/barzkit/sdk) · [Examples](https://github.com/barzkit/examples) · [Trust Wallet Barz](https://github.com/trustwallet/barz)
+[Documentation](https://github.com/barzkit/docs) · [Examples](https://github.com/barzkit/examples) · [Trust Wallet Barz](https://github.com/trustwallet/barz)

package/dist/index.cjs

@@ -88,6 +88,12 @@ var TransactionError = class extends BarzKitError {
     this.txHash = txHash;
   }
 };
+var X402Error = class extends BarzKitError {
+  constructor(message) {
+    super(message, "X402_ERROR");
+    this.name = "X402Error";
+  }
+};
 var BundlerError = class extends BarzKitError {
   constructor(message) {
     super(message, "BUNDLER_ERROR");
@@ -318,6 +324,362 @@ var ERC20_ABI = [
     type: "function"
   }
 ];
+var ETH_SENTINEL = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+var TOKEN_DECIMALS = {
+  ETH: 18,
+  WETH: 18,
+  USDC: 6,
+  USDT: 6,
+  DAI: 18,
+  USDbC: 6
+};
+function resolveToken(symbolOrAddress, chain) {
+  if (symbolOrAddress.startsWith("0x")) {
+    return viem.getAddress(symbolOrAddress);
+  }
+  const symbol = symbolOrAddress.toUpperCase();
+  if (symbol === "ETH") {
+    return ETH_SENTINEL;
+  }
+  const chainTokens = TOKENS[chain];
+  if (!chainTokens) {
+    throw new BarzKitError(
+      `No tokens configured for chain "${chain}".`,
+      "UNSUPPORTED_CHAIN"
+    );
+  }
+  const address = chainTokens[symbol];
+  if (!address) {
+    throw new BarzKitError(
+      `Unknown token "${symbolOrAddress}" on ${chain}. Available: ${Object.keys(chainTokens).join(", ")}`,
+      "UNKNOWN_TOKEN"
+    );
+  }
+  return address;
+}
+function getTokenDecimals(symbol) {
+  return TOKEN_DECIMALS[symbol.toUpperCase()] ?? null;
+}
+function isNativeETH(token) {
+  if (token.toUpperCase() === "ETH") return true;
+  if (token.startsWith("0x")) {
+    return token.toLowerCase() === ETH_SENTINEL.toLowerCase();
+  }
+  return false;
+}
+
+// src/actions/swap.ts
+var UNISWAP_V3_ROUTER = {
+  sepolia: "0x3bFA4769FB09eefC5a80d6E87c3B9C650f7Ae48E"
+};
+var SWAP_ROUTER_ABI = [
+  {
+    inputs: [
+      {
+        components: [
+          { name: "tokenIn", type: "address" },
+          { name: "tokenOut", type: "address" },
+          { name: "fee", type: "uint24" },
+          { name: "recipient", type: "address" },
+          { name: "amountIn", type: "uint256" },
+          { name: "amountOutMinimum", type: "uint256" },
+          { name: "sqrtPriceLimitX96", type: "uint160" }
+        ],
+        name: "params",
+        type: "tuple"
+      }
+    ],
+    name: "exactInputSingle",
+    outputs: [{ name: "amountOut", type: "uint256" }],
+    stateMutability: "payable",
+    type: "function"
+  }
+];
+function buildSwapTransactions(params, chain, account) {
+  const router = UNISWAP_V3_ROUTER[chain];
+  if (!router) {
+    throw new BarzKitError(
+      `Uniswap V3 is not available on "${chain}". Supported: ${Object.keys(UNISWAP_V3_ROUTER).join(", ")}`,
+      "UNSUPPORTED_CHAIN"
+    );
+  }
+  const tokenIn = resolveToken(params.from, chain);
+  const tokenOut = resolveToken(params.to, chain);
+  if (tokenIn.toLowerCase() === tokenOut.toLowerCase()) {
+    throw new BarzKitError(
+      `Cannot swap a token to itself ("${params.from}" \u2192 "${params.to}").`,
+      "INVALID_SWAP"
+    );
+  }
+  const fromIsETH = isNativeETH(params.from);
+  const fromSymbol = params.from.startsWith("0x") ? null : params.from;
+  const decimals = fromSymbol ? getTokenDecimals(fromSymbol) ?? 18 : 18;
+  const amountIn = viem.parseUnits(params.amount, decimals);
+  const routerTokenIn = fromIsETH ? resolveToken("WETH", chain) : tokenIn;
+  const routerTokenOut = isNativeETH(params.to) ? resolveToken("WETH", chain) : tokenOut;
+  const fee = params.fee ?? 3e3;
+  const amountOutMinimum = 0n;
+  const swapData = viem.encodeFunctionData({
+    abi: SWAP_ROUTER_ABI,
+    functionName: "exactInputSingle",
+    args: [
+      {
+        tokenIn: routerTokenIn,
+        tokenOut: routerTokenOut,
+        fee,
+        recipient: account,
+        amountIn,
+        amountOutMinimum,
+        sqrtPriceLimitX96: 0n
+      }
+    ]
+  });
+  const txs = [];
+  if (fromIsETH) {
+    txs.push({
+      to: router,
+      value: amountIn,
+      data: swapData
+    });
+  } else {
+    const approveData = viem.encodeFunctionData({
+      abi: ERC20_ABI,
+      functionName: "approve",
+      args: [router, amountIn]
+    });
+    txs.push({
+      to: tokenIn,
+      data: approveData
+    });
+    txs.push({
+      to: router,
+      data: swapData
+    });
+  }
+  return txs;
+}
+function getSwapTokenAddresses(params, chain) {
+  const addresses = [];
+  const tokenIn = resolveToken(params.from, chain);
+  const tokenOut = resolveToken(params.to, chain);
+  if (tokenIn !== ETH_SENTINEL) addresses.push(tokenIn);
+  if (tokenOut !== ETH_SENTINEL) addresses.push(tokenOut);
+  return addresses;
+}
+var AAVE_V3_POOL = {
+  sepolia: "0x6Ae43d3271ff6888e7Fc43Fd7321a503ff738951"
+};
+var AAVE_POOL_ABI = [
+  {
+    inputs: [
+      { name: "asset", type: "address" },
+      { name: "amount", type: "uint256" },
+      { name: "onBehalfOf", type: "address" },
+      { name: "referralCode", type: "uint16" }
+    ],
+    name: "supply",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  }
+];
+function buildLendTransactions(params, chain, account) {
+  if (params.protocol !== "aave") {
+    throw new BarzKitError(
+      `Unknown lending protocol "${params.protocol}". Supported: aave`,
+      "UNKNOWN_PROTOCOL"
+    );
+  }
+  const pool = AAVE_V3_POOL[chain];
+  if (!pool) {
+    throw new BarzKitError(
+      `Aave V3 is not available on "${chain}". Supported: ${Object.keys(AAVE_V3_POOL).join(", ")}`,
+      "UNSUPPORTED_CHAIN"
+    );
+  }
+  if (isNativeETH(params.token)) {
+    throw new BarzKitError(
+      "Cannot supply native ETH to Aave. Wrap to WETH first, then supply WETH.",
+      "NATIVE_ETH_NOT_SUPPORTED"
+    );
+  }
+  const tokenAddress = resolveToken(params.token, chain);
+  const tokenSymbol = params.token.startsWith("0x") ? null : params.token;
+  const decimals = tokenSymbol ? getTokenDecimals(tokenSymbol) ?? 18 : 18;
+  const amount = viem.parseUnits(params.amount, decimals);
+  const approveData = viem.encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: "approve",
+    args: [pool, amount]
+  });
+  const supplyData = viem.encodeFunctionData({
+    abi: AAVE_POOL_ABI,
+    functionName: "supply",
+    args: [tokenAddress, amount, account, 0]
+  });
+  return [
+    {
+      to: tokenAddress,
+      data: approveData
+    },
+    {
+      to: pool,
+      data: supplyData
+    }
+  ];
+}
+function getLendTokenAddresses(params, chain) {
+  const tokenAddress = resolveToken(params.token, chain);
+  return [tokenAddress];
+}
+var HEADER_AMOUNT = "x-payment-amount";
+var HEADER_ADDRESS = "x-payment-address";
+var HEADER_TOKEN = "x-payment-token";
+var HEADER_NETWORK = "x-payment-network";
+var HEADER_PROOF = "X-Payment-Proof";
+function parsePaymentRequired(response) {
+  const amount = response.headers.get(HEADER_AMOUNT);
+  const address = response.headers.get(HEADER_ADDRESS);
+  const token = response.headers.get(HEADER_TOKEN);
+  const network = response.headers.get(HEADER_NETWORK);
+  if (!amount || !address || !token || !network) {
+    const missing = [
+      !amount && "X-Payment-Amount",
+      !address && "X-Payment-Address",
+      !token && "X-Payment-Token",
+      !network && "X-Payment-Network"
+    ].filter(Boolean);
+    throw new X402Error(`402 response missing required headers: ${missing.join(", ")}`);
+  }
+  const parsed = BigInt(amount);
+  if (parsed <= 0n) {
+    throw new X402Error(`Invalid payment amount: ${amount}`);
+  }
+  return {
+    amount: parsed,
+    address,
+    token,
+    network
+  };
+}
+function validateDomain(url, allowedDomains) {
+  if (!allowedDomains || allowedDomains.length === 0) return;
+  const hostname = new URL(url).hostname;
+  if (!allowedDomains.includes(hostname)) {
+    throw new X402Error(
+      `Domain "${hostname}" is not in the allowed list. Allowed: ${allowedDomains.join(", ")}`
+    );
+  }
+}
+var X402Manager = class {
+  _config = null;
+  _dailySpent = 0n;
+  _windowStart = 0;
+  get enabled() {
+    return this._config !== null;
+  }
+  get config() {
+    return this._config;
+  }
+  get dailySpent() {
+    this.resetIfExpired();
+    return this._dailySpent;
+  }
+  enable(config) {
+    this._config = config;
+    this._dailySpent = 0n;
+    this._windowStart = Date.now();
+  }
+  validatePayment(amount) {
+    if (!this._config) throw new X402Error("x402 not enabled");
+    this.resetIfExpired();
+    const maxPerRequest = parseHumanAmountToAtomic(this._config.maxPaymentPerRequest);
+    if (amount > maxPerRequest) {
+      throw new PermissionError(
+        `Payment amount ${amount} exceeds per-request limit of ${maxPerRequest} (${this._config.maxPaymentPerRequest})`
+      );
+    }
+    const maxDaily = parseHumanAmountToAtomic(this._config.maxDailyPayments);
+    if (this._dailySpent + amount > maxDaily) {
+      throw new PermissionError(
+        `Payment would exceed daily limit of ${maxDaily} (${this._config.maxDailyPayments}). Already spent: ${this._dailySpent}`
+      );
+    }
+  }
+  recordPayment(amount) {
+    this.resetIfExpired();
+    this._dailySpent += amount;
+  }
+  resetIfExpired() {
+    const now = Date.now();
+    const elapsed = now - this._windowStart;
+    const DAY_MS = 24 * 60 * 60 * 1e3;
+    if (elapsed >= DAY_MS) {
+      this._dailySpent = 0n;
+      this._windowStart = now;
+    }
+  }
+};
+function buildPaymentTransaction(payment) {
+  const data = viem.encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: "transfer",
+    args: [payment.address, payment.amount]
+  });
+  return {
+    to: payment.token,
+    data
+  };
+}
+function createFetchWithPayment(manager, sendTransaction) {
+  return async function fetchWithPayment(url, options) {
+    if (!manager.enabled) {
+      throw new X402Error("x402 not enabled. Call agent.enableX402() first.");
+    }
+    const config = manager.config;
+    validateDomain(url, config.allowedDomains);
+    const response = await fetch(url, options);
+    if (response.status !== 402) {
+      return response;
+    }
+    const payment = parsePaymentRequired(response);
+    manager.validatePayment(payment.amount);
+    const txHash = await sendTransaction(buildPaymentTransaction(payment));
+    manager.recordPayment(payment.amount);
+    return fetch(url, {
+      ...options,
+      headers: {
+        ...options?.headers,
+        [HEADER_PROOF]: txHash
+      }
+    });
+  };
+}
+function parseHumanAmountToAtomic(input) {
+  const parts = input.trim().split(/\s+/);
+  if (parts.length !== 2) {
+    throw new X402Error(`Invalid amount format: "${input}". Expected "0.01 USDC".`);
+  }
+  const [numStr, unit] = parts;
+  const upper = unit.toUpperCase();
+  let decimals;
+  switch (upper) {
+    case "USDC":
+    case "USDT":
+      decimals = 6;
+      break;
+    case "DAI":
+    case "ETH":
+    case "WETH":
+      decimals = 18;
+      break;
+    default:
+      throw new X402Error(`Unknown token unit in amount: "${unit}"`);
+  }
+  const [whole, frac = ""] = numStr.split(".");
+  const padded = frac.padEnd(decimals, "0").slice(0, decimals);
+  return BigInt(whole + padded);
+}
 
 // src/core/account.ts
 async function createBarzAgent(config) {
@@ -353,7 +715,30 @@ async function createBarzAgent(config) {
     console.warn("\u26A0\uFE0F Using Base mainnet \u2014 real funds at risk");
   }
   const permissionManager = new PermissionManager(config.permissions);
+  const x402Manager = new X402Manager();
   let frozen = false;
+  async function executeBatch(txs) {
+    for (const tx of txs) {
+      permissionManager.validate(tx);
+    }
+    try {
+      const userOpHash = await smartAccountClient.sendUserOperation({
+        calls: txs.map((tx) => ({
+          to: tx.to,
+          value: tx.value ?? 0n,
+          data: tx.data ?? "0x"
+        }))
+      });
+      const receipt = await smartAccountClient.waitForUserOperationReceipt({
+        hash: userOpHash
+      });
+      const totalValue = txs.reduce((sum, tx) => sum + (tx.value ?? 0n), 0n);
+      if (totalValue > 0n) permissionManager.recordSpend(totalValue);
+      return receipt.receipt.transactionHash;
+    } catch (error) {
+      throw humanizeError(error);
+    }
+  }
   const agent = {
     address: smartAccount.address,
     chain: config.chain,
@@ -381,26 +766,7 @@ async function createBarzAgent(config) {
           "BATCH_EMPTY"
         );
       }
-      for (const tx of txs) {
-        permissionManager.validate(tx);
-      }
-      try {
-        const userOpHash = await smartAccountClient.sendUserOperation({
-          calls: txs.map((tx) => ({
-            to: tx.to,
-            value: tx.value ?? 0n,
-            data: tx.data ?? "0x"
-          }))
-        });
-        const receipt = await smartAccountClient.waitForUserOperationReceipt({
-          hash: userOpHash
-        });
-        const totalValue = txs.reduce((sum, tx) => sum + (tx.value ?? 0n), 0n);
-        if (totalValue > 0n) permissionManager.recordSpend(totalValue);
-        return receipt.receipt.transactionHash;
-      } catch (error) {
-        throw humanizeError(error);
-      }
+      return executeBatch(txs);
     },
     async getBalance(token) {
       try {
@@ -434,6 +800,24 @@ async function createBarzAgent(config) {
         );
       }
     },
+    async swap(params) {
+      if (frozen) throw new FrozenError();
+      const tokenAddresses = getSwapTokenAddresses(params, config.chain);
+      validateTokenPermissions(tokenAddresses, permissionManager.permissions);
+      const txs = buildSwapTransactions(params, config.chain, smartAccount.address);
+      return executeBatch(txs);
+    },
+    async lend(params) {
+      if (frozen) throw new FrozenError();
+      const tokenAddresses = getLendTokenAddresses(params, config.chain);
+      validateTokenPermissions(tokenAddresses, permissionManager.permissions);
+      const txs = buildLendTransactions(params, config.chain, smartAccount.address);
+      return executeBatch(txs);
+    },
+    enableX402(x402Config) {
+      x402Manager.enable(x402Config);
+    },
+    fetchWithPayment: null,
     getExplorerUrl(hash) {
       return `${chainConfig.explorerUrl}/tx/${hash}`;
     },
@@ -455,6 +839,10 @@ async function createBarzAgent(config) {
       return !frozen;
     }
   };
+  agent.fetchWithPayment = createFetchWithPayment(
+    x402Manager,
+    (tx) => agent.sendTransaction(tx)
+  );
   return agent;
 }
 function validateConfig(config) {
@@ -474,17 +862,44 @@ function validateConfig(config) {
     throw new ConfigError('Missing "pimlico.apiKey". Get a free key at https://dashboard.pimlico.io');
   }
 }
+function validateTokenPermissions(tokenAddresses, permissions) {
+  if (!permissions.allowedTokens || permissions.allowedTokens.length === 0) return;
+  const allowed = permissions.allowedTokens.map((a) => a.toLowerCase());
+  for (const token of tokenAddresses) {
+    if (!allowed.includes(token.toLowerCase())) {
+      throw new PermissionError(
+        `Token ${token} is not in the allowed list. Allowed: ${permissions.allowedTokens.join(", ")}`
+      );
+    }
+  }
+}
 
+exports.AAVE_V3_POOL = AAVE_V3_POOL;
 exports.BarzKitError = BarzKitError;
 exports.BundlerError = BundlerError;
 exports.CHAIN_CONFIGS = CHAIN_CONFIGS;
 exports.ConfigError = ConfigError;
 exports.ERC20_ABI = ERC20_ABI;
+exports.ETH_SENTINEL = ETH_SENTINEL;
 exports.FrozenError = FrozenError;
 exports.PermissionError = PermissionError;
 exports.TOKENS = TOKENS;
 exports.TransactionError = TransactionError;
+exports.UNISWAP_V3_ROUTER = UNISWAP_V3_ROUTER;
+exports.X402Error = X402Error;
+exports.X402Manager = X402Manager;
+exports.buildLendTransactions = buildLendTransactions;
+exports.buildPaymentTransaction = buildPaymentTransaction;
+exports.buildSwapTransactions = buildSwapTransactions;
 exports.createBarzAgent = createBarzAgent;
+exports.createFetchWithPayment = createFetchWithPayment;
 exports.getChainConfig = getChainConfig;
+exports.getLendTokenAddresses = getLendTokenAddresses;
+exports.getSwapTokenAddresses = getSwapTokenAddresses;
+exports.getTokenDecimals = getTokenDecimals;
+exports.isNativeETH = isNativeETH;
+exports.parsePaymentRequired = parsePaymentRequired;
+exports.resolveToken = resolveToken;
+exports.validateDomain = validateDomain;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map