EarnWidget Integration

Use EarnWidget when you want Pods yield UX in your app while keeping wallet custody and transaction execution in your infrastructure.

What You Own vs What Pods Owns

Area	Owner
Wallet connection, signatures, tx submission	Your app
Strategy data, quote/bytecode generation, protocol routing	Pods API
UI state and yield screens (overview, details, deposit, withdraw, investment details, history)	`EarnWidget`

Verified integration contract

Install the current widget package set:

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

Use the same SDK package for DeframeProvider, EarnWidget, and SwapWidget. The Pods Wallet-style widget stack imports them from pods-sdk and uses @deframe-sdk/components for the shared visual system and swap view override.

For Privy smart-wallet hosts, add the wallet stack from the Privy Integration guide.

Styles and Theme

Import the published component stylesheet in your app entrypoint before your own app CSS. For Next.js App Router:

// app/layout.tsx
import '@deframe-sdk/components/styles.css'
import './globals.css'

For Vite React:

// src/main.tsx
import '@deframe-sdk/components/styles.css'
import './index.css'

Treat .deframe-widget as the style boundary owned by the SDK:

Scope host app styles to your own containers.
Avoid global resets like * { ... } or broad element resets that can leak into the widget.
Use DeframeProvider.config.theme as the source of truth for widget theming.
Use widget-scoped CSS variables only as host-side branding extensions.
Do not copy internal SDK view overrides into customer integrations unless you own and test those override components.

.pods-host-shell {
  width: min(1180px, 100%);
  margin: 0 auto;
  overflow-x: hidden;
}

.deframe-widget-slot {
  width: min(760px, 100%);
  margin: 0 auto;
  overflow-x: hidden;
}

.pods-host-shell .deframe-widget {
  --deframe-widget-color-brand-primary: #2dd881;
  --deframe-widget-color-bg-primary: #0b0f14;
  --deframe-widget-color-bg-raised: #161e29;
  --deframe-widget-color-text-primary: #f6f8fb;
  --deframe-widget-color-text-secondary: #aab6c5;
  --deframe-widget-size-radius-lg: 18px;
}

Environment Variables

Canonical client env names for widget hosts:

NEXT_PUBLIC_PODS_API_URL=https://api.pods.finance
NEXT_PUBLIC_PODS_API_KEY=your_api_key
NEXT_PUBLIC_PODS_WEBSOCKET_URL=wss://api.pods.finance/updates

If you proxy Pods API calls through your own backend, pass the proxy route as NEXT_PUBLIC_PODS_API_URL and inject the API key server-side. The browser still needs NEXT_PUBLIC_PODS_WEBSOCKET_URL when realtime action updates should connect directly.

If your host uses Vite and you want to keep these same names, configure:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  envPrefix: ['VITE_', 'NEXT_PUBLIC_'],
  resolve: {
    alias: {
      'next/link': fileURLToPath(new URL('./src/shims/next-link.tsx', import.meta.url)),
    },
  },
})

For non-Next hosts, add the shim used by that alias:

import type { AnchorHTMLAttributes, PropsWithChildren } from 'react'

type NextLinkShimProps = PropsWithChildren<
  AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }
>

export default function Link({ href, children, ...props }: NextLinkShimProps) {
  return (
    <a href={href} {...props}>
      {children}
    </a>
  )
}

Step 1: Implement `processBytecode`

processBytecode is the host bridge between widget actions and wallet execution. Batch all legs on the same chainId into one atomic wallet submission — see processBytecode Contract and Executing Bytecode.

import type { UpdateTxStatus } from 'pods-sdk'

// Group by chainId → sendBatchedTransactionWithWallet({ chainId, legs }) per chain
// Emit: HOST_ACK → SIGNATURE_PROMPTED → TX_SUBMITTED → TX_CONFIRMED → TX_FINALIZED
// See widgets/process-bytecode.mdx for the full minimal implementation.

For the complete transaction lifecycle, see processBytecode Contract.

Step 2: Create a Shared Provider Wrapper

