@unifold/core 0.1.69 → 0.1.70

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;
@@ -73,6 +73,18 @@ interface CreateDepositAddressRequest {
  * @param overrides - Override default configuration (external_user_id, recipient_address, etc.)
  * @param publishableKey - Optional publishable key, defaults to configured key
  */
+/**
+ * Thrown when deposit-address creation fails with a `validation_error` (HTTP 400).
+ * In the deposit flow the recipient address is the only user-entered address
+ * (the destination token comes from the supported list), so callers treat this
+ * as an invalid-recipient signal and can render the invalid-address screen
+ * without waiting for the separate /verify call.
+ */
+declare class DepositAddressValidationError extends Error {
+    readonly isDepositAddressValidationError = true;
+    constructor(message: string);
+}
+declare function isDepositAddressValidationError(error: unknown): error is DepositAddressValidationError;
 declare function createDepositAddress(overrides?: Partial<CreateDepositAddressRequest>, publishableKey?: string): Promise<DepositAddressResponse>;
 interface GetExistingDepositAddressRequest {
     external_user_id: string;
@@ -325,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;
@@ -359,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;
@@ -372,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;
@@ -406,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[];
     /**
@@ -605,6 +634,12 @@ interface ProjectConfigResponse {
         enabled: boolean;
     };
 }
+interface PublicIncidentResponse {
+    enabled: boolean;
+    severity: 'info' | 'degraded' | 'outage';
+    messages: string[];
+    status_page_url?: string;
+}
 /**
  * Bank-transfer project-level toggle returned by `/projects/config`.
  *
@@ -633,6 +668,11 @@ interface GetProjectConfigOptions {
     subdivisionCode?: string;
 }
 declare function getProjectConfig(publishableKey?: string, options?: GetProjectConfigOptions): Promise<ProjectConfigResponse>;
+/**
+ * Get the env-driven public incident payload used for in-product outage messaging.
+ * Requires a publishable key for consistency with other public widget endpoints.
+ */
+declare function getPublicIncident(publishableKey?: string): Promise<PublicIncidentResponse>;
 interface IpAddressResponse {
     alpha2: string;
     alpha3: string;
@@ -761,8 +801,10 @@ interface WalletMobileDeepLinkResponse {
  * @param wallet - Wallet id (phantom, metamask, coinbase, trust, rainbow, rabby, okx)
  * @param depositAddresses - Unifold deposit addresses (one per source chain) to embed in the hosted pay URL
  * @param publishableKey - Optional publishable key, defaults to configured key
+ * @param amountUsd - Optional USD amount to pre-fill on the hosted pay page so the user
+ *   doesn't have to re-enter it after the mobile wallet redirect
  */
-declare function getWalletMobileDeepLink(wallet: WalletMobileDeepLinkWallet, depositAddresses: WalletMobileDeepLinkDepositAddress[], publishableKey?: string): Promise<WalletMobileDeepLinkResponse>;
+declare function getWalletMobileDeepLink(wallet: WalletMobileDeepLinkWallet, depositAddresses: WalletMobileDeepLinkDepositAddress[], publishableKey?: string, amountUsd?: string): Promise<WalletMobileDeepLinkResponse>;
 interface AddressBalanceResponse {
     address: string;
     chain_type: string;
@@ -799,6 +841,8 @@ interface VerifyAddressResponse {
     valid: boolean;
     /** Standardized error code for frontend i18n */
     failure_code?: AddressValidationFailureCode;
+    /** Optional human-readable message from backend */
+    message?: string;
     /** Metadata for message interpolation */
     metadata?: AddressValidationMetadata;
 }
@@ -1560,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.
@@ -1973,6 +2031,32 @@ interface DirectExecution {
     destinationTransactionHashes: string[];
     status: ExecutionStatus;
     failureReason: string | null;
+    /** ISO timestamp the execution was created. */
+    createdAt?: string;
+    /** ISO timestamp the execution was last updated. */
+    updatedAt?: string;
+    /** Block explorer URL for the source transaction. */
+    explorerUrl?: string;
+    /** Block explorer URL for the destination transaction, when available. */
+    destinationExplorerUrl?: string | null;
+    /** Display metadata (icon, decimals) for the source token. */
+    sourceTokenMetadata?: {
+        iconUrl?: string;
+        iconUrls?: {
+            url: string;
+            format: 'svg' | 'png';
+        }[];
+        decimals?: number;
+    };
+    /** Display metadata (icon, decimals) for the destination token. */
+    destinationTokenMetadata?: {
+        iconUrl?: string;
+        iconUrls?: {
+            url: string;
+            format: 'svg' | 'png';
+        }[];
+        decimals?: number;
+    };
 }
 /** Map from event type to its `data.object` shape */
 interface DepositEventDataMap {
@@ -2055,6 +2139,439 @@ type CheckoutPaymentIntentSucceededEvent = Extract<CheckoutEvent, {
     type: CheckoutEventType.PAYMENT_INTENT_SUCCEEDED;
 }>;
 
+/**
+ * Display metadata for a token involved in an execution (camelCase projection
+ * of the wire `*_token_metadata` objects).
+ */
+interface TokenDisplayMetadata {
+    iconUrl?: string;
+    iconUrls?: IconUrl[];
+    decimals?: number;
+}
+/**
+ * A deposit address the user can fund on a given chain type.
+ *
+ * camelCase SDK projection of the wire {@link Wallet} shape returned by
+ * `POST /v1/public/deposit_addresses`. Named `DepositAddress` (not "wallet")
+ * because "wallet" is overloaded across the SDK (browser wallets, exchange
+ * wallets); this resource is the address an integrator shows the user.
+ */
+interface DepositAddress {
+    id: string;
+    chainType: ChainType;
+    addressType: string | null;
+    address: string;
+    destinationChainType: ChainType;
+    destinationChainId: string;
+    destinationTokenAddress: string;
+    recipientAddress: string;
+    isPrimary: boolean;
+}
+/** Map a wire {@link Wallet} to the SDK-facing {@link DepositAddress}. */
+declare function mapWalletToDepositAddress(wallet: Wallet): DepositAddress;
+/**
+ * Map a wire {@link DirectExecutionResponse} to the SDK-facing
+ * {@link DirectExecution} used in events and callbacks.
+ *
+ * Superset of the mapping historically done inside the deposit polling hook:
+ * additionally carries timestamps, explorer URLs, and token display metadata,
+ * which custom (headless) UIs need to render an execution timeline.
+ */
+declare function mapDirectExecution(execution: DirectExecutionResponse): DirectExecution;
+
+/** How often `/direct_executions/query` is polled (modal: POLL_INTERVAL_MS). */
+declare const DETECTION_POLL_INTERVAL_MS = 2500;
+/** How often `/direct_executions/poll` is nudged once armed (modal: POLL_ENDPOINT_INTERVAL_MS). */
+declare const SCAN_NUDGE_INTERVAL_MS = 5000;
+/** Delay before the scan nudge auto-arms in 'auto' mode (modal: DEPOSIT_CONFIRM_DELAY_MS). */
+declare const DETECTION_ARM_DELAY_MS = 5000;
+/**
+ * Lookback window for catching deposits sent just before start() — fixed, not
+ * host-configurable (modal: CUTOFF_BUFFER_MS). In-flight (non-terminal)
+ * executions created up to this long before the session baseline are detected
+ * and their settlement fires live; executions created before the baseline that
+ * are ALREADY terminal at first sight are ignored as history (prevents
+ * duplicate success side effects on quick re-entry); anything older is
+ * ignored entirely.
+ */
+declare const LOOKBACK_MS = 60000;
+/**
+ * Events emitted by {@link DepositSession}, following the `resource.action`
+ * convention. `direct_execution.succeeded` intentionally matches the existing
+ * {@link DepositEventType.DIRECT_EXECUTION_SUCCEEDED} name so one host-side
+ * handler can serve modal `onEvent` events and headless session events.
+ */
+declare enum DepositSessionEventType {
+    SESSION_STARTED = "deposit_session.started",
+    ADDRESSES_CREATED = "deposit_session.addresses_created",
+    /** The backend scan nudge (/poll) was armed — auto timer or confirmFundsSent(). */
+    CONFIRMATION_STARTED = "deposit_session.confirmation_started",
+    SESSION_STOPPED = "deposit_session.stopped",
+    /** Non-fatal (transient polling outage) and fatal errors; `data.object.fatal` distinguishes. */
+    SESSION_ERRORED = "deposit_session.errored",
+    /** First time an execution is seen this session. */
+    EXECUTION_DETECTED = "direct_execution.detected",
+    /** Any status transition on a tracked execution. */
+    EXECUTION_UPDATED = "direct_execution.updated",
+    /** Kept byte-compatible with the modal's DepositEventType member. */
+    EXECUTION_SUCCEEDED = "direct_execution.succeeded",
+    EXECUTION_FAILED = "direct_execution.failed"
+}
+type DepositSessionErrorCode = 'ADDRESS_CREATION_FAILED' | 'POLLING_ERROR' | 'DEPOSIT_FAILED' | 'INVALID_RECIPIENT';
+interface DepositSessionError {
+    code: DepositSessionErrorCode;
+    message: string;
+    /** Fatal errors end the run (status 'error'); non-fatal ones don't stop polling. */
+    fatal: boolean;
+    cause?: unknown;
+}
+interface DepositSessionEventDataMap {
+    [DepositSessionEventType.SESSION_STARTED]: {
+        sessionId: string;
+    };
+    [DepositSessionEventType.ADDRESSES_CREATED]: {
+        sessionId: string;
+        addresses: DepositAddress[];
+    };
+    [DepositSessionEventType.CONFIRMATION_STARTED]: {
+        sessionId: string;
+        trigger: 'auto' | 'manual';
+    };
+    [DepositSessionEventType.SESSION_STOPPED]: {
+        sessionId: string;
+    };
+    [DepositSessionEventType.SESSION_ERRORED]: {
+        sessionId: string;
+        code: DepositSessionErrorCode;
+        message: string;
+        fatal: boolean;
+    };
+    [DepositSessionEventType.EXECUTION_DETECTED]: DirectExecution;
+    [DepositSessionEventType.EXECUTION_UPDATED]: DirectExecution & {
+        previousStatus: ExecutionStatus | null;
+    };
+    [DepositSessionEventType.EXECUTION_SUCCEEDED]: DirectExecution;
+    [DepositSessionEventType.EXECUTION_FAILED]: DirectExecution;
+}
+/**
+ * Event envelope emitted by the deposit session. Mirrors the server-side
+ * webhook payload shape (top-level `id`, `type`, `created`, resource under
+ * `data.object`), with `sevt_` IDs to distinguish from backend `evt_` IDs.
+ */
+type DepositSessionEvent = {
+    [K in DepositSessionEventType]: {
+        id: string;
+        type: K;
+        created: number;
+        /**
+         * Host-provided rail hint ({@link DepositSessionParams.method}, default
+         * 'transfer'). The session can't observe how funds were sent — a host
+         * driving its own wallet integration sets 'wallet_connect'.
+         */
+        method?: DepositMethod;
+        data: {
+            object: DepositSessionEventDataMap[K];
+        };
+    };
+}[DepositSessionEventType];
+/** Map from event type to its fully-narrowed envelope. */
+type DepositSessionEventMap = {
+    [K in DepositSessionEventType]: Extract<DepositSessionEvent, {
+        type: K;
+    }>;
+};
+interface DepositSessionDestination {
+    chainType: ChainType;
+    chainId: string;
+    tokenAddress: string;
+    /** Address that receives the deposited funds. */
+    recipientAddress: string;
+    /** EVM-only post-delivery calls; same constraints as DepositConfig.contractCalls. */
+    contractCalls?: EvmContractCall[];
+}
+interface DepositSessionParams {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string;
+    /** Destination — what the deposit converts into and where it lands. */
+    destination: DepositSessionDestination;
+    /**
+     * When the backend scan nudge (/poll) is armed:
+     *  - 'auto'   (default): armed automatically DETECTION_ARM_DELAY_MS after start.
+     *  - 'manual': armed only when the host calls session.confirmFundsSent().
+     * Detection polling of /query runs from start() in both modes.
+     */
+    confirmationMode?: 'auto' | 'manual';
+    /** Rail hint stamped onto emitted events' `method` field. @default 'transfer' */
+    method?: DepositMethod;
+}
+/** Internal construction config — created via `UnifoldClient.createDepositSession`. */
+interface DepositSessionConfig extends DepositSessionParams {
+    publishableKey: string;
+}
+/**
+ * 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. */
+    addresses: DepositAddress[];
+    /** All executions observed this session, newest first. */
+    executions: DirectExecution[];
+    latestExecution: DirectExecution | null;
+    /**
+     * True while the backend is actively checking for the deposit — i.e. the
+     * scan nudge (/poll) is armed (auto timer elapsed or confirmFundsSent()).
+     */
+    isCheckingDeposit: boolean;
+    /** Latest non-fatal (e.g. transient polling outage) or fatal error, if any. */
+    error: DepositSessionError | null;
+}
+interface DepositSessionWaitOptions {
+    /**
+     * Abort the wait (reject with code 'ABORTED'; the signal's abort `reason`
+     * is passed through as the error's `cause`). Cancels only the wait — the
+     * session keeps polling, because a deposit is not cancelable: once the user
+     * has sent funds they will arrive regardless of who is still awaiting.
+     *
+     * For a deadline, compose the platform primitive:
+     * `waitForSuccess({ signal: AbortSignal.timeout(60_000) })`.
+     * There is deliberately no `timeoutMs` option — a timeout is "outcome
+     * unknown", not "outcome bad", and modeling it as a distinct failure code
+     * tempts hosts into rendering a deposit as failed right before it lands.
+     */
+    signal?: AbortSignal;
+}
+type DepositSessionWaitErrorCode = 'ABORTED' | 'DESTROYED' | 'DEPOSIT_FAILED' | 'SESSION_ERROR';
+/** Rejection type for {@link DepositSession.waitForStatus} / {@link DepositSession.waitForSuccess}. */
+declare class DepositSessionWaitError extends Error {
+    readonly code: DepositSessionWaitErrorCode;
+    /** Failed execution (`DEPOSIT_FAILED`) or fatal {@link DepositSessionError} (`SESSION_ERROR`). */
+    readonly cause?: unknown;
+    constructor(code: DepositSessionWaitErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Headless controller for one attempt by one user to fund a destination via
+ * their deposit addresses — regardless of rail (manual transfer, host-broadcast
+ * wallet transaction, exchange push). Owns:
+ *
+ * 1. creating/fetching the deposit addresses,
+ * 2. detection polling (`/direct_executions/query` every 2.5s),
+ * 3. the backend scan nudge (`/direct_executions/poll` every 5s, once armed),
+ * 4. execution tracking (lookback window, new-execution detection,
+ *    status-transition detection, poll-error latching) — ported from the
+ *    modal's `useDepositPolling`,
+ * 5. a status state machine and a typed event stream.
+ *
+ * UI state should come from {@link getSnapshot} (or the React hook built on
+ * it); events are for side effects (analytics, toasts, navigation).
+ */
+declare class DepositSession {
+    /** Immutable id for correlation, `dsess_<ksuid>`. Client-generated. */
+    readonly id: string;
+    private readonly emitter;
+    private readonly listeners;
+    private readonly publishableKey;
+    private readonly externalUserId;
+    private readonly destination;
+    private readonly confirmationMode;
+    private readonly method;
+    private runToken;
+    private startPromise;
+    private destroyed;
+    /** Pending waiter rejections, invoked by destroy() so waiters never hang. */
+    private waiterDestroyCallbacks;
+    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;
+    private status;
+    private addresses;
+    private addressIds;
+    private executions;
+    private checkingDeposit;
+    private error;
+    private snapshot;
+    constructor(config: DepositSessionConfig);
+    /** Synchronous snapshot; the reference is stable until state changes. */
+    getSnapshot(): DepositSessionSnapshot;
+    /**
+     * Subscribe to snapshot changes (external-store contract; drives
+     * `useSyncExternalStore` in the React binding). Returns an unsubscribe fn.
+     */
+    subscribe(listener: () => void): () => void;
+    /** Typed event subscription. Returns an unsubscribe function. */
+    on<K extends DepositSessionEventType>(type: K, handler: (event: DepositSessionEventMap[K]) => void): () => void;
+    on(type: '*', handler: (event: DepositSessionEvent) => void): () => void;
+    /**
+     * Creates/fetches addresses (with a fail-fast recipient check) and starts
+     * detection polling. Idempotent while running; callable again after stop()
+     * or a fatal error (fresh baseline).
+     */
+    start(): Promise<void>;
+    /** Arms the backend scan nudge in 'manual' mode. No-op if already armed. */
+    confirmFundsSent(): void;
+    /**
+     * Stops all polling. The session can be restarted with start(), which
+     * resets the baseline and tracked executions (fresh run).
+     */
+    stop(): void;
+    /** stop() + release all listeners. Terminal — start() rejects afterwards. */
+    destroy(): void;
+    /**
+     * Resolve when the session reaches one of the given statuses (immediately
+     * 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.
+     */
+    waitForStatus(status: DepositSessionStatus | DepositSessionStatus[], options?: DepositSessionWaitOptions): Promise<DepositSessionSnapshot>;
+    /**
+     * Resolve with the **first** succeeded {@link DirectExecution} observed by
+     * this session — the one-liner for the 90% case. Mirrors `beginDeposit()`'s
+     * promise contract: resolve on success, reject on failure.
+     *
+     * 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 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 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.
+     */
+    waitForSuccess(options?: DepositSessionWaitOptions): Promise<DirectExecution>;
+    /**
+     * Shared waiter plumbing: AbortSignal and destroy() rejection, with
+     * single-settlement and cleanup. `subscribe` installs the wait condition
+     * and returns its unsubscribe fn; it settles via `settle(fn)`.
+     */
+    private installWaiter;
+    private run;
+    private failFatally;
+    private createAddressesWithRetry;
+    /**
+     * Fail-fast recipient validation (e.g. Algorand asset opt-in). Fails open
+     * on network errors — the backend still enforces at execution time — but a
+     * definitive negative result is fatal.
+     *
+     * Deliberately NOT IP/geo-aware: generating deposit addresses headless
+     * carries no region gate. Hosts that want the modal's geo behavior render
+     * against the opt-in `useAllowedCountry` hook instead.
+     */
+    private runStartChecks;
+    private startDetectionLoop;
+    private pollExecutions;
+    private pollExecutionsOnce;
+    private processExecutionChange;
+    private armConfirmation;
+    private anyExecutionInFlight;
+    private setStatus;
+    private clearTimers;
+    private buildSnapshot;
+    /** Rebuild the snapshot so getSnapshot() reflects current state. */
+    private commit;
+    private notify;
+    private executionEventTimestamp;
+    private emitSessionEvent;
+    private emitExecutionEvent;
+}
+
+interface UnifoldClientOptions {
+    /** Publishable key (`pk_test_*` / `pk_live_*`). */
+    publishableKey: string;
+}
+interface DepositAddressParams {
+    externalUserId: string;
+    destination: {
+        chainType: ChainType;
+        chainId: string;
+        tokenAddress: string;
+        recipientAddress: string;
+        contractCalls?: EvmContractCall[];
+    };
+}
+interface ListExecutionsParams {
+    externalUserId: string;
+    /** @default ActionType.Deposit */
+    actionType?: ActionType;
+}
+interface SupportedDepositTokensParams {
+    destination?: {
+        chainType: string;
+        chainId: string;
+        tokenAddress: string;
+    };
+    productType?: ProductType;
+}
+interface VerifyAddressParams {
+    chainType: string;
+    chainId: string;
+    tokenAddress: string;
+    recipientAddress: string;
+}
+interface AddressVerification {
+    valid: boolean;
+    failureCode: AddressValidationFailureCode | null;
+    metadata: {
+        chain_name?: string;
+        token_symbol?: string;
+    } | null;
+}
+/**
+ * Configured entry object for the headless SDK — mirrors `loadStripe(pk)`.
+ *
+ * All resource methods return camelCase SDK types; snake_case wire shapes
+ * stay internal. Flow controllers (deposit sessions) are created from here so
+ * they inherit the client's publishable key.
+ */
+declare class UnifoldClient {
+    readonly publishableKey: string;
+    constructor(options: UnifoldClientOptions);
+    /** Create a headless deposit-session flow controller. */
+    createDepositSession(params: DepositSessionParams): DepositSession;
+    /**
+     * Create (idempotently) and return the user's deposit addresses for a
+     * destination — `POST /v1/public/deposit_addresses`.
+     */
+    getDepositAddresses(params: DepositAddressParams): Promise<DepositAddress[]>;
+    /** List the user's executions — `POST /v1/public/direct_executions/query`. */
+    listExecutions(params: ListExecutionsParams): Promise<DirectExecution[]>;
+    /** Source tokens/chains a user can deposit from for a destination. */
+    getSupportedDepositTokens(params?: SupportedDepositTokensParams): Promise<SupportedToken[]>;
+    /** Validate a recipient address for a destination (e.g. Algorand opt-in). */
+    verifyAddress(params: VerifyAddressParams): Promise<AddressVerification>;
+    /** Project-level configuration (feature flags, blocked countries, ...). */
+    getProjectConfig(options?: {
+        countryCode?: string;
+        subdivisionCode?: string;
+    }): Promise<ProjectConfigResponse>;
+}
+/** Create a configured {@link UnifoldClient} — mirrors `loadStripe(pk)`. */
+declare function createUnifoldClient(options: UnifoldClientOptions): UnifoldClient;
+
 /**
  * User IP information interface
  */
@@ -2177,4 +2694,4 @@ declare const i18n: {
 };
 type I18nStrings = typeof i18n;
 
-export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, 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, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, 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, 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 QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, type RequestCoinbaseApplePayLimitUpgradeRequest, type RequestCoinbaseApplePayLimitUpgradeResponse, 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 SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, type UserIpInfo, 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, 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, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, isApplePayLimitReached, listPaymentIntentExecutions, 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 };