Custom UI Integration

Use this guide when you want your own UI — asset selector, amount input, buttons, status — and the SDK only as the execution engine. This is the pattern our live production integrations use. The prebuilt modals (SpiceSupply, SpiceDeposit) package this same pipeline; use them instead if you want less code. The pattern, per market:

Describe the market’s token as a destinationToken.
Write one buildActionCalls function returning the market’s on chain calls (approve + supply).
useSupplyAssets lists every asset the user can fund it with, across all supported chains.
useSupplyQuote resolves routing (swap needed or direct) for the selected source asset.
estimateFeePreview produces the fee quote — surface it before enabling the submit button.
executeSupply runs the whole flow: funding, routing, delegation signing, solver execution.

The user never bridges and never needs gas on the source chain — the Spicenet solver executes via EIP 7702 and covers gas on the routing legs, accounted for in the fee quote. If your app already sponsors gas on the destination chain (e.g. Privy gas sponsorship on Base), keep it: it applies to your app’s own transactions and needs no SDK configuration.

Provider Setup

SpiceFlowProvider does not mount Privy, wagmi, or react-query — it reads wallet state from those contexts. Your app mounts all four, in this order:

import "@spicenet-io/spiceflow-ui/styles.css"; // required once, at app entry

import type { ReactNode } from "react";
import { WagmiProvider, createConfig, http } from "wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { PrivyProvider } from "@privy-io/react-auth";
import { SpiceFlowProvider } from "@spicenet-io/spiceflow-ui";
import { getMainnetChains } from "@spicenet-io/spiceflow-core";
import { defineChain, type Chain } from "viem";

// Every chain the installed SDK supports; new chains arrive with SDK upgrades.
const chains = getMainnetChains().map((c): Chain =>
  defineChain({
    id: c.id,
    name: c.displayName,
    nativeCurrency: c.nativeCurrency,
    rpcUrls: { default: { http: [c.rpcUrl] } },
    blockExplorers: { default: { name: "Explorer", url: c.blockExplorer } },
  }),
) as [Chain, ...Chain[]];

const wagmiConfig = createConfig({
  chains,
  transports: Object.fromEntries(chains.map((c) => [c.id, http()])),
});

const queryClient = new QueryClient();

export function Providers({ children }: { children: ReactNode }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <PrivyProvider
          appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!}
          config={{
            supportedChains: [...chains],
            embeddedWallets: { ethereum: { createOnLogin: "all-users" } },
          }}
        >
          {/* supportedChainIds omitted: SpiceFlowProvider defaults to every supported chain */}
          <SpiceFlowProvider provider="privy" network="mainnet" nativeChainId={8453}>
            {children}
          </SpiceFlowProvider>
        </PrivyProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

One chains array feeds wagmi, Privy, and the SDK, so the three stay consistent by construction. If you restrict to specific chains instead, keep all three in sync — a chain missing from the PrivyProvider config fails at wallet-client creation with “Chain X is not configured in PrivyProvider”. If you already run Privy, reuse your existing PrivyProvider — just add the source chains you enable. For production, put your own RPC URLs in the wagmi transports — the bare http() falls back to each chain’s public endpoint, which rate-limits under real traffic.

The styles.css import is required even with a fully custom UI — the Privy login modal renders unstyled (invisible) without it. On Vite, also polyfill Node’s Buffer global before the SDK loads; cross-chain swap quoting references it at runtime.

Complete Example

A supply panel for one market. Verified against @spicenet-io/spiceflow-ui@4.7.9.

"use client";

import { useRef, useState } from "react";
import { type Address } from "viem";
import {
  useWallet,
  useSpiceExecution,
  useSupplyAssets,
  useSupplyQuote,
  buildSupplyChainBatches,
  buildPayChainBatches,
  estimateFeePreview,
  executeSupply,
  type Asset,
  type BatchBuilderContext,
  type BuildActionCallsContext,
  type Call,
  type ExecutorContext,
  type SupplyStep,
  type SupplyQuoteResult,
} from "@spicenet-io/spiceflow-ui";

const destinationToken = {
  chainId: 8453,
  address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as Address, // USDC on Base
  symbol: "USDC",
  decimals: 6,
};

