@yo-protocol/react

React hooks and components for the Yo Protocol — built on top of @yo-protocol/core, wagmi, and TanStack Query.

Installation

npm install @yo-protocol/react @yo-protocol/core viem wagmi @tanstack/react-query

Setup

Wrap your app with YieldProvider inside your existing wagmi and query providers:

import { YieldProvider } from "@yo-protocol/react";

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <YieldProvider
          partnerId={9999}        // optional, defaults to 9999
          defaultSlippageBps={50} // optional, default 50 (0.5%)
          onError={(err) => console.error(err)} // optional global error handler
        >
          {children}
        </YieldProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

For pre-built UI components, also wrap with YoKitProvider:

import { YieldProvider, YoKitProvider } from "@yo-protocol/react";

<YieldProvider>
  <YoKitProvider theme="dark">
    {children}
  </YoKitProvider>
</YieldProvider>

Hooks

All hooks must be used within a YieldProvider. Vault parameters accept either an Address or a VaultId string (e.g. "yoUSD").

All query hooks support an enabled option:

const { vaultState } = useVaultState("yoUSD", { enabled: false });
const { position } = useUserPosition("yoUSD", address, { enabled: false });
const { stats } = useVaultStats({ enabled: false });

Vault On-Chain

useVaultState(vault, options?)

Fetch a vault's on-chain state (totalAssets, totalSupply, exchangeRate, decimals, etc.).

const { vaultState, isLoading, isError, error, refetch } = useVaultState("yoUSD");

usePreviewDeposit(vault, assets, options?)

Preview the number of shares received for a deposit amount.

const { shares, isLoading } = usePreviewDeposit("yoUSD", 1_000_000n);

usePreviewRedeem(vault, shares, options?)

Preview the assets received for a given number of shares.

const { assets, isLoading } = usePreviewRedeem("yoUSD", 500_000n);

Vault API

useVaults(options?)

Fetch all available vault configurations.

const { vaults, isLoading } = useVaults();

useVaultStats(options?)

Fetch aggregated vault statistics — TVL, yield, share price, cap.

const { stats, isLoading } = useVaultStats();

useVaultSnapshot(vault, options?)

Fetch a detailed vault snapshot including stats, deployment info, and protocol data.

const { snapshot, isLoading } = useVaultSnapshot("yoETH");

useVaultSnapshots(options?)

Fetch snapshots for all vaults.

const { snapshots, isLoading } = useVaultSnapshots();

useVaultHistory(vault, options?)

Fetch historical yield and TVL timeseries data.

const { yieldHistory, tvlHistory, isLoading } = useVaultHistory("yoETH");

useVaultTransactionHistory(vault, options?)

Fetch vault transaction history with pagination and filtering. Supports allNetworks flag.

const { history, isLoading } = useVaultTransactionHistory("yoUSD", {
  limit: 50,
  allNetworks: true,
});

useGlobalVaultHistory(options?)

Fetch global vault transaction history across all vaults.

const { history, isLoading } = useGlobalVaultHistory({ limit: 100 });

useVaultPerformance(vault, options?)

Fetch a vault's realized and unrealized performance.

const { performance, isLoading } = useVaultPerformance("yoUSD");

useVaultPercentile(vault, options?)

Fetch a vault's ranking compared to other DeFi pools.

const { percentile, isLoading } = useVaultPercentile("yoUSD");

usePerformanceBenchmark(vault, options?)

Fetch benchmark data comparing vault performance against other pools.

const { benchmark, isLoading } = usePerformanceBenchmark("yoUSD");

useVaultAllocations(vault, options?)

Fetch protocol allocation time series.

const { allocations, isLoading } = useVaultAllocations("yoUSD");

useVaultPendingRedeems(vault, options?)

Fetch total pending redemptions for a vault.

const { pendingRedeems, isLoading } = useVaultPendingRedeems("yoETH");

useSharePriceHistory(vault, options?)

Fetch historical share price data.

const { history, isLoading } = useSharePriceHistory("yoETH");

useTotalTvl(options?)

Fetch total TVL time series across all vaults.

const { tvl, isLoading } = useTotalTvl();

usePrices(options?)

Fetch current token prices.

