You can perform the following token management operations in Hedera:
- Explicitly associate a list of tokens with a new account.
- Automatically associate new tokens with an account.
- Disassociate tokens from an account.
Each of these operations involves the creation of a transaction order.
You can also issue Hedera tokens with a transfer order or transaction order. Transfer orders are the recommended method for sending assets. For more information, see Send assets.
Before you can send or receive fungible tokens or non-fungible tokens (NFT) with a Hedera account, you need to explicitly associate the tokens with the account. By default, new Hedera accounts are not associated with any tokens, unless a token is used to pre-fund the account when it is initialized and the Hedera account Id is generated.
Learn more about initializing Hedera accounts
All new requests to change the system state follow the same process. To familiarize yourself with this process first, see Manage intents and approvals.
To associate tokens with a Hedera account, follow the steps in Manage intents and approvals, with a transaction order payload similar to the following example.
The following example shows the association of a fungible token of type Ticker and a non-fungible token of type TokenId.
{
"payload": {
"id": "2ea89e96-246a-4458-8e03-1edeb1322690",
"accountId": "5ff7cb0b-ac4e-4e9d-85bc-bd4b027740ce",
"ledgerId": "hedera-testnet-january-2023",
"parameters": {
"operation": {
"tokens": [
{
"tokenId": "0.0.15053490",
"type": "TokenId"
},
{
"tickerId": "0c863615-0b5d-4a23-b5e8-cb39971f154a",
"type": "Ticker"
}
],
"type": "TokenAssociate"
},
"feeStrategy": {
"priority": "Medium",
"type": "Priority"
},
"maximumFee": "100000000",
"type": "Hedera"
},
"description": "Hedera tx",
"customProperties": {},
"type": "v0_CreateTransactionOrder"
}
}Fields of the payload block to note are as follows:
| Field | Description |
|---|---|
accountId | Internal account ID of an existing Hedera account in Ripple Custody. |
operation.tokens | One or more tokens to associate with the account. You can use two different token identifiers:
|
operation.type | TokenAssociate |
parameters.feeStrategy | Fee strategy field included in the transaction order payload. For Hedera, fees are retrieved directly from the chain and customers cannot prioritize the transaction. For more information, see Fee strategy and maximum fee. |
parameters.maximumFee | The maximum fee, in tinybar. For more information, see Fee strategy and maximum fee. |
parameters.type | Ledger type, in this case Hedera. |
type | v0_CreateTransactionOrder |
When the transaction order is successfully approved, Ripple Custody does the following:
- Creates a transaction, to broadcast the token association on the blockchain.
- Creates one or more transfers, to represent the separate amounts associated with the transaction, such as the cryptocurrency amount and the fees.
You can update a Hedera account to automatically associate newly-created tokens with the account. You can set the number of tokens to a number up to 1000. You do not need to associate tokens with the account that mints them, as this association is automatic.
Once the limit of the automatic token associations is reached, to continue associating tokens with the account, perform one of the following:
- Create a new
TokenAssociateoperation including the tokens to be associated. - Create a new
AccountUpdateoperation to increase the value ofmaxAutomaticTokenAssociations.
All new requests to change the system state follow the same process. To familiarize yourself with this process first, see Manage intents and approvals.
To automatically associate tokens with a Hedera account, follow the steps in Manage intents and approvals, with a transaction order payload similar to the following example.
The following example shows the automatic association of up to five tokens with the account.
{
"payload": {
"id": "2ea89e96-246a-4458-8e03-1edeb1322690",
"accountId": "5ff7cb0b-ac4e-4e9d-85bc-bd4b027740ce",
"ledgerId": "hedera-testnet-january-2023",
"parameters": {
"operation": {
"maxAutomaticTokenAssociations": 5,
"type": "AccountUpdate"
},
"feeStrategy": {
"priority": "Medium",
"type": "Priority"
},
"maximumFee": "22991332",
"type": "Hedera"
},
"description": "Hedera tx",
"customProperties": {},
"type": "v0_CreateTransactionOrder"
}
}Fields of the payload block to note are as follows:
| Field | Description |
|---|---|
accountId | Internal account ID of an existing Hedera account in Ripple Custody. |
operation.maxAutomaticTokenAssociations | Number of tokens to automatically associate with the account, between 0 and 1000. |
operation.type | AccountUpdate |
parameters.feeStrategy | Fee strategy field included in the transaction order payload. For Hedera, fees are retrieved directly from the chain and customers cannot prioritize the transaction. For more information, see Fee strategy and maximum fee. |
parameters.maximumFee | The maximum fee, in tinybar. For more information, see Fee strategy and maximum fee. |
type | v0_CreateTransactionOrder |
This transaction does not broadcast successfully if the balance of the associated token in the account is above zero.
All new requests to change the system state follow the same process. To familiarize yourself with this process first, see Manage intents and approvals.
To disassociate tokens from a Hedera account, follow the steps in Manage intents and approvals, with a transaction order payload similar to the following example.
The following example shows the disassociation of a fungible token of type Ticker and a non-fungible token of type TokenId.
{
"payload": {
"id": "d28a2cce-af3d-4a4e-b589-c8d61fd824b8",
"accountId": "5ff7cb0b-ac4e-4e9d-85bc-bd4b027740ce",
"ledgerId": "hedera-testnet-january-2023",
"parameters": {
"operation": {
"tokens": [
{
"tokenId": "0.0.15053490",
"type": "TokenId"
},
{
"tickerId": "0c863615-0b5d-4a23-b5e8-cb39971f154a",
"type": "Ticker"
}
],
"type": "TokenDissociate"
},
"feeStrategy": {
"priority": "Medium",
"type": "Priority"
},
"maximumFee": "208340972",
"type": "Hedera"
},
"description": "Hedera tx",
"customProperties": {},
"type": "v0_CreateTransactionOrder"
}
}Fields of the payload block to note are as follows:
| Field | Description |
|---|---|
accountId | Internal account ID of an existing Hedera account in Ripple Custody. |
operation.tokens | One or more tokens to disassociate from the account. You can use two different token identifiers:
|
operation.type | TokenDissociate |
parameters.feeStrategy | Fee strategy field included in the transaction order payload. For Hedera, fees are retrieved directly from the chain and customers cannot prioritize the transaction. For more information, see Fee strategy and maximum fee. |
parameters.maximumFee | The maximum fee, in tinybar. For more information, see Fee strategy and maximum fee. |
type | v0_CreateTransactionOrder |
When the transaction order is successfully approved, Ripple Custody does the following:
- Creates a transaction, to broadcast the token disassociation on the blockchain.
- Creates one or more transfers, to represent the separate amounts associated with the transaction, such as the cryptocurrency amount and the fees.