Aptos Blockchain MCP

Instructions

Implementation Reference

• src/tools/native/transferApt.ts:35-59 (handler)

  The primary handler function for the 'transfer_apt' tool. It validates input arguments, calls the core transfer function, and formats success/error responses.

  export async function transferAptHandler(args: Record<string, any> | undefined) {
    if (!isTransferAptArgs(args)) {
      throw new Error("Invalid arguments for transfer_apt");
    }
  
    const { recipient_address, amount, max_gas_amount = 2000 } = args;
  
    try {
      const results = await performTransferApt(recipient_address, amount, max_gas_amount);
      return {
        content: [{ type: "text", text: results }],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error transferring APT: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/native/transferApt.ts:6-28 (schema)

  Tool schema definition including name, description, and input schema for validation.

  export const TRANSFER_APT: Tool = {
    name: "transfer_apt",
    description: "Transfer native APT tokens to another Aptos account. This is used for sending APT tokens from your account to another address. Returns the transaction hash upon successful transfer.",
    inputSchema: {
      type: "object",
      properties: {
        recipient_address: {
          type: "string",
          description: "Recipient Aptos address, e.g., 0x1 or 0x742d35Cc6634C0532925a3b8D6Ac0C4db9c8b3",
        },
        amount: {
          type: "string",
          description: "Amount of APT to transfer (e.g., '1.5' for 1.5 APT)",
        },
        max_gas_amount: {
          type: "number",
          description: "Maximum gas amount for the transaction (optional)",
          default: 2000,
        },
      },
      required: ["recipient_address", "amount"],
    },
  };

• src/tools/native/transferApt.ts:68-126 (helper)

  Core helper function that performs the actual APT transfer using Aptos SDK: builds, signs, submits transaction, waits for confirmation, and returns formatted results.

  export async function performTransferApt(
    recipientAddress: string,
    amount: string,
    maxGasAmount: number = 2000
  ): Promise<string> {
    try {
      const aptos = getAptosClient();
      const senderAccount = getDefaultAccount();
      
      // Convert APT amount to Octas
      const amountOctas = aptToOctas(amount);
      
      // Build the transfer transaction
      const transaction = await aptos.transaction.build.simple({
        sender: senderAccount.accountAddress,
        data: {
          function: "0x1::aptos_account::transfer",
          functionArguments: [recipientAddress, amountOctas],
        },
        options: {
          maxGasAmount,
        },
      });
  
      // Sign and submit the transaction
      const committedTxn = await aptos.signAndSubmitTransaction({
        signer: senderAccount,
        transaction,
      });
  
      // Wait for transaction confirmation
      const executedTxn = await aptos.waitForTransaction({
        transactionHash: committedTxn.hash,
      });
  
      return `APT Transfer Successful:
  From: ${formatAddress(senderAccount.accountAddress.toString())}
  To: ${formatAddress(recipientAddress)}
  Amount: ${amount} APT (${amountOctas} Octas)
  Transaction Hash: ${committedTxn.hash}
  Gas Used: ${executedTxn.gas_used}
  Status: ${executedTxn.success ? 'Success' : 'Failed'}
  
  ✅ Transfer completed successfully!`;
    } catch (error) {
      console.error('Error transferring APT:', error);
      
      if (error instanceof Error) {
        if (error.message.includes('insufficient')) {
          throw new Error("Insufficient APT balance to complete the transfer");
        }
        if (error.message.includes('invalid')) {
          throw new Error("Invalid recipient address format");
        }
      }
      
      throw new Error(`Failed to transfer APT: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/tools/native/transferApt.ts:133-147 (schema)

  Type guard function for validating input arguments against the tool's schema.

  export function isTransferAptArgs(args: unknown): args is { 
    recipient_address: string; 
    amount: string; 
    max_gas_amount?: number 
  } {
    return (
      typeof args === "object" &&
      args !== null &&
      "recipient_address" in args &&
      typeof (args as any).recipient_address === "string" &&
      "amount" in args &&
      typeof (args as any).amount === "string" &&
      (!(args as any).max_gas_amount || typeof (args as any).max_gas_amount === "number")
    );
  }

• src/index.ts:122-123 (registration)

  Tool registration in the main MCP server switch dispatcher for stdio transport.

  case "transfer_apt":
    return await transferAptHandler(args);