const { prices, isLoading } = usePrices();

User On-Chain

useUserPosition(vault, account?, options?)

Fetch a user's position in a vault (shares and equivalent assets). Defaults to the connected wallet.

const { position, isLoading } = useUserPosition("yoUSD", address);

useUserPositions(account?, options?)

Fetch a user's positions across all chains.

const { positions, isLoading } = useUserPositions(address);

useTokenBalance(token, account?, options?)

Fetch a user's ERC-20 token balance.

const { balance, isLoading } = useTokenBalance(usdcAddress, address);

useShareBalance(vault, account?, options?)

Fetch a user's vault share balance.

const { shares, isLoading } = useShareBalance("yoUSD", address);

useAllowance(token, spender, owner?, options?)

Fetch a token allowance for a given spender.

const { allowance, isLoading } = useAllowance(usdcAddress, gatewayAddress, address);

User API

useUserHistory(vault, user?, options?)

Fetch a user's transaction history for a vault.

const { history, isLoading } = useUserHistory("yoETH", address, { limit: 50 });

useUserPerformance(vault, user?, options?)

Fetch a user's P&L (realized and unrealized) for a vault.

const { performance, isLoading } = useUserPerformance("yoUSD", address);

useUserSnapshots(vault, user?, options?)

Fetch historical balance snapshots for a user.

const { snapshots, isLoading } = useUserSnapshots("yoETH", address);

useUserBalances(user?, options?)

Fetch a user's balances across all vaults.

const { balances, isLoading } = useUserBalances(address);

usePendingRedemptions(vault, user?, options?)

Fetch pending (queued) redemptions for a user.

const { pendingRedemptions, isLoading } = usePendingRedemptions("yoUSD", address);

useUserRewards(tokenAddress, user?, options?)

Fetch a user's rewards for a specific asset.

const { rewards, isLoading } = useUserRewards("0x...", address);

Leaderboard

useLeaderboard(period, tokenAddress, options?)

Fetch weekly or all-time reward leaderboard data.

const { data, isLoading } = useLeaderboard("weekly", "0x...");
const { data: allTime } = useLeaderboard("allTime", "0x...");

Merkl Rewards

useMerklCampaigns(options?)

Fetch Merkl reward campaigns.

const { campaigns, isLoading } = useMerklCampaigns({ status: "active" });

useMerklRewards(account?, options?)

Fetch claimable Merkl rewards with convenience fields.

const { rewards, totalClaimable, hasClaimable, isLoading } = useMerklRewards(address);

useClaimMerklRewards(options?)

Claim Merkl rewards. Uses prepareClaimMerklRewards() under the hood.

const { claim, isLoading, hash } = useClaimMerklRewards({
  onConfirmed: (hash) => {},
});

if (hasClaimable && rewards) {
  await claim(rewards);
}

Transactions

Transaction hooks use the prepare + send pattern — core's prepareX() methods build the transaction, wagmi's useSendTransaction sends it. Each hook tracks a step through the transaction lifecycle.

useDeposit(options)

Steps: idle → switching-chain → approving → depositing → waiting → success | error

const { deposit, step, isLoading, isSuccess, hash, approveHash, error, reset } = useDeposit({
  vault: "yoUSD",
  slippageBps: 50,
  onSubmitted: (hash) => {},
  onConfirmed: (hash) => {},
  onError: (err) => {},
});

await deposit({
  token: usdcAddress,
  amount: 1_000_000n,
  chainId: 8453, // optional, triggers chain switch if needed
});

useRedeem(options)

Steps: idle → approving → redeeming → waiting → success | error

const { redeem, step, isLoading, hash, instant, assetsOrRequestId } = useRedeem({
  vault: "yoUSD",
  onSubmitted: (hash) => {},
  onConfirmed: (hash) => {},
});

await redeem(500_000n);
// instant — true if assets were returned immediately
// assetsOrRequestId — asset amount or queued request ID

useApprove(options)

const { approve, approveMax, isLoading, hash } = useApprove({
  token: usdcAddress,
  spender: gatewayAddress, // optional, defaults to YO_GATEWAY_ADDRESS
  onConfirmed: (hash) => {},
});

await approve(1_000_000n);
// or
await approveMax();

