Configuration

Wallet Provider

Spice Flow uses Privy for wallet connections and embedded wallets.

Privy

Best for embedded wallets and social logins.

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
>
  {children}
</SpiceFlowProvider>

Configuration: your Privy app ID and embedded-wallet policy are configured on your own PrivyProvider (which the SDK reads through Privy’s hooks), not on SpiceFlowProvider:

<PrivyProvider
  appId="your-privy-app-id"
  config={{
    supportedChains: [...chains],
    embeddedWallets: { ethereum: { createOnLogin: "all-users" } },
  }}
>

The privyAppId and embeddedWalletConfig props on SpiceFlowProvider exist for compatibility but have no effect in the current release. Get Your Privy App ID:

Sign up at privy.io
Create a new app
Copy your App ID from the dashboard

Execution Modes

mode="7702" selects the embedded account (default). mode="ondemand" selects the external account; "presign" is an alias of "ondemand". These account modes do not mean that all external-mode actions are implemented through host callbacks.

<SpiceFlowProvider network="mainnet" nativeChainId={8453} mode="7702">
  {children}
</SpiceFlowProvider>

For Supply/Pay/Lock, the SDK owns execution in both modes:

A positive-amount external action using its matching destination token on the destination chain executes directly from that wallet, with its native gas. Fee-only and proceeds-funded actions are excluded.
Other supported sources use the routed path through the embedded wallet. The host defines destination calls and any separate beneficiary; it does not send the transaction through onPayExecute or onLockExecute.
Same-wallet, same-chain embedded actions that need no routing execute without an unnecessary Spice funding leg.

SpiceDeposit / SpiceWithdraw retain their own non-7702 callbacks (onDepositExecute, onWithdrawExecute). They are account funding/withdrawal flows, not the Supply/Lock override contract. Use useSpiceAccount() to render mode and owner. Omit a fixed provider mode when the SDK account toggle should control it. Funding from both connected wallets is enabled by default; mode chooses the account owner and is not a source-wallet filter. See Migration.

Card and Exchange Deposits

Available from @spicenet-io/spiceflow-ui@4.7.11. When enabled, SpiceDeposit opens with a source chooser in front of the existing flow: Wallet, Card, or Exchange. Card and exchange deposits run through the Swapper Finance widget, and the SDK verifies on chain that the USDC arrived before handing off. Users can fund with a debit card or from an exchange account instead of only from a connected wallet. It is off by default. Nothing changes for your integration until you opt in:

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
  swapper={{ enabled: true }}
>
  {children}
</SpiceFlowProvider>

enabled: true is the only required field. The integrator id defaults to Spicenet’s; pass integratorId only if Swapper has issued you your own.

Where the funds land

Swapper delivers USDC to the wallet the user is operating with, and the wallet mode decides what happens next.

Wallet mode	Delivered to	Chain	Then
Embedded (`7702`)	The user’s embedded wallet	Arbitrum	Continues into the escrow deposit and credits the spice balance, which is usable on any supported chain
External (`presign` / `ondemand`)	The user’s connected wallet	Your app’s chain if it is Base or Arbitrum, otherwise Arbitrum	The flow ends. Funds are in the user’s wallet and no spice balance is credited

Swapper currently delivers to Base and Arbitrum. An embedded deposit always lands on Arbitrum because escrow abstracts the chain downstream. An external deposit lands on your app’s chain when Swapper covers it, and on Arbitrum when it does not. The app’s chain is read from destinationChainId on SpiceDeposit, falling back to nativeChainId on the provider.

If your app runs on a chain Swapper does not deliver to, an external-wallet user’s card or exchange deposit ends up on Arbitrum, in their own wallet. Consider enabling this only for embedded-wallet users on those chains, or make sure your flow can handle funds arriving there.

Telling the two outcomes apart

onDepositSuccess on SpiceDeposit reports which path completed through detail.type:

<SpiceDeposit
  onDepositSuccess={(detail) => {
    if (detail.type === "wallet-funding") {
      // Card/exchange deposit landed in the user's external wallet. No spice credited.
      return;
    }
    // "deposit": escrow deposit completed and spice was credited.
  }}
/>

Code that already checks for "deposit" keeps working and will not treat a wallet funding as a spice credit. The source chooser only appears on network="mainnet"; testnets skip it and go straight to the wallet flow.

Network Configuration

Set the network to control which chains are available:

<SpiceFlowProvider network="mainnet" nativeChainId={8453}>

Default Chains by Network

