@unifold/headless-react 0.1.75 → 0.1.77

package/README.md

@@ -117,8 +117,8 @@ stream (they only listen — neither starts nor stops the session):
 
 ```ts
 // Generic primitive over the lifecycle state machine:
-await session.waitForStatus('processing');       // live activity detected
-await session.waitForStatus('ready');   // addresses ready / all settled
+await session.waitForStatus('processing'); // live activity detected
+await session.waitForStatus('ready'); // addresses ready / all settled
 
 // The 90% case — mirrors beginDeposit()'s promise contract
 // (resolve on success, reject on failure):
@@ -130,7 +130,7 @@ try {
 }
 ```
 
-Both accept `{ signal }` — an `AbortSignal` cancels the *wait*, never the
+Both accept `{ signal }` — an `AbortSignal` cancels the _wait_, never the
 session (a deposit isn't cancelable: once the user sends funds, they arrive
 whether or not anyone is awaiting). For a deadline, compose the platform
 primitive — `waitForSuccess({ signal: AbortSignal.timeout(60_000) })` — and
@@ -147,7 +147,7 @@ its own `direct_execution.succeeded` event.
 
 **Live outcomes only.** The 60s lookback window exists to catch deposits sent
 moments before the session started — it only admits executions still
-*in-flight* at first sight (their settlement then fires live). An execution
+_in-flight_ at first sight (their settlement then fires live). An execution
 that already settled before the session began is history and never re-fires
 success/failure events, so reopening a deposit screen right after a success
 cannot double-credit. Render history with `useExecutions` instead. To credit each deposit, subscribe
