Hedera Service Solidity Libraries

Hedera Token Service

Hedera Token Service integration allows you to write token transactions natively in Solidity smart contracts. There are a few Solidity source files available to developers.

• HederaTokenService.sol
• HederaResponseCodes.sol
• IHederaTokenService.sol
• ExpiryHelper.sol
• FeeHelper.sol
• KeyHelper.sol

The Hedera Token Service Solidity file provides the transactions to interact with tokens created on Hedera. The Hedera Response Codes contract provides the response codes associated with network errors. The IHedera Token Service is a supporting library for the Hedera Token Service Solidity file. You can grab these libraries here to add to your project and import them to your Solidity contract. Please see the example file below.

ContractExample.sol

// SPDX-License-Identifier: GPL-3.0

pragma solidity >=0.7.0 <0.9.0;

import "./HederaTokenService.sol";
import "./HederaResponseCodes.sol";

contract contractExample is HederaTokenService {
...
int response = HederaTokenService.transferToken(tokenAddress, msg.sender, address(this), amount);
...
}

Note: Although the IHederaTokenService.sol file is not imported in the contract, you will need it in your project directory for the supporting libraries to reference.

HederaTokenService.sol API Docs

Create Tokens

HIP-358: Token create precompile is live on previewnet and testnet. The TokenCreateContract example contains four examples of how to create a token using the token create solidity libraries.

createFungibleToken(token, initialTotalSupply, decimals)

A transaction that creates a fungible token. Returns the new token address.

Param	Type	Description
token	IHederaTokenService.HederaToken memory	The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.
initialTotalSupply	uint	Specifies the initial supply of tokens to be put in circulation. The initial supply is sent to the Treasury Account. The supply is in the lowest denomination possible.
decimals	uint	The number of decimal places a token is divisible by.

createFungibleTokenWithCustomFees(token, initialTotalSupply, decimals, fixedFees, fractionalFees)

A transaction that creates a fungible token with custom fees. Returns the new token address.

Param	Type	Description
token	IHederaTokenService.HederaToken memory	The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.
initialTotalSupply	uint	Specifies the initial supply of tokens to be put in circulation. The initial supply is sent to the Treasury Account. The supply is in the lowest denomination possible.
decimals	uint	The number of decimal places a token is divisible by.
fixedFees	IHederaTokenService.FixedFee[]	List of fixed fees to apply to the token.
fractionalFees	IHederaTokenService.FractionalFee[]	List of fractional fees to apply to the token.

createNonFungibleToken(token)

Creates a non fungible token. Returns the new token address.

Param	Type	Description
token	IHederaTokenService.HederaToken memory	The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.

createNonFungibleTokenWithCustomFees(token, fixedFees, fractionalFees)

Creates a non fungible token with custom fees. Returns the new token address.

Param	Type	Description
token	IHederaTokenService.HederaToken memory	The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.
fixedFees	IHederaTokenService.FixedFee[]	List of fixed fees to apply to the token.
fractionalFees	IHederaTokenService.FractionalFee[]	List of fractional fees to apply to the token.

Transfer Tokens

cryptoTransfer(tokenTransfers)

A transaction that transfers the provided list of tokens.

ABI Version: 2

Param	Type	Description
tokenTransfers	IHederaTokenService.TokenTransferList[] memory	The list of token transfers

transferToken(token, sender, receiver, amount)

Transfers tokens where the calling account/contract is implicitly the first entry in the token transfer list, where the amount is the value needed to zero balance the transfers. The account address sending the token is required to sign the transaction.

ABI Version: 1

Param	Type	Description
token	address	The token ID to transfer to/from. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
sender	address	The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
receiver	address	The address of the receiver of the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amount	int64	Non-negative value of the token to send. A negative value will result in a failure.

transferTokens(token, accountIds, amount)

Initiates a fungible token transfer. This transaction accepts zero unit token transfer operations for fungible tokens (HIP-564). Not applicable to non-fungible tokens.

ABI Version: 1

Param	Type	Description
token	address	The token ID to transfer. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
accountIds	address[] memory	Hedera accounts to do a transfer to/from. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amounts	int64[] memory	Non-negative value to send. A negative value will result in a failure.

transferNFT(token, sender, receiver, serialNum)

Transfers tokens where the calling account/contract is implicitly the first entry in the token transfer list, where the amount is the value needed to zero balance the transfers. The address sending the token is required to sign the transaction.

ABI Version: 1

