@funkit/connect 9.19.0 → 9.20.0

package/dist/modals/CheckoutModal/FunCheckoutStep.d.ts

@@ -21,5 +21,6 @@ export declare enum FunCheckoutStep {
     CONNECT_EXCHANGE = "connect_exchange",
     BROKERAGE_TWO_FA = "brokerage_two_fa",
     BROKERAGE_SUCCESS = "brokerage_success",
-    SWAPPED_IFRAME = "swapped_iframe"
+    SWAPPED_IFRAME = "swapped_iframe",
+    PERPS_TRANSFER = "perps_transfer"
 }

package/dist/modals/CheckoutModal/InputAmount/QuickOptions.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
 export declare const USD_AMOUNT_OPTIONS_PCT: number[];
+export declare const BITCOIN_LIGHTNING_USD_AMOUNT_OPTIONS: number[];
 interface QuickOptionsProps {
     currency?: string;
     disabled?: boolean;

package/dist/modals/CheckoutModal/InputAmount/aaveClient.d.ts

@@ -1,5 +1,5 @@
 /**
- * Aave V3 client and constants for the native fast-path supply flow.
+ * Aave V3 client singleton for the native fast-path supply flow.
  *
  * The PoC uses `@aave/client` (V3 SDK) directly via its action functions, with
  * the viem adapter for signing. We don't mount `<AaveProvider>` because the
@@ -9,12 +9,8 @@
  * (`useAaveNativeSupply.ts`). It does NOT belong in `~/clients/` — that
  * directory is reserved for customer-specific code exported via the
  * `./clients/*` subpath; pulling Aave SDK setup in from there would bloat
- * the main bundle for every customer. As more callers appear (e.g. reserve
- * queries for confirmation-screen metadata), move this to a dedicated
- * `~/integrations/aave.ts` or similar — it's a third-party SDK integration
- * boundary, not a constant (singleton) and not domain logic.
+ * the main bundle for every customer. Pure Aave constants and predicates
+ * live in `~/domains/aave.ts` (importable without running SDK init).
  */
 import { AaveClient } from '@aave/client';
-import type { Address } from 'viem';
 export declare const aaveClient: AaveClient;
-export declare const AAVE_MARKET_ADDRESS_BY_CHAIN: Record<string, Address>;

package/dist/modals/CheckoutModal/InputAmount/state.d.ts

@@ -1,4 +1,5 @@
 import type { Dnum } from 'dnum';
+import type { Address } from 'viem';
 import { type PaymentMethodInfo } from '../../../domains/paymentMethods';
 import type { QuoteBuilder } from '../../../domains/quoteMode/types';
 import type { AssetHoldingsItem } from '../../../utils/assets';
@@ -139,6 +140,29 @@ export type AmountInputError = {
  * Return half the balance and round up to nearest 10, 100, 1000 etc
  */
 export declare function calcInitialFiatAmount(balance: number): number;
-export declare function initializeState({ checkoutConfig, defaultAmount, fiatCurrency, quoteBuilder, locale, maxUsd, minUsd, paymentMethodInfo, quickOptions, sourceHolding, unitPrice: realUnitPrice, meldEnabled, defaultAssetAmount, defaultIsInputInFiat, isNativeToken, gasPriceWei, gasUnits, }: AmountInputInitOptions): AmountInputState;
+/** Minimal source-token identity needed to resolve the default input mode. */
+export interface SourceTokenRef {
+    chainId: string;
+    address: Address;
+}
+/**
+ * Resolves whether the amount screen should open in fiat (`true`) or token
+ * (`false`) entry.
+ *
+ * Precedence: card and BTC Lightning payments always force fiat (ramps are
+ * fiat-denominated, and Lightning's amount input only supports fiat today).
+ * Lighter **spot** deposits paid with the same asset open in token entry —
+ * perps deposits (and every other customer) keep the legacy fiat default.
+ * Legacy behavior: token entry only for vault-style deposits (a finalized
+ * token set), fiat otherwise. A value preserved from prior navigation
+ * (`defaultIsInputInFiat`) is handled by the caller and wins over this.
+ */
+export declare function resolveDefaultIsInputInFiat({ checkoutConfig, paymentMethodInfo, sourceToken, apiKey, }: {
+    checkoutConfig: FunkitCheckoutConfig;
+    paymentMethodInfo: PaymentMethodInfo;
+    sourceToken: SourceTokenRef | null;
+    apiKey: string;
+}): boolean;
+export declare function initializeState({ checkoutConfig, defaultAmount, fiatCurrency, quoteBuilder, locale, maxUsd, minUsd, paymentMethodInfo, quickOptions, sourceHolding, unitPrice: realUnitPrice, meldEnabled, apiKey, defaultAssetAmount, defaultIsInputInFiat, isNativeToken, gasPriceWei, gasUnits, }: AmountInputInitOptions): AmountInputState;
 export declare function reduceState(state: AmountInputState, action: AmountInputAction): AmountInputState;
 export declare function getDerivedState(state: AmountInputState, targetAssetTicker: string): AmountInputDerivedState;

package/dist/modals/CheckoutModal/InputAmount/useAaveNativeSupply.d.ts

@@ -1,7 +1,7 @@
 /**
  * Native-supply fast-path: same-token same-chain deposits go straight to the
- * Aave Pool, bypassing Relay. `permitSupported` is exposed because the toggle
- * visibility gate is in `InputAmountLoaded`, not here.
+ * Aave Pool, bypassing Relay. Toggle visibility is gated centrally in
+ * `FunkitQuoteContext` (`showApprovalMethodToggle`), not here.
  */
 import { type ERC712Signature, type SupplyRequest } from '@aave/client';
 import type { ApiFunkitCheckoutConfig } from '@funkit/utils';
@@ -10,23 +10,6 @@ import { type Address, type Hex, type WalletClient } from 'viem';
 import { type CheckoutConfirmationError } from '../../../domains/checkoutErrors';
 import type { FunkitActiveCheckoutItem, FunkitCheckoutConfig } from '../../../providers/FunkitCheckoutContext';
 import { type Config } from '../../../wagmi/hooks';
-interface AaveNativeSupplyContextArgs {
-    apiKey: string;
-    sourceAsset: {
-        chainId: string | number;
-        address: string;
-    };
-    checkoutConfig: Pick<FunkitCheckoutConfig, 'targetChain' | 'targetAsset'>;
-}
-/**
- * True when the customer has the Aave native fast-path enabled, the
- * checkout's target chain has an Aave market configured (membership in
- * AAVE_MARKET_ADDRESS_BY_CHAIN is the single source of truth for "Aave
- * supported here"), and the source asset matches the target asset
- * (same chain, same token address). Decoupled from the hook so callers
- * can branch their UI before mounting the hook.
- */
-export declare function isAaveNativeSupplyContext({ apiKey, sourceAsset, checkoutConfig, }: AaveNativeSupplyContextArgs): boolean;
 /**
  * Stringify an amount for Aave's `bigDecimal()`. Prefers the precise
  * base-unit Dnum (carries the token's real decimals) so we don't ship

package/dist/modals/CheckoutModal/InputAmount/useCheckoutAmountLimits.d.ts

@@ -0,0 +1,17 @@
+import { PaymentMethod } from '../../../domains/paymentMethods';
+import type { FunkitCheckoutConfig } from '../../../providers/FunkitCheckoutContext';
+export interface CheckoutAmountLimitsUsd {
+    minUsd: number | undefined;
+    maxUsd: number;
+}
+/**
+ * Resolves the min/max USD bounds for the amount input based on the active
+ * payment method:
+ * - Bitcoin Lightning and brokerage checkouts carry their own floors/ceilings.
+ * - Everything else uses the customer-configured min deposit and the global
+ *   max-checkout dynamic config.
+ */
+export declare const useCheckoutAmountLimits: ({ checkoutConfig, paymentMethod, }: {
+    checkoutConfig: FunkitCheckoutConfig;
+    paymentMethod: PaymentMethod;
+}) => CheckoutAmountLimitsUsd;

package/dist/modals/CheckoutModal/SourceChange/SourceChange.d.ts

@@ -50,4 +50,4 @@ export type SourceChangeNext = {
     paymentMethodInfo: ConnectablePaymentMethodInfo;
 };
 export declare const SourceChangeInfo: ModalStepInfo<FunCheckoutStep.SOURCE_CHANGE>;
-export declare function SourceChange({ modalState, onClose, onNext, setModalState, }: ModalStepComponentProps<FunCheckoutStep.SOURCE_CHANGE>): React.JSX.Element;
+export declare function SourceChange({ modalState, onClose, onNext, onStepChange, setModalState, }: ModalStepComponentProps<FunCheckoutStep.SOURCE_CHANGE>): React.JSX.Element;

package/dist/modals/CheckoutModal/SourceChange/useSourceChangeLayout.d.ts

@@ -0,0 +1,10 @@
+import type { BoxProps } from '../../../components/Box/Box';
+/**
+ * Layout decisions shared between SourceChange and SourceChangeLoading so the
+ * loading skeleton can't drift from the loaded screen.
+ */
+export declare function useSourceChangeLayout(): {
+    isTargetAssetSelectable: boolean;
+    showContentDivider: boolean;
+    cryptoCashToggleMarginTop: BoxProps['marginTop'];
+};

package/dist/modals/CheckoutModal/stepTransition.d.ts

@@ -3,8 +3,9 @@ import { type BridgeCustomerNext, type BridgeCustomerState } from '../../modals/
 import { type BridgeKycNext, type BridgeKycState } from '../../modals/CheckoutModal/VirtualFiatAccount/BridgeKyc';
 import { type ErrorScreenState } from '../../modals/CheckoutModal/VirtualFiatAccount/ErrorScreen';
 import { type VirtualFiatAccountNext, type VirtualFiatAccountState } from '../../modals/CheckoutModal/VirtualFiatAccount/VirtualFiatAccount';
-import { FunCheckoutStartingStep, type FunkitActiveCheckoutItem } from '../../providers/FunkitCheckoutContext';
+import { type DynamicTargetAssetCandidate, FunCheckoutStartingStep, type FunkitActiveCheckoutItem } from '../../providers/FunkitCheckoutContext';
 import { type FunkitTextCustomizationsConfig } from '../../providers/FunkitConfigContext';
+import { type PerpsTransferNext, type PerpsTransferState } from '../PolymarketPerpsTransfer/PerpsTransferStep';
 import { type BrokerageSuccessState } from './Brokerage/BrokerageSuccessModal';
 import { type BrokerageTwoFANext, type BrokerageTwoFAState } from './Brokerage/BrokerageTwoFA';
 import { type ConnectExchangeNext, type ConnectExchangeState } from './Brokerage/ConnectExchange';
@@ -45,8 +46,31 @@ export interface ModalStepComponentProps<S extends FunCheckoutStep = FunCheckout
     }): void;
     onAnimationComplete(callback: () => void): void;
     onNext(payload: NextPayload<S>): void;
