@unifold/core 0.1.70-beta.1 → 0.1.70

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-type ChainType = 'ethereum' | 'solana' | 'bitcoin' | 'algorand' | 'xrpl' | 'cardano' | 'n1';
+type ChainType = 'ethereum' | 'solana' | 'bitcoin' | 'algorand' | 'xrpl' | 'cardano' | 'n1' | 'tron';
 
 declare function setApiConfig(config: {
     baseUrl?: string;
@@ -337,7 +337,13 @@ interface OnrampQuote {
     destination_currency: string;
     destination_network: string;
     exchange_rate: number;
-    payment_method_type: string;
+    /**
+     * Unified payment method type (`card` / `apple_pay` / `sepa`). Provider-native
+     * values (e.g. Meld's `credit_debit_card`) are normalized to this vocabulary.
+     */
+    payment_method_type: OnrampSessionPaymentMethodType;
+    /** @deprecated Use `payment_method_type` instead (same value). */
+    payment_method: OnrampSessionPaymentMethodType;
     customer_score: number;
     service_provider: string;
     service_provider_display_name: string;
@@ -371,7 +377,12 @@ declare function getOnrampQuotes(request: OnrampQuotesRequest, publishableKey?:
  * (Coinbase only) — useful as a fallback when the headless Apple Pay flow
  * is unavailable.
  */
-type OnrampSessionPaymentMethod = 'card' | 'sepa' | 'apple_pay';
+type OnrampSessionPaymentMethodType = 'card' | 'sepa' | 'apple_pay';
+/**
+ * @deprecated Use `OnrampSessionPaymentMethodType` instead. Retained as an alias so
+ * previously-released SDK consumers keep compiling.
+ */
+type OnrampSessionPaymentMethod = OnrampSessionPaymentMethodType;
 interface OnrampSessionRequest {
     service_provider: string;
     country_code: string;
@@ -384,7 +395,13 @@ interface OnrampSessionRequest {
     redirect_url?: string;
     external_id?: string;
     email?: string;
-    payment_method?: OnrampSessionPaymentMethod;
+    /**
+     * Payment method type for the session (`card` / `sepa` / `apple_pay`).
+     * Defaults to `card`.
+     */
+    payment_method_type?: OnrampSessionPaymentMethodType;
+    /** @deprecated Use `payment_method_type` instead (same value). */
+    payment_method?: OnrampSessionPaymentMethodType;
 }
 interface OnrampSessionResponse {
     url: string;
@@ -418,7 +435,7 @@ interface BankTransferProvider {
      * a single provider can light up multiple rails (e.g. SEPA + ACH) without
      * forking the row.
      */
-    payment_methods: OnrampSessionPaymentMethod[];
+    payment_methods: OnrampSessionPaymentMethodType[];
     /** All fiat currencies the rail accepts (e.g. ['eur', 'gbp']). */
     supported_currencies: string[];
     /**
@@ -1587,18 +1604,32 @@ interface StripeQuotesResponse {
  * Backend error_type values for headless Stripe onramp failures. The SDK can
  * branch on these instead of string-matching Stripe messages.
  */
-type StripeOnrampErrorType = 'stripe_onramp_missing_minimum_identity_verification' | 'stripe_onramp_missing_identity_verification' | 'stripe_onramp_missing_document_verification' | 'stripe_onramp_purchase_limit_reached' | 'stripe_onramp_bad_request' | 'stripe_onramp_forbidden' | 'stripe_onramp_not_found' | 'stripe_onramp_upstream_error' | (string & NonNullable<unknown>);
+type StripeOnrampErrorType = 'stripe_onramp_missing_minimum_identity_verification' | 'stripe_onramp_missing_identity_verification' | 'stripe_onramp_missing_document_verification' | 'stripe_onramp_purchase_limit_reached' | 'stripe_onramp_payment_method_consumed' | 'stripe_onramp_bad_request' | 'stripe_onramp_forbidden' | 'stripe_onramp_not_found' | 'stripe_onramp_upstream_error' | (string & NonNullable<unknown>);
 declare class StripeApiResponseError extends Error {
     readonly statusCode: number;
     /** Underlying Stripe error code (e.g. `crypto_onramp_session_error`), when available */
     readonly stripeCode?: string | undefined;
     /** Unifold backend error_type (e.g. `stripe_onramp_missing_document_verification`) */
     readonly errorType?: StripeOnrampErrorType | undefined;
+    /**
+     * The raw Stripe error message (from `details.stripe_error.message`), without
+     * the operation prefix baked into `message`. This is the human-readable text
+     * Stripe returns (e.g. "Your card was declined.") and is safe to show to the
+     * user directly when there's no more specific mapped message.
+     */
+    readonly stripeMessage?: string | undefined;
     constructor(message: string, statusCode: number, 
     /** Underlying Stripe error code (e.g. `crypto_onramp_session_error`), when available */
     stripeCode?: string | undefined, 
     /** Unifold backend error_type (e.g. `stripe_onramp_missing_document_verification`) */
-    errorType?: StripeOnrampErrorType | undefined);
+    errorType?: StripeOnrampErrorType | undefined, 
+    /**
+     * The raw Stripe error message (from `details.stripe_error.message`), without
+     * the operation prefix baked into `message`. This is the human-readable text
+     * Stripe returns (e.g. "Your card was declined.") and is safe to show to the
+     * user directly when there's no more specific mapped message.
+     */
+    stripeMessage?: string | undefined);
 }
 /**
  * Fetch Stripe config (publishable key + merchant ID) for SDK initialization.
@@ -2277,7 +2308,16 @@ interface DepositSessionParams {
 interface DepositSessionConfig extends DepositSessionParams {
     publishableKey: string;
 }
-type DepositSessionStatus = 'idle' | 'creating_addresses' | 'awaiting_funds' | 'processing' | 'succeeded' | 'failed' | 'error';
+/**
+ * Session status is LIFECYCLE-ONLY. A DepositSession is an ongoing watcher
+ * that can observe many executions, so execution outcomes deliberately never
+ * appear here — a session-level "succeeded"/"failed" misleads the moment a
+ * second deposit arrives (a failure right after a success would flip the
+ * whole session to "failed"). Outcomes live on the executions themselves:
+ * `snapshot.executions` / `latestExecution` statuses, the
+ * `direct_execution.succeeded`/`.failed` events, and `waitForSuccess()`.
+ */
+type DepositSessionStatus = 'idle' | 'creating_addresses' | 'ready' | 'processing' | 'error';
 interface DepositSessionSnapshot {
     status: DepositSessionStatus;
     /** Deposit addresses (one per chain type); empty until created. */
@@ -2350,6 +2390,9 @@ declare class DepositSession {
     private baselineMs;
     private tracked;
     private pollErrorLatched;
+    private pollInFlight;
+    /** First execution to succeed this run — waitForSuccess's one-shot answer. */
+    private firstSuccess;
     private detectionTimer;
     private nudgeTimer;
     private armTimer;
@@ -2388,9 +2431,11 @@ declare class DepositSession {
     destroy(): void;
     /**
      * Resolve when the session reaches one of the given statuses (immediately
-     * if it's already there). Generic primitive over the status state machine:
-     * `waitForStatus('processing')` awaits detection; `waitForStatus(['succeeded',
-     * 'failed'])` awaits a terminal outcome.
+     * if it's already there). Generic primitive over the lifecycle state
+     * machine — e.g. `waitForStatus('processing')` awaits detection of live
+     * activity, `waitForStatus('ready')` awaits readiness. Statuses
+     * carry no outcomes; await those with {@link waitForSuccess} or the
+     * `direct_execution.*` events.
      *
      * Rejects with {@link DepositSessionWaitError} on abort or destroy().
      * Does not start or stop the session — it only listens.
@@ -2404,14 +2449,15 @@ declare class DepositSession {
      * Multi-execution semantics (unlike quote-scoped models such as Privy's,
      * one session can observe many executions — a user may send twice, or on
      * two chains): this waiter is one-shot "first completion" detection. If an
-     * execution has already succeeded, it resolves immediately with that
-     * execution. The session keeps polling after success — to react to every
-     * settlement, subscribe to `direct_execution.succeeded` events or read
-     * `snapshot.executions` instead.
+     * execution has already succeeded this run, it resolves immediately with
+     * the FIRST one that did (not the newest). The session keeps polling after
+     * success — to react to every settlement, subscribe to
+     * `direct_execution.succeeded` events or read `snapshot.executions`.
      *
      * Rejects with {@link DepositSessionWaitError}:
-     * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails
-     *   before any succeeds,
+     * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails and
+     *   NO other observed execution is still in flight — a failure while
+     *   another deposit is pending keeps waiting (that one may still succeed),
      * - `SESSION_ERROR` (cause: the fatal {@link DepositSessionError}) on fatal
      *   session errors (e.g. address creation failed),
      * - `ABORTED` / `DESTROYED` per the wait options and session lifecycle.
@@ -2438,8 +2484,10 @@ declare class DepositSession {
     private runStartChecks;
     private startDetectionLoop;
     private pollExecutions;
+    private pollExecutionsOnce;
     private processExecutionChange;
     private armConfirmation;
+    private anyExecutionInFlight;
     private setStatus;
     private clearTimers;
     private buildSnapshot;
@@ -2646,4 +2694,4 @@ declare const i18n: {
 };
 type I18nStrings = typeof i18n;
 
-export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AddressVerification, type ApplePayLimitUpgradeStatus, type ApplePayProvider, type ApplePayProvidersResponse, type AuthenticateOAuthResult, type AutoSwapRequest, type AutoSwapResponse, type BankTransferConfig, type BankTransferProvider, type BankTransferProvidersResponse, type BlockedCountrySubdivision, type BuildHypercoreTransactionRequest, type BuildHypercoreTransactionResponse, type BuildSolanaTransactionRequest, type BuildSolanaTransactionResponse, type CashAppLimits, type CashAppSessionRequest, type CashAppSessionResponse, type CashAppSessionStatusResponse, type ChainType, type CheckoutEvent, CheckoutEventType, type CheckoutMethod, type CheckoutPaymentIntent, type CheckoutPaymentIntentData, type CheckoutPaymentIntentSucceededEvent, type CoinbaseApplePayLimit, type CoinbaseApplePayLimitUpgradeOption, type CoinbaseApplePayLimitsResponse, type CoinbaseApplePaySessionResponse, type CoinbaseLegalAgreement, type CoinbaseLegalAgreementsResponse, type ConfirmIntegrationTransferResult, type CreateCoinbaseApplePaySessionRequest, type CreateDepositAddressRequest, type CreateExchangeSessionRequest, type CreateExchangeSessionResponse, type CreateIntegrationTransferParams, type CreateIntegrationTransferResult, type CreateOnrampVerificationSessionRequest, DETECTION_ARM_DELAY_MS, DETECTION_POLL_INTERVAL_MS, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddress, type DepositAddressParams, type DepositAddressResponse, DepositAddressValidationError, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, DepositSession, type DepositSessionConfig, type DepositSessionDestination, type DepositSessionError, type DepositSessionErrorCode, type DepositSessionEvent, type DepositSessionEventMap, DepositSessionEventType, type DepositSessionParams, type DepositSessionSnapshot, type DepositSessionStatus, DepositSessionWaitError, type DepositSessionWaitErrorCode, type DepositSessionWaitOptions, type DestinationToken, type DestinationTokenChain, type DirectExecution, type DirectExecutionResponse, type DirectExecutionSucceededEvent, type EvmContractCall, type ExchangeProviderInfo, type ExchangeProvidersResponse, type ExchangeSessionStartParams, type ExchangeWalletAddress, ExecutionStatus, type ExternalWalletChainType, type ExternalWalletInfo, type ExternalWalletsResponse, type FeaturedToken, type FeaturedWallet, type FiatCurrenciesResponse, type FiatCurrency, type GetBankTransferProvidersOptions, type GetExchangesQuery, type HypercoreActivationRequest, type HypercoreActivationResponse, type I18nStrings, type IconUrl, IneligibilityReason, type IntegrationAccount, type IntegrationExchangeInfo, type IntegrationExchangesResponse, type IntegrationFeeAmount, type IntegrationHoldingsResponse, IntegrationProvider, type IpAddressResponse, LOOKBACK_MS, type ListExecutionsParams, type LockedQuoteLimits, type LockedQuotePreview, type LockedQuotePreviewRequest, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionCreatedData, type OnrampSessionCreatedEvent, type OnrampSessionPaymentMethod, type OnrampSessionRequest, type OnrampSessionResponse, type OnrampVerificationFactor, type OnrampVerificationFactorStatus, type OnrampVerificationSession, type OnrampVerificationStatus, type OnrampVerificationTokenResponse, type PaymentIntent, type PaymentIntentDepositAddress, type PaymentIntentExecutionsResponse, type PaymentIntentStatus, type PaymentIntentType, type PaymentNetwork, type PollExecutionsRequest, type PollExecutionsResponse, type ProductType, type ProjectConfigResponse, type PublicIncidentResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, type RequestCoinbaseApplePayLimitUpgradeRequest, type RequestCoinbaseApplePayLimitUpgradeResponse, SCAN_NUDGE_INTERVAL_MS, SOLANA_USDC_ADDRESS, type SendHypercoreTransactionRequest, type SendHypercoreTransactionResponse, type SendSolanaTransactionRequest, type SendSolanaTransactionResponse, type SourceToken, type SourceTokenNetwork, type StartIntegrationOAuthResult, type StripeAccessTokenResponse, StripeApiResponseError, type StripeAuthIntentResponse, type StripeConfigResponse, type StripeConfirmRequest, type StripeConsumerWallet, type StripeCreateSessionRequest, type StripeCryptoCustomer, type StripeCustomerVerification, type StripeDefaultTokenResponse, type StripeListResponse, type StripeOnrampErrorType, type StripeOnrampSession, type StripeOnrampTransactionDetails, type StripePaymentToken, type StripeQuoteRequest, type StripeQuotesResponse, type StripeTransactionLimitEntry, type StripeTransactionLimitsResponse, type SupportedChain, type SupportedDepositTokensParams, type SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenDisplayMetadata, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, UnifoldClient, type UnifoldClientOptions, type UserIpInfo, type VerifyAddressParams, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, type WalletMobileDeepLinkDepositAddress, type WalletMobileDeepLinkResponse, type WalletMobileDeepLinkWallet, type WithdrawDirectExecutionSucceededEvent, type WithdrawEvent, WithdrawEventType, authenticateIntegrationOAuth, buildHypercoreTransaction, buildSolanaTransaction, checkHypercoreActivation, confirmIntegrationTransfer, createCashAppSession, createCoinbaseApplePaySession, createDepositAddress, createExchangeSession, createIntegrationTransfer, createOnrampSession, createOnrampVerificationSession, createUnifoldClient, exchangeOnrampVerificationToken, formatStablecoinAmount, generateKSUID, generatePrefixedKSUID, getAddressBalance, getAddressBalances, getApiBaseUrl, getApplePayLimitUpgradeStatus, getApplePayProviders, getBankTransferProviders, getCashAppLimits, getCashAppSessionStatus, getChainName, getCoinbaseApplePayLimits, getCoinbaseLegalAgreements, getDefaultOnrampToken, getDepositAddress, getDepositQuote, getExchangeSessionStartUrl, getExchanges, getExternalWallets, getFiatCurrencies, getFiatExchangeRates, getIconUrl, getIconUrlWithCdn, getIntegrationExchanges, getIntegrationHoldings, getIntegrationTransferDefaultToken, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getOnrampVerificationSession, getPreferredIconUrl, getProjectConfig, getPublicIncident, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, isApplePayLimitReached, isDepositAddressValidationError, listPaymentIntentExecutions, mapDirectExecution, mapWalletToDepositAddress, pollDirectExecutions, queryExecutions, refreshIntegrationToken, requestCoinbaseApplePayLimitUpgrade, retrievePaymentIntent, revokeIntegrationToken, sendHypercoreTransaction, sendOnrampVerificationOtp, sendSolanaTransaction, setApiConfig, startIntegrationOAuth, stripeConfirmSession, stripeCreateAuthIntent, stripeCreateSession, stripeExchangeTokens, stripeGetConfig, stripeGetCustomer, stripeGetDefaultToken, stripeGetQuotes, stripeGetSession, stripeGetTransactionLimits, stripeListPaymentTokens, stripeListWallets, stripeRefreshQuote, stripeRefreshToken, useUserIp, verifyOnrampVerificationOtp, verifyRecipientAddress };
+export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AddressVerification, type ApplePayLimitUpgradeStatus, type ApplePayProvider, type ApplePayProvidersResponse, type AuthenticateOAuthResult, type AutoSwapRequest, type AutoSwapResponse, type BankTransferConfig, type BankTransferProvider, type BankTransferProvidersResponse, type BlockedCountrySubdivision, type BuildHypercoreTransactionRequest, type BuildHypercoreTransactionResponse, type BuildSolanaTransactionRequest, type BuildSolanaTransactionResponse, type CashAppLimits, type CashAppSessionRequest, type CashAppSessionResponse, type CashAppSessionStatusResponse, type ChainType, type CheckoutEvent, CheckoutEventType, type CheckoutMethod, type CheckoutPaymentIntent, type CheckoutPaymentIntentData, type CheckoutPaymentIntentSucceededEvent, type CoinbaseApplePayLimit, type CoinbaseApplePayLimitUpgradeOption, type CoinbaseApplePayLimitsResponse, type CoinbaseApplePaySessionResponse, type CoinbaseLegalAgreement, type CoinbaseLegalAgreementsResponse, type ConfirmIntegrationTransferResult, type CreateCoinbaseApplePaySessionRequest, type CreateDepositAddressRequest, type CreateExchangeSessionRequest, type CreateExchangeSessionResponse, type CreateIntegrationTransferParams, type CreateIntegrationTransferResult, type CreateOnrampVerificationSessionRequest, DETECTION_ARM_DELAY_MS, DETECTION_POLL_INTERVAL_MS, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddress, type DepositAddressParams, type DepositAddressResponse, DepositAddressValidationError, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, DepositSession, type DepositSessionConfig, type DepositSessionDestination, type DepositSessionError, type DepositSessionErrorCode, type DepositSessionEvent, type DepositSessionEventMap, DepositSessionEventType, type DepositSessionParams, type DepositSessionSnapshot, type DepositSessionStatus, DepositSessionWaitError, type DepositSessionWaitErrorCode, type DepositSessionWaitOptions, type DestinationToken, type DestinationTokenChain, type DirectExecution, type DirectExecutionResponse, type DirectExecutionSucceededEvent, type EvmContractCall, type ExchangeProviderInfo, type ExchangeProvidersResponse, type ExchangeSessionStartParams, type ExchangeWalletAddress, ExecutionStatus, type ExternalWalletChainType, type ExternalWalletInfo, type ExternalWalletsResponse, type FeaturedToken, type FeaturedWallet, type FiatCurrenciesResponse, type FiatCurrency, type GetBankTransferProvidersOptions, type GetExchangesQuery, type HypercoreActivationRequest, type HypercoreActivationResponse, type I18nStrings, type IconUrl, IneligibilityReason, type IntegrationAccount, type IntegrationExchangeInfo, type IntegrationExchangesResponse, type IntegrationFeeAmount, type IntegrationHoldingsResponse, IntegrationProvider, type IpAddressResponse, LOOKBACK_MS, type ListExecutionsParams, type LockedQuoteLimits, type LockedQuotePreview, type LockedQuotePreviewRequest, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionCreatedData, type OnrampSessionCreatedEvent, type OnrampSessionPaymentMethod, type OnrampSessionPaymentMethodType, type OnrampSessionRequest, type OnrampSessionResponse, type OnrampVerificationFactor, type OnrampVerificationFactorStatus, type OnrampVerificationSession, type OnrampVerificationStatus, type OnrampVerificationTokenResponse, type PaymentIntent, type PaymentIntentDepositAddress, type PaymentIntentExecutionsResponse, type PaymentIntentStatus, type PaymentIntentType, type PaymentNetwork, type PollExecutionsRequest, type PollExecutionsResponse, type ProductType, type ProjectConfigResponse, type PublicIncidentResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, type RequestCoinbaseApplePayLimitUpgradeRequest, type RequestCoinbaseApplePayLimitUpgradeResponse, SCAN_NUDGE_INTERVAL_MS, SOLANA_USDC_ADDRESS, type SendHypercoreTransactionRequest, type SendHypercoreTransactionResponse, type SendSolanaTransactionRequest, type SendSolanaTransactionResponse, type SourceToken, type SourceTokenNetwork, type StartIntegrationOAuthResult, type StripeAccessTokenResponse, StripeApiResponseError, type StripeAuthIntentResponse, type StripeConfigResponse, type StripeConfirmRequest, type StripeConsumerWallet, type StripeCreateSessionRequest, type StripeCryptoCustomer, type StripeCustomerVerification, type StripeDefaultTokenResponse, type StripeListResponse, type StripeOnrampErrorType, type StripeOnrampSession, type StripeOnrampTransactionDetails, type StripePaymentToken, type StripeQuoteRequest, type StripeQuotesResponse, type StripeTransactionLimitEntry, type StripeTransactionLimitsResponse, type SupportedChain, type SupportedDepositTokensParams, type SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenDisplayMetadata, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, UnifoldClient, type UnifoldClientOptions, type UserIpInfo, type VerifyAddressParams, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, type WalletMobileDeepLinkDepositAddress, type WalletMobileDeepLinkResponse, type WalletMobileDeepLinkWallet, type WithdrawDirectExecutionSucceededEvent, type WithdrawEvent, WithdrawEventType, authenticateIntegrationOAuth, buildHypercoreTransaction, buildSolanaTransaction, checkHypercoreActivation, confirmIntegrationTransfer, createCashAppSession, createCoinbaseApplePaySession, createDepositAddress, createExchangeSession, createIntegrationTransfer, createOnrampSession, createOnrampVerificationSession, createUnifoldClient, exchangeOnrampVerificationToken, formatStablecoinAmount, generateKSUID, generatePrefixedKSUID, getAddressBalance, getAddressBalances, getApiBaseUrl, getApplePayLimitUpgradeStatus, getApplePayProviders, getBankTransferProviders, getCashAppLimits, getCashAppSessionStatus, getChainName, getCoinbaseApplePayLimits, getCoinbaseLegalAgreements, getDefaultOnrampToken, getDepositAddress, getDepositQuote, getExchangeSessionStartUrl, getExchanges, getExternalWallets, getFiatCurrencies, getFiatExchangeRates, getIconUrl, getIconUrlWithCdn, getIntegrationExchanges, getIntegrationHoldings, getIntegrationTransferDefaultToken, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getOnrampVerificationSession, getPreferredIconUrl, getProjectConfig, getPublicIncident, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, isApplePayLimitReached, isDepositAddressValidationError, listPaymentIntentExecutions, mapDirectExecution, mapWalletToDepositAddress, pollDirectExecutions, queryExecutions, refreshIntegrationToken, requestCoinbaseApplePayLimitUpgrade, retrievePaymentIntent, revokeIntegrationToken, sendHypercoreTransaction, sendOnrampVerificationOtp, sendSolanaTransaction, setApiConfig, startIntegrationOAuth, stripeConfirmSession, stripeCreateAuthIntent, stripeCreateSession, stripeExchangeTokens, stripeGetConfig, stripeGetCustomer, stripeGetDefaultToken, stripeGetQuotes, stripeGetSession, stripeGetTransactionLimits, stripeListPaymentTokens, stripeListWallets, stripeRefreshQuote, stripeRefreshToken, useUserIp, verifyOnrampVerificationOtp, verifyRecipientAddress };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type ChainType = 'ethereum' | 'solana' | 'bitcoin' | 'algorand' | 'xrpl' | 'cardano' | 'n1';
+type ChainType = 'ethereum' | 'solana' | 'bitcoin' | 'algorand' | 'xrpl' | 'cardano' | 'n1' | 'tron';
 
 declare function setApiConfig(config: {
     baseUrl?: string;
@@ -337,7 +337,13 @@ interface OnrampQuote {
     destination_currency: string;
     destination_network: string;
     exchange_rate: number;
-    payment_method_type: string;
+    /**
+     * Unified payment method type (`card` / `apple_pay` / `sepa`). Provider-native
+     * values (e.g. Meld's `credit_debit_card`) are normalized to this vocabulary.
+     */
+    payment_method_type: OnrampSessionPaymentMethodType;
+    /** @deprecated Use `payment_method_type` instead (same value). */
+    payment_method: OnrampSessionPaymentMethodType;
     customer_score: number;
     service_provider: string;
     service_provider_display_name: string;
@@ -371,7 +377,12 @@ declare function getOnrampQuotes(request: OnrampQuotesRequest, publishableKey?:
  * (Coinbase only) — useful as a fallback when the headless Apple Pay flow
  * is unavailable.
  */
-type OnrampSessionPaymentMethod = 'card' | 'sepa' | 'apple_pay';
+type OnrampSessionPaymentMethodType = 'card' | 'sepa' | 'apple_pay';
+/**
+ * @deprecated Use `OnrampSessionPaymentMethodType` instead. Retained as an alias so
+ * previously-released SDK consumers keep compiling.
+ */
+type OnrampSessionPaymentMethod = OnrampSessionPaymentMethodType;
 interface OnrampSessionRequest {
     service_provider: string;
     country_code: string;
@@ -384,7 +395,13 @@ interface OnrampSessionRequest {
     redirect_url?: string;
     external_id?: string;
     email?: string;
-    payment_method?: OnrampSessionPaymentMethod;
+    /**
+     * Payment method type for the session (`card` / `sepa` / `apple_pay`).
+     * Defaults to `card`.
+     */
+    payment_method_type?: OnrampSessionPaymentMethodType;
+    /** @deprecated Use `payment_method_type` instead (same value). */
+    payment_method?: OnrampSessionPaymentMethodType;
 }
 interface OnrampSessionResponse {
     url: string;
@@ -418,7 +435,7 @@ interface BankTransferProvider {
      * a single provider can light up multiple rails (e.g. SEPA + ACH) without
      * forking the row.
      */
-    payment_methods: OnrampSessionPaymentMethod[];
+    payment_methods: OnrampSessionPaymentMethodType[];
     /** All fiat currencies the rail accepts (e.g. ['eur', 'gbp']). */
     supported_currencies: string[];
     /**
@@ -1587,18 +1604,32 @@ interface StripeQuotesResponse {
  * Backend error_type values for headless Stripe onramp failures. The SDK can
  * branch on these instead of string-matching Stripe messages.
  */
-type StripeOnrampErrorType = 'stripe_onramp_missing_minimum_identity_verification' | 'stripe_onramp_missing_identity_verification' | 'stripe_onramp_missing_document_verification' | 'stripe_onramp_purchase_limit_reached' | 'stripe_onramp_bad_request' | 'stripe_onramp_forbidden' | 'stripe_onramp_not_found' | 'stripe_onramp_upstream_error' | (string & NonNullable<unknown>);
+type StripeOnrampErrorType = 'stripe_onramp_missing_minimum_identity_verification' | 'stripe_onramp_missing_identity_verification' | 'stripe_onramp_missing_document_verification' | 'stripe_onramp_purchase_limit_reached' | 'stripe_onramp_payment_method_consumed' | 'stripe_onramp_bad_request' | 'stripe_onramp_forbidden' | 'stripe_onramp_not_found' | 'stripe_onramp_upstream_error' | (string & NonNullable<unknown>);
 declare class StripeApiResponseError extends Error {
     readonly statusCode: number;
     /** Underlying Stripe error code (e.g. `crypto_onramp_session_error`), when available */
     readonly stripeCode?: string | undefined;
     /** Unifold backend error_type (e.g. `stripe_onramp_missing_document_verification`) */
     readonly errorType?: StripeOnrampErrorType | undefined;
+    /**
+     * The raw Stripe error message (from `details.stripe_error.message`), without
+     * the operation prefix baked into `message`. This is the human-readable text
+     * Stripe returns (e.g. "Your card was declined.") and is safe to show to the
+     * user directly when there's no more specific mapped message.
+     */
+    readonly stripeMessage?: string | undefined;
     constructor(message: string, statusCode: number, 
     /** Underlying Stripe error code (e.g. `crypto_onramp_session_error`), when available */
     stripeCode?: string | undefined, 
     /** Unifold backend error_type (e.g. `stripe_onramp_missing_document_verification`) */
-    errorType?: StripeOnrampErrorType | undefined);
+    errorType?: StripeOnrampErrorType | undefined, 
+    /**
+     * The raw Stripe error message (from `details.stripe_error.message`), without
+     * the operation prefix baked into `message`. This is the human-readable text
+     * Stripe returns (e.g. "Your card was declined.") and is safe to show to the
+     * user directly when there's no more specific mapped message.
+     */
+    stripeMessage?: string | undefined);
 }
 /**
  * Fetch Stripe config (publishable key + merchant ID) for SDK initialization.
@@ -2277,7 +2308,16 @@ interface DepositSessionParams {
 interface DepositSessionConfig extends DepositSessionParams {
     publishableKey: string;
 }
-type DepositSessionStatus = 'idle' | 'creating_addresses' | 'awaiting_funds' | 'processing' | 'succeeded' | 'failed' | 'error';
+/**
+ * Session status is LIFECYCLE-ONLY. A DepositSession is an ongoing watcher
+ * that can observe many executions, so execution outcomes deliberately never
+ * appear here — a session-level "succeeded"/"failed" misleads the moment a
+ * second deposit arrives (a failure right after a success would flip the
+ * whole session to "failed"). Outcomes live on the executions themselves:
+ * `snapshot.executions` / `latestExecution` statuses, the
+ * `direct_execution.succeeded`/`.failed` events, and `waitForSuccess()`.
+ */
+type DepositSessionStatus = 'idle' | 'creating_addresses' | 'ready' | 'processing' | 'error';
 interface DepositSessionSnapshot {
     status: DepositSessionStatus;
     /** Deposit addresses (one per chain type); empty until created. */
@@ -2350,6 +2390,9 @@ declare class DepositSession {
     private baselineMs;
     private tracked;
     private pollErrorLatched;
+    private pollInFlight;
+    /** First execution to succeed this run — waitForSuccess's one-shot answer. */
+    private firstSuccess;
     private detectionTimer;
     private nudgeTimer;
     private armTimer;
@@ -2388,9 +2431,11 @@ declare class DepositSession {
     destroy(): void;
     /**
      * Resolve when the session reaches one of the given statuses (immediately
-     * if it's already there). Generic primitive over the status state machine:
-     * `waitForStatus('processing')` awaits detection; `waitForStatus(['succeeded',
-     * 'failed'])` awaits a terminal outcome.
+     * if it's already there). Generic primitive over the lifecycle state
+     * machine — e.g. `waitForStatus('processing')` awaits detection of live
+     * activity, `waitForStatus('ready')` awaits readiness. Statuses
+     * carry no outcomes; await those with {@link waitForSuccess} or the
+     * `direct_execution.*` events.
      *
      * Rejects with {@link DepositSessionWaitError} on abort or destroy().
      * Does not start or stop the session — it only listens.
@@ -2404,14 +2449,15 @@ declare class DepositSession {
      * Multi-execution semantics (unlike quote-scoped models such as Privy's,
      * one session can observe many executions — a user may send twice, or on
      * two chains): this waiter is one-shot "first completion" detection. If an
-     * execution has already succeeded, it resolves immediately with that
-     * execution. The session keeps polling after success — to react to every
-     * settlement, subscribe to `direct_execution.succeeded` events or read
-     * `snapshot.executions` instead.
+     * execution has already succeeded this run, it resolves immediately with
+     * the FIRST one that did (not the newest). The session keeps polling after
+     * success — to react to every settlement, subscribe to
+     * `direct_execution.succeeded` events or read `snapshot.executions`.
      *
      * Rejects with {@link DepositSessionWaitError}:
-     * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails
-     *   before any succeeds,
+     * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails and
+     *   NO other observed execution is still in flight — a failure while
+     *   another deposit is pending keeps waiting (that one may still succeed),
      * - `SESSION_ERROR` (cause: the fatal {@link DepositSessionError}) on fatal
      *   session errors (e.g. address creation failed),
      * - `ABORTED` / `DESTROYED` per the wait options and session lifecycle.
@@ -2438,8 +2484,10 @@ declare class DepositSession {
     private runStartChecks;
     private startDetectionLoop;
     private pollExecutions;
+    private pollExecutionsOnce;
     private processExecutionChange;
     private armConfirmation;
+    private anyExecutionInFlight;
     private setStatus;
     private clearTimers;
     private buildSnapshot;
@@ -2646,4 +2694,4 @@ declare const i18n: {
 };
 type I18nStrings = typeof i18n;
 
-export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AddressVerification, type ApplePayLimitUpgradeStatus, type ApplePayProvider, type ApplePayProvidersResponse, type AuthenticateOAuthResult, type AutoSwapRequest, type AutoSwapResponse, type BankTransferConfig, type BankTransferProvider, type BankTransferProvidersResponse, type BlockedCountrySubdivision, type BuildHypercoreTransactionRequest, type BuildHypercoreTransactionResponse, type BuildSolanaTransactionRequest, type BuildSolanaTransactionResponse, type CashAppLimits, type CashAppSessionRequest, type CashAppSessionResponse, type CashAppSessionStatusResponse, type ChainType, type CheckoutEvent, CheckoutEventType, type CheckoutMethod, type CheckoutPaymentIntent, type CheckoutPaymentIntentData, type CheckoutPaymentIntentSucceededEvent, type CoinbaseApplePayLimit, type CoinbaseApplePayLimitUpgradeOption, type CoinbaseApplePayLimitsResponse, type CoinbaseApplePaySessionResponse, type CoinbaseLegalAgreement, type CoinbaseLegalAgreementsResponse, type ConfirmIntegrationTransferResult, type CreateCoinbaseApplePaySessionRequest, type CreateDepositAddressRequest, type CreateExchangeSessionRequest, type CreateExchangeSessionResponse, type CreateIntegrationTransferParams, type CreateIntegrationTransferResult, type CreateOnrampVerificationSessionRequest, DETECTION_ARM_DELAY_MS, DETECTION_POLL_INTERVAL_MS, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddress, type DepositAddressParams, type DepositAddressResponse, DepositAddressValidationError, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, DepositSession, type DepositSessionConfig, type DepositSessionDestination, type DepositSessionError, type DepositSessionErrorCode, type DepositSessionEvent, type DepositSessionEventMap, DepositSessionEventType, type DepositSessionParams, type DepositSessionSnapshot, type DepositSessionStatus, DepositSessionWaitError, type DepositSessionWaitErrorCode, type DepositSessionWaitOptions, type DestinationToken, type DestinationTokenChain, type DirectExecution, type DirectExecutionResponse, type DirectExecutionSucceededEvent, type EvmContractCall, type ExchangeProviderInfo, type ExchangeProvidersResponse, type ExchangeSessionStartParams, type ExchangeWalletAddress, ExecutionStatus, type ExternalWalletChainType, type ExternalWalletInfo, type ExternalWalletsResponse, type FeaturedToken, type FeaturedWallet, type FiatCurrenciesResponse, type FiatCurrency, type GetBankTransferProvidersOptions, type GetExchangesQuery, type HypercoreActivationRequest, type HypercoreActivationResponse, type I18nStrings, type IconUrl, IneligibilityReason, type IntegrationAccount, type IntegrationExchangeInfo, type IntegrationExchangesResponse, type IntegrationFeeAmount, type IntegrationHoldingsResponse, IntegrationProvider, type IpAddressResponse, LOOKBACK_MS, type ListExecutionsParams, type LockedQuoteLimits, type LockedQuotePreview, type LockedQuotePreviewRequest, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionCreatedData, type OnrampSessionCreatedEvent, type OnrampSessionPaymentMethod, type OnrampSessionRequest, type OnrampSessionResponse, type OnrampVerificationFactor, type OnrampVerificationFactorStatus, type OnrampVerificationSession, type OnrampVerificationStatus, type OnrampVerificationTokenResponse, type PaymentIntent, type PaymentIntentDepositAddress, type PaymentIntentExecutionsResponse, type PaymentIntentStatus, type PaymentIntentType, type PaymentNetwork, type PollExecutionsRequest, type PollExecutionsResponse, type ProductType, type ProjectConfigResponse, type PublicIncidentResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, type RequestCoinbaseApplePayLimitUpgradeRequest, type RequestCoinbaseApplePayLimitUpgradeResponse, SCAN_NUDGE_INTERVAL_MS, SOLANA_USDC_ADDRESS, type SendHypercoreTransactionRequest, type SendHypercoreTransactionResponse, type SendSolanaTransactionRequest, type SendSolanaTransactionResponse, type SourceToken, type SourceTokenNetwork, type StartIntegrationOAuthResult, type StripeAccessTokenResponse, StripeApiResponseError, type StripeAuthIntentResponse, type StripeConfigResponse, type StripeConfirmRequest, type StripeConsumerWallet, type StripeCreateSessionRequest, type StripeCryptoCustomer, type StripeCustomerVerification, type StripeDefaultTokenResponse, type StripeListResponse, type StripeOnrampErrorType, type StripeOnrampSession, type StripeOnrampTransactionDetails, type StripePaymentToken, type StripeQuoteRequest, type StripeQuotesResponse, type StripeTransactionLimitEntry, type StripeTransactionLimitsResponse, type SupportedChain, type SupportedDepositTokensParams, type SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenDisplayMetadata, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, UnifoldClient, type UnifoldClientOptions, type UserIpInfo, type VerifyAddressParams, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, type WalletMobileDeepLinkDepositAddress, type WalletMobileDeepLinkResponse, type WalletMobileDeepLinkWallet, type WithdrawDirectExecutionSucceededEvent, type WithdrawEvent, WithdrawEventType, authenticateIntegrationOAuth, buildHypercoreTransaction, buildSolanaTransaction, checkHypercoreActivation, confirmIntegrationTransfer, createCashAppSession, createCoinbaseApplePaySession, createDepositAddress, createExchangeSession, createIntegrationTransfer, createOnrampSession, createOnrampVerificationSession, createUnifoldClient, exchangeOnrampVerificationToken, formatStablecoinAmount, generateKSUID, generatePrefixedKSUID, getAddressBalance, getAddressBalances, getApiBaseUrl, getApplePayLimitUpgradeStatus, getApplePayProviders, getBankTransferProviders, getCashAppLimits, getCashAppSessionStatus, getChainName, getCoinbaseApplePayLimits, getCoinbaseLegalAgreements, getDefaultOnrampToken, getDepositAddress, getDepositQuote, getExchangeSessionStartUrl, getExchanges, getExternalWallets, getFiatCurrencies, getFiatExchangeRates, getIconUrl, getIconUrlWithCdn, getIntegrationExchanges, getIntegrationHoldings, getIntegrationTransferDefaultToken, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getOnrampVerificationSession, getPreferredIconUrl, getProjectConfig, getPublicIncident, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, isApplePayLimitReached, isDepositAddressValidationError, listPaymentIntentExecutions, mapDirectExecution, mapWalletToDepositAddress, pollDirectExecutions, queryExecutions, refreshIntegrationToken, requestCoinbaseApplePayLimitUpgrade, retrievePaymentIntent, revokeIntegrationToken, sendHypercoreTransaction, sendOnrampVerificationOtp, sendSolanaTransaction, setApiConfig, startIntegrationOAuth, stripeConfirmSession, stripeCreateAuthIntent, stripeCreateSession, stripeExchangeTokens, stripeGetConfig, stripeGetCustomer, stripeGetDefaultToken, stripeGetQuotes, stripeGetSession, stripeGetTransactionLimits, stripeListPaymentTokens, stripeListWallets, stripeRefreshQuote, stripeRefreshToken, useUserIp, verifyOnrampVerificationOtp, verifyRecipientAddress };
+export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AddressVerification, type ApplePayLimitUpgradeStatus, type ApplePayProvider, type ApplePayProvidersResponse, type AuthenticateOAuthResult, type AutoSwapRequest, type AutoSwapResponse, type BankTransferConfig, type BankTransferProvider, type BankTransferProvidersResponse, type BlockedCountrySubdivision, type BuildHypercoreTransactionRequest, type BuildHypercoreTransactionResponse, type BuildSolanaTransactionRequest, type BuildSolanaTransactionResponse, type CashAppLimits, type CashAppSessionRequest, type CashAppSessionResponse, type CashAppSessionStatusResponse, type ChainType, type CheckoutEvent, CheckoutEventType, type CheckoutMethod, type CheckoutPaymentIntent, type CheckoutPaymentIntentData, type CheckoutPaymentIntentSucceededEvent, type CoinbaseApplePayLimit, type CoinbaseApplePayLimitUpgradeOption, type CoinbaseApplePayLimitsResponse, type CoinbaseApplePaySessionResponse, type CoinbaseLegalAgreement, type CoinbaseLegalAgreementsResponse, type ConfirmIntegrationTransferResult, type CreateCoinbaseApplePaySessionRequest, type CreateDepositAddressRequest, type CreateExchangeSessionRequest, type CreateExchangeSessionResponse, type CreateIntegrationTransferParams, type CreateIntegrationTransferResult, type CreateOnrampVerificationSessionRequest, DETECTION_ARM_DELAY_MS, DETECTION_POLL_INTERVAL_MS, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddress, type DepositAddressParams, type DepositAddressResponse, DepositAddressValidationError, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, DepositSession, type DepositSessionConfig, type DepositSessionDestination, type DepositSessionError, type DepositSessionErrorCode, type DepositSessionEvent, type DepositSessionEventMap, DepositSessionEventType, type DepositSessionParams, type DepositSessionSnapshot, type DepositSessionStatus, DepositSessionWaitError, type DepositSessionWaitErrorCode, type DepositSessionWaitOptions, type DestinationToken, type DestinationTokenChain, type DirectExecution, type DirectExecutionResponse, type DirectExecutionSucceededEvent, type EvmContractCall, type ExchangeProviderInfo, type ExchangeProvidersResponse, type ExchangeSessionStartParams, type ExchangeWalletAddress, ExecutionStatus, type ExternalWalletChainType, type ExternalWalletInfo, type ExternalWalletsResponse, type FeaturedToken, type FeaturedWallet, type FiatCurrenciesResponse, type FiatCurrency, type GetBankTransferProvidersOptions, type GetExchangesQuery, type HypercoreActivationRequest, type HypercoreActivationResponse, type I18nStrings, type IconUrl, IneligibilityReason, type IntegrationAccount, type IntegrationExchangeInfo, type IntegrationExchangesResponse, type IntegrationFeeAmount, type IntegrationHoldingsResponse, IntegrationProvider, type IpAddressResponse, LOOKBACK_MS, type ListExecutionsParams, type LockedQuoteLimits, type LockedQuotePreview, type LockedQuotePreviewRequest, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionCreatedData, type OnrampSessionCreatedEvent, type OnrampSessionPaymentMethod, type OnrampSessionPaymentMethodType, type OnrampSessionRequest, type OnrampSessionResponse, type OnrampVerificationFactor, type OnrampVerificationFactorStatus, type OnrampVerificationSession, type OnrampVerificationStatus, type OnrampVerificationTokenResponse, type PaymentIntent, type PaymentIntentDepositAddress, type PaymentIntentExecutionsResponse, type PaymentIntentStatus, type PaymentIntentType, type PaymentNetwork, type PollExecutionsRequest, type PollExecutionsResponse, type ProductType, type ProjectConfigResponse, type PublicIncidentResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, type RequestCoinbaseApplePayLimitUpgradeRequest, type RequestCoinbaseApplePayLimitUpgradeResponse, SCAN_NUDGE_INTERVAL_MS, SOLANA_USDC_ADDRESS, type SendHypercoreTransactionRequest, type SendHypercoreTransactionResponse, type SendSolanaTransactionRequest, type SendSolanaTransactionResponse, type SourceToken, type SourceTokenNetwork, type StartIntegrationOAuthResult, type StripeAccessTokenResponse, StripeApiResponseError, type StripeAuthIntentResponse, type StripeConfigResponse, type StripeConfirmRequest, type StripeConsumerWallet, type StripeCreateSessionRequest, type StripeCryptoCustomer, type StripeCustomerVerification, type StripeDefaultTokenResponse, type StripeListResponse, type StripeOnrampErrorType, type StripeOnrampSession, type StripeOnrampTransactionDetails, type StripePaymentToken, type StripeQuoteRequest, type StripeQuotesResponse, type StripeTransactionLimitEntry, type StripeTransactionLimitsResponse, type SupportedChain, type SupportedDepositTokensParams, type SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenDisplayMetadata, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, UnifoldClient, type UnifoldClientOptions, type UserIpInfo, type VerifyAddressParams, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, type WalletMobileDeepLinkDepositAddress, type WalletMobileDeepLinkResponse, type WalletMobileDeepLinkWallet, type WithdrawDirectExecutionSucceededEvent, type WithdrawEvent, WithdrawEventType, authenticateIntegrationOAuth, buildHypercoreTransaction, buildSolanaTransaction, checkHypercoreActivation, confirmIntegrationTransfer, createCashAppSession, createCoinbaseApplePaySession, createDepositAddress, createExchangeSession, createIntegrationTransfer, createOnrampSession, createOnrampVerificationSession, createUnifoldClient, exchangeOnrampVerificationToken, formatStablecoinAmount, generateKSUID, generatePrefixedKSUID, getAddressBalance, getAddressBalances, getApiBaseUrl, getApplePayLimitUpgradeStatus, getApplePayProviders, getBankTransferProviders, getCashAppLimits, getCashAppSessionStatus, getChainName, getCoinbaseApplePayLimits, getCoinbaseLegalAgreements, getDefaultOnrampToken, getDepositAddress, getDepositQuote, getExchangeSessionStartUrl, getExchanges, getExternalWallets, getFiatCurrencies, getFiatExchangeRates, getIconUrl, getIconUrlWithCdn, getIntegrationExchanges, getIntegrationHoldings, getIntegrationTransferDefaultToken, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getOnrampVerificationSession, getPreferredIconUrl, getProjectConfig, getPublicIncident, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, isApplePayLimitReached, isDepositAddressValidationError, listPaymentIntentExecutions, mapDirectExecution, mapWalletToDepositAddress, pollDirectExecutions, queryExecutions, refreshIntegrationToken, requestCoinbaseApplePayLimitUpgrade, retrievePaymentIntent, revokeIntegrationToken, sendHypercoreTransaction, sendOnrampVerificationOtp, sendSolanaTransaction, setApiConfig, startIntegrationOAuth, stripeConfirmSession, stripeCreateAuthIntent, stripeCreateSession, stripeExchangeTokens, stripeGetConfig, stripeGetCustomer, stripeGetDefaultToken, stripeGetQuotes, stripeGetSession, stripeGetTransactionLimits, stripeListPaymentTokens, stripeListWallets, stripeRefreshQuote, stripeRefreshToken, useUserIp, verifyOnrampVerificationOtp, verifyRecipientAddress };

package/dist/index.js

@@ -550,6 +550,9 @@ function getOnrampSessionStartUrl(request, publishableKey) {
   if (request.email) {
     params.append("email", request.email);
   }
+  if (request.payment_method_type) {
+    params.append("payment_method_type", request.payment_method_type);
+  }
   if (request.payment_method) {
     params.append("payment_method", request.payment_method);
   }
@@ -1207,11 +1210,12 @@ async function stripeGetDefaultToken(params, publishableKey) {
 }
 var HEADLESS_STRIPE_BASE = "/v1/public/onramps/headless/stripe";
 var StripeApiResponseError = class extends Error {
-  constructor(message, statusCode, stripeCode, errorType) {
+  constructor(message, statusCode, stripeCode, errorType, stripeMessage) {
     super(message);
     this.statusCode = statusCode;
     this.stripeCode = stripeCode;
     this.errorType = errorType;
+    this.stripeMessage = stripeMessage;
     this.name = "StripeApiResponseError";
   }
 };
@@ -1222,7 +1226,8 @@ function throwStripeError(prefix, response, error) {
     `${prefix}: ${detailMessage}`,
     response.status,
     stripeError?.code,
-    error.error_type
+    error.error_type,
+    stripeError?.message
   );
 }
 async function stripeGetConfig(publishableKey) {
@@ -1858,6 +1863,9 @@ var DepositSession = class {
     __publicField(this, "baselineMs", 0);
     __publicField(this, "tracked", /* @__PURE__ */ new Map());
     __publicField(this, "pollErrorLatched", false);
+    __publicField(this, "pollInFlight", false);
+    /** First execution to succeed this run — waitForSuccess's one-shot answer. */
+    __publicField(this, "firstSuccess", null);
     __publicField(this, "detectionTimer", null);
     __publicField(this, "nudgeTimer", null);
     __publicField(this, "armTimer", null);
@@ -1928,8 +1936,9 @@ var DepositSession = class {
     this.runToken += 1;
     this.clearTimers();
     this.startPromise = null;
-    if (this.checkingDeposit) {
-      this.checkingDeposit = false;
+    this.checkingDeposit = false;
+    if (this.status !== "idle" && this.status !== "error") {
+      this.setStatus("idle");
     }
     if (wasActive && !this.destroyed) {
       this.commit();
@@ -1951,9 +1960,11 @@ var DepositSession = class {
   // -- Promise waiters (subscription sugar over the event stream) ------------
   /**
    * Resolve when the session reaches one of the given statuses (immediately
-   * if it's already there). Generic primitive over the status state machine:
-   * `waitForStatus('processing')` awaits detection; `waitForStatus(['succeeded',
-   * 'failed'])` awaits a terminal outcome.
+   * if it's already there). Generic primitive over the lifecycle state
+   * machine — e.g. `waitForStatus('processing')` awaits detection of live
+   * activity, `waitForStatus('ready')` awaits readiness. Statuses
+   * carry no outcomes; await those with {@link waitForSuccess} or the
+   * `direct_execution.*` events.
    *
    * Rejects with {@link DepositSessionWaitError} on abort or destroy().
    * Does not start or stop the session — it only listens.
@@ -1982,14 +1993,15 @@ var DepositSession = class {
    * Multi-execution semantics (unlike quote-scoped models such as Privy's,
    * one session can observe many executions — a user may send twice, or on
    * two chains): this waiter is one-shot "first completion" detection. If an
-   * execution has already succeeded, it resolves immediately with that
-   * execution. The session keeps polling after success — to react to every
-   * settlement, subscribe to `direct_execution.succeeded` events or read
-   * `snapshot.executions` instead.
+   * execution has already succeeded this run, it resolves immediately with
+   * the FIRST one that did (not the newest). The session keeps polling after
+   * success — to react to every settlement, subscribe to
+   * `direct_execution.succeeded` events or read `snapshot.executions`.
    *
    * Rejects with {@link DepositSessionWaitError}:
-   * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails
-   *   before any succeeds,
+   * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails and
+   *   NO other observed execution is still in flight — a failure while
+   *   another deposit is pending keeps waiting (that one may still succeed),
    * - `SESSION_ERROR` (cause: the fatal {@link DepositSessionError}) on fatal
    *   session errors (e.g. address creation failed),
    * - `ABORTED` / `DESTROYED` per the wait options and session lifecycle.
@@ -2000,29 +2012,28 @@ var DepositSession = class {
         options,
         reject,
         subscribe: (settle) => {
-          const { executions, error } = this.snapshot;
-          const alreadySucceeded = executions.find(
-            (execution) => execution.status === "succeeded" /* SUCCEEDED */
+          const rejectFailure = (failed) => settle(
+            () => reject(new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", failed))
           );
-          if (alreadySucceeded) {
-            settle(() => resolve(alreadySucceeded));
+          const { executions, error } = this.snapshot;
+          if (this.firstSuccess) {
+            const first = this.firstSuccess;
+            settle(() => resolve(first));
             return () => {
             };
           }
           const alreadyFailed = executions.find(
             (execution) => FAILURE_STATUSES.includes(execution.status)
           );
-          if (alreadyFailed) {
-            settle(
-              () => reject(
-                new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", alreadyFailed)
-              )
-            );
+          if (alreadyFailed && !this.anyExecutionInFlight()) {
+            rejectFailure(alreadyFailed);
             return () => {
             };
           }
           if (error?.fatal) {
-            settle(() => reject(new DepositSessionWaitError("SESSION_ERROR", error.message, error)));
+            settle(
+              () => reject(new DepositSessionWaitError("SESSION_ERROR", error.message, error))
+            );
             return () => {
             };
           }
@@ -2031,14 +2042,20 @@ var DepositSession = class {
               "direct_execution.succeeded" /* EXECUTION_SUCCEEDED */,
               (event) => settle(() => resolve(event.data.object))
             ),
-            this.on(
-              "direct_execution.failed" /* EXECUTION_FAILED */,
-              (event) => settle(
-                () => reject(
-                  new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", event.data.object)
-                )
-              )
-            ),
+            this.on("direct_execution.failed" /* EXECUTION_FAILED */, (event) => {
+              if (this.anyExecutionInFlight()) return;
+              rejectFailure(event.data.object);
+            }),
+            // A previously-failed wait condition can become settleable when
+            // the last in-flight execution also fails (updated → failed is
+            // covered above; updated → refunded transitions re-check here).
+            this.on("direct_execution.updated" /* EXECUTION_UPDATED */, () => {
+              if (this.anyExecutionInFlight() || this.firstSuccess) return;
+              const failed = this.snapshot.executions.find(
+                (execution) => FAILURE_STATUSES.includes(execution.status)
+              );
+              if (failed) rejectFailure(failed);
+            }),
             this.on("deposit_session.errored" /* SESSION_ERRORED */, (event) => {
               if (!event.data.object.fatal) return;
               settle(
@@ -2092,7 +2109,9 @@ var DepositSession = class {
       () => reject(new DepositSessionWaitError("ABORTED", "Wait aborted", options.signal?.reason))
     );
     const onDestroy = () => settle(
-      () => reject(new DepositSessionWaitError("DESTROYED", "DepositSession was destroyed while waiting"))
+      () => reject(
+        new DepositSessionWaitError("DESTROYED", "DepositSession was destroyed while waiting")
+      )
     );
     this.waiterDestroyCallbacks.add(onDestroy);
     options.signal?.addEventListener("abort", onAbort, { once: true });
@@ -2106,19 +2125,20 @@ var DepositSession = class {
     this.tracked.clear();
     this.pollErrorLatched = false;
     this.executions = [];
+    this.firstSuccess = null;
     this.error = null;
     this.checkingDeposit = false;
+    this.addresses = [];
+    this.addressIds = [];
     this.setStatus("creating_addresses");
+    this.commit();
     this.emitSessionEvent("deposit_session.started" /* SESSION_STARTED */, {
       sessionId: this.id
     });
     this.notify();
     let wallets;
     try {
-      [wallets] = await Promise.all([
-        this.createAddressesWithRetry(token),
-        this.runStartChecks()
-      ]);
+      [wallets] = await Promise.all([this.createAddressesWithRetry(token), this.runStartChecks()]);
     } catch (cause) {
       if (token !== this.runToken) return;
       const isCheck = cause instanceof SessionCheckError;
@@ -2132,13 +2152,14 @@ var DepositSession = class {
     if (token !== this.runToken) return;
     this.addresses = wallets.map(mapWalletToDepositAddress);
     this.addressIds = wallets.map((w) => w.id).filter(Boolean);
-    this.setStatus("awaiting_funds");
+    this.setStatus("ready");
     this.commit();
     this.emitSessionEvent("deposit_session.addresses_created" /* ADDRESSES_CREATED */, {
       sessionId: this.id,
       addresses: this.addresses
     });
     this.notify();
+    if (token !== this.runToken) return;
     this.startDetectionLoop(token);
     if (this.confirmationMode === "auto") {
       this.armTimer = setTimeout(() => {
@@ -2214,11 +2235,29 @@ var DepositSession = class {
   }
   // -- Detection polling (port of useDepositPolling Effect 2) ----------------
   startDetectionLoop(token) {
-    const poll = () => void this.pollExecutions(token);
+    const poll = () => {
+      if (token !== this.runToken) {
+        if (this.detectionTimer) {
+          clearInterval(this.detectionTimer);
+          this.detectionTimer = null;
+        }
+        return;
+      }
+      void this.pollExecutions(token);
+    };
     poll();
     this.detectionTimer = setInterval(poll, DETECTION_POLL_INTERVAL_MS);
   }
   async pollExecutions(token) {
+    if (this.pollInFlight) return;
+    this.pollInFlight = true;
+    try {
+      await this.pollExecutionsOnce(token);
+    } finally {
+      this.pollInFlight = false;
+    }
+  }
+  async pollExecutionsOnce(token) {
     try {
       const response = await queryExecutions(
         this.externalUserId,
@@ -2284,9 +2323,7 @@ var DepositSession = class {
     const execution = mapDirectExecution(wire);
     const existingIndex = this.executions.findIndex((e) => e.id === execution.id);
     if (existingIndex >= 0) {
-      this.executions = this.executions.map(
-        (e, i) => i === existingIndex ? execution : e
-      );
+      this.executions = this.executions.map((e, i) => i === existingIndex ? execution : e);
     } else {
       this.executions = [...this.executions, execution].sort((a, b) => {
         const timeA = a.createdAt ? new Date(a.createdAt).getTime() : 0;
@@ -2294,21 +2331,15 @@ var DepositSession = class {
         return timeB - timeA;
       });
     }
-    if (wire.status === "succeeded" /* SUCCEEDED */) {
-      this.setStatus("succeeded");
-    } else if (FAILURE_STATUSES.includes(wire.status)) {
-      this.setStatus("failed");
-    } else if (IN_PROGRESS_STATUSES.includes(wire.status)) {
-      this.setStatus("processing");
+    this.setStatus(this.anyExecutionInFlight() ? "processing" : "ready");
+    const wasInProgressOrNew = previousStatus === null || IN_PROGRESS_STATUSES.includes(previousStatus);
+    if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew && !this.firstSuccess) {
+      this.firstSuccess = execution;
     }
     this.commit();
     const eventCreated = this.executionEventTimestamp(wire);
     if (previousStatus === null) {
-      this.emitExecutionEvent(
-        "direct_execution.detected" /* EXECUTION_DETECTED */,
-        execution,
-        eventCreated
-      );
+      this.emitExecutionEvent("direct_execution.detected" /* EXECUTION_DETECTED */, execution, eventCreated);
     } else {
       this.emitExecutionEvent(
         "direct_execution.updated" /* EXECUTION_UPDATED */,
@@ -2316,25 +2347,17 @@ var DepositSession = class {
         eventCreated
       );
     }
-    const wasInProgressOrNew = previousStatus === null || IN_PROGRESS_STATUSES.includes(previousStatus);
     if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew) {
-      this.emitExecutionEvent(
-        "direct_execution.succeeded" /* EXECUTION_SUCCEEDED */,
-        execution,
-        eventCreated
-      );
+      this.emitExecutionEvent("direct_execution.succeeded" /* EXECUTION_SUCCEEDED */, execution, eventCreated);
     } else if (FAILURE_STATUSES.includes(wire.status) && (previousStatus === null || !FAILURE_STATUSES.includes(previousStatus))) {
-      this.emitExecutionEvent(
-        "direct_execution.failed" /* EXECUTION_FAILED */,
-        execution,
-        eventCreated
-      );
+      this.emitExecutionEvent("direct_execution.failed" /* EXECUTION_FAILED */, execution, eventCreated);
     }
     this.notify();
   }
   // -- Scan nudge (port of useDepositPolling Effects 1 + 3) ------------------
   armConfirmation(trigger) {
     if (this.checkingDeposit || this.destroyed) return;
+    if (this.addressIds.length === 0) return;
     if (this.armTimer) {
       clearTimeout(this.armTimer);
       this.armTimer = null;
@@ -2351,10 +2374,8 @@ var DepositSession = class {
       if (token !== this.runToken) return;
       void Promise.all(
         this.addressIds.map(
-          (id) => pollDirectExecutions({ deposit_wallet_id: id }, this.publishableKey).catch(
-            () => {
-            }
-          )
+          (id) => pollDirectExecutions({ deposit_wallet_id: id }, this.publishableKey).catch(() => {
+          })
         )
       );
     };
@@ -2362,6 +2383,11 @@ var DepositSession = class {
     this.nudgeTimer = setInterval(nudge, SCAN_NUDGE_INTERVAL_MS);
   }
   // -- Internals --------------------------------------------------------------
+  anyExecutionInFlight() {
+    return Array.from(this.tracked.values()).some(
+      (status) => IN_PROGRESS_STATUSES.includes(status)
+    );
+  }
   setStatus(status) {
     this.status = status;
   }
@@ -2436,9 +2462,7 @@ var UnifoldClient = class {
       throw new Error("Unifold: publishableKey is required");
     }
     if (!publishableKey.startsWith("pk_test_") && !publishableKey.startsWith("pk_live_")) {
-      console.warn(
-        'Unifold: publishableKey should start with "pk_test_" or "pk_live_".'
-      );
+      console.warn('Unifold: publishableKey should start with "pk_test_" or "pk_live_".');
     }
     this.publishableKey = publishableKey;
   }

package/dist/index.mjs

@@ -421,6 +421,9 @@ function getOnrampSessionStartUrl(request, publishableKey) {
   if (request.email) {
     params.append("email", request.email);
   }
+  if (request.payment_method_type) {
+    params.append("payment_method_type", request.payment_method_type);
+  }
   if (request.payment_method) {
     params.append("payment_method", request.payment_method);
   }
@@ -1078,11 +1081,12 @@ async function stripeGetDefaultToken(params, publishableKey) {
 }
 var HEADLESS_STRIPE_BASE = "/v1/public/onramps/headless/stripe";
 var StripeApiResponseError = class extends Error {
-  constructor(message, statusCode, stripeCode, errorType) {
+  constructor(message, statusCode, stripeCode, errorType, stripeMessage) {
     super(message);
     this.statusCode = statusCode;
     this.stripeCode = stripeCode;
     this.errorType = errorType;
+    this.stripeMessage = stripeMessage;
     this.name = "StripeApiResponseError";
   }
 };
@@ -1093,7 +1097,8 @@ function throwStripeError(prefix, response, error) {
     `${prefix}: ${detailMessage}`,
     response.status,
     stripeError?.code,
-    error.error_type
+    error.error_type,
+    stripeError?.message
   );
 }
 async function stripeGetConfig(publishableKey) {
@@ -1729,6 +1734,9 @@ var DepositSession = class {
     __publicField(this, "baselineMs", 0);
     __publicField(this, "tracked", /* @__PURE__ */ new Map());
     __publicField(this, "pollErrorLatched", false);
+    __publicField(this, "pollInFlight", false);
+    /** First execution to succeed this run — waitForSuccess's one-shot answer. */
+    __publicField(this, "firstSuccess", null);
     __publicField(this, "detectionTimer", null);
     __publicField(this, "nudgeTimer", null);
     __publicField(this, "armTimer", null);
@@ -1799,8 +1807,9 @@ var DepositSession = class {
     this.runToken += 1;
     this.clearTimers();
     this.startPromise = null;
-    if (this.checkingDeposit) {
-      this.checkingDeposit = false;
+    this.checkingDeposit = false;
+    if (this.status !== "idle" && this.status !== "error") {
+      this.setStatus("idle");
     }
     if (wasActive && !this.destroyed) {
       this.commit();
@@ -1822,9 +1831,11 @@ var DepositSession = class {
   // -- Promise waiters (subscription sugar over the event stream) ------------
   /**
    * Resolve when the session reaches one of the given statuses (immediately
-   * if it's already there). Generic primitive over the status state machine:
-   * `waitForStatus('processing')` awaits detection; `waitForStatus(['succeeded',
-   * 'failed'])` awaits a terminal outcome.
+   * if it's already there). Generic primitive over the lifecycle state
+   * machine — e.g. `waitForStatus('processing')` awaits detection of live
+   * activity, `waitForStatus('ready')` awaits readiness. Statuses
+   * carry no outcomes; await those with {@link waitForSuccess} or the
+   * `direct_execution.*` events.
    *
    * Rejects with {@link DepositSessionWaitError} on abort or destroy().
    * Does not start or stop the session — it only listens.
@@ -1853,14 +1864,15 @@ var DepositSession = class {
    * Multi-execution semantics (unlike quote-scoped models such as Privy's,
    * one session can observe many executions — a user may send twice, or on
    * two chains): this waiter is one-shot "first completion" detection. If an
-   * execution has already succeeded, it resolves immediately with that
-   * execution. The session keeps polling after success — to react to every
-   * settlement, subscribe to `direct_execution.succeeded` events or read
-   * `snapshot.executions` instead.
+   * execution has already succeeded this run, it resolves immediately with
+   * the FIRST one that did (not the newest). The session keeps polling after
+   * success — to react to every settlement, subscribe to
+   * `direct_execution.succeeded` events or read `snapshot.executions`.
    *
    * Rejects with {@link DepositSessionWaitError}:
-   * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails
-   *   before any succeeds,
+   * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails and
+   *   NO other observed execution is still in flight — a failure while
+   *   another deposit is pending keeps waiting (that one may still succeed),
    * - `SESSION_ERROR` (cause: the fatal {@link DepositSessionError}) on fatal
    *   session errors (e.g. address creation failed),
    * - `ABORTED` / `DESTROYED` per the wait options and session lifecycle.
@@ -1871,29 +1883,28 @@ var DepositSession = class {
         options,
         reject,
         subscribe: (settle) => {
-          const { executions, error } = this.snapshot;
-          const alreadySucceeded = executions.find(
-            (execution) => execution.status === "succeeded" /* SUCCEEDED */
+          const rejectFailure = (failed) => settle(
+            () => reject(new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", failed))
           );
-          if (alreadySucceeded) {
-            settle(() => resolve(alreadySucceeded));
+          const { executions, error } = this.snapshot;
+          if (this.firstSuccess) {
+            const first = this.firstSuccess;
+            settle(() => resolve(first));
             return () => {
             };
           }
           const alreadyFailed = executions.find(
             (execution) => FAILURE_STATUSES.includes(execution.status)
           );
-          if (alreadyFailed) {
-            settle(
-              () => reject(
-                new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", alreadyFailed)
-              )
-            );
+          if (alreadyFailed && !this.anyExecutionInFlight()) {
+            rejectFailure(alreadyFailed);
             return () => {
             };
           }
           if (error?.fatal) {
-            settle(() => reject(new DepositSessionWaitError("SESSION_ERROR", error.message, error)));
+            settle(
+              () => reject(new DepositSessionWaitError("SESSION_ERROR", error.message, error))
+            );
             return () => {
             };
           }
@@ -1902,14 +1913,20 @@ var DepositSession = class {
               "direct_execution.succeeded" /* EXECUTION_SUCCEEDED */,
               (event) => settle(() => resolve(event.data.object))
             ),
-            this.on(
-              "direct_execution.failed" /* EXECUTION_FAILED */,
-              (event) => settle(
-                () => reject(
-                  new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", event.data.object)
-                )
-              )
-            ),
+            this.on("direct_execution.failed" /* EXECUTION_FAILED */, (event) => {
+              if (this.anyExecutionInFlight()) return;
+              rejectFailure(event.data.object);
+            }),
+            // A previously-failed wait condition can become settleable when
+            // the last in-flight execution also fails (updated → failed is
+            // covered above; updated → refunded transitions re-check here).
+            this.on("direct_execution.updated" /* EXECUTION_UPDATED */, () => {
+              if (this.anyExecutionInFlight() || this.firstSuccess) return;
+              const failed = this.snapshot.executions.find(
+                (execution) => FAILURE_STATUSES.includes(execution.status)
+              );
+              if (failed) rejectFailure(failed);
+            }),
             this.on("deposit_session.errored" /* SESSION_ERRORED */, (event) => {
               if (!event.data.object.fatal) return;
               settle(
@@ -1963,7 +1980,9 @@ var DepositSession = class {
       () => reject(new DepositSessionWaitError("ABORTED", "Wait aborted", options.signal?.reason))
     );
     const onDestroy = () => settle(
-      () => reject(new DepositSessionWaitError("DESTROYED", "DepositSession was destroyed while waiting"))
+      () => reject(
+        new DepositSessionWaitError("DESTROYED", "DepositSession was destroyed while waiting")
+      )
     );
     this.waiterDestroyCallbacks.add(onDestroy);
     options.signal?.addEventListener("abort", onAbort, { once: true });
@@ -1977,19 +1996,20 @@ var DepositSession = class {
     this.tracked.clear();
     this.pollErrorLatched = false;
     this.executions = [];
+    this.firstSuccess = null;
     this.error = null;
     this.checkingDeposit = false;
+    this.addresses = [];
+    this.addressIds = [];
     this.setStatus("creating_addresses");
+    this.commit();
     this.emitSessionEvent("deposit_session.started" /* SESSION_STARTED */, {
       sessionId: this.id
     });
     this.notify();
     let wallets;
     try {
-      [wallets] = await Promise.all([
-        this.createAddressesWithRetry(token),
-        this.runStartChecks()
-      ]);
+      [wallets] = await Promise.all([this.createAddressesWithRetry(token), this.runStartChecks()]);
     } catch (cause) {
       if (token !== this.runToken) return;
       const isCheck = cause instanceof SessionCheckError;
@@ -2003,13 +2023,14 @@ var DepositSession = class {
     if (token !== this.runToken) return;
     this.addresses = wallets.map(mapWalletToDepositAddress);
     this.addressIds = wallets.map((w) => w.id).filter(Boolean);
-    this.setStatus("awaiting_funds");
+    this.setStatus("ready");
     this.commit();
     this.emitSessionEvent("deposit_session.addresses_created" /* ADDRESSES_CREATED */, {
       sessionId: this.id,
       addresses: this.addresses
     });
     this.notify();
+    if (token !== this.runToken) return;
     this.startDetectionLoop(token);
     if (this.confirmationMode === "auto") {
       this.armTimer = setTimeout(() => {
@@ -2085,11 +2106,29 @@ var DepositSession = class {
   }
   // -- Detection polling (port of useDepositPolling Effect 2) ----------------
   startDetectionLoop(token) {
-    const poll = () => void this.pollExecutions(token);
+    const poll = () => {
+      if (token !== this.runToken) {
+        if (this.detectionTimer) {
+          clearInterval(this.detectionTimer);
+          this.detectionTimer = null;
+        }
+        return;
+      }
+      void this.pollExecutions(token);
+    };
     poll();
     this.detectionTimer = setInterval(poll, DETECTION_POLL_INTERVAL_MS);
   }
   async pollExecutions(token) {
+    if (this.pollInFlight) return;
+    this.pollInFlight = true;
+    try {
+      await this.pollExecutionsOnce(token);
+    } finally {
+      this.pollInFlight = false;
+    }
+  }
+  async pollExecutionsOnce(token) {
     try {
       const response = await queryExecutions(
         this.externalUserId,
@@ -2155,9 +2194,7 @@ var DepositSession = class {
     const execution = mapDirectExecution(wire);
     const existingIndex = this.executions.findIndex((e) => e.id === execution.id);
     if (existingIndex >= 0) {
-      this.executions = this.executions.map(
-        (e, i) => i === existingIndex ? execution : e
-      );
+      this.executions = this.executions.map((e, i) => i === existingIndex ? execution : e);
     } else {
       this.executions = [...this.executions, execution].sort((a, b) => {
         const timeA = a.createdAt ? new Date(a.createdAt).getTime() : 0;
@@ -2165,21 +2202,15 @@ var DepositSession = class {
         return timeB - timeA;
       });
     }
-    if (wire.status === "succeeded" /* SUCCEEDED */) {
-      this.setStatus("succeeded");
-    } else if (FAILURE_STATUSES.includes(wire.status)) {
-      this.setStatus("failed");
-    } else if (IN_PROGRESS_STATUSES.includes(wire.status)) {
-      this.setStatus("processing");
+    this.setStatus(this.anyExecutionInFlight() ? "processing" : "ready");
+    const wasInProgressOrNew = previousStatus === null || IN_PROGRESS_STATUSES.includes(previousStatus);
+    if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew && !this.firstSuccess) {
+      this.firstSuccess = execution;
     }
     this.commit();
     const eventCreated = this.executionEventTimestamp(wire);
     if (previousStatus === null) {
-      this.emitExecutionEvent(
-        "direct_execution.detected" /* EXECUTION_DETECTED */,
-        execution,
-        eventCreated
-      );
+      this.emitExecutionEvent("direct_execution.detected" /* EXECUTION_DETECTED */, execution, eventCreated);
     } else {
       this.emitExecutionEvent(
         "direct_execution.updated" /* EXECUTION_UPDATED */,
@@ -2187,25 +2218,17 @@ var DepositSession = class {
         eventCreated
       );
     }
-    const wasInProgressOrNew = previousStatus === null || IN_PROGRESS_STATUSES.includes(previousStatus);
     if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew) {
-      this.emitExecutionEvent(
-        "direct_execution.succeeded" /* EXECUTION_SUCCEEDED */,
-        execution,
-        eventCreated
-      );
+      this.emitExecutionEvent("direct_execution.succeeded" /* EXECUTION_SUCCEEDED */, execution, eventCreated);
     } else if (FAILURE_STATUSES.includes(wire.status) && (previousStatus === null || !FAILURE_STATUSES.includes(previousStatus))) {
-      this.emitExecutionEvent(
-        "direct_execution.failed" /* EXECUTION_FAILED */,
-        execution,
-        eventCreated
-      );
+      this.emitExecutionEvent("direct_execution.failed" /* EXECUTION_FAILED */, execution, eventCreated);
     }
     this.notify();
   }
   // -- Scan nudge (port of useDepositPolling Effects 1 + 3) ------------------
   armConfirmation(trigger) {
     if (this.checkingDeposit || this.destroyed) return;
+    if (this.addressIds.length === 0) return;
     if (this.armTimer) {
       clearTimeout(this.armTimer);
       this.armTimer = null;
@@ -2222,10 +2245,8 @@ var DepositSession = class {
       if (token !== this.runToken) return;
       void Promise.all(
         this.addressIds.map(
-          (id) => pollDirectExecutions({ deposit_wallet_id: id }, this.publishableKey).catch(
-            () => {
-            }
-          )
+          (id) => pollDirectExecutions({ deposit_wallet_id: id }, this.publishableKey).catch(() => {
+          })
         )
       );
     };
@@ -2233,6 +2254,11 @@ var DepositSession = class {
     this.nudgeTimer = setInterval(nudge, SCAN_NUDGE_INTERVAL_MS);
   }
   // -- Internals --------------------------------------------------------------
+  anyExecutionInFlight() {
+    return Array.from(this.tracked.values()).some(
+      (status) => IN_PROGRESS_STATUSES.includes(status)
+    );
+  }
   setStatus(status) {
     this.status = status;
   }
@@ -2307,9 +2333,7 @@ var UnifoldClient = class {
       throw new Error("Unifold: publishableKey is required");
     }
     if (!publishableKey.startsWith("pk_test_") && !publishableKey.startsWith("pk_live_")) {
-      console.warn(
-        'Unifold: publishableKey should start with "pk_test_" or "pk_live_".'
-      );
+      console.warn('Unifold: publishableKey should start with "pk_test_" or "pk_live_".');
     }
     this.publishableKey = publishableKey;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifold/core",
-  "version": "0.1.70-beta.1",
+  "version": "0.1.70",
   "description": "Unifold Core SDK - Core types, API client, and business logic",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",