@circle-fin/app-kit 1.5.1 → 1.6.0

package/index.cjs

@@ -1074,6 +1074,35 @@ function createUnsupportedSwapRouteError(tokenIn, tokenOut, chain) {
     };
     return new KitError(errorDetails);
 }
+/**
+ * Creates error for unsupported earn route.
+ *
+ * This error is thrown when no available earn provider supports the requested
+ * operation on the specified chain.
+ *
+ * @param operation - Earn operation name
+ * @param chain - Chain name where the earn operation was attempted
+ * @returns KitError with specific earn route details
+ *
+ * @example
+ * ```typescript
+ * import { createUnsupportedEarnRouteError } from '@core/errors'
+ *
+ * throw createUnsupportedEarnRouteError('deposit', 'Ethereum')
+ * // Message: "Earn deposit on Ethereum is not supported by any available provider."
+ * ```
+ */
+function createUnsupportedEarnRouteError(operation, chain) {
+    const errorDetails = {
+        ...InputError.UNSUPPORTED_ROUTE,
+        recoverability: 'FATAL',
+        message: `Earn ${operation} on ${chain} is not supported by any available provider.`,
+        cause: {
+            trace: { operation, chain },
+        },
+    };
+    return new KitError(errorDetails);
+}
 /**
  * Creates error for unsupported token on chain.
  *
@@ -3217,7 +3246,7 @@ function handleTimeoutError(serviceName, operation, error) {
  * @returns `true` when `error.responseBody` is a non-null object
  * @internal
  */