Context Hooks

useYieldConfig()

Access provider configuration.

const { ready, partnerId, defaultSlippageBps } = useYieldConfig();

useYoClient()

Access the underlying YoClient instance from @yo-protocol/core.

const client = useYoClient();
// client?.getVaultState(address), etc.

useCreateYoClient(options)

Create a standalone YoClient outside of YieldProvider.

const client = useCreateYoClient({
  chainId: 8453,
  partnerId: 9999,
  publicClients: { 8453: publicClient },
});

Components

Pre-built UI components for common vault interactions. Requires YoKitProvider for theming.

import { VaultCard, DepositModal, RedeemModal } from "@yo-protocol/react";

<VaultCard
  vault="yoUSD"
  onDeposit={() => setDepositOpen(true)}
  onRedeem={() => setRedeemOpen(true)}
/>

<DepositModal
  vault="yoUSD"
  isOpen={depositOpen}
  onClose={() => setDepositOpen(false)}
  onSuccess={(hash) => console.log("Deposited:", hash)}
/>

<RedeemModal
  vault="yoUSD"
  isOpen={redeemOpen}
  onClose={() => setRedeemOpen(false)}
  onSuccess={(hash) => console.log("Redeemed:", hash)}
/>

Query Keys

All queries follow the pattern ['yo-<feature>', ...params] for easy invalidation:

| Hook | Key Pattern | | --- | --- | | useVaultState | ['yo-vault-state', vaultAddress, chainId] | | usePreviewDeposit | ['yo-preview-deposit', vaultAddress, assets, chainId] | | usePreviewRedeem | ['yo-preview-redeem', vaultAddress, shares, chainId] | | useVaults | ['yo-vaults', chainId] | | useVaultStats | ['yo-vault-stats', chainId] | | useVaultSnapshot | ['yo-vault-snapshot', vaultAddress, chainId] | | useVaultSnapshots | ['yo-vault-snapshots', chainId] | | useVaultHistory | ['yo-vault-yield-history', ...] / ['yo-vault-tvl-history', ...] | | useVaultTransactionHistory | ['yo-vault-tx-history', vaultAddress, ...] | | useGlobalVaultHistory | ['yo-global-vault-history', ...] | | useVaultPerformance | ['yo-vault-performance', vaultAddress, chainId] | | useVaultPercentile | ['yo-vault-percentile', vaultAddress, chainId] | | usePerformanceBenchmark | ['yo-performance-benchmark', vaultAddress, chainId] | | useVaultAllocations | ['yo-vault-allocations', vaultAddress, chainId] | | useVaultPendingRedeems | ['yo-vault-pending-redeems', vaultAddress, chainId] | | useSharePriceHistory | ['yo-share-price-history', vaultAddress, chainId] | | useTotalTvl | ['yo-total-tvl', chainId] | | usePrices | ['yo-prices', chainId] | | useUserPosition | ['yo-user-position', vaultAddress, account, chainId] | | useUserPositions | ['yo-user-positions', account, chainId] | | useTokenBalance | ['yo-token-balance', token, account, chainId] | | useShareBalance | ['yo-share-balance', vaultAddress, account, chainId] | | useAllowance | ['yo-allowance', token, owner, spender, chainId] | | useUserHistory | ['yo-user-history', vaultAddress, account, limit, chainId] | | useUserPerformance | ['yo-user-performance', vaultAddress, user, chainId] | | useUserSnapshots | ['yo-user-snapshots', vaultAddress, user, chainId] | | useUserBalances | ['yo-user-balances', account, chainId] | | usePendingRedemptions | ['yo-pending-redemptions', vaultAddress, user, chainId] | | useUserRewards | ['yo-user-rewards', account, tokenAddress, chainId] | | useLeaderboard | ['yo-leaderboard', period, tokenAddress, chainId] | | useMerklCampaigns | ['merkl-campaigns', status, chainId] | | useMerklRewards | ['merkl-rewards', account, chainId] |

Peer Dependencies

• react >= 18.0.0
• react-dom >= 18.0.0
• wagmi >= 2.0.0
• viem >= 2.0.0
• @tanstack/react-query >= 5.0.0

License

MIT