FT Contract Deployment and Token Transfer

KIP-7 is an FT (Fungible Token) contract standard defined by Klaytn. KAS provides the KIP-7 API for conveniently creating and managing KIP-7 tokens. The main features of KIP-7 API are KIP-7 contract deployment and minting/burning/sending tokens.

In this tutorial, we will walk you through how to deploy KIP-7 contracts, as well as how to mint and transfer KIP-7 tokens, using the KIP-7 API. For more details, please refer to KAS KIP-7 API Reference.

Deploying KIP-7 contract

The KIP-7 API deploys and manages FT contracts that follow the KIP-7 standard.

For more information on the functions of the KIP-7 contract standard, please refer to KIP-7.

You can deploy a KIP-7 contract by executing the following curl command.

curl

curl --location --request POST "https://kip7-api.klaytnapi.com/v1/contract" \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
  --data-raw '{
        "alias": "my-first-kip7",
        "name": "My First KIP-7",
        "symbol": "MFK",
        "decimals": 8,
        "initialSupply": "0x100000000"
  }'

javascript

const result = await caver.kas.kip7.deploy('My First KIP-7', 'MFK', 8, '0x100000000', 'my-first-kip7')

API Path and Request

We will break down curl command in parts. You can call Deploy Contract API with the endpoint POST /v1/contract. Since KIP-7 API is being serviced by https://kip7-api.klaytnapi.com, set the URL for curl as https://kip7-api.klaytnapi.com/v1/contract, with the request type as POST (—-request POST).

Contract Deploy API accepts the POST request and requires the following JSON data.

curl

{
     "alias": "my-first-kip7",
     "name": "My First KIP-7",
     "symbol": "MFK",
     "decimals": 8,
     "initialSupply": "0x100000000"
}

Here is a brief description of each field:

• Alias (alias): Nickname of the contract. It can be used in place of the contract address in different APIs. Allowed characters are lowercase letters, numbers, and hyphens; and the first letter must be a lowercase alphabet.

• Name (name): Name given to the contract. Used as name in accordance with the KIP-7 standard.

• Symbol (symbol): Symbol of the contract. Used as symbol in accordance with the KIP-7 standard. It usually consists of 3-4 uppercase letters, but there is no restriction.

• Decimals (decimals): Token decimals. Used as decimals in accordance with the KIP-7 standard. 18 decimals is the standard practice.

• InitialSupply(initialSupply): The inital token supply of the contract. Used as totalSupply in accordance with the KIP-7 standard.

Required Headers

All KIP-7 APIs require x-chain-id header. Accepted values are 1001 (Baobab) and 8217 (Cypress).

Authentication

For all APIs provided by KAS, credentials must be provided: the access-key-id and secret-access-key. More on generating and obtaining credentials, please refer to Link.

API Response

Executing the curl command for token deployment will return the following result:

curl

{
    "status": "Submitted",
    "transactionHash": "0xde30017fa4474274bd8e0f8bf4eea799d6873d1f2e24f5d7afe97400b24acf4c"
}

javascript

 {
  status: 'Submitted',
  transactionHash: '0xe5bf5cbd8d9f13e31af8e1cac1ff7749f649779a1e0eb62579012b38ff7737c3'
}

You can use transactionHash returned in the response to execute RPC functions such as klay_getTransactionReceipt.

Result

KIP-7 API's Get Contract List API(GET /v1/contract) can be used for retrieving a list of deployed contracts. You can do this by running the curl command:

curl

curl --location --request GET 'https://kip7-api.klaytnapi.com/v1/contract' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}

javascript

const queryOptions = { size: 1, status: caver.kas.kip7.queryOptions.status.DEPLOYED }
const result = await caver.kas.kip7.getContractList(queryOptions)

If your contract has been successfully deployed, you will get the following response.

curl

