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.

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

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

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

The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

receiver

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

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

The token to transfer to/from.

sender

The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

receiver

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

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

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

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

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

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

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

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 Hedera account ID in Solidity format.

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

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

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

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

The token key type.

Gas Cost

Gas and Fees

Examples

Deploy a Contract Using the Hedera Token Service

Last updated