Aptos Blockchain MCP

Instructions

Implementation Reference

• src/tools/coin/registerCoin.ts:31-55 (handler)

  Main handler function for the 'register_coin' tool. Validates input arguments and orchestrates the registration process by calling performRegisterCoin.

  export async function registerCoinHandler(args: Record<string, any> | undefined) {
    if (!isRegisterCoinArgs(args)) {
      throw new Error("Invalid arguments for register_coin");
    }
  
    const { coin_type, max_gas_amount = 1000 } = args;
  
    try {
      const results = await performRegisterCoin(coin_type, max_gas_amount);
      return {
        content: [{ type: "text", text: results }],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error registering for coin: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/coin/registerCoin.ts:6-24 (schema)

  Tool schema definition for 'register_coin', including input schema with coin_type (required) and optional max_gas_amount.

  export const REGISTER_COIN: Tool = {
    name: "register_coin",
    description: "Register your account to receive a specific coin type. This is required before you can receive transfers of custom coins on Aptos. Returns the registration transaction details.",
    inputSchema: {
      type: "object",
      properties: {
        coin_type: {
          type: "string",
          description: "The coin type identifier to register for (e.g., '0x123::coin::T')",
        },
        max_gas_amount: {
          type: "number",
          description: "Maximum gas amount for the transaction (optional)",
          default: 1000,
        },
      },
      required: ["coin_type"],
    },
  };

• src/tools/coin/registerCoin.ts:63-177 (helper)

  Core helper function implementing the coin registration logic: validates inputs, checks existing registration, builds and submits the managed_coin::register transaction.

  export async function performRegisterCoin(
    coinType: string,
    maxGasAmount: number = 1000
  ): Promise<string> {
    try {
      const aptos = getAptosClient();
      const account = getDefaultAccount();
      const accountAddress = account.accountAddress.toString();
  
      // Validate inputs
      if (!coinType || coinType.trim().length === 0) {
        throw new Error("Coin type cannot be empty");
      }
  
      // Validate coin type format
      if (!coinType.match(/^0x[a-fA-F0-9]+::[a-zA-Z_][a-zA-Z0-9_]*::[a-zA-Z_][a-zA-Z0-9_]*$/)) {
        throw new Error("Invalid coin type format. Expected format: 0xADDRESS::module::Type");
      }
  
      // Check if already registered
      try {
        const balance = await aptos.getAccountCoinAmount({
          accountAddress,
          coinType: coinType as `${string}::${string}::${string}`,
        });
        
        // If we can get the balance, the account is already registered
        return `📋 Coin Registration Status:
  Account: ${formatAddress(accountAddress)}
  Coin Type: ${coinType}
  Status: ✅ Already registered
  Current Balance: ${balance}
  
  ℹ️  Your account is already registered for this coin type and can receive transfers.`;
      } catch (error) {
        // If we can't get the balance, the account is not registered yet
        // This is expected, so we continue with registration
      }
  
      // Build the registration transaction
      const transaction = await aptos.transaction.build.simple({
        sender: account.accountAddress,
        data: {
          function: "0x1::managed_coin::register",
          typeArguments: [coinType],
          functionArguments: [],
        },
        options: {
          maxGasAmount,
        },
      });
  
      // Sign and submit the transaction
      const committedTxn = await aptos.signAndSubmitTransaction({
        signer: account,
        transaction,
      });
  
      // Wait for transaction confirmation
      const executedTxn = await aptos.waitForTransaction({
        transactionHash: committedTxn.hash,
      });
  
      let result = `🪙 Coin Registration Successful!
  
  Registration Details:
  Account: ${formatAddress(accountAddress)}
  Coin Type: ${coinType}
  Status: ✅ Successfully registered
  
  Transaction Information:
  Transaction Hash: ${committedTxn.hash}
  Gas Used: ${executedTxn.gas_used}
  Status: ${executedTxn.success ? 'Success' : 'Failed'}`;
  
      // Note: Coin info details are not available in current SDK version
  
      result += `
  
  📋 Next Steps:
  1. You can now receive transfers of this coin type
  2. Check your balance using get_coin_balance
  3. Transfer these coins using transfer_coin
  4. Others can now send you this coin type
  
  ⚠️  Important Notes:
  - Registration is a one-time process per coin type
  - You need to register for each custom coin you want to receive
  - APT (native Aptos coin) doesn't require registration
  - Keep some APT for transaction fees
  
  ✅ Your account is now ready to receive ${coinType}!`;
  
      return result;
    } catch (error) {
      console.error('Error registering for coin:', error);
      
      if (error instanceof Error) {
        if (error.message.includes('insufficient')) {
          throw new Error("Insufficient APT balance to pay for registration transaction fees");
        }
        if (error.message.includes('already registered')) {
          throw new Error("Account is already registered for this coin type");
        }
        if (error.message.includes('not found')) {
          throw new Error("Coin type not found. Make sure the coin has been deployed and the type is correct.");
        }
        if (error.message.includes('invalid')) {
          throw new Error("Invalid coin type format or coin type does not exist");
        }
      }
      
      throw new Error(`Failed to register for coin: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:134-135 (registration)

  Registration in the main tool dispatcher switch statement, mapping 'register_coin' to its handler.

  case "register_coin":
    return await registerCoinHandler(args);

• src/index.ts:52-52 (registration)

  Inclusion of REGISTER_COIN in the TOOLS_LIST array for tool discovery.

  REGISTER_COIN,

• src/tools/coin/registerCoin.ts:184-195 (schema)

  Type guard function for validating register_coin arguments at runtime.

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