Hooks

These hooks let you build custom UIs on top of the Spice Flow SDK. If the prebuilt components don’t fit your use case, use these hooks to access wallet state, balances, and execution directly.

useSpiceExecution

The core execution hook. Handles EIP 7702 delegation signing, intent submission, and solver execution polling. This is what powers SpiceDeposit under the hood.

Usage

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

function CustomDeposit() {
  const { execute, estimate, clearStatus } = useSpiceExecution();

  const handleExecute = async () => {
    const actionId = await execute(
      chainBatches,           // destination chain calls
      tokenAddress,           // token being deposited
      tokenTransferAmount,    // amount in wei
      (progress) => {         // progress callback
        console.log(progress.step, progress.message);
      },
    );
    console.log("Action completed:", actionId);
  };

  return <button onClick={handleExecute}>Execute</button>;
}

Return Value

The hook returns execute (not executeGasless), plus fee estimation, status, and a status reset:

{
  execute: (
    chainBatches: ChainBatch[],
    tokenAddress: string,
    tokenTransferAmount: bigint,
    onProgress?: (progress: ExecutionProgress) => void,
    signal?: AbortSignal,
    options?: ExecutionOptions,
  ) => Promise<string>;         // returns actionId
  estimate: (chainBatches: ChainBatch[], tokenAddress: string, amount: bigint) => Promise<FeeEstimate>;
  lastFeeEstimate: FeeEstimate | null;
  hasEmbeddedWallet: boolean;
  intentStatus: unknown;
  clearStatus: () => void;      // call between sequential executions (there is no reset())
}

The SDK holds its own concurrency lock and throws on an overlapping execute call, so you do not need a module-level mutex. For multi-step flows, call clearStatus() between executions.

Progress Steps

The onProgress callback receives updates as execution proceeds:

Step	Description
`idle`	Not started
`building`	Building the intent
`signing-delegation`	User signing EIP 7702 delegation
`signing-intent`	User signing the intent hash
`submitting`	Submitting to the solver
`executing`	Solver executing on chain
`confirming-rollup`	Confirming settlement on the Spicenet rollup
`success`	Execution complete
`error`	Something went wrong

useSpiceAssets

Fetch the user’s Spice balance from the relayer API. This returns the off chain balance (what the user has deposited via escrow), not on chain wallet balances.

Usage

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

function BalanceDisplay() {
  const { assets, loading, hasBalance, refetch, getAssetsByChain } = useSpiceAssets({
    address: "0x...",
    supportedChains: [8453, 4114],
    refetchInterval: 30000,
  });

  if (loading) return <p>Loading...</p>;
  if (!hasBalance) return <p>No deposits yet</p>;

  return (
    <ul>
      {assets.map(asset => (
        <li key={`${asset.chainId}-${asset.address}`}>
          {asset.symbol}: {asset.balanceFormatted} on chain {asset.chainId}
        </li>
      ))}
    </ul>
  );
}

Config

Param	Type	Default	Description
`address`	`string`		Wallet address to query
`supportedChains`	`number[]`		Filter to specific chains
`enabled`	`boolean`	`true`	Enable or disable fetching
`refetchInterval`	`number`		Auto refetch interval in ms

Return Value

Field	Type	Description
`assets`	`Asset[]`	Array of deposited assets with balances
`loading`	`boolean`	True during initial load
`error`	`string \| null`	Error message if fetch failed
`hasBalance`	`boolean`	Whether user has any balance
`refetch`	`() => Promise<void>`	Manually refetch balances
`getAssetsByChain`	`(chainId) => Asset[]`	Filter assets by chain

useSupplyAssets

Lists every asset the user can fund a given destination token with — wallet balances and Spice balances, across all supported chains. This is the source-selection half of a custom supply UI (see the Custom UI Integration guide for the full flow).

Usage

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

const { displayAssets, embeddedWalletAddress, externalAddress, isNon7702 } = useSupplyAssets({
  address,                       // user wallet address
  destinationToken: { chainId: 8453, address: USDC, symbol: "USDC", decimals: 6 },
  sourceChains: [1, 8453, 42161], // optional: restrict source chains
  supportedSourceAssets: ["usdc", "eth"], // optional: restrict by symbol
  enabled: true,
});