+    /** Navigate directly to an arbitrary step state (animates + pushes history). */
+    onStepChange(state: CheckoutModalState): void;
     setModalState(state: SetStateAction<CheckoutModalState<S>>): void;
 }
+/**
+ * Props passed to a `sourceChangeScreen.customTopComponent` so it can navigate
+ * the checkout modal (e.g. jump to a different step).
+ */
+export interface SourceChangeTopComponentProps {
+    onStepChange: (state: CheckoutModalState) => void;
+    modalState: CheckoutModalState;
+    /**
+     * The active checkout's routing id. Passed in (rather than read via
+     * `useCheckoutContext`) because a custom top component may be bundled
+     * separately from `@funkit/connect` (e.g. `@funkit/connect/clients/*`), where
+     * the checkout context is a different instance and would read as empty.
+     */
+    dynamicRoutingId?: string;
+    /**
+     * Apply a destination candidate (target token + routing id + optional
+     * recipient) in one atomic update — the same selection path the
+     * SourceChange target-asset dropdown uses.
+     */
+    applyDynamicTargetAssetCandidate: (candidate: DynamicTargetAssetCandidate) => void;
+}
 export declare function extractCommonState(state: CheckoutModalState): CheckoutModalCommonState;
 interface ModalStepInput<S extends FunCheckoutStep> {
     state: CheckoutModalState<S>;
@@ -98,6 +122,7 @@ export type CheckoutModalState<S extends FunCheckoutStep = FunCheckoutStep> = {
         [FunCheckoutStep.BROKERAGE_TWO_FA]: BrokerageTwoFAState;
         [FunCheckoutStep.BROKERAGE_SUCCESS]: BrokerageSuccessState;
         [FunCheckoutStep.SWAPPED_IFRAME]: SwappedIframeState;
+        [FunCheckoutStep.PERPS_TRANSFER]: PerpsTransferState;
     }[T] & {
         step: T;
         previousStep?: FunCheckoutStep | null;
@@ -127,6 +152,7 @@ export type NextPayload<S extends FunCheckoutStep = FunCheckoutStep> = {
     [FunCheckoutStep.BROKERAGE_TWO_FA]: BrokerageTwoFANext;
     [FunCheckoutStep.BROKERAGE_SUCCESS]: null;
     [FunCheckoutStep.SWAPPED_IFRAME]: SwappedIframeNext;
+    [FunCheckoutStep.PERPS_TRANSFER]: PerpsTransferNext;
 }[S] & {
     /** Whether screen transition should change direction to simulate back transition. Only applies if there is a history entry in the stack*/
     reverseAnimation?: boolean;

package/dist/modals/PolymarketPerpsTransfer/DirectionSwapButton.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export interface DirectionSwapButtonProps {
+    onClick: () => void;
+    testId?: string;
+}
+/**
+ * The control sitting between the two account rows. Pressing it swaps which
+ * account is the source: the top row is always the "From" account (the amount
+ * you send), so a swap just changes the labels on each row. The icon is a
+ * static downward arrow (matching the design) — it does not rotate on toggle.
+ *
+ * Styled per Figma as a 32px outlined circle: white surface with a 1px border
+ * (gray/100 → gray/200 on hover) and a faint hover/pressed fill. The Figma
+ * border vars map to the nearest funkit stroke tokens (mediumStroke ≈ #efefef,
+ * heavyStroke ≈ #ddd); the surface uses the icon-button background defaults.
+ */
+export declare function DirectionSwapButton({ onClick, testId, }: DirectionSwapButtonProps): React.JSX.Element;

package/dist/modals/PolymarketPerpsTransfer/PerpsTransferBottomBar.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { PerpsTransferForm } from './usePerpsTransferForm';
+/**
+ * The notice line + Transfer button under the transfer rows, rendered from
+ * {@link usePerpsTransferForm} state. The in-modal `PerpsTransferStep` portals
+ * this into the modal's bottom section; the standalone screen renders it in
+ * its `Dialog.BottomSection`.
+ */
+export declare function PerpsTransferBottomBar({ form }: {
+    form: PerpsTransferForm;
+}): React.JSX.Element;

package/dist/modals/PolymarketPerpsTransfer/PerpsTransferRows.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { PerpsTransferForm } from './usePerpsTransferForm';
+/**
+ * The From/To account rows with the direction-swap button between them —
+ * the body of the Perps ⇄ Predictions transfer screen, rendered from
+ * {@link usePerpsTransferForm} state.
+ */
+export declare function PerpsTransferRows({ form }: {
+    form: PerpsTransferForm;
+}): React.JSX.Element;

package/dist/modals/PolymarketPerpsTransfer/PerpsTransferStep.d.ts

@@ -0,0 +1,11 @@
+import type { FunCheckoutStep } from '../CheckoutModal/FunCheckoutStep';
+import type { CheckoutModalCommonState, ModalStepInfo } from '../CheckoutModal/stepTransition';
+/**
+ * Per-step state for the perps transfer screen. Balances are not carried in on
+ * navigation — the step reads them from the shared balance cache (see
+ * {@link usePolymarketAccountBalances}), the same cache the deposit picker
+ * populates, so there's no reload flash on entry.
+ */
+export type PerpsTransferState = CheckoutModalCommonState;
+export type PerpsTransferNext = null;
+export declare const PerpsTransferStepInfo: ModalStepInfo<FunCheckoutStep.PERPS_TRANSFER>;

package/dist/modals/PolymarketPerpsTransfer/PolymarketPerpsTransferScreen.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+export type PerpsTransferDirection = 'toPerps' | 'toPredictions';
+export type PerpsTransferStatus = 'idle' | 'processing' | 'success' | 'error';
+export interface PolymarketPerpsTransferScreenProps {
+    /** Whether the modal is open. Defaults to true (the screen owns its Dialog). */
+    open?: boolean;
+    /** Modal title. Defaults to the localized "Transfer". */
+    title?: string;
+    /** Predictions account balance in USD. */
+    predictionsBalanceUsd: number;
+    /** Perps account balance in USD. */
+    perpsBalanceUsd: number;
+    /** Minimum pUSD to transfer *into* predictions (USD). Drives the
+     * below-minimum notice when the destination is Predictions. */
+    predictionsMinTransferUsd?: number;
+    /** Minimum pUSD to transfer *into* perps (USD). Drives the below-minimum
+     * notice when the destination is Perps (e.g. perps' 10 pUSD minimum). */
+    perpsMinTransferUsd?: number;
+    /** Initial transfer direction. Defaults to Predictions → Perps. */
+    initialDirection?: PerpsTransferDirection;
+    /** Initial amount input string (pUSD). */
+    initialAmountUsd?: string;
+    /**
+     * Visual status, controlled by the host so the same screen renders the
+     * idle / processing / success / error frames. `error` shows a retry-able
+     * Transfer button with an error notice. No transfer logic is wired here — the
+     * Transfer button simply reports clicks via {@link onTransfer}.
+     */
+    status?: PerpsTransferStatus;
+    /**
+     * Fired when the (enabled) Transfer button is pressed, with the entered
+     * amount and direction — mirrors {@link usePerpsTransferForm}'s callback
+     * so a host receives everything it needs to perform the transfer.
+     */
+    onTransfer: (params: {
+        amountUsd: string;
+        direction: PerpsTransferDirection;
+    }) => void;
+    onClose?: () => void;
+    onBack?: () => void;
+}
+/**
+ * Polymarket "Transfer" screen — moves a balance between the Predictions and
+ * Perps accounts. Self-contained: it renders its own Dialog so it can be used
+ * standalone or in a Storybook story. The in-checkout-modal variant is the
+ * `PerpsTransferStep` (which renders the same UI via {@link usePerpsTransferForm}
+ * as a registered step instead of a Dialog).
+ *
+ * UI only: balances are props, and the Transfer button's processing/success
+ * states are driven by the {@link status} prop rather than any real transfer.
+ */
+export declare function PolymarketPerpsTransferScreen({ open, title, predictionsBalanceUsd, perpsBalanceUsd, predictionsMinTransferUsd, perpsMinTransferUsd, initialDirection, initialAmountUsd, status, onTransfer, onClose, onBack, }: PolymarketPerpsTransferScreenProps): React.JSX.Element;

package/dist/modals/PolymarketPerpsTransfer/TransferActionButton.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+import type { PerpsTransferStatus } from './PolymarketPerpsTransferScreen';
+export interface TransferActionButtonProps {
+    /** Drives the visual state and the label/icon swap. */
+    status: PerpsTransferStatus;
+    /** Label shown in the idle state (already translated). */
+    idleLabel: string;
+    /** Label shown while processing (already translated). */
+    processingLabel: string;
+    /** Label shown on success (already translated). */
+    successLabel: string;
+    /** Greys out / blocks the idle button until an amount is entered. */
+    isDisabled?: boolean;
+    onClick?: () => void;
+    testId?: string;
+}
+/**
+ * The bottom-bar transfer button. It morphs across the three flow states:
+ *
+ * - **idle**: primary (blue) "Transfer".
+ * - **processing**: dimmed blue, spinner + "Processing", inert.
+ * - **success**: secondary (grey) surface, green check + success label, inert.
+ *
+ * Two details keep the morph smooth:
+ *
+ * 1. Each state's content (icon + label) is a single absolutely-positioned,
+ *    centered layer, and we swap whole layers. Because every layer centres
+ *    itself, the label never shifts horizontally when the icon appears — the
+ *    transition is a pure vertical blur/fade (matching the From/To row swap).
+ * 2. The grey surface is the always-present base; the blue sits on top as an
+ *    overlay whose opacity only ever fades *out* toward success. Nothing
+ *    brightens mid-transition, so there's no blue "flush" as it turns grey.
+ */
+export declare function TransferActionButton({ status, idleLabel, processingLabel, successLabel, isDisabled, onClick, testId, }: TransferActionButtonProps): React.JSX.Element;

package/dist/modals/PolymarketPerpsTransfer/TransferAmountRow.css.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Borderless big-number amount field used inside the editable (source) row.
+ * The row's outer Box owns the border/background; this input is transparent so
+ * it reads as inline editable text.
+ *
+ * The 32px size matches the Figma amount type — there is no 32px token in the
+ * font scale, so it is set here. The family is the theme `body` font (same as
+ * the rest of the modal) — note the customer `header`/`inputAmount` tokens can
+ * resolve to `inherit`, so they must not be used here. The placeholder uses
+ * `secondaryText` to mirror the greyed-out empty "0.00" treatment in the design.
+ */
+export declare const amountInput: string;
+export declare const transferAmountRowContainer: string;

package/dist/modals/PolymarketPerpsTransfer/TransferAmountRow.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+export interface TransferAmountRowProps {
+    /** "From" / "To" prefix (already translated). */
+    relationLabel: string;
+    /** Account name, e.g. "Predictions" / "Perps". */
+    accountLabel: string;
+    /** Account balance in USD; rendered floored to the cent as "$X,XXX.XX". */
+    balanceUsd: number;
+    /**
+     * The source row is the editable side: it owns the input + Max button and
+     * gets the active border. The destination row mirrors the amount read-only
+     * and has no Max button.
+     */
+    isSource: boolean;
+    /** Controlled amount string (raw user input; may contain separators). */
+    amount: string;
+    onAmountChange?: (next: string) => void;
+    onMax?: () => void;
+    testId?: string;
+}
+/**
+ * A single From/To account row in the Perps ⇄ Predictions transfer screen.
+ * Top line shows the relation + account name, the account balance, and — on the
+ * source row — a Max button; the bottom line shows the (large) amount and, on
+ * the source row, the `pUSD` denomination.
+ */
+export declare function TransferAmountRow({ relationLabel, accountLabel, balanceUsd, isSource, amount, onAmountChange, onMax, testId, }: TransferAmountRowProps): React.JSX.Element;

package/dist/modals/PolymarketPerpsTransfer/usePerpsTransferForm.d.ts

@@ -0,0 +1,66 @@
+import type { PerpsTransferDirection, PerpsTransferStatus } from './PolymarketPerpsTransferScreen';
+/**
+ * pUSD has 6 on-chain decimals, so balances carry up to 6 decimal places. We
+ * render only the decimals actually present, up to 6: capping at 2 rounded
+ * `196.867461` *up* to `196.87`, so Max filled a value above the real balance
+ * and tripped the insufficient-balance guard. At 6 decimals the value is
+ * reproduced exactly. There is no minimum, so trailing zeros are trimmed —
+ * a `1.1` balance fills as `1.1`, not `1.100000` (or `1.10`).
+ *
+ * Not `formatCurrencyAndStringify` — that helper produces a 2-decimal `$`
+ * display string, while this fills the editable input with an exact,
+ * re-parsable pUSD amount.
+ */
+export declare function formatAmountValue(value: number): string;
+export interface PerpsTransferFormProps {
+    predictionsBalanceUsd: number;
+    perpsBalanceUsd: number;
+    /** Minimum pUSD to transfer *into* predictions (USD). */
+    predictionsMinTransferUsd?: number;
+    /** Minimum pUSD to transfer *into* perps (USD). */
+    perpsMinTransferUsd?: number;
+    initialDirection?: PerpsTransferDirection;
+    /** Initial amount input string (pUSD). */
+    initialAmountUsd?: string;
+    status?: PerpsTransferStatus;
+    onTransfer: (params: {
+        /** Exact string the user entered (validated numeric, ≤6 decimals). */
+        amountUsd: string;
+        direction: PerpsTransferDirection;
+    }) => void;
+}
+export interface PerpsTransferAccount {
+    /** Localized account name ("Predictions" / "Perps"). */
+    label: string;
+    balanceUsd: number;
+}
+/** Plain form state consumed by `PerpsTransferRows` and `PerpsTransferBottomBar`. */
+export interface PerpsTransferForm {
+    /** Raw amount input string (may contain separators). */
+    amount: string;
+    /** Validated setter — ignores input that isn't numeric with ≤6 decimals. */
+    setAmount: (next: string) => void;
+    /** Fills the amount with the source balance at full 6-decimal precision. */
+    fillMaxAmount: () => void;
+    swapDirection: () => void;
+    /** The editable "From" account. */
+    source: PerpsTransferAccount;
+    /** The read-only "To" account mirroring the source. */
+    destination: PerpsTransferAccount;
+    /** Validation/error notice line; `null` when nothing should be shown. */
+    noticeText: string | null;
+    /** Status for the action button (`error` is remapped to a retry-able idle). */
+    buttonStatus: PerpsTransferStatus;
+    isTransferDisabled: boolean;
+    /** Reports the entered amount + direction via the host's `onTransfer`. */
+    requestTransfer: () => void;
+}
+/**
+ * Owns the Perps ⇄ Predictions transfer form state — amount, direction, and
+ * the derived validation/notice/button values — so both the standalone
+ * {@link PolymarketPerpsTransferScreen} (Dialog) and the in-modal
+ * `PerpsTransferStep` (renders rows inline + portals the bottom bar) share
+ * identical behavior. Returns plain values; `PerpsTransferRows` and
+ * `PerpsTransferBottomBar` render them.
+ */
+export declare function usePerpsTransferForm({ predictionsBalanceUsd, perpsBalanceUsd, predictionsMinTransferUsd, perpsMinTransferUsd, initialDirection, initialAmountUsd, status, onTransfer, }: PerpsTransferFormProps): PerpsTransferForm;

package/dist/providers/FunkitCheckoutContext/index.d.ts

@@ -5,7 +5,7 @@ import { type PaymentMethodInfo } from '../../domains/paymentMethods';
 import type { AssetHoldingsItem } from '../../utils/assets';
 import type { WithdrawalClient, WithdrawalTransaction } from '../../wallets/Wallet';
 import { type FunkitCheckoutQuoteResult } from '../FunkitHistoryContext';
-import type { FunkitActiveCheckoutItem, FunkitActiveWithdrawalItem, FunkitCheckoutConfig, FunkitWithdrawalConfig, UseFunkitCheckoutProps, UseFunkitCheckoutPropsWithFullConfig } from './types';
+import type { DynamicTargetAssetCandidate, FunkitActiveCheckoutItem, FunkitActiveWithdrawalItem, FunkitCheckoutConfig, FunkitWithdrawalConfig, UseFunkitCheckoutProps, UseFunkitCheckoutPropsWithFullConfig } from './types';
 export * from './types';
 interface FunkitCheckoutContextInterface {
     checkoutItem: FunkitActiveCheckoutItem | null;
@@ -45,6 +45,15 @@ interface FunkitCheckoutContextInterface {
     resetForNewDeposit(): void;
     applyDynamicRouting(path: ApplyDynamicRoutingPath): void;
     updateDynamicRoutingId(dynamicRoutingId: string): void;
+    /**
+     * Apply a selected {@link DynamicTargetAssetCandidate} to the active checkout
+     * in one atomic update: target token fields, `dynamicRoutingId`, and (when the
+     * candidate carries one) `customRecipient`. The single source of truth for
+     * "select a destination candidate", shared by the SourceChange target-asset
+     * dropdown and customer account pickers (e.g. Polymarket) so neither has to
+     * re-sequence the individual setters.
+     */
+    applyDynamicTargetAssetCandidate(candidate: DynamicTargetAssetCandidate): void;
 }
 export type CheckoutProgressStep = 1 | 2;
 export type CheckoutProgress = {

package/dist/providers/FunkitCheckoutContext/types.d.ts

@@ -36,6 +36,14 @@ export interface DynamicTargetAssetCandidate extends TokenInfo {
      */
     finalizedTokenRate?: number;
     dynamicRoutingId?: string;
+    /**
+     * Recipient to point the checkout at when this candidate is selected. Set when
+     * candidates represent destination *accounts* that share a target token but
+     * differ by recipient (e.g. Polymarket Predictions vs Perps); selecting one
+     * routes funds to its address. Omit for plain token candidates (the recipient
+     * is unchanged).
+     */
+    customRecipient?: Address;
 }
 /**
  * A token to offer adding to the user's wallet (EIP-747 `wallet_watchAsset`) on
@@ -60,7 +68,48 @@ export interface AddToWalletToken extends TokenInfo {
 export declare enum FunCheckoutStartingStep {
     SOURCE_CHANGE = "source_change",
     CONFIRMATION = "confirmation",
-    SELECT_ASSET = "select_asset"
+    SELECT_ASSET = "select_asset",
+    /**
+     * Open directly on the Polymarket perps ⇄ predictions transfer step.
+     * Requires {@link FunkitCheckoutConfig.polymarketPerpsTransfer} handles
+     * (set by `createPolymarketDepositConfig`) — without them the step renders
+     * but cannot transfer.
+     */
+    PERPS_TRANSFER = "perps_transfer"
+}
+/** Token a Polymarket account can be topped up with. */
+export type PolymarketTopupToken = 'pUSD';
+/**
+ * A Polymarket account in the transfer step. Both accounts share the same shape
+ * so each direction is symmetrical and integrator-owned.
+ */
+export interface PolymarketTransferAccount {
+    /** Account address (the transfer target when funds move *into* it). */
+    address: Address;
+    /** Minimum amount (USD) to top this account up with `token` (0 = none). */
+    getMinTopupAmount: (token: PolymarketTopupToken) => number;
+    /**
+     * Transfers funds *from* this account to `toAddress`. Implemented by the
+     * integrator (keeps their perps API auth in-house); the SDK invokes the
+     * source account's transfer when the user confirms. `amountUsd` is the exact
+     * string the user entered (validated numeric, ≤6 decimals) — never a parsed
+     * number — so no float precision is lost before the integrator scales it.
+     */
+    transfer: (params: {
+        toAddress: Address;
+        amountUsd: string;
+    }) => Promise<void>;
+    /**
+     * Fetches this account's live balance (USD). The transfer step polls this so
+     * the displayed balances reconcile with the real on-chain / perps-API state
+     * after a transfer (optimistic updates alone go stale). Integrator-owned.
+     */
+    getBalanceUsd: () => Promise<number>;
+}
+/** The two accounts the perps transfer step moves funds between. */
+export interface PolymarketPerpsTransferHandles {
+    predictions: PolymarketTransferAccount;
+    perps: PolymarketTransferAccount;
 }
 export interface FunkitCheckoutConfig extends Omit<ApiFunkitCheckoutConfig, 'generateActionsParams' | 'customRecipient' | 'modalTitle' | 'iconSrc' | 'modalTitleMeta'> {
     /** List of contract action params **/
@@ -116,11 +165,22 @@ export interface FunkitCheckoutConfig extends Omit<ApiFunkitCheckoutConfig, 'gen
      ********************************/
     /** a list of candidate assets to be chosen dynamically */
     dynamicTargetAssetCandidates?: DynamicTargetAssetCandidate[];
-    /** minimal USD needed to deposit */
-    getMinDepositUSD?: (asset: TokenInfo) => number;
+    /**
+     * Minimal USD needed to deposit. Receives the active `dynamicRoutingId` (like
+     * {@link modalTitle}) so the minimum can vary by route when two routes share a
+     * target token (e.g. Polymarket predictions vs perps).
+     */
+    getMinDepositUSD?: (asset: ModalTitleContext) => number;
     /** For Checkout with Custom Action, QRCode needs special action type
      * to specify the onchain action to execute after deposit */
     qrcodeActionType?: string;
+    /**
+     * Polymarket-specific handles for the perps ⇄ predictions transfer step. Set
+     * by `createPolymarketDepositConfig` and read by the perps transfer step.
+     * Lets Polymarket keep their perps API auth in-house (they implement the
+     * withdrawal) instead of handing the SDK an API key.
+     */
+    polymarketPerpsTransfer?: PolymarketPerpsTransferHandles;
     /** set this if you want enable vault like deposit*/
     finalizedToken?: DynamicTargetAssetCandidate;
     /**

package/dist/providers/FunkitConfigContext.d.ts

@@ -1,6 +1,7 @@
 import { type ComponentType, type JSX, type ReactNode } from 'react';
 import type { BluvoExchangeType } from '../consts/bluvo';
 import type { PaymentMethod } from '../domains/paymentMethods';
+import type { SourceChangeTopComponentProps } from '../modals/CheckoutModal/stepTransition';
 export interface FunkitTextCustomizationsConfig {
     virtualFiat: string;
     brokerageOrExchange: string;
@@ -8,6 +9,7 @@ export interface FunkitTextCustomizationsConfig {
     accountBalance: string;
     selectAccount: string;
     sourceChangeTitle?: string;
+    perpsTransferTitle: string;
     sourceMethodTitle: string;
     tokensListTitle: string;
     transferTokens: string;
@@ -195,8 +197,17 @@ export interface FunkitUiCustomizationsConfig {
         showWalletOnInsufficientBalance?: boolean;
         /** Whether to show the wallet connect payment option - defaults to true */
         showWalletConnect?: boolean;
-        /** Function that returns a custom React component to render before other UIs in the source change screen */
-        customTopComponent?: () => ReactNode;
+        /**
+         * Renders custom content before other UIs in the source change screen.
+         * Receives modal navigation handles so it can jump to another step (e.g.
+         * open a transfer step). Existing zero-arg components remain valid.
+         */
+        customTopComponent?: (props?: SourceChangeTopComponentProps) => ReactNode;
+        /**
+         * Render a full-width divider beneath {@link customTopComponent} (matching
+         * the target-asset selector divider). Defaults to false.
+         */
+        showCustomTopComponentDivider?: boolean;
         paymentMethodIcons?: {
             primary?: FunkitPaymentMethodIconsConfig;
             /** Custom secondary icon or "value icon" in the context of FunPaymentMethodItem */

package/dist/providers/FunkitQuoteContext.d.ts

@@ -63,6 +63,22 @@ interface FunkitQuoteContextInterface extends CheckoutQuoteState {
     targetAssetPoolAllowance: bigint | undefined;
     setTargetAssetPoolAllowance: (value: bigint | undefined) => void;
 }
+/**
+ * Shared preconditions (wallet-executed account-balance flows only), then a
+ * per-flow gate. Aave native supply is capability-gated: EIP-2612 support
+ * (`undefined` = still loading → show optimistically, `false` = hide) and no
+ * covering Pool allowance — never the feature flag (ENG-4070). The Relay
+ * flow's source-side Permit2-vs-approve choice stays behind the
+ * `enable-permit-toggle` Statsig rollout gate.
+ */
+export declare function shouldShowApprovalMethodToggle({ isPermitToggleGateOn, isDirectExecution, isAccountBalancePayment, isAaveNativeSupplyFlow, targetAssetSupportsPermit, targetAssetAllowanceCoversAmount, }: {
+    isPermitToggleGateOn: boolean;
+    isDirectExecution: boolean;
+    isAccountBalancePayment: boolean;
+    isAaveNativeSupplyFlow: boolean;
+    targetAssetSupportsPermit: boolean | undefined;
+    targetAssetAllowanceCoversAmount: boolean;
+}): boolean;
 export declare function FunkitQuoteProvider({ children }: {
     children: ReactNode;
 }): React.JSX.Element;