Create human-readable names(User Handles)

Once you have purchased a custom domain, you can create human-readable names for your users under your custom domain. These names are also known as User Handles. The User Handles can be used in place of the blockchain addresses in your app to make it easier for users to interact with your app and reduce the risk of errors.


  1. The User Handles can be up to 64 characters long. For more details, please check the FIO documentation.
  2. You should create 1 FIO handle per user. You can create multiple handles for a user, but it's not recommended since it can lead to confusion and errors. For billing, you will be charged the maximum number of handles created or active users, whichever is higher in a month.

Steps to Create a User Handle

1: Check if the handle is available

Before creating the handle, call the FIO availability check API to check if the handle is available. If the handle is available, you can proceed to create the handle.

If the handle is not available, you can suggest alternative handles to the user or ask them to choose a different handle.

2. Get the user's FIO public key

Before creating a User Handle, you will need the user's FIO public key. The FIO public key is used to create the User Handle and map it to the user's blockchain address.

Use the User Wallet API to get the user's wallet and then extract the FIO public key from the wallet.

const userWallet = await
    user: {
      // Email of the user
      email: "[email protected]",
    headers: {
      "Content-Type": "application/json",
      // Replace with your MetaKeep FIO app API key
      "x-api-key": "YOUR_API_KEY_FOR_METAKEEP_FIO_APP",

// Remove "EOS" prefix and prepend "FIO" to convert to FIO public key
const fioPublicKey = "FIO" +;

3. Call the FIO API to create the User Handle

Once you have the user's FIO public key, call the FIO buy handle API to create the handle for the user. You will need an apiToken and a referralCode that will be provided by the FIO team.

© Copyright 2024, Passbird Research Inc.