Return Value

Field	Type	Description
`displayAssets`	`(Asset & { _source: "wallet" \| "spice" })[]`	Fundable assets across chains, tagged by source
`filteredSpiceAssets`	`Asset[]`	Spice balance assets only
`walletAssets`	`Asset[]`	Wallet balance assets only
`embeddedWalletAddress`	`0x${string}` \| undefined	The user’s embedded wallet
`externalAddress`	`0x${string}` \| undefined	The user’s external wallet
`isNon7702`	`boolean`	True when running without an embedded 7702 wallet
`refreshSpiceAssets`	`() => Promise<void>`	Refetch Spice balances
`refreshWalletAssets`	`() => void`	Refetch wallet balances

useSupplyQuote

Resolves routing for a selected source asset: whether it funds the destination token directly or needs a swap, and the quote for it. Feed its output into buildSupplyChainBatches / estimateFeePreview — see Custom UI Integration.

Usage

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

const quote = useSupplyQuote({
  direction: "input",            // amount is what the user pays ("output": what the market receives)
  selectedAsset,                 // { asset, amount } or null
  destinationToken,
  chainId: destinationToken.chainId,
  recipient: embeddedWalletAddress,
  paymentAmount: amount,
});

Return Value

Field	Type	Description
`isQuoting`	`boolean`	Quote in flight
`quoteError`	`string \| null`	Quote failure
`estimatedOutput`	`string \| null`	Destination amount for `direction: "input"`
`estimatedInput`	`string \| null`	Source amount for `direction: "output"`
`needsSwap`	`boolean`	Source asset must be swapped into the destination token
`isDirect`	`boolean`	Direct funding, no swap
`resolvedSwap`	`ResolvedSwap \| null`	The resolved routing swap
`exactOutputSwap`	`ResolvedExactOutputSwap \| null`	Exact-output variant when quoting by output
`quoteAmountOut`	`bigint \| null`	Raw quoted output amount
`resolvedTokenIn`	`Address \| null`	The destination-chain token the funding arrives in
`selectedIsEquivalent`	`boolean`	Source is the same asset as the destination token on another chain

useWallet

Access wallet connection state and signing actions for the configured provider (Privy).

Usage

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

function WalletInfo() {
  const { address, isConnected, isAuthenticated, provider, actions } = useWallet();

  if (!isConnected) return <p>Not connected</p>;

  return (
    <div>
      <p>Connected via {provider}: {address}</p>
      <button onClick={() => actions.signMessage("Hello")}>Sign Message</button>
    </div>
  );
}

Return Value

Field	Type	Description
`isReady`	`boolean`	Provider is initialized
`isAuthenticated`	`boolean`	User has authenticated
`isConnected`	`boolean`	Wallet is connected
`address`	`Address \| undefined`	Connected wallet address
`provider`	`"privy" \| null`	Active provider
`actions.signMessage`	`(message) => Promise<{signature}>`	Sign a message
`actions.signAuthorization`	`(params) => Promise<Authorization>`	Sign EIP 7702 authorization

Getting the embedded wallet address

There is no standalone useEmbeddedWalletAddress hook. In 7702 mode the embedded wallet is the on-chain identity; read its address from useWallet() or from the provider context:

import { useContext } from "react";
import { useWallet, SpiceFlowProviderContext } from "@spicenet-io/spiceflow-ui";

function EmbeddedWallet() {
  const ctx = useContext(SpiceFlowProviderContext);
  const embeddedAddress = ctx?.embeddedWalletAddress;

  if (!embeddedAddress) return <p>No embedded wallet</p>;
  return <p>Embedded: {embeddedAddress}</p>;
}

useAssetInput

Manage asset selection and amount input state. Used to control the asset selector in deposit and lock flows from your own UI.

Usage

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

function CustomInput() {
  const { selectedAsset, setSelectedAsset, assetAmount, setAssetAmount } = useAssetInput();

  return (
    <input
      type="text"
      value={assetAmount}
      onChange={(e) => setAssetAmount(e.target.value)}
      placeholder="Amount"
    />
  );
}