The SDK derives the chain set from the installed core package: Mainnet: Ethereum (1), Base (8453), Arbitrum (42161), Citrea (4114), Robinhood (4663), BSC (56), Polygon (137), Monad (143) Testnet: Sepolia (11155111), Arbitrum Sepolia (421614), Base Sepolia (84532), Citrea Testnet (5115), Base Camp (123420001114), Pharos (688688), Pharos Atlantic (688689), Robinhood Testnet (46630), Monad Testnet (10143), BSC Testnet (97), Avalanche Fuji (43113), Polygon Amoy (80002), Optimism Sepolia (11155420) The list grows with releases — read it from your installed version with getChainIdsByNetwork("mainnet") (exported from the SDK) rather than hardcoding.

Custom Chain IDs

Override the defaults with supportedChainIds:

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
  supportedChainIds={[8453, 4114]}
>
  {children}
</SpiceFlowProvider>

RPC provider and token discovery

Wallet token discovery and USD prices use the Alchemy API of the RPC endpoint in use for a chain. On an endpoint that is not Alchemy’s, or on a chain where Alchemy has no token API, the SDK lists only the tokens configured for that chain, and balances show without provider prices. Pass your own endpoint per chain with rpcOverrides; a chain without an entry uses the SDK’s built-in endpoint. Production integrations should supply their own endpoints for the chains they exercise. Wagmi transports alone do not configure SDK reads. Rollup price lookups require a host-configured RPC.

Liquidity Venues

Available from @spicenet-io/spiceflow-ui@4.8.0. When a flow has to swap on the destination chain, the SDK quotes every liquidity venue that covers that chain and takes the best fill: the most output for an exact input, the least input for an exact output. Routing is decided in the SDK, on your RPC. The solver only executes the calls the winning quote produced. Leave liquidityVenues off and you get the built-in venues:

Chain	Built-in venues
Citrea (4114, 5115)	Satsuma
Base (8453)	Uniswap v3, Uniswap v4, Aerodrome Slipstream
Robinhood (4663)	Uniswap v3, SushiSwap, Uniswap v4
Ethereum (1), Arbitrum (42161), Polygon (137), BSC (56), Monad (143)	Uniswap v3

Every built-in serves both swap directions, so a venue is never reachable for an exact-input swap but missing for an exact-output one. A supported chain still needs a configured venue and liquidity for the requested swap pair. The SDK has no keyless 1inch fallback in its default venue list. For deployments outside the built-ins, declare a venue explicitly; both exact-input and exact-output routing use the declaration.

Adding your own venue

Declare it once on the provider and every component picks it up. This is the whole change needed to route through a deployment the SDK does not ship — here, the SushiSwap v3 deployment on Robinhood:

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={4663}
  rpcOverrides={{ 4663: ROBINHOOD_RPC }}
  liquidityVenues={{
    venues: [
      {
        protocol: "uniswap-v3",
        chainId: 4663,
        name: "SushiSwap",
        swapRouter: "0x1e406484F1F204b23cE84B9901C0171a738fd406",
        quoterV2: "0x3E290e5E01818002A0b672148BdC7514D861C7B3",
        feeTiers: [100, 500, 3000, 10000],
        hubCurrencies: [
          "0x0bd7d308f8e1639fab988df18a8011f41eacad73",
          "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
        ],
        routerHasDeadline: true,
      },
    ],
  }}
>
  {children}
</SpiceFlowProvider>

Your venue races the built-ins on price. It does not override them, and it is used in both swap directions.

Turning the built-ins off

Set includeDefaults: false to drop every built-in venue, and route only through what you declared:

liquidityVenues={{
  venues: [ /* ... */ ],
  includeDefaults: false,
}}

On a chain with no venue at all, quoting then fails naming that chain rather than falling back to something you did not configure. Leave includeDefaults off (or true) to keep the built-ins and add yours alongside them.

Venue fields

Supply the deployment’s addresses, not a pool address. A v3-style pool calls back into msg.sender, so swaps go through the router and quotes through the quoter; the SDK finds the pools itself from the fee tiers (or tick spacings) and hub currencies.

`protocol`	Required	Optional
`uniswap-v3`	`chainId`, `swapRouter`, `quoterV2`	`name`, `feeTiers`, `hubCurrencies`, `routerHasDeadline`
`uniswap-v4`	`chainId`, `quoter`, `universalRouter`, `permit2`	`name`, `hubCurrencies`
`aerodrome-slipstream`	`chainId`, `swapRouter`, `quoterV2`	`name`, `tickSpacings`, `hubCurrencies`

Each entry names exactly one chain. Declare the same deployment twice if it runs on two chains.

name is shown to the user as via <name> once an exact-output swap is quoted. It defaults to the protocol.
hubCurrencies are the intermediate tokens tried for two-hop routes, usually wrapped native and the chain’s main stablecoin.
feeTiers / tickSpacings are the pool tiers to search. Include any non-standard tier your venue uses, such as PancakeSwap’s 2500.