{
    "items": [
      {
          "address": "0x33779fc606de8b1c1095dc3760be4c4f8b2a1ad3",
          "alias": "my-first-kip7",
          "decimals": 8,
          "name": "My First KIP-7",
          "status": "deployed",
          "symbol": "MFK",
          "totalSupply": "0x100000000"
      }
    ],
    "cursor": ""
}

javascript

{
  items: [
    {
      address: '0x05a86c8e60aefb9ce975fe26511f72da86ab2a7a',
      alias: 'my-first-kip7',
      decimals: 8,
      name: 'My First KIP-7',
      status: 'deployed',
      symbol: 'MFK',
      totalSupply: '0x100000000'
    }
  ],
  cursor:  'eyJjcmVhdGVkX2F0IjoxNjIxODE4NTQwLCJpZCI6ImNvbnRyYWN0IzEwMDEjMTczZGI2OWMtZjFiOC00ZGQ1LTlhYzItZWQ4YTBiYWRhYjI5Iiwic19pZCI6Imphc21pbmUtcWNvYnNiNnM2d2oifQ=='
}

Minting KIP-7 Tokens

If you successfully deployed your contract, you can start minting tokens now. The API for minting tokens is POST /v1/contract/{contract-address-or-alias}/mint. The path parameter {contract-address-or-alias} is the alias or the address of the contract that will be minting the tokens. You can use the alias submitted for minting tokens, or the address that you found on the Get Contract List API after deploying the contract.

Contracts deployed with KAS KIP-7 implement the IKIP7Mintable interface. Minting tokens will also increase the total supply.

Request for Minting Tokens

Below is the curl command for calling Mint Token API using the alias my-first-kip7 from the previous example.

curl

curl --location --request POST 'https://kip7-api.klaytnapi.com/v1/contract/my-first-kip7/mint' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
    --data-raw '{
      "to": "0x72b03ca464609c82be1d490ecfce004e2d3c4cfc",
      "amount": "0x100"
}'

javascript

const result = await caver.kas.kip7.mint('my-first-kip7', '0x72b03ca464609c82be1d490ecfce004e2d3c4cfc', '0x100')

The required header and authentication data are the same as those for contract deployment. You can enter data such as location, or send request in the same way as for Mint Token API (POST /v1/contract/{contract-address-or-alias}/mint).

Token Mint API requires the following JSON data:

curl

{
    "to": "0x72b03ca464609c82be1d490ecfce004e2d3c4cfc",
    "amount": "0x100"
}

• Recipient (to): Klaytn account address of the token recipient. Mint Token API will mint a new token in a designated address.

• Amount (amount): The amount of tokens to be created. It is hexadecimal and uses values that include decimals. The above tutorial creates 0.00000256(0x100 / 10 ^ 8) MFK tokens.

Klaytn account address is in hexadecimal. It is 20-byte long and is written in 42 hexadecimal characters including the prefix "0x".

Checking the Response and the Result of Token Creation

Executing the curl command for creating tokens, you will get the following response.

curl

{
    "transactionHash": "0x8fa73465785c5aedc7df3123ed2670f37f3cd42f63d32c53aba37c8fe1afc078",
    "status": "Submitted"
}

javascript

{
  status: 'Submitted',
  transactionHash: '0xe4db23b626f98e592156b4e69761cfecff414839fbcec0b6b73080d8a6b0a3e9'
}

You will see a response that looks like the example above, which is the same as the one for contract deployment.

To check if your token has been minted correctly, use Get Contract Balance API (GET /v1/contract/{contract-address-or-alias}/account/{owner}/balance) and check the balance for the owner's address. You can use the following curl command to check the balance of the account 0x72b03ca464609c82be1d490ecfce004e2d3c4cfc of the my-first-kip7 contract.

curl

curl --location --request GET 'https://kip7-api.klaytnapi.com/v1/contract/my-first-kip7/account/0x72b03ca464609c82be1d490ecfce004e2d3c4cfc/balance' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}

javascript

const result = await caver.kas.kip7.balance('my-first-kip7', '0x72b03ca464609c82be1d490ecfce004e2d3c4cfc')

