Skip to main content

​
Overview

This guide will walk you through building a basic cross-chain swap interface using the Spice Flow SDK. You’ll have a working application where users can swap assets across different chains without bridging. What you’ll build:
  • A wallet connection button
  • A swap interface supporting multiple chains
  • Cross-chain transaction execution

​
Step 1: Installation

Install the Spice Flow SDK and your preferred wallet provider: 
npm install @spicenet-io/spiceflow @privy-io/react-auth

​
Step 2: Setup Provider

Create a new component and wrap it with SpiceFlowProvider: 
"use client"; // For Next.js App Router

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

function App() {
  return (
    <SpiceFlowProvider
      provider="privy"
      privyAppId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
    >
      {/* Your app components will go here */}
    </SpiceFlowProvider>
  );
}

export default App;
Get your Privy App ID from privy.io. You can also use Dynamic or Para as your wallet provider.

​
Step 3: Add Wallet Connection

Import and add the ProviderLogin component: 
import { SpiceFlowProvider, ProviderLogin } from "@spicenet-io/spiceflow";

function App() {
  return (
    <SpiceFlowProvider
      provider="privy"
      privyAppId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
    >
      <div style={{ padding: "20px" }}>
        <ProviderLogin />
      </div>
    </SpiceFlowProvider>
  );
}

​
Step 4: Add the Swap Widget

Add the SwapWidget component to enable cross-chain swaps: 
import { 
  SpiceFlowProvider, 
  ProviderLogin, 
  SwapWidget 
} from "@spicenet-io/spiceflow";

function App() {
  return (
    <SpiceFlowProvider
      provider="privy"
      privyAppId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
    >
      <div style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        gap: "20px",
        padding: "40px"
      }}>
        <ProviderLogin />
        <SwapWidget 
          swapBatches={your_swap_calls_array_here} 
          supportedChains={[11155111, 1551]} // Sepolia + Citrea Testnet
        />
      </div>
    </SpiceFlowProvider>
  );
}

export default App;

​
Complete Example

Here’s a complete Next.js example: 
"use client";

import { 
  SpiceFlowProvider, 
  SwapWidget, 
  ProviderLogin 
} from "@spicenet-io/spiceflow";

function WalletComponent() {
  // Required for Next.js SSR compatibility
  if (typeof window === 'undefined') {
    return <div>Loading...</div>;
  }

  return (
    <SpiceFlowProvider
      provider="privy"
      privyAppId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
    >
      <div style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        justifyContent: "center",
        height: "90vh",
        gap: "20px",
      }}>
        <h1>My Cross-Chain Swap App</h1>
        <ProviderLogin />
        <SwapWidget 
          swapBatches={your_swap_calls_array_here} 
          supportedChains={[11155111, 1551]}
        />
      </div>
    </SpiceFlowProvider>
  );
}

export default function Home() {
  return <WalletComponent />;
}

​
Environment Setup

Create a .env.local file in your project root: 
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here
Get your credentials:
  • Privy: Sign up at privy.io and create an app
  • Dynamic: Sign up at dynamic.xyz and get your environment ID
  • Para: Sign up at getpara.com and get your API key

​
Test Your App

  1. Start your development server: 
    npm run dev
  2. Open your browser to http://localhost:3000
  3. Connect your wallet using the login button
  4. Try a swap using the swap widget
Congratulations! You’ve built your first Spice Flow app. Users can now swap assets across chains without bridging.

​
What’s Next?

Components

Explore all available components and their props

Hooks

Build custom UIs with React hooks

Native Swap Example

Build a complete swap application with custom logic

Styling

Customize the appearance to match your brand

Configuration

Configure chains, providers, and more

How It Works

Understand the technical architecture

​
Using Other Wallet Providers

​
Dynamic

<SpiceFlowProvider
  provider="dynamic"
  dynamicEnvironmentId={process.env.NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID}
>
  {children}
</SpiceFlowProvider>

​
Para

<SpiceFlowProvider
  provider="para"
  paraApiKey={process.env.NEXT_PUBLIC_PARA_API_KEY}
  paraAppName="My App"
>
  {children}
</SpiceFlowProvider>

​
Troubleshooting

​
”Window is not defined” Error

If you see this error in Next.js, ensure you’re using the "use client" directive and checking for window: 
"use client";

if (typeof window === 'undefined') {
  return <div>Loading...</div>;
}

​
Wallet Not Connecting

  1. Check that your provider credentials are correct in .env.local
  2. Ensure you’re using the correct provider name ("privy", "dynamic", or "para")
  3. Check the browser console for any error messages

​
Need More Help?

Join our Discord

Get help from the community and our team