Hook

useTokenSafety

Loads token metadata and exposes normalized safe, caution, danger, and unknown states for financial UI.

Installation

terminal

$npx shadcn@latest add https://uxdotsol.xyz/r/use-token-safety.json

Usage

usage

"use client";
 
import { useTokenSafety } from "@/hooks/uxdotsol/use-token-safety";
 
export function TokenSafetyDisclosure({ mint }: { mint: string }) {
  const safety = useTokenSafety(mint);
 
  if (safety.isLoading) return <p>Checking token...</p>;
  if (safety.status === "not-found") return <p>Token information unavailable.</p>;
  if (safety.error) {
    return <button onClick={safety.refetch}>Retry safety check</button>;
  }
 
  return (
    <section aria-live="polite">
      <p>Risk: {safety.risk}</p>
      <ul>
        {safety.reasons.map((reason) => (
          <li key={reason.code}>{reason.message}</li>
        ))}
      </ul>
    </section>
  );
}

.env.local

JUPITER_API_KEY=your_server_side_key

Options

Name	Type	Default	Description
mint	string \| null \| undefined	required	Solana token mint to assess. Empty values keep the hook idle.
adapter	TokenSafetyAdapter	same-origin HTTP adapter	Optional provider adapter implementing getToken. Use this to replace the bundled endpoint.
endpoint	string	'/api/token-safety'	Same-origin endpoint used by the default HTTP adapter.
assess	TokenSafetyAssessor	assessTokenSafety	Optional policy function for converting normalized metadata into risk and reasons.
enabled	boolean	true	Disables requests and returns the idle state when false.
fetcher / headers	typeof fetch / HeadersInit	fetch / undefined	Optional HTTP overrides for the default adapter.

Functions

Name	Type	Default	Description
refetch	() => void	-	Repeats the current token lookup.
assessTokenSafety	(token: TokenSafetyToken) => TokenSafetyAssessment	-	Default explainable policy. Suspicious or banned tokens are danger; other detected risks are caution.
createTokenSafetyHttpAdapter	(config?) => TokenSafetyAdapter	-	Creates a same-origin adapter with endpoint, fetch and header overrides.

Types

Name	Type	Default	Description
TokenSafetyRisk	'safe' \| 'caution' \| 'danger' \| 'unknown'	-	Small risk vocabulary designed for disclosure UI.
TokenSafetyReason	{ code; severity; message }	-	Explainable signal that can be rendered directly or mapped to product copy.
TokenSafetyAdapter	{ getToken(mint, context?): Promise<TokenSafetyToken \| null> }	-	Provider boundary used to replace Jupiter or the bundled server route.

Returns

Name	Type	Default	Description
risk / reasons	TokenSafetyRisk / TokenSafetyReason[]	'unknown' / []	Normalized risk state and its supporting explanations.
token	TokenSafetyToken \| null	null	Normalized token identity, verification, audit, activity, liquidity, and holder data.
status / isLoading	TokenSafetyStatus / boolean	'idle' / false	Request lifecycle state.
isVerified / isSuspicious	boolean / boolean	false / false	Convenience values for common disclosure branches.
error	Error \| null	null	Network or invalid-response error.