RampWidget Integration

Use RampWidget to ship Pix fiat on-ramp and off-ramp UX while your host app still owns the wallet and signing. On-ramp has no client-side signing — the user pays a Pix code and Pods settles the crypto leg server-side. Off-ramp prompts the wallet for exactly one signature to send the on-chain leg, then Pods pays out Pix.

Money-movement routes are available only after the wallet’s Ramp KYC profile is approved. Pair this with the KycWidget, and see Set up Pods Ramp.

Install

Use the same package set and the shared PodsWidgetProvider wrapper as EarnWidget, pinned to a version that includes the ramp widget:

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

Import PodsProvider, EarnWidget, SwapWidget, and RampWidget from pods-sdk so they share the same React context.

Styles and Theme

RampWidget follows the same styling model as EarnWidget: import @deframe-sdk/components/styles.css once, keep host CSS scoped to .pods-widget, and theme via PodsProvider.config.theme. See EarnWidget Styles and Theme.

Choose a Route

RampWidget quotes exactly one crypto leg per instance, so it requires both a mode (onramp | offramp) and a rampRouteId. Build a route picker from getAvailableRampRoutes() and pass the user’s choice.

`rampRouteId`	Asset	Chain	Token	Min
`usdc-base`	USDC	Base (`8453`)	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	5
`usdc-monad`	USDC	Monad (`143`)	`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`	5
`brla-polygon`	BRLA	Polygon (`137`)	`0xE6A537a407488807F0bbeb0038B79004f19DDDFb`	5

import { getAvailableRampRoutes } from 'pods-sdk'

// All registered routes, or pass an allowlist: getAvailableRampRoutes(['usdc-base'])
const routes = getAvailableRampRoutes()
// routes[].id is the value you pass to RampWidget as `rampRouteId`

Render the On-ramp

Mount RampWidget inside the shared PodsWidgetProvider from the Earn guide. On-ramp shows the Pix payment instructions and has nothing for the user to sign — the crypto lands on currentUserWalletAddress after the Pix payment settles.

'use client'

import { RampWidget } from 'pods-sdk'
import { PodsWidgetProvider } from './PodsWidgetProvider'

export function OnrampPage({ walletAddress }: { walletAddress: string }) {
  return (
    <PodsWidgetProvider walletAddress={walletAddress}>
      <div className="pods-widget-slot" data-testid="ramp-onramp">
        <RampWidget
          mode="onramp"
          rampRouteId="usdc-base"
          currentUserWalletAddress={walletAddress}
          autoHeight
          onTicketCreated={(ticket) => persist(ticket)}
          onComplete={({ success }) => console.log('onramp', success)}
        />
      </div>
    </PodsWidgetProvider>
  )
}

Render the Off-ramp

Off-ramp collects the amount and the user’s Pix key, then prompts the wallet for a single signature. currentUserWalletAddress must be an approved Ramp wallet.

<RampWidget
  mode="offramp"
  rampRouteId="usdc-base"
  currentUserWalletAddress={walletAddress}
  autoHeight
  onTicketCreated={(ticket) => persist(ticket)}
  onStatusChange={(status) => syncStore(status)}
  onComplete={({ success, txHashes }) => console.log('offramp', success, txHashes)}
/>

Gate on KYC

The SDK has no account concept, so the host tells the widget whether the wallet still needs verification. When isKycRequired is true, the widget renders a “verify first” panel instead of the amount form, and onKycRequiredAction fires when the user acts on it — route them to the KycWidget.

<RampWidget
  mode="onramp"
  rampRouteId="usdc-base"
  currentUserWalletAddress={walletAddress}
  isKycRequired={!kycApproved}
  onKycRequiredAction={() => router.push('/kyc')}
/>

Track and Persist

A quote/bytecode round trip mints a single-use ticket. Persist it so a reactive poller can resume after a page refresh.

onTicketCreated({ actionId, quoteId?, depositAddress? }) — fires once the ticket exists.
onStatusChange(status) — mirrors every status poll into your own store.
onComplete({ success, txHashes? }) — fires once, when the flow reaches a terminal state.
onRouteChange(routeName) — adapt host shell/analytics.

`RampWidget` Props

type RampWidgetProps = {
  mode: 'onramp' | 'offramp'          // required
  rampRouteId: 'usdc-base' | 'usdc-monad' | 'brla-polygon' // required
  currentUserWalletAddress?: string   // originAddress (offramp) / destinationAddress (onramp)
  isKycRequired?: boolean
  onKycRequiredAction?: () => void
  onTicketCreated?: (ticket: { actionId: string; quoteId?: string; depositAddress?: string }) => void
  onStatusChange?: (status: SwapStatusResponse) => void
  onComplete?: (outcome: { success: boolean; txHashes?: string[] }) => void
  onRouteChange?: (routeName: string) => void
  onTrack?: (event: string, props?: Record<string, unknown>) => void
  // Layout
  className?: string
  style?: React.CSSProperties
  height?: string | number
  enableScroll?: boolean
  autoHeight?: boolean
}

API Endpoints Used in Ramp Flows

GET /v2/swap/quote — price the on/off-ramp (origin/destination fiat selects the Pix rail)
POST /v2/swap/bytecode — build the executable payload (pixKey on off-ramp payout)
GET /v2/swap/status/{id} — track the ticket to a terminal state

Guides:

Transaction Bridge

Off-ramp signing uses the same processBytecode contract as EarnWidget and SwapWidget. See processBytecode Contract.

Overview

Guides

Integrations

Agents

RampWidget Integration

Install

Styles and Theme

Choose a Route

Render the On-ramp

Render the Off-ramp

Gate on KYC

Track and Persist

`RampWidget` Props

API Endpoints Used in Ramp Flows

Transaction Bridge

​Install

​Styles and Theme

​Choose a Route

​Render the On-ramp

​Render the Off-ramp

​Gate on KYC

​Track and Persist

​RampWidget Props

​API Endpoints Used in Ramp Flows

​Transaction Bridge

Install

Styles and Theme

Choose a Route

Render the On-ramp

Render the Off-ramp

Gate on KYC

Track and Persist

`RampWidget` Props

API Endpoints Used in Ramp Flows

Transaction Bridge