Skip to main content

Overview

This guide walks you through adding Spice Flow to your app. By the end, your users will be able to fund protocol actions across supported chains without manually managing bridges. This guide targets stable SDK 4.10.0. What you’ll build:
  • A wallet connection flow (embedded + external wallet)
  • A deposit interface that accepts any token from any supported chain
  • Cross chain execution powered by EIP 7702

Step 1: Installation

Install the Spice Flow UI SDK and Privy for wallet management:

Step 2: Setup Providers

SpiceFlowProvider reads wallet state from Privy, wagmi, and react-query — your app mounts all four providers, in this order:
Get your Privy App ID from privy.io — it goes on PrivyProvider. This setup enables every chain the SDK supports; to restrict, pass explicit chains to wagmi, Privy, and supportedChainIds, keeping the three in sync. See Configuration.

Step 3: Add a Protocol Action

Use SpiceSupply for a vault deposit, supply or payment. Define destination calls once; the SDK owns source selection, routing, fees and execution. This ERC-4626 example accepts your vault address as a prop; the vault must use Base USDC as its underlying asset.
amount is a raw bigint in destination-token units. The SDK resolves the token’s symbol and decimals. The default amountDirection="input" adds fees to the entered principal; choose "input-inclusive" for a total spending budget or "output" with paymentAmount for a fixed payment.

Step 4: Add Account Controls (Optional)

This composes the account display and its deposit/withdraw modals with no required component props. SpiceDeposit adds funds to Spice balance; SpiceWithdraw takes Spice balance back to a wallet. They are distinct from depositing into, or withdrawing from, your protocol’s position. Keep AccountDisplay if your app already owns those modals. For your own presentation, use the same action controller through Custom UI Integration. Existing integrations should read Migration to 4.10.0.

Environment Setup

Create a .env.local file in your project root:
Get your credentials:
  • Privy: Sign up at privy.io and create an app

How It Works

  1. The user connects their wallet and selects a source asset and amount.
  2. The SDK quotes funding, any swaps and fees; the UI enables submission when the plan is ready.
  3. A matching-token external action on the destination chain executes directly from that wallet. Routed external sources fund the embedded wallet, then the SDK coordinates cross-chain delivery and destination calls.
  4. The SDK reports completion after the required transaction steps, then awaits application work in onSuccess if provided.
Source transfers and direct wallet transactions can require native gas. Routed execution fees are shown in the SDK quote. Your app defines the protocol calls and intended beneficiary, while the SDK handles the funding and execution path.

What’s Next?

Components

Explore all available components and their props

Hooks

Build custom UIs with React hooks

Styling

Customize the appearance to match your brand

Configuration

Configure chains, providers, and execution modes

Troubleshooting

”Window is not defined” Error

If you see this in Next.js, ensure you’re using the "use client" directive:

“usePrivy must be used within PrivyProvider” (or a wagmi context error)

The provider stack from Step 2 isn’t mounted above the component. SpiceFlowProvider alone is not enough — WagmiProvider, QueryClientProvider, and PrivyProvider must wrap it.

Wallet Not Connecting

  1. Check that your provider credentials are correct in .env.local
  2. Check the browser console for any error messages

Need More Help?

Join our Discord

Get help from the community and our team