> For the complete documentation index, see [llms.txt](https://surf-2.gitbook.io/surfliquid-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surf-2.gitbook.io/surfliquid-docs/sdk-docs/widget-integration.md).

# Widget Integration

`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.

***

### Props Reference

| Prop            | Type                       | Required | Default | Description                                                   |
| --------------- | -------------------------- | -------- | ------- | ------------------------------------------------------------- |
| `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                       |

***

### Callbacks

```typescript
onSuccess?: (action: 'deposit' | 'withdraw', txHash: string) => void
onError?:   (action: 'deposit' | 'withdraw', error: Error) => void
```

Use these to trigger notifications, update your own application state, or log events in your analytics.

***

### Deposit Flow

The widget guides users through a multi-step deposit experience:

1. **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.
2. **Contract creation** - on first deposit, a personal smart contract vault is deployed on-chain for the user. This is automatic.
3. **Approval** - the widget handles the ERC-20 approval step as part of a single guided flow.
4. **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.

***

### Withdrawal Flow

Withdrawals are available at any time, for any amount.

1. **Amount selection** - the user chooses a partial or full withdrawal amount, with percentage quick-select buttons
2. **Position closing** - the widget processes the withdrawal. Accrued returns are included automatically.
3. **Confirmation** - funds are returned to the user's wallet

Progress tracker: Position Closing → Confirmed.

***

### Surf AI Activity Feed

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

***

### Asset and Deposit History

A separate tab view shows:

* All assets currently held in the user's vault
* Full deposit history with amounts and timestamps