SwapWidget Integration

Use SwapWidget to ship same-chain and cross-chain swap UX quickly while your host app still owns signing and transaction submission.

Install

Use the same package set and the same DeframeProvider wrapper as EarnWidget:

pnpm add [email protected] @deframe-sdk/[email protected] @reduxjs/toolkit@^2 react-redux@^9 redux@^5

Use the Pods Wallet-style swap view by overriding SwapFormView with PodsSwapFormView. Import DeframeProvider, EarnWidget, and SwapWidget from pods-sdk so the widgets share the same React context.

Styles and Theme

SwapWidget follows the same styling model as EarnWidget:

Import @deframe-sdk/components/styles.css once in the host app entrypoint.
Keep host CSS scoped and avoid global resets leaking into .deframe-widget.
Configure branding through DeframeProvider.config.theme.
Use .deframe-widget CSS variables only from a wrapper you own.

See EarnWidget Styles and Theme for the full CSS example.

Render SwapWidget

Mount SwapWidget inside the shared DeframeProvider wrapper from the Earn guide.

'use client'

import { SwapWidget } from 'pods-sdk'
import { DeframeWidgetProvider } from './DeframeWidgetProvider'

export function SwapPage({
  walletAddress,
  userId,
}: {
  walletAddress: string
  userId?: string
}) {
  return (
    <DeframeWidgetProvider walletAddress={walletAddress} userId={userId}>
      <div className="deframe-widget-slot" data-testid="swap-widget-container">
        <SwapWidget autoHeight />
      </div>
    </DeframeWidgetProvider>
  )
}

Use the Pods Wallet Swap View

Register PodsSwapFormView at the provider level so every SwapWidget renders the Pods Wallet-style view: title and subtitle, history action, two token amount cards, the centered direction button, and the primary action button state.

'use client'

import { useMemo, type ReactNode } from 'react'
import { PodsSwapFormView } from '@deframe-sdk/components'
import { DeframeProvider } from 'pods-sdk'
import { processBytecode } from './processBytecode'

type DeframeWidgetProviderProps = {
  children: ReactNode
  walletAddress?: string
  userId?: string
}

export function DeframeWidgetProvider({
  children,
  walletAddress,
  userId,
}: DeframeWidgetProviderProps) {
  const podsApiUrl = process.env.NEXT_PUBLIC_PODS_API_URL
  const podsApiKey = process.env.NEXT_PUBLIC_PODS_API_KEY
  const podsWebSocketUrl = process.env.NEXT_PUBLIC_PODS_WEBSOCKET_URL

  const config = useMemo(() => ({
    // [email protected] still expects these provider field names.
    DEFRAME_API_URL: podsApiUrl,
    DEFRAME_API_KEY: podsApiKey,
    DEFRAME_WEBSOCKET_URL: podsWebSocketUrl,
    walletAddress,
    userId,
    enableCrossChainInvestments: true,
    components: {
      SwapFormView: PodsSwapFormView,
    },
  }), [podsApiKey, podsApiUrl, podsWebSocketUrl, walletAddress, userId])

  return (
    <DeframeProvider config={config} processBytecode={processBytecode}>
      {children}
    </DeframeProvider>
  )
}

Keep this override in the wrapper that owns DeframeProvider, not on each swap page. The page still renders the SDK widget normally with <SwapWidget />; the provider decides which swap form view is used.

Prefill Token/Chain Params

You can initialize swap inputs from host route or query params. This is the pattern to use when another widget or dashboard card sends the user into swap with a target token already selected.

'use client'

import { Suspense, useMemo } from 'react'
import { useSearchParams } from 'next/navigation'
import { SwapWidget } from 'pods-sdk'
import { DeframeWidgetProvider } from './DeframeWidgetProvider'

function readNumberParam(params: URLSearchParams, key: string): number | undefined {
  const value = params.get(key)
  if (!value) return undefined

  const parsed = Number(value)
  return Number.isFinite(parsed) ? parsed : undefined
}

function SwapContent({
  walletAddress,
  userId,
}: {
  walletAddress: string
  userId?: string
}) {
  const params = useSearchParams()

  const fromTokenAddress = params.get('fromTokenAddress') ?? undefined
  const fromChainId = readNumberParam(params, 'fromChainId')
  const toTokenAddress = params.get('toTokenAddress') ?? undefined
  const toChainId = readNumberParam(params, 'toChainId')

  const widgetProps = useMemo(() => ({
    autoHeight: true,
    fromTokenAddress,
    fromChainId,
    toTokenAddress,
    toChainId,
  }), [fromTokenAddress, fromChainId, toTokenAddress, toChainId])

  const widgetKey = [
    fromTokenAddress,
    fromChainId,
    toTokenAddress,
    toChainId,
  ].join('-')

  return (
    <DeframeWidgetProvider walletAddress={walletAddress} userId={userId}>
      <div className="deframe-widget-slot" data-testid="swap-page">
        <SwapWidget key={widgetKey} {...widgetProps} />
      </div>
    </DeframeWidgetProvider>
  )
}

export function SwapPageWithPrefill({
  walletAddress,
  userId,
}: {
  walletAddress: string
  userId?: string
}) {
  return (
    <Suspense fallback={<div className="deframe-widget-slot">Loading swap...</div>}>
      <SwapContent walletAddress={walletAddress} userId={userId} />
    </Suspense>
  )
}

`SwapWidget` Props

type SwapWidgetProps = {
  className?: string
  style?: React.CSSProperties
  height?: string | number
  enableScroll?: boolean
  autoHeight?: boolean
  fromTokenAddress?: string
  fromChainId?: number
  toTokenAddress?: string
  toChainId?: number
}

API Endpoints Used in Swap Flows

GET /v2/swap/quote to request same-chain/cross-chain quotes
POST /v2/swap/bytecode to build executable transaction payloads
GET /v2/swap/status/{id} to track cross-chain swap lifecycle

Guides:

Cross-chain Lifecycle Recommendations

Generate quote and bytecode.
Execute all returned bytecodes in order through processBytecode.
Persist quoteId and clientTxId in your backend.
Poll the swap status endpoint until the flow reaches a terminal state.
Display status history in customer support/admin surfaces.

Transaction Bridge

SwapWidget uses the same processBytecode contract as EarnWidget. See processBytecode Contract for required status emissions and error mapping.

​Install

​Styles and Theme

​Render SwapWidget

​Use the Pods Wallet Swap View

​Prefill Token/Chain Params

​SwapWidget Props

​API Endpoints Used in Swap Flows

​Cross-chain Lifecycle Recommendations

​Transaction Bridge

Install

Styles and Theme

Render SwapWidget

Use the Pods Wallet Swap View

Prefill Token/Chain Params

`SwapWidget` Props

API Endpoints Used in Swap Flows

Cross-chain Lifecycle Recommendations

Transaction Bridge