Components

This reference is verified against the published @spicenet-io/spiceflow-ui package by tools/check-sdk-drift.mjs on every change. The check verifies export and prop names; examples and behavioral guidance target stable SDK 4.10.0.

SpiceFlowProvider

The root provider for chain configuration, theming, and execution mode. It reads wallet state from Privy, wagmi, and react-query — mount those above it in your app (see Quick Start Step 2).

Usage

import { SpiceFlowProvider } from "@spicenet-io/spiceflow-ui";

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
  theme={{ primaryColor: "#f97316", dark: true }}
>
  {children}
</SpiceFlowProvider>

Props

Prop	Type	Required	Default	Description
`provider`	`"privy"`	No	`"privy"`	Wallet provider. Privy is the only provider in the current release
`children`	`ReactNode`	Yes		Your application components
`network`	`"mainnet" \| "testnet"`	No	`"testnet"`	Network environment. Set this explicitly: leaving it default sends submissions to testnet
`nativeChainId`	`number`	No		Your app’s chain. Deposits are delivered here unless a component sets `destinationChainId`, and External-mode deposits ask the wallet to be on it
`theme`	`SpiceTheme`	No		Branding and theme config (see Styling)
`privyAppId`	`string`	No		No effect — set `appId` on your own `PrivyProvider`
`supportedChainIds`	`number[]`	No	Per network	Override supported chain IDs
`allowedTokens`	`string[]`	No		Restrict the token list by lowercase symbol, e.g. `["usdc", "eth"]`
`mode`	`"7702" \| "presign" \| "ondemand"`	No	`"7702"`	Execution mode. `"presign"` behaves exactly like `"ondemand"`
`whitelist`	`SpiceFlowWhitelistOptions \| false`	No		Gate the flow to whitelisted wallets. When a user is not whitelisted the SDK forces `ondemand` mode and blanks the allowed tokens
`rpcOverrides`	`Record<number, string>`	No		Per-chain RPC URL overrides
`skipFlow`	`number[]`	No	`[]`	No effect
`appName`	`string`	No		No effect. Set `theme.appName` instead
`apiUrl`	`string`	No		Override the relayer API URL
`embeddedWalletConfig`	`{ createOnLogin?: "off" \| "users-without-wallets" \| "all-users" }`	No		No effect — set `embeddedWallets` in the `PrivyProvider` config
`swapper`	`{ enabled?: boolean; integratorId?: string }`	No	off	Card and exchange deposit sources in `SpiceDeposit`, opt-in. See Card and Exchange Deposits

Examples

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
  theme={{ primaryColor: "#f97316", dark: true }}
>
  {children}
</SpiceFlowProvider>

<SpiceFlowProvider
  provider="privy"
  mode="ondemand"
  network="mainnet"
  nativeChainId={8453}
>
  {children}
</SpiceFlowProvider>

SpiceDeposit

The main deposit flow. Handles everything: Privy login, external wallet connection, token selection, escrow deposit, 7702 signing, and solver execution. Use SpiceSupply for a protocol action; this component handles account deposits.

Usage

import { SpiceDeposit } from "@spicenet-io/spiceflow-ui";

<SpiceDeposit
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  depositBatches={batches}
  styles={{ primaryColor: "#f97316" }}
/>

Props

Prop	Type	Required	Default	Description
`isOpen`	`boolean`	Yes		Control modal visibility
`onClose`	`() => void`	Yes		Close handler
`styles`	`CustomStyles`	No		Custom styling
`depositBatches`	`ChainBatch[] \| ((ctx: PostDepositContext) => Promise<ChainBatch[]>) \| ((amount, token) => Promise<ChainBatch[]>)`	No		Destination chain calls to execute after deposit
`onDepositAmountChange`	`(amount: string) => void`	No		Fires when the user changes the deposit amount
`destinationChainId`	`number`	No		Target chain for execution
`destinationTokenAddress`	`string`	No		Target token on the destination chain
`onDepositExecute`	`(amount: string) => Promise<void>`	No		Callback for non-7702 mode (app handles execution)
`depositActionLabel`	`string`	No		Custom label for the action button
`sponsorGas`	`boolean`	No	`false`	Backend sponsors gas
`skipTokenSelection`	`boolean`	No	`false`	Skip the token selection step
`skipRecovery`	`boolean`	No	`false`	Skip the stranded-funds recovery prompt
`escrowRecovery`	`EscrowRecovery`	No		Recover funds stuck in escrow
`onDepositSuccess`	`(detail) => void`	No		Success callback. `detail.type` is `"deposit"` for an escrow deposit, or `"wallet-funding"` when a card or exchange deposit landed in an external wallet
`onDepositError`	`(error) => void`	No		Error callback

