@coinbase/cdp-sdk 1.10.0 → 1.12.0

package/actions/evm/types.ts

@@ -1,3 +1,11 @@
+import { FundOptions } from "./fund/fund.js";
+import { Quote } from "./fund/Quote.js";
+import { QuoteFundOptions } from "./fund/quoteFund.js";
+import { FundOperationResult } from "./fund/types.js";
+import {
+  WaitForFundOperationOptions,
+  WaitForFundOperationResult,
+} from "./fund/waitForFundOperationReceipt.js";
 import { SendUserOperationOptions, SendUserOperationReturnType } from "./sendUserOperation.js";
 import { GetUserOperationOptions, UserOperation } from "../../client/evm/evm.types.js";
 import { Hex } from "../../types/misc.js";
@@ -5,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,
@@ -50,6 +59,71 @@ type Actions = {
    * ```
    */
   requestFaucet: (options: Omit<RequestFaucetOptions, "address">) => Promise<RequestFaucetResult>;
+
+  /**
+   * Gets a quote to fund an EVM account.
+   *
+   * @param options - The options for the quote fund.
+   * @param options.network - The network to fund the account on.
+   * @param options.token - The token to fund the account with.
+   * @param options.amount - The amount of the token to fund represented as an atomic unit.
+   * It's common to use `parseUnits` utils from viem to convert to atomic units.
+   * Otherwise, you can pass atomic units directly.
+   *
+   * @returns A promise that resolves to a Quote object containing details about the funding operation.
+   *
+   * @example
+   * ```ts
+   * const quote = await account.quoteFund({
+   *   network: "base",
+   *   token: "usdc",
+   *   amount: 1000000n,
+   * });
+   * ```
+   */
+  quoteFund: (options: Omit<QuoteFundOptions, "address">) => Promise<Quote>;
+
+  /**
+   * Funds an EVM account with the specified token amount.
+   *
+   * @param options - The options for the fund operation.
+   * @param options.network - The network to fund the account on.
+   * @param options.token - The token to fund the account with (e.g., 'usdc').
+   * @param options.amount - The amount of the token to fund represented as an atomic unit.
+   * It's common to use `parseUnits` utils from viem to convert to atomic units.
+   * Otherwise, you can pass atomic units directly.
+   *
+   * @returns A promise that resolves to the fund operation result containing the transfer details.
+   *
+   * @example
+   * ```ts
+   * const fundOperation = await account.fund({
+   *   network: "base",
+   *   token: "usdc",
+   *   amount: 1000000n,
+   * });
+   * ```
+   */
+  fund: (options: Omit<FundOptions, "address">) => Promise<FundOperationResult>;
+
+  /**
+   * Waits for a fund operation to complete and returns the transfer receipt.
+   *
+   * @param options - The options for the wait for fund operation.
+   * @param options.transferId - The ID of the transfer to wait for.
+   *
+   * @returns A promise that resolves to the completed transfer receipt containing details about the funding operation.
+   *
+   * @example
+   * ```ts
+   * const completedTransfer = await account.waitForFundOperationReceipt({
+   *   transferId: "transfer_123",
+   * });
+   * ```
+   */
+  waitForFundOperationReceipt(
+    options: WaitForFundOperationOptions,
+  ): Promise<WaitForFundOperationResult>;
 };
 
 export type AccountActions = Actions & {
@@ -176,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 & {

package/client/evm/evm.ts

@@ -27,6 +27,11 @@ import {
   SignTypedDataOptions,
   UpdateEvmAccountOptions,
   ImportServerAccountOptions,
+  GetSwapPriceOptions,
+  CreateSwapQuoteOptions,
+  GetSwapPriceResult,
+  CreateSwapQuoteResult,
+  SwapUnavailableResult,
 } from "./evm.types.js";
 import { toEvmServerAccount } from "../../accounts/evm/toEvmServerAccount.js";
 import { toEvmSmartAccount } from "../../accounts/evm/toEvmSmartAccount.js";
@@ -47,6 +52,8 @@ import {
   SendUserOperationOptions,
   SendUserOperationReturnType,
 } from "../../actions/evm/sendUserOperation.js";
+import { createSwapQuote } from "../../actions/evm/swap/createSwapQuote.js";
+import { getSwapPrice } from "../../actions/evm/swap/getSwapPrice.js";
 import {
   waitForUserOperation,
   WaitForUserOperationReturnType,
@@ -103,6 +110,7 @@ export class EvmClient implements EvmClientInterface {
     const openApiAccount = await CdpOpenApiClient.createEvmAccount(
       {
         name: options.name,
+        accountPolicy: options.accountPolicy,
       },
       options.idempotencyKey,
     );
@@ -159,6 +167,8 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async importAccount(options: ImportServerAccountOptions): Promise<ServerAccount> {
+    const encryptionPublicKey = options.encryptionPublicKey || ImportEvmAccountPublicRSAKey;
+
     const privateKeyHex = options.privateKey.startsWith("0x")
       ? options.privateKey.slice(2)
       : options.privateKey;
@@ -172,7 +182,7 @@ export class EvmClient implements EvmClientInterface {
 
       const encryptedPrivateKey = publicEncrypt(
         {
-          key: ImportEvmAccountPublicRSAKey,
+          key: encryptionPublicKey,
           padding: constants.RSA_PKCS1_OAEP_PADDING,
           oaepHash: "sha256",
         },
@@ -385,6 +395,54 @@ export class EvmClient implements EvmClientInterface {
     }
   }
 
+  /**
+   * Gets the price for a swap between two tokens on an EVM network.
+   *
+   * @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
+   * ```typescript
+   * const price = await cdp.evm.getSwapPrice({
+   *   network: "ethereum-mainnet",
+   *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+   *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+   *   fromAmount: BigInt("1000000000000000000"), // 1 WETH
+   *   taker: "0x1234567890123456789012345678901234567890"
+   * });
+   * ```
+   */
+  async getSwapPrice(
+    options: GetSwapPriceOptions,
+  ): Promise<GetSwapPriceResult | SwapUnavailableResult> {
+    return getSwapPrice(CdpOpenApiClient, options);
+  }
+
+  /**
+   * Creates a quote for a swap between two tokens on an EVM network.
+   *
+   * @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
+   * ```typescript
+   * const swapQuote = await cdp.evm.createSwapQuote({
+   *   network: "ethereum",
+   *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+   *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+   *   fromAmount: BigInt("1000000000000000000"), // 1 WETH
+   *   taker: "0x1234567890123456789012345678901234567890"
+   * });
+   * ```
+   */
+  async createSwapQuote(
+    options: CreateSwapQuoteOptions,
+  ): Promise<CreateSwapQuoteResult | SwapUnavailableResult> {
+    return createSwapQuote(CdpOpenApiClient, options);
+  }
+
   /**
    * Gets a user operation for a smart account by user operation hash.
    *

package/client/evm/evm.types.ts

@@ -18,6 +18,7 @@ import type {
 } from "../../actions/evm/sendUserOperation.js";
 import type { SmartAccountActions } from "../../actions/evm/types.js";
 import type {
+  EvmSwapsNetwork,
   EvmUserOperationNetwork,
   EvmUserOperationStatus,
   OpenApiEvmMethods,
@@ -38,6 +39,8 @@ export type EvmClientInterface = Omit<
   | "getEvmAccount" // mapped to getAccount
   | "getEvmAccountByName" // mapped to getAccount
   | "getEvmSmartAccount" // mapped to getSmartAccount
+  | "getEvmSwapPrice" // mapped to getSwapPrice
+  | "createEvmSwapQuote" // mapped to createSwapQuote
   | "getUserOperation"
   | "updateEvmAccount" // mapped to updateAccount
   | "listEvmAccounts" // mapped to listAccounts
@@ -59,6 +62,12 @@ export type EvmClientInterface = Omit<
   importAccount: (options: ImportServerAccountOptions) => Promise<ServerAccount>;
   getAccount: (options: GetServerAccountOptions) => Promise<ServerAccount>;
   getSmartAccount: (options: GetSmartAccountOptions) => Promise<SmartAccount>;
+  getSwapPrice: (
+    options: GetSwapPriceOptions,
+  ) => Promise<GetSwapPriceResult | SwapUnavailableResult>;
+  createSwapQuote: (
+    options: CreateSwapQuoteOptions,
+  ) => Promise<CreateSwapQuoteResult | SwapUnavailableResult>;
   getOrCreateAccount: (options: GetOrCreateServerAccountOptions) => Promise<ServerAccount>;
   getUserOperation: (options: GetUserOperationOptions) => Promise<UserOperation>;
   updateAccount: (options: UpdateEvmAccountOptions) => Promise<ServerAccount>;
@@ -79,6 +88,153 @@ export type EvmClientInterface = Omit<
 
 export type { ServerAccount, SmartAccount };
 
+/**
+ * Options for creating a swap quote between two tokens on an EVM network.
+ */
+export interface CreateSwapQuoteOptions {
+  /** The network to create a swap quote on. */
+  network: EvmSwapsNetwork;
+  /** 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 getting a swap price.
+ */
+export interface GetSwapPriceOptions {
+  /** The network to get a price from. */
+  network: EvmSwapsNetwork;
+  /** 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;
+}
+
+/**
+ * Result of getting a swap price.
+ */
+export interface GetSwapPriceResult {
+  /** Whether liquidity is available for the swap. */
+  liquidityAvailable: true;
+  /** 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 amount to receive in atomic units of the token. */
+  toAmount: bigint;
+  /** The minimum amount to receive after slippage in atomic units of the token. */
+  minToAmount: bigint;
+  /** The block number at which the liquidity conditions were examined. */
+  blockNumber: bigint;
+  /** The estimated fees for the swap. */
+  fees: SwapFees;
+  /** Potential issues discovered during validation. */
+  issues: SwapIssues;
+  /** The gas estimate for the swap. */
+  gas?: bigint;
+  /** The gas price in Wei. */
+  gasPrice?: bigint;
+}
+
+/**
+ * Result when liquidity is unavailable for a swap.
+ */
+export interface SwapUnavailableResult {
+  /** Whether liquidity is available for the swap. */
+  liquidityAvailable: false;
+}
+
+/**
+ * Options for executing a swap quote.
+ */
+export interface ExecuteSwapQuoteOptions {
+  /** Optional idempotency key for the request. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Result of executing a swap quote.
+ */
+export interface ExecuteSwapQuoteResult {
+  /** The transaction hash of the executed swap. */
+  transactionHash: Hex;
+}
+
+/**
+ * Result of creating a swap quote.
+ */
+export interface CreateSwapQuoteResult {
+  /** Whether liquidity is available for the swap. */
+  liquidityAvailable: true;
+  /** The network for which this swap quote was created. */
+  network: EvmSwapsNetwork;
+  /** 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 amount to receive in atomic units of the token. */
+  toAmount: bigint;
+  /** The minimum amount to receive after slippage in atomic units of the token. */
+  minToAmount: bigint;
+  /** The block number at which the liquidity conditions were examined. */
+  blockNumber: bigint;
+  /** The estimated fees for the swap. */
+  fees: SwapFees;
+  /** Potential issues discovered during validation. */
+  issues: SwapIssues;
+  /** The transaction to execute the swap. */
+  transaction?: {
+    /** The contract address to send the transaction to. */
+    to: Address;
+    /** The transaction data. */
+    data: Hex;
+    /** The value to send with the transaction in Wei. */
+    value: bigint;
+    /** The gas limit for the transaction. */
+    gas: bigint;
+    /** The gas price for the transaction in Wei. */
+    gasPrice: bigint;
+  };
+  /** Permit2 data if required for the swap. */
+  permit2?: {
+    /** EIP-712 typed data for signing. */
+    eip712: EIP712Message;
+  };
+  /**
+   * Execute the swap using the quote.
+   *
+   * @param {ExecuteSwapQuoteOptions} options - Options for executing the swap.
+   * @returns {Promise<ExecuteSwapQuoteResult>} A promise that resolves to the swap execution result.
+   */
+  execute: (options?: ExecuteSwapQuoteOptions) => Promise<ExecuteSwapQuoteResult>;
+}
+
 /**
  * Options for getting a user operation.
  */
@@ -145,6 +301,8 @@ export interface UserOperation {
 export interface CreateServerAccountOptions {
   /** The name of the account. */
   name?: string;
+  /** The policy ID to apply to the account. */
+  accountPolicy?: string;
   /** The idempotency key. */
   idempotencyKey?: string;
 }
@@ -153,6 +311,8 @@ export interface CreateServerAccountOptions {
  * Options for importing an EVM server account.
  */
 export interface ImportServerAccountOptions {
+  /** The public RSA key used to encrypt the private key when importing an EVM account. */
+  encryptionPublicKey?: string;
   /** The name of the account. */
   name?: string;
   /** The idempotency key. */
@@ -293,7 +453,7 @@ export interface SignMessageOptions {
 }
 
 /**
- * Options for signing an EVM message.
+ * Options for signing an EVM typed data message.
  */
 export interface SignTypedDataOptions {
   /** The address of the account. */
@@ -330,6 +490,60 @@ export interface SignatureResult {
   signature: Hex;
 }
 
+/**
+ * A fee in a specific token.
+ */
+export interface TokenFee {
+  /** The amount of the fee in atomic units of the token. */
+  amount: bigint;
+  /** The contract address of the token that the fee is paid in. */
+  token: Address;
+}
+
+/**
+ * The estimated fees for a swap.
+ */
+export interface SwapFees {
+  /** The estimated gas fee for the swap. */
+  gasFee?: TokenFee;
+  /** The estimated protocol fee for the swap. */
+  protocolFee?: TokenFee;
+}
+
+/**
+ * Details of allowance issues for a swap.
+ */
+export interface SwapAllowanceIssue {
+  /** The current allowance of the fromToken by the taker. */
+  currentAllowance: bigint;
+  /** The address to set the allowance on. */
+  spender: Address;
+}
+
+/**
+ * Details of balance issues for a swap.
+ */
+export interface SwapBalanceIssue {
+  /** The contract address of the token. */
+  token: Address;
+  /** The current balance of the fromToken by the taker. */
+  currentBalance: bigint;
+  /** The amount of the token that the taker must hold. */
+  requiredBalance: bigint;
+}
+
+/**
+ * Potential issues discovered during swap validation.
+ */
+export interface SwapIssues {
+  /** Details of the allowances that the taker must set. Null if no allowance is required. */
+  allowance?: SwapAllowanceIssue;
+  /** Details of the balance of the fromToken that the taker must hold. Null if sufficient balance. */
+  balance?: SwapBalanceIssue;
+  /** True when the transaction cannot be validated (e.g., insufficient balance). */
+  simulationIncomplete: boolean;
+}
+
 /**
  * Options for waiting for a user operation.
  */
@@ -341,3 +555,15 @@ export interface WaitForUserOperationOptions {
   /** The wait options. */
   waitOptions?: WaitOptions;
 }
+
+/**
+ * Legacy type aliases for backwards compatibility.
+ *
+ * @deprecated Use the new type names instead.
+ */
+export type CreateSwapOptions = CreateSwapQuoteOptions;
+export type CreateSwapResult = CreateSwapQuoteResult;
+export type GetSwapQuoteOptions = GetSwapPriceOptions;
+export type GetSwapQuoteResult = GetSwapPriceResult;
+export type SwapQuoteUnavailableResult = SwapUnavailableResult;
+export type SwapPriceUnavailableResult = SwapUnavailableResult;

package/client/solana/solana.ts

@@ -56,7 +56,10 @@ export class SolanaClient implements SolanaClientInterface {
    */
   async createAccount(options: CreateAccountOptions = {}): Promise<SolanaAccount> {
     const openApiAccount = await CdpOpenApiClient.createSolanaAccount(
-      options,
+      {
+        name: options.name,
+        accountPolicy: options.accountPolicy,
+      },
       options.idempotencyKey,
     );
 

package/client/solana/solana.types.ts

@@ -40,6 +40,8 @@ export interface SignatureResult {
 export interface CreateAccountOptions {
   /** The name of the account. */
   name?: string;
+  /** The policy ID to apply to the account. */
+  accountPolicy?: string;
   /** The idempotency key. */
   idempotencyKey?: string;
 }