Table of Contents

• Overview
• Installation
• Quick Start
• Project Structure
• Architecture Overview
• Widgets
• Hooks
• What's Exported
• Development
• Documentation

Overview

Deframe SDK is a React component library for integrating DeFi functionality into applications. It provides:

• Yield Strategies: Browse and invest in DeFi yield-generating strategies
• Token Swaps: Multi-chain token swaps with aggregated routing
• Portfolio Management: Track positions, balances, and transaction history
• Gasless Transactions: ERC-4337 smart account integration support

Installation

pnpm add deframe-sdk

Quick Start

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

function App() {
  const processBytecode = async (payload, ctx) => {
    // Handle bytecode signing with your wallet integration
    ctx.updateTxStatus({ type: 'HOST_ACK', clientTxId: payload.clientTxId })
    // ... sign and submit transaction
    ctx.updateTxStatus({ type: 'TX_CONFIRMED', clientTxId: payload.clientTxId, txHash: '0x...' })
  }

  return (
    <DeframeProvider
      config={{
        DEFRAME_API_URL: 'https://api.deframe.io',
        DEFRAME_API_KEY: 'your-api-key',
        walletAddress: '0x...',
        theme: { mode: 'dark' },
        globalCurrency: 'USD'
      }}
      processBytecode={processBytecode}
    >
      <EarnWidget height="600px" />
    </DeframeProvider>
  )
}

Project Structure

deframe-sdk/
├── src/
│   ├── index.ts                 # SDK entry point and exports
│   ├── providers/
│   │   └── DeframeProvider.tsx  # Main provider component
│   ├── widgets/
│   │   ├── EarnWidget.tsx       # Yield strategies widget
│   │   └── SwapWidget.tsx       # Token swap widget
│   ├── pages/
│   │   ├── StrategyDetails/     # Strategy detail views
│   │   │   ├── DepositFlow.tsx
│   │   │   └── WithdrawFlow.tsx
│   │   └── SwapFlow/            # Swap flow views
│   │       └── SwapFlow.tsx
│   ├── hooks/
│   │   ├── useStrategies.ts     # Strategy data hooks
│   │   ├── useWalletPositions.ts
│   │   ├── useSwapQuote.ts
│   │   └── useSwapBytecode.ts
│   ├── state/
│   │   ├── store.ts             # Redux store configuration
│   │   └── features/
│   │       ├── config/          # Configuration state
│   │       ├── tx/              # Transaction state
│   │       ├── ui/              # UI state
│   │       └── portfolio/       # Portfolio state
│   ├── api/
│   │   ├── baseQuery.ts         # RTK Query base configuration
│   │   ├── strategies.api.ts    # Strategies endpoints
│   │   ├── swap.api.ts          # Swap endpoints
│   │   └── bytecode.api.ts      # Bytecode endpoints
│   ├── bridge/
│   │   └── txOrchestrator.ts    # Transaction orchestration
│   ├── ui/                      # Reusable UI components
│   │   ├── buttons/
│   │   ├── card/
│   │   └── tabs/
│   └── types/                   # TypeScript definitions
├── docs/
│   └── flows/                   # Flow documentation
└── examples/
    └── earn-widget/             # Example integration

Architecture Overview

DeframeProvider

The root provider that configures the SDK:

interface DeframeConfig {
  DEFRAME_API_URL?: string       // API base URL
  DEFRAME_API_KEY?: string       // API authentication key
  walletAddress?: string         // User's wallet address
  userId?: string                // User identifier
  globalCurrency?: 'BRL' | 'USD' // Display currency
  globalCurrencyExchangeRate?: number
  theme?: {
    mode?: 'light' | 'dark' | 'auto'
    preset?: 'default' | 'cryptocontrol'
  }
  debug?: boolean
}

State Management

The SDK uses Redux Toolkit for state management:

| Slice | Purpose | |-------|---------| | config | SDK configuration | | connection | Connection state | | ui | Form states and navigation | | portfolio | Balance data | | tx | Transaction lifecycle | | strategies | Cached strategies | | history | Transaction history |