// One function per market: the destination chain calls to run once funds arrive.
// ctx.userAddress is the wallet the action runs as.
const buildActionCalls = (amount: bigint, ctx: BuildActionCallsContext): Call[] => [
  { to: destinationToken.address, value: 0n, data: encodeApprove(MARKET, amount) },
  { to: MARKET, value: 0n, data: encodeSupply(destinationToken.address, amount, ctx.userAddress) },
];

export function SupplyPanel() {
  const { address, isReady, isAuthenticated, isConnected, provider } = useWallet();
  const { execute, estimate } = useSpiceExecution();

  // Every asset the user can fund this market with, across all chains
  const { displayAssets, embeddedWalletAddress, externalAddress, isNon7702 } =
    useSupplyAssets({ address, destinationToken, enabled: true });

  const [selected, setSelected] = useState<Asset | null>(null);
  const [amount, setAmount] = useState("");
  const [step, setStep] = useState<SupplyStep>("idle");
  const [error, setError] = useState<string | null>(null);
  const [statusMsg, setStatusMsg] = useState("");
  const [txHash, setTxHash] = useState<string | null>(null);
  const [isExecuting, setIsExecuting] = useState(false);
  const [, setShowStatusPanel] = useState(false);
  const [, setPaymentResult] = useState<any>(null);
  const submittedRef = useRef(false);
  const abortRef = useRef<AbortController | null>(null);

  const selectedAsset = selected ? { asset: selected, amount } : null;

  // Routing quote: does the chosen source asset need a swap into the destination token?
  const quote: SupplyQuoteResult = useSupplyQuote({
    direction: "input",
    selectedAsset,
    destinationToken,
    chainId: destinationToken.chainId,
    recipient: embeddedWalletAddress ?? address,
    paymentAmount: amount,
  });

  // The token the execution is funded in on the destination chain
  const executionTokenAddress: Address =
    quote.needsSwap && quote.resolvedTokenIn
      ? quote.resolvedTokenIn
      : selected && selected.chainId === destinationToken.chainId
        ? selected.address
        : (quote.resolvedTokenIn ?? destinationToken.address);

  const isSourceDestToken =
    !!selected &&
    selected.address.toLowerCase() === destinationToken.address.toLowerCase() &&
    selected.chainId === destinationToken.chainId;

  const supply = async () => {
    if (!selectedAsset) return;

    const batchCtx: BatchBuilderContext = {
      currentPaymentAmount: amount,
      destinationToken,
      embeddedWalletAddress,
      providerEmbeddedAddress: embeddedWalletAddress,
      externalWalletAddress: externalAddress,
      address,
      isNon7702,
      isPayMode: false,
      resolvedChainId: destinationToken.chainId,
      buildActionCalls,
      feeExecutionMode: "backend-transfer",
      buildSpicenetBatch: undefined,
      selectedAsset,
      needsSwap: quote.needsSwap,
      resolvedSwap: quote.resolvedSwap,
      exactOutputSwap: quote.exactOutputSwap,
      quoteAmountOut: quote.quoteAmountOut,
      resolvedTokenIn: quote.resolvedTokenIn,
      requestTimestampMs: Date.now(),
    };
    const buildSupply = (opts?: Parameters<typeof buildSupplyChainBatches>[1]) =>
      buildSupplyChainBatches(batchCtx, opts);
    const buildPay = (opts?: Parameters<typeof buildPayChainBatches>[1]) =>
      buildPayChainBatches(batchCtx, opts);

    const parsedAmount = parseFloat(amount) || 0;

    // Fee quote. In production, run this when the amount settles and show it
    // before enabling the submit button.
    const feeQuote = await estimateFeePreview({
      selectedAsset,
      isPayMode: false,
      parsedAmount,
      needsSwap: quote.needsSwap,
      exactOutputSwap: quote.exactOutputSwap,
      isNon7702,
      isSourceDestToken,
      currentPaymentAmount: amount,
      destinationToken,
      feeExecutionMode: "backend-transfer",
      resolvedTokenIn: quote.resolvedTokenIn,
      embeddedWalletAddress,
      providerEmbeddedAddress: embeddedWalletAddress,
      resolvedChainId: destinationToken.chainId,
      isConnected,
      address,
      ready: isReady,
      authenticated: isAuthenticated,
      isDirect: quote.isDirect,
      resolvedSwap: quote.resolvedSwap,
      isQuoting: quote.isQuoting,
      executionTokenAddress,
      buildPayChainBatches: buildPay,
      buildSupplyChainBatches: buildSupply,
      estimate,
    });

    const ctx: ExecutorContext = {
      selectedAsset,
      parsedAmount,
      currentPaymentAmount: amount,
      isInsufficientBalance: parsedAmount > (selected?.balanceFormatted ?? 0),
      isPayMode: false,
      isNon7702,
      isSourceDestToken,
      needsSwap: quote.needsSwap,
      exactOutputSwap: quote.exactOutputSwap,
      selectedIsEquivalent: quote.selectedIsEquivalent,
      resolvedTokenIn: quote.resolvedTokenIn,
      embeddedWalletAddress,
      providerEmbeddedAddress: embeddedWalletAddress,
      externalWallet: null,
      externalWalletAddress: externalAddress,
      address,
      isConnected,
      ready: isReady,
      authenticated: isAuthenticated,
      provider,
      resolvedChainId: destinationToken.chainId,
      executionTokenAddress,
      feeQuote,
      execution: {
        estimate,
        execute,
        buildPayChainBatches: buildPay,
        buildSupplyChainBatches: buildSupply,
        onProgress: (p) => setStatusMsg(p.message),
      },
      ui: {
        setError,
        setStep,
        setStatusMsg,
        setTxHash,
        setIsExecuting,
        setShowStatusPanel,
        setPaymentResult,
      },
      refs: {
        spiceDepositSubmittedRef: submittedRef,
        abortControllerRef: abortRef,
      },
      destinationToken,
      buildActionCalls,
      feeExecutionMode: "backend-transfer",
      buildSpicenetBatch: undefined,
      onPayExecute: undefined,
      onSuccess: (hash) => console.log("supplied", hash),
    };

    await executeSupply(ctx);
  };

  return (
    <div>
      {displayAssets.map((a) => (
        <button key={`${a.chainId}-${a.address}`} onClick={() => setSelected(a)}>
          {a.symbol} on chain {a.chainId}: {a.balanceFormatted}
        </button>
      ))}
      <input value={amount} onChange={(e) => setAmount(e.target.value)} />
      <button onClick={supply} disabled={isExecuting || !selected}>
        {step === "success" ? "Done" : "Supply"}
      </button>
      {statusMsg && <p>{statusMsg}</p>}
      {error && <p>{error}</p>}
      {txHash && <p>{txHash}</p>}
    </div>
  );
}

