@mycelium-sdk/core 0.1.0 → 1.0.0-alpha.1

package/dist/index.d.ts

@@ -4,23 +4,6 @@ import { SmartAccount, BundlerClient, WebAuthnAccount, toCoinbaseSmartAccount }
 declare const SUPPORTED_CHAIN_IDS: number[];
 type SupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 
-/**
- * @internal
- * @category Types
- *  Detailed token balance information
- *
- */
-interface TokenBalance {
-    symbol: string;
-    totalBalance: bigint;
-    totalFormattedBalance: string;
-    chainBalances: Array<{
-        chainId: SupportedChainId;
-        balance: bigint;
-        formattedBalance: string;
-    }>;
-}
-
 /**
  * Chain configuration
  *  Configuration for each supported chain
@@ -135,6 +118,23 @@ declare class ChainManager {
     private createPublicClient;
 }
 
+/**
+ * @internal
+ * @category Types
+ *  Detailed token balance information
+ *
+ */
+interface TokenBalance {
+    symbol: string;
+    totalBalance: bigint;
+    totalFormattedBalance: string;
+    chainBalances: Array<{
+        chainId: SupportedChainId;
+        balance: bigint;
+        formattedBalance: string;
+    }>;
+}
+
 /**
  * Asset identifier - can be a symbol (like 'usdc') or address
  */
