Components

This reference is verified against the published @spicenet-io/spiceflow-ui package by tools/check-sdk-drift.mjs on every change. If a component or prop below is wrong, that check fails.

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		Chain where Spice Account deposits originate
`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
`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	`[]`	Chain IDs to skip in the flow
`appName`	`string`	No	`"Spicenet"`	Your application name
`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. This is the primary component most apps will use.

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 gasless execution, driven by a buildActionCalls callback that returns your destination-chain calls. This is the highest-leverage component for a “fund then act” flow (live production integrations build their pay and supply surfaces on it), and it is far less code than wiring useSpiceExecution by hand.

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.userAddress) },
];

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

buildActionCalls takes (amount, ctx) in that order. ctx (BuildActionCallsContext) carries userAddress, chainId, destinationToken, and the fee fields. Read the current prop and context shapes from the installed package (SpiceSupplyProps, BuildActionCallsContext).

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	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	Override the Spicenet-side delivery batch

SpiceLock

Lock tokens for a duration (veToken style), with cross-chain deposits into the lock. 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="veTOKEN"
  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[]`	Yes	On-chain lock calls
`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`	No	Success callback
`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. See SpiceLockModalProps in the installed package for the full, current shape.

AccountDisplay

A popover that shows the user’s Spice balance breakdown, pending deposits, and quick actions for deposit/withdraw. Great for header navigation.

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		Token price overrides
`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

SpiceWithdraw

Usage

Props

SpiceLock

Usage

Props

AccountDisplay

Usage

Props

SelectChainModal

ProviderLogin

Usage

Props

Next Steps

Hooks

Styling

Configuration

Examples

​SpiceFlowProvider

​Usage

​Props

​Examples

​SpiceDeposit

​Usage

​Props

​depositBatches

​SpiceSupply

​Usage

​SpiceWithdraw

​Usage

​Props

​SpiceLock

​Usage

​Props

​AccountDisplay

​Usage

​Props

​SelectChainModal

​ProviderLogin

​Usage

​Props

​Next Steps

Hooks

Styling

Configuration

Examples

SpiceFlowProvider

Usage

Props

Examples

SpiceDeposit

Usage

Props

depositBatches

SpiceSupply

Usage

SpiceWithdraw

Usage

Props

SpiceLock

Usage

Props

AccountDisplay

Usage

Props

SelectChainModal

ProviderLogin

Usage

Props

Next Steps