Skip to main content
Use SwapWidget to ship swap UX quickly while your host app still owns signing and transaction submission.

​
Install

npm install deframe-sdk @deframe-sdk/components @reduxjs/toolkit react-redux redux
If you already integrated EarnWidget, use the same package setup and the same DeframeProvider.
deframe-sdk relies on Redux internals. If your app does not already provide these deps, install @reduxjs/toolkit, react-redux, and redux explicitly.

​
Styles and Theme

SwapWidget follows the same styling model as EarnWidget:
  • SDK styles are loaded from the package entrypoint.
  • No separate CSS import is required in the default setup.
  • Keep host CSS scoped and avoid global resets leaking into .deframe-widget.

​
Render SwapWidget

import { DeframeProvider, SwapWidget } from 'deframe-sdk'

export function SwapWidgetScreen({ walletAddress }: { walletAddress: string }) {
  return (
    <DeframeProvider
      config={{
        DEFRAME_API_URL: process.env.NEXT_PUBLIC_DEFRAME_API_URL,
        DEFRAME_API_KEY: process.env.NEXT_PUBLIC_DEFRAME_API_KEY,
        walletAddress,
        language: 'EN',
        theme: { mode: 'dark', preset: 'default' }
      }}
      processBytecode={processBytecode}
    >
      <SwapWidget autoHeight />
    </DeframeProvider>
  )
}

​
Prefill Token/Chain Params

You can initialize swap inputs from host route/query params. 
import { useMemo } from 'react'
import { useSearchParams } from 'next/navigation'
import { SwapWidget } from 'deframe-sdk'

export function SwapPageWithPrefill() {
  const params = useSearchParams()

  const widgetProps = useMemo(() => ({
    autoHeight: true,
    fromTokenAddress: params.get('fromTokenAddress') ?? undefined,
    fromChainId: params.get('fromChainId') ? Number(params.get('fromChainId')) : undefined,
    toTokenAddress: params.get('toTokenAddress') ?? undefined,
    toChainId: params.get('toChainId') ? Number(params.get('toChainId')) : undefined
  }), [params])

  return <SwapWidget {...widgetProps} />
}

​
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

  1. Generate quote and bytecode.
  2. Execute all returned bytecodes in order through processBytecode.
  3. Persist quoteId/clientTxId in your backend.
  4. Poll swap status endpoint until terminal state.
  5. 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.