> 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/hooks-and-headless-mode.md).

# Hooks and Headless Mode

For teams building a fully custom UI on top of Surf SDK, these React hooks give you direct access to all vault data and operations without rendering any of the pre-built widget components.

***

### useVault

```typescript
const { vault, isLoading, error, refetch } = useVault();
```

Returns the user's vault state: current balance, APY, total earnings and per-asset breakdown.

Use this to build your own balance display, portfolio view or performance dashboard.

***

### useDeposit

```typescript
const { step, isProcessing, execute, reset } = useDeposit();
```

State machine for the deposit flow. Call `execute(amount)` to start a deposit. The `step` value tracks progress through contract creation, ERC-20 approval and deposit confirmation. Call `reset()` to return to the initial state.

***

### useWithdraw

```typescript
const { step, isProcessing, execute, reset } = useWithdraw();
```

State machine for withdrawals. Call `execute(amount)` to start. Supports partial and full withdrawals. Accrued returns are included automatically.

***

### useBalance

```typescript
const { balance, isLoading, refetch } = useBalance();
```

Returns the user's wallet and vault token balances. Use this to show available deposit amounts or current holdings.

***

### useAgentMessages

```typescript
const { messages, isLoading, fetchMore, hasMore } = useAgentMessages();
```

Paginated feed of all Surf AI activity on the user's vault. Each message includes the action description, executor, protocol, timestamp, transaction hash and APY impact. Call `fetchMore()` to load older entries.

***

### Building a custom UI

With these hooks, you have full control over the presentation layer while the SDK handles all wallet interactions, contract calls and state management.

A typical headless integration:

```tsx
import { SurfProvider } from '@surf_liquid/surf-widget';
import { useVault, useDeposit, useWithdraw, useAgentMessages } from '@surf_liquid/surf-widget';

function MyCustomSavingsView() {
  const { vault, isLoading } = useVault();
  const { execute: deposit, step: depositStep } = useDeposit();
  const { execute: withdraw } = useWithdraw();
  const { messages } = useAgentMessages();

  if (isLoading) return <p>Loading vault...</p>;

  return (
    <div>
      <h2>Balance: ${vault.totalValueUSD}</h2>
      <p>Earnings: ${vault.totalEarningsUSD}</p>
      <p>APY: {vault.currentAPY}%</p>

      <button onClick={() => deposit('100')}>Deposit 100 USDC</button>
      <button onClick={() => withdraw('50')}>Withdraw 50 USDC</button>

      <h3>Surf AI Activity</h3>
      {messages.map(msg => (
        <div key={msg.txHash}>
          <span>{msg.description}</span>
          <span>{msg.timestamp}</span>
        </div>
      ))}
    </div>
  );
}

// Wrap with provider at app level
<SurfProvider client={client}>
  <MyCustomSavingsView />
</SurfProvider>
```