@@ -294,7 +294,7 @@ declare abstract class SmartWallet {
      * @param amount Amount to deposit in human-readable format
      * @returns Promise resolving to a {@link VaultTxnResult}
      */
-    abstract earn(amount: string): Promise<VaultTxnResult>;
+    abstract earn(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Retrieves the balance of deposited funds in the selected protocol vault
      *
@@ -302,7 +302,7 @@ declare abstract class SmartWallet {
      * @category Yield
      * @returns Promise resolving to a {@link VaultBalance} or null if none
      */
-    abstract getEarnBalance(): Promise<VaultBalance | null>;
+    abstract getEarnBalances(): Promise<VaultBalance[] | null>;
     /**
      * Withdraws a specific amount of shares from the protocol vault
      *
@@ -311,7 +311,7 @@ declare abstract class SmartWallet {
      * @param amount Human-readable amount of shares to withdraw
      * @returns Promise resolving to a {@link VaultTxnResult}
      */
-    abstract withdraw(amount: string): Promise<VaultTxnResult>;
+    abstract withdraw(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Funds the smart wallet with the specified amount of the specified token via Coinbase CDP on-ramp service
      *
@@ -350,6 +350,63 @@ declare abstract class SmartWallet {
     abstract cashOut(country: string, paymentMethod: string, redirectUrl: string, sellAmount: string, cashoutCurrency?: string, sellCurrency?: string): Promise<OffRampUrlResponse>;
 }
 
+type ApiResponse<T = unknown> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+type OperationType = 'config' | 'deposit' | 'withdraw' | 'log' | 'vaults' | 'balances' | 'apiKeyValidation';
+
+declare class ApiClient {
+    private readonly client;
+    /** URL settings for the endpoint: get the best vaults to deposit funds */
+    private readonly bestVaultUrlSettings;
+    /** URL settings for the endpoint: deposit funds to a provided vault */
+    private readonly depositUrlSettings;
+    /** URL settings for the endpoint: log a vault-related operation after deposit or withdraw funds */
+    private readonly logOperationSettings;
+    /** URL settings for the endpoint: withdraw funds from a provided vault */
+    private readonly withdrawUrlSettings;
+    /** URL settings for the endpoint: get the balances of a user by a provided address */
+    private readonly balancesUrlSettings;
+    /** URL settings for the endpoint: validate the API key */
+    private readonly apiKeyValidUrlSettings;
+    /** URL settings for the endpoint: get the config for services */
+    private readonly configUrlSettings;
+    /** URL settings mapping with operation types */
+    private readonly operationTypeToUrlSettings;
+    /** API key for the backend API */
+    private apiKey;
+    constructor(apiKey: string);
+    /**
+     * Send a request to the backend API
+     * @param path Path of the endpoint to send the request to
+     * @param method Method of the request
+     * @param body Body of the request
+     * @returns Response from the backend API
+     */
+    sendRequest(operationType: OperationType, params?: Record<string, string>, protocolId?: string, body?: Record<string, string | VaultInfo>): Promise<ApiResponse<unknown>>;
+    /**
+     * Validates whether the provided API key is valid
+     *
+     * @internal
+     * @param apiKey API key from {@link ProtocolsRouterConfig}
+     * @returns True if the API key is considered valid
+     */
+    validate(): Promise<boolean>;
+    /**
+     *
+     * Validates the format of the API key. Must start with 'sk_' and contain only hexadecimal characters
+     *
+     * @internal
+     * @param apiKey API key from {@link ProtocolsRouterConfig}
+     * @returns
+     */
+    private validateApiKeyFormat;
+}
+
 /**
  * Base Protocol
  *
@@ -363,56 +420,51 @@ declare abstract class SmartWallet {
  *
  * Generic parameters allow protocol-specific typing for vault info, balances, and transaction results
  */
-declare abstract class BaseProtocol<TVaultInfo extends VaultInfo = VaultInfo, TVaultBalance extends VaultBalance = VaultBalance, TVaultTxnResult extends VaultTxnResult = VaultTxnResult> {
-    /** Chain manager instance injected during initialization */
+declare abstract class BaseProtocol {
+    /** Selected chain ID for the protocol */
+    protected selectedChainId: SupportedChainId | undefined;
+    /** Public client to make requests to RPC */
+    protected publicClient: PublicClient | undefined;
+    /** Chain manager instance for network access */
     chainManager: ChainManager | undefined;
     /**
      * Initialize the protocol
      * @param chainManager Chain manager for accessing RPC and bundler clients
      */
-    abstract init(chainManager: ChainManager): Promise<void>;
+    abstract init(chainManager: ChainManager, protocolsSecurityConfig: ProtocolsSecurityConfig, apiClient?: ApiClient): Promise<void>;
     /**
      * Ensure the protocol has been initialized
      * @throws Error if `init()` has not been called
      */
     protected ensureInitialized(): void;
-    /**
-     * Get all available vaults
-     * @returns List of vaults that support deposits
-     */
-    abstract getVaults(): Promise<TVaultInfo[]> | TVaultInfo[];
     /**
      * Get the best vault for deposits
      * @returns Single vault considered optimal for deposit
      */
-    abstract getBestVault(): Promise<TVaultInfo> | TVaultInfo;
-    /**
-     * Get a vault where funds may already be deposited
-     * @param smartWallet Wallet to check for existing deposits
-     * @returns Vault info if deposits exist, otherwise null
-     */
-    abstract fetchDepositedVaults(smartWallet: SmartWallet): Promise<TVaultInfo | null>;
+    abstract getBestVaults(stableVaultsLimit?: number, nonStableVaultsLimit?: number): Promise<Vaults> | Vaults;
     /**
      * Deposit funds into a vault
+     * @param vaultInfo Vault information
      * @param amount Amount in human-readable format
      * @param smartWallet Wallet executing the deposit
      * @returns Result of the deposit transaction
      */
-    abstract deposit(amount: string, smartWallet: SmartWallet): Promise<TVaultTxnResult>;
+    abstract deposit(vaultInfo: VaultInfo, amount: string, smartWallet: SmartWallet): Promise<VaultTxnResult>;
     /**
      * Withdraw funds from a vault
-     * @param amountInShares Amount of shares to withdraw
+     * @param vaultInfo Vault information
+     * @param amount Amount in human-readable format (or undefined to withdraw all)
      * @param smartWallet Wallet executing the withdrawal
      * @returns Result of the withdrawal transaction
      */
-    abstract withdraw(amountInShares: string, smartWallet: SmartWallet): Promise<TVaultTxnResult>;
+    abstract withdraw(vaultInfo: VaultInfo, amountInShares: string, smartWallet: SmartWallet): Promise<VaultTxnResult>;
     /**
      * Get deposited balance in a vault
-     * @param vaultInfo Vault info for a selected protocol
      * @param walletAddress Wallet address to check the balance of
+     * @param protocolId Protocol ID to get balances for
      * @returns Balance of deposited funds
      */
-    abstract getBalance(vaultInfo: TVaultInfo, walletAddress: Address): Promise<TVaultBalance>;
+    abstract getBalances(walletAddress: Address, protocolId?: string): Promise<VaultBalance[]>;
     /**
      * Approve a token for protocol use
      * @param tokenAddress Token address
@@ -434,35 +486,14 @@ declare abstract class BaseProtocol<TVaultInfo extends VaultInfo = VaultInfo, TV
     protected checkAllowance(tokenAddress: Address, spenderAddress: Address, walletAddress: Address, chainId: SupportedChainId): Promise<bigint>;
 }
 
-/**
- * Base information that can be used to identify a protocol
- */
-interface ProtocolInfo {
-    id: string;
-    name: string;
-    website: string;
-    logo: string;
-    supportedChains: number[];
-    riskLevel: 'low' | 'medium' | 'high';
-    isPremium: boolean;
-}
-/**
- * Interface with protocol information and instance object
- */
-interface Protocol {
-    instance: BaseProtocol;
-    info: ProtocolInfo;
-}
 /**
  * The protocols router config that defines which protocols should be used for an integrator
  */
-interface ProtocolsRouterConfig {
+interface ProtocolsSecurityConfig {
     riskLevel: 'low' | 'medium' | 'high';
-    minApy?: number;
-    apiKey?: string;
 }
 /**
- * @internal
+ * @public
  * The info about a protocol vault
  * @category Types
  * @remarks
@@ -470,17 +501,26 @@ interface ProtocolsRouterConfig {
  */
 interface VaultInfo {
     id: string;
-    chain: string;
-    chainId?: number;
-    depositTokenAddress: Address;
-    depositTokenDecimals: number;
-    depositTokenSymbol?: string;
+    protocolId: string;
     vaultAddress: Address;
-    earnTokenAddress?: Address;
-    earnTokenDecimals?: number;
-    earnTokenSymbol?: string;
+    tokenAddress: Address;
+    tokenDecimals: number;
+    tokenSymbol?: string;
+    name: string;
+    type: 'stable' | 'non-stable';
+    chain: string;
     metadata?: Record<string, number | string>;
 }
+/**
+ * @public
+ * The array of stable and non-stable vaults for a protocol
+ * @remarks Stable and non-stable vaults are @see VaultInfo type
+ * @category Types
+ */
+interface Vaults {
+    stable: VaultInfo[];
+    nonStable: VaultInfo[];
+}
 /**
  * @public
  * The info about current user's balance in a protocol vault
@@ -489,10 +529,8 @@ interface VaultInfo {
  * The generic type that shows fields that should be present in a protocol vault balance
  */
 interface VaultBalance {
-    /** amount of shares in a protocol vault based on a deposited amount */
-    shares: string;
     /** amount of deposited tokens in a protocol vault (e.g. sUSDC)*/
-    depositedAmount: string;
+    balance: string | ProxyBalance | null;
     /** info about a protocol vault where a user deposited funds */
     vaultInfo: VaultInfo;
 }
@@ -512,112 +550,75 @@ interface VaultTxnResult {
     error?: string;
 }
 
-interface SparkVaultInfo extends VaultInfo {
-    id: string;
-    chain: string;
-    earnTokenAddress: Address;
-    earnTokenDecimals: number;
-    depositTokenSymbol: string;
-    earnTokenSymbol: string;
-    metadata?: {
-        apy?: number;
-    };
+interface ProxyBalance {
+    userAddress: Address;
+    integratorId: string;
+    protocolId: string;
+    vaultAddress: Address;
+    chainId: number;
+    currentBalance: string;
+    actualCurrentBalance: string;
+    pnl: number;
+    balanceInShares: string;
+    earnedOverall: string;
+    earned7d: string;
+    earned30d: string;
+    earned90d: string;
+    earnedOverallUpdatedAt: string | null;
+    earned7dUpdatedAt: string | null;
+    earned30dUpdatedAt: string | null;
+    earned90dUpdatedAt: string | null;
 }
+
 /**
- * @public
- * The result of a Spark vault deposit or withdrawal transaction
- * @category Types
+ * Options for creating a smart wallet
+ * Parameters for creating a new smart wallet with specified owners and signer
  */
-interface SparkVaultTxnResult {
-    /** the boolean value that indicates if the transaction was successful */
-    success: boolean;
-    /** hash of the operation */
-    hash: string;
-}
+type CreateSmartWalletOptions = {
+    owners: Array<Address | WebAuthnAccount>;
+    signer: LocalAccount;
+    nonce?: bigint;
+};
 /**
- * @public
- * The info about current user's balance in a Spark vault
- * @category Types
+ * Options for creating a wallet with embedded signer
+ * Parameters for creating both embedded and smart wallets, with embedded wallet automatically added as signer
  */
-interface SparkVaultBalance {
-    /** amount of shares in sUSDC token that user has in the Spark vault */
-    shares: string;
-    /**
-     *  amount of deposited tokens + earned tokens
-     * @remarks
-     * To get the amount of earned tokens, you need to store all user's deposits and withdrawals
-     * on your side and then subtract the amount of deposited tokens from the `depositedAmount` */
-    depositedAmount: string;
-    /** detailed info about a Spark vault where a user deposited funds */
-    vaultInfo: SparkVaultInfo;
-}
-
+type CreateAccountOptions = {
+    owners?: Array<Address | WebAuthnAccount>;
+    embeddedWalletIndex?: number;
+    nonce?: bigint;
+};
 /**
- * Abstract base class for smart wallet providers
- *
- * @internal
- * @category Wallet Providers
- * @remarks
- * Defines the interface for factories that create and manage {@link SmartWallet} instances
- * Extended by implementations such as {@link DefaultSmartWalletProvider}
+ * Options for retrieving a smart wallet with provided signer
+ * Parameters for getting an existing smart wallet using a provided LocalAccount signer
  */
-declare abstract class SmartWalletProvider$1 {
-    /**
-     * Creates a new smart wallet instance that will be deployed on first transaction
-     *
-     * @internal
-     * @category Creation
-     * @remarks
-     * Address is calculated deterministically using owners and nonce
-     *
-     * @param params Wallet creation parameters
-     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
-     * @param params.signer Local account used for signing
-     * @param params.nonce Optional nonce for address derivation, default 0
-     * @returns Promise resolving to a {@link SmartWallet} instance
-     */
-    abstract createWallet(params: {
-        owners: Array<Address | WebAuthnAccount>;
-        signer: LocalAccount;
-        nonce?: bigint;
-    }): Promise<SmartWallet>;
-    /**
-     * Returns a smart wallet instance for an already deployed contract
-     *
-     * @internal
-     * @category Retrieval
-     * @remarks
-     * Use when the wallet address is already known
-     *
-     * @param params Wallet retrieval parameters
-     * @param params.walletAddress Deployed smart wallet address
-     * @param params.signer Local account to operate the wallet
-     * @param params.ownerIndex Optional index of signer in the owners list, default 0
-     * @returns A {@link SmartWallet} instance
-     */
-    abstract getWallet(params: {
-        walletAddress: Address;
-        signer: LocalAccount;
-        ownerIndex?: number;
-    }): SmartWallet;
-    /**
-     * Predicts the deterministic address of a smart wallet
-     *
-     * @internal
-     * @category Addressing
-     * @remarks
-     * Uses CREATE2 with owners and nonce to calculate the wallet address
-     *
-     * @param params Prediction parameters
-     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
-     * @param params.nonce Optional nonce, default 0
-     * @returns Promise resolving to the predicted {@link Address}
-     */
-    abstract getWalletAddress(params: {
-        owners: Array<Address | WebAuthnAccount>;
-        nonce?: bigint;
-    }): Promise<Address>;
-}
+type GetSmartWalletOptions = {
+    signer: LocalAccount;
+    deploymentOwners?: Array<Address | WebAuthnAccount>;
+    signerOwnerIndex?: number;
+    walletAddress?: Address;
+    nonce?: bigint;
+};
+/**
+ * Options for retrieving an embedded wallet
+ * Parameters for getting an existing embedded wallet
+ */
+type GetEmbeddedWalletOptions = {
+    walletId: string;
+};
+/**
+ * Options for retrieving a smart wallet with embedded wallet signer
+ * Parameters for getting an existing smart wallet using an embedded wallet as signer.
+ * If neither walletAddress nor deploymentOwners is provided, defaults to using the embedded wallet as single owner.
+ */
+type GetAccountOptions = Omit<GetSmartWalletOptions, 'signer'> & GetEmbeddedWalletOptions;
+/**
+ * Result of creating a unified web3 account in {@link WalletProvider.createAccount} and {@link WalletNamespace.createAccount}
+ */
+type CreateAccountResult = {
+    embeddedWalletId: string;
+    smartWallet: SmartWallet;
+};
 
 /**
  * Abstract base class for embedded wallet implementations
@@ -703,47 +704,71 @@ declare abstract class EmbeddedWalletProvider {
 }
 
 /**
- * Options for creating a smart wallet
- *  Parameters for creating a new smart wallet with specified owners and signer
- */
-type CreateSmartWalletOptions = {
-    owners: Array<Address | WebAuthnAccount>;
-    signer: LocalAccount;
-    nonce?: bigint;
-};
-/**
- * Options for creating a wallet with embedded signer
- *  Parameters for creating both embedded and smart wallets, with embedded wallet automatically added as signer
- */
-type CreateWalletWithEmbeddedSignerOptions = {
-    owners?: Array<Address | WebAuthnAccount>;
-    embeddedWalletIndex?: number;
-    nonce?: bigint;
-};
-/**
- * Options for retrieving a smart wallet with provided signer
- *  Parameters for getting an existing smart wallet using a provided LocalAccount signer
- */
-type GetSmartWalletOptions = {
-    signer: LocalAccount;
-    deploymentOwners?: Array<Address | WebAuthnAccount>;
-    signerOwnerIndex?: number;
-    walletAddress?: Address;
-    nonce?: bigint;
-};
-/**
- * Options for retrieving an embedded wallet
- *  Parameters for getting an existing embedded wallet
- */
-type GetEmbeddedWalletOptions = {
-    walletId: string;
-};
-/**
- * Options for retrieving a smart wallet with embedded wallet signer
- *  Parameters for getting an existing smart wallet using an embedded wallet as signer.
- * If neither walletAddress nor deploymentOwners is provided, defaults to using the embedded wallet as single owner.
+ * Abstract base class for smart wallet providers
+ *
+ * @internal
+ * @category Wallet Providers
+ * @remarks
+ * Defines the interface for factories that create and manage {@link SmartWallet} instances
+ * Extended by implementations such as {@link DefaultSmartWalletProvider}
  */
-type GetSmartWalletWithEmbeddedSignerOptions = Omit<GetSmartWalletOptions, 'signer'> & GetEmbeddedWalletOptions;
+declare abstract class SmartWalletProvider$1 {
+    /**
+     * Creates a new smart wallet instance that will be deployed on first transaction
+     *
+     * @internal
+     * @category Creation
+     * @remarks
+     * Address is calculated deterministically using owners and nonce
+     *
+     * @param params Wallet creation parameters
+     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
+     * @param params.signer Local account used for signing
+     * @param params.nonce Optional nonce for address derivation, default 0
+     * @returns Promise resolving to a {@link SmartWallet} instance
+     */
+    abstract createWallet(params: {
+        owners: Array<Address | WebAuthnAccount>;
+        signer: LocalAccount;
+        nonce?: bigint;
+    }): Promise<SmartWallet>;
+    /**
+     * Returns a smart wallet instance for an already deployed contract
+     *
+     * @internal
+     * @category Retrieval
+     * @remarks
+     * Use when the wallet address is already known
+     *
+     * @param params Wallet retrieval parameters
+     * @param params.walletAddress Deployed smart wallet address
+     * @param params.signer Local account to operate the wallet
+     * @param params.ownerIndex Optional index of signer in the owners list, default 0
+     * @returns A {@link SmartWallet} instance
+     */
+    abstract getWallet(params: {
+        walletAddress: Address;
+        signer: LocalAccount;
+        ownerIndex?: number;
+    }): SmartWallet;
+    /**
+     * Predicts the deterministic address of a smart wallet
+     *
+     * @internal
+     * @category Addressing
+     * @remarks
+     * Uses CREATE2 with owners and nonce to calculate the wallet address
+     *
+     * @param params Prediction parameters
+     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
+     * @param params.nonce Optional nonce, default 0
+     * @returns Promise resolving to the predicted {@link Address}
+     */
+    abstract getWalletAddress(params: {
+        owners: Array<Address | WebAuthnAccount>;
+        nonce?: bigint;
+    }): Promise<Address>;
+}
 
 /**
  * Unified Wallet Provider class
@@ -821,9 +846,9 @@ declare class WalletProvider {
      * @param params.nonce Optional salt/nonce for deterministic address calculation (defaults to 0)
      * @returns Promise that resolves to the created {@link SmartWallet}
      */
-    createWalletWithEmbeddedSigner(params?: CreateWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    createAccount(params?: CreateAccountOptions): Promise<CreateAccountResult>;
     /**
-     * Gets a smart wallet using an embedded wallet as the signer
+     * Gets a unified web3 account: a smart wallet using an embedded wallet as the signer
      *
      * @internal
      * @remarks
@@ -840,7 +865,7 @@ declare class WalletProvider {
      * @returns Promise that resolves to the {@link SmartWallet}
      * @throws Error if the embedded wallet cannot be found
      */
-    getSmartWalletWithEmbeddedSigner(params: GetSmartWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    getAccount(params: GetAccountOptions): Promise<SmartWallet>;
     /**
      * Gets an existing embedded wallet by ID
      *
@@ -873,22 +898,27 @@ declare class WalletProvider {
 }
 
 /**
- * Public wallet namespace that exposes unified wallet operations
+ * Wallet namespace to create and retrieve different wallet formats and overall web3 account
  *
  * @public
- * @category Wallets creation and retrieval
+ * @category 2. Accounts creation and retrieval
  * @remarks
- * This class is returned by {@link MyceliumSDK} and provides a simplified
- * interface for wallet creation and retrieval. Advanced functionality can be accessed through
- * the underlying providers via the getters {@link embeddedWalletProvider} and
- * {@link smartWalletProvider}
+ * This class is returned by {@link MyceliumSDK} and provides a methods to create and retrieve different wallet formats
+ * The common methods are:
+ * - {@link createAccount} which creates a unified account: a smart wallet with an embedded wallet as signer
+ * - {@link getAccount} which retrieves a unified account: a smart wallet using an embedded walletId
+ * More advanced option are also available
  *
- * Typical flows:
- * - Create embedded wallet only: {@link createEmbeddedWallet}
- * - Create smart wallet only (you provide signer/owners): {@link createSmartWallet}
- * - Create smart wallet with embedded as signer: {@link createWalletWithEmbeddedSigner}
- * - Get smart wallet using embedded as signer: {@link getSmartWalletWithEmbeddedSigner}
- * - Get smart wallet using a provided signer: {@link getSmartWallet}
+ * @example
+ * ```ts
+ * // Create a smart wallet and related embedded wallet
+ * const { embeddedWalletId, smartWallet } = await myceliumSDK.wallet.createAccount();
+ *
+ * // Get the smart wallet using the embedded walletId
+ * const smartWallet = await myceliumSDK.wallet.getAccount({
+ *   embeddedWalletId,
+ * });
+ * ```
  */
 declare class WalletNamespace {
     /**
@@ -901,28 +931,6 @@ declare class WalletNamespace {
      * @param provider Unified provider that composes embedded & smart providers
      */
     constructor(provider: WalletProvider);
-    /**
-     * Direct access to the underlying embedded wallet provider
-     *
-     * @public
-     * @category Providers
-     * @remarks
-     * Useful when you need advanced functionality beyond the unified namespace. By default, you should use the unified namespace
-     *
-     * @returns The configured embedded wallet provider instance
-     */
-    get embeddedWalletProvider(): EmbeddedWalletProvider;
-    /**
-     * Direct access to the underlying smart wallet provider
-     *
-     * @public
-     * @category Providers
-     * @remarks
-     * Useful when you need advanced functionality beyond the unified namespace. By default, you should use the unified namespace
-     *
-     * @returns The configured smart wallet provider instance
-     */
-    get smartWalletProvider(): SmartWalletProvider$1;
     /**
      * Creates an embedded wallet
      *
@@ -951,7 +959,7 @@ declare class WalletNamespace {
      */
     createSmartWallet(params: CreateSmartWalletOptions): Promise<SmartWallet>;
     /**
-     * Creates a smart wallet with an embedded wallet as signer
+     * A unified a web3 account: creates a smart wallet with an embedded wallet as signer
      *
      * @public
      * @category Creation
@@ -965,9 +973,9 @@ declare class WalletNamespace {
      * @param params.nonce Optional nonce/salt for deterministic address generation (defaults to 0)
      * @returns Promise that resolves to the created {@link SmartWallet}
      */
-    createWalletWithEmbeddedSigner(params?: CreateWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    createAccount(params?: CreateAccountOptions): Promise<CreateAccountResult>;
     /**
-     * Gets a smart wallet using an embedded wallet as the signer
+     * Gets a unified web3 account: a smart wallet using an embedded wallet as the signer
      *
      * @public
      * @category Retrieval
@@ -985,7 +993,7 @@ declare class WalletNamespace {
      * @returns Promise that resolves to the {@link SmartWallet}
      * @throws Error if the embedded wallet cannot be found
      */
-    getSmartWalletWithEmbeddedSigner(params: GetSmartWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    getAccount(params: GetAccountOptions): Promise<SmartWallet>;
     /**
      * Gets an existing embedded wallet by ID
      *
@@ -1018,6 +1026,22 @@ declare class WalletNamespace {
     getSmartWallet(params: GetSmartWalletOptions): Promise<SmartWallet>;
 }
 
+/**
+ * Protocol namespace to manage protocol related operations, e.g. get best vaults
+ * @public
+ * @category Protocols
+ */
+declare class ProtocolsNamespace {
+    private protocol;
+    constructor(protocol: BaseProtocol);
+    /**
+     * Find the best vaults for protocols that were selected based on integrator's settings
+     *
+     * @returns Best vaults for protocols that were selected based on integrator's settings
+     */
+    getBestVaults(stableVaultsLimit?: number, nonStableVaultsLimit?: number): Promise<Vaults>;
+}
+
 /**
  * Mycelium SDK configuration
  * Configuration object for initializing the Mycelium SDK
@@ -1080,7 +1104,7 @@ interface MyceliumSDKConfig {
      * @remarks
      * If an integrator is not provided any requirements, `low` risk level protocols will be used by default
      */
-    protocolsRouterConfig?: ProtocolsRouterConfig;
+    protocolsSecurityConfig?: ProtocolsSecurityConfig;
     /**
      * Coinbase CDP configuration
      * @remarks
@@ -1091,6 +1115,15 @@ interface MyceliumSDKConfig {
      */
     coinbaseCDPConfig?: CoinbaseCDPConfig;
 }
+/**
+ * Basic Mycelium SDK configuration for a case when a user provided only API key without advanced configurations
+ */
+interface BasicMyceliumSDKConfig {
+    apiKey: string;
+    chainId?: number;
+    protocolsSecurityConfig: ProtocolsSecurityConfig;
+    overrides?: Partial<MyceliumSDKConfig>;
+}
 /**
  * Coinbase CDP configuration
  * Configuration for Coinbase CDP API
@@ -1245,7 +1278,7 @@ declare class CoinbaseCDP {
  * Default ERC-4337 smart wallet implementation. Implements main methods that a user can use to interact with DeFi protocols and use all related functionalities
  *
  * @public
- * @category Wallets operations
+ * @category 3. Account operations
  * @remarks
  * Backed by Coinbase Smart Account and compatible with ERC-4337 UserOperations
  * Supports multi-owner wallets (EVM addresses or WebAuthn owners), gas-sponsored flows,
@@ -1280,7 +1313,8 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @param signerOwnerIndex Optional index of `signer` in owners (default 0)
      * @param nonce Optional salt for deterministic address calc (default 0)
      */
-    constructor(owners: Array<Address | WebAuthnAccount>, signer: LocalAccount, chainManager: ChainManager, protocolProvider: Protocol['instance'], coinbaseCDP: CoinbaseCDP | null, deploymentAddress?: Address, signerOwnerIndex?: number, nonce?: bigint);
+    constructor(owners: Array<Address | WebAuthnAccount>, signer: LocalAccount, chainManager: ChainManager, protocolProvider: BaseProtocol, // Protocol['instance'],
+    coinbaseCDP: CoinbaseCDP | null, deploymentAddress?: Address, signerOwnerIndex?: number, nonce?: bigint);
     /**
      * Returns the signer account for this smart wallet
      *
@@ -1330,7 +1364,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @param amount Human-readable amount string
      * @returns Transaction result for the deposit
      */
-    earn(amount: string): Promise<VaultTxnResult>;
+    earn(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Reads current deposit balance from the selected protocol’s vault
      * Method to read the current deposit balance from the selected protocol’s vault for a smart account
@@ -1339,7 +1373,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @category Earn
      * @returns Vault balance or `null` if nothing deposited
      */
-    getEarnBalance(): Promise<VaultBalance | null>;
+    getEarnBalances(): Promise<VaultBalance[]>;
     /**
      * Withdraws from the selected protocol’s vault
      * @public
@@ -1349,7 +1383,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @throws Error if the withdrawal fails
      * @throws Error a user didn't deposit anything
      */
-    withdraw(amount: string): Promise<VaultTxnResult>;
+    withdraw(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Builds a UserOperation and submits via the bundler, then waits for inclusion
   
@@ -1379,7 +1413,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * Funds the smart wallet with the specified amount of the specified token via Coinbase CDP on-ramp service
      *
      * @public
-     * @category Ramp
+     * @category Funding
      *
      * @remarks
      * If Coinbase CDP is not initialized, the method will throw an error. For more details, visit @see {@link https://docs.cdp.coinbase.com/api-reference/v2/rest-api/onramp/create-an-onramp-session}
@@ -1400,7 +1434,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * Cashout token from smart wallet to fiat currency via Coinbase CDP off-ramp service
      *
      * @public
-     * @category Ramp
+     * @category Funding
      *
      * @remarks
      * If Coinbase CDP is not initialized, the method will throw an error. For more details, visit @see {@link https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/create-sell-quote}
@@ -1431,49 +1465,116 @@ declare class DefaultSmartWallet extends SmartWallet {
     sendTokens(amount: number, asset: AssetIdentifier, recipientAddress: Address): Promise<TransactionData>;
 }
 
+/**
+ * Namespace to manage funding & payouts of an account
+ * @public
+ * @remarks
+ * Contains 2 methods to get available options to top up an account and cash out funds
+ * - {@link getTopUpConfig} to get available options to top up an account
+ * - {@link getCashOutConfig} to get available options to cash out funds
+ *
+ * @example
+ * ```ts
+ * const topUpConfig = await myceliumSDK.funding.getTopUpConfig();
+ * const cashOutConfig = await myceliumSDK.funding.getCashOutConfig();
+ * ```
+ * @category 4. Funding & payouts
+ */
+declare class FundingNamespace {
+    private readonly coinbaseCDP;
+    constructor(coinbaseCDP: CoinbaseCDP);
+    /**
+     * Return all supported countries and payment methods for on-ramp by Coinbase CDP
+     * @public
+     * @category Funding
+     *
+     * @returns @see {@link RampConfigResponse} with supported countries and payment methods for top-up
+     * @throws If API returned an error
+     */
+    getTopUpConfig(): Promise<RampConfigResponse>;
+    /**
+     * Return all supported countries and payment methods for off-ramp by Coinbase CDP
+     * @public
+     * @category Funding
+     *
+     *
+     * @returns @see {@link RampConfigResponse} with supported countries and payment methods for cash out
+     * @throws If API returned an error
+     */
+    getCashOutConfig(): Promise<RampConfigResponse>;
+}
+
+/**
+ * @packageDocumentation
+ * Entry point for the Mycelium SDK
+ *
+ * Exports stable types and the main SDK facade (`MyceliumSDK`)
+ * Internal base classes and implementations are not part of the public API
+ * and are hidden from public documentation
+ */
+
 /**
  * Main SDK facade for integrating wallets and protocols.
  *
  * @public
- * @category Get started
+ * @category 1. Getting started
  * @remarks
  * This class encapsulates:
- * - protocol selection and initialization (`Smart Router`),
+ * - protocol selection and initialization
  * - chain/network management (`ChainManager`),
  * - public wallet namespace (accessible through {@link MyceliumSDK.wallet | wallet}).
  *
  * By default, if no chain config is provided, it uses the public RPC
  * and Bundler for the Base chain
  *
+ * The SDK can be initialized in two ways:
+ * 1. With an API key - fetches configuration from backend automatically
+ * 2. With full configuration - uses provided configuration directly
+ *
  * @example
- * ```ts
- * import { MyceliumSDK, type MyceliumSDKConfig } from '@mycelium-sdk/core';
  *
+ * import { MyceliumSDK, type MyceliumSDKConfig, type BasicMyceliumSDKConfig } from '@mycelium-sdk/core';
+ *
+ * // Option 1: Initialize with API key (fetches config from backend)
+ * const sdk = await MyceliumSDK.init({
+ *   apiKey: 'sk_...'
+ * });
+ *
+ * // Option 2: Initialize with full configuration
  * const config: MyceliumSDKConfig = {
  *   walletsConfig: { /* ... *\/ },
- *   protocolsRouterConfig: { /* ... *\/ },
+ *   protocolsSecurityConfig: { riskLevel: 'low' },
  *   chain: { /* ... *\/ },
  *   coinbaseCDPConfig: { /* ... *\/ },
  *   integratorId: 'MyceliumApp',
  * };
+ * const sdk = await MyceliumSDK.init(config);
  *
- * const sdk = new MyceliumSDK(config);
- *
- * const embeddedWallet = await sdk.wallet.createEmbeddedWallet();
- * const wallet = await sdk.wallet.createSmartWallet({
- *     owners: [embeddedWallet.address],
- *     signer: await embeddedWallet.account(),
- * })
- * const balance = await wallet.getBalance();
- * ```
- */
+ * const {embeddedWalletId, smartWallet} = await sdk.wallet.createAccount();
+ * const balance = await smartWallet.getBalance();
+ *  */
 declare class MyceliumSDK {
     /**
-     * Unified wallet namespace to manage embedded/smart wallets and related operations
+     * Returns a unified wallet namespace to manage embedded/smart wallets and related operations
      * @public
      * @category Wallets
      */
     readonly wallet: WalletNamespace;
+    /**
+     * Protocol namespace to manage protocol related operations
+     * @public
+     * @category Protocols
+     */
+    readonly protocols: ProtocolsNamespace;
+    /**
+     * Ramp namespace to manage ramp operations. Methods are available on {@link RampNamespace}
+     * @internal
+     * @remarks
+     * If the Coinbase CDP configuration is not provided, the ramp functionality will be disabled.
+     * Calling the respective method will throw an error
+     * @category Tools
+     */
+    readonly fundingNamespace: FundingNamespace | null;
     /**
      * Chain manager instance to manage chain related entities
      * @internal
@@ -1488,6 +1589,8 @@ declare class MyceliumSDK {
      * @internal
      */
     private protocol;
+    /** API client for the backend API */
+    apiClient: ApiClient | undefined;
     /**
      * Coinbase CDP instance to Coinbase related and onchain operations using Coinbase CDP API
      * @remarks
@@ -1496,6 +1599,12 @@ declare class MyceliumSDK {
      * @internal
      */
     private coinbaseCDP;
+    /**
+     * Initializes the SDK
+     * @param config SDK configuration (networks, wallets, protocol router settings)
+     * @returns SDK instance
+     */
+    static init(config: BasicMyceliumSDKConfig | MyceliumSDKConfig): Promise<MyceliumSDK>;
     /**
      * Creates a new SDK instance
      *
@@ -1503,41 +1612,27 @@ declare class MyceliumSDK {
      * @throws Throws if an unsupported wallet provider is given
      * @see MyceliumSDKConfig
      */
-    constructor(config: MyceliumSDKConfig);
+    constructor(config: MyceliumSDKConfig, isPremiumAvailable: boolean, apiClient?: ApiClient);
     /**
      * Returns the chain manager instance for multi-chain operations
      * @public
+     * @remarks
+     * More about methods in {@link ChainManager}
      * @category Tools
      *
      * @returns ChainManager instance of the type {@link ChainManager}
      */
     get chainManager(): ChainManager;
     /**
-     * Coinbase CDP configuration methods for ramp operations
+     * Returns a funding namespace to manage top ups & cash outs configurations
      * @public
+     * @remarks
+     * More about methods in {@link FundingNamespace}
      * @category Tools
+     *
+     * @returns Funding namespace of the type {@link FundingNamespace}
      */
-    readonly rampConfig: {
-        /**
-         * Return all supported countries and payment methods for on-ramp by Coinbase CDP
-         * @public
-         * @category Ramp
-         *
-         * @returns @see {@link RampConfigResponse} with supported countries and payment methods for top-up
-         * @throws If API returned an error
-         */
-        getTopUpConfig: () => Promise<RampConfigResponse>;
-        /**
-         * Return all supported countries and payment methods for off-ramp by Coinbase CDP
-         * @public
-         * @category Ramp
-         *
-         *
-         * @returns @see {@link RampConfigResponse} with supported countries and payment methods for cash out
-         * @throws If API returned an error
-         */
-        getCashOutConfig: () => Promise<RampConfigResponse>;
-    };
+    get funding(): FundingNamespace;
     /**
      * Recommends and initializes a protocol based on router settings
      *
@@ -1545,7 +1640,7 @@ declare class MyceliumSDK {
      * @param config Protocol router configuration (e.g. risk level)
      * @returns Selected protocol object of the type {@link Protocol}
      */
-    private findProtocol;
+    private selectProtocol;
     /**
      * Creates a wallet provider (embedded + smart) and combines them
      *
@@ -1565,4 +1660,4 @@ declare class MyceliumSDK {
     private createWalletNamespace;
 }
 
-export { type OffRampUrlResponse as CashOutUrlResponse, DefaultSmartWallet, EmbeddedWallet, MyceliumSDK, type MyceliumSDKConfig, type RampConfigResponse, SmartWallet, type SparkVaultBalance, type SparkVaultTxnResult, type TokenBalance, type OnRampUrlResponse as TopUpUrlResponse, type VaultBalance, type VaultTxnResult, WalletNamespace };
+export { type OffRampUrlResponse as CashOutUrlResponse, DefaultSmartWallet, EmbeddedWallet, FundingNamespace, type RampConfigResponse as FundingOptionsResponse, MyceliumSDK, type MyceliumSDKConfig, ProtocolsNamespace, type ProxyBalance, SmartWallet, type TokenBalance, type OnRampUrlResponse as TopUpUrlResponse, type VaultBalance, type VaultInfo, type VaultTxnResult, type Vaults, WalletNamespace };