Set routerHasDeadline: true when the deployment forked the original Uniswap SwapRouter, whose exact-output structs carry a deadline. SwapRouter02 forks do not, and this is the default.Getting it wrong is invisible until execution: quoting goes through the quoter, which does not care, so the quote looks correct either way and only the transaction reverts. If your exact-output swaps quote cleanly but revert on chain, this flag is the first thing to check.

Every venue covering a chain is quoted on every keystroke, and each one costs several quoter calls against your RPC (roughly feeTiers x (1 + hubCurrencies) per venue). Adding venues improves fill and increases RPC load. Scope chainId tightly and keep hubCurrencies to the tokens that actually carry liquidity.

Venues from another protocol family

Most DEXs are forks of one of the three families above, so adding one is addresses only. A venue built on a different family — a Uniswap v2 pair, Curve, Balancer — needs an adapter inside the SDK, because the SDK owns the calldata rather than asking you to encode swaps yourself. Send us the chain, router, quoter and one funded pool and it becomes a protocol every integration can name.

Theming

Set your app’s visual identity through the theme prop. All SDK components inherit these values.

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
  theme={{
    primaryColor: "#f97316",
    dark: true,
    appName: "MyApp",
  }}
>
  {children}
</SpiceFlowProvider>

See Styling for the full theming reference.

API URL Override

By default, the SDK connects to the Spicenet relayer. Override this if you’re proxying requests or using a custom deployment:

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  apiUrl="/api/relayer"
>
  {children}
</SpiceFlowProvider>

Complete Provider Reference

Prop	Type	Default	Description
`provider`	`"privy"`	`"privy"`	Wallet provider (Privy only in the current release)
`network`	`"mainnet" \| "testnet"`	`"testnet"`	Network environment
`nativeChainId`	`number`		Your app’s chain. Deposits are delivered here unless a component sets `destinationChainId`, and External-mode deposits ask the wallet to be on it
`theme`	`SpiceTheme`		Colors, dark mode, surfaces, fonts, app name
`privyAppId`	`string`		No effect — set `appId` on `PrivyProvider`
`supportedChainIds`	`number[]`	Per network	Override supported chains
`allowedTokens`	`string[]`		Restrict tokens by lowercase symbol
`mode`	`"7702" \| "presign" \| "ondemand"`	`"7702"`	Execution mode. `"presign"` behaves exactly like `"ondemand"`
`whitelist`	`SpiceFlowWhitelistOptions \| false`		Gate the flow to whitelisted wallets
`rpcOverrides`	`Record<number, string>`		Per-chain RPC overrides
`skipFlow`	`number[]`	`[]`	No effect
`appName`	`string`		No effect. Set `theme.appName` instead
`apiUrl`	`string`		Override relayer API URL
`embeddedWalletConfig`	`object`		No effect — set `embeddedWallets` in the `PrivyProvider` config
`swapper`	`SpiceSwapperConfig`	off	Enable card and exchange deposits. See Card and Exchange Deposits
`liquidityVenues`	`LiquidityVenuesConfig`	Built-ins	Declare your own swap venues, or turn the built-ins off. See Liquidity Venues

Next Steps

Styling

Customize component appearance

Components

Explore available components

Examples

See complete examples

Best Practices

Security and integration patterns

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

Wallet Provider

Privy

Execution Modes

Card and Exchange Deposits

Where the funds land

Telling the two outcomes apart

Network Configuration

Default Chains by Network

Custom Chain IDs

RPC provider and token discovery

Liquidity Venues

Adding your own venue

Turning the built-ins off

Venue fields

Venues from another protocol family

Theming

API URL Override

Complete Provider Reference

Next Steps

Styling

Components

Examples

Best Practices

​Wallet Provider

​Privy

​Execution Modes

​Card and Exchange Deposits

​Where the funds land

​Telling the two outcomes apart

​Network Configuration

​Default Chains by Network

​Custom Chain IDs

​RPC provider and token discovery

​Liquidity Venues

​Adding your own venue

​Turning the built-ins off

​Venue fields

​Venues from another protocol family

​Theming

​API URL Override

​Complete Provider Reference

​Next Steps

Styling

Components

Examples

Best Practices

Wallet Provider

Privy

Execution Modes

Card and Exchange Deposits

Where the funds land

Telling the two outcomes apart

Network Configuration

Default Chains by Network

Custom Chain IDs

RPC provider and token discovery

Liquidity Venues

Adding your own venue

Turning the built-ins off

Venue fields

Venues from another protocol family

Theming

API URL Override

Complete Provider Reference

Next Steps