useToken()

function useToken(address?): UseTokenResult;

Resolves an ERC-20’s identity and display metadata.

undefined means no address was supplied or the read has not completed; null means the completed read did not find an ERC-20 at that address.

Token metadata does not change, so a resolved token is held fresh for 24 hours and is never re-read on an interval.

Parameters

Parameter	Type	Description
address?	`0x${string}`	ERC-20 to resolve. Omit to leave the hook idle — no query is created and no cache entry is written.

Returns

UseTokenResult

The read envelope. data distinguishes “not read yet” (undefined) from “no ERC-20 at that address” (null); isLoading and error report request state, and retry re-runs the latest request.

Throws

Error when rendered outside <AnvilProvider>, by way of useAnvilSDK.

Example

export function TokenLabel({ address }: { address?: Address }) {
  const { data: token, isLoading, error, retry } = useToken(address);

  if (isLoading) return <span>Loading…</span>;
  if (error) return <button onClick={retry}>Retry</button>;
  // `undefined`: no address yet. `null`: no ERC-20 at that address.
  if (token === undefined) return <span>Pick a token</span>;
  if (token === null) return <span>Not an ERC-20</span>;
  return <span>{token.symbol}</span>;
}