@@ -159,9 +159,129 @@ session.on(DepositSessionEventType.EXECUTION_SUCCEEDED, ({ data }) => {
 });
 ```
 
+## Buy with card — a custom fiat onramp screen
+
+`useOnramp` is the no-UI equivalent of
+`beginDeposit({ initialScreen: 'card' })`: provider quotes + a hosted
+checkout URL + the same settlement watching as a transfer. You render the
+amount input, the provider list, and the progress UI.
+
+```tsx
+import { useOnramp, useFiatCurrencies } from '@unifold/headless-react';
+
+function BuyUSDC({ externalUserId }: Props) {
+  const [amount, setAmount] = useState('100');
+  const { data: fiat } = useFiatCurrencies(); // min/max limits, suggested amounts
+
+  const buy = useOnramp({
+    externalUserId,
+    // Payer country is auto-detected from IP; pass `countryCode` to override.
+    sourceAmount: amount, // live: changes refetch quotes (debounced 500ms)
+    destination: {
+      chainType: 'ethereum',
+      chainId: '8453',
+      tokenAddress: USDC_BASE,
+      recipientAddress: userTreasuryAddress,
+    },
+    onSuccess: (execution) => toast.success(`Received $${execution.destinationAmountUsd}`),
+  });
+
+  return (
+    <div>
+      <AmountInput value={amount} onChange={setAmount} />
+      {/* canSelectProvider is false under fiat-onramp smart routing (the
+          backend routes to a single provider) or when only one provider
+          quotes — hide the picker then, like the modal does. */}
+      {buy.canSelectProvider && (
+        <ProviderList
+          quotes={buy.quotes}
+          selected={buy.selectedQuote}
+          onSelect={(q) => buy.selectQuote(q.serviceProvider)}
+        />
+      )}
+      <button
+        disabled={buy.status !== 'ready' || !buy.selectedQuote}
+        onClick={() => {
+          // Synchronous URL build — safe to open inside the click handler.
+          const checkout = buy.createCheckout();
+          if (checkout) window.open(checkout.url, '_blank');
+        }}
+      >
+        Continue
+      </button>
+      {buy.status === 'awaiting_payment' && <WaitingForProvider checkout={buy.checkout!} />}
+      {buy.status === 'processing' && <MyProgress execution={buy.latestExecution!} />}
+    </div>
+  );
+}
+```
+
+The lifecycle state machine:
+
+```
+idle → preparing → quoting → ready → awaiting_payment ⇄ processing
+              ↘ error (fatal: addresses / no onramp route / invalid recipient)
+```
+
+A full reference screen — amount modes, currency picker, provider list,
+checkout redirect, settlement — lives in `apps/ui-demo/app/onramp/headless`
+(`/demo/onramp/headless`), and `docs/recipes/deposits/headless-card-onramp.mdx`
+walks through building the flow step by step (amount input and prefills,
+quoting, checkout, polling, crediting, error handling).
+
+Same outcome philosophy as `useDeposit`: **outcomes never appear on the
+session status** — read them from `executions`/`latestExecution`, the
+`direct_execution.succeeded`/`.failed` events, or `session.waitForSuccess()`.
+Under the hood the settlement phase _is_ a `DepositSession` (method `'card'`)
+composed over the same deposit addresses, so detection polling, the scan
+nudge, and the lookback window behave identically across rails.
+
+Worth knowing:
+
+- **Quotes auto-refresh every 60s** until checkout (configure with
+  `quoteRefreshIntervalMs`, 0 disables); `quotesUpdatedAt` drives your own
+  countdown. `selectQuote()` is sticky across refreshes and falls back to the
+  backend's top quote if the provider stops quoting.
+- **Provider choice has three modes.** Default: the backend's top quote
+  (`quotes[0]` — the order encodes provider priority) is auto-selected. Host
+  choice: render `quotes` and call `selectQuote()`, or pass a one-shot
+  `createCheckout({ serviceProvider })` without touching the sticky
+  selection. Backend choice: projects with **fiat-onramp smart routing**
+  enabled get exactly one routed quote — `canSelectProvider` is `false` and
+  there is nothing to pick.
+- **Quote failures are non-fatal** (`error.code === 'QUOTES_FAILED'`) — quotes
+  are cleared rather than left stale, and refresh keeps trying.
+- **Payer country is auto-detected** from the user's IP when `countryCode`
+  is omitted ('US' fallback if detection fails — modal parity); the
+  effective value is exposed as `countryCode` on the result. Pass
+  `countryCode` (live) to override with your own geo signal. This is the
+  one deliberate exception to the headless SDK's not-IP-aware stance:
+  for the onramp, country is a functional input of quoting, not a policy
+  gate. Changing it live re-resolves the onramp route as well as the quotes
+  (routing is geo-dependent), so `destinationToken` and `quotes` are briefly
+  empty while that settles.
+- **Amount validation is host-side**: check `minimum_amount`/`maximum_amount`
+  from `useFiatCurrencies` before quoting; the session only requires a
+  parseable amount > 0.
+- **Two amount modes — provide exactly one.** `sourceAmount` ("spend 100
+  USD", fees included; `quote.destinationAmount` is what you receive) or
+  `destinationAmount` ("receive exactly 100 USDC", provider fees added on
+  top; `quote.sourceAmount` is the fiat the user pays). Both are live inputs;
+  swapping which one you pass switches modes in place. In destination mode
+  only providers that support fixed-destination quoting appear in `quotes` —
+  the backend filters the rest — and the destination token has to be a
+  stablecoin (`destinationToken.isStablecoin`), because the amount prices the
+  provider-side currency. For anything else, quoting stops with a non-fatal
+  `DESTINATION_AMOUNT_UNSUPPORTED` error until you switch back to
+  `sourceAmount` (the modal shows an error screen for the same case).
+- `onramp_session.created` and `direct_execution.*` events are byte-compatible
+  with the modal SDK's `onEvent`, so one handler can serve both surfaces.
+- Other rails ride the same hook via `paymentMethodType`
+  (`'card' | 'apple_pay' | 'sepa' | 'us_bank_account'`; default `'card'`).
+
 ### Vanilla JS (no React)
 
-The controller is usable without React from `@unifold/core`:
+The controllers are usable without React from `@unifold/core`:
 
 ```ts
 import { createUnifoldClient } from '@unifold/core';