Return Value

Field	Type	Description
`selectedAsset`	`SelectedAsset \| null`	Currently selected asset
`setSelectedAsset`	`(asset) => void`	Set the selected asset
`assetAmount`	`string`	Current amount string
`setAssetAmount`	`(amount) => void`	Set the amount

useLockDuration

Manage lock duration selection state for SpiceLock.

Usage

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

const durationOptions = [
  { label: "1 Month", months: 1 },
  { label: "6 Months", months: 6 },
  { label: "12 Months", months: 12 },
];

function DurationPicker() {
  const { selectedDurationIdx, setSelectedDurationIdx, selectedDuration } = useLockDuration(durationOptions);

  return (
    <div>
      {durationOptions.map((opt, i) => (
        <button key={i} onClick={() => setSelectedDurationIdx(i)}>
          {opt.label} {i === selectedDurationIdx ? "(selected)" : ""}
        </button>
      ))}
    </div>
  );
}

useSpicePendingDeposits

Detect funds stranded in the user’s embedded wallet (deposits that were sent but not yet credited to Spice balance). Used by SpiceDeposit internally for recovery flows.

Usage

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

function PendingCheck() {
  const { pendingDeposits } = useSpicePendingDeposits({
    chainIds: [8453, 4114],
  });

  if (pendingDeposits.length > 0) {
    return <p>You have {pendingDeposits.length} pending deposit(s) to recover.</p>;
  }
  return null;
}

useSpiceBrand

Resolve the current theme from the provider’s theme prop and any component-level styles/dark overrides. Only used when building custom components that need to match the SDK’s look.

Usage

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

function CustomCard({ styles, dark }) {
  const { primaryColor, dk, palette } = useSpiceBrand(styles, dark);

  return (
    <div style={{
      backgroundColor: palette.cardBg,
      color: palette.textPrimary,
      border: `1px solid ${palette.cardBorder}`,
    }}>
      Themed card
    </div>
  );
}

Return Value

Field	Type	Description
`dark`	`boolean`	Whether dark mode is active
`primaryColor`	`string`	Brand accent color
`theme`	`Theme`	Full theme object
`dk`	`ResolvedDarkPalette`	Dark palette values
`palette`	`ResolvedDarkPalette`	Mode resolved palette (light or dark)

Next Steps

Components

Use prebuilt components for common flows

Styling

Customize appearance with the brand system

API Reference

Explore the REST API for advanced use cases

Configuration

Configure chains and providers

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

useSpiceExecution

Usage

Return Value

Progress Steps

useSpiceAssets

Usage

Config

Return Value

useSupplyAssets

Usage

Return Value

useSupplyQuote

Usage

Return Value

useWallet

Usage

Return Value

Getting the embedded wallet address

useAssetInput

Usage

Return Value

useLockDuration

Usage

useSpicePendingDeposits

Usage

useSpiceBrand

Usage

Return Value

Next Steps

Components

Styling

API Reference

Configuration

​useSpiceExecution

​Usage

​Return Value

​Progress Steps

​useSpiceAssets

​Usage

​Config

​Return Value

​useSupplyAssets

​Usage

​Return Value

​useSupplyQuote

​Usage

​Return Value

​useWallet

​Usage

​Return Value

​Getting the embedded wallet address

​useAssetInput

​Usage

​Return Value

​useLockDuration

​Usage

​useSpicePendingDeposits

​Usage

​useSpiceBrand

​Usage

​Return Value

​Next Steps

Components

Styling

API Reference

Configuration

useSpiceExecution

Usage

Return Value

Progress Steps

useSpiceAssets

Usage

Config

Return Value

useSupplyAssets

Usage

Return Value

useSupplyQuote

Usage

Return Value

useWallet

Usage

Return Value

Getting the embedded wallet address

useAssetInput

Usage

Return Value

useLockDuration

Usage

useSpicePendingDeposits

Usage

useSpiceBrand

Usage

Return Value

Next Steps