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:
Step 3: Add a Protocol Action
UseSpiceSupply 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)
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:
- Privy: Sign up at privy.io and create an app
How It Works
- The user connects their wallet and selects a source asset and amount.
- The SDK quotes funding, any swaps and fees; the UI enables submission when the plan is ready.
- 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.
- The SDK reports completion after the required transaction steps, then awaits application work in
onSuccessif provided.
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
- Check that your provider credentials are correct in
.env.local - Check the browser console for any error messages
Need More Help?
Join our Discord
Get help from the community and our team
