azeth_whitelist_token

Manage token whitelist for smart account automated operations. Add or remove tokens to enable payment agreements and executor-module transactions.

Instructions

Add or remove a token from your smart account's guardian whitelist.

Use this when: You need to whitelist a new token for payment agreements or other executor-module operations. Newly created accounts already have ETH, USDC, and WETH whitelisted by default.

Why it matters: The GuardianModule enforces a token whitelist for automated operations (payment agreements, swap execution). Owner-signed transfers bypass the whitelist, but executor modules like PaymentAgreementModule require the token to be whitelisted.

Returns: Transaction hash confirming the whitelist update.

Note: Only the account owner can update their own whitelist.

Example: { "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "allowed": true }

Input Schema

TableJSON Schema

Name	Required	Description
`chain`	No	Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").
`token`	Yes	Token contract address to whitelist/delist. Use "0x0000000000000000000000000000000000000000" for native ETH.
`allowed`	Yes	true to whitelist the token, false to remove it from the whitelist.
`smartAccount`	No	Smart account address, name, or "#N". Defaults to first smart account.

Implementation Reference

src/tools/account.ts:645-693 (handler)

The handler function for 'azeth_whitelist_token' which resolves the smart account, validates the token, and calls client.setTokenWhitelist to update the whitelist status.

async (args) => {
  if (!validateAddress(args.token)) {
    return error('INVALID_INPUT', `Invalid token address: "${args.token}".`, 'Must be 0x-prefixed followed by 40 hex characters.');
  }

  let client;
  try {
    client = await createClient(args.chain);

    let account: `0x${string}`;
    if (args.smartAccount) {
      try {
        account = (await resolveSmartAccount(args.smartAccount, client))!;
      } catch (resolveErr) {
        return handleError(resolveErr);
      }
    } else {
      account = await client.resolveSmartAccount();
    }

    const txHash = await client.setTokenWhitelist(
      args.token as `0x${string}`,
      args.allowed,
      account,
    );

    const action = args.allowed ? 'whitelisted' : 'removed from whitelist';
    // Resolve token symbol for display
    const chain = resolveChain(args.chain);
    const tokens = TOKENS[chain];
    const tokenLower = args.token.toLowerCase();
    let tokenSymbol = args.token.slice(0, 6) + '...' + args.token.slice(-4);
    if (args.token === '0x0000000000000000000000000000000000000000') tokenSymbol = 'ETH';
    else if (tokenLower === tokens.USDC.toLowerCase()) tokenSymbol = 'USDC';
    else if (tokenLower === tokens.WETH.toLowerCase()) tokenSymbol = 'WETH';

    return success(
      {
        token: args.token,
        tokenSymbol,
        allowed: args.allowed,
        message: `${tokenSymbol} (${args.token}) ${action} on account ${account}.`,
      },
      { txHash },
    );
  } catch (err) {
    // Detect AA24 signature validation failure — common for guardian-gated operations
    if (err instanceof Error && /AA24/.test(err.message)) {
      return guardianRequiredError(

src/tools/account.ts:638-643 (schema)

The input schema definition for 'azeth_whitelist_token' using Zod.

inputSchema: z.object({
  chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
  token: z.string().describe('Token contract address to whitelist/delist. Use "0x0000000000000000000000000000000000000000" for native ETH.'),
  allowed: z.boolean().describe('true to whitelist the token, false to remove it from the whitelist.'),
  smartAccount: z.string().optional().describe('Smart account address, name, or "#N". Defaults to first smart account.'),
}),

src/tools/account.ts:619-644 (registration)

The registration of the 'azeth_whitelist_token' tool using the server.registerTool method.

server.registerTool(
  'azeth_whitelist_token',
  {
    description: [
      'Add or remove a token from your smart account\'s guardian whitelist.',
      '',
      'Use this when: You need to whitelist a new token for payment agreements or other executor-module operations.',
      'Newly created accounts already have ETH, USDC, and WETH whitelisted by default.',
      '',
      'Why it matters: The GuardianModule enforces a token whitelist for automated operations',
      '(payment agreements, swap execution). Owner-signed transfers bypass the whitelist,',
      'but executor modules like PaymentAgreementModule require the token to be whitelisted.',
      '',
      'Returns: Transaction hash confirming the whitelist update.',
      '',
      'Note: Only the account owner can update their own whitelist.',
      '',
      'Example: { "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "allowed": true }',
    ].join('\n'),
    inputSchema: z.object({
      chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
      token: z.string().describe('Token contract address to whitelist/delist. Use "0x0000000000000000000000000000000000000000" for native ETH.'),
      allowed: z.boolean().describe('true to whitelist the token, false to remove it from the whitelist.'),
      smartAccount: z.string().optional().describe('Smart account address, name, or "#N". Defaults to first smart account.'),
    }),
  },

mcp-azeth