usePermissions

Hook to get the current permissions for the connected account. Automatically updates when permissions change.

Type: hook

Import

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

Signature

function usePermissions(parameters?: {
  address?: Address;
  chainId?: number;
  connector?: Connector;
  config?: Config;
  query?: UseQueryParameters;
}): UseQueryResult

Parameters

address

Type: Address (optional)

Specific account address to get permissions for. Defaults to connected account.

chainId

Type: number (optional)

Specific chain ID. Defaults to current chain.

connector

Type: Connector (optional)

Specific connector to use. Defaults to active connector.

config

Type: Config (optional)

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

query

Type: UseQueryParameters (optional)

TanStack React Query options (excluding gcTime and staleTime which are managed internally).

Returns

Returns a TanStack React Query result:

Property	Type	Description
`data`	`WalletGetPermissionsResponse`	Array of permissions
`isLoading`	`boolean`	Whether initial load is in progress
`isFetching`	`boolean`	Whether any fetch is in progress
`isSuccess`	`boolean`	Whether query succeeded
`isError`	`boolean`	Whether query failed
`error`	`Error`	Error if query failed
`refetch`	`function`	Manually refetch permissions

data

When successful, data is an array of permissions:

type WalletGetPermissionsResponse = Permission[];
 
interface Permission {
  /** Permission identifier (hash) */
  id: Hex;
  /** Smart account address */
  account: Address;
  /** Spender address */
  spender: Address;
  /** Start timestamp */
  start: number;
  /** Expiry timestamp */
  expiry: number;
  /** Call permissions */
  calls: CallPermissionDetail[];
  /** Spend permissions */
  spends: SpendPermissionDetail[];
}

Behavior

Auto-enables when wallet is connected
Listens for changes via permissionsChanged event
Auto-refetches when permissions change on-chain
Caches indefinitely until invalidated by events

Examples

Basic Usage

import { useAccount } from 'wagmi';
import { usePermissions } from '@jaw.id/wagmi';
 
function PermissionsList() {
  const { isConnected } = useAccount();
  const { data: permissions, isLoading } = usePermissions();
 
  if (!isConnected) return <p>Connect wallet to view permissions</p>;
  if (isLoading) return <p>Loading permissions...</p>;
 
  if (!permissions?.length) {
    return <p>No active permissions</p>;
  }
 
  return (
    <ul>
      {permissions.map((permission) => (
        <li key={permission.id}>
          <p>Spender: {permission.spender}</p>
          <p>Expires: {new Date(permission.expiry * 1000).toLocaleString()}</p>
          <p>Calls: {permission.calls.length}</p>
          <p>Spends: {permission.spends.length}</p>
        </li>
      ))}
    </ul>
  );
}

For Specific Address

import { usePermissions } from '@jaw.id/wagmi';
 
function PermissionsForAddress({ address }: { address: `0x${string}` }) {
  const { data: permissions } = usePermissions({ address });
 
  // ...
}

Disable Auto-Fetch

import { usePermissions } from '@jaw.id/wagmi';
 
function ManualPermissions() {
  const { data, refetch } = usePermissions({
    query: {
      enabled: false, // Don't fetch automatically
    },
  });
 
  return (
    <div>
      <button onClick={() => refetch()}>Load Permissions</button>
      {data && <p>{data.length} permissions found</p>}
    </div>
  );
}

useGrantPermissions - Grant new permissions
useRevokePermissions - Revoke a permission
wallet_getPermissions - RPC method reference