useAddFunds

Hook to open the receive screen: the chains the account accepts deposits on, a QR code, and the address itself.

Type: hook

Import

import { useAddFunds } from '@jaw.id/wagmi';

Signature

function useAddFunds(parameters?: { config?: Config; mutation?: UseMutationParameters }): UseMutationResult;

Parameters

config

Type: Config (optional)

Wagmi config. If not provided, uses the config from WagmiProvider.

mutation

Type: UseMutationParameters (optional)

TanStack React Query mutation options.

Returns

Returns a TanStack React Query mutation result:

data

Always null. Deposits land off-app, so the wallet has no outcome to report: a resolved mutation means the screen was shown and closed, not that funds arrived.

Mutation Variables

When calling mutate(), you can optionally pass an object with the following properties:

chainId (optional)

Type: number

Chain the QR code pins via EIP-681, and on its own the only chain offered — chainId: base.id shows Base and nothing else. Defaults to the first entry of chains, then the connected chain. Nothing is sent, so the connector does not need to be on this chain.

chains (optional)

Type: number[]

Chains your app accepts deposits on. The chain row on the screen shows exactly these instead of every chain the address works on.

Worth sending whenever your app only credits deposits on certain networks: the default is true of a smart account, but it invites a deposit your app will not see. Order it with your primary chain first — that is the one the QR code pins when no chainId comes with it. An empty array is rejected rather than read as "no preference".

If you pass chainId as well, it must be one of chains — a QR code pinned to a chain your own list excludes is rejected rather than resolved silently.

address (optional)

Type: Address

Which connected account to act as, as in the other actions. This is not a destination: the address funds are received at is always the connected account, resolved by the wallet from the session.

connector (optional)

Type: Connector

Specific connector to use. If omitted, uses the active connector.

Examples

Basic Usage

import { useAccount } from 'wagmi';
import { useAddFunds } from '@jaw.id/wagmi';
 
function AddFundsButton() {
  const { isConnected } = useAccount();
  const { mutate: addFunds, isPending } = useAddFunds();
 
  if (!isConnected) return null;
 
  return (
    <button onClick={() => addFunds({})} disabled={isPending}>
      Add funds
    </button>
  );
}

Pin the QR Code to a Chain

import { useAddFunds } from '@jaw.id/wagmi';
import { base } from 'viem/chains';
 
function FundOnBase() {
  const { mutate: addFunds } = useAddFunds();
 
  return <button onClick={() => addFunds({ chainId: base.id })}>Add funds on Base</button>;
}

Narrow the Chains You Accept

import { useAddFunds } from '@jaw.id/wagmi';
import { base, optimism } from 'viem/chains';
 
function FundOnBaseOnly() {
  const { mutate: addFunds } = useAddFunds();
 
  // One chain: the row shows Base alone, and the QR code pins it.
  return <button onClick={() => addFunds({ chains: [base.id] })}>Add funds</button>;
}
 
function FundOnEither() {
  const { mutate: addFunds } = useAddFunds();
 
  // Several: the row shows exactly these two, Base first and pinned.
  return <button onClick={() => addFunds({ chains: [base.id, optimism.id] })}>Add funds</button>;
}

With Callbacks

import { useAccount } from 'wagmi';
import { useAddFunds, useGetAssets } from '@jaw.id/wagmi';
 
function FundAndRefresh() {
  const { address } = useAccount();
  const { refetch } = useGetAssets({ account: address });
 
  const { mutate: addFunds } = useAddFunds({
    mutation: {
      // Fires when the screen closes, which is not the same as funds landing.
      onSuccess: () => refetch(),
    },
  });
 
  return <button onClick={() => addFunds({})}>Add funds</button>;
}

Behavior

• Opens the receive screen: the address, its ENS name and avatar when they resolve, and the chains it accepts deposits on — the ones in chains, or every mainnet the address works on when you send none
• The QR code encodes an EIP-681 payment request, ethereum:<address>@<chainId>, so a scanner selects the network itself
• Resolves when the user closes the screen. Closing is a normal finish, not a rejection
• Reads no balances and polls for nothing

Important Notes

Related

• useGetAssets - Read token balances after funding
• useCapabilities - Chains and their metadata
• wallet_addFunds - RPC method reference