Everything above the JSX is wiring; the JSX is yours to replace entirely.

Scaling to All Markets

Only two things vary per market: destinationToken and buildActionCalls. Wrap the panel in a component that takes those as props (or a market config object) and every market gets any-asset, any-chain funding with the same code path.

Withdrawals

SpiceWithdraw handles withdrawing Spice balances back to a wallet on any supported chain. To build your own withdraw UI instead, use useSpiceAssets for balances and useSpiceExecution for execution — see Hooks.

Testing

Set network="testnet" on SpiceFlowProvider (and swap the wagmi/Privy chain set to the testnet chains) to run the identical flow against testnet infrastructure. Testnet funds for supported tokens come from the airdrop endpoint. Move to network="mainnet" only after the full supply → withdraw loop passes on testnet.

Notes

feeExecutionMode: "backend-transfer" lets the backend collect fees from the funded amount; the fee quote’s netAmount is what reaches the market.
executeSupply drives your state through the ui setters — render step, statusMsg, and error however you like. Steps: idle → signing-delegation → signing-intent → submitting → executing → success | error.
Supported chains come from the SDK per network — see Configuration. Restrict with supportedChainIds or sourceChains on useSupplyAssets.

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

Custom UI Integration

Provider Setup

Complete Example

Scaling to All Markets

Withdrawals

Testing

Notes

​Provider Setup

​Complete Example

​Scaling to All Markets

​Withdrawals

​Testing

​Notes

Provider Setup

Complete Example

Scaling to All Markets

Withdrawals

Testing

Notes