To restrict which tokens appear, set allowedTokens on SpiceFlowProvider (lowercase symbols), not on SpiceDeposit.

With swapper={{ enabled: true }} on SpiceFlowProvider, the modal opens with a Wallet / Card / Exchange chooser so users can fund by debit card or from an exchange. Off by default. See Card and Exchange Deposits for where the funds land in each wallet mode.

depositBatches

The depositBatches prop defines what happens on the destination chain after the deposit. It can be a static array or an async function that returns batches based on the deposit amount:

// Static batches
const batches = [
  {
    chainId: 8453,
    calls: [
      { to: TOKEN, value: 0n, data: encodeApprove(VAULT, amount) },
      { to: VAULT, value: 0n, data: encodeDeposit(TOKEN, amount) },
    ],
  },
];

// Dynamic batches (computed from deposit amount)
const dynamicBatches = async (amount: string, tokenAddress: string) => {
  const parsedAmount = parseUnits(amount, 6);
  return [
    {
      chainId: 8453,
      calls: [
        { to: tokenAddress, value: 0n, data: encodeApprove(VAULT, parsedAmount) },
        { to: VAULT, value: 0n, data: encodeDeposit(tokenAddress, parsedAmount) },
      ],
    },
  ];
};

SpiceSupply

Runs a deposit / supply / stake action end to end: token selection, funding, fee quoting, and execution, driven by a buildActionCalls callback that returns your destination-chain calls. This is the stock presentation of useSpiceSupply. Keep your existing UI with that controller when a stock modal does not fit. See Custom UI Integration.

Usage

import { SpiceSupply, type BuildActionCallsContext, type Call } from "@spicenet-io/spiceflow-ui";

const buildActionCalls = (amount: bigint, ctx: BuildActionCallsContext): Call[] => [
  { to: ctx.destinationToken, value: 0n, data: encodeApprove(PROTOCOL, amount) },
  { to: PROTOCOL, value: 0n, data: encodeSupply(ctx.destinationToken, amount, ctx.beneficiary ?? ctx.userAddress) },
];

<SpiceSupply
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  actionLabel="Supply"
  destinationToken={{ chainId: 8453, address: TOKEN }}
  buildActionCalls={buildActionCalls}
  styles={{ primaryColor: "#f97316" }}
/>

buildActionCalls takes (amount, ctx) in that order. ctx (BuildActionCallsContext) carries userAddress, executorAddress, beneficiary, chainId, destinationToken, and fee fields. The bigint is in destination-token units; honor it after swaps and fee allocation. Read the current prop and context shapes from the installed package (SpiceSupplyProps, BuildActionCallsContext).

Routes paid from the user’s Spice balance need a Spicenet funding batch in front of the destination batch. The SDK builds it automatically. buildSpicenetBatch and feeExecutionMode are deprecated compatibility props; leave them unset in new integrations. Existing values remain supported.

Props

Prop	Type	Required	Default	Description
`isOpen`	`boolean`	Yes		Modal visibility
`onClose`	`() => void`	Yes		Close handler
`actionLabel`	`string`	Yes		Submit button label
`destinationToken`	`DestinationTokenDeclaration`	Yes		Chain/address; metadata resolves automatically
`buildActionCalls`	`(amount, ctx) => Call[] \| Promise<Call[]>`	Yes		Destination contract calls
`amountDirection`	`"input" \| "input-inclusive" \| "output"`	No	`"input"`	Principal plus fees, total budget, or fixed destination amount
`paymentAmount`	`string`	For output mode		Fixed destination amount
`recipient`	`Address`	No		Intended protocol beneficiary
`sourceChains`	`number[]`	No	Provider chains	Restrict source chains
`supportedSourceAssets`	`string[]`	No		Restrict by symbol, address or `native`
`onSubmit`	`() => void`	No		Accepted submission before prompts
`onSuccess`	`(hash: string) => void \| Promise<void>`	No		Awaited application updates
`onError`	`(error, detail?) => void`	No		Error handler
`feeOnlyAction`	`boolean`	No	`false`	Existing principal; SDK funds only execution fees
`styles`	`CustomStyles`	No	Provider theme	Presentation overrides

