Aptos Blockchain MCP

Instructions

Implementation Reference

• src/tools/account/fundAccount.ts:30-54 (handler)

  The main handler function for the 'fund_account' tool. It validates input arguments using isFundAccountArgs, calls performFundAccount to execute the funding, and returns a formatted success or error response.

  export async function fundAccountHandler(args: Record<string, any> | undefined) {
    if (!isFundAccountArgs(args)) {
      throw new Error("Invalid arguments for fund_account");
    }
  
    const { account_address, amount = 1 } = args;
  
    try {
      const results = await performFundAccount(account_address, amount);
      return {
        content: [{ type: "text", text: results }],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error funding account: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/account/fundAccount.ts:5-23 (schema)

  The Tool definition object for 'fund_account', including name, description, and input schema for validation.

  export const FUND_ACCOUNT: Tool = {
    name: "fund_account",
    description: "Fund an Aptos account using the testnet faucet. This is only available on testnet and is used to add APT tokens to an account for testing purposes. Returns the funding transaction details.",
    inputSchema: {
      type: "object",
      properties: {
        account_address: {
          type: "string",
          description: "Aptos account address to fund, e.g., 0x1 or 0x742d35Cc6634C0532925a3b8D6Ac0C4db9c8b3",
        },
        amount: {
          type: "number",
          description: "Amount of APT to fund (optional, defaults to 1 APT)",
          default: 1,
        },
      },
      required: ["account_address"],
    },
  };

• src/tools/account/fundAccount.ts:62-102 (helper)

  Core helper function that performs the actual account funding using Aptos client faucet, handles testnet check, amount conversion, and error cases with specific messages.

  export async function performFundAccount(accountAddress: string, amount: number = 1): Promise<string> {
    try {
      if (!isTestnet()) {
        throw new Error("Account funding is only available on testnet");
      }
  
      const aptos = getAptosClient();
      
      // Convert APT to Octas (1 APT = 10^8 Octas)
      const amountOctas = Math.floor(amount * 100000000);
      
      // Fund the account using the faucet
      const txns = await aptos.fundAccount({
        accountAddress,
        amount: amountOctas,
      });
  
      // Get the first transaction hash
      const txHash = Array.isArray(txns) ? txns[0] : txns;
  
      return `Account Funding Successful:
  Account: ${formatAddress(accountAddress)}
  Amount: ${amount} APT (${amountOctas} Octas)
  Transaction Hash: ${txHash}
  
  ✅ Account has been funded and is ready for transactions!`;
    } catch (error) {
      console.error('Error funding account:', error);
      
      if (error instanceof Error) {
        if (error.message.includes('faucet')) {
          throw new Error("Faucet service is unavailable. Please try again later or use a different faucet.");
        }
        if (error.message.includes('rate limit')) {
          throw new Error("Faucet rate limit exceeded. Please wait before requesting more funds.");
        }
      }
      
      throw new Error(`Failed to fund account: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:37-57 (registration)

  Registration of the FUND_ACCOUNT tool in the pre-defined TOOLS_LIST array used for listTools requests in the main stdio server.

  const TOOLS_LIST = [
    // Account tools
    CREATE_ACCOUNT,
    GET_ACCOUNT_INFO,
    FUND_ACCOUNT,
  
    // Native APT tools
    GET_APT_BALANCE,
    TRANSFER_APT,
  
    // Coin tools
    GET_COIN_BALANCE,
    TRANSFER_COIN,
    DEPLOY_COIN,
    MINT_COIN,
    REGISTER_COIN,
  
    // Transaction tools
    GET_TRANSACTION_STATUS,
    GET_ACCOUNT_TRANSACTIONS,
  ];

• src/http-server.ts:82-94 (registration)

  Registration of the FUND_ACCOUNT tool in the tools list for ListToolsRequestSchema handler in the HTTP server.

  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      CREATE_ACCOUNT,
      GET_ACCOUNT_INFO,
      FUND_ACCOUNT,
      GET_APT_BALANCE,
      TRANSFER_APT,
      GET_COIN_BALANCE,
      TRANSFER_COIN,
      GET_TRANSACTION_STATUS,
      GET_ACCOUNT_TRANSACTIONS,
    ],
  }));