Use a single host wrapper for EarnWidget, SwapWidget, and any SDK hooks that need provider context.

'use client'

import { PodsSwapFormView } from '@deframe-sdk/components'
import { DeframeProvider, useDeframe } from 'pods-sdk'
import { useEffect, useMemo, useRef, type ReactNode } from 'react'
import { useRouter } from 'next/navigation'
import { processBytecode } from './processBytecode'

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

type NavigateToSwapEvent = {
  toTokenAddress: string
  toChainId: number
  fromTokenAddress?: string
  fromChainId?: number
}

type RouteChangeRequestEvent = {
  route: string
}

function DeframeEventBridge() {
  const router = useRouter()
  const { addEventListener, removeEventListener } = useDeframe()
  const subscribedRef = useRef(false)

  useEffect(() => {
    if (subscribedRef.current) return
    subscribedRef.current = true

    const handleNavigateToSwap = (eventData: unknown) => {
      const data = eventData as NavigateToSwapEvent
      const params = new URLSearchParams()
      params.set('toTokenAddress', data.toTokenAddress)
      params.set('toChainId', String(data.toChainId))
      if (data.fromTokenAddress) params.set('fromTokenAddress', data.fromTokenAddress)
      if (data.fromChainId) params.set('fromChainId', String(data.fromChainId))
      router.push(`/dashboard/swap?${params.toString()}`)
    }

    const handleRouteChangeRequest = (eventData: unknown) => {
      const data = eventData as RouteChangeRequestEvent
      if (data.route === 'history') router.push('/dashboard/history')
      if (data.route === 'wallet') router.push('/dashboard')
      if (data.route === 'swap') router.push('/dashboard/swap')
      if (data.route === 'earn') router.push('/dashboard/earn')
    }

    addEventListener('navigateToSwap', handleNavigateToSwap)
    addEventListener('routeChangeRequest', handleRouteChangeRequest)

    return () => {
      removeEventListener('navigateToSwap', handleNavigateToSwap)
      removeEventListener('routeChangeRequest', handleRouteChangeRequest)
      subscribedRef.current = false
    }
  }, [addEventListener, removeEventListener, router])

  return null
}

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

  // Next.js client example. In Vite, replace process.env with import.meta.env.
  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,
    language: 'EN' as const,
    globalCurrency: 'USD' as const,
    globalCurrencyExchangeRate: 1,
    enableCrossChainInvestments: true,
    components: {
      SwapFormView: PodsSwapFormView,
    },
    debug: process.env.NODE_ENV === 'development',
    theme: {
      mode: 'dark' as const,
      preset: 'default' as const,
      overrides: {
        dark: {
          colors: {
            brandPrimary: '#1FC16B',
            brandSecondary: '#A9ABF7',
            bgDefault: '#121212',
            bgSubtle: '#1E1E1E',
            bgMuted: '#2C2C2C',
            bgRaised: '#232323',
            textPrimary: '#FFFFFF',
            textSecondary: '#99A0AE',
            textDisabled: '#525866',
            stateSuccess: '#2BA176',
            stateWarning: '#F6A700',
            stateError: '#FF4D4F',
            stateInfo: '#58B4FF',
          },
        },
      },
    },
  }), [podsApiKey, podsApiUrl, podsWebSocketUrl, walletAddress, userId])

  if (!walletAddress) {
    return <div>Connect a wallet before loading Pods widgets.</div>
  }

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

Step 3: Mount the Invest View

The Pods Wallet-style Invest page lets the overview use a wider layout and narrows detail or transaction routes.

'use client'

import { EarnWidget } from 'pods-sdk'
import { useState } from 'react'
import { DeframeWidgetProvider } from './DeframeWidgetProvider'