If the token has been minted successfully, you will receive the following response:

curl

{
    "balance": "0x100",
    "decimals": 8
}

javascript

{ balance: '0x100', decimals: 8 }

You will have noticed in the status of the response that it's "Submitted", instead of "Success" or "Completed". All blockchains including Klaytn runs asynchronously, so the response of the request doesn't get returned immediately, meaning that you can't check the status right away. For cases like minting tokens, a request can fail depending on certain values (e.g., insufficient transaction fee), so it's all the more important to check beforehand that your account has sufficient KLAY.

Transferring KIP-7 Tokens

The Transfer Token API for KIP-7 is POST /v1/contract/{contract-address-or-alias}/transfer. {contract-address-or-alias} refers to the contract that you wish to use.

Create an account on KAS Wallet Account Pool(https://console.klaytnapi.com/en/service/wallet/accounts/list) before using KAS KIP-7 Token Transfer API. The account address used in this tutorial (0x72b03ca464609c82be1d490ecfce004e2d3c4cfc) is an account registered in advance.

For more information on creating and managing accounts, please visit here.

In order to transfer tokens using KIP-7 API, the account of the sender must be included in the default KAS Wallet Account Pool. If the account is not in the default Account Pool, the KRN of the pool must be specified under the x-krn header.

Below is the curl command for sending one token of the my-first-kip7 contract owned by 0x72b03ca464609c82be1d490ecfce004e2d3c4cfc to 0x4d3224314b704be8887551e8c9b9bbb9aa5c48b3:

curl

curl --location --request POST 'https://kip7-api.klaytnapi.com/v1/contract/my-first-kip7/transfer' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
    --data-raw '{
      "from": "0x72b03ca464609c82be1d490ecfce004e2d3c4cfc",
      "to": "0x4d3224314b704be8887551e8c9b9bbb9aa5c48b3",
      "amount": "0x1"
    }'

javascript

const result = await caver.kas.kip7.transfer('my-first-kip7', '0x72b03ca464609c82be1d490ecfce004e2d3c4cfc', '0x4d3224314b704be8887551e8c9b9bbb9aa5c48b3', '0x1')

JSON for Token Transfer

The JSON data required for trasferring tokens are as follows:

• From (from): The address of the token owner

• To (to): The address of the token recipient. Keep in mind that due to the nature of blockchain, once a token is transferred, it is irreversible.

• Amount (amount): Amount of tokens to send. In hexadecimal without decimals.

If from is inaccurate or the balance is insufficient, the transfer request will fail.

Even when the balance is insufficient, the transfer request API will produce a normal response. KIP-7 API will only verify the format and syntax of the request.

To check if your transfer request has been successfully received by the blockchain, you can either use KIP-7 API's Get Token Balance or run the Node API's klay_getTransactionReceipt.

Token Transfer Result

Executing the Token Transfer API will return the following response:

curl

{
    "transactionHash": "0xf55b6bda2b0b610b461f0a8533001d38e4fad95a77eb4e2a60d38c14fdf0c997",
    "status": "Submitted"
}

javascript

{
  status: 'Submitted',
  transactionHash: '0x736dd99fc06dbc237d55eddf204b053fdc35b07faf30dcd1bfa504c7cb651192'
}

To check if your token has been transferred successfully, use Get Contract Balance API (GET /v1/contract/{contract-address-or-alias}/account/{owner}/balance). You should see that your token balance is updated.

curl

curl --location --request GET 'https://kip7-api.klaytnapi.com/v1/contract/my-first-kip7/account/0x4d3224314b704be8887551e8c9b9bbb9aa5c48b3/balance' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}

javascript

const result = await caver.kas.kip7.balance('my-first-kip7', '0x4d3224314b704be8887551e8c9b9bbb9aa5c48b3')

If your token is transferred successfully, the balance will be updated as below:

curl

{
    "balance": "0x1",
    "decimals": 8
}

javascript

{ balance: '0x1', decimals: 8 }