AgentPay-mcp

Instructions

Implementation Reference

• src/tools/wallet.ts:66-122 (handler)

  The `handleGetWalletInfo` function executes the `get_wallet_info` tool logic, fetching budget forecasts, wallet health, and ETH balances.

  export async function handleGetWalletInfo(
    input: GetWalletInfoInput
  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
    try {
      const wallet = getWallet();
      const config = getConfig();
      const token = (input.token as Address | undefined) ?? NATIVE_TOKEN;
      const tokenLabel = token === NATIVE_TOKEN ? 'ETH' : token;
  
      // Parallel fetches for speed
      const [forecast, health, ethBalance] = await Promise.all([
        getBudgetForecast(wallet, token).catch(() => null),
        getWalletHealth(wallet, [], [token]).catch(() => null),
        wallet.publicClient.getBalance({ address: config.walletAddress }).catch(() => null),
      ]);
  
      const explorerUrl = explorerAddressUrl(config.walletAddress, config.chainId);
      const cname = chainName(config.chainId);
  
      let out = `📊 **Agent Wallet Info**\n\n`;
      out += `📍 Address: ${config.walletAddress}\n`;
      out += `🌐 Chain: ${cname}\n`;
      out += `🔗 Explorer: ${explorerUrl}\n\n`;
  
      if (ethBalance !== null) {
        out += `💰 ETH Balance: ${formatEth(ethBalance)}\n\n`;
      }
  
      if (forecast) {
        const badge = utilizationBadge(forecast.utilizationPercent);
        out += `📈 **Spend Limits (${tokenLabel})**\n`;
        out += `  Per-tx limit:     ${formatSpendLimit(forecast.perTxLimit)}\n`;
        out += `  Period limit:     ${formatSpendLimit(forecast.periodLimit)}\n`;
        out += `  Period spent:     ${formatEth(forecast.periodSpent)}\n`;
        out += `  Remaining:        ${formatEth(forecast.remainingInPeriod)}\n`;
        out += `  Utilization:      ${forecast.utilizationPercent}% ${badge}\n`;
        out += `  Period length:    ${formatDuration(forecast.periodLength)}\n`;
        out += `  Period started:   ${formatTimestamp(forecast.periodStart)}\n`;
        out += `  Resets in:        ${formatDuration(forecast.secondsUntilReset)}\n\n`;
      }
  
      if (health) {
        out += `🔧 **Wallet Health**\n`;
        out += `  NFT contract:     ${health.tokenContract}\n`;
        out += `  NFT token ID:     ${health.tokenId.toString()}\n`;
        out += `  Operator epoch:   ${health.operatorEpoch.toString()}\n`;
        out += `  Pending queue:    ${health.pendingQueueDepth} transaction(s) awaiting approval\n`;
      }
  
      return { content: [textContent(out)] };
    } catch (error: unknown) {
      return {
        content: [textContent(formatError(error, 'get_wallet_info'))],
        isError: true,
      };
    }
  }

• src/tools/wallet.ts:34-45 (schema)

  The `GetWalletInfoSchema` defines the input structure and validation for the tool.

  export const GetWalletInfoSchema = z.object({
    token: z
      .string()
      .optional()
      .describe(
        'Token address to check budget for. ' +
        'Use "0x0000000000000000000000000000000000000000" for ETH (default). ' +
        'Or use a USDC/ERC20 contract address.'
      ),
  });
  
  export type GetWalletInfoInput = z.infer<typeof GetWalletInfoSchema>;

• src/tools/wallet.ts:47-64 (registration)

  The `getWalletInfoTool` constant defines the name, description, and input schema for registration.

  export const getWalletInfoTool = {
    name: 'get_wallet_info',
    description:
      'Get comprehensive wallet information including address, on-chain balance, ' +
      'spend limits, remaining period allowance, and queue depth. ' +
      'Use token parameter to check budget for a specific ERC20 (defaults to ETH).',
    inputSchema: {
      type: 'object' as const,
      properties: {
        token: {
          type: 'string',
          description:
            'Token address to check. Use "0x0000000000000000000000000000000000000000" for ETH (default).',
        },
      },
      required: [],
    },
  };