Widget Integration
Last updated
SurfWidget is a self-contained React component that handles the complete user journey: vault creation, deposits, withdrawals, live balance and APY display, earnings tracking, and a full Surf AI activity feed.
client
ISurfClient
Yes
-
SurfClient instance from core-sdk
walletAddress
string
Yes
-
Connected wallet address
chainId
number
No
8453
Target chain (8453 for Base, 1 for Ethereum, 137 for Polygon)
theme
SurfTheme
No
{}
Design token overrides (see Customisation)
className
string
No
-
Additional CSS class on the root element
minDeposit
number
No
0.1
Minimum deposit amount in USDC
onSuccess
(action, txHash) => void
No
-
Fires on a confirmed deposit or withdrawal
onError
(action, error) => void
No
-
Fires on a failed deposit or withdrawal
onSuccess?: (action: 'deposit' | 'withdraw', txHash: string) => void
onError?: (action: 'deposit' | 'withdraw', error: Error) => voidUse these to trigger notifications, update your own application state, or log events in your analytics.
The widget guides users through a multi-step deposit experience:
Amount entry - the user enters a deposit amount with 10%, 25%, 50% and 100% quick-select buttons. Live wallet balance is displayed with a refresh option. The minimum deposit threshold is enforced in the UI.
Contract creation - on first deposit, a personal smart contract vault is deployed on-chain for the user. This is automatic.
Approval - the widget handles the ERC-20 approval step as part of a single guided flow.
Deposit confirmation - funds are deposited into the user's vault. A transaction hash is displayed with a link to the block explorer.
A multi-step progress tracker is visible throughout: Contract Creation → Approval → Deposit → Confirmed.
Withdrawals are available at any time, for any amount.
Amount selection - the user chooses a partial or full withdrawal amount, with percentage quick-select buttons
Position closing - the widget processes the withdrawal. Accrued returns are included automatically.
Confirmation - funds are returned to the user's wallet
Progress tracker: Position Closing → Confirmed.
The widget includes a built-in activity feed that logs every on-chain action taken by Surf AI in plain language:
Deposits and withdrawals (user-initiated)
Rebalancing events (Surf AI-initiated)
Strategy changes: asset swaps, additions and removals
Reward claims and protocol distributions
Cross-chain movements
Each entry shows:
Description of the action
Who executed it (user or Surf AI)
Protocol involved
Timestamp
Transaction hash
Before and after APY impact
A separate tab view shows:
All assets currently held in the user's vault
Full deposit history with amounts and timestamps
Last updated