AgentWallet MCP Server

Instructions

Implementation Reference

• src/index.ts:719-759 (registration)

  Registration of the 'get_allowance' tool using server.tool() with the tool name, description, and zod schema defining the input parameters (wallet_id, token, spender, chain_id, decimals).

  // ─── Tool: get_allowance ────────────────────────────────────────
  
  server.tool(
    'get_allowance',
    'Check how many ERC-20 tokens a spender is approved to transfer. ' +
      'Returns the allowance in both raw and human-readable format. ' +
      'Use this to check if an approval is needed before a DeFi transaction.',
    {
      wallet_id: z.number().int().describe('Wallet ID (used to determine the owner address)'),
      token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
      spender: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Spender contract address to check'),
      chain_id: z.number().int().describe('Chain ID'),
      decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
    },
    async ({ wallet_id, token, spender, chain_id, decimals }) => {
      if (isSolanaChain(chain_id)) {
        throw new Error('get_allowance is not supported on Solana. Solana SPL tokens do not use ERC-20 style allowances.');
      }
      // First get the wallet address
      const wallet = await api(`/wallets/${wallet_id}`) as { address: string };
  
      // allowance(address owner, address spender) — selector: 0xdd62ed3e
      const calldata = '0xdd62ed3e' + padAddress(wallet.address) + padAddress(spender);
  
      const result = await api('/eth-call', 'POST', { chain_id, to: token, data: calldata }) as { result: string };
  
      // Parse uint256 result
      const rawHex = result.result.replace('0x', '');
      const raw = BigInt('0x' + (rawHex || '0')).toString();
      const maxUint256 = (BigInt(2) ** BigInt(256) - BigInt(1)).toString();
  
      return jsonResponse({
        token,
        spender,
        allowance_raw: raw,
        allowance: raw === maxUint256 ? 'unlimited' : formatUnits(raw, decimals),
        is_unlimited: raw === maxUint256,
        decimals,
      });
    },
  );

• src/index.ts:733-758 (handler)

  The handler function for get_allowance that: (1) checks if chain is Solana and throws error, (2) fetches wallet address via API, (3) constructs ERC-20 allowance(address,address) calldata, (4) makes eth_call to get allowance value, (5) parses and formats the result returning allowance_raw, allowance (human-readable), and is_unlimited flag.

  async ({ wallet_id, token, spender, chain_id, decimals }) => {
    if (isSolanaChain(chain_id)) {
      throw new Error('get_allowance is not supported on Solana. Solana SPL tokens do not use ERC-20 style allowances.');
    }
    // First get the wallet address
    const wallet = await api(`/wallets/${wallet_id}`) as { address: string };
  
    // allowance(address owner, address spender) — selector: 0xdd62ed3e
    const calldata = '0xdd62ed3e' + padAddress(wallet.address) + padAddress(spender);
  
    const result = await api('/eth-call', 'POST', { chain_id, to: token, data: calldata }) as { result: string };
  
    // Parse uint256 result
    const rawHex = result.result.replace('0x', '');
    const raw = BigInt('0x' + (rawHex || '0')).toString();
    const maxUint256 = (BigInt(2) ** BigInt(256) - BigInt(1)).toString();
  
    return jsonResponse({
      token,
      spender,
      allowance_raw: raw,
      allowance: raw === maxUint256 ? 'unlimited' : formatUnits(raw, decimals),
      is_unlimited: raw === maxUint256,
      decimals,
    });
  },

• src/index.ts:726-732 (schema)

  Zod schema definition for get_allowance tool inputs: wallet_id (int), token (0x-prefixed 40-char hex), spender (0x-prefixed 40-char hex), chain_id (int), and decimals (int, default 18).

  {
    wallet_id: z.number().int().describe('Wallet ID (used to determine the owner address)'),
    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
    spender: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Spender contract address to check'),
    chain_id: z.number().int().describe('Chain ID'),
    decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
  },