useGrantPermissions

Hook to grant permissions to a spender address.

Type: hook

Import

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

Signature

function useGrantPermissions(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:

Property	Type	Description
`mutate`	`function`	Function to grant permissions
`mutateAsync`	`function`	Async version of mutate
`data`	`WalletGrantPermissionsResponse`	Granted permission details
`isPending`	`boolean`	Whether granting is in progress
`isSuccess`	`boolean`	Whether granting succeeded
`isError`	`boolean`	Whether granting failed
`error`	`Error`	Error if granting failed

data

When successful, data contains:

interface WalletGrantPermissionsResponse {
  /** Smart account this permission is valid for */
  account: Address;
  /** Entity that can use this permission */
  spender: Address;
  /** Timestamp when permission becomes valid */
  start: number;
  /** Timestamp when permission expires */
  end: number;
  /** Salt for uniqueness */
  salt: Hex;
  /** Array of call permissions */
  calls: CallPermissionDetail[];
  /** Array of spend permissions */
  spends: SpendPermissionDetail[];
  /** Permission identifier (hash) */
  permissionId: Hex;
  /** Chain ID in hex */
  chainId: Hex;
}

Mutation Variables

When calling mutate(), pass:

expiry

Type: number (required)

Unix timestamp (in seconds) when the permission expires.

spender

Type: Address (required)

The address that can use this permission to execute calls on behalf of the account.

permissions

Type: PermissionsDetail (required)

The permissions to grant:

interface PermissionsDetail {
  /** Call permissions - which contracts and functions can be called */
  calls?: CallPermissionDetail[];
  /** Spend permissions - token spending limits */
  spends?: SpendPermissionDetail[];
}
 
interface CallPermissionDetail {
  /** Target contract address */
  target: Address;
  /** Function selector (4 bytes) or signature */
  selector: Hex;
}
 
interface SpendPermissionDetail {
  /** Token address (use 0xEee...EEeE for native ETH) */
  token: Address;
  /** Maximum amount per period */
  limit: string;
  /** Time period for the limit */
  period: 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
}

Optional Parameters

Parameter	Type	Description
`address`	`Address`	Specific account address
`chainId`	`number`	Specific chain ID
`connector`	`Connector`	Specific connector

Examples

Basic Usage

import { useGrantPermissions } from '@jaw.id/wagmi';
 
function GrantPermissionButton() {
  const { mutate: grant, isPending, data } = useGrantPermissions();
 
  const handleGrant = () => {
    grant({
      expiry: Math.floor(Date.now() / 1000) + 86400 * 7, // 1 week
      spender: '0xAutomatedBot...',
      permissions: {
        calls: [
          {
            target: ROUTER_ADDRESS,
            selector: '0x38ed1739', // swapExactTokensForTokens
          },
        ],
        spends: [
          {
            token: USDC_ADDRESS,
            limit: '500000000', // 500 USDC
            period: 'week',
          },
        ],
      },
    });
  };
 
  return (
    <div>
      <button onClick={handleGrant} disabled={isPending}>
        {isPending ? 'Granting...' : 'Grant Permission'}
      </button>
      {data && <p>Permission ID: {data.permissionId}</p>}
    </div>
  );
}

With Callbacks

import { useGrantPermissions } from '@jaw.id/wagmi';
 
function GrantWithCallbacks() {
  const { mutate: grant } = useGrantPermissions({
    mutation: {
      onSuccess: (data) => {
        console.log('Permission granted:', data.permissionId);
        // Store permission ID for later revocation
      },
      onError: (error) => {
        console.error('Failed to grant permission:', error);
      },
    },
  });
 
  // ...
}

Daily Spending Limit

import { useGrantPermissions } from '@jaw.id/wagmi';
import { parseUnits } from 'viem';
 
function DailySpendingLimit() {
  const { mutate: grant, isPending } = useGrantPermissions();
 
  const handleGrant = () => {
    grant({
      expiry: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days
      spender: '0xSubscriptionService...',
      permissions: {
        calls: [
          {
            target: USDC_ADDRESS,
            selector: '0xa9059cbb', // transfer
          },
        ],
        spends: [
          {
            token: USDC_ADDRESS,
            limit: parseUnits('100', 6).toString(), // 100 USDC per day
            period: 'day',
          },
        ],
      },
    });
  };
 
  return (
    <button onClick={handleGrant} disabled={isPending}>
      Allow $100/day Subscription
    </button>
  );
}

Use Cases

Session Keys - Allow a temporary key to perform specific actions
Subscription Services - Grant recurring spending permissions
Automated Trading - Allow a bot to execute specific trades
Gaming - Let a game contract execute moves without prompts
DeFi Automation - Enable auto-compounding or limit orders

usePermissions - Get current permissions
useRevokePermissions - Revoke a permission
wallet_grantPermissions - RPC method reference