Skip to main content

Self-custody guide

Beginner
Tutorial

Overview​

Within the Internet Computer ecosystem, Internet Computer Protocol tokens (ICP tokens) are a native utility token. ICP tokens play a key role in both the governance and economics of the Internet Computer.

This self-custody guide scenario assumes:

  • You are a new ICP token holder.

  • You want to understand what you can do with your ICP tokens.

  • You want to know how to convert, transfer, or lock your ICP tokens using the SDK command-line interface dfx.

If you aren’t yet a token holder, you’ll need to purchase ICP tokens from an exchange or receive a token grant before you can take custody. For an overview of how to get ICP tokens and custody options, see how you can get ICP tokens and choosing self-custody for digital assets.

If you are using another application—such as the Network Nervous System (NNS) application or the user interface provided by a hardware wallet—to interact with your ICP tokens, you should refer to the documentation for that application.

This self-custody guide focuses solely on interacting with ICP tokens using the SDK command-line interface dfx.

How you can use ICP tokens​

The following diagram provides a simplified overview of the three most common ways you can use tokens.

developers guide:icp tokens how to use

As this diagram suggests, how you use ICP tokens depends primarily on your goals in acquiring them.

If you are a developer or entrepreneur, ICP tokens can be converted to cycles. Cycles can then be used to build and deploy applications to deliver products and services to the market.

If you are a member of the community interested in participating in governance and influencing the direction of the Internet Computer, you can lock up ICP tokens in a stake—called a neuron—so that you can submit and vote on proposals.

Prerequisites​

To get started, verify the following:

  • You have an internet connection and access to a shell terminal on your local Intel-based macOS or Linux computer.

  • You know how to open a new terminal shell on your local computer and how to run basic command-line programs in the terminal.

  • You hold ICP tokens in a self-custody wallet.

  • You have downloaded and installed the SDK by running the following command in a terminal on your local computer:

    sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

  • You have created a backup copy of the public/private key for the identity you are using for self-custody.

    For example, if you are using the default developer identity created using the SDK dfx command-line interface, you should have a backup of the ~/.config/dfx/identity/default/identity.pem file stored in a secure location.

  • You have a secure environment in which to perform operations involving ICP tokens.

As a security best practice, any operations that involve the transfer of ICP tokens would require both an air-gapped computer with minimal hardware and software and a computer connected to the network. In practice, this requires moving files between two computers and taking other precautions to minimize risks.

For simplicity, this page describes how to complete key tasks using a single computer connected to the network.

Connect to a ledger and get your account identifier​

All ICP token transactions are recorded in a ledger canister running on the Internet Computer. These instructions assume that you are using the default developer identity that dfx has created for you.

This identity is represented by a principal data type and a textual representation of the principal often referred to as your principal identifier. This representation of your identity is similar to a Bitcoin or Ethereum address.

However, the principal associated with your developer identity is typically not the same as your account identifier in the ledger. The principal identifier and the account identifier are related; both provide a textual representation of your identity, but they use different formats.

To connect to the ledger and get account information:

  • Step 1: Create an empty dfx.json file in your current directory by running the following command:​

echo '{}' > dfx.json

  • Step 2: Check the current status of the Internet Computer network and your ability to connect to it by running the following command:​

dfx ping ic

You should see output similar to the following:

{
    "ic_api_version": "0.18.0"  "impl_hash": "d639545e0f38e075ad240fd4ec45d4eeeb11e1f67a52cdd449cd664d825e7fec"  "impl_version": "8dc1a28b4fb9605558c03121811c9af9701a6142"  "replica_health_status": "healthy"  "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 129, 76, 14, 110, 199, 31, 171, 88, 59, 8, 189, 129, 55, 60, 37, 92, 60, 55, 27, 46, 132, 134, 60, 152, 164, 241, 224, 139, 116, 35, 93, 20, 251, 93, 156, 12, 213, 70, 217, 104, 95, 145, 58, 12, 11, 44, 197, 52, 21, 131, 191, 75, 67, 146, 228, 103, 219, 150, 214, 91, 155, 180, 203, 113, 113, 18, 248, 71, 46, 13, 90, 77, 20, 80, 95, 253, 116, 132, 176, 18, 145, 9, 28, 95, 135, 185, 136, 131, 70, 63, 152, 9, 26, 11, 170, 174]
}

  • Step 3: (Optional) Confirm the developer identity you are currently using by running the following command:​

dfx identity whoami

In most cases, you should see that you are currently using your default developer identity. For example:

default

  • Step 4: (Optional) View the textual representation of the principal for your current identity by running the following command:​

dfx identity get-principal

This command displays output similar to the following:

tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe

  • Step 5: Get the account identifier for your developer identity by running the following command:​

dfx ledger account-id

This command displays the ledger account identifier associated with your developer identity. For example, you should see output similar to the following:

03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223

  • Step 6: Check your account balance by running the following command:​

dfx ledger --network ic balance

This command displays the ICP token balance from the ledger account. For example, you should see output similar to the following:

10.00000000 ICP

Convert ICP tokens to cycles​

If you want to use your ICP tokens in your ledger account to power application development, you first must convert them to cycles.

To convert ICP tokens to cycles:

With those ICP tokens ready, you can now convert them into cycles using the following command:

dfx cycles convert AMOUNT --network ic

This workflow utilizes the cycles ledger feature. If you'd like to use the cycles wallet instead, view the cycles wallet documentation.

Please note that the cycles wallet will be removed from dfx in a future release.

Then, check the cycles balance with the command:

dfx cycles balance --network ic

This should print something looking like this:

6.951 TC (trillion cycles).

Transfer ICP tokens to another account​

If you want to transfer ICP tokens to another account in the ledger, you need to know the account identifier for the destination account.

To transfer ICP tokens to another account:

  • Step 1: Check that you are using an identity with control over the ledger account by running the following command:​

dfx identity whoami

  • Step 2: Check the current balance in the ledger account associated with your identity by running the following command:​

dfx ledger --network ic balance

  • Step 3: Transfer ICP tokens to another account by running a command similar to the following:​

dfx ledger --network ic transfer <destination-ledger-account-id> --icp <ICP-amount> --memo <numeric-memo>

For example:

dfx ledger --network ic transfer ae6e1a76da5725bbbf0c5c035aaf0525b791e0f0f7cce27d8e27826389871406 --icp 5 --memo 12345

This example illustrates how to transfer ICP tokens to the specified account using a whole number with the --icp command-line option.

  • You can also specify fractional units of ICP tokens—called e8s—using the --e8s option, either on its own or in conjunction with the --icp option.
  • Alternatively, you can use the --amount to specify the number of ICP tokens to transfer with fractional units up to 8 decimal places, for example, as 5.00000025.

The destination address can be an address in the ledger canister running on the Internet Computer network, an account you have added using the Network Nervous System application, or the address for a wallet you have on an exchange.

If you transfer the ICP tokens to an account in the Network Nervous System application, you might need to refresh the browser to see the transaction reflected.

For more information about using the dfx ledger command-line options, see dfx ledger.

Lock ICP tokens by staking them in a neuron​

If you want to lock up ICP tokens to participate in governance and earn rewards, you must use the Network Nervous System (NNS) application or dfx canister call commands.

Because locking up ICP tokens to create staked neurons is a more complex process when using the SDK command-line interface than it is when using the Network Nervous System (NNS) application, the steps aren’t included in this guide.

For information about the Network Nervous System, see understanding the Internet Computer’s Network Nervous System, neurons, and ICP utility tokens.

For additional details about setting the locked period and dissolve delay for a neuron, see the Internet Computer Network Nervous System application and wallet.