export function InvestPage({
  walletAddress,
  userId,
}: {
  walletAddress: string
  userId?: string
}) {
  const [routeName, setRouteName] = useState('overview')
  const isOverview = routeName === 'overview'

  return (
    <div className={`pods-host-shell ${isOverview ? 'pods-host-shell-wide' : ''}`}>
      <div className={isOverview ? 'pods-invest-overview-slot' : 'deframe-widget-slot'}>
        <DeframeWidgetProvider walletAddress={walletAddress} userId={userId}>
          <EarnWidget autoHeight onRouteChange={setRouteName} />
        </DeframeWidgetProvider>
      </div>
    </div>
  )
}

.pods-host-shell-wide {
  width: min(1400px, 100%);
}

.pods-invest-overview-slot {
  width: min(1400px, 100%);
  margin: 0 auto;
  overflow-x: hidden;
}

Route Names Exposed by `onRouteChange`

Common values: overview, details, deposit, withdraw, investment-details, history, history-deposit-details, history-withdraw-details. Use these to adapt host shell layout, breadcrumbs, and analytics tags.

Host Env and Provider Config Reference

Field	Purpose
`NEXT_PUBLIC_PODS_API_URL`	Pods API base URL or your host proxy route.
`NEXT_PUBLIC_PODS_API_KEY`	API key when calling Pods directly from the browser. Omit it if your proxy injects the key server-side.
`NEXT_PUBLIC_PODS_WEBSOCKET_URL`	Realtime action update endpoint.
`walletAddress`	Connected wallet or smart-wallet address used for balances, positions, and history.
`userId`	Optional host user ID for analytics/reconciliation.
`language`	`EN` or `PT`.
`globalCurrency`	`USD` or `BRL`.
`globalCurrencyExchangeRate`	USD-to-selected-currency rate. Use `1` for USD.
`enableCrossChainInvestments`	Enables network selection for cross-chain deposit/withdraw flows.
`hiddenChainIds`	Optional chain IDs to hide from SDK network selectors.
`chains`	Optional host-owned chain list with `id`, `name`, `iconUrl`, `explorerTxUrl`, and optional `swapSlug`.
`strategyAssetWhitelists`	Optional strategy-specific token/network allowlists.
`theme`	Preferred theme API: `mode`, `preset`, and `overrides`.
`debug`	Enables SDK debug logging in development.

[email protected] still exposes the provider fields as DEFRAME_API_URL, DEFRAME_API_KEY, and DEFRAME_WEBSOCKET_URL. Keep the host env names branded as PODS_*, then map them into those provider fields in the wrapper.

API Endpoints Used in Earn Flows

GET /strategies for strategy discovery
GET /strategies/{strategyId} for strategy details
GET /strategies/{strategyId}/bytecode for deposit/withdraw transaction data
GET /wallets/{wallet} for portfolio state
GET /wallets/{wallet}/history/{strategyId} for investment activity

Guides:

Customer Integration Checklist

Install pods-sdk, @deframe-sdk/components, and Redux peer packages.
Import @deframe-sdk/components/styles.css before your host CSS.
Pass the connected wallet or smart-wallet address into DeframeProvider.config.walletAddress.
Implement processBytecode with your wallet stack.
Emit all required tx lifecycle statuses back to the widget.
Configure NEXT_PUBLIC_PODS_WEBSOCKET_URL so the widget can recover realtime cross-chain state.
Keep host CSS scoped to containers around .deframe-widget.
Track completed transactions in your own ledger for reconciliation/support.

​What You Own vs What Pods Owns

​Verified integration contract

​Styles and Theme

​Environment Variables

​Step 1: Implement processBytecode

​Step 2: Create a Shared Provider Wrapper

​Step 3: Mount the Invest View

​Route Names Exposed by onRouteChange

​Host Env and Provider Config Reference

​API Endpoints Used in Earn Flows

​Customer Integration Checklist

What You Own vs What Pods Owns

Verified integration contract

Styles and Theme

Environment Variables

Step 1: Implement `processBytecode`

Step 2: Create a Shared Provider Wrapper

Step 3: Mount the Invest View

Route Names Exposed by `onRouteChange`

Host Env and Provider Config Reference

API Endpoints Used in Earn Flows

Customer Integration Checklist