@coinbase/cdp-sdk 1.11.0 → 1.13.0

package/actions/evm/swap/createSwapQuote.ts

@@ -0,0 +1,148 @@
+import { sendSwapTransaction } from "./sendSwapTransaction.js";
+import {
+  CreateSwapQuoteOptions,
+  CreateSwapQuoteResult,
+  ExecuteSwapQuoteOptions,
+  ExecuteSwapQuoteResult,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import {
+  CdpOpenApiClientType,
+  CreateSwapQuoteResponse,
+  type SendEvmTransactionBodyNetwork,
+} from "../../../openapi-client/index.js";
+import { Address, Hex } from "../../../types/misc.js";
+
+/**
+ * Creates a quote for a swap between two tokens on an EVM network.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use to create the swap quote.
+ * @param {CreateSwapQuoteOptions} options - The options for creating a swap quote.
+ *
+ * @returns {Promise<CreateSwapQuoteResult | SwapUnavailableResult>} A promise that resolves to the swap quote result or a response indicating that liquidity is unavailable.
+ *
+ * @example **Creating a swap quote**
+ * ```ts
+ * const swapQuote = await createSwapQuote(client, {
+ *   network: "ethereum",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: "0x1234567890123456789012345678901234567890"
+ * });
+ * ```
+ */
+export async function createSwapQuote(
+  client: CdpOpenApiClientType,
+  options: CreateSwapQuoteOptions,
+): Promise<CreateSwapQuoteResult | SwapUnavailableResult> {
+  // Validate required parameters
+  if (!options.taker) {
+    throw new Error("taker is required for createSwapQuote");
+  }
+
+  // Store validated taker for type safety
+  const taker = options.taker as Address;
+
+  // Call the createEvmSwapQuote function directly with the client's configured API
+  const response = await client.createEvmSwapQuote({
+    network: options.network,
+    toToken: options.toToken,
+    fromToken: options.fromToken,
+    fromAmount: options.fromAmount.toString(),
+    taker: taker,
+    signerAddress: options.signerAddress,
+    gasPrice: options.gasPrice?.toString(),
+    slippageBps: options.slippageBps,
+  });
+
+  // Check if liquidity is unavailable
+  if (!response.liquidityAvailable) {
+    // Return the SwapUnavailableResult
+    return {
+      liquidityAvailable: false,
+    };
+  }
+
+  // At this point we know it's a CreateSwapQuoteResponse with liquidityAvailable as true
+  const swapResponse = response as CreateSwapQuoteResponse;
+  const result: CreateSwapQuoteResult = {
+    liquidityAvailable: true,
+    network: options.network,
+    toToken: swapResponse.toToken as Address,
+    fromToken: swapResponse.fromToken as Address,
+    fromAmount: BigInt(swapResponse.fromAmount),
+    toAmount: BigInt(swapResponse.toAmount),
+    minToAmount: BigInt(swapResponse.minToAmount),
+    blockNumber: BigInt(swapResponse.blockNumber),
+    fees: {
+      gasFee: swapResponse.fees.gasFee
+        ? {
+            amount: BigInt(swapResponse.fees.gasFee.amount),
+            token: swapResponse.fees.gasFee.token as Address,
+          }
+        : undefined,
+      protocolFee: swapResponse.fees.protocolFee
+        ? {
+            amount: BigInt(swapResponse.fees.protocolFee.amount),
+            token: swapResponse.fees.protocolFee.token as Address,
+          }
+        : undefined,
+    },
+    issues: {
+      allowance: swapResponse.issues.allowance
+        ? {
+            currentAllowance: BigInt(swapResponse.issues.allowance.currentAllowance),
+            spender: swapResponse.issues.allowance.spender as Address,
+          }
+        : undefined,
+      balance: swapResponse.issues.balance
+        ? {
+            token: swapResponse.issues.balance.token as Address,
+            currentBalance: BigInt(swapResponse.issues.balance.currentBalance),
+            requiredBalance: BigInt(swapResponse.issues.balance.requiredBalance),
+          }
+        : undefined,
+      simulationIncomplete: swapResponse.issues.simulationIncomplete,
+    },
+    transaction: swapResponse.transaction
+      ? {
+          to: swapResponse.transaction.to as Address,
+          data: swapResponse.transaction.data as Hex,
+          value: BigInt(swapResponse.transaction.value),
+          gas: BigInt(swapResponse.transaction.gas),
+          gasPrice: BigInt(swapResponse.transaction.gasPrice),
+        }
+      : undefined,
+    permit2: swapResponse.permit2
+      ? {
+          eip712: {
+            domain: {
+              ...swapResponse.permit2.eip712.domain,
+              verifyingContract: swapResponse.permit2.eip712.domain.verifyingContract as
+                | Address
+                | undefined,
+              salt: swapResponse.permit2.eip712.domain.salt as Hex | undefined,
+            },
+            types: swapResponse.permit2.eip712.types,
+            primaryType: swapResponse.permit2.eip712.primaryType,
+            message: swapResponse.permit2.eip712.message,
+          },
+        }
+      : undefined,
+    // Add the execute method
+    execute: async (
+      executeOptions: ExecuteSwapQuoteOptions = {},
+    ): Promise<ExecuteSwapQuoteResult> => {
+      const { transactionHash } = await sendSwapTransaction(client, {
+        address: options.signerAddress || taker, // Use signerAddress for smart accounts, taker for EOAs
+        network: result.network as SendEvmTransactionBodyNetwork,
+        swapQuote: result,
+        idempotencyKey: executeOptions.idempotencyKey,
+      });
+      return { transactionHash };
+    },
+  };
+
+  return result;
+}

package/actions/evm/swap/getSwapPrice.ts

@@ -0,0 +1,95 @@
+import {
+  GetSwapPriceOptions,
+  GetSwapPriceResult,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import { CdpOpenApiClientType, GetSwapPriceResponse } from "../../../openapi-client/index.js";
+import { Address } from "../../../types/misc.js";
+
+/**
+ * Gets the price for a swap between two tokens on an EVM network.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use to get the swap price.
+ * @param {GetSwapPriceOptions} options - The options for getting a swap price.
+ *
+ * @returns {Promise<GetSwapPriceResult | SwapUnavailableResult>} A promise that resolves to the swap price result or a response indicating that liquidity is unavailable.
+ *
+ * @example **Getting a swap price**
+ * ```ts
+ * const price = await getSwapPrice(client, {
+ *   network: "ethereum-mainnet",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: "0x1234567890123456789012345678901234567890"
+ * });
+ * ```
+ */
+export async function getSwapPrice(
+  client: CdpOpenApiClientType,
+  options: GetSwapPriceOptions,
+): Promise<GetSwapPriceResult | SwapUnavailableResult> {
+  // Call the getEvmSwapPrice function directly with the client's configured API
+  const response = await client.getEvmSwapPrice({
+    network: options.network,
+    toToken: options.toToken,
+    fromToken: options.fromToken,
+    fromAmount: options.fromAmount.toString(),
+    taker: options.taker,
+    signerAddress: options.signerAddress,
+    gasPrice: options.gasPrice?.toString(),
+    slippageBps: options.slippageBps,
+  });
+
+  // Check if liquidity is unavailable
+  if (!response.liquidityAvailable) {
+    // Return the SwapUnavailableResult
+    return {
+      liquidityAvailable: false,
+    };
+  }
+
+  // At this point we know it's a GetSwapPriceResponse with liquidityAvailable as true
+  const quoteResponse = response as GetSwapPriceResponse;
+  return {
+    blockNumber: BigInt(quoteResponse.blockNumber),
+    toAmount: BigInt(quoteResponse.toAmount),
+    toToken: quoteResponse.toToken as Address,
+    fees: {
+      gasFee: quoteResponse.fees.gasFee
+        ? {
+            amount: BigInt(quoteResponse.fees.gasFee.amount),
+            token: quoteResponse.fees.gasFee.token as Address,
+          }
+        : undefined,
+      protocolFee: quoteResponse.fees.protocolFee
+        ? {
+            amount: BigInt(quoteResponse.fees.protocolFee.amount),
+            token: quoteResponse.fees.protocolFee.token as Address,
+          }
+        : undefined,
+    },
+    issues: {
+      allowance: quoteResponse.issues.allowance
+        ? {
+            currentAllowance: BigInt(quoteResponse.issues.allowance.currentAllowance),
+            spender: quoteResponse.issues.allowance.spender as Address,
+          }
+        : undefined,
+      balance: quoteResponse.issues.balance
+        ? {
+            token: quoteResponse.issues.balance.token as Address,
+            currentBalance: BigInt(quoteResponse.issues.balance.currentBalance),
+            requiredBalance: BigInt(quoteResponse.issues.balance.requiredBalance),
+          }
+        : undefined,
+      simulationIncomplete: quoteResponse.issues.simulationIncomplete,
+    },
+    liquidityAvailable: true,
+    minToAmount: BigInt(quoteResponse.minToAmount),
+    fromAmount: BigInt(quoteResponse.fromAmount),
+    fromToken: quoteResponse.fromToken as Address,
+    gas: quoteResponse.gas ? BigInt(quoteResponse.gas) : undefined,
+    gasPrice: quoteResponse.gasPrice ? BigInt(quoteResponse.gasPrice) : undefined,
+  };
+}

package/actions/evm/swap/sendSwapTransaction.ts

@@ -0,0 +1,173 @@
+import { concat, numberToHex, size } from "viem";
+
+import { createSwapQuote } from "./createSwapQuote.js";
+import { sendTransaction } from "../sendTransaction.js";
+
+import type { SendSwapTransactionOptions, SendSwapTransactionResult } from "./types.js";
+import type {
+  CreateSwapQuoteResult,
+  CreateSwapQuoteOptions,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import type {
+  CdpOpenApiClientType,
+  SendEvmTransactionBodyNetwork,
+} from "../../../openapi-client/index.js";
+import type { Hex } from "../../../types/misc.js";
+import type { TransactionRequestEIP1559 } from "viem";
+
+/**
+ * Sends a swap transaction to the blockchain.
+ * Handles any permit2 signatures required for the swap.
+ *
+ * If you encounter token allowance issues, you'll need to perform a token approval transaction first to allow
+ * the Permit2 contract to spend the appropriate amount of your fromToken.
+ * See `examples/typescript/evm/account.sendSwapTransaction.ts` for example code on handling token approvals.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use for sending the swap.
+ * @param {SendSwapTransactionOptions} options - The options for the swap submission.
+ *
+ * @returns {Promise<SendSwapTransactionResult>} A promise that resolves to the transaction hash.
+ *
+ * @throws {Error} If liquidity is not available for the swap.
+ * @throws {Error} If there are insufficient token allowances. In this case, you need to approve the
+ *                 Permit2 contract to spend your tokens before attempting the swap. The error message
+ *                 will include the current allowance and the spender address that needs approval.
+ * @throws {Error} If no transaction data is found in the swap result.
+ *
+ * @example **Sending a swap with pre-created swap quote object**
+ * ```ts
+ * // First create a swap quote
+ * const swapQuote = await cdp.evm.createSwapQuote({
+ *   network: "base",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: account.address
+ * });
+ *
+ * // Check if liquidity is available
+ * if (!swapQuote.liquidityAvailable) {
+ *   console.error("Insufficient liquidity for swap");
+ *   return;
+ * }
+ *
+ * // Send the swap
+ * const result = await sendSwapTransaction(client, {
+ *   address: account.address,
+ *   swapQuote: swapQuote
+ * });
+ *
+ * console.log(`Swap sent with transaction hash: ${result.transactionHash}`);
+ * ```
+ *
+ * @example **Sending a swap with inline options (all-in-one)**
+ * ```ts
+ * // Send swap in one call
+ * const result = await sendSwapTransaction(client, {
+ *   address: account.address,
+ *   network: "base",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: account.address
+ * });
+ *
+ * console.log(`Swap sent with transaction hash: ${result.transactionHash}`);
+ * ```
+ */
+export async function sendSwapTransaction(
+  client: CdpOpenApiClientType,
+  options: SendSwapTransactionOptions,
+): Promise<SendSwapTransactionResult> {
+  const { address, idempotencyKey } = options;
+
+  let swapResult: CreateSwapQuoteResult | SwapUnavailableResult;
+
+  // Determine if we need to create the swap quote or use the provided one
+  if ("swapQuote" in options) {
+    // Use the provided swap quote
+    swapResult = options.swapQuote;
+  } else {
+    // Create the swap quote using the provided options (InlineSendSwapTransactionOptions)
+    swapResult = await createSwapQuote(client, {
+      network: options.network as CreateSwapQuoteOptions["network"],
+      toToken: options.toToken,
+      fromToken: options.fromToken,
+      fromAmount: options.fromAmount,
+      taker: options.taker,
+      signerAddress: options.signerAddress,
+      gasPrice: options.gasPrice,
+      slippageBps: options.slippageBps,
+    });
+  }
+
+  // Check if liquidity is available
+  if (!swapResult.liquidityAvailable) {
+    throw new Error("Insufficient liquidity for swap");
+  }
+
+  // At this point, we know that swapResult is CreateSwapQuoteResult
+  const swap = swapResult as CreateSwapQuoteResult;
+
+  // Check for allowance issues
+  if (swap.issues?.allowance) {
+    const { currentAllowance, spender } = swap.issues.allowance;
+    throw new Error(
+      `Insufficient token allowance for swap. Current allowance: ${currentAllowance}. ` +
+        `Please approve the Permit2 contract (${spender}) to spend your tokens.`,
+    );
+  }
+
+  // If the transaction doesn't exist, throw an error
+  if (!swap.transaction) {
+    throw new Error("No transaction data found in the swap");
+  }
+
+  // Get the transaction data and modify it if needed for Permit2
+  let txData = swap.transaction.data as Hex;
+
+  if (swap.permit2?.eip712) {
+    // Sign the Permit2 EIP-712 message
+    const signature = await client.signEvmTypedData(
+      address,
+      {
+        domain: swap.permit2.eip712.domain,
+        types: swap.permit2.eip712.types,
+        primaryType: swap.permit2.eip712.primaryType,
+        message: swap.permit2.eip712.message,
+      },
+      idempotencyKey,
+    );
+
+    // Calculate the signature length as a 32-byte hex value
+    const signatureLengthInHex = numberToHex(size(signature.signature as Hex), {
+      signed: false,
+      size: 32,
+    });
+
+    // Append the signature length and signature to the transaction data
+    txData = concat([txData, signatureLengthInHex, signature.signature as Hex]);
+  }
+
+  // Create a transaction object
+  const transaction: TransactionRequestEIP1559 = {
+    to: swap.transaction.to as `0x${string}`,
+    data: txData,
+    // Only include these properties if they exist
+    ...(swap.transaction.value ? { value: BigInt(swap.transaction.value) } : {}),
+    ...(swap.transaction.gas ? { gas: BigInt(swap.transaction.gas) } : {}),
+  };
+
+  // Use sendTransaction instead of directly calling client.sendEvmTransaction
+  const result = await sendTransaction(client, {
+    address,
+    network: swap.network as SendEvmTransactionBodyNetwork,
+    transaction,
+    idempotencyKey,
+  });
+
+  return {
+    transactionHash: result.transactionHash,
+  };
+}

package/actions/evm/swap/types.ts

@@ -0,0 +1,137 @@
+import type {
+  CreateSwapQuoteOptions,
+  CreateSwapQuoteResult,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import type { SendEvmTransactionBodyNetwork } from "../../../openapi-client/index.js";
+import type { Address, Hex } from "../../../types/misc.js";
+
+/**
+ * Base options for sending a swap transaction.
+ */
+interface BaseSendSwapTransactionOptions {
+  /**
+   * The address of the account that will execute the swap.
+   */
+  address: Address;
+
+  /**
+   * Optional idempotency key for the request.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options when providing an already created swap quote.
+ */
+interface QuoteBasedSendSwapTransactionOptions extends BaseSendSwapTransactionOptions {
+  /**
+   * The swap quote returned by the createSwapQuote method.
+   */
+  swapQuote: CreateSwapQuoteResult;
+}
+
+/**
+ * Options when creating a swap quote inline.
+ */
+interface InlineSendSwapTransactionOptions extends BaseSendSwapTransactionOptions {
+  /**
+   * The network to execute the swap on (e.g., "ethereum", "base").
+   */
+  network: SendEvmTransactionBodyNetwork;
+  /** The token to receive (destination token). */
+  toToken: Address;
+  /** The token to send (source token). */
+  fromToken: Address;
+  /** The amount to send in atomic units of the token. */
+  fromAmount: bigint;
+  /** The address that will perform the swap. */
+  taker: Address;
+  /** The signer address (only needed if taker is a smart contract). */
+  signerAddress?: Address;
+  /** The gas price in Wei. */
+  gasPrice?: bigint;
+  /** The slippage tolerance in basis points (0-10000). */
+  slippageBps?: number;
+}
+
+/**
+ * Options for sending a swap transaction.
+ * Either provide a pre-created swap quote result or inline swap parameters.
+ */
+export type SendSwapTransactionOptions =
+  | QuoteBasedSendSwapTransactionOptions
+  | InlineSendSwapTransactionOptions;
+
+/**
+ * Result of sending a swap transaction.
+ */
+export interface SendSwapTransactionResult {
+  /**
+   * The transaction hash of the submitted swap.
+   */
+  transactionHash: Hex;
+}
+
+/**
+ * Options for creating a swap quote (account-level).
+ */
+export type QuoteSwapOptions = Omit<CreateSwapQuoteOptions, "taker">;
+
+/**
+ * Result of creating a swap quote (account-level).
+ */
+export type QuoteSwapResult = CreateSwapQuoteResult | SwapUnavailableResult;
+
+/**
+ * Options when providing an already created swap quote (account-level).
+ */
+interface AccountQuoteBasedSwapOptions {
+  /**
+   * The swap quote returned by the createSwapQuote method.
+   */
+  swapQuote: CreateSwapQuoteResult;
+
+  /**
+   * Optional idempotency key for the request.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options when creating a swap quote inline (account-level).
+ */
+interface AccountInlineSwapOptions {
+  /**
+   * The network to execute the swap on (e.g., "ethereum", "base").
+   */
+  network: SendEvmTransactionBodyNetwork;
+  /** The token to receive (destination token). */
+  toToken: Address;
+  /** The token to send (source token). */
+  fromToken: Address;
+  /** The amount to send in atomic units of the token. */
+  fromAmount: bigint;
+  /** The signer address (only needed if taker is a smart contract). */
+  signerAddress?: Address;
+  /** The gas price in Wei. */
+  gasPrice?: bigint;
+  /** The slippage tolerance in basis points (0-10000). */
+  slippageBps?: number;
+
+  /**
+   * Optional idempotency key for the request.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for executing a token swap (account-level).
+ * The taker is automatically set to the account's address.
+ */
+export type SwapOptions = AccountQuoteBasedSwapOptions | AccountInlineSwapOptions;
+
+/**
+ * Result of executing a token swap (account-level).
+ */
+export type SwapResult = SendSwapTransactionResult;

package/actions/evm/types.ts

@@ -13,6 +13,7 @@ import { Hex } from "../../types/misc.js";
 import type { ListTokenBalancesOptions, ListTokenBalancesResult } from "./listTokenBalances.js";
 import type { RequestFaucetOptions, RequestFaucetResult } from "./requestFaucet.js";
 import type { SendTransactionOptions, TransactionResult } from "./sendTransaction.js";
+import type { SwapOptions, SwapResult, QuoteSwapOptions, QuoteSwapResult } from "./swap/types.js";
 import type { TransferOptions } from "./transfer/types.js";
 import type {
   WaitForUserOperationOptions,
@@ -249,6 +250,93 @@ export type AccountActions = Actions & {
    * ```
    */
   sendTransaction: (options: Omit<SendTransactionOptions, "address">) => Promise<TransactionResult>;
+
+  /**
+   * Creates a swap quote without executing the transaction.
+   * This is useful when you need to get swap details before executing the swap.
+   * The taker is automatically set to the account's address.
+   *
+   * @param {QuoteSwapOptions} options - Configuration options for creating the swap quote.
+   * @param {string} options.network - The network to create the quote on
+   * @param {string} options.fromToken - The token address to sell
+   * @param {string} options.toToken - The token address to buy
+   * @param {bigint} options.fromAmount - The amount of fromToken to sell
+   * @param {string} [options.signerAddress] - The signer address (only needed if taker is a smart contract)
+   * @param {bigint} [options.gasPrice] - The gas price in Wei
+   * @param {number} [options.slippageBps] - The slippage tolerance in basis points (0-10000)
+   *
+   * @returns A promise that resolves to the swap quote or a response indicating that liquidity is unavailable.
+   *
+   * @example
+   * ```ts
+   * const swapQuote = await account.quoteSwap({
+   *   network: "base",
+   *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+   *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+   *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+   * });
+   *
+   * if (swapQuote.liquidityAvailable) {
+   *   console.log(`Can swap for ${swapQuote.toAmount} USDC`);
+   * }
+   * ```
+   */
+  quoteSwap: (options: QuoteSwapOptions) => Promise<QuoteSwapResult>;
+
+  /**
+   * Executes a token swap on the specified network.
+   * This method handles all the steps required for a swap, including Permit2 signatures if needed.
+   *
+   * @param {SwapOptions} options - Configuration options for the swap.
+   * @param {string} [options.network] - The network to execute the swap on
+   * @param {CreateSwapQuoteResult} [options.swapQuote] - The swap quote returned by the createSwapQuote method.
+   * @param {CreateSwapQuoteOptions} [options.swapOptions] - Options to create a swap quote. The function will call createSwapQuote internally.
+   * @param {string} [options.idempotencyKey] - Optional idempotency key for the request.
+   *
+   * @returns A promise that resolves to the transaction hash.
+   *
+   * @throws {Error} If liquidity is not available when using swapOptions.
+   *
+   * @example **Using a pre-created swap quote**
+   * ```ts
+   * // First create a swap quote
+   * const swapQuote = await cdp.evm.createSwapQuote({
+   *   network: "base",
+   *   buyToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+   *   sellToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+   *   sellAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+   *   taker: account.address
+   * });
+   *
+   * // Check if liquidity is available
+   * if (!swapQuote.liquidityAvailable) {
+   *   console.error("Insufficient liquidity for swap");
+   *   return;
+   * }
+   *
+   * // Execute the swap
+   * const { transactionHash } = await account.swap({
+   *   swapQuote: swapQuote
+   * });
+   *
+   * console.log(`Swap executed with transaction hash: ${transactionHash}`);
+   * ```
+   *
+   * @example **Using swap options (all-in-one)**
+   * ```ts
+   * // Create and execute swap in one call
+   * const { transactionHash } = await account.swap({
+   *   network: "base",
+   *   buyToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+   *   sellToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+   *   sellAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+   *   taker: account.address
+   * });
+   *
+   * console.log(`Swap executed with transaction hash: ${transactionHash}`);
+   * ```
+   */
+  swap: (options: SwapOptions) => Promise<SwapResult>;
 };
 
 export type SmartAccountActions = Actions & {