onPayExecute blocks execution until migrated. Define the calls with buildActionCalls and use onSuccess for app updates. See Migration for direct versus routed execution.

SpiceWithdraw

Withdraw assets from the user’s Spice balance back to their wallet.

Usage

import { SpiceWithdraw } from "@spicenet-io/spiceflow-ui";

<SpiceWithdraw
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  styles={{ primaryColor: "#f97316" }}
/>

Props

Prop	Type	Required	Default	Description
`isOpen`	`boolean`	Yes		Control modal visibility
`onClose`	`() => void`	Yes		Close handler
`styles`	`CustomStyles`	No		Custom styling
`onWithdrawExecute`	`(amount: string) => Promise<void>`	No		Callback for non-7702 mode
`onWithdrawSuccess`	`(data: { token, amount, chainId }) => void`	No		Success callback
`onWithdrawError`	`(error: string, detail?) => void`	No		Error callback
`availableTokens`	`Record<number, DestinationToken[]>`	No		Restrict withdrawable tokens, keyed by chain ID
`buildSpicenetBatch`	`(params) => ChainBatch \| null`	No	`buildSpicenetWithdrawalBatch`	Override the Spicenet-side delivery batch

SpiceLock

Lock tokens for a duration (veToken style), using the shared input-inclusive Supply controller. The amount and duration inputs are driven by hooks you create with useAssetInput and useLockDuration and pass in, so you can read the live selection for your own preview UI.

Usage

import { SpiceLock } from "@spicenet-io/spiceflow-ui";

<SpiceLock
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  lockBatches={lockBatches}
  lockTokenSymbol="TOKEN"
  destinationTokenAddress={TOKEN}
  lockChainId={4114}
  durationOptions={[
    { label: "1 Month", months: 1 },
    { label: "3 Months", months: 3 },
    { label: "6 Months", months: 6 },
    { label: "12 Months", months: 12 },
  ]}
  styles={{ primaryColor: "#f97316" }}
/>

Props

Prop	Type	Required	Description
`isOpen`	`boolean`	Yes	Modal visibility
`onClose`	`() => void`	Yes	Close handler
`lockBatches`	`ChainBatch[] \| ((ctx: LockBatchContext) => ChainBatch[])`	Yes	Destination-only calls using fee-adjusted `amountWei`
`lockTokenSymbol`	`string`	Yes	Display symbol for the lock token
`lockChainId`	`number`	Yes	Chain where the lock contract lives
`durationOptions`	`LockDurationOption[]`	Yes	Available lock durations
`styles`	`CustomStyles`	No	Custom styling
`dark`	`boolean`	No	Dark mode override
`lockTokenLogoURI`	`string`	No	Logo URL for the lock token
`votingPowerEstimate`	`(amount, months) => number`	No	Estimate voting power from amount and duration
`sourceToDestinationConversionRate`	`number`	No	Conversion rate display
`onLockSuccess`	`(txHash?: string) => void \| Promise<void>`	No	Awaited application updates
`beneficiary`	`Address`	No	Intended position owner
`onSubmit`	`() => void`	No	Accepted submission before prompts
`onAddFunds`	`() => void`	No	Handler for “add funds”
`destinationTokenAddress`	`Address`	No	Target token on the lock chain

SpiceLock also accepts hoistable input hooks (sourceAssetInputHook, lockDurationHook) and escrowAddress. The builder receives destination-token amountWei, beneficiary and executorAddress; the SDK supplies conversion and delivery. onLockExecute blocks execution until moved into the builder and success callback. See SpiceLockModalProps for the full shape.

