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

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

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

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

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

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:

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>