-function hasResponseBody(error) {
+function hasResponseBody$1(error) {
     return (typeof error === 'object' &&
         error !== null &&
         'responseBody' in error &&
@@ -3230,10 +3259,12 @@ function hasResponseBody(error) {
  *
  * @param error - The raw error from the HTTP layer
  * @returns The parsed body cast to {@link ApiErrorResponseBody}, or undefined
+ * @throws Never. Returns `undefined` when the error does not carry a valid
+ *   `responseBody`.
  * @internal
  */
 function extractResponseBody(error) {
-    if (!hasResponseBody(error)) {
+    if (!hasResponseBody$1(error)) {
         return undefined;
     }
     return error.responseBody;
@@ -3365,6 +3396,224 @@ function extractHttpStatusCode(msg) {
     return null;
 }
 
+/**
+ * Standardized error definitions for Earn/Zenith operations.
+ *
+ * These error codes provide fine-grained categorization of failures
+ * from the Zenith earn service, enabling SDK consumers to distinguish
+ * between input errors (fix your request) and service errors (retry later).
+ *
+ * Error code ranges:
+ * - 1100-1104: INPUT errors — invalid inputs, unsupported configurations
+ * - 8100-8103: SERVICE errors — retryable backend/provider failures
+ *
+ * @example
+ * ```typescript
+ * import { EarnError, isInputError, isRetryableError } from '@circle-fin/earn-kit'
+ *
+ * try {
+ *   await earnKit.deposit(params)
+ * } catch (error) {
+ *   if (isInputError(error)) {
+ *     // Fix the request: vault doesn't exist, chain not supported, etc.
+ *   }
+ *   if (isRetryableError(error)) {
+ *     // Try again: signing timed out, provider temporarily unavailable, etc.
+ *   }
+ * }
+ * ```
+ */
+const EarnError = {
+    /** The requested vault does not exist for the provided chain. */
+    VAULT_NOT_FOUND: {
+        code: 1100,
+        name: 'EARN_VAULT_NOT_FOUND',
+        type: 'INPUT',
+    },
+    /** The specified blockchain is not supported for earn operations. */
+    UNSUPPORTED_CHAIN: {
+        code: 1101,
+        name: 'EARN_UNSUPPORTED_CHAIN',
+        type: 'INPUT',
+    },
+    /** The vault's underlying asset is not supported. */
+    UNSUPPORTED_VAULT: {
+        code: 1102,
+        name: 'EARN_UNSUPPORTED_VAULT',
+        type: 'INPUT',
+    },
+    /** The submitted signature could not be verified. */
+    SIGNATURE_REJECTED: {
+        code: 1103,
+        name: 'EARN_SIGNATURE_REJECTED',
+        type: 'INPUT',
+    },
+    /** General input validation failure (invalid ID, batch size, etc.). */
+    INVALID_INPUT: {
+        code: 1104,
+        name: 'EARN_INVALID_INPUT',
+        type: 'INPUT',
+    },
+    /** The proxy signing call failed — retryable. */
+    SIGNING_FAILED: {
+        code: 8100,
+        name: 'EARN_SIGNING_FAILED',
+        type: 'SERVICE',
+    },
+    /** An external provider API request failed — retryable. */
+    PROVIDER_ERROR: {
+        code: 8101,
+        name: 'EARN_PROVIDER_ERROR',
+        type: 'SERVICE',
+    },
+    /** Failed to fetch reward data — retryable. */
+    REWARDS_FETCH_FAILED: {
+        code: 8102,
+        name: 'EARN_REWARDS_FETCH_FAILED',
+        type: 'SERVICE',
+    },
+    /** An internal earn service error occurred — retryable. */
+    INTERNAL_ERROR: {
+        code: 8103,
+        name: 'EARN_INTERNAL_ERROR',
+        type: 'SERVICE',
+    },
+};
+
+function hasResponseBody(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'responseBody' in error &&
+        typeof error['responseBody'] === 'object' &&
+        error['responseBody'] !== null);
+}
+function extractEarnResponseBody(error) {
+    if (!hasResponseBody(error)) {
+        return undefined;
+    }
+    return error.responseBody;
+}
+function getOptionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Maps earn service backend error codes (380xxx) to typed EarnError constants
+ * with correct recoverability.
+ *
+ * INPUT errors (FATAL) — fix your request:
+ * - vault-not-found, unsupported-chain, unsupported-vault,
+ *   signature-rejected, invalid-id, invalid-batch-size, position-not-registered,
+ *   withdrawal-max-exceeded, insufficient-balance
+ *
+ * SERVICE errors (RETRYABLE) — try again later:
+ * - signing-failed, provider-error, rewards-fetch-failed,
+ *   internal-error, vault-refresh-busy, bridge failures
+ *
+ * Unrecognized codes fall through to `parseApiError` for HTTP-status-based
+ * handling.
+ *
+ * @internal
+ */
+const EARN_CODE_MAP = new Map([
+    // Common (380_0XX)
+    [380001, { errorDef: EarnError.INVALID_INPUT, recoverability: 'FATAL' }],
+    [
+        380002,
+        {
+            errorDef: RateLimitError.RATE_LIMIT_EXCEEDED,
+            recoverability: 'RETRYABLE',
+        },
+    ],
+    // Shared (380_1XX)
+    [380100, { errorDef: EarnError.VAULT_NOT_FOUND, recoverability: 'FATAL' }],
+    [380101, { errorDef: EarnError.SIGNATURE_REJECTED, recoverability: 'FATAL' }],
+    [380102, { errorDef: EarnError.UNSUPPORTED_CHAIN, recoverability: 'FATAL' }],
+    // Vault Discovery (380_3XX)
+    [380300, { errorDef: EarnError.VAULT_NOT_FOUND, recoverability: 'FATAL' }],
+    [380301, { errorDef: EarnError.INVALID_INPUT, recoverability: 'FATAL' }],
+    [380302, { errorDef: EarnError.PROVIDER_ERROR, recoverability: 'RETRYABLE' }],
+    [380303, { errorDef: EarnError.UNSUPPORTED_VAULT, recoverability: 'FATAL' }],
+    // EarnKit (380_4XX)
+    [380400, { errorDef: EarnError.UNSUPPORTED_CHAIN, recoverability: 'FATAL' }],
+    [380401, { errorDef: EarnError.SIGNING_FAILED, recoverability: 'RETRYABLE' }],
+    [
+        380402,
+        { errorDef: EarnError.REWARDS_FETCH_FAILED, recoverability: 'RETRYABLE' },
+    ],
+    [380403, { errorDef: EarnError.INTERNAL_ERROR, recoverability: 'RETRYABLE' }],
+    [380404, { errorDef: EarnError.PROVIDER_ERROR, recoverability: 'RETRYABLE' }],
+    [380405, { errorDef: EarnError.PROVIDER_ERROR, recoverability: 'RETRYABLE' }],
+    [380406, { errorDef: EarnError.INTERNAL_ERROR, recoverability: 'RETRYABLE' }],
+    [380407, { errorDef: EarnError.INVALID_INPUT, recoverability: 'FATAL' }],
+    [380408, { errorDef: EarnError.INVALID_INPUT, recoverability: 'FATAL' }],
+    [380409, { errorDef: EarnError.INVALID_INPUT, recoverability: 'FATAL' }],
+    // Bridge (380_5XX)
+    [380500, { errorDef: EarnError.PROVIDER_ERROR, recoverability: 'RETRYABLE' }],
+    [380501, { errorDef: EarnError.SIGNING_FAILED, recoverability: 'RETRYABLE' }],
+    [380502, { errorDef: EarnError.PROVIDER_ERROR, recoverability: 'RETRYABLE' }],
+]);
+/**
+ * Parses Earn Service API errors into typed KitError instances using
+ * earn service backend error codes for fine-grained categorization.
+ *
+ * When the response body contains a recognized earn service backend code
+ * (380xxx), the error is mapped to a specific EarnError constant with the
+ * correct recoverability. The original backend error code is preserved in
+ * `error.cause.trace.earnServiceCode`.
+ *
+ * When the code is unrecognized or the response body is unavailable,
+ * falls through to the generic `parseApiError` for HTTP-status-based handling.
+ *
+ * @param error - The raw error from the API call
+ * @param context - Context information (operation name)
+ * @returns A structured KitError instance
+ * @throws Never — all error paths are caught and returned as a `KitError`
+ *   instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await earnServiceApi.deposit(params)
+ * } catch (error) {
+ *   throw parseEarnApiError(error, { operation: 'deposit' })
+ * }
+ * ```
+ */
+function parseEarnApiError(error, context) {
+    // If it's already a KitError, return it as-is
+    if (error instanceof KitError) {
+        return error;
+    }
+    const responseBody = extractEarnResponseBody(error);
+    const earnServiceCode = typeof responseBody?.['code'] === 'number'
+        ? responseBody['code']
+        : undefined;
+    if (earnServiceCode !== undefined) {
+        const mapping = EARN_CODE_MAP.get(earnServiceCode);
+        if (mapping !== undefined) {
+            const message = getOptionalString(responseBody?.['externalMessage']) ??
+                getOptionalString(responseBody?.['message']) ??
+                `Earn Service ${context.operation ?? 'API'} failed`;
+            return new KitError({
+                ...mapping.errorDef,
+                recoverability: mapping.recoverability,
+                message,
+                cause: {
+                    trace: {
+                        earnServiceCode,
+                        originalError: error,
+                    },
+                },
+            });
+        }
+    }
+    // Fallthrough: unrecognized code or no response body — use HTTP-status-based parsing
+    return parseApiError(error, {
+        ...context,
+        service: context.service ?? 'Earn Service',
+    });
+}
+
 // -----------------------------------------------------------------------------
 // Blockchain Enum
 // -----------------------------------------------------------------------------
@@ -3724,24 +3973,22 @@ exports.UnifiedBalanceChain = void 0;
  * Enumeration of blockchains that support earn (vault deposit/withdraw)
  * operations through the Earn Kit.
  *
- * Currently only Ethereum mainnet is supported. Additional chains
- * will be added as vault protocol support expands.
- *
  * @example
  * ```typescript
  * import { EarnChain } from '@core/chains'
  *
  * const result = await earnKit.deposit({
- *   from: { adapter, chain: EarnChain.Ethereum },
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
  *   vaultAddress: '0x...',
  *   amount: '100',
  * })
  * ```
  */
-var EarnChain;
+// Values must match Blockchain enum members exactly.
+exports.EarnChain = void 0;
 (function (EarnChain) {
-    EarnChain["Ethereum"] = "Ethereum";
-})(EarnChain || (EarnChain = {}));
+    EarnChain["Arc_Testnet"] = "Arc_Testnet";
+})(exports.EarnChain || (exports.EarnChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -7481,7 +7728,7 @@ const bridgeChainIdentifierSchema = zod.z.union([
  * Zod schema for validating earn-specific chain identifiers.
  *
  * Validate that the provided chain is supported for earn (vault
- * deposit/withdraw) operations. Currently only Ethereum is
+ * deposit/withdraw) operations. Currently only Arc Testnet is
  * supported.
  *
  * Accept an EarnChain enum value, a matching string literal, or
@@ -7490,26 +7737,26 @@ const bridgeChainIdentifierSchema = zod.z.union([
  * @example
  * ```typescript
  * import { earnChainIdentifierSchema } from '@core/chains'
- * import { EarnChain, Ethereum } from '@core/chains'
+ * import { ArcTestnet, EarnChain } from '@core/chains'
  *
  * // Valid
- * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
- * earnChainIdentifierSchema.parse('Ethereum')
- * earnChainIdentifierSchema.parse(Ethereum)
+ * earnChainIdentifierSchema.parse(EarnChain.Arc_Testnet)
+ * earnChainIdentifierSchema.parse('Arc_Testnet')
+ * earnChainIdentifierSchema.parse(ArcTestnet)
  *
  * // Invalid (throws ZodError)
  * earnChainIdentifierSchema.parse('Solana')
  * ```
  */
-zod.z.union([
-    zod.z.string().refine((val) => val in EarnChain, (val) => ({
+const earnChainIdentifierSchema = zod.z.union([
+    zod.z.string().refine((val) => val in exports.EarnChain, (val) => ({
         message: `"${val}" is not a supported earn chain. ` +
-            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+            `Supported chains: ${Object.values(exports.EarnChain).join(', ')}`,
     })),
-    zod.z.nativeEnum(EarnChain),
-    chainDefinitionSchema$2.refine((chain) => chain.chain in EarnChain, (chain) => ({
+    zod.z.nativeEnum(exports.EarnChain),
+    chainDefinitionSchema$2.refine((chain) => chain.chain in exports.EarnChain, (chain) => ({
         message: `"${chain.chain}" is not a supported earn chain. ` +
-            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+            `Supported chains: ${Object.values(exports.EarnChain).join(', ')}`,
     })),
 ]);
 /**
@@ -8359,7 +8606,7 @@ function handleAddressError(path, _code, _message, paramsObj) {
  * Default configuration values for the API polling utility.
  * @internal
  */
-const DEFAULT_CONFIG$2 = {
+const DEFAULT_CONFIG$3 = {
     timeout: 2_000,
     maxRetries: 10,
     retryDelay: 200,
@@ -8568,10 +8815,10 @@ const isRetryableError = (error) => {
 const pollApiWithValidation = async (url, method, isValidType, config = {}, body) => {
     // Merge headers so that 'User-Agent' is always present and not overwritten
     const effectiveConfig = {
-        ...DEFAULT_CONFIG$2,
+        ...DEFAULT_CONFIG$3,
         ...config,
         headers: {
-            ...DEFAULT_CONFIG$2.headers,
+            ...DEFAULT_CONFIG$3.headers,
             ...(config.headers ?? {}),
             // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
             // This is why we use the 'X-User-Agent' header instead.
@@ -10078,7 +10325,7 @@ zod.z.custom((value) => {
  * formatAmount({ value: '3141592000000000000', token: 'NATIVE', chain: Ethereum }) // "3.141592"
  * ```
  */
-const formatAmount$1 = (params) => {
+const formatAmount$2 = (params) => {
     const { value, token, tokens } = params;
     // Handle NATIVE token first (chain-specific decimals)
     if (token === 'NATIVE') {
@@ -10798,11 +11045,11 @@ function emitResultStepErrorTelemetry(failedStep, stepEventMap, fallbackEventTyp
     void emitAnalyticsLog(buildPayload$1(config, stepEntry?.[1] ?? fallbackEventType, errorDetails, context));
 }
 
-var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.10.0";
-var pkg$3 = {
-	name: name$2,
-	version: version$3};
+var name$3 = "@circle-fin/bridge-kit";
+var version$4 = "1.10.1";
+var pkg$4 = {
+	name: name$3,
+	version: version$4};
 
 const assertCustomFeePolicySymbol$2 = Symbol('assertCustomFeePolicy');
 /**
@@ -11098,7 +11345,9 @@ const hexStringSchema = zod.z
  * console.log(result.success) // true
  * ```
  */
-const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)');
+const evmAddressSchema = hexStringSchema
+    .refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)')
+    .transform((value) => value);
 /**
  * Schema for validating transaction hashes.
  *
@@ -11119,6 +11368,29 @@ const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42,
  * ```
  */
 hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
+/**
+ * Schema for validating EVM signatures.
+ *
+ * This schema validates that a string is a properly formatted 65-byte EVM
+ * signature:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 132 characters long (0x + 130 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { evmSignatureSchema } from '@core/adapter'
+ *
+ * const validSignature = `0x${'ab'.repeat(65)}`
+ *
+ * const result = evmSignatureSchema.safeParse(validSignature)
+ * console.log(result.success) // true
+ * ```
+ */
+const evmSignatureSchema = hexStringSchema
+    .refine((value) => value.length === 132, 'EVM signature must be exactly 132 characters long (0x + 130 hex characters)')
+    .transform((value) => value);
 /**
  * Schema for validating base58-encoded strings.
  *
@@ -11773,7 +12045,7 @@ function createRecipientAddressValidator() {
  *
  * Optionally includes address for developer-controlled adapters.
  */
-const adapterContextSchema$6 = zod.z.object({
+const adapterContextSchema$7 = zod.z.object({
     adapter: adapterSchema$1,
     chain: bridgeChainIdentifierSchema,
     address: zod.z.string().optional(),
@@ -11783,7 +12055,7 @@ const adapterContextSchema$6 = zod.z.object({
  * Contains an explicit recipientAddress along with adapter and chain.
  * The address format is validated based on the chain type (EVM or Solana).
  */
-const bridgeDestinationWithAddressSchema = adapterContextSchema$6
+const bridgeDestinationWithAddressSchema = adapterContextSchema$7
     .extend({
     recipientAddress: zod.z.string().min(1, 'Recipient address is required'),
     useForwarder: zod.z.boolean().optional(),
@@ -11793,7 +12065,7 @@ const bridgeDestinationWithAddressSchema = adapterContextSchema$6
  * Schema for validating AdapterContext with optional useForwarder.
  * Extends adapterContextSchema with the useForwarder flag.
  */
-const adapterContextWithForwarderSchema = adapterContextSchema$6.extend({
+const adapterContextWithForwarderSchema = adapterContextSchema$7.extend({
     useForwarder: zod.z.boolean().optional(),
 });
 /**
@@ -11874,7 +12146,7 @@ const bridgeDestinationSchema = zod.z.union([
  * ```
  */
 const bridgeParamsWithChainIdentifierSchema = zod.z.object({
-    from: adapterContextSchema$6.strict(),
+    from: adapterContextSchema$7.strict(),
     to: bridgeDestinationSchema,
     amount: zod.z
         .string()
@@ -12940,7 +13212,7 @@ function resolveBridgeInvocation$1(invocationMeta) {
     const bridgeKitCaller = {
         type: 'kit',
         name: 'BridgeKit',
-        version: pkg$3.version,
+        version: pkg$4.version,
     };
     // Create default runtime and tokens for invocation context resolution
     const defaults = {
@@ -13210,7 +13482,7 @@ async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet)
     }
     // Fetch the fee tiers from the API
     const url = buildFastBurnFeeUrl(sourceDomain, destinationDomain, isTestnet);
-    const response = await pollApiGet(url, isFastBurnFeeResponse, DEFAULT_CONFIG$2);
+    const response = await pollApiGet(url, isFastBurnFeeResponse, DEFAULT_CONFIG$3);
     // Validate that we have at least one fee tier
     if (response.length === 0) {
         throw new KitError({
@@ -13559,7 +13831,7 @@ async function fetchForwardingFee(sourceDomain, destinationDomain, isTestnet, fi
     }
     // Fetch the fee tiers from the API with forward=true
     const url = buildForwardingFeeUrl(sourceDomain, destinationDomain, isTestnet);
-    const response = await pollApiGet(url, isForwardingFeeResponse, DEFAULT_CONFIG$2);
+    const response = await pollApiGet(url, isForwardingFeeResponse, DEFAULT_CONFIG$3);
     // Validate that we have at least one fee tier
     if (response.length === 0) {
         throw new KitError({
@@ -13626,7 +13898,7 @@ const CCTPv2MinFinalityThreshold = {
  * Default configuration values for the attestation fetcher.
  * @internal
  */
-const DEFAULT_CONFIG$1 = {
+const DEFAULT_CONFIG$2 = {
     timeout: 2_000, // 2 seconds
     maxRetries: 30 * 20, // 30 * 20 * 2 seconds (from the retry delay) = 20 minutes (to account for slow transfers maximum time based on confirmations)
     retryDelay: 2_000, // 2 seconds
@@ -13797,7 +14069,7 @@ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet) => {
  */
 const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {}) => {
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = { ...DEFAULT_CONFIG$1, ...config };
+    const effectiveConfig = { ...DEFAULT_CONFIG$2, ...config };
     return await pollApiGet(url, isAttestationResponse, effectiveConfig);
 };
 /**
@@ -13843,7 +14115,7 @@ const fetchAttestationWithoutStatusCheck = async (sourceDomainId, transactionHas
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
     // Use minimal retries since we're just fetching existing data
     const effectiveConfig = {
-        ...DEFAULT_CONFIG$1,
+        ...DEFAULT_CONFIG$2,
         maxRetries: 3,
         ...config,
     };
@@ -13908,7 +14180,7 @@ const isReAttestedAttestationResponse = (obj) => {
  */
 const fetchReAttestedAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {}) => {
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = { ...DEFAULT_CONFIG$1, ...config };
+    const effectiveConfig = { ...DEFAULT_CONFIG$2, ...config };
     return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
 };
 /**
@@ -13983,7 +14255,7 @@ const requestReAttestation = async (nonce, isTestnet, config = {}) => {
     const url = buildReAttestUrl(nonce, isTestnet);
     // Use minimal retries since we're just submitting a request, not polling for state
     const effectiveConfig = {
-        ...DEFAULT_CONFIG$1,
+        ...DEFAULT_CONFIG$2,
         maxRetries: 3,
         ...config,
     };
@@ -15238,7 +15510,7 @@ const isRelayerMintConfirmed = (obj) => {
  */
 const fetchRelayerMint = async (sourceDomainId, transactionHash, isTestnet, config = {}) => {
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = { ...DEFAULT_CONFIG$1, ...config };
+    const effectiveConfig = { ...DEFAULT_CONFIG$2, ...config };
     let response;
     try {
         response = await pollApiGet(url, isRelayerMintConfirmed, effectiveConfig);
@@ -15750,9 +16022,9 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain, statusCo
     return step;
 }
 
-var version$2 = "1.8.1";
-var pkg$2 = {
-	version: version$2};
+var version$3 = "1.8.2";
+var pkg$3 = {
+	version: version$3};
 
 /**
  * Provider caller component for bridge operations.
@@ -15760,7 +16032,7 @@ var pkg$2 = {
 const BRIDGE_CALLER = {
     type: 'provider',
     name: 'CCTPV2BridgingProvider.bridge',
-    version: pkg$2.version,
+    version: pkg$3.version,
 };
 /**
  * Resolve invocation context for bridge operations.
@@ -16140,7 +16412,7 @@ async function bridgeReAttest({ params, provider, }, burnTxHash) {
 const RETRY_CALLER = {
     type: 'provider',
     name: 'CCTPV2BridgingProvider.retry',
-    version: pkg$2.version,
+    version: pkg$3.version,
 };
 /**
  * Resolve invocation context for retry operations.
@@ -17346,7 +17618,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
  * The default providers that will be used in addition to the providers provided
  * to the BridgeKit constructor.
  */
-const getDefaultProviders$2 = () => [new CCTPV2BridgingProvider()];
+const getDefaultProviders$3 = () => [new CCTPV2BridgingProvider()];
 
 /**
  * A helper function to get a function that transforms an amount into a human-readable string or a bigint string.
@@ -17354,7 +17626,7 @@ const getDefaultProviders$2 = () => [new CCTPV2BridgingProvider()];
  * @returns A function that transforms an amount into a human-readable string or a bigint string.
  */
 const getAmountTransformer = (formatDirection) => formatDirection === 'to-human-readable'
-    ? (params) => formatAmount$1(params)
+    ? (params) => formatAmount$2(params)
     : (params) => parseAmount(params).toString();
 /**
  * Format the bridge result into human-readable string values for the user or bigint string values for internal use.
@@ -17444,14 +17716,14 @@ const BRIDGE_STEP_EVENT_MAP = [
 ];
 
 /** SDK name used in telemetry payloads. */
-const SDK_NAME$2 = resolveKitSdkName(pkg$3.name);
+const SDK_NAME$2 = resolveKitSdkName(pkg$4.name);
 /**
  * BridgeKit caller component for retry and estimate operations.
  */
 const BRIDGE_KIT_CALLER = {
     type: 'kit',
     name: 'BridgeKit',
-    version: pkg$3.version,
+    version: pkg$4.version,
 };
 /**
  * Merge BridgeKit's caller into the invocation metadata for retry operations.
@@ -17546,13 +17818,13 @@ class BridgeKit {
      */
     constructor(config = {}) {
         // Handle provider configuration
-        const defaultProviders = getDefaultProviders$2();
+        const defaultProviders = getDefaultProviders$3();
         this.providers = [...defaultProviders, ...(config.providers ?? [])];
         this.actionDispatcher = new Actionable();
         this.disableErrorReporting = config.disableErrorReporting === true;
         this.telemetryConfig = {
             sdkName: SDK_NAME$2,
-            sdkVersion: pkg$3.version,
+            sdkVersion: pkg$4.version,
             disabled: this.disableErrorReporting,
         };
         for (const provider of this.providers) {
@@ -18081,7 +18353,7 @@ class BridgeKit {
  * @packageDocumentation
  */
 // Auto-register this kit for user agent tracking
-registerKit(`${pkg$3.name}/${pkg$3.version}`);
+registerKit(`${pkg$4.name}/${pkg$4.version}`);
 
 /**
  * Create a BridgeKit instance with optional developer fee configuration.
@@ -18148,11 +18420,11 @@ const createBridgeKit = (context) => {
     return kit;
 };
 
-var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.2.1";
-var pkg$1 = {
-	name: name$1,
-	version: version$1};
+var name$2 = "@circle-fin/swap-kit";
+var version$2 = "1.2.2";
+var pkg$2 = {
+	name: name$2,
+	version: version$2};
 
 /**
  * @packageDocumentation
@@ -18249,7 +18521,7 @@ const serviceSwapConfigSchema = zod.z.object({
  * @remarks
  * Optionally includes address for developer-controlled adapters.
  */
-const adapterContextSchema$5 = zod.z.object({
+const adapterContextSchema$6 = zod.z.object({
     adapter: adapterSchema$1,
     chain: chainIdentifierSchema,
     address: zod.z.string().optional(),
@@ -18271,7 +18543,7 @@ const adapterContextSchema$5 = zod.z.object({
  * ```
  */
 const serviceSwapParamsSchema = zod.z.object({
-    from: adapterContextSchema$5,
+    from: adapterContextSchema$6,
     tokenIn: zod.z
         .string({
         required_error: 'tokenIn is required',
@@ -18486,7 +18758,7 @@ const validateServiceSwapParams = (params) => {
  *
  * @internal
  */
-const DEFAULT_CONFIG = {
+const DEFAULT_CONFIG$1 = {
     timeout: 30_000, // 30 seconds - matches load balancer timeout
     maxRetries: 3, // 3 retries as per requirements
     retryDelay: 200, // 200ms between retries
@@ -19151,6 +19423,46 @@ const parseCreateSwapResponse = (obj) => createSwapResponseSchema.parse(obj);
  * ```
  */
 const isGetSwapStatusResponse = (obj) => getSwapStatusResponseSchema.safeParse(obj).success;
+/**
+ * Validates that an API key is properly formatted for Circle Stablecoin Service.
+ *
+ * This function performs validation on API keys to ensure they conform to the
+ * expected format before making API requests. The key must follow the structure:
+ * `KIT_KEY:keyId:keySecret`
+ *
+ * @param apiKey - The API key to validate (can be any type for graceful handling).
+ * @returns True if the API key is valid, false otherwise.
+ *
+ * @remarks
+ * This function handles invalid inputs gracefully by returning false rather than
+ * throwing errors. It validates:
+ * - The key starts with the `KIT_KEY:` prefix
+ * - Contains exactly three colon-separated parts
+ * - keyId and keySecret contain only valid characters (alphanumeric, `-`, `_`, `.`)
+ * - keyId and keySecret are non-empty
+ * - No whitespace anywhere in the API key (including leading, trailing, or internal)
+ *
+ * Valid characters in keyId and keySecret: `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
+ *
+ * @example
+ * ```typescript
+ * import { isValidApiKey } from '@core/service-client'
+ *
+ * // Valid API key
+ * const isValid = isValidApiKey('KIT_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
+ * console.log(isValid) // true
+ *
+ * ```
+ */
+const isValidApiKey = (apiKey) => {
+    // Handle invalid input types
+    if (typeof apiKey !== 'string') {
+        return false;
+    }
+    const apiKeyPattern = /^KIT_KEY:[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$/;
+    // Validate without trimming - any whitespace will cause validation to fail
+    return apiKeyPattern.test(apiKey);
+};
 
 /**
  * @packageDocumentation
@@ -19221,9 +19533,9 @@ const createSwap = async (params) => {
     // Remove the API key from the request body
     const { apiKey, ...requestBody } = validatedParams;
     const effectiveConfig = {
-        ...DEFAULT_CONFIG,
+        ...DEFAULT_CONFIG$1,
         headers: {
-            ...DEFAULT_CONFIG.headers,
+            ...DEFAULT_CONFIG$1.headers,
             Authorization: `Bearer ${apiKey}`,
         },
     };
@@ -19376,9 +19688,9 @@ const getQuote = async (params) => {
     const url = buildQuoteUrl(validatedParams);
     // Merge default config with Authorization header
     const effectiveConfig = {
-        ...DEFAULT_CONFIG,
+        ...DEFAULT_CONFIG$1,
         headers: {
-            ...DEFAULT_CONFIG.headers,
+            ...DEFAULT_CONFIG$1.headers,
             Authorization: `Bearer ${validatedParams.apiKey}`,
         },
     };
@@ -19431,9 +19743,9 @@ const getSwapStatus = async (params) => {
     }
     const url = buildSwapStatusUrl(result.data);
     const effectiveConfig = {
-        ...DEFAULT_CONFIG,
+        ...DEFAULT_CONFIG$1,
         headers: {
-            ...DEFAULT_CONFIG.headers,
+            ...DEFAULT_CONFIG$1.headers,
             Authorization: `Bearer ${result.data.apiKey}`,
         },
     };
@@ -22308,6 +22620,27 @@ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
  */
 const NATIVE_TOKEN_ADDRESS$1 = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
 
+const hexBytesSchema$1 = zod.z
+    .string()
+    .regex(/^0x([0-9a-fA-F]{2})*$/, {
+    message: 'value must be a 0x-prefixed even-length hex string',
+})
+    .transform((value) => value);
+zod.z
+    .object({
+    executeParams: zod.z.object({}).passthrough(),
+    signature: evmSignatureSchema,
+    tokenInputs: zod.z.array(zod.z.object({
+        permitType: zod.z.nativeEnum(PermitType),
+        token: evmAddressSchema,
+        amount: zod.z.bigint().refine((value) => value >= 0n, {
+            message: 'amount must be a non-negative bigint',
+        }),
+        permitCalldata: hexBytesSchema$1,
+    })),
+})
+    .passthrough();
+
 /**
  * Solana mainnet genesis hash
  */
@@ -24518,21 +24851,21 @@ function buildInsufficientSwapBalanceError(tokenSymbol, walletAddress, currentBa
     const displaySymbol = resolvedSymbol ?? tokenSymbol;
     // Format human-readable amounts if we can resolve the token, otherwise use base units only
     const currentFormatted = canFormat
-        ? formatAmount$1({
+        ? formatAmount$2({
             value: currentBalance.toString(),
             token: resolvedSymbol,
             chain,
         })
         : null;
     const requiredFormatted = canFormat
-        ? formatAmount$1({
+        ? formatAmount$2({
             value: requiredAmount.toString(),
             token: resolvedSymbol,
             chain,
         })
         : null;
     const shortfallFormatted = canFormat
-        ? formatAmount$1({
+        ? formatAmount$2({
             value: shortfall.toString(),
             token: resolvedSymbol,
             chain,
@@ -24618,7 +24951,7 @@ async function formatTokenValue(value, token, chain, adapter) {
     if (resolvedSymbol) {
         if (isSwapToken(resolvedSymbol)) {
             return {
-                amount: formatAmount$1({
+                amount: formatAmount$2({
                     value,
                     token: resolvedSymbol,
                     chain,
@@ -24659,7 +24992,7 @@ async function formatTokenValue(value, token, chain, adapter) {
  * i.e. 1 + 0.2 + 0.1 = 1.3. Use the greater of (local estimate × this multiplier)
  * or the proxy's gasLimit.
  */
-const GAS_SAFETY_MULTIPLIER = 1.3;
+const GAS_SAFETY_MULTIPLIER$1 = 1.3;
 const TOKEN_REGISTRY = createTokenRegistry();
 /**
  * Enhances a KitError with transaction details (txHash and explorerUrl).
@@ -25092,7 +25425,7 @@ class StablecoinServiceSwapProvider {
             const gasEstimate = await params.from.adapter.calculateTransactionFee(gasLimitUnits, undefined, // Use default 5% buffer
             chain);
             // Format the fee from wei to human-readable native currency amount
-            estimatedGasFee = formatAmount$1({
+            estimatedGasFee = formatAmount$2({
                 value: gasEstimate.fee,
                 token: 'NATIVE',
                 chain,
@@ -25105,7 +25438,7 @@ class StablecoinServiceSwapProvider {
             const gasEstimate = await params.from.adapter.calculateTransactionFee(300000n, undefined, // Use default buffer
             chain);
             // Format the fee from lamports to human-readable SOL amount
-            estimatedGasFee = formatAmount$1({
+            estimatedGasFee = formatAmount$2({
                 value: gasEstimate.fee,
                 token: 'NATIVE',
                 chain,
@@ -25639,7 +25972,7 @@ class StablecoinServiceSwapProvider {
                 const localEstimate = await preparedAction.estimate();
                 const localGas = Number(localEstimate?.gas);
                 if (Number.isFinite(localGas) && localGas > 0) {
-                    const localWithBuffer = Math.ceil(localGas * GAS_SAFETY_MULTIPLIER);
+                    const localWithBuffer = Math.ceil(localGas * GAS_SAFETY_MULTIPLIER$1);
                     if (Number.isFinite(localWithBuffer) && localWithBuffer > 0) {
                         effectiveGasLimit = Math.max(localWithBuffer, proxyGasLimit);
                     }
@@ -25735,7 +26068,7 @@ class StablecoinServiceSwapProvider {
  * Must always contain both adapter and chain explicitly.
  * Optionally includes address for developer-controlled adapters.
  */
-const adapterContextSchema$4 = zod.z.object({
+const adapterContextSchema$5 = zod.z.object({
     adapter: adapterSchema$1,
     chain: swapChainIdentifierSchema,
     address: zod.z.string().optional(),
@@ -25951,7 +26284,7 @@ const amountInSchema = zod.z
  * ```
  */
 const swapParamsSchema = zod.z.object({
-    from: adapterContextSchema$4,
+    from: adapterContextSchema$5,
     tokenIn: swapTokenSchema,
     tokenOut: swapTokenSchema,
     amountIn: amountInSchema,
@@ -28482,7 +28815,7 @@ async function swap$1(context, params) {
  * )
  * ```
  */
-function getSupportedChains$3(context) {
+function getSupportedChains$4(context) {
     const swapChains = new Set(Object.values(exports.SwapChain));
     // Collect all supported chains from all providers
     // Use optional chaining to gracefully handle providers without supportedChains
@@ -28669,7 +29002,7 @@ function removeCustomFeePolicy(context) {
  * @returns An array containing the default StablecoinServiceSwapProvider
  * @internal
  */
-const getDefaultProviders$1 = () => [new StablecoinServiceSwapProvider()];
+const getDefaultProviders$2 = () => [new StablecoinServiceSwapProvider()];
 /**
  * Create a SwapKit context with validated configuration.
  *
@@ -28729,7 +29062,7 @@ const getDefaultProviders$1 = () => [new StablecoinServiceSwapProvider()];
  */
 function createSwapKitContext(config = {}) {
     // Initialize default providers
-    const defaultProviders = getDefaultProviders$1();
+    const defaultProviders = getDefaultProviders$2();
     // Merge default and custom providers
     const providers = [...defaultProviders, ...(config.providers ?? [])];
     // Build base context without fee policy
@@ -28757,7 +29090,7 @@ const SWAP_EVENT_TYPES = {
 };
 
 /** SDK name used in telemetry payloads. */
-const SDK_NAME$1 = resolveKitSdkName(pkg$1.name);
+const SDK_NAME$1 = resolveKitSdkName(pkg$2.name);
 /**
  * A high-level class-based interface for single-chain token swap operations.
  *
@@ -28884,7 +29217,7 @@ class SwapKit {
         this.disableErrorReporting = config.disableErrorReporting === true;
         this.telemetryConfig = {
             sdkName: SDK_NAME$1,
-            sdkVersion: pkg$1.version,
+            sdkVersion: pkg$2.version,
             disabled: this.disableErrorReporting,
         };
     }
@@ -29028,7 +29361,7 @@ class SwapKit {
      * ```
      */
     getSupportedChains() {
-        return getSupportedChains$3(this.context);
+        return getSupportedChains$4(this.context);
     }
     /**
      * Set a custom fee policy for all swap operations.
@@ -29152,7 +29485,7 @@ class SwapKit {
  * @packageDocumentation
  */
 // Auto-register this kit for user agent tracking
-registerKit(`${pkg$1.name}/${pkg$1.version}`);
+registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 /**
  * Create a SwapKit instance with optional developer fee configuration.
@@ -29250,288 +29583,3138 @@ const createSwapKit = (context) => {
     return kit;
 };
 
+var name$1 = "@circle-fin/earn-kit";
+var version$1 = "1.0.0";
+var pkg$1 = {
+	name: name$1,
+	version: version$1};
+
 /**
- * Register event handlers from a context actions map to a kit instance.
- *
- * This utility function registers event handlers stored in a context actions map
- * with a kit instance that supports event handling via an `on` method. It handles
- * wildcard handlers ('*') and prefixed action handlers, stripping the prefix
- * before registration.
+ * Default base URL for the Earn Service API.
  *
- * The function is designed to be reusable across different operation types
- * (bridge, swap, stake, etc.) by accepting a configurable prefix parameter.
- *
- * @param kit - The kit instance to register handlers with (must have an `on` method)
- * @param handlers - Map of action names to arrays of handler functions
- * @param prefix - Optional prefix to strip from action names (e.g., 'bridge.')
+ * @internal
+ */
+const EARN_SERVICE_BASE_URL = 'https://api.circle.com';
+/**
+ * API path prefix for all EarnKit endpoints.
  *
- * @example
- * ```typescript
- * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
- * import { BridgeKit } from '@circle-fin/bridge-kit'
+ * @internal
+ */
+const EARN_KIT_API_PREFIX = '/v1/earnKit';
+/**
+ * Map SDK chain identifiers to Zenith API chain strings.
  *
- * const kit = new BridgeKit()
- * const handlers = {
- *   '*': [(payload) => console.log('All actions:', payload)],
- *   'bridge.approve': [(payload) => console.log('Approved:', payload)],
- *   'bridge.burn': [(payload) => console.log('Burned:', payload)],
- * }
+ * The Zenith backend uses short-form blockchain identifiers (e.g., 'ARC-TESTNET')
+ * while the SDK uses the {@link Blockchain} enum (e.g., 'Arc_Testnet').
+ * Adding a new {@link EarnSupportedBlockchain} without a corresponding
+ * entry here produces a compile error.
  *
- * registerActionHandlers(kit, handlers, 'bridge.')
- * ```
+ * @internal
+ */
+const CHAIN_TO_API = {
+    [exports.Blockchain.Arc_Testnet]: 'ARC-TESTNET',
+};
+/**
+ * Display symbol for vault share tokens.
  *
- * @example
- * ```typescript
- * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
- * import { SwapKit } from '@circle-fin/swap-kit'
+ * @internal
+ */
+const VAULT_SHARE_SYMBOL = 'shares';
+/**
+ * Default polling configuration for Earn Service API calls.
  *
- * const kit = new SwapKit()
- * const handlers = {
- *   'swap.initiate': [(payload) => console.log('Swap initiated:', payload)],
- * }
+ * Match the load-balancer timeout (30 s) with retry settings consistent
+ * with `@core/service-client` defaults.
  *
- * registerActionHandlers(kit, handlers, 'swap.')
- * ```
+ * @internal
  */
-const registerActionHandlers = (kit, handlers, prefix = '') => {
-    for (const [action, handlerArray] of Object.entries(handlers)) {
-        // Register all handlers for this action
-        for (const handler of handlerArray) {
-            if (action === '*') {
-                // Wildcard handlers are registered as-is
-                kit.on('*', handler);
-            }
-            else if (prefix && action.startsWith(prefix)) {
-                // Remove prefix to get the actual kit action name
-                const kitAction = action.split('.').at(1);
-                if (kitAction) {
-                    kit.on(kitAction, handler);
-                }
-            }
-            else if (!prefix) {
-                // No prefix configured, register action as-is
-                kit.on(action, handler);
-            }
-            // Actions that don't match the prefix are silently ignored
-        }
-    }
+const DEFAULT_CONFIG = {
+    timeout: 30_000,
+    maxRetries: 3,
+    retryDelay: 200,
+    headers: {
+        'Content-Type': 'application/json',
+    },
 };
 
+const API_TO_CHAIN = Object.fromEntries(Object.entries(CHAIN_TO_API).map(([sdkChain, apiChain]) => [
+    apiChain,
+    sdkChain,
+]));
+function toApiChain(chain) {
+    if (!Object.hasOwn(CHAIN_TO_API, chain)) {
+        return undefined;
+    }
+    return CHAIN_TO_API[chain];
+}
+function toSdkChain(chain) {
+    if (Object.hasOwn(CHAIN_TO_API, chain)) {
+        return chain;
+    }
+    if (!Object.hasOwn(API_TO_CHAIN, chain)) {
+        return undefined;
+    }
+    return API_TO_CHAIN[chain];
+}
+
 /**
- * List of all supported token aliases for App Kit send operations.
+ * Extract address and chain string from an adapter context.
  *
- * This array is used for runtime validation to check if a token string
- * is a known alias rather than a custom address.
+ * Handle both user-controlled adapters (address resolved via
+ * `adapter.getAddress()`) and developer-controlled adapters
+ * (address provided explicitly in the context).
  *
- * @remarks
- * The type annotation `readonly TokenAlias[]` ensures this array stays in sync
- * with the TokenAlias type definition - TypeScript will enforce any changes.
+ * @param from - Adapter context containing adapter, chain, and optional address
+ * @returns Resolved wallet address, API chain string, and chain definition
+ * @throws {@link KitError} If the chain is unsupported by the Earn Service provider.
+ * @throws Propagates errors from `adapter.getAddress(chain)` when
+ *   `from.address` is not supplied.
  *
- * For swap operations, additional tokens (EURC, DAI, USDE, PYUSD) are supported
- * via SwapKit's SupportedToken type.
+ * @example
+ * ```typescript
+ * const { address, chain, chainDefinition } =
+ *   await resolveAdapterContext(params.from)
+ * ```
+ *
+ * @internal
  */
-const TOKEN_ALIASES = ['USDC', 'USDT', 'NATIVE'];
+async function resolveAdapterContext(from) {
+    const chainDef = resolveChainIdentifier(from.chain);
+    const apiChain = toApiChain(chainDef.chain);
+    if (apiChain === undefined) {
+        throw createInvalidChainError(chainDef.chain, 'Chain is not supported by the Earn Service provider');
+    }
+    const hasAddress = 'address' in from &&
+        typeof from.address === 'string' &&
+        from.address.length > 0;
+    const address = hasAddress
+        ? from.address
+        : await from.adapter.getAddress(chainDef);
+    return { address, chain: apiChain, chainDefinition: chainDef };
+}
+
 /**
- * Check if a token string is a known alias.
- *
- * This function performs case-sensitive matching against the list of known
- * token aliases. Known aliases take precedence over custom addresses in the
- * send operation logic.
+ * Assert that a value is a 0x-prefixed 20-byte hex address.
  *
- * @param token - The token identifier to check
- * @returns True if the token is a known alias, false otherwise
+ * @param field - Name of the field being validated.
+ * @param value - Runtime value to validate.
+ * @param message - Optional message describing the expected address.
+ * @returns The validated value narrowed to a 0x-prefixed string.
+ * @throws {@link KitError} If the value is not an EVM address.
  *
  * @example
  * ```typescript
- * import { isTokenAlias } from '@circle-fin/app-kit'
- *
- * console.log(isTokenAlias('USDC')) // true
- * console.log(isTokenAlias('NATIVE')) // true
- * console.log(isTokenAlias('0x6B175474E89094C44Da98b954EedeAC495271d0F')) // false
+ * const token = assertHexAddress(
+ *   'chain.usdcAddress',
+ *   '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ * )
  * ```
+ *
+ * @internal
  */
-function isTokenAlias(token) {
-    return TOKEN_ALIASES.includes(token);
+function assertHexAddress(field, value, message = `${field} must be a 0x-prefixed 20-byte hex address`) {
+    const result = evmAddressSchema.safeParse(value);
+    if (!result.success) {
+        throw createValidationFailedError$1(field, value, message);
+    }
+    return result.data;
 }
+
 /**
- * Type guard to check if a string is a valid token address for a chain.
- *
- * This function verifies that a token string is:
- * 1. Not a known alias ('USDC', 'USDT', 'NATIVE')
- * 2. A valid address format for the specified chain
- *
- * Use this to narrow the type to `TokenAddress` in TypeScript.
+ * Return the adapter contract address configured for the chain, or throw a
+ * fatal KitError if unavailable. Earn operations require an adapter contract
+ * to forward service-signed payloads.
  *
- * @param token - The token string to validate
- * @param chain - The chain definition for address validation
- * @returns True if the token is a valid address (not an alias)
+ * @param chain - Resolved chain definition.
+ * @returns Adapter contract address as a 0x-prefixed hex string.
+ * @throws {@link KitError} If `chain.kitContracts.adapter` is undefined.
+ * @throws {@link KitError} If `chain.kitContracts.adapter` is malformed.
  *
  * @example
  * ```typescript
- * import { isTokenAddress } from '@circle-fin/app-kit'
- * import { Ethereum } from '@core/chains'
- *
- * const daiAddress = '0x6B175474E89094C44Da98b954EedeAC495271d0F'
- * if (isTokenAddress(daiAddress, Ethereum)) {
- *   // TypeScript knows daiAddress is TokenAddress here
- *   console.log('Valid token address:', daiAddress)
- * }
- *
- * console.log(isTokenAddress('USDC', Ethereum)) // false - it's an alias
- * console.log(isTokenAddress('invalid', Ethereum)) // false - invalid format
+ * const adapterContract = requireAdapterContract(chain)
  * ```
+ *
+ * @internal
  */
-function isTokenAddress(token, chain) {
-    return !isTokenAlias(token) && isValidAddressForChain(token, chain);
+function requireAdapterContract(chain) {
+    const adapterContractAddress = chain.kitContracts?.adapter;
+    if (adapterContractAddress === undefined) {
+        throw createValidationFailedError$1('chain.kitContracts.adapter', adapterContractAddress, `Adapter contract not configured for chain ${chain.name}. Earn operations require an adapter contract.`);
+    }
+    return assertHexAddress('chain.kitContracts.adapter', adapterContractAddress, `Adapter contract for chain ${chain.name} must be a 0x-prefixed 20-byte hex address.`);
 }
+
 /**
- * Validate and classify a token identifier.
- *
- * This function determines whether a token string is:
- * 1. A known alias ('USDC', 'USDT', or 'NATIVE')
- * 2. A valid token address for the given chain
- * 3. An invalid/unrecognized token identifier
+ * Safety multiplier applied to locally estimated gas for earn transactions.
  *
- * Known aliases always take precedence. If the token is not an alias,
- * it's validated as an address for the given chain.
+ * Earn transactions can include nested vault and token contract calls.
+ * Local gas estimation has undercounted those execution paths in production.
+ * A 1.3x buffer matching swap-kit reduces out-of-gas risk while preserving
+ * the adapter fallback path when local estimation fails.
  *
- * @param token - The token identifier to validate
- * @param chain - The chain definition for address validation
- * @returns An object containing validation results
+ * @internal
+ */
+const GAS_SAFETY_MULTIPLIER = 1.3;
+/**
+ * Estimate gas for a prepared chain request and apply {@link GAS_SAFETY_MULTIPLIER}.
  *
- * @example
- * ```typescript
- * import { validateToken } from '@circle-fin/app-kit'
- * import { Ethereum } from '@core/chains'
+ * Returns the buffered gas limit, or `undefined` if estimation fails or
+ * produces an invalid value. Callers should fall through to the adapter's
+ * default gas handling when `undefined` is returned.
  *
- * // Known alias
- * const usdc = validateToken('USDC', Ethereum)
- * console.log(usdc) // { isAlias: true, isAddress: false, isValid: true }
+ * @internal
+ */
+async function estimateBufferedGasLimit(prepared) {
+    try {
+        const estimate = await prepared.estimate();
+        const estimatedGas = Number(estimate.gas);
+        if (Number.isFinite(estimatedGas) && estimatedGas > 0) {
+            const buffered = Math.ceil(estimatedGas * GAS_SAFETY_MULTIPLIER);
+            if (Number.isFinite(buffered) && buffered > 0) {
+                return buffered;
+            }
+        }
+    }
+    catch {
+        // If estimation fails, fall through and let the adapter handle gas internally
+    }
+    return undefined;
+}
+
+/**
+ * Maximum `uint256` value. The approval amount used when this helper needs
+ * to send a token approval.
  *
- * // Custom token address
- * const dai = validateToken('0x6B175474E89094C44Da98b954EedeAC495271d0F', Ethereum)
- * console.log(dai) // { isAlias: false, isAddress: true, isValid: true }
+ * @internal
+ */
+const MAX_UINT256$1 = 2n ** 256n - 1n;
+/**
+ * Allowance threshold above which a prior max-approve is assumed to still
+ * cover any earn operation. Detects prior max-approvals even when the token
+ * decrements allowance on `transferFrom`, since that decay is negligible
+ * relative to 2^255.
  *
- * // Invalid token
- * const invalid = validateToken('invalid', Ethereum)
- * console.log(invalid) // { isAlias: false, isAddress: false, isValid: false }
- * ```
+ * @internal
  */
-function validateToken(token, chain) {
-    // Check if it's a known alias first (aliases take precedence)
-    const alias = isTokenAlias(token);
-    if (alias) {
-        return {
-            isAlias: true,
-            isAddress: false,
-            isValid: true,
-        };
+const ALLOWANCE_THRESHOLD = MAX_UINT256$1 / 2n;
+function parseAllowanceResponse(allowanceRaw) {
+    if (allowanceRaw === undefined || allowanceRaw === null) {
+        return 0n;
     }
-    // Not an alias - check if it's a valid address for the chain
-    const address = isTokenAddress(token, chain);
-    return {
-        isAlias: false,
-        isAddress: address,
-        isValid: address,
-    };
+    let allowance;
+    if (typeof allowanceRaw === 'bigint') {
+        allowance = allowanceRaw;
+    }
+    else if (typeof allowanceRaw === 'string') {
+        try {
+            allowance = BigInt(allowanceRaw);
+        }
+        catch {
+            allowance = undefined;
+        }
+    }
+    if (allowance === undefined || allowance < 0n) {
+        throw createValidationFailedError$1('token.allowance', allowanceRaw, 'token.allowance response must be a non-negative bigint-compatible string or bigint');
+    }
+    return allowance;
 }
-
 /**
- * Estimate the costs and details of a cross-chain bridge transfer using the AppKit context.
+ * Read the current ERC-20 allowance and, if below threshold, send a
+ * max-approval transaction and wait for confirmation.
  *
- * This function provides cost estimation for bridge operations within the AppKit
- * ecosystem. It delegates to the underlying BridgeKit infrastructure while maintaining
- * consistency with the AppKit patterns and context-based architecture.
+ * Uses the generalised `token.allowance` + `token.approve` adapter actions so
+ * the kit stays chain-agnostic. Assumes the target token supports
+ * non-zero-to-non-zero approve (USDC, ERC-4626 share tokens). Tokens with
+ * USDT-style semantics (require allowance == 0 before non-zero approve) need
+ * a different pattern.
  *
- * The function validates parameters, applies context-specific configurations,
- * and returns comprehensive estimation details including fees, gas costs, and
- * transaction parameters without executing the actual transfer.
+ * Approval status is checked explicitly because `waitForTransaction` returns
+ * a receipt with `status: 'reverted'` rather than throwing on revert.
  *
- * @param context - AppKit context containing fee calculation and configuration hooks
- * @param params - Bridge parameters containing source, destination, amount, and token
- * @returns Promise resolving to the estimate result with comprehensive fee and cost information
- * @throws If bridge parameters are invalid
- * @throws If the bridge route is not supported
- * @throws If estimation fails due to network or configuration issues
+ * @returns The approval tx hash when an approval was sent, or `undefined` if
+ *   the existing allowance was already above threshold.
+ * @throws {@link KitError} If the allowance response is malformed.
+ * @throws {@link KitError} If the approval transaction reverts on-chain.
  *
  * @example
  * ```typescript
- * import { estimateBridge } from '@circle-fin/app-kit/bridge'
- * import { createContext } from '@circle-fin/app-kit/context'
- *
- * const context = createContext({
- *   getFee: async (type, params) => '1000000', // 1 USDC fee
- *   getFeeRecipient: async (type, info) => '0xfee-recipient-address'
- * })
+ * const delegate = requireAdapterContract(chain)
  *
- * const estimate = await estimateBridge(context, {
- *   from: sourceAdapter,
- *   to: { adapter: destAdapter, chain: 'Polygon' },
- *   amount: '100.50',
- *   token: 'USDC'
+ * const approvalTxHash = await approveMaxIfNeeded({
+ *   adapter,
+ *   chain,
+ *   tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   delegate,
+ *   address,
+ *   revertMessage: 'USDC approval reverted on-chain',
  * })
- *
- * console.log('Estimated total fee:', estimate.fee)
- * console.log('Estimated gas cost:', estimate.gasEstimate)
  * ```
+ *
+ * @internal
  */
-const estimateBridge = async (context, params) => {
-    const kit = createBridgeKit(context);
-    // Delegate to the BridgeKit for actual estimation
-    return kit.estimate(params);
-};
+async function approveMaxIfNeeded(params) {
+    const { adapter, chain, tokenAddress, delegate, address, revertMessage } = params;
+    const allowancePrepared = await adapter.prepareAction('token.allowance', { tokenAddress, delegate }, { chain, address });
+    const allowanceRaw = await allowancePrepared.execute();
+    const currentAllowance = parseAllowanceResponse(allowanceRaw);
+    if (currentAllowance >= ALLOWANCE_THRESHOLD) {
+        return undefined;
+    }
+    const approvalPrepared = await adapter.prepareAction('token.approve', { tokenAddress, delegate, amount: MAX_UINT256$1 }, { chain, address });
+    const gasLimitOverride = await estimateBufferedGasLimit(approvalPrepared);
+    const approvalTxHash = approvalPrepared.type === 'evm' && gasLimitOverride !== undefined
+        ? await approvalPrepared.execute({ gasLimit: gasLimitOverride })
+        : await approvalPrepared.execute();
+    const approvalReceipt = await adapter.waitForTransaction(approvalTxHash, { confirmations: 1 }, chain);
+    if (approvalReceipt.status === 'reverted') {
+        throw createTransactionRevertedError(chain.name, revertMessage, undefined, approvalTxHash);
+    }
+    return approvalTxHash;
+}
 
-const assertSendParamsSymbol = Symbol('assertSendParams');
 /**
- * Matches numeric amount strings with optional thousands separators and decimal part.
+ * Build the `tokenInputs` array forwarded to the adapter contract's
+ * `execute(executeParams, tokenInputs, signature)` call.
  *
- * Accepts both US (e.g. "1,234.56") and EU (e.g. "1.234,56") styles by allowing
- * either "," or "." as the grouping and decimal separators. Also matches integers
- * like "10" and simple decimals like "10.5" or "10,5".
- */
-const amountNumericStringWithSeparatorsRegex = /^\d+(?:[.,]\d{3})*(?:[.,]\d+)?$/;
-/**
- * Schema describing the minimal adapter surface required by the kit.
+ * The adapter contract pulls ERC-20 tokens from `msg.sender` using the
+ * entries in `tokenInputs`, combined either with a pre-existing allowance
+ * ({@link PermitType.NONE}) or a permit signature ({@link PermitType.EIP2612}).
+ * Without an entry, the contract never moves the user's tokens and the
+ * nested instruction reverts with "ERC20: transfer amount exceeds balance"
+ * when the adapter tries to forward tokens it does not hold.
  *
- * The adapter must implement two functions:
- * - `prepare` — build the transaction or instruction payload.
- * - `waitForTransaction` — await finality/confirmation for a submitted transaction.
+ * Earn deposit and withdraw responses are schema-validated to contain at
+ * least one instruction. This helper emits one `PermitType.NONE` entry per
+ * instruction with a positive `amountToApprove`. Return an empty array when
+ * the service did not request any token pulls.
  *
- * @returns Zod schema validating an object with `prepare` and `waitForTransaction` functions.
+ * @param executionParams - Service-signed `ExecutionParams` forwarded to the adapter.
+ * @param approvedToken - Token approved for adapter spending on this chain.
+ * @returns `TokenInput[]` entries when pulls are required, `[]` otherwise.
+ * @throws {@link KitError} If `tokenIn` differs from the approved token.
  *
  * @example
  * ```typescript
- * import { adapterSchema } from '@circle-fin/app-kit'
+ * const approvedToken = assertHexAddress(
+ *   'chain.usdcAddress',
+ *   chain.usdcAddress,
+ * )
  *
- * console.log(adapterSchema.safeParse(ethereumAdapter).success) // true
+ * const tokenInputs = buildEarnTokenInputs(
+ *   executionPayload.executionParams,
+ *   approvedToken,
+ * )
  * ```
+ *
+ * @internal
  */
-const adapterSchema = zod.z.object({
-    prepare: zod.z.function().returns(zod.z.any()),
-    waitForTransaction: zod.z.function().returns(zod.z.any()),
-});
+function buildEarnTokenInputs(executionParams, approvedToken) {
+    const tokenInputs = [];
+    executionParams.instructions.forEach((instruction, index) => {
+        const amount = BigInt(instruction.amountToApprove);
+        if (amount <= 0n) {
+            return;
+        }
+        const { tokenIn } = instruction;
+        if (tokenIn.toLowerCase() !== approvedToken.toLowerCase()) {
+            throw createValidationFailedError$1(`executionParams.instructions[${index.toString()}].tokenIn`, tokenIn, 'tokenIn must match the token approved for adapter spending');
+        }
+        tokenInputs.push({
+            permitType: PermitType.NONE,
+            token: tokenIn,
+            amount,
+            permitCalldata: '0x',
+        });
+    });
+    return tokenInputs;
+}
+
 /**
- * Schema for validating adapter contexts.
- * Ensure required fields are present and properly typed. An adapter context must include:
- * - A valid adapter with `prepare` and `waitForTransaction` methods.
- * - A valid chain identifier (string literal or chain object recognized by the kit).
+ * Prepare an earn adapter action, execute it, wait for confirmation, and
+ * throw a structured revert error if the receipt status is `'reverted'`.
  *
- * @returns Zod schema validating an adapter context object.
- * @throws ZodError If validation fails, with details about which properties failed.
+ * Wraps the prepareAction, execute, waitForTransaction, and status check
+ * sequence so the provider can dispatch any `earn.*` action key with
+ * consistent revert handling.
+ *
+ * Gas estimation: after preparing the action the helper calls
+ * {@link estimateBufferedGasLimit}, which applies a safety buffer to the
+ * returned gas value. If estimation fails, execution falls through to the
+ * adapter's default gas handling.
+ *
+ * @typeParam TActionKey - Earn action key being executed.
+ * @param params - Adapter action, execution context, and revert message.
+ * @returns The confirmed on-chain transaction hash and explorer URL.
+ * @throws {@link KitError} If the transaction reverts on-chain.
  *
  * @example
  * ```typescript
- * import { adapterContextSchema } from '@circle-fin/app-kit'
- *
- * const result = adapterContextSchema.safeParse(context)
- * console.log(result.success) // true
+ * const { txHash, explorerUrl } = await executeEarnAction({
+ *   adapter,
+ *   chain,
+ *   address,
+ *   actionKey: 'earn.deposit',
+ *   actionParams: { executeParams, tokenInputs, signature },
+ *   revertMessage: 'Earn deposit reverted on-chain',
+ * })
  * ```
+ *
+ * @internal
  */
-const adapterContextSchema$3 = zod.z.object({
-    adapter: adapterSchema,
-    /**
-     * Note: We cast chainIdentifierSchema to 'never' here to work around a TypeScript
-     * limitation (TS2589: Type instantiation is excessively deep and possibly infinite)
+async function executeEarnAction(params) {
+    const { adapter, chain, address, actionKey, actionParams, revertMessage } = params;
+    const prepared = await adapter.prepareAction(actionKey, actionParams, {
+        chain,
+        address,
+    });
+    const gasLimitOverride = await estimateBufferedGasLimit(prepared);
+    const txHash = prepared.type === 'evm' && gasLimitOverride !== undefined
+        ? await prepared.execute({ gasLimit: gasLimitOverride })
+        : await prepared.execute();
+    const explorerUrl = buildExplorerUrl(chain, txHash);
+    const receipt = await adapter.waitForTransaction(txHash, { confirmations: 1 }, chain);
+    if (receipt.status === 'reverted') {
+        throw createTransactionRevertedError(chain.name, revertMessage, undefined, txHash, explorerUrl);
+    }
+    return { txHash, explorerUrl };
+}
+
+/**
+ * Validate that a service-signed execution payload has not expired before
+ * the SDK asks the wallet to broadcast a transaction.
+ *
+ * @internal
+ */
+function validateExecutionDeadline(executionParams) {
+    const deadline = BigInt(executionParams.deadline);
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    if (deadline <= now) {
+        throw createValidationFailedError$1('executionParams.deadline', executionParams.deadline, 'Earn execution deadline has expired');
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+function isBigIntLike(value) {
+    try {
+        BigInt(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNonNegativeBigIntLike(value) {
+    try {
+        return BigInt(value) >= 0n;
+    }
+    catch {
+        return false;
+    }
+}
+const hexSignatureSchema = evmSignatureSchema;
+const hexAddressSchema = evmAddressSchema;
+/**
+ * Zod schema for a non-negative uint256-like value.
+ *
+ * The service emits uint256 fields as decimal strings in JSON, while tests and
+ * lower-level SDK callers may already hold bigint values. Keep the parsed value
+ * unchanged so signed execution params can be forwarded verbatim.
+ *
+ * @internal
+ */
+const uint256LikeSchema = zod.z
+    .union([zod.z.string(), zod.z.bigint()])
+    .refine(isNonNegativeBigIntLike, {
+    message: 'value must be a non-negative bigint-compatible string or bigint',
+});
+/**
+ * Zod schema for typed amount objects emitted by the API.
+ *
+ * @internal
+ */
+const amountJsonSchema = zod.z.object({
+    raw: zod.z.string().refine(isBigIntLike, {
+        message: 'raw must be a bigint-compatible string',
+    }),
+    decimals: zod.z.number().int().nonnegative(),
+});
+/** @internal */
+const hexBytesSchema = zod.z.string().regex(/^0x([0-9a-fA-F]{2})*$/, {
+    message: 'value must be a 0x-prefixed even-length hex string',
+});
+// ---------------------------------------------------------------------------
+// Vault response schemas
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a vault reward token in the API response.
+ *
+ * @internal
+ */
+const vaultRewardSchema = zod.z.object({
+    token: zod.z.string(),
+    tokenAddress: zod.z.string(),
+    apy: zod.z.number(),
+});
+/**
+ * Zod schema for a vault collateral market in the API response.
+ *
+ * @internal
+ */
+const collateralSchema = zod.z.object({
+    asset: zod.z.string(),
+    assetAddress: zod.z.string(),
+    lltv: zod.z.number(),
+    supplyUsd: zod.z.number(),
+});
+/**
+ * Zod schema for a Morpho vault warning in the API response.
+ *
+ * @internal
+ */
+const vaultWarningSchema = zod.z.object({
+    type: zod.z.string(),
+    level: zod.z.enum(['YELLOW', 'RED']),
+});
+/**
+ * Zod schema for a single vault info object in the API response.
+ *
+ * @internal
+ */
+const vaultInfoResponseSchema = zod.z.object({
+    vaultAddress: zod.z.string(),
+    chain: zod.z.string(),
+    name: zod.z.string(),
+    protocol: zod.z.string(),
+    asset: zod.z.string(),
+    assetAddress: zod.z.string(),
+    currentApy: zod.z.number(),
+    nativeApy: zod.z.number(),
+    vaultFee: zod.z.number(),
+    rewards: zod.z.array(vaultRewardSchema),
+    collateral: zod.z.array(collateralSchema),
+    totalDeposits: amountJsonSchema,
+    liquidity: amountJsonSchema,
+    status: zod.z.enum(['active', 'low_liquidity']),
+    warnings: zod.z.array(vaultWarningSchema).optional(),
+    earnKitWarnings: zod.z.array(zod.z.string()).optional(),
+});
+// ---------------------------------------------------------------------------
+// Position response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for an accrued reward in the position API response.
+ *
+ * @internal
+ */
+const accruedRewardSchema = zod.z.object({
+    token: zod.z.string(),
+    symbol: zod.z.string(),
+    amount: amountJsonSchema,
+});
+const positionPnlSchema = zod.z.discriminatedUnion('status', [
+    zod.z.object({
+        status: zod.z.literal('available'),
+        principalDeposited: amountJsonSchema,
+        totalYieldEarned: amountJsonSchema,
+    }),
+    zod.z.object({
+        status: zod.z.literal('pending'),
+    }),
+    zod.z.object({
+        status: zod.z.literal('unavailable'),
+        reason: zod.z.string(),
+    }),
+]);
+/**
+ * Zod schema for the inner position payload.
+ *
+ * @internal
+ */
+const positionPayloadSchema = zod.z.object({
+    wallet: zod.z.string(),
+    chain: zod.z.string(),
+    vaultAddress: zod.z.string(),
+    vaultName: zod.z.string(),
+    asset: zod.z.string(),
+    currentBalance: amountJsonSchema,
+    currentApy: zod.z.number(),
+    shares: amountJsonSchema,
+    pnl: positionPnlSchema,
+    accruedRewards: zod.z.array(accruedRewardSchema).optional(),
+    rewardsUnavailableReason: zod.z.string().optional(),
+});
+/**
+ * Zod schema for the `GET /v1/earnKit/position/{address}` API response.
+ *
+ * The Earn Service API wraps the position payload in a `data` envelope.
+ *
+ * @internal
+ */
+const positionResponseSchema = zod.z.object({
+    data: positionPayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Deposit response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the deposit instruction fields used by the provider.
+ *
+ * The canonical instruction shape includes more fields, but deposit
+ * orchestration only depends on `tokenIn` and `amountToApprove` to build the
+ * token input and approval flow. Preserve additional signed fields with
+ * `passthrough()` so the adapter receives the full service payload.
+ *
+ * @internal
+ */
+const earnInstructionSchema = zod.z
+    .object({
+    tokenIn: hexAddressSchema,
+    amountToApprove: uint256LikeSchema,
+})
+    .passthrough();
+/**
+ * Zod schema for earn execution params returned by the earn service.
+ *
+ * Require at least one instruction so the provider can derive token pulls
+ * before it submits the signed params on-chain. Claim rewards has its own
+ * schema because it does not run approval preflight.
+ *
+ * @internal
+ */
+const earnExecutionParamsSchema = zod.z
+    .object({
+    instructions: zod.z.tuple([earnInstructionSchema]).rest(earnInstructionSchema),
+    deadline: uint256LikeSchema,
+})
+    .passthrough();
+/** @internal */
+const depositExecutionParamsSchema = earnExecutionParamsSchema;
+/** @internal */
+const withdrawExecutionParamsSchema = earnExecutionParamsSchema;
+/**
+ * Zod schema for the claim rewards instruction fields that must be safe to
+ * ABI-encode.
+ *
+ * Claim rewards has no approval preflight, so this validates the forwarded
+ * signed payload at the provider boundary. Additional instruction fields are
+ * accepted and preserved.
+ *
+ * @internal
+ */
+const claimRewardsInstructionSchema = zod.z
+    .object({
+    target: hexAddressSchema,
+    data: hexBytesSchema,
+    value: uint256LikeSchema,
+    tokenIn: hexAddressSchema,
+    amountToApprove: uint256LikeSchema,
+    tokenOut: hexAddressSchema,
+    minTokenOut: uint256LikeSchema,
+})
+    .passthrough();
+/** @internal */
+const claimRewardsTokenSchema = zod.z
+    .object({
+    token: hexAddressSchema,
+    beneficiary: hexAddressSchema,
+})
+    .passthrough();
+/**
+ * Zod schema for signed claim rewards execution params.
+ *
+ * This enforces the required envelope and preserves additive fields so the
+ * adapter receives the signed params verbatim.
+ *
+ * @internal
+ */
+const claimRewardsExecutionParamsSchema = zod.z
+    .object({
+    instructions: zod.z
+        .tuple([claimRewardsInstructionSchema])
+        .rest(claimRewardsInstructionSchema),
+    tokens: zod.z.tuple([claimRewardsTokenSchema]).rest(claimRewardsTokenSchema),
+    execId: uint256LikeSchema,
+    deadline: uint256LikeSchema,
+    metadata: hexBytesSchema,
+})
+    .passthrough();
+/**
+ * Zod schema for the deposit payload inside the API `data` envelope.
+ *
+ * @internal
+ */
+const depositPayloadSchema = zod.z.object({
+    executionParams: depositExecutionParamsSchema,
+    signature: hexSignatureSchema,
+});
+/**
+ * Zod schema for the `POST /v1/earnKit/deposit` API response.
+ *
+ * The API wraps the deposit payload in a `data` envelope.
+ *
+ * @internal
+ */
+const depositResponseSchema = zod.z.object({
+    data: depositPayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Withdraw response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the withdraw payload inside the API `data` envelope.
+ *
+ * @internal
+ */
+const withdrawPayloadSchema = zod.z.object({
+    executionParams: withdrawExecutionParamsSchema,
+    signature: hexSignatureSchema,
+});
+/**
+ * Zod schema for the `POST /v1/earnKit/withdraw` API response.
+ *
+ * The Earn Service API wraps the withdraw payload in a `data` envelope.
+ *
+ * @internal
+ */
+const withdrawResponseSchema = zod.z.object({
+    data: withdrawPayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Claim rewards response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a claimed reward amount in the API response.
+ *
+ * @internal
+ */
+const claimedAmountSchema = zod.z.object({
+    token: hexAddressSchema,
+    symbol: zod.z.string(),
+    amount: amountJsonSchema,
+});
+/**
+ * Zod schema for the claim rewards payload inside the API `data` envelope.
+ *
+ * Enforce that `executionParams` and `signature` are either both
+ * present (claimable rewards) or both absent (nothing to claim).
+ *
+ * @internal
+ */
+const claimRewardsPayloadSchema = zod.z
+    .object({
+    rewards: zod.z.array(claimedAmountSchema),
+    executionParams: claimRewardsExecutionParamsSchema.optional(),
+    signature: hexSignatureSchema.optional(),
+})
+    .refine((data) => {
+    const signedFieldCount = (data.executionParams === undefined ? 0 : 1) +
+        (data.signature === undefined ? 0 : 1);
+    if (data.rewards.length > 0) {
+        return signedFieldCount === 2;
+    }
+    return signedFieldCount === 0;
+}, {
+    message: 'claim rewards response must include executionParams and signature only when rewards are claimable',
+});
+/**
+ * Zod schema for the `POST /v1/earnKit/claimRewards` API response.
+ *
+ * The Earn Service API wraps the claim rewards payload in a `data` envelope.
+ *
+ * @internal
+ */
+const claimRewardsResponseSchema = zod.z.object({
+    data: claimRewardsPayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Deposit quote response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the inner deposit quote payload.
+ *
+ * @internal
+ */
+const depositQuotePayloadSchema = zod.z.object({
+    vaultAddress: zod.z.string(),
+    vaultName: zod.z.string(),
+    asset: zod.z.string(),
+    depositAmount: amountJsonSchema,
+    expectedShares: amountJsonSchema,
+    sharePrice: zod.z.string(),
+    currentApy: zod.z.number(),
+});
+/**
+ * Zod schema for the `POST /v1/earnKit/deposit/quote` API response.
+ *
+ * The Zenith API wraps the payload in a `data` envelope.
+ *
+ * @internal
+ */
+const depositQuoteResponseSchema = zod.z.object({
+    data: depositQuotePayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Withdrawal quote response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a withdrawal quote fee in the API response.
+ *
+ * @internal
+ */
+const withdrawalQuoteFeeSchema = zod.z.object({
+    token: zod.z.string(),
+    amount: amountJsonSchema,
+});
+/**
+ * Zod schema for the inner withdrawal quote payload.
+ *
+ * @internal
+ */
+const withdrawalQuotePayloadSchema = zod.z.object({
+    vaultAddress: zod.z.string(),
+    vaultName: zod.z.string(),
+    asset: zod.z.string(),
+    withdrawAmount: amountJsonSchema,
+    sharesToRedeem: amountJsonSchema,
+    sharePrice: zod.z.string(),
+    maxWithdrawable: amountJsonSchema,
+    fees: zod.z.array(withdrawalQuoteFeeSchema),
+    warnings: zod.z.array(zod.z.string()).optional(),
+});
+/**
+ * Zod schema for the `POST /v1/earnKit/withdrawal/quote` API response.
+ *
+ * The Zenith API wraps the payload in a `data` envelope.
+ *
+ * @internal
+ */
+const withdrawalQuoteResponseSchema = zod.z.object({
+    data: withdrawalQuotePayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Claim rewards quote response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a reward in the claim rewards quote response.
+ *
+ * @internal
+ */
+const claimRewardsQuoteRewardSchema = zod.z.object({
+    token: zod.z.string(),
+    symbol: zod.z.string(),
+    amount: amountJsonSchema,
+});
+/**
+ * Zod schema for the inner claim rewards quote payload.
+ *
+ * @internal
+ */
+const claimRewardsQuotePayloadSchema = zod.z.object({
+    rewards: zod.z.array(claimRewardsQuoteRewardSchema),
+});
+/**
+ * Zod schema for the `POST /v1/earnKit/claimRewards/quote` API response.
+ *
+ * The Zenith API wraps the payload in a `data` envelope.
+ *
+ * @internal
+ */
+const claimRewardsQuoteResponseSchema = zod.z.object({
+    data: claimRewardsQuotePayloadSchema,
+});
+// ---------------------------------------------------------------------------
+// Batch vault response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a per-vault error in the batch vault API response.
+ *
+ * @internal
+ */
+const vaultErrorSchema = zod.z.object({
+    chain: zod.z.string(),
+    vaultAddress: zod.z.string(),
+    code: zod.z.number(),
+    message: zod.z.string(),
+});
+/**
+ * Zod schema for the inner batch vault payload.
+ *
+ * @internal
+ */
+const getVaultsPayloadSchema = zod.z.object({
+    vaults: zod.z.array(vaultInfoResponseSchema),
+    errors: zod.z.array(vaultErrorSchema),
+});
+/**
+ * Zod schema for the `GET /v1/earnKit/vaults` batch API response.
+ *
+ * The Earn Service API wraps the vault payload in a `data` envelope.
+ *
+ * @internal
+ */
+const getVaultsResponseSchema = zod.z.object({
+    data: getVaultsPayloadSchema,
+});
+
+/**
+ * Type guard for the batch vault lookup API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the batch vault response shape
+ *
+ * @internal
+ */
+function isGetVaultsResponse(value) {
+    return getVaultsResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the position API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the position response shape
+ *
+ * @internal
+ */
+function isPositionResponse(value) {
+    return positionResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the deposit API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the deposit response shape
+ *
+ * @internal
+ */
+function isDepositResponse(value) {
+    return depositResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the withdraw API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the withdraw response shape
+ *
+ * @internal
+ */
+function isWithdrawResponse(value) {
+    return withdrawResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the claim rewards API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the claim rewards response shape
+ *
+ * @internal
+ */
+function isClaimRewardsResponse(value) {
+    return claimRewardsResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the deposit quote API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the deposit quote response shape
+ *
+ * @internal
+ */
+function isDepositQuoteResponse(value) {
+    return depositQuoteResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the withdrawal quote API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the withdrawal quote response shape
+ *
+ * @internal
+ */
+function isWithdrawalQuoteResponse(value) {
+    return withdrawalQuoteResponseSchema.safeParse(value).success;
+}
+/**
+ * Type guard for the claim rewards quote API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the claim rewards quote response shape
+ *
+ * @internal
+ */
+function isClaimRewardsQuoteResponse(value) {
+    return claimRewardsQuoteResponseSchema.safeParse(value).success;
+}
+
+/**
+ * Build an API polling config with optional authorization header,
+ * and resolve the base URL (configurable for testing).
+ *
+ * @param serviceConfig - Optional earn service configuration
+ * @returns Resolved polling config and base URL
+ *
+ * @internal
+ */
+function buildConfig(serviceConfig) {
+    const baseUrl = serviceConfig?.baseUrl ?? EARN_SERVICE_BASE_URL;
+    if (serviceConfig?.kitKey === undefined) {
+        return { pollingConfig: DEFAULT_CONFIG, baseUrl };
+    }
+    if (!isValidApiKey(serviceConfig.kitKey)) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Invalid kitKey format. Expected KIT_KEY:<keyId>:<keySecret>.',
+        });
+    }
+    return {
+        pollingConfig: {
+            ...DEFAULT_CONFIG,
+            headers: {
+                ...DEFAULT_CONFIG.headers,
+                Authorization: `Bearer ${serviceConfig.kitKey}`,
+            },
+        },
+        baseUrl,
+    };
+}
+
+function toVaultInfo(data) {
+    const { totalDeposits, liquidity, ...vault } = data;
+    const chain = toSdkChain(vault.chain);
+    if (chain === undefined) {
+        throw createInvalidChainError(vault.chain, 'Chain returned by the Earn Service is not supported by the SDK');
+    }
+    return {
+        ...vault,
+        chain,
+        totalDeposits: Amount.fromJSON(totalDeposits),
+        liquidity: Amount.fromJSON(liquidity),
+    };
+}
+function toVaultError(error) {
+    const chain = toSdkChain(error.chain);
+    if (chain === undefined) {
+        throw createInvalidChainError(error.chain, 'Chain returned by the Earn Service is not supported by the SDK');
+    }
+    return { ...error, chain };
+}
+function getVaultQueryChainLabel(chain) {
+    return typeof chain === 'string' ? chain : 'unknown';
+}
+function resolveVaultQueryChain(chain) {
+    try {
+        return resolveChainIdentifier(chain);
+    }
+    catch {
+        throw createInvalidChainError(getVaultQueryChainLabel(chain), 'Chain is not supported by the Earn Service provider');
+    }
+}
+/**
+ * Fetch vault information from the Earn Service API.
+ *
+ * Call `GET /v1/earnKit/vaults` with repeated chain and vaultAddress
+ * query parameters for batch vault lookup.
+ *
+ * @param params - Vault query parameters
+ * @returns Batch result with vaults and per-vault errors
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchVaults(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/vaults`, baseUrl);
+    // The API pairs chain[i] with vaultAddress[i] by insertion order.
+    for (const vault of params.vaults) {
+        const chainDefinition = resolveVaultQueryChain(vault.chain);
+        const apiChain = toApiChain(chainDefinition.chain);
+        if (apiChain === undefined) {
+            throw createInvalidChainError(chainDefinition.chain, 'Chain is not supported by the Earn Service provider');
+        }
+        url.searchParams.append('chain', apiChain);
+        url.searchParams.append('vaultAddress', vault.vaultAddress);
+    }
+    try {
+        const response = await pollApiGet(url.toString(), isGetVaultsResponse, pollingConfig);
+        return {
+            vaults: response.data.vaults.map(toVaultInfo),
+            errors: response.data.errors.map(toVaultError),
+        };
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'getVaults' });
+    }
+}
+
+function toAccruedReward(reward) {
+    return {
+        tokenAddress: reward.token,
+        symbol: reward.symbol,
+        amount: Amount.fromJSON(reward.amount),
+    };
+}
+function assertNever(value) {
+    throw new KitError({
+        ...EarnError.INTERNAL_ERROR,
+        recoverability: 'FATAL',
+        message: `Unhandled PnL status: ${JSON.stringify(value)}`,
+        cause: {
+            trace: value,
+        },
+    });
+}
+function toPositionPnL(data) {
+    switch (data.status) {
+        case 'available':
+            return {
+                status: 'available',
+                principalDeposited: Amount.fromJSON(data.principalDeposited),
+                totalYieldEarned: Amount.fromJSON(data.totalYieldEarned),
+            };
+        case 'pending':
+            return { status: 'pending' };
+        case 'unavailable':
+            return { status: 'unavailable', reason: data.reason };
+        default:
+            return assertNever(data);
+    }
+}
+function toPositionInfo(data) {
+    const { currentBalance, shares, pnl, accruedRewards = [], ...position } = data;
+    const chain = toSdkChain(position.chain);
+    if (chain === undefined) {
+        throw new KitError({
+            ...EarnError.INTERNAL_ERROR,
+            recoverability: 'FATAL',
+            message: `Unsupported Earn Service chain: ${position.chain}`,
+            cause: {
+                trace: {
+                    chain: position.chain,
+                },
+            },
+        });
+    }
+    return {
+        ...position,
+        chain,
+        currentBalance: Amount.fromJSON(currentBalance),
+        shares: Amount.fromJSON(shares),
+        pnl: toPositionPnL(pnl),
+        accruedRewards: accruedRewards.map(toAccruedReward),
+    };
+}
+/**
+ * Fetch a user's vault position from the Earn Service API.
+ *
+ * Call `GET /v1/earnKit/position/{address}` with the provided chain
+ * and vault address as query parameters.
+ *
+ * @param params - Position query parameters
+ * @returns The user's position information
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchPosition(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/position/${encodeURIComponent(params.address)}`, baseUrl);
+    url.searchParams.set('chain', params.chain);
+    url.searchParams.set('vaultAddress', params.vaultAddress);
+    try {
+        const response = await pollApiGet(url.toString(), isPositionResponse, pollingConfig);
+        return toPositionInfo(response.data);
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'getPosition' });
+    }
+}
+
+/**
+ * Build signed deposit instructions via the Earn Service API.
+ *
+ * Call `POST /v1/earnKit/deposit` with the vault address, amount,
+ * wallet address, and chain. Return EIP-712 signed execution
+ * parameters for on-chain submission.
+ *
+ * @param params - Deposit parameters
+ * @returns Signed execution parameters for the deposit
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchDeposit(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/deposit`, baseUrl);
+    const requestBody = {
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        address: params.address,
+        chain: params.chain,
+    };
+    try {
+        const response = await pollApiPost(url.toString(), requestBody, isDepositResponse, pollingConfig);
+        return response.data;
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'deposit' });
+    }
+}
+
+/**
+ * Build signed withdrawal instructions via the Earn Service API.
+ *
+ * Call `POST /v1/earnKit/withdraw` with the vault address, amount,
+ * wallet address, and chain. Return EIP-712 signed execution
+ * parameters for on-chain submission.
+ *
+ * @param params - Withdrawal parameters
+ * @returns Signed execution parameters for the withdrawal
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchWithdraw(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/withdraw`, baseUrl);
+    const requestBody = {
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        address: params.address,
+        chain: params.chain,
+    };
+    try {
+        const response = await pollApiPost(url.toString(), requestBody, isWithdrawResponse, pollingConfig);
+        return response.data;
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'withdraw' });
+    }
+}
+
+function toClaimedAmount(reward) {
+    return {
+        address: reward.token,
+        symbol: reward.symbol,
+        amount: Amount.fromJSON(reward.amount),
+    };
+}
+/**
+ * Build signed claim rewards instructions via the Earn Service API.
+ *
+ * Call `POST /v1/earnKit/claimRewards` with the wallet address, chain, and
+ * vault address. Return EIP-712 signed execution parameters for on-chain
+ * submission. When no rewards are claimable, return an empty rewards array
+ * without execution parameters.
+ *
+ * @param params - Claim rewards parameters
+ * @returns Signed execution parameters and reward details
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchClaimRewards(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/claimRewards`, baseUrl);
+    const requestBody = {
+        address: params.address,
+        chain: params.chain,
+        vaultAddress: params.vaultAddress,
+    };
+    try {
+        const response = await pollApiPost(url.toString(), requestBody, isClaimRewardsResponse, pollingConfig);
+        const { rewards, executionParams, signature } = response.data;
+        return {
+            rewards: rewards.map(toClaimedAmount),
+            ...(executionParams === undefined ? {} : { executionParams }),
+            ...(signature === undefined ? {} : { signature }),
+        };
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'claimRewards' });
+    }
+}
+
+function toDepositQuoteInfo(data) {
+    return {
+        vaultAddress: data.vaultAddress,
+        vaultName: data.vaultName,
+        deposit: {
+            symbol: data.asset,
+            amount: Amount.fromJSON(data.depositAmount),
+        },
+        expectedShares: {
+            symbol: VAULT_SHARE_SYMBOL,
+            address: data.vaultAddress,
+            amount: Amount.fromJSON(data.expectedShares),
+        },
+        sharePrice: data.sharePrice,
+        currentApy: data.currentApy,
+        fees: [],
+    };
+}
+/**
+ * Fetch a deposit quote from the Earn Service API.
+ *
+ * Call `POST /v1/earnKit/deposit/quote` with the vault address, amount,
+ * wallet address, and chain. Return informational quote data including
+ * expected shares, share price, and APY.
+ *
+ * @param params - Deposit quote parameters
+ * @returns Deposit quote information
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchDepositQuote(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/deposit/quote`, baseUrl);
+    const requestBody = {
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        address: params.address,
+        chain: params.chain,
+    };
+    try {
+        const response = await pollApiPost(url.toString(), requestBody, isDepositQuoteResponse, pollingConfig);
+        return toDepositQuoteInfo(response.data);
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'getDepositQuote' });
+    }
+}
+
+function toWithdrawalQuoteInfo(data) {
+    return {
+        vaultAddress: data.vaultAddress,
+        vaultName: data.vaultName,
+        withdrawal: {
+            symbol: data.asset,
+            amount: Amount.fromJSON(data.withdrawAmount),
+        },
+        sharesToRedeem: {
+            symbol: VAULT_SHARE_SYMBOL,
+            address: data.vaultAddress,
+            amount: Amount.fromJSON(data.sharesToRedeem),
+        },
+        sharePrice: data.sharePrice,
+        maxWithdrawable: {
+            symbol: data.asset,
+            amount: Amount.fromJSON(data.maxWithdrawable),
+        },
+        fees: data.fees.map((fee) => ({
+            symbol: fee.token,
+            amount: Amount.fromJSON(fee.amount),
+        })),
+        // Wire format uses `warnings`, but the SDK surface uses
+        // `earnKitWarnings` to match the precedent set by `VaultInfo` —
+        // `warnings` is reserved for the structured `VaultWarning` shape.
+        ...(data.warnings !== undefined && { earnKitWarnings: data.warnings }),
+    };
+}
+/**
+ * Fetch a withdrawal quote from the Earn Service API.
+ *
+ * Call `POST /v1/earnKit/withdrawal/quote` with the vault address, amount,
+ * wallet address, and chain. Return informational quote data including
+ * shares to redeem, max withdrawable, and fees.
+ *
+ * @param params - Withdrawal quote parameters
+ * @returns Withdrawal quote information
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchWithdrawalQuote(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/withdrawal/quote`, baseUrl);
+    const requestBody = {
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        address: params.address,
+        chain: params.chain,
+    };
+    try {
+        const response = await pollApiPost(url.toString(), requestBody, isWithdrawalQuoteResponse, pollingConfig);
+        return toWithdrawalQuoteInfo(response.data);
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'getWithdrawalQuote' });
+    }
+}
+
+/**
+ * Fetch a claim rewards quote from the Earn Service API.
+ *
+ * Call `POST /v1/earnKit/claimRewards/quote` with the wallet address,
+ * chain, and vault address. Return informational quote data including
+ * claimable reward details.
+ *
+ * @param params - Claim rewards quote parameters
+ * @returns Claim rewards quote information
+ * @throws {@link KitError} When the API call fails
+ *
+ * @internal
+ */
+async function fetchClaimRewardsQuote(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/claimRewards/quote`, baseUrl);
+    const requestBody = {
+        vaultAddress: params.vaultAddress,
+        address: params.address,
+        chain: params.chain,
+    };
+    try {
+        const response = await pollApiPost(url.toString(), requestBody, isClaimRewardsQuoteResponse, pollingConfig);
+        return {
+            rewards: response.data.rewards.map((r) => ({
+                symbol: r.symbol,
+                amount: Amount.fromJSON(r.amount),
+                address: r.token,
+            })),
+        };
+    }
+    catch (error) {
+        throw parseEarnApiError(error, { operation: 'getClaimRewardsQuote' });
+    }
+}
+
+/**
+ * Earn Service provider for the Circle earn service API.
+ *
+ * Implement the {@link EarningProvider} interface for yield-bearing vault
+ * operations including vault discovery, position queries, deposits,
+ * withdrawals, and reward claiming.
+ *
+ * @example
+ * ```typescript
+ * import { EarnServiceProvider } from '@circle-fin/provider-earn-service'
+ *
+ * // Permissionless mode
+ * const provider = new EarnServiceProvider()
+ *
+ * // Permissioned mode with Kit Key
+ * const provider = new EarnServiceProvider({
+ *   kitKey: 'KIT_KEY:keyId:keySecret',
+ * })
+ *
+ * // Custom base URL for testing
+ * const provider = new EarnServiceProvider({
+ *   baseUrl: 'https://api-staging.circle.com',
+ * })
+ *
+ * const result = await provider.getVaults({
+ *   vaults: [
+ *     { chain: 'Arc_Testnet', vaultAddress: '0x8eB67...' },
+ *   ],
+ * })
+ * ```
+ */
+class EarnServiceProvider {
+    /** {@inheritdoc} */
+    name = 'EarnService';
+    /** {@inheritdoc} */
+    supportedChains = Object.keys(CHAIN_TO_API).map((chain) => resolveChainIdentifier(chain));
+    defaultConfig;
+    /**
+     * Create a new EarnServiceProvider.
+     *
+     * @param config - Optional default configuration applied to all operations.
+     *   Per-operation config takes precedence when provided.
+     */
+    constructor(config) {
+        this.defaultConfig = config;
+    }
+    resolveConfig(config) {
+        const resolvedConfig = this.defaultConfig === undefined
+            ? config
+            : { ...this.defaultConfig, ...config };
+        return resolvedConfig;
+    }
+    /** {@inheritdoc} */
+    async getVaults(params) {
+        const config = this.resolveConfig(params.config);
+        return fetchVaults({
+            vaults: params.vaults,
+            config,
+        });
+    }
+    /** {@inheritdoc} */
+    async getPosition(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain } = await resolveAdapterContext(params.from);
+        return fetchPosition({
+            address,
+            chain,
+            vaultAddress: params.vaultAddress,
+            config,
+        });
+    }
+    /** {@inheritdoc} */
+    async deposit(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
+        const adapterContractAddress = requireAdapterContract(chain);
+        const rawUsdcAddress = chain.usdcAddress;
+        if (rawUsdcAddress === null) {
+            throw createUnsupportedTokenError('USDC', chain.name);
+        }
+        const usdcAddress = assertHexAddress('chain.usdcAddress', rawUsdcAddress, `USDC address for chain ${chain.name} must be a 0x-prefixed 20-byte hex address.`);
+        const { executionParams, signature } = await fetchDeposit({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain: apiChain,
+            config,
+        });
+        validateExecutionDeadline(executionParams);
+        const { adapter } = params.from;
+        const tokenInputs = buildEarnTokenInputs(executionParams, usdcAddress);
+        const approvalToken = tokenInputs[0]?.token;
+        if (approvalToken !== undefined) {
+            await approveMaxIfNeeded({
+                adapter,
+                chain,
+                tokenAddress: approvalToken,
+                delegate: adapterContractAddress,
+                address,
+                revertMessage: 'USDC approval reverted on-chain',
+            });
+        }
+        const { txHash, explorerUrl } = await executeEarnAction({
+            adapter,
+            chain,
+            address,
+            actionKey: 'earn.deposit',
+            actionParams: {
+                executeParams: executionParams,
+                tokenInputs,
+                signature,
+            },
+            revertMessage: 'Earn deposit reverted on-chain',
+        });
+        return {
+            txHash,
+            explorerUrl,
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+        };
+    }
+    /** {@inheritdoc} */
+    async withdraw(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
+        const adapterContractAddress = requireAdapterContract(chain);
+        const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
+        const { executionParams, signature } = await fetchWithdraw({
+            vaultAddress,
+            amount: params.amount,
+            address,
+            chain: apiChain,
+            config,
+        });
+        validateExecutionDeadline(executionParams);
+        const { adapter } = params.from;
+        const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
+        const approvalToken = tokenInputs[0]?.token;
+        if (approvalToken !== undefined) {
+            await approveMaxIfNeeded({
+                adapter,
+                chain,
+                tokenAddress: approvalToken,
+                delegate: adapterContractAddress,
+                address,
+                revertMessage: 'Vault share token approval reverted on-chain',
+            });
+        }
+        const { txHash, explorerUrl } = await executeEarnAction({
+            adapter,
+            chain,
+            address,
+            actionKey: 'earn.withdraw',
+            actionParams: {
+                executeParams: executionParams,
+                tokenInputs,
+                signature,
+            },
+            revertMessage: 'Earn withdraw reverted on-chain',
+        });
+        return {
+            txHash,
+            explorerUrl,
+            vaultAddress,
+            amount: params.amount,
+        };
+    }
+    /** {@inheritdoc} */
+    async claimRewards(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
+        // Claim rewards has no approval step, but still requires adapter support.
+        requireAdapterContract(chain);
+        const { rewards, executionParams, signature } = await fetchClaimRewards({
+            address,
+            chain: apiChain,
+            vaultAddress: params.vaultAddress,
+            config,
+        });
+        const nothingToClaim = rewards.length === 0;
+        if (nothingToClaim) {
+            return { status: 'no_rewards', rewards: [] };
+        }
+        const missingExecutionParams = executionParams === undefined;
+        const missingSignature = signature === undefined;
+        if (missingExecutionParams || missingSignature) {
+            throw new KitError({
+                ...EarnError.INTERNAL_ERROR,
+                recoverability: 'RETRYABLE',
+                message: 'Claim rewards response must include executionParams and signature when rewards are claimable',
+                cause: {
+                    trace: {
+                        rewardsCount: rewards.length,
+                        missingExecutionParams,
+                        missingSignature,
+                    },
+                },
+            });
+        }
+        validateExecutionDeadline(executionParams);
+        const { txHash, explorerUrl } = await executeEarnAction({
+            adapter: params.from.adapter,
+            chain,
+            address,
+            actionKey: 'earn.claimRewards',
+            actionParams: {
+                executeParams: executionParams,
+                tokenInputs: [],
+                signature,
+            },
+            revertMessage: 'Earn claim rewards reverted on-chain',
+        });
+        return { status: 'claimed', rewards, txHash, explorerUrl };
+    }
+    /** {@inheritdoc} */
+    async getDepositQuote(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain } = await resolveAdapterContext(params.from);
+        return fetchDepositQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+        });
+    }
+    /** {@inheritdoc} */
+    async getWithdrawalQuote(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain } = await resolveAdapterContext(params.from);
+        return fetchWithdrawalQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+        });
+    }
+    /** {@inheritdoc} */
+    async getClaimRewardsQuote(params) {
+        const config = this.resolveConfig(params.config);
+        const { address, chain } = await resolveAdapterContext(params.from);
+        return fetchClaimRewardsQuote({
+            vaultAddress: params.vaultAddress,
+            address,
+            chain,
+            config,
+        });
+    }
+}
+
+/**
+ * The default providers used when no custom providers are specified.
+ *
+ * @returns An array containing the default EarnServiceProvider
+ * @internal
+ */
+const getDefaultProviders$1 = () => [new EarnServiceProvider()];
+/**
+ * Create an EarnKit context with validated configuration.
+ *
+ * Initialize an EarnKitContext with default providers and optional
+ * custom configuration. Custom and default providers are merged,
+ * preserving their exact types for type safety.
+ *
+ * @typeParam TExtraProviders - Array type of additional earn providers
+ * @param config - Optional configuration for the EarnKit context
+ * @returns A fully initialized EarnKitContext ready for earn operations
+ *
+ * @example
+ * ```typescript
+ * import { createEarnKitContext } from '@circle-fin/earn-kit'
+ *
+ * // Create context with defaults
+ * const context = createEarnKitContext()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createEarnKitContext } from '@circle-fin/earn-kit'
+ *
+ * // Create context with custom providers
+ * const context = createEarnKitContext({
+ *   providers: [myCustomEarnProvider],
+ * })
+ * ```
+ */
+function createEarnKitContext(config = {}) {
+    const defaultProviders = getDefaultProviders$1();
+    const providers = [...(config.providers ?? []), ...defaultProviders];
+    const context = {
+        providers,
+    };
+    return context;
+}
+
+/**
+ * Symbol used to track that assertEarnParams has validated an object.
+ * @internal
+ */
+const ASSERT_EARN_PARAMS_SYMBOL = Symbol('assertEarnParams');
+/**
+ * Assert that the provided value conforms to the given earn params schema.
+ *
+ * Validate earn parameters using the provided Zod schema and track
+ * validation state to avoid duplicate checks. Throw a structured
+ * error with detailed validation messages if any parameter is invalid.
+ *
+ * @typeParam T - The expected type after validation
+ * @param params - The earn parameters to validate
+ * @param schema - The Zod schema to validate against
+ * @throws {@link KitError} If the parameters fail validation
+ *
+ * @example
+ * ```typescript
+ * import { assertEarnParams, depositParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * assertEarnParams(params, depositParamsSchema)
+ * ```
+ */
+function assertEarnParams(params, schema) {
+    validateWithStateTracking(params, schema, 'earn parameters', ASSERT_EARN_PARAMS_SYMBOL);
+}
+
+function findProvider(context, chain, operation = 'earn') {
+    let fallback;
+    for (const provider of context.providers) {
+        fallback ??= provider;
+        if (provider.supportedChains.length === 0)
+            continue;
+        if (chain === undefined ||
+            provider.supportedChains.some((c) => c.chain === chain.chain)) {
+            return provider;
+        }
+    }
+    if (fallback === undefined) {
+        throw createValidationFailedError$1('context.providers', [], 'No earn providers configured');
+    }
+    if (chain !== undefined) {
+        throw createUnsupportedEarnRouteError(operation, chain.name);
+    }
+    return fallback;
+}
+
+/**
+ * Format a provider amount object as a human-readable decimal string.
+ *
+ * The kit result surface intentionally exposes only the decimal string value,
+ * so nested provider amount metadata is not retained at this boundary.
+ *
+ * @param amount - Provider amount object to format
+ * @returns Human-readable decimal amount string
+ */
+function formatAmount$1(amount) {
+    return formatUnits(amount.raw.toString(), amount.decimals);
+}
+function formatAssetAmount(assetAmount) {
+    const { amount, ...rest } = assetAmount;
+    return {
+        ...rest,
+        amount: formatAmount$1(amount),
+    };
+}
+function formatClaimedAmount(claimedAmount) {
+    const { amount, ...rest } = claimedAmount;
+    return {
+        ...rest,
+        amount: formatAmount$1(amount),
+    };
+}
+function formatAccruedReward(reward) {
+    const { amount, ...rest } = reward;
+    return {
+        ...rest,
+        amount: formatAmount$1(amount),
+    };
+}
+function formatPositionPnL(pnl) {
+    if (pnl.status !== 'available') {
+        return pnl;
+    }
+    return {
+        ...pnl,
+        principalDeposited: formatAmount$1(pnl.principalDeposited),
+        totalYieldEarned: formatAmount$1(pnl.totalYieldEarned),
+    };
+}
+/**
+ * Convert provider vault info into an EarnKit vault result.
+ *
+ * @param vault - Provider vault info with raw amount objects
+ * @returns Vault info with total deposits and liquidity formatted as strings
+ */
+function formatVaultInfo(vault) {
+    const { totalDeposits, liquidity, ...rest } = vault;
+    return {
+        ...rest,
+        totalDeposits: formatAmount$1(totalDeposits),
+        liquidity: formatAmount$1(liquidity),
+    };
+}
+/**
+ * Convert a provider vault lookup result into an EarnKit result.
+ *
+ * @param result - Provider vault lookup result
+ * @returns Vault lookup result with each vault amount formatted as strings
+ */
+function formatGetVaultsResult(result) {
+    return {
+        ...result,
+        vaults: result.vaults.map(formatVaultInfo),
+    };
+}
+/**
+ * Convert provider position info into an EarnKit position result.
+ *
+ * @param position - Provider position info with raw amount objects
+ * @returns Position info with balances, shares, PnL, and rewards formatted as strings
+ */
+function formatPositionInfo(position) {
+    const { currentBalance, shares, pnl, accruedRewards, ...rest } = position;
+    return {
+        ...rest,
+        currentBalance: formatAmount$1(currentBalance),
+        shares: formatAmount$1(shares),
+        pnl: formatPositionPnL(pnl),
+        accruedRewards: accruedRewards.map(formatAccruedReward),
+    };
+}
+/**
+ * Convert a provider deposit quote into an EarnKit deposit quote result.
+ *
+ * @param quote - Provider deposit quote with raw amount objects
+ * @returns Deposit quote with deposit, shares, and fees formatted as strings
+ */
+function formatDepositQuoteInfo(quote) {
+    return {
+        ...quote,
+        deposit: formatAssetAmount(quote.deposit),
+        expectedShares: formatAssetAmount(quote.expectedShares),
+        fees: quote.fees.map(formatAssetAmount),
+    };
+}
+/**
+ * Convert a provider withdrawal quote into an EarnKit withdrawal quote result.
+ *
+ * @param quote - Provider withdrawal quote with raw amount objects
+ * @returns Withdrawal quote with withdrawal, shares, max, and fees formatted as strings
+ */
+function formatWithdrawalQuoteInfo(quote) {
+    return {
+        ...quote,
+        withdrawal: formatAssetAmount(quote.withdrawal),
+        sharesToRedeem: formatAssetAmount(quote.sharesToRedeem),
+        maxWithdrawable: formatAssetAmount(quote.maxWithdrawable),
+        fees: quote.fees.map(formatAssetAmount),
+    };
+}
+/**
+ * Convert a provider claim-rewards quote into an EarnKit quote result.
+ *
+ * @param quote - Provider claim-rewards quote with raw reward amount objects
+ * @returns Claim-rewards quote with rewards formatted as strings
+ */
+function formatClaimRewardsQuoteInfo(quote) {
+    return {
+        ...quote,
+        rewards: quote.rewards.map(formatAssetAmount),
+    };
+}
+/**
+ * Convert a provider claim-rewards result into an EarnKit result.
+ *
+ * @param result - Provider claim-rewards result
+ * @returns Claim-rewards result with claimed reward amounts formatted as strings
+ */
+function formatClaimRewardsResult(result) {
+    if (result.status === 'no_rewards') {
+        return result;
+    }
+    return {
+        ...result,
+        rewards: result.rewards.map(formatClaimedAmount),
+    };
+}
+
+/**
+ * Schema for the adapter context within earn operations.
+ *
+ * Validate that a properly-shaped adapter instance and a valid chain
+ * identifier are provided. The address field is optional (resolved from
+ * the adapter at runtime).
+ *
+ * @internal
+ */
+const adapterContextSchema$4 = zod.z.object({
+    adapter: adapterSchema$1,
+    // AdapterContext accepts a wider chain field, but runtime validation must
+    // stay constrained to EarnChain identifiers.
+    chain: earnChainIdentifierSchema,
+    address: zod.z.string().optional(),
+});
+/**
+ * Schema for the EarnConfig options.
+ *
+ * Validate the optional Kit Key field using the standard `apiKeySchema`
+ * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
+ * operates in permissionless mode.
+ *
+ * @internal
+ */
+const earnConfigSchema = zod.z.object({
+    kitKey: apiKeySchema.optional(),
+});
+/**
+ * Schema for validating human-readable decimal amount strings.
+ *
+ * Accept positive decimal strings like '100', '100.50', '0.001'.
+ * Reject zero, negative, and non-numeric strings. Support up to 18
+ * decimal places for maximum token compatibility.
+ *
+ * @internal
+ */
+const amountSchema$1 = zod.z
+    .string({ required_error: 'amount is required' })
+    .min(1, 'amount is required')
+    .pipe(createDecimalStringValidator({
+    allowZero: false,
+    regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
+    attributeName: 'amount',
+    maxDecimals: 18,
+})(zod.z.string()));
+/**
+ * Schema for vault address validation.
+ *
+ * Validate that the vault address is a valid EVM address (0x + 40 hex
+ * chars). EarnKit currently supports EVM vault addresses on Arc Testnet.
+ *
+ * @internal
+ */
+const vaultAddressSchema = evmAddressSchema;
+/**
+ * Validation schema for VaultQuery.
+ *
+ * @example
+ * ```typescript
+ * import { vaultQuerySchema } from '@circle-fin/earn-kit'
+ *
+ * const result = vaultQuerySchema.safeParse({
+ *   chain: 'Arc_Testnet',
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ * })
+ * ```
+ */
+const vaultQuerySchema = zod.z.object({
+    chain: earnChainIdentifierSchema,
+    vaultAddress: vaultAddressSchema,
+});
+/**
+ * Validation schema for GetVaultsParams.
+ *
+ * @example
+ * ```typescript
+ * import { getVaultsParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = getVaultsParamsSchema.safeParse({
+ *   vaults: [
+ *     {
+ *       chain: 'Arc_Testnet',
+ *       vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+const getVaultsParamsSchema = zod.z.object({
+    vaults: zod.z
+        .array(vaultQuerySchema)
+        .min(1, 'at least one vault query is required')
+        .max(20, 'maximum 20 vault queries per request'),
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for GetPositionParams.
+ *
+ * @example
+ * ```typescript
+ * import { getPositionParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = getPositionParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ * })
+ * ```
+ */
+const getPositionParamsSchema = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for DepositParams.
+ *
+ * @example
+ * ```typescript
+ * import { depositParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = depositParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   amount: '100.50',
+ * })
+ * ```
+ */
+const depositParamsSchema$1 = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    amount: amountSchema$1,
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for WithdrawParams.
+ *
+ * @example
+ * ```typescript
+ * import { withdrawParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = withdrawParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   amount: '50.00',
+ * })
+ * ```
+ */
+const withdrawParamsSchema = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    amount: amountSchema$1,
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for ClaimRewardsParams.
+ *
+ * @example
+ * ```typescript
+ * import { claimRewardsParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = claimRewardsParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ * })
+ * ```
+ */
+const claimRewardsParamsSchema = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for GetDepositQuoteParams.
+ *
+ * @example
+ * ```typescript
+ * import { getDepositQuoteParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = getDepositQuoteParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   amount: '100.50',
+ * })
+ * ```
+ */
+const getDepositQuoteParamsSchema = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    amount: amountSchema$1,
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for GetWithdrawalQuoteParams.
+ *
+ * @example
+ * ```typescript
+ * import { getWithdrawalQuoteParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = getWithdrawalQuoteParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   amount: '50.00',
+ * })
+ * ```
+ */
+const getWithdrawalQuoteParamsSchema = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    amount: amountSchema$1,
+    config: earnConfigSchema.optional(),
+});
+/**
+ * Validation schema for GetClaimRewardsQuoteParams.
+ *
+ * @example
+ * ```typescript
+ * import { getClaimRewardsQuoteParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * const result = getClaimRewardsQuoteParamsSchema.safeParse({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ * })
+ * ```
+ */
+const getClaimRewardsQuoteParamsSchema = zod.z.object({
+    from: adapterContextSchema$4,
+    vaultAddress: vaultAddressSchema,
+    config: earnConfigSchema.optional(),
+});
+
+/**
+ * Fetch vault information from the earn service.
+ *
+ * Query the configured earn providers to get information about one
+ * or more DeFi lending vaults. Accept batch queries as chain +
+ * vaultAddress pairs.
+ *
+ * @param context - The EarnKit context containing providers
+ * @param params - Vault query parameters
+ * @returns A promise resolving to the vault lookup results
+ * @throws {@link KitError} If validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { createEarnKitContext, getVaults } from '@circle-fin/earn-kit'
+ *
+ * const context = createEarnKitContext()
+ * const result = await getVaults(context, {
+ *   vaults: [{ chain: 'Arc_Testnet', vaultAddress: '0x...' }],
+ * })
+ * console.log(`Found ${result.vaults.length} vaults`)
+ * ```
+ */
+async function getVaults$1(context, params) {
+    assertEarnParams(params, getVaultsParamsSchema);
+    const provider = findProvider(context);
+    const result = await provider.getVaults({
+        vaults: params.vaults,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+    return formatGetVaultsResult(result);
+}
+
+/**
+ * Resolve the wallet address to use for on-chain operations.
+ *
+ * For developer-controlled adapters, callers pass `address` explicitly and we
+ * return it unchanged. For user-controlled adapters, we fall back to
+ * `adapter.getAddress(chain)`.
+ *
+ * @param from - Adapter context containing the adapter and optional explicit address.
+ * @param chain - Resolved chain definition.
+ * @returns The wallet address.
+ * @throws Propagates errors from `adapter.getAddress(chain)` when
+ *   `from.address` is not supplied.
+ *
+ * @example
+ * ```typescript
+ * const address = await resolveAdapterAddress(params.from, chain)
+ * ```
+ *
+ * @internal
+ */
+async function resolveAdapterAddress(from, chain) {
+    if (from.address !== undefined && from.address !== '') {
+        return from.address;
+    }
+    return from.adapter.getAddress(chain);
+}
+
+/**
+ * Fetch P&L position data for a wallet.
+ *
+ * Query the configured earn providers to get balance, principal,
+ * earnings, and shares data for the wallet specified in the adapter context.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Position query parameters with adapter context
+ * @returns A promise resolving to the wallet's position info
+ * @throws {@link KitError} If validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   getPosition,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const context = createEarnKitContext()
+ * const adapter = createViemAdapterFromPrivateKey({ privateKey: '0x...' })
+ *
+ * const position = await getPosition(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ * })
+ * console.log(`Balance: ${position.currentBalance}`)
+ * ```
+ */
+async function getPosition$1(context, params) {
+    assertEarnParams(params, getPositionParamsSchema);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'getPosition');
+    const address = await resolveAdapterAddress(params.from, chain);
+    const result = await provider.getPosition({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+    return formatPositionInfo(result);
+}
+
+/**
+ * Execute a deposit into a DeFi lending vault.
+ *
+ * Validate user params, resolve the chain and wallet address, then delegate
+ * the full on-chain flow (fetch signed instructions, issue a max USDC ERC-20
+ * approval when needed, submit the deposit, wait for confirmation) to the
+ * selected earn provider.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Deposit parameters including vault address, amount, and adapter
+ * @returns A promise resolving to the deposit result with transaction details
+ * @throws {@link KitError} If validation fails or no provider is configured
+ * @throws {@link KitError} If the chain has no adapter contract configured
+ * @throws {@link KitError} If the chain does not support USDC
+ * @throws {@link KitError} If the USDC approval transaction reverts on-chain
+ * @throws {@link KitError} If the deposit transaction reverts on-chain
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   deposit,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const context = createEarnKitContext()
+ * const adapter = createViemAdapterFromPrivateKey({ privateKey: '0x...' })
+ *
+ * const result = await deposit(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * })
+ * console.log(`Deposited ${result.amount} into ${result.vaultAddress}, tx: ${result.txHash}`)
+ * ```
+ */
+async function deposit$3(context, params) {
+    assertEarnParams(params, depositParamsSchema$1);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'deposit');
+    const address = await resolveAdapterAddress(params.from, chain);
+    return provider.deposit({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+}
+
+/**
+ * Execute a withdrawal from a DeFi lending vault.
+ *
+ * Validate user params, resolve the chain and wallet address, then delegate
+ * the full on-chain flow (fetch signed instructions, issue a max vault-share
+ * ERC-20 approval when needed, submit the withdrawal, wait for confirmation)
+ * to the selected earn provider.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Withdrawal parameters including vault address, amount, and adapter
+ * @returns A promise resolving to the withdrawal result with transaction details
+ * @throws {@link KitError} If validation fails or no provider is configured
+ * @throws {@link KitError} If the chain has no adapter contract configured
+ * @throws {@link KitError} If the vault share token approval transaction reverts on-chain
+ * @throws {@link KitError} If the withdrawal transaction reverts on-chain
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   withdraw,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const context = createEarnKitContext()
+ * const adapter = createViemAdapterFromPrivateKey({ privateKey: '0x...' })
+ *
+ * const result = await withdraw(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '50.00',
+ * })
+ * console.log(`Withdrew ${result.amount} from ${result.vaultAddress}, tx: ${result.txHash}`)
+ * ```
+ */
+async function withdraw$1(context, params) {
+    assertEarnParams(params, withdrawParamsSchema);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'withdraw');
+    const address = await resolveAdapterAddress(params.from, chain);
+    return provider.withdraw({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+}
+
+/**
+ * Claim rewards from earn vaults.
+ *
+ * Validate user params, resolve the chain and wallet address, then delegate
+ * the full on-chain flow (fetch signed instructions, submit the claim, wait
+ * for confirmation) to the selected earn provider. When no rewards are
+ * claimable, the provider returns rewards without submitting a transaction.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Claim parameters including adapter context and vault address
+ * @returns A promise resolving to the claim result with reward details
+ * @throws {@link KitError} If validation fails or no provider is configured
+ * @throws {@link KitError} If the chain has no adapter contract configured
+ * @throws {@link KitError} If the earn service API request or response fails
+ * @throws {@link KitError} If the claim transaction reverts on-chain
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   claimRewards,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const context = createEarnKitContext()
+ * const adapter = createViemAdapterFromPrivateKey({ privateKey: '0x...' })
+ *
+ * const result = await claimRewards(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ * })
+ * if (result.status === 'no_rewards') {
+ *   console.log('No rewards to claim')
+ * } else {
+ *   console.log(`Claimed ${result.rewards.length} reward(s), tx: ${result.txHash}`)
+ * }
+ * ```
+ */
+async function claimRewards$1(context, params) {
+    assertEarnParams(params, claimRewardsParamsSchema);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'claimRewards');
+    const address = await resolveAdapterAddress(params.from, chain);
+    const result = await provider.claimRewards({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        ...(params.config === undefined ? {} : { config: params.config }),
+    });
+    return formatClaimRewardsResult(result);
+}
+
+/**
+ * Get an informational quote for a deposit into a vault.
+ *
+ * Query expected shares, share price, and APY for the specified
+ * deposit amount without executing any transaction.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Deposit quote parameters including vault address and amount
+ * @returns A promise resolving to the deposit quote information
+ * @throws {@link KitError} If validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   getDepositQuote,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ *
+ * const context = createEarnKitContext()
+ * const quote = await getDepositQuote(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * })
+ * console.log(`Expected shares: ${quote.expectedShares.amount}`)
+ * ```
+ */
+async function getDepositQuote$1(context, params) {
+    assertEarnParams(params, getDepositQuoteParamsSchema);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'getDepositQuote');
+    const address = await resolveAdapterAddress(params.from, chain);
+    const result = await provider.getDepositQuote({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+    return formatDepositQuoteInfo(result);
+}
+
+/**
+ * Get an informational quote for a withdrawal from a vault.
+ *
+ * Query shares to redeem, max withdrawable, and fees for the specified
+ * withdrawal amount without executing any transaction.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Withdrawal quote parameters including vault address and amount
+ * @returns A promise resolving to the withdrawal quote information
+ * @throws {@link KitError} If validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   getWithdrawalQuote,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ *
+ * const context = createEarnKitContext()
+ * const quote = await getWithdrawalQuote(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '50.00',
+ * })
+ * console.log(`Shares to redeem: ${quote.sharesToRedeem.amount}`)
+ * ```
+ */
+async function getWithdrawalQuote$1(context, params) {
+    assertEarnParams(params, getWithdrawalQuoteParamsSchema);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'getWithdrawalQuote');
+    const address = await resolveAdapterAddress(params.from, chain);
+    const result = await provider.getWithdrawalQuote({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        amount: params.amount,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+    return formatWithdrawalQuoteInfo(result);
+}
+
+/**
+ * Return all chains supported by configured earn providers.
+ *
+ * @param context - The EarnKit context containing providers
+ * @returns Deduplicated supported chain definitions
+ *
+ * @example
+ * ```typescript
+ * import { createEarnKitContext, getSupportedChains } from '@circle-fin/earn-kit'
+ *
+ * const context = createEarnKitContext()
+ * const chains = getSupportedChains(context)
+ * ```
+ */
+function getSupportedChains$3(context) {
+    const earnChains = new Set(Object.values(exports.EarnChain));
+    const chainsById = new Map();
+    for (const provider of context.providers) {
+        for (const chain of provider.supportedChains) {
+            if (earnChains.has(chain.chain)) {
+                chainsById.set(chain.chain, chain);
+            }
+        }
+    }
+    return [...chainsById.values()];
+}
+
+/**
+ * Get an informational quote for claiming rewards.
+ *
+ * Query claimable reward details without executing any transaction.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ * @param context - The EarnKit context containing providers
+ * @param params - Claim rewards quote parameters including vault address
+ * @returns A promise resolving to the claim rewards quote information
+ * @throws {@link KitError} If validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEarnKitContext,
+ *   getClaimRewardsQuote,
+ *   EarnChain,
+ * } from '@circle-fin/earn-kit'
+ *
+ * const context = createEarnKitContext()
+ * const quote = await getClaimRewardsQuote(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ * })
+ * console.log(`Claimable rewards: ${quote.rewards.length}`)
+ * ```
+ */
+async function getClaimRewardsQuote$1(context, params) {
+    assertEarnParams(params, getClaimRewardsQuoteParamsSchema);
+    const chain = resolveChainIdentifier(params.from.chain);
+    params.from.adapter.validateChainSupport(chain);
+    const provider = findProvider(context, chain, 'getClaimRewardsQuote');
+    const address = await resolveAdapterAddress(params.from, chain);
+    const result = await provider.getClaimRewardsQuote({
+        from: { ...params.from, chain, address },
+        vaultAddress: params.vaultAddress,
+        ...(params.config !== undefined && { config: params.config }),
+    });
+    return formatClaimRewardsQuoteInfo(result);
+}
+
+/**
+ * A high-level class-based interface for DeFi lending vault operations.
+ *
+ * EarnKit provides a familiar class-based API for developers who prefer
+ * traditional object-oriented patterns. The class maintains an internal
+ * context and provides methods for depositing, withdrawing, claiming
+ * rewards, and querying vault and position data.
+ *
+ * Key features:
+ * - Strongly typed parameters with comprehensive Zod validation
+ * - Supported earn vault deposits and withdrawals
+ * - Deposit quote queries (expected shares, share price, APY without executing a transaction)
+ * - Withdrawal quote queries (shares to redeem, max withdrawable, fees without executing a transaction)
+ * - Claim rewards quote queries (claimable reward details without executing a transaction)
+ * - Reward claiming
+ * - P&L position tracking
+ * - Dual-mode authentication (permissioned and permissionless)
+ * - Full TypeScript support with IntelliSense
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain, EarnKit } from '@circle-fin/earn-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const kit = new EarnKit()
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY,
+ * })
+ *
+ * // Fetch vault info
+ * const { vaults } = await kit.getVaults({
+ *   vaults: [{ chain: EarnChain.Arc_Testnet, vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458' }],
+ * })
+ * const [vault] = vaults
+ * if (vault === undefined) {
+ *   throw new Error('No earn vaults available')
+ * }
+ *
+ * // Deposit into a vault
+ * const result = await kit.deposit({
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: vault.vaultAddress,
+ *   amount: '100.50',
+ * })
+ * console.log(`Deposited ${result.amount} into ${result.vaultAddress}, tx: ${result.txHash}`)
+ * ```
+ *
+ * @remarks
+ * For functional usage, import and use the operations directly:
+ * ```typescript
+ * import { createEarnKitContext, deposit } from '@circle-fin/earn-kit'
+ * const context = createEarnKitContext()
+ * await deposit(context, params)
+ * ```
+ */
+class EarnKit {
+    context;
+    /**
+     * Create a new EarnKit instance.
+     *
+     * Accept an optional configuration object to customize the kit's
+     * behavior. If no configuration is provided, the kit is initialized
+     * with default settings using the built-in EarnServiceProvider.
+     *
+     * @param config - Optional configuration for the EarnKit instance
+     *
+     * @example
+     * ```typescript
+     * import { EarnKit } from '@circle-fin/earn-kit'
+     *
+     * // Create with default configuration
+     * const kit = new EarnKit()
+     * ```
+     */
+    constructor(config = {}) {
+        this.context = createEarnKitContext(config);
+    }
+    /**
+     * Return the chains supported by configured earn providers.
+     *
+     * @returns Deduplicated supported chain definitions
+     *
+     * @example
+     * ```typescript
+     * const kit = new EarnKit()
+     * const chains = kit.getSupportedChains()
+     * ```
+     */
+    getSupportedChains() {
+        return getSupportedChains$3(this.context);
+    }
+    /**
+     * Fetch available vault information.
+     *
+     * Query the configured earn providers to get a list of available
+     * DeFi lending vaults with APY, TVL, and reward information.
+     *
+     * @param params - Query parameters with vault address and optional chain filter
+     * @returns A promise resolving to the list of available vaults
+     * @throws {@link KitError} If no provider is configured
+     *
+     * @example
+     * ```typescript
+     * const kit = new EarnKit()
+     * const result = await kit.getVaults({
+     *   vaults: [{ chain: 'Arc_Testnet', vaultAddress: '0x8eB67...' }],
+     * })
+     * result.vaults.forEach(v => console.log(`${v.name}: ${(v.currentApy * 100).toFixed(2)}% APY`))
+     * ```
+     */
+    async getVaults(params) {
+        return getVaults$1(this.context, params);
+    }
+    /**
+     * Fetch P&L position data for the connected wallet.
+     *
+     * Query balance, principal, earnings, and shares data for the wallet
+     * specified in the adapter context.
+     *
+     * @param params - Position query parameters with adapter context
+     * @returns A promise resolving to the wallet's position info
+     * @throws {@link KitError} If validation fails or no provider is configured
+     *
+     * @example
+     * ```typescript
+     * const position = await kit.getPosition({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+     * })
+     * if (position.pnl.status === 'available') {
+     *   console.log(`Yield: ${position.pnl.totalYieldEarned}`)
+     * }
+     * ```
+     */
+    async getPosition(params) {
+        return getPosition$1(this.context, params);
+    }
+    /**
+     * Execute a deposit into a DeFi lending vault.
+     *
+     * Build signed deposit instructions via the earn service, issue a max USDC
+     * ERC-20 approval for the adapter contract when the current allowance is
+     * below the SDK threshold, then submit the deposit on-chain. Return the
+     * confirmed transaction hash together with the deposited amount and target
+     * vault.
+     *
+     * @param params - Deposit parameters including vault address and amount
+     * @returns A promise resolving to the deposit result with transaction details
+     * @throws {@link KitError} If validation fails, no provider is configured, the
+     *   chain has no adapter contract configured, the approval transaction
+     *   reverts on-chain, or the deposit transaction reverts on-chain
+     *
+     * @example
+     * ```typescript
+     * const result = await kit.deposit({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x...',
+     *   amount: '100.50',
+     * })
+     * console.log(`Deposited ${result.amount} into ${result.vaultAddress}, tx: ${result.txHash}`)
+     * ```
+     */
+    async deposit(params) {
+        return deposit$3(this.context, params);
+    }
+    /**
+     * Execute a withdrawal from a DeFi lending vault.
+     *
+     * Build signed withdrawal instructions via the earn service, approve the
+     * adapter contract to spend vault share tokens if needed, then submit the
+     * withdrawal on-chain. Return the withdrawal result including the on-chain
+     * transaction hash, withdrawn amount, and target vault.
+     *
+     * @param params - Withdrawal parameters including vault address and amount
+     * @returns A promise resolving to the withdrawal result with transaction details
+     * @throws {@link KitError} If validation fails, no provider is configured,
+     *   the chain has no adapter contract configured, the share-token approval
+     *   reverts on-chain, or the withdrawal transaction reverts on-chain.
+     *
+     * @example
+     * ```typescript
+     * const result = await kit.withdraw({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x...',
+     *   amount: '50.00',
+     * })
+     * console.log(`Withdrew ${result.amount} from ${result.vaultAddress}, tx: ${result.txHash}`)
+     * ```
+     */
+    async withdraw(params) {
+        return withdraw$1(this.context, params);
+    }
+    /**
+     * Claim rewards from earn vaults.
+     *
+     * Build signed claim rewards instructions via the earn service, submit
+     * them on-chain through the adapter, and return the confirmed transaction
+     * hash. When no rewards are claimable, no transaction is submitted.
+     *
+     * @param params - Claim parameters including adapter context
+     * @returns A promise resolving to the claim result with reward details
+     * @throws {@link KitError} If validation fails or no provider is configured
+     *
+     * @example
+     * ```typescript
+     * const result = await kit.claimRewards({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+     * })
+     *
+     * if (result.status === 'claimed') {
+     *   console.log(`Claimed ${result.rewards.length} reward token(s), tx: ${result.txHash}`)
+     * }
+     * ```
+     */
+    async claimRewards(params) {
+        return claimRewards$1(this.context, params);
+    }
+    /**
+     * Get an informational quote for a deposit into a vault.
+     *
+     * Query expected shares, share price, and APY for the specified
+     * deposit amount without executing any transaction.
+     *
+     * @param params - Deposit quote parameters including vault address and amount
+     * @returns A promise resolving to the deposit quote information
+     * @throws {@link KitError} If validation fails or no provider is configured
+     *
+     * @example
+     * ```typescript
+     * const quote = await kit.getDepositQuote({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x...',
+     *   amount: '100.50',
+     * })
+     * console.log(`Expected shares: ${quote.expectedShares.amount}`)
+     * ```
+     */
+    async getDepositQuote(params) {
+        return getDepositQuote$1(this.context, params);
+    }
+    /**
+     * Get an informational quote for a withdrawal from a vault.
+     *
+     * Query shares to redeem, max withdrawable, and fees for the specified
+     * withdrawal amount without executing any transaction.
+     *
+     * @param params - Withdrawal quote parameters including vault address and amount
+     * @returns A promise resolving to the withdrawal quote information
+     * @throws {@link KitError} If validation fails or no provider is configured
+     *
+     * @example
+     * ```typescript
+     * const quote = await kit.getWithdrawalQuote({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x...',
+     *   amount: '50.00',
+     * })
+     * console.log(`Shares to redeem: ${quote.sharesToRedeem.amount}`)
+     * ```
+     */
+    async getWithdrawalQuote(params) {
+        return getWithdrawalQuote$1(this.context, params);
+    }
+    /**
+     * Get an informational quote for claiming rewards.
+     *
+     * Query claimable reward details without executing any transaction.
+     *
+     * @param params - Claim rewards quote parameters including vault address
+     * @returns A promise resolving to the claim rewards quote information
+     * @throws {@link KitError} If validation fails or no provider is configured
+     *
+     * @example
+     * ```typescript
+     * const quote = await kit.getClaimRewardsQuote({
+     *   from: { adapter, chain: 'Arc_Testnet' },
+     *   vaultAddress: '0x...',
+     * })
+     * console.log(`Claimable rewards: ${quote.rewards.length}`)
+     * ```
+     */
+    async getClaimRewardsQuote(params) {
+        return getClaimRewardsQuote$1(this.context, params);
+    }
+}
+
+/**
+ *
+ * Earn Kit
+ *
+ * A strongly-typed SDK for DeFi lending vault deposits, withdrawals, and rewards
+ * @packageDocumentation
+ */
+// Auto-register this kit for user agent tracking
+registerKit(`${pkg$1.name}/${pkg$1.version}`);
+
+/**
+ * Create an EarnKit instance for AppKit earn operations.
+ *
+ * @remarks The context parameter is reserved for future EarnKit wiring.
+ * EarnKit does not currently support AppKit developer fee hooks, so the
+ * factory does not read fee callbacks from the context. Earn custom fees remain
+ * reserved until EarnKit fee support ships.
+ *
+ * When EarnKit supports developer fee hooks, this factory can wire AppKit context through.
+ *
+ * @param context - AppKit context reserved for future EarnKit wiring
+ * @returns A new EarnKit instance
+ *
+ * @example
+ * ```typescript
+ * const earnKit = createEarnKit(context)
+ * ```
+ */
+const createEarnKit = () => new EarnKit();
+
+/**
+ * Register event handlers from a context actions map to a kit instance.
+ *
+ * This utility function registers event handlers stored in a context actions map
+ * with a kit instance that supports event handling via an `on` method. It handles
+ * wildcard handlers ('*') and prefixed action handlers, stripping the prefix
+ * before registration.
+ *
+ * The function is designed to be reusable across different operation types
+ * (bridge, swap, stake, etc.) by accepting a configurable prefix parameter.
+ *
+ * @param kit - The kit instance to register handlers with (must have an `on` method)
+ * @param handlers - Map of action names to arrays of handler functions
+ * @param prefix - Optional prefix to strip from action names (e.g., 'bridge.')
+ *
+ * @example
+ * ```typescript
+ * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
+ * import { BridgeKit } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ * const handlers = {
+ *   '*': [(payload) => console.log('All actions:', payload)],
+ *   'bridge.approve': [(payload) => console.log('Approved:', payload)],
+ *   'bridge.burn': [(payload) => console.log('Burned:', payload)],
+ * }
+ *
+ * registerActionHandlers(kit, handlers, 'bridge.')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
+ * import { SwapKit } from '@circle-fin/swap-kit'
+ *
+ * const kit = new SwapKit()
+ * const handlers = {
+ *   'swap.initiate': [(payload) => console.log('Swap initiated:', payload)],
+ * }
+ *
+ * registerActionHandlers(kit, handlers, 'swap.')
+ * ```
+ */
+const registerActionHandlers = (kit, handlers, prefix = '') => {
+    for (const [action, handlerArray] of Object.entries(handlers)) {
+        // Register all handlers for this action
+        for (const handler of handlerArray) {
+            if (action === '*') {
+                // Wildcard handlers are registered as-is
+                kit.on('*', handler);
+            }
+            else if (prefix && action.startsWith(prefix)) {
+                // Remove prefix to get the actual kit action name
+                const kitAction = action.split('.').at(1);
+                if (kitAction) {
+                    kit.on(kitAction, handler);
+                }
+            }
+            else if (!prefix) {
+                // No prefix configured, register action as-is
+                kit.on(action, handler);
+            }
+            // Actions that don't match the prefix are silently ignored
+        }
+    }
+};
+
+/**
+ * List of all supported token aliases for App Kit send operations.
+ *
+ * This array is used for runtime validation to check if a token string
+ * is a known alias rather than a custom address.
+ *
+ * @remarks
+ * The type annotation `readonly TokenAlias[]` ensures this array stays in sync
+ * with the TokenAlias type definition - TypeScript will enforce any changes.
+ *
+ * For swap operations, additional tokens (EURC, DAI, USDE, PYUSD) are supported
+ * via SwapKit's SupportedToken type.
+ */
+const TOKEN_ALIASES = ['USDC', 'USDT', 'NATIVE'];
+/**
+ * Check if a token string is a known alias.
+ *
+ * This function performs case-sensitive matching against the list of known
+ * token aliases. Known aliases take precedence over custom addresses in the
+ * send operation logic.
+ *
+ * @param token - The token identifier to check
+ * @returns True if the token is a known alias, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isTokenAlias } from '@circle-fin/app-kit'
+ *
+ * console.log(isTokenAlias('USDC')) // true
+ * console.log(isTokenAlias('NATIVE')) // true
+ * console.log(isTokenAlias('0x6B175474E89094C44Da98b954EedeAC495271d0F')) // false
+ * ```
+ */
+function isTokenAlias(token) {
+    return TOKEN_ALIASES.includes(token);
+}
+/**
+ * Type guard to check if a string is a valid token address for a chain.
+ *
+ * This function verifies that a token string is:
+ * 1. Not a known alias ('USDC', 'USDT', 'NATIVE')
+ * 2. A valid address format for the specified chain
+ *
+ * Use this to narrow the type to `TokenAddress` in TypeScript.
+ *
+ * @param token - The token string to validate
+ * @param chain - The chain definition for address validation
+ * @returns True if the token is a valid address (not an alias)
+ *
+ * @example
+ * ```typescript
+ * import { isTokenAddress } from '@circle-fin/app-kit'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const daiAddress = '0x6B175474E89094C44Da98b954EedeAC495271d0F'
+ * if (isTokenAddress(daiAddress, Ethereum)) {
+ *   // TypeScript knows daiAddress is TokenAddress here
+ *   console.log('Valid token address:', daiAddress)
+ * }
+ *
+ * console.log(isTokenAddress('USDC', Ethereum)) // false - it's an alias
+ * console.log(isTokenAddress('invalid', Ethereum)) // false - invalid format
+ * ```
+ */
+function isTokenAddress(token, chain) {
+    return !isTokenAlias(token) && isValidAddressForChain(token, chain);
+}
+/**
+ * Validate and classify a token identifier.
+ *
+ * This function determines whether a token string is:
+ * 1. A known alias ('USDC', 'USDT', or 'NATIVE')
+ * 2. A valid token address for the given chain
+ * 3. An invalid/unrecognized token identifier
+ *
+ * Known aliases always take precedence. If the token is not an alias,
+ * it's validated as an address for the given chain.
+ *
+ * @param token - The token identifier to validate
+ * @param chain - The chain definition for address validation
+ * @returns An object containing validation results
+ *
+ * @example
+ * ```typescript
+ * import { validateToken } from '@circle-fin/app-kit'
+ * import { Ethereum } from '@core/chains'
+ *
+ * // Known alias
+ * const usdc = validateToken('USDC', Ethereum)
+ * console.log(usdc) // { isAlias: true, isAddress: false, isValid: true }
+ *
+ * // Custom token address
+ * const dai = validateToken('0x6B175474E89094C44Da98b954EedeAC495271d0F', Ethereum)
+ * console.log(dai) // { isAlias: false, isAddress: true, isValid: true }
+ *
+ * // Invalid token
+ * const invalid = validateToken('invalid', Ethereum)
+ * console.log(invalid) // { isAlias: false, isAddress: false, isValid: false }
+ * ```
+ */
+function validateToken(token, chain) {
+    // Check if it's a known alias first (aliases take precedence)
+    const alias = isTokenAlias(token);
+    if (alias) {
+        return {
+            isAlias: true,
+            isAddress: false,
+            isValid: true,
+        };
+    }
+    // Not an alias - check if it's a valid address for the chain
+    const address = isTokenAddress(token, chain);
+    return {
+        isAlias: false,
+        isAddress: address,
+        isValid: address,
+    };
+}
+
+/**
+ * Estimate the costs and details of a cross-chain bridge transfer using the AppKit context.
+ *
+ * This function provides cost estimation for bridge operations within the AppKit
+ * ecosystem. It delegates to the underlying BridgeKit infrastructure while maintaining
+ * consistency with the AppKit patterns and context-based architecture.
+ *
+ * The function validates parameters, applies context-specific configurations,
+ * and returns comprehensive estimation details including fees, gas costs, and
+ * transaction parameters without executing the actual transfer.
+ *
+ * @param context - AppKit context containing fee calculation and configuration hooks
+ * @param params - Bridge parameters containing source, destination, amount, and token
+ * @returns Promise resolving to the estimate result with comprehensive fee and cost information
+ * @throws If bridge parameters are invalid
+ * @throws If the bridge route is not supported
+ * @throws If estimation fails due to network or configuration issues
+ *
+ * @example
+ * ```typescript
+ * import { estimateBridge } from '@circle-fin/app-kit/bridge'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ *
+ * const context = createContext({
+ *   getFee: async (type, params) => '1000000', // 1 USDC fee
+ *   getFeeRecipient: async (type, info) => '0xfee-recipient-address'
+ * })
+ *
+ * const estimate = await estimateBridge(context, {
+ *   from: sourceAdapter,
+ *   to: { adapter: destAdapter, chain: 'Polygon' },
+ *   amount: '100.50',
+ *   token: 'USDC'
+ * })
+ *
+ * console.log('Estimated total fee:', estimate.fee)
+ * console.log('Estimated gas cost:', estimate.gasEstimate)
+ * ```
+ */
+const estimateBridge = async (context, params) => {
+    const kit = createBridgeKit(context);
+    // Delegate to the BridgeKit for actual estimation
+    return kit.estimate(params);
+};
+
+const assertSendParamsSymbol = Symbol('assertSendParams');
+/**
+ * Matches numeric amount strings with optional thousands separators and decimal part.
+ *
+ * Accepts both US (e.g. "1,234.56") and EU (e.g. "1.234,56") styles by allowing
+ * either "," or "." as the grouping and decimal separators. Also matches integers
+ * like "10" and simple decimals like "10.5" or "10,5".
+ */
+const amountNumericStringWithSeparatorsRegex = /^\d+(?:[.,]\d{3})*(?:[.,]\d+)?$/;
+/**
+ * Schema describing the minimal adapter surface required by the kit.
+ *
+ * The adapter must implement two functions:
+ * - `prepare` — build the transaction or instruction payload.
+ * - `waitForTransaction` — await finality/confirmation for a submitted transaction.
+ *
+ * @returns Zod schema validating an object with `prepare` and `waitForTransaction` functions.
+ *
+ * @example
+ * ```typescript
+ * import { adapterSchema } from '@circle-fin/app-kit'
+ *
+ * console.log(adapterSchema.safeParse(ethereumAdapter).success) // true
+ * ```
+ */
+const adapterSchema = zod.z.object({
+    prepare: zod.z.function().returns(zod.z.any()),
+    waitForTransaction: zod.z.function().returns(zod.z.any()),
+});
+/**
+ * Schema for validating adapter contexts.
+ * Ensure required fields are present and properly typed. An adapter context must include:
+ * - A valid adapter with `prepare` and `waitForTransaction` methods.
+ * - A valid chain identifier (string literal or chain object recognized by the kit).
+ *
+ * @returns Zod schema validating an adapter context object.
+ * @throws ZodError If validation fails, with details about which properties failed.
+ *
+ * @example
+ * ```typescript
+ * import { adapterContextSchema } from '@circle-fin/app-kit'
+ *
+ * const result = adapterContextSchema.safeParse(context)
+ * console.log(result.success) // true
+ * ```
+ */
+const adapterContextSchema$3 = zod.z.object({
+    adapter: adapterSchema,
+    /**
+     * Note: We cast chainIdentifierSchema to 'never' here to work around a TypeScript
+     * limitation (TS2589: Type instantiation is excessively deep and possibly infinite)
      * that can occur with complex Zod unions (e.g., string literals + enums).
      * This cast is safe in this context because runtime validation is correct,
      * and the type is enforced at the API boundary.
@@ -30058,14 +33241,15 @@ const estimateSwap = async (context, params) => {
  * Get chains supported by AppKit operations.
  *
  * This helper returns the set of chains that can be used for a given
- * operation type (bridge, swap, or both). When no operation type is specified,
- * it returns all chains known to support any AppKit operation.
+ * operation type (bridge, swap, earn, unified balance, or all). When no
+ * operation type is specified, it returns all chains known to support any
+ * AppKit operation.
  *
  * The result list contains unique chains and is safe to pass directly into
  * higher-level flows such as chain pickers or routing logic.
  *
  * @param context - AppKit context containing fee configuration.
- * @param operationType - Optional operation type to filter chains ('bridge' | 'swap' | 'unifiedBalance').
+ * @param operationType - Optional operation type to filter chains ('bridge' | 'swap' | 'earn' | 'unifiedBalance').
  * @param unifiedBalance - Persistent AppKitUnifiedBalance namespace instance.
  * @returns Array of unique chain definitions supporting the specified operation(s)
  *
@@ -30091,6 +33275,12 @@ const estimateSwap = async (context, params) => {
  * console.log('Chains supporting swap:', swapChains.map(c => c.name))
  * ```
  *
+ * @example Get earn-specific chains
+ * ```typescript
+ * const earnChains = kit.getSupportedChains('earn')
+ * console.log('Chains supporting earn:', earnChains.map(c => c.name))
+ * ```
+ *
  * @example Check if specific chain supports an operation
  * ```typescript
  * import { Ethereum } from '@core/chains'
@@ -30105,11 +33295,12 @@ const getSupportedChains$2 = (context, operationType, unifiedBalance) => {
     if (operationType !== undefined &&
         operationType !== 'bridge' &&
         operationType !== 'swap' &&
+        operationType !== 'earn' &&
         operationType !== 'unifiedBalance') {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
             recoverability: 'FATAL',
-            message: `Invalid operationType: "${String(operationType)}". Expected 'bridge', 'swap', or 'unifiedBalance'.`,
+            message: `Invalid operationType: "${String(operationType)}". Expected 'bridge', 'swap', 'earn', or 'unifiedBalance'.`,
         });
     }
     // Return bridge-specific chains
@@ -30122,23 +33313,228 @@ const getSupportedChains$2 = (context, operationType, unifiedBalance) => {
         const swapKit = createSwapKit(context);
         return swapKit.getSupportedChains();
     }
+    // Return earn-specific chains
+    if (operationType === 'earn') {
+        const earnKit = createEarnKit();
+        return earnKit.getSupportedChains();
+    }
     // Return unified balance chains
     if (operationType === 'unifiedBalance') {
         return unifiedBalance.getSupportedChains();
     }
     // No operation type specified - return union of all chains
+    // Reuse kit instances here if provider constructors become expensive or stateful.
     const bridgeKit = createBridgeKit(context);
     const swapKit = createSwapKit(context);
+    const earnKit = createEarnKit();
     const bridgeChains = bridgeKit.getSupportedChains();
     const swapChains = swapKit.getSupportedChains();
+    const earnChains = earnKit.getSupportedChains();
     const ubChains = unifiedBalance.getSupportedChains();
-    const allChains = [...bridgeChains, ...swapChains, ...ubChains];
-    // Deduplicate by chain identifier
-    return Object.values(Object.fromEntries(allChains.map((chain) => [chain.chain, chain])));
+    // Combine chains from all operations
+    const allChains = [...bridgeChains, ...swapChains, ...earnChains, ...ubChains];
+    // Deduplicate by chain identifier. Later duplicates override earlier ones.
+    return [...new Map(allChains.map((chain) => [chain.chain, chain])).values()];
 };
 
+/**
+ * Execute an earn deposit operation.
+ *
+ * @param context - AppKit context
+ * @param params - Deposit parameters including source adapter, vault address, and amount
+ * @returns Promise resolving to the earn deposit result
+ * @throws If EarnKit validation fails, no provider is configured, or the deposit transaction fails
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { deposit } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const result = await deposit(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * })
+ * ```
+ */
+async function deposit$2(context, params) {
+    return createEarnKit().deposit(params);
+}
+/**
+ * Execute an earn withdrawal operation.
+ *
+ * @param context - AppKit context
+ * @param params - Withdrawal parameters including source adapter, vault address, and amount
+ * @returns Promise resolving to the earn withdrawal result
+ * @throws If EarnKit validation fails, no provider is configured, or the withdrawal transaction fails
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { withdraw } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const result = await withdraw(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '50.00',
+ * })
+ * ```
+ */
+async function withdraw(context, params) {
+    return createEarnKit().withdraw(params);
+}
+/**
+ * Claim earn rewards.
+ *
+ * @param context - AppKit context
+ * @param params - Claim rewards parameters including source adapter and vault address
+ * @returns Promise resolving to the earn claim rewards result
+ * @throws If EarnKit validation fails, no provider is configured, or the claim transaction fails
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { claimRewards } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const result = await claimRewards(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ * })
+ * ```
+ */
+async function claimRewards(context, params) {
+    return createEarnKit().claimRewards(params);
+}
+/**
+ * Fetch vault information.
+ *
+ * @param context - AppKit context
+ * @param params - Vault query parameters. `vaults` selects the chain and vault address pairs to query
+ * @returns Promise resolving to vault data and per-vault errors
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { getVaults } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const result = await getVaults(context, {
+ *   vaults: [{ chain: EarnChain.Arc_Testnet, vaultAddress: '0x...' }],
+ * })
+ * ```
+ */
+async function getVaults(context, params) {
+    return createEarnKit().getVaults(params);
+}
+/**
+ * Fetch a wallet position in a vault.
+ *
+ * @param context - AppKit context
+ * @param params - Position parameters including source adapter and vault address
+ * @returns Promise resolving to wallet position information
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { getPosition } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const position = await getPosition(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ * })
+ * ```
+ */
+async function getPosition(context, params) {
+    return createEarnKit().getPosition(params);
+}
+/**
+ * Fetch a deposit quote.
+ *
+ * @param context - AppKit context
+ * @param params - Deposit quote parameters including source adapter, vault address, and amount
+ * @returns Promise resolving to deposit quote information
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { getDepositQuote } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const quote = await getDepositQuote(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * })
+ * ```
+ */
+async function getDepositQuote(context, params) {
+    return createEarnKit().getDepositQuote(params);
+}
+/**
+ * Fetch a withdrawal quote.
+ *
+ * @param context - AppKit context
+ * @param params - Withdrawal quote parameters including source adapter, vault address, and amount
+ * @returns Promise resolving to withdrawal quote information
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { getWithdrawalQuote } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const quote = await getWithdrawalQuote(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ *   amount: '50.00',
+ * })
+ * ```
+ */
+async function getWithdrawalQuote(context, params) {
+    return createEarnKit().getWithdrawalQuote(params);
+}
+/**
+ * Fetch a claim rewards quote.
+ *
+ * @param context - AppKit context
+ * @param params - Claim rewards quote parameters including source adapter and vault address
+ * @returns Promise resolving to claim rewards quote information
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { getClaimRewardsQuote } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const quote = await getClaimRewardsQuote(context, {
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
+ *   vaultAddress: '0x...',
+ * })
+ * ```
+ */
+async function getClaimRewardsQuote(context, params) {
+    return createEarnKit().getClaimRewardsQuote(params);
+}
+
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.1.1";
+var version = "1.1.2";
 var pkg = {
 	name: name,
 	version: version};
@@ -37057,7 +40453,7 @@ class AppKitUnifiedBalance {
 }
 
 /**
- * A high-level SDK for stablecoin operations, including bridging and swapping.
+ * A high-level SDK for stablecoin operations, including bridging, swapping, and earn.
  *
  * The AppKit provides a unified interface for various stablecoin operations
  * with strongly typed parameters and comprehensive fee estimation capabilities.
@@ -37068,6 +40464,7 @@ class AppKitUnifiedBalance {
  * - Strongly typed fee estimation with operation-specific parameters
  * - Cross-chain USDC bridging through CCTPv2
  * - Same-chain token swapping between USDC, USDT, and native tokens
+ * - Earn vault deposits, withdrawals, rewards, and quote queries
  * - Token sending operations
  * - Comprehensive error handling and validation
  * - Full TypeScript support with IntelliSense
@@ -37100,6 +40497,13 @@ class AppKitUnifiedBalance {
  *   amountIn: '50.00'
  * })
  *
+ * // Query an earn vault
+ * const quote = await kit.earn.getDepositQuote({
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * })
+ *
  * // Query unified balances across chains
  * const balances = await kit.unifiedBalance.getBalances({
  *   token: 'USDC',
@@ -37114,6 +40518,25 @@ class AppKitUnifiedBalance {
  */
 class AppKit {
     context;
+    /**
+     * Earn operations exposed under `kit.earn`.
+     *
+     * @see {@link AppKitEarnOperations}
+     *
+     * @example
+     * ```typescript
+     * import { AppKit, EarnChain } from '@circle-fin/app-kit'
+     *
+     * const kit = new AppKit()
+     *
+     * const result = await kit.earn.deposit({
+     *   from: { adapter, chain: EarnChain.Arc_Testnet },
+     *   vaultAddress: '0x...',
+     *   amount: '100.50',
+     * })
+     * ```
+     */
+    earn;
     /**
      * Namespace object for unified balance operations (deposit, spend,
      * balance queries, delegation, fund removal).
@@ -37167,6 +40590,16 @@ class AppKit {
                 disableErrorReporting: config.disableErrorReporting,
             }),
         });
+        this.earn = {
+            deposit: async (params) => deposit$2(this.context, params),
+            withdraw: async (params) => withdraw(this.context, params),
+            claimRewards: async (params) => claimRewards(this.context, params),
+            getVaults: async (params) => getVaults(this.context, params),
+            getPosition: async (params) => getPosition(this.context, params),
+            getDepositQuote: async (params) => getDepositQuote(this.context, params),
+            getWithdrawalQuote: async (params) => getWithdrawalQuote(this.context, params),
+            getClaimRewardsQuote: async (params) => getClaimRewardsQuote(this.context, params),
+        };
     }
     /**
      * Execute a cross-chain USDC bridge transfer.
@@ -37424,9 +40857,9 @@ class AppKit {
      *
      * Returns blockchain networks that support specific stablecoin operations.
      * When no operation type is specified, returns all chains supporting any
-     * operation (bridge, swap, or unified balance).
+     * operation (bridge, swap, earn, or unified balance).
      *
-     * @param operationType - Optional operation type to filter chains ('bridge' | 'swap' | 'unifiedBalance')
+     * @param operationType - Optional operation type to filter chains ('bridge' | 'swap' | 'earn' | 'unifiedBalance')
      * @returns Array of unique chain definitions supporting the specified operation(s)
      *
      * @example Get all supported chains
@@ -37489,6 +40922,8 @@ class AppKit {
 
 exports.AppKit = AppKit;
 exports.BalanceError = BalanceError;
+exports.EarnError = EarnError;
+exports.EarnKit = EarnKit;
 exports.InputError = InputError;
 exports.KitError = KitError;
 exports.NetworkError = NetworkError;
@@ -37497,9 +40932,26 @@ exports.RateLimitError = RateLimitError;
 exports.RpcError = RpcError;
 exports.ServiceError = ServiceError;
 exports.TOKEN_ALIASES = TOKEN_ALIASES;
+exports.claimRewardsParamsSchema = claimRewardsParamsSchema;
+exports.createEarnKitContext = createEarnKitContext;
+exports.depositParamsSchema = depositParamsSchema$1;
+exports.earnClaimRewards = claimRewards$1;
+exports.earnDeposit = deposit$3;
+exports.earnGetClaimRewardsQuote = getClaimRewardsQuote$1;
+exports.earnGetDepositQuote = getDepositQuote$1;
+exports.earnGetPosition = getPosition$1;
+exports.earnGetSupportedChains = getSupportedChains$3;
+exports.earnGetVaults = getVaults$1;
+exports.earnGetWithdrawalQuote = getWithdrawalQuote$1;
+exports.earnWithdraw = withdraw$1;
+exports.getClaimRewardsQuoteParamsSchema = getClaimRewardsQuoteParamsSchema;
+exports.getDepositQuoteParamsSchema = getDepositQuoteParamsSchema;
 exports.getErrorCode = getErrorCode;
 exports.getErrorMessage = getErrorMessage;
+exports.getPositionParamsSchema = getPositionParamsSchema;
 exports.getTokenDecimals = getTokenDecimals;
+exports.getVaultsParamsSchema = getVaultsParamsSchema;
+exports.getWithdrawalQuoteParamsSchema = getWithdrawalQuoteParamsSchema;
 exports.isBalanceError = isBalanceError;
 exports.isFatalError = isFatalError;
 exports.isInputError = isInputError;
@@ -37515,4 +40967,5 @@ exports.isTokenAlias = isTokenAlias;
 exports.isUserCancellationError = isUserCancellationError;
 exports.setExternalPrefix = setExternalPrefix;
 exports.validateToken = validateToken;
+exports.withdrawParamsSchema = withdrawParamsSchema;
 //# sourceMappingURL=index.cjs.map