@@ -177,24 +297,46 @@ showSuccess(execution);
 session.destroy();
 ```
 
+The onramp follows the same shape:
+
+```ts
+const card = unifold.createOnrampSession({
+  externalUserId,
+  destination,
+  quoteRequest: { sourceAmount: '100' }, // country auto-detected; override with countryCode
+});
+await card.start(); // addresses + onramp route + first quotes
+const checkout = card.createCheckout(); // sync — build URL from the selected quote
+openUrl(checkout.url);
+const execution = await card.waitForSuccess();
+card.destroy();
+```
+
 ## Hooks
 
-| Hook | Purpose |
-| --- | --- |
-| `useDeposit` | Flagship flow hook: deposit addresses + execution detection + status state machine + events |
-| `useDepositAddresses` | Addresses without a live session (cached, idempotent create) |
-| `useSupportedDepositTokens` | Source token/chain list for custom pickers |
-| `useExecutions` | Deposit history (tracker screens) |
-| `useAllowedCountry` | Geo gate the modal uses; decide what to render when blocked |
-| `useAddressValidation` | Inline recipient validation (e.g. Algorand opt-in) |
-| `useUnifoldClient` | Escape hatch to the configured vanilla client |
+| Hook                        | Purpose                                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------- |
+| `useDeposit`                | Flagship flow hook: deposit addresses + execution detection + status state machine + events |
+| `useOnramp`                 | Card onramp flow hook: quotes + provider checkout URL + settlement watching                 |
+| `useDepositAddresses`       | Addresses without a live session (cached, idempotent create)                                |
+| `useSupportedDepositTokens` | Source token/chain list for custom pickers                                                  |
+| `useFiatCurrencies`         | Fiat currencies + amount limits/suggestions for card onramp screens                         |
+| `useExecutions`             | Deposit history (tracker screens)                                                           |
+| `useAllowedCountry`         | Geo gate the modal uses; decide what to render when blocked                                 |
+| `useAddressValidation`      | Inline recipient validation (e.g. Algorand opt-in)                                          |
+| `useUnifoldClient`          | Escape hatch to the configured vanilla client                                               |
 
 ## Events
 
 `resource.action` names with webhook-mirroring envelopes; `direct_execution.succeeded`
 is byte-compatible with the modal SDK's `onEvent`:
 
+Envelope fields mirror the webhook payload, so `created` is a Unix timestamp in
+**seconds** (multiply by 1000 before handing it to `Date`).
+
 - `deposit_session.started` / `.addresses_created` / `.confirmation_started` / `.stopped` / `.errored`
+- `onramp_session.started` / `.addresses_created` / `.quotes_updated` / `.created` / `.stopped` / `.errored`
+  (`onramp_session.created` = checkout built — same name and `externalId` payload as the modal)
 - `direct_execution.detected` / `.updated` / `.succeeded` / `.failed`
 
 When mixing the modal and headless surfaces, dedupe on `execution.id` (envelope

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 export { UnifoldConfig, UnifoldProvider, UnifoldProviderProps, useUnifold } from '@unifold/react-provider';
-import { UnifoldClient, ChainType, EvmContractCall, DepositMethod, DepositSessionEvent, DepositAddress, DirectExecution, ExecutionStatus, DepositSessionError, DepositSessionStatus, DepositSession, ActionType, ProductType, SupportedToken, AddressValidationFailureCode } from '@unifold/core';
-export { ActionType, ChainType, DepositAddress, DepositMethod, DepositSession, DepositSessionDestination, DepositSessionError, DepositSessionErrorCode, DepositSessionEvent, DepositSessionEventMap, DepositSessionEventType, DepositSessionParams, DepositSessionSnapshot, DepositSessionStatus, DepositSessionWaitError, DepositSessionWaitErrorCode, DepositSessionWaitOptions, DirectExecution, EvmContractCall, ExecutionStatus, SupportedChain, SupportedToken, UnifoldClient, UnifoldClientOptions, createUnifoldClient } from '@unifold/core';
+import { UnifoldClient, ChainType, EvmContractCall, DepositMethod, DepositSessionEvent, DepositAddress, DirectExecution, ExecutionStatus, DepositSessionError, DepositSessionStatus, DepositSession, OnrampSessionPaymentMethodType, OnrampSessionEvent, OnrampProviderQuote, OnrampSessionError, OnrampSessionStatus, OnrampDestinationToken, OnrampCheckout, OnrampQuoteRequest, OnrampSession, ActionType, ProductType, SupportedToken, AddressValidationFailureCode, FiatCurrenciesResponse } from '@unifold/core';
+export { ActionType, ChainType, DepositAddress, DepositMethod, DepositSession, DepositSessionDestination, DepositSessionError, DepositSessionErrorCode, DepositSessionEvent, DepositSessionEventMap, DepositSessionEventType, DepositSessionParams, DepositSessionSnapshot, DepositSessionStatus, DepositSessionWaitError, DepositSessionWaitErrorCode, DepositSessionWaitOptions, DirectExecution, EvmContractCall, ExecutionStatus, FiatCurrency, OnrampCheckout, OnrampDestinationToken, OnrampProviderQuote, OnrampQuoteRequest, OnrampSession, OnrampSessionError, OnrampSessionErrorCode, OnrampSessionEvent, OnrampSessionEventMap, OnrampSessionEventType, OnrampSessionParams, OnrampSessionPaymentMethodType, OnrampSessionSnapshot, OnrampSessionStatus, OnrampSessionWaitError, OnrampSessionWaitErrorCode, OnrampSessionWaitOptions, SupportedChain, SupportedToken, UnifoldClient, UnifoldClientOptions, createUnifoldClient } from '@unifold/core';
 import * as _tanstack_react_query from '@tanstack/react-query';
 
 /**
@@ -98,6 +98,170 @@ interface UseDepositResult {
  */
 declare function useDeposit(options: UseDepositOptions): UseDepositResult;
 
+interface UseOnrampOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    /** Destination — what the purchase converts into and where it lands. */
+    destination: UseDepositDestination;
+    /**
+     * ISO 3166-1 alpha-2 country of the payer. OPTIONAL — when omitted, the
+     * session auto-detects it from the user's IP during start ('US' fallback,
+     * modal parity). Provide it only to override detection with your own geo
+     * signal; live like the other quote inputs. The effective value is
+     * exposed as `countryCode` on the result.
+     */
+    countryCode?: string;
+    /** ISO 3166-2 subdivision (e.g. 'US-NY') when relevant for provider routing. */
+    subdivisionCode?: string;
+    /**
+     * Fiat amount to spend (fees included), as a decimal string. Live: changes
+     * refetch quotes (debounced). Provide exactly one of `sourceAmount` /
+     * `destinationAmount` — the amount mode.
+     */
+    sourceAmount?: string;
+    /**
+     * Fixed crypto (destination) amount to receive, with provider fees added
+     * on top — "receive 100 USDC". Live like `sourceAmount`, and mutually
+     * exclusive with it. Only providers that support fixed-destination quoting
+     * appear in `quotes`; each quote's `sourceAmount` is the fiat the user
+     * pays.
+     *
+     * Requires a stablecoin destination (`destinationToken.isStablecoin`) —
+     * the amount prices the provider-side currency, so it only means "receive
+     * 100 of the requested token" for stablecoins. Otherwise quoting stops
+     * with a non-fatal `DESTINATION_AMOUNT_UNSUPPORTED` error.
+     */
+    destinationAmount?: string;
+    /** ISO 4217 fiat currency code the user pays in. Live like `sourceAmount`. @default 'usd' */
+    sourceCurrency?: string;
+    /** Payment rail forwarded to the provider session. @default 'card' */
+    paymentMethodType?: OnrampSessionPaymentMethodType;
+    /** Prefill email forwarded to the provider checkout. */
+    email?: string;
+    /** Quote auto-refresh interval; 0 disables. @default 60000 */
+    quoteRefreshIntervalMs?: number;
+    /**
+     * Debounce applied when the live quote inputs (amount/currency/country)
+     * change between renders, so binding an input's value doesn't hit the
+     * quotes API per keystroke (parity with the modal's 500ms). @default 500
+     */
+    quoteDebounceMs?: number;
+    /**
+     * When true (default), start() is called automatically once externalUserId
+     * and the provider's publishable key are present. Set false to gate on
+     * your own UI.
+     */
+    autoStart?: boolean;
+    /** Every lifecycle event ('*' subscription) — analytics/debug fan-out. */
+    onEvent?: (event: OnrampSessionEvent) => void;
+    /** onramp_session.addresses_created */
+    onAddressesReady?: (addresses: DepositAddress[]) => void;
+    /** onramp_session.quotes_updated */
+    onQuotes?: (quotes: OnrampProviderQuote[], selectedQuote: OnrampProviderQuote | null) => void;
+    /** onramp_session.created (checkout built; host opens `url`) */
+    onCheckoutCreated?: (checkout: {
+        externalId: string;
+        url: string;
+        serviceProvider: string;
+    }) => void;
+    /** direct_execution.detected */
+    onExecutionDetected?: (execution: DirectExecution) => void;
+    /** direct_execution.updated */
+    onExecutionUpdated?: (execution: DirectExecution & {
+        previousStatus: ExecutionStatus | null;
+    }) => void;
+    /** direct_execution.succeeded */
+    onSuccess?: (execution: DirectExecution) => void;
+    /** direct_execution.failed + onramp_session.errored */
+    onError?: (error: OnrampSessionError) => void;
+    /** Fired whenever snapshot.status changes. */
+    onStatusChange?: (status: OnrampSessionStatus) => void;
+}
+interface UseOnrampResult {
+    status: OnrampSessionStatus;
+    /**
+     * Effective payer country driving quotes (host override or IP-detected;
+     * null until known).
+     */
+    countryCode: string | null;
+    /** Deposit addresses backing the purchase; empty until created. */
+    addresses: DepositAddress[];
+    /**
+     * Provider-side network/currency the fiat converts on; null until resolved,
+     * and briefly again while a `countryCode` change re-resolves the route.
+     */
+    destinationToken: OnrampDestinationToken | null;
+    /** Latest provider quotes, backend priority order. */
+    quotes: OnrampProviderQuote[];
+    /** Quote used by createCheckout() — quotes[0] unless selectQuote() was called. */
+    selectedQuote: OnrampProviderQuote | null;
+    /** False once the host picked a provider via selectQuote(). */
+    isQuoteAutoSelected: boolean;
+    /**
+     * True when there is more than one quote to pick between — gate your
+     * provider-picker UI on this. False under the project's fiat-onramp smart
+     * routing (backend collapses the list to one routed quote).
+     */
+    canSelectProvider: boolean;
+    isRefreshingQuotes: boolean;
+    /** Epoch ms of the last successful quote fetch — drive your own countdown. */
+    quotesUpdatedAt: number | null;
+    /** The active provider checkout; null until createCheckout(). */
+    checkout: OnrampCheckout | null;
+    /** All executions observed since checkout, newest first. */
+    executions: DirectExecution[];
+    latestExecution: DirectExecution | null;
+    /** True while the backend is actively scanning for the provider's transfer. */
+    isCheckingDeposit: boolean;
+    error: OnrampSessionError | null;
+    /** Start the session (relevant when autoStart: false, or to retry after error). */
+    start: () => Promise<void>;
+    /** Refetch quotes with the current request. */
+    refreshQuotes: () => Promise<void>;
+    /** Imperative alternative to the live sourceAmount/sourceCurrency options. */
+    updateQuoteRequest: (patch: Partial<OnrampQuoteRequest>) => void;
+    /** Pick a provider quote (sticky across refreshes). Returns it, or null when absent. */
+    selectQuote: (serviceProvider: string) => OnrampProviderQuote | null;
+    /**
+     * Build the provider checkout and start watching for settlement. Uses the
+     * selected quote, or a one-shot `options.serviceProvider` choice.
+     * Synchronous — call it in your click handler and `window.open(result.url)`
+     * to stay popup-blocker safe. Returns null while the session doesn't exist
+     * yet; throws when called before quotes are ready (gate on `status`).
+     */
+    createCheckout: (options?: {
+        serviceProvider?: string;
+        email?: string;
+        externalId?: string;
+    }) => OnrampCheckout | null;
+    /** Stop quote refresh and settlement watching. */
+    stop: () => void;
+    /** stop() + fresh run + start(). */
+    restart: () => Promise<void>;
+    /** Escape hatch to the underlying session (waiters, extra subscriptions). */
+    session: OnrampSession | null;
+}
+/**
+ * Headless fiat-onramp hook (buy with card by default) — the no-UI
+ * equivalent of `beginDeposit({ initialScreen: 'card' })`.
+ *
+ * Wraps a core {@link OnrampSession}: creates it, subscribes via
+ * `useSyncExternalStore`, destroys it on unmount, and exposes the snapshot,
+ * imperative controls, and callback sugar. The host renders 100% of the UI —
+ * amount input, provider list, checkout button, settlement progress.
+ *
+ * The quote inputs (`sourceAmount` / `destinationAmount` — provide exactly
+ * one — plus `sourceCurrency`, `countryCode`, `subdivisionCode`) are LIVE:
+ * changing them updates the running session (debounced) instead of tearing
+ * it down, so you can bind them straight to form state. Swapping which
+ * amount is provided switches the amount mode in place. Changing the flow
+ * identity (user, destination, payment method) creates a fresh session.
+ *
+ * SSR-safe: the session is constructed in an effect; server renders see
+ * `status: 'idle'` and empty arrays.
+ */
+declare function useOnramp(options: UseOnrampOptions): UseOnrampResult;
+
 interface UseDepositAddressesOptions {
     /** Host platform's stable user identifier (maps to external_user_id). */
     externalUserId: string | undefined;
@@ -215,4 +379,20 @@ interface AddressValidationResult {
  */
 declare function useAddressValidation(options: UseAddressValidationOptions): AddressValidationResult;
 
-export { type AddressValidationResult, type AllowedCountryResult, type UseAddressValidationOptions, type UseDepositAddressesOptions, type UseDepositDestination, type UseDepositOptions, type UseDepositResult, type UseExecutionsOptions, type UseSupportedDepositTokensOptions, useAddressValidation, useAllowedCountry, useDeposit, useDepositAddresses, useExecutions, useSupportedDepositTokens, useUnifoldClient };
+interface UseFiatCurrenciesOptions {
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Fiat currencies supported by the card onramp — for building custom
+ * currency pickers and amount screens next to {@link useOnramp}.
+ *
+ * Each {@link FiatCurrency} carries `minimum_amount` / `maximum_amount`
+ * (validate the user's amount host-side before quoting — the session only
+ * requires a parseable amount > 0), `default_amount`, `suggested_amounts`
+ * (quick-pick buttons), and `country_codes` (map your geo signal to a
+ * default currency). `data.preferred` lists currency codes to pin first.
+ */
+declare function useFiatCurrencies(options?: UseFiatCurrenciesOptions): _tanstack_react_query.UseQueryResult<FiatCurrenciesResponse, Error>;
+
+export { type AddressValidationResult, type AllowedCountryResult, type UseAddressValidationOptions, type UseDepositAddressesOptions, type UseDepositDestination, type UseDepositOptions, type UseDepositResult, type UseExecutionsOptions, type UseFiatCurrenciesOptions, type UseOnrampOptions, type UseOnrampResult, type UseSupportedDepositTokensOptions, useAddressValidation, useAllowedCountry, useDeposit, useDepositAddresses, useExecutions, useFiatCurrencies, useOnramp, useSupportedDepositTokens, useUnifoldClient };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { UnifoldConfig, UnifoldProvider, UnifoldProviderProps, useUnifold } from '@unifold/react-provider';
-import { UnifoldClient, ChainType, EvmContractCall, DepositMethod, DepositSessionEvent, DepositAddress, DirectExecution, ExecutionStatus, DepositSessionError, DepositSessionStatus, DepositSession, ActionType, ProductType, SupportedToken, AddressValidationFailureCode } from '@unifold/core';
-export { ActionType, ChainType, DepositAddress, DepositMethod, DepositSession, DepositSessionDestination, DepositSessionError, DepositSessionErrorCode, DepositSessionEvent, DepositSessionEventMap, DepositSessionEventType, DepositSessionParams, DepositSessionSnapshot, DepositSessionStatus, DepositSessionWaitError, DepositSessionWaitErrorCode, DepositSessionWaitOptions, DirectExecution, EvmContractCall, ExecutionStatus, SupportedChain, SupportedToken, UnifoldClient, UnifoldClientOptions, createUnifoldClient } from '@unifold/core';
+import { UnifoldClient, ChainType, EvmContractCall, DepositMethod, DepositSessionEvent, DepositAddress, DirectExecution, ExecutionStatus, DepositSessionError, DepositSessionStatus, DepositSession, OnrampSessionPaymentMethodType, OnrampSessionEvent, OnrampProviderQuote, OnrampSessionError, OnrampSessionStatus, OnrampDestinationToken, OnrampCheckout, OnrampQuoteRequest, OnrampSession, ActionType, ProductType, SupportedToken, AddressValidationFailureCode, FiatCurrenciesResponse } from '@unifold/core';
+export { ActionType, ChainType, DepositAddress, DepositMethod, DepositSession, DepositSessionDestination, DepositSessionError, DepositSessionErrorCode, DepositSessionEvent, DepositSessionEventMap, DepositSessionEventType, DepositSessionParams, DepositSessionSnapshot, DepositSessionStatus, DepositSessionWaitError, DepositSessionWaitErrorCode, DepositSessionWaitOptions, DirectExecution, EvmContractCall, ExecutionStatus, FiatCurrency, OnrampCheckout, OnrampDestinationToken, OnrampProviderQuote, OnrampQuoteRequest, OnrampSession, OnrampSessionError, OnrampSessionErrorCode, OnrampSessionEvent, OnrampSessionEventMap, OnrampSessionEventType, OnrampSessionParams, OnrampSessionPaymentMethodType, OnrampSessionSnapshot, OnrampSessionStatus, OnrampSessionWaitError, OnrampSessionWaitErrorCode, OnrampSessionWaitOptions, SupportedChain, SupportedToken, UnifoldClient, UnifoldClientOptions, createUnifoldClient } from '@unifold/core';
 import * as _tanstack_react_query from '@tanstack/react-query';
 
 /**
@@ -98,6 +98,170 @@ interface UseDepositResult {
  */
 declare function useDeposit(options: UseDepositOptions): UseDepositResult;
 
+interface UseOnrampOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    /** Destination — what the purchase converts into and where it lands. */
+    destination: UseDepositDestination;
+    /**
+     * ISO 3166-1 alpha-2 country of the payer. OPTIONAL — when omitted, the
+     * session auto-detects it from the user's IP during start ('US' fallback,
+     * modal parity). Provide it only to override detection with your own geo
+     * signal; live like the other quote inputs. The effective value is
+     * exposed as `countryCode` on the result.
+     */
+    countryCode?: string;
+    /** ISO 3166-2 subdivision (e.g. 'US-NY') when relevant for provider routing. */
+    subdivisionCode?: string;
+    /**
+     * Fiat amount to spend (fees included), as a decimal string. Live: changes
+     * refetch quotes (debounced). Provide exactly one of `sourceAmount` /
+     * `destinationAmount` — the amount mode.
+     */
+    sourceAmount?: string;
+    /**
+     * Fixed crypto (destination) amount to receive, with provider fees added
+     * on top — "receive 100 USDC". Live like `sourceAmount`, and mutually
+     * exclusive with it. Only providers that support fixed-destination quoting
+     * appear in `quotes`; each quote's `sourceAmount` is the fiat the user
+     * pays.
+     *
+     * Requires a stablecoin destination (`destinationToken.isStablecoin`) —
+     * the amount prices the provider-side currency, so it only means "receive
+     * 100 of the requested token" for stablecoins. Otherwise quoting stops
+     * with a non-fatal `DESTINATION_AMOUNT_UNSUPPORTED` error.
+     */
+    destinationAmount?: string;
+    /** ISO 4217 fiat currency code the user pays in. Live like `sourceAmount`. @default 'usd' */
+    sourceCurrency?: string;
+    /** Payment rail forwarded to the provider session. @default 'card' */
+    paymentMethodType?: OnrampSessionPaymentMethodType;
+    /** Prefill email forwarded to the provider checkout. */
+    email?: string;
+    /** Quote auto-refresh interval; 0 disables. @default 60000 */
+    quoteRefreshIntervalMs?: number;
+    /**
+     * Debounce applied when the live quote inputs (amount/currency/country)
+     * change between renders, so binding an input's value doesn't hit the
+     * quotes API per keystroke (parity with the modal's 500ms). @default 500
+     */
+    quoteDebounceMs?: number;
+    /**
+     * When true (default), start() is called automatically once externalUserId
+     * and the provider's publishable key are present. Set false to gate on
+     * your own UI.
+     */
+    autoStart?: boolean;
+    /** Every lifecycle event ('*' subscription) — analytics/debug fan-out. */
+    onEvent?: (event: OnrampSessionEvent) => void;
+    /** onramp_session.addresses_created */
+    onAddressesReady?: (addresses: DepositAddress[]) => void;
+    /** onramp_session.quotes_updated */
+    onQuotes?: (quotes: OnrampProviderQuote[], selectedQuote: OnrampProviderQuote | null) => void;
+    /** onramp_session.created (checkout built; host opens `url`) */
+    onCheckoutCreated?: (checkout: {
+        externalId: string;
+        url: string;
+        serviceProvider: string;
+    }) => void;
+    /** direct_execution.detected */
+    onExecutionDetected?: (execution: DirectExecution) => void;
+    /** direct_execution.updated */
+    onExecutionUpdated?: (execution: DirectExecution & {
+        previousStatus: ExecutionStatus | null;
+    }) => void;
+    /** direct_execution.succeeded */
+    onSuccess?: (execution: DirectExecution) => void;
+    /** direct_execution.failed + onramp_session.errored */
+    onError?: (error: OnrampSessionError) => void;
+    /** Fired whenever snapshot.status changes. */
+    onStatusChange?: (status: OnrampSessionStatus) => void;
+}
+interface UseOnrampResult {
+    status: OnrampSessionStatus;
+    /**
+     * Effective payer country driving quotes (host override or IP-detected;
+     * null until known).
+     */
+    countryCode: string | null;
+    /** Deposit addresses backing the purchase; empty until created. */
+    addresses: DepositAddress[];
+    /**
+     * Provider-side network/currency the fiat converts on; null until resolved,
+     * and briefly again while a `countryCode` change re-resolves the route.
+     */
+    destinationToken: OnrampDestinationToken | null;
+    /** Latest provider quotes, backend priority order. */
+    quotes: OnrampProviderQuote[];
+    /** Quote used by createCheckout() — quotes[0] unless selectQuote() was called. */
+    selectedQuote: OnrampProviderQuote | null;
+    /** False once the host picked a provider via selectQuote(). */
+    isQuoteAutoSelected: boolean;
+    /**
+     * True when there is more than one quote to pick between — gate your
+     * provider-picker UI on this. False under the project's fiat-onramp smart
+     * routing (backend collapses the list to one routed quote).
+     */
+    canSelectProvider: boolean;
+    isRefreshingQuotes: boolean;
+    /** Epoch ms of the last successful quote fetch — drive your own countdown. */
+    quotesUpdatedAt: number | null;
+    /** The active provider checkout; null until createCheckout(). */
+    checkout: OnrampCheckout | null;
+    /** All executions observed since checkout, newest first. */
+    executions: DirectExecution[];
+    latestExecution: DirectExecution | null;
+    /** True while the backend is actively scanning for the provider's transfer. */
+    isCheckingDeposit: boolean;
+    error: OnrampSessionError | null;
+    /** Start the session (relevant when autoStart: false, or to retry after error). */
+    start: () => Promise<void>;
+    /** Refetch quotes with the current request. */
+    refreshQuotes: () => Promise<void>;
+    /** Imperative alternative to the live sourceAmount/sourceCurrency options. */
+    updateQuoteRequest: (patch: Partial<OnrampQuoteRequest>) => void;
+    /** Pick a provider quote (sticky across refreshes). Returns it, or null when absent. */
+    selectQuote: (serviceProvider: string) => OnrampProviderQuote | null;
+    /**
+     * Build the provider checkout and start watching for settlement. Uses the
+     * selected quote, or a one-shot `options.serviceProvider` choice.
+     * Synchronous — call it in your click handler and `window.open(result.url)`
+     * to stay popup-blocker safe. Returns null while the session doesn't exist
+     * yet; throws when called before quotes are ready (gate on `status`).
+     */
+    createCheckout: (options?: {
+        serviceProvider?: string;
+        email?: string;
+        externalId?: string;
+    }) => OnrampCheckout | null;
+    /** Stop quote refresh and settlement watching. */
+    stop: () => void;
+    /** stop() + fresh run + start(). */
+    restart: () => Promise<void>;
+    /** Escape hatch to the underlying session (waiters, extra subscriptions). */
+    session: OnrampSession | null;
+}
+/**
+ * Headless fiat-onramp hook (buy with card by default) — the no-UI
+ * equivalent of `beginDeposit({ initialScreen: 'card' })`.
+ *
+ * Wraps a core {@link OnrampSession}: creates it, subscribes via
+ * `useSyncExternalStore`, destroys it on unmount, and exposes the snapshot,
+ * imperative controls, and callback sugar. The host renders 100% of the UI —
+ * amount input, provider list, checkout button, settlement progress.
+ *
+ * The quote inputs (`sourceAmount` / `destinationAmount` — provide exactly
+ * one — plus `sourceCurrency`, `countryCode`, `subdivisionCode`) are LIVE:
+ * changing them updates the running session (debounced) instead of tearing
+ * it down, so you can bind them straight to form state. Swapping which
+ * amount is provided switches the amount mode in place. Changing the flow
+ * identity (user, destination, payment method) creates a fresh session.
+ *
+ * SSR-safe: the session is constructed in an effect; server renders see
+ * `status: 'idle'` and empty arrays.
+ */
+declare function useOnramp(options: UseOnrampOptions): UseOnrampResult;
+
 interface UseDepositAddressesOptions {
     /** Host platform's stable user identifier (maps to external_user_id). */
     externalUserId: string | undefined;
@@ -215,4 +379,20 @@ interface AddressValidationResult {
  */
 declare function useAddressValidation(options: UseAddressValidationOptions): AddressValidationResult;
 
-export { type AddressValidationResult, type AllowedCountryResult, type UseAddressValidationOptions, type UseDepositAddressesOptions, type UseDepositDestination, type UseDepositOptions, type UseDepositResult, type UseExecutionsOptions, type UseSupportedDepositTokensOptions, useAddressValidation, useAllowedCountry, useDeposit, useDepositAddresses, useExecutions, useSupportedDepositTokens, useUnifoldClient };
+interface UseFiatCurrenciesOptions {
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Fiat currencies supported by the card onramp — for building custom
+ * currency pickers and amount screens next to {@link useOnramp}.
+ *
+ * Each {@link FiatCurrency} carries `minimum_amount` / `maximum_amount`
+ * (validate the user's amount host-side before quoting — the session only
+ * requires a parseable amount > 0), `default_amount`, `suggested_amounts`
+ * (quick-pick buttons), and `country_codes` (map your geo signal to a
+ * default currency). `data.preferred` lists currency codes to pin first.
+ */
+declare function useFiatCurrencies(options?: UseFiatCurrenciesOptions): _tanstack_react_query.UseQueryResult<FiatCurrenciesResponse, Error>;
+
+export { type AddressValidationResult, type AllowedCountryResult, type UseAddressValidationOptions, type UseDepositAddressesOptions, type UseDepositDestination, type UseDepositOptions, type UseDepositResult, type UseExecutionsOptions, type UseFiatCurrenciesOptions, type UseOnrampOptions, type UseOnrampResult, type UseSupportedDepositTokensOptions, useAddressValidation, useAllowedCountry, useDeposit, useDepositAddresses, useExecutions, useFiatCurrencies, useOnramp, useSupportedDepositTokens, useUnifoldClient };