Param	Type	Description
token	address	The token to transfer to/from.
sender	address	The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
receiver	address	The address of the receiver of the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
serialNum	int64	The serial number of the NFT to transfer.

transferNFTs(token, sender, receiver, serialNumber)

Initiates a non-fungible token transfer

ABI Version: 1

Param	Type	Description
token	address	The ID of the token to transfer. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
sender	address[] memory	The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
receiver	address[] memory	The address of the receiver of the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
serialNumber	int64	The serial number of the NFT is sent by the same index of the sender.

Mint Tokens

mintToken(token, amount, metadata)

Mints an amount of the token to the defined treasury account. This transaction accepts zero-amount token mint operations for fungible tokens (HIP-564).

ABI Version: 2

Param	Type	Description
token	address	The Hedera token to mint. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amount	uint64	Applicable to FUNGIBLE TOKENS ONLY. The amount to mint to the Treasury Account. Amount must be a positive non-zero number represented in the lowest denomination of the token. The new supply must be lower than 2^63.
metadata	bytes[] memory	Applicable to NON-FUNGIBLE TOKENS ONLY. Maximum allowed size of each metadata is 100 bytes

Burn Tokens

burnToken(token, amount, serialNumbers)

Burns an amount of the token from the defined treasury account. This transaction accepts zero amount token burn operations for fungible tokens (HIP-564).

ABI Version: 2

Param	Type	Description
token	address	The token to burn. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amount	uint64	Applicable to FUNGIBLE TOKENS ONLY. The amount to burn from the Treasury Account. Amount must be a positive non-zero number, not bigger than the token balance of the treasury account (0; balance], represented in the lowest denomination.
serialNumbers	int64[]	Applicable to NON-FUNGIBLE TOKENS ONLY. The list of serial numbers to be burned.

Associate Tokens

associateToken(account, tokens)

Associates the provided account with the provided tokens. Must be signed by the account that is associated with the token.

ABI Version: 2

Param	Type	Description
account	address	The account to be associated with the provided tokens. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
token	address[] memory	The list of tokens to be associated with the provided account. In the case of non-fungible tokens, once an account is associated, it can hold any number of NFTs (serial numbers) of that token type. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

Dissociate Tokens

dissociateToken(account, token)

Dissociates the provided account with the provided token. Must be signed by the provided Account’s key.

ABI Version: 2

Param	Type	Description
account	address	The Hedera account to be dissociated from the provided token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
token	address	The token to be dissociated from the provided account. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

dissociateTokens(account, tokens)

Dissociates the provided account with the provided token. Must be signed by the account the token is being dissociated from.

ABI Version: 2

Param	Type	Description
account	address	The account is to be dissociated from the provided tokens.
tokens	address[] memory	The list of tokens to be dissociated from the provided account. The address is a mapping of shard.realm.number (0.0.x) into a 20-byte Solidity address.

allowance(token, owner, spender)

Returns the amount the spender is still allowed to withdraw from the owner. Only applicable to fungible tokens.

Param	Type	Description
token	address	The Hedera token ID in Solidity format to check the allowance of.
owner	address	The owner account in Solidity format of the tokens to be spent.
spender	address	The spender account in Solidity format.

approve(token, spender, amount)

Allows spender to withdraw from your account multiple times, up to the value amount. If this function is called again it overwrites the current allowance.

Param	Type	Description
token	address	The Hedera token ID to approve in Solidity format.
spender	address	The spender account ID authorized to spend in Solidity format.
amount	uint256	The amount of tokens the spender is authorized to spend.

approveNFT(token, approved, serialNumber)

Allow or reaffirm the approved address to transfer an NFT the approved address does not own. Applicable to non-fungible tokens (NFTs).

Param	Type	Description
token	address	The Hedera NFT token ID in solidity format to approve.
approved	address	The Hedera account ID to approve in Solidity format. To revoke approvals pass in the zero address.
serialNumber	uint256	The NFT serial number to approve.

getApproved(token, serialNumber)

Get the approved Hedera accounts for a single NFT. Applicable to non-fungible tokens (NFTs).

Param	Type	Description
token	address	The Hedera token ID for the NFT in Solidity format.
serialNumber	int64	The NFT serial number.

isApprovedForAll(token, owner, operator)

Returns whether or not the operator account is approved to spend on behalf of the owner.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
owner	address	The Hedera account ID in Solidity format
operator	address	The Hedera account ID in Solidity format

setApprovalForAll(token, operator, approved)