SpiceAccount

Composes AccountDisplay, SpiceDeposit and SpiceWithdraw, including open/close state and the selected withdrawal asset. It has zero required props inside the provider stack.

import { SpiceAccount } from "@spicenet-io/spiceflow-ui";

<SpiceAccount />

Optional depositProps and withdrawProps customize the nested flows without their visibility props. It also accepts the display’s branding, extra assets, token prices and mode-toggle props, but owns onDepositClick / onWithdrawClick itself. Keep AccountDisplay if your app needs to own those modals.

AccountDisplay

A popover for wallet and Spice balances and deposit/withdraw actions. It uses shared inventory and policy. extraAssets can add metadata or undiscovered positions but cannot override an SDK-acquired balance, including zero. Host tokenPrices are display-only fallbacks, not execution prices.

Usage

import { AccountDisplay } from "@spicenet-io/spiceflow-ui";

<AccountDisplay
  styles={{ primaryColor: "#f97316" }}
  onDepositClick={() => setDepositOpen(true)}
  onWithdrawClick={() => setWithdrawOpen(true)}
/>

Props

Prop	Type	Required	Default	Description
`styles`	`CustomStyles`	No		Custom styling
`dark`	`boolean`	No		Dark mode override
`appName`	`string`	No	`"Spice"`	Display name
`status`	`"active" \| "inactive"`	No	`"active"`	Account status indicator
`statusLabel`	`string`	No		Custom status text
`onDepositClick`	`() => void`	No		Deposit button handler
`onWithdrawClick`	`() => void`	No		Withdraw button handler
`onDepositSuccess`	`() => void`	No		Called after a successful deposit
`customSections`	`CustomSection[]`	No		Add custom sections to the popover
`extraAssets`	`SpiceAsset[]`	No		Additional assets to display (e.g. the app’s own positions)
`tokenPrices`	`Record<string, number>`	No		Display prices for tokens without an SDK price, keyed by `chainId:lowercaseAddress`
`showModeToggle`	`boolean`	No		Show the Embedded / External mode toggle
`defaultMode`	`"7702" \| "non7702"`	No		Initial mode for the toggle

SelectChainModal

The source-chain picker on its own, for when you want the chain-selection step outside the full deposit flow. See SelectChainModal in the installed package for its current props.

import { SelectChainModal } from "@spicenet-io/spiceflow-ui";

ProviderLogin

Wallet connection button for the configured provider (Privy).

Usage

import { ProviderLogin } from "@spicenet-io/spiceflow-ui";

<ProviderLogin onAuthSuccess={() => console.log("Logged in")} />

Props

Prop	Type	Required	Description
`onAuthSuccess`	`() => void`	No	Callback after successful authentication
`autoTrigger`	`boolean`	No	Automatically trigger login on mount

Next Steps

Hooks

Build custom UIs with React hooks

Styling

Customize component appearance

Configuration

Configure chains and providers

Examples

See complete examples

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

SpiceFlowProvider

Usage

Props

Examples

SpiceDeposit

Usage

Props

depositBatches

SpiceSupply

Usage

Props

SpiceWithdraw

Usage

Props

SpiceLock

Usage

Props

SpiceAccount

AccountDisplay

Usage

Props

SelectChainModal

ProviderLogin

Usage

Props

Next Steps

Hooks

Styling

Configuration

Examples

​SpiceFlowProvider

​Usage

​Props

​Examples

​SpiceDeposit

​Usage

​Props

​depositBatches

​SpiceSupply

​Usage

​Props

​SpiceWithdraw

​Usage

​Props

​SpiceLock

​Usage

​Props

​SpiceAccount

​AccountDisplay

​Usage

​Props

​SelectChainModal

​ProviderLogin

​Usage

​Props

​Next Steps

Hooks

Styling

Configuration

Examples

SpiceFlowProvider

Usage

Props

Examples

SpiceDeposit

Usage

Props

depositBatches

SpiceSupply

Usage

Props

SpiceWithdraw

Usage

Props

SpiceLock

Usage

Props

SpiceAccount

AccountDisplay

Usage

Props

SelectChainModal

ProviderLogin

Usage

Props

Next Steps