Transaction Lifecycle

BUILDING_BYTECODE → BYTECODE_READY → BYTECODE_SENT_HOST
  → HOST_ACK → WAITING_HOST_SIGNATURE
    → [SIGNED / SIGNATURE_ERROR / SIGNATURE_DECLINED]
      → TX_SUBMITTED → CONFIRMED → FINALIZED

Integration Modes

1. processBytecode callback: Direct function callback
2. postMessage bridge: Cross-frame communication

Widgets

EarnWidget

Display yield strategies and manage positions:

<EarnWidget
  height="500px"
  enableScroll={true}
  onRouteChange={(route) => console.log(route)}
/>

Routes:

• overview - Portfolio overview
• details - Strategy details
• deposit - Deposit flow
• withdraw - Withdraw flow
• investment-details - Position details

SwapWidget

Token swap with multi-chain support:

<SwapWidget
  fromTokenAddress="0x..."
  fromChainId="137"
  toTokenAddress="0x..."
  toChainId="42161"
/>

Routes:

• swap - Main swap form
• history-swap - Swap history

Hooks

Strategy Hooks

// Fetch all strategies
const { data, isLoading } = useStrategies()

// Fetch single strategy
const { data } = useStrategyById(strategyId)

// Fetch user positions
const { data } = useWalletPositions(walletAddress)

// Strategies with APY data
const { data } = useStrategiesWithApy()

Swap Hooks

// Get swap quote
const { data, refetch } = useSwapQuote({
  originChain: '137',
  destinationChain: '42161',
  tokenIn: '0x...',
  tokenOut: '0x...',
  amountIn: '1000000'
})

// Get swap bytecode
const { data } = useSwapBytecode({
  originAddress: '0x...',
  destinationAddress: '0x...',
  quoteId: quote.id
})

Portfolio Hooks

// Fetch balances
const { data } = useBalances(walletAddress)

// Fetch history
const { data } = useGlobalHistory(walletAddress)

// Fetch token groups
const { data } = useTokenGroups()

What's Exported

Provider & Context

export { DeframeProvider, useDeframe } from './providers/DeframeProvider'

Widgets

export { EarnWidget } from './widgets/EarnWidget'
export { SwapWidget } from './widgets/SwapWidget'

UI Components

export { PrimaryButton, SecondaryButton, TertiaryButton } from './ui/buttons'
export { TabBar } from './ui/tabs'
export { SearchInput } from './ui/inputs'
export { BalanceCard, SectionCard } from './ui/card'

Hooks

export {
  useStrategies,
  useStrategyById,
  useStrategyWithWallet,
  useWalletPositions,
  useStrategiesWithApy,
  useBalances,
  useGlobalHistory,
  useTokenGroups,
  useSwapQuote,
  useSwapBytecode,
} from './hooks'

Types

export type {
  DeframeConfig,
  Strategy,
  EarnStrategy,
  BalanceData,
  BytecodeResponse,
  BytecodeTransaction,
  SwapQuoteResponse,
  TxUpdateEvent,
  TxStatus,
} from './types'

Development

Local Development

# Clone the repository
git clone https://github.com/pods-finance/deframe-sdk.git
cd deframe-sdk

# Install dependencies
pnpm install

# Start Storybook
pnpm run storybook

# Build the SDK
pnpm run build

# Link for local development
pnpm link

Example App

cd examples/earn-widget
pnpm install
pnpm run dev

Scripts

| Command | Description | |---------|-------------| | pnpm dev | Start development server | | pnpm build | Production build | | pnpm storybook | Start Storybook | | pnpm lint | Run ESLint | | pnpm test | Run tests |

Documentation

Flow Diagrams

Detailed Mermaid diagrams are available in /docs/flows/:

• SDK Initialization
• Earn Strategies Flow
• Deposit Flow
• Withdraw Flow
• Swap Flow
• Transaction Lifecycle

License

Proprietary. All rights reserved. This software is not open source and may not be copied, modified, distributed, or used without explicit permission from the copyright holder.