Enable or disable approval for a third party (“operator”) to manage all of msg.sender’s assets.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
operator	address	The Hedera account ID in Solidity format.
approved	bool	The Boolean data type in true or false.

isFrozen(token, account)

Returns whether or not the account was frozen. The response will return true is the account is frozen. This means the token cannot be transferred from the account until the account is unfrozen.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.

isKyc(token, account)

Returns whether or not the token has been granted KYC.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.

isToken(token)

Returns whether or not the token exists on Hedera.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

deleteToken(token)

Deletes the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

getTokenCustomFees(token)

Returns the custom fees for the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

getTokenDefaultFreezeStatus(token)

Returns the token freeze status on the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

getTokenDefaultKycStatus(token)

Returns the KYC status on the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

getTokenExpiryInfo(token)

Returns the token expiration for the specified token.

Param	Type	Description
token	address	The ID of the Hedera token in Solidity format.

getTokenInfo(token)

Retrieves general token entity information for the specified token.

Param	Type	Description
token	address	The ID of the Hedera token in Solidity format.

getFungibleTokenInfo(token)

Retrieves fungible specific token property information for a fungible token.

Param	Type	Description
token	address	The Hedera token ID of the fungible token in Solidity format.

getNonFungibleTokenInfo(token)

Retrieves non-fungible specific token info for a given NFT.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

getTokenKey(token, keyType)

Returns the token key for the specified key type. A key type can be be the KYC key, pause key, freeze key, etc.

Param	Type	Description
token	address	The ID of the token in solidity format to return the key value.
keyType	uint	The keyType of the desired key value.

getTokenType(token)

Returns the token type (fungible or non-fungible) for the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

freezeToken(token, account)

Freezes the account from transacting the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.

unfreezeToken(token, account)

Unfreezes the account from transacting the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.

grantTokenKyc(token, account)

Grants KYC to the Hedera account for the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.

revokeTokenKyc(token, account)

Revokes KYC to the Hedera account for the specified token.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.

pauseToken(token)

Prevents a token from being transacted if set.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

unpauseToken(token)

Unpauses a token from a previously paused state.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.

wipeTokenAccount(token, account, amount)

Wipes fungible tokens from the specified account. This transaction accepts zero amount token wipe operations for fungible tokens (HIP-564).

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.
amount	uint32	The amount of fungible tokens to wipe.

wipeTokenAccountNFT(token, token, serialNumbers)

Wipes a non-fungible token from the specified account.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
account	address	The Hedera account ID in Solidity format.
serialNumbers	int64[] memory	The NFT serial numbers to wipe from the account.

updateTokenInfo(token, tokenInfo)

Updates the properties of a token including the name, symbol, treasury account, memo, etc.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
tokenInfo	IHederaTokenService.HederaToken memory	The token properties to update.

updateTokenExpiryInfo(token, expiryInfo)

Update the token expiration time.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
expiryInfo	IHederaTokenService.Expiry memory	The expiry properties of a token.

updateTokenKeys(token, keys)

Update the keys set on a token. The key type is defined in the key parameter.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
keys	IHederaTokenService.TokenKey[] memory	The token key type.

updateTokenKeys(token, keys)

Update the keys set on a token. The key type is defined in the key parameter.

Param	Type	Description
token	address	The Hedera token ID in Solidity format.
keys	IHederaTokenService.TokenKey[] memory	The token key type.

Airdrop Tokens

airdropTokens(tokenTransfers)

Airdrop one or more tokens to one or more accounts.

Param	Type	Description
tokenTransfers	IHederaTokenService.TokenTransferList[] memory	The list of token transfers

cancelAirdrop(pendingAirdrops)

Cancels pending airdrops that have not yet been claimed.

Param	Type	Description
pendingAirdrops	IHederaTokenService.PendingAirdrop[] memory	The list of pending airdrops to cancel.

claimAirdrops(pendingAirdrops)

Claims pending airdrops that were sent to the calling account.

Param	Type	Description
pendingAirdrops	IHederaTokenService.PendingAirdrop[] memory	The list of pending airdrops to claim.

rejectTokens(rejectAddress, ftAddresses, nftIds)

Airdrop one or more tokens to one or more accounts.

Param	Type	Description
rejectingAddress	address	The address rejecting the tokens
ftAddresses	memory	Array of fungible token addresses to reject
nftIds	IHederaTokenService.NftId[] memory	Array of NFT IDs to reject

Gas Cost

Fees

Examples