컨트랙트 배포 및 토큰 발행/전송

KIP-37은 Klaytn에서 정의한 MT(Multi Token) 컨트랙트 표준입니다. KIP-37은 NFT(Non-Fungible Token)와 FT(Fungible Token)를 모두 지원합니다.

KAS는 KIP-37 API를 통해 KIP-37 토큰을 쉽고 편리하게 생성/관리할 수 있는 API를 제공합니다. KIP-37 API의 대표적인 기능은 KIP-37 컨트랙트의 배포, 토큰의 발급, 소각, 전송, 소유자 목록 조회 등입니다.

전체 KIP-37 API에 대한 자세한 사양은 KAS KIP-37 API Reference를 통해 확인하실 수 있습니다.

KIP-37 컨트랙트 배포

KIP-37 API는 KIP-37 표준을 따르는 MT 컨트랙트를 배포하고 제어합니다.

info

KIP-37 컨트랙트 표준 함수 및 소스코드에 관한 더 자세한 정보는 KIP-37 Standard과 klaytn/klaytn-contracts을 확인하세요.

API 호출

KIP-37 컨트랙트의 배포는 다음과 같은 curl 명령어를 실행하여 수행할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request POST "https://kip37-api.klaytnapi.com/v2/contract" \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
  --data-raw '{
    "alias": "my-first-kip37-contract",
    "uri": "https://token-cdn-domain/{id}.json",
    "options": {
      "enableGlobalFeePayer": true
    }
  }'
Copy
Copied
const result = await caver.kas.kip37.deploy(
  "https://token-cdn-domain/{id}.json",
  "my-first-kip37-contract"
);
Copy
Copied
String alias = "my-first-kip37-contract";
String uri = "https://token-cdn-domain/{id}.json";

Kip37FeePayerOptions option = new Kip37FeePayerOptions();
option.setEnableGlobalFeePayer(false);

Kip37DeployResponse deployResponse = caver.kas.kip37.deploy(uri, alias, option);

curl 명령어를 부분으로 나누어 하나씩 살펴보겠습니다. 컨트랙트 배포 API는 POST /v2/contract로 실행할 수 있습니다. KIP-37 API가 https://kip37-api.klaytnapi.com에서 서비스되고 있으니 curl 요청의 URL을 https://kip37-api.klaytnapi.com/v2/contract로, 요청 유형은 POST (—-request POST)로 설정합니다.

컨트랙트 배포 API는 POST 요청을 받아들이며 다음과 같은 JSON 데이터를 요구합니다.

Copy
Copied
{
  "alias": "my-first-kip37-contract",
  "uri": "https://token-cdn-domain/{id}.json",
  "options": {
    "enableGlobalFeePayer": true
  }
}

각각의 필드에 대한 설명은 다음과 같습니다.

  • Alias ( alias ): 컨트랙트의 별명입니다. 이후 여러 API에서 컨트랙트 주소를 대신해 사용 가능합니다. 허용되는 문자는 알파벳 소문자, 숫자, 하이픈이며 별명의 첫 문자는 알파벳 소문자로 제한됩니다.
  • URI ( uri ): 토큰의 메타데이터 URI를 식별할 수 있는 URI입니다. 클라이언트는 토큰의 메타데이터 URI를 식별하기 위해 {id} 값을 토큰 아이디( 0x 를 제외한 16진수)로 변경합니다. 예를 들어 토큰 아이디 0x1 의 메타데이터는 https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json 으로 확인할 수 있습니다.
  • Options( options ): 트랜잭션 전송 시 수수료 지불 방법에 대한 설정입니다. 예제에서는 KAS Global FeePayer를 이용한 대납으로 설정하였습니다. 자세한 설명은 Fee Payer Options 를 확인하세요.
info

모든 KIP-37 API는 x-chain-id 헤더값을 필수로 요구합니다. 허용되는 값은 1001(Baobab), 8217(Cypress)입니다.

  • 인증

    KAS가 제공하는 모든 API는 계정 인증 정보, 즉 access-key-id와 secret-access-key를 요구합니다. 인증 정보의 생성 및 획득은 다음 링크를 참조해주세요.

API 응답

컨트랙트 배포 curl 명령어를 실행하면 다음과 같은 결과를 받게 됩니다.

cURLJavaScriptJava
Copy
Copied
{
  "status": "Submitted",
  "transactionHash": "0xca97254ab324a5a205538e83b5559c469cdc3f366659f610642021a3febab32f",
  "options": {
    "enableGlobalFeepayer": true,
    "userFeePayer": {
      "address": "",
      "krn": ""
    }
  }
}
Copy
Copied
{
  status: 'Submitted',
  transactionHash: '0x7dbb6f9c823f1f8bc4a3203486bd79d5979a1c7e23c207ccfe8fdb611bd5cfd8',
  options: {
    enableGlobalFeepayer: true,
    userFeePayer: { krn: '', address: '' }
  }
}
Copy
Copied
class Kip37DeployResponse {
    status: Submitted
    transactionHash: 0xca97254ab324a5a205538e83b5559c469cdc3f366659f610642021a3febab32f
    options: class Kip37FeePayerOptionsResponse {
        enableGlobalFeepayer: true
        userFeePayer: class Kip37FeePayerOptionsUserFeePayer {
            krn:
            address:
        }
    }
}

결과로 받는 transactionHash는 klay_getTransactionReceipt과 같은 RPC 함수를 실행할 때 사용할 수 있습니다.

KIP-37 컨트랙트 목록 조회

API 호출

KIP-37 API의 컨트랙트 목록 조회 API(GET /v2/contract)를 사용하여 배포한 컨트랙트를 조회할 수 있습니다. 다음 curl 명령어를 실행하여 컨트랙트 목록을 조회합니다.

info

컨트랙트 정보 조회 API(GET /v2/contract/{contract-address-or-alias})를 사용하여 컨트랙트를 조회할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET 'https://kip37-api.klaytnapi.com/v2/contract' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}
Copy
Copied
const list = await caver.kas.kip37.getContractList();
Copy
Copied
Kip37ContractListResponse response = caver.kas.kip37.getContractList();

API 응답

컨트랙트가 올바르게 배포되었다면 다음과 같은 응답을 받습니다.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "address": "0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a",
      "alias": "my-first-kip37-contract",
      "options": {
        "enableGlobalFeePayer": true,
        "userFeePayer": {
          "address": "",
          "krn": ""
        }
      },
      "status": "deployed",
      "uri": "https://token-cdn-domain/{id}.json"
    }
  ],
  "cursor": ""
}
Copy
Copied
{
  items: [
    {
      address: '0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a',
      alias: 'my-first-kip37-contract',
      status: 'deployed',
      uri: 'https://token-cdn-domain/{id}.json',
      options: {
        enableGlobalFeePayer: true,
        userFeePayer: { krn: '', address: '' }
      }
    }
  ],
  cursor: ''
}
Copy
Copied
class Kip37ContractListResponse {
    items:[class Kip37Contract {
        address:0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a
        alias:my-first-kip37-contract
        status:deployed
        uri:https://token-cdn-domain/{id}.json
        options: class Kip37FeePayerOptions {
            enableGlobalFeePayer:true
            userFeePayer: class Kip37FeePayerOptionsUserFeePayer {
                krn:
                address:
            }
        }
    }]
}

토큰 생성

컨트랙트를 성공적으로 배포했다면 이제 토큰을 발행할 수 있습니다. 토큰을 발행하는 API는 POST /v2/contract/{contract-address-or-alias}/token 입니다. 여기서 {contract-address-or-alias}는 토큰을 발행하려는 컨트랙트의 별명(alias) 또는 주소(address)로, 토큰을 배포할 때 제출한 alias나 토큰 배포 후 컨트랙트 목록 조회 API에서 확인한 address를 사용합니다.

API 요청

다음은 앞서 예제에서 사용된 alias my-first-kip37-contract을 사용하여 토큰 생성 API를 호출하는 curl 명령어입니다.

info

토큰 생성 API를 이용하면 실제 컨트랙트의 function create(uint256 _id, uint256 _initialSupply, string calldata _uri) external returns (bool); 함수를 호출합니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request POST 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
	--data-raw '{
      "sender": "",
      "id": "0x1",
      "initialSupply": "0x100",
      "uri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json"
}'
Copy
Copied
const created = await caver.kas.kip37.create(
  "my-first-kip37-contract",
  "0x1",
  "0x100",
  "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json"
);
Copy
Copied
String alias = "my-first-kip37-contract";
String id = "0x1";
String initialSupply = "0x100";
String uri = "uri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json";

Kip37TransactionStatusResponse response = caver.kas.kip37.create(alias, id, initialSupply, uri);

필수 헤더, 인증 정보 등은 컨트랙트 배포 API와 동일하며 location, request와 같은 정보는 토큰 발행 API(POST /v2/contract/{contract-address-or-alias}/token)에 맞추어 입력합니다.

토큰 발행 API는 다음과 같은 JSON 데이터를 요구합니다.

Copy
Copied
{
  "sender": "",
  "id": "0x1",
  "initialSupply": "0x100",
  "uri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json"
}
  • Sender ( sender ): 토큰을 생성할 Klaytn 계정 주소로써 Minter 권한이 있어야 합니다. 생략 시 컨트랙트를 배포한 계정으로 토큰을 생성합니다. 컨트랙트 배포 계정( deployer )은 컨트랙트 배포 기본 계정 조회 를 통해 확인 가능합니다.
  • Token ID ( id ): 생성할 토큰의 16진수로 표현된 고유번호입니다. 이미 발행되어있는 토큰의 고유번호는 사용할 수 없습니다. 단, 소각된 토큰의 고유번호는 재사용할 수 있습니다.
  • Initial Supply ( initialSupply ): 16진수로 표현된 토큰의 발행량입니다.
  • Token URI ( uri ): 토큰 정보를 담은 JSON 파일의 위치를 URI 로 표현한 값입니다. 해당 토큰의 정보, 속성 등을 기록하여 URI로 표현될 수 있는 위치에 사전 배포한 뒤 토큰 발행 시 해당 URI를 포함시킵니다. URI 링크의 유효성 여부는 확인하지 않으니 주의하여 입력 부탁드립니다.
info

Klaytn 계정의 주소는 16진수로 표현됩니다. 길이는 20-byte로, 접두사 "0x"를 포함하여 16진수 42자로 표현됩니다.

API 응답

토큰 발행 curl을 수행하면 다음과 같은 응답을 받을 수 있습니다.

cURLJavaScriptJava
Copy
Copied
{
  "transactionHash": "0x354aed16b2dbf43b32ab6fdd259c9d3d7b244236870658979a8a2b34fa7b579b",
  "status": "Submitted"
}
Copy
Copied
{
  status: 'Submitted',
  transactionHash: '0x7b13e0d318aa2283c0e27c3e92996e2c3488c227480d61bff1f5c6148174dd07'
}
Copy
Copied
class Kip37TransactionStatusResponse {
    status: Submitted
    transactionHash: 0x354aed16b2dbf43b32ab6fdd259c9d3d7b244236870658979a8a2b34fa7b579b
    transactionId: null
}
info

응답의 status를 눈여겨 보셨다면 "Success"나 "Completed"가 아닌 "Submitted"인 것을 확인할 수 있습니다. Klaytn을 비롯한 모든 블록체인은 요청에 대한 응답이 즉시 돌아오지 않는 비동기 형태로 동작하기 때문에 요청이 성공했는지 바로 확인할 수 없습니다. 특히 토큰 발행과 같이 요청값에 따라 요청이 실패할 수 있는 경우(e.g., 이미 존재하는 토큰 고유번호를 사용)가 존재하기 때문에 토큰 목록 조회 실행과 같은 명시적인 확인이 필요합니다.

컨트랙트 배포를 실행했을 때와 같은 형식의 응답이 오는 것을 확인할 수 있습니다.

발행 결과 조회

API 호출

토큰이 잘 발행되었는지 확인하려면 토큰 목록 조회 API GET /v2/contract/{contract-address-or-alias}/token를 사용하여 새로 발행한 토큰이 컨트랙트에 추가되었는지 확인합니다.

다음 curl 명령어를 사용하여 my-first-kip37-contract 컨트랙트의 토큰 목록을 조회할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}
Copy
Copied
const tokens = await caver.kas.kip37.getTokenList("my-first-kip37-contract");
Copy
Copied
String alias = "my-first-kip37-contract";
Kip37TokenInfoListResponse response = caver.kas.kip37.getTokenList(alias);

API 응답

토큰이 성공적으로 발행되었다면 다음과 같은 응답을 받을 수 있습니다.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "tokenId": "0x1",
      "tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
      "totalSupply": "0x100"
    }
  ],
  "cursor": ""
}
Copy
Copied
{
  items: [
    {
      tokenId: '0x1',
      totalSupply: '0x100',
      tokenUri: 'https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json'
    }
  ],
  cursor: ''
}
Copy
Copied
class Kip37TokenInfoListResponse {
    items: [class Kip37TokenInfoListResponseItem {
        tokenId: 0x1
        totalSupply: 0x100
        tokenUri: https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json
    }]
    cursor:
}

토큰 추가 발행

토큰을 성공적으로 생성했다면 이제 토큰을 추가 발행할 수 있습니다. KIP-37에서는 KIP-17과 다르게 create가 토큰 생성, 그리고 mint가 이미 생성된 토큰의 추가 발행을 의미합니다.

API 요청

다음은 앞서 예제에서 사용된 alias my-first-kip37-contract, token id 0x1를 사용하여 토큰 추가 발행 API를 호출하는 curl 명령어입니다.

info

토큰 추가 API를 이용하면 실제 컨트랙트의 function mint(uint256 _id, address _to, uint256 _value) external;(단일), function mintBatch(address _to, uint256[] calldata _ids, uint256[] calldata _values)(다중) 함수를 호출합니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request POST 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token/mint' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
  --data-raw '{
    "sender": "",
    "to": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
    "ids": [
      "0x1"
    ],
    "amounts": [
      "0x10"
    ]
  }'
Copy
Copied
const minted = await caver.kas.kip37.mint(
  "my-first-kip37-contract",
  "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
  ["0x1"],
  ["0x10"]
);
Copy
Copied
String alias = "my-first-kip37-contract";
String id = "0x1";
String amount = "0x10";
String to = "0xd9Fe560d3141E78CDd2F617147985e458a529c1E";

Kip37TransactionStatusResponse response = caver.kas.kip37.mint(alias, to, id, amount);
  • Sender ( sender ): 토큰을 추가 발행할 Klaytn 계정 주소로써 Minter 권한이 있어야 합니다. 생략 시 컨트랙트를 배포한 계정으로 토큰을 생성합니다. 컨트랙트 배포 계정( deployer )은 컨트랙트 배포 기본 계정 조회 를 통해 확인 가능합니다.
  • Recipient ( to ): 토큰을 받는 사람의 Klaytn 계정 주소입니다. 토큰 추가 발행 API는 지정된 주소로 추가 발행합니다.
  • Token ID ( ids ): 추가 발행할 토큰의 고유번호 리스트입니다. KIP-37에서는 다중 토큰을 추가 발행할 수 있습니다.
  • Amount ( amounts ): 추가 발행할 토큰의 수량 리스트입니다. 수량은 16진수를 사용합니다. ids 와 amounts 의 원소 수는 항상 같아야 합니다.

API 응답

토큰 추가 발행 curl을 수행하면 다음과 같은 응답을 받을 수 있습니다.

cURLJavaScriptJava
Copy
Copied
{
  "status": "Submitted",
  "transactionHash": "0x63172503a362566aeed9e64271830ddc090affe7612f99e5f2415caaa379a7f3"
}
Copy
Copied
{
  status: 'Submitted',
  transactionHash: '0xd8de974acf6c436644fa049cac7268e7192aa7fe8cf44de80bc4874a2076d83a'
}
Copy
Copied
class Kip37TransactionStatusResponse {
    status: Submitted
    transactionHash: 0x63172503a362566aeed9e64271830ddc090affe7612f99e5f2415caaa379a7f3
    transactionId: null
}

추가 발행 결과 조회

API 호출

토큰 생성과 마찬가지로 토큰 목록 조회 API GET /v2/contract/{contract-address-or-alias}/token를 사용하여 토큰 발행량(totalSupply)을 확인할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}
Copy
Copied
const tokens = await caver.kas.kip37.getTokenList("my-first-kip37-contract");
Copy
Copied
Kip37ContractListResponse response = caver.kas.kip37.getContractList();

API 응답

토큰이 성공적으로 발행되었다면 다음과 같은 응답을 받을 수 있습니다.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "tokenId": "0x1",
      "tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
      "totalSupply": "0x110"
    }
  ],
  "cursor": ""
}
Copy
Copied
{
  items: [
    {
      tokenId: '0x1',
      totalSupply: '0x110',
      tokenUri: 'https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json'
    }
  ],
  cursor: ''
}
Copy
Copied
class Kip37TokenInfoListResponse {
    items: [class Kip37TokenInfoListResponseItem {
        tokenId: 0x1
        totalSupply: 0x110
        tokenUri: https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json
    }]
    cursor:
}

토큰 전송

KIP-37 토큰을 전송하는 API는 POST /v2/contract/{contract-address-or-alias}/token/transfer입니다.

이 예제는 KAS 사용자가 KAS Wallet Account Pool에 등록한 계정이 이미 존재한다고 가정합니다.

info

계정 생성과 관리는 여기를 참조해주시기 바랍니다.

info

KIP-37 API로 토큰을 전송하려면 토큰을 보내는 사람의 계정의 (cryptographic) key가 KAS Wallet Account Pool에 등록되어 있어야 합니다. 만약 Key가 Default Account Pool에 등록되어 있지 않을 경우 해당 Pool의 KRN을 x-krn 헤더에 직접 입력해야합니다.

info

KIP-37 API는 다중(batch) 전송을 허용합니다. 만약 원소가 1개인 경우 function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external; 함수를 호출합니다. 다중의 경우 function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; 함수를 호출합니다.

API 요청

다음 curl 명령어는 소유 계정(0xd9Fe560d3141E78CDd2F617147985e458a529c1E)이 소유한 my-first-kip37-contract 컨트랙트의 0x1 토큰을 수령 계정(0x74B9bE845D276E6382081995A61a65da91C76328)으로 1개(0x1) 전송합니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request POST 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token/transfer' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
	--data-raw '{
      "sender": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
      "owner": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
      "to": "0x74B9bE845D276E6382081995A61a65da91C76328",
      "ids": [
        "0x1"
      ],
      "amounts": [
        "0x1"
      ]
    }'
Copy
Copied
const result = await caver.kas.kip37.transfer(
  "my-first-kip37-contract",
  "0x0d10a78a15abc40181fd88536f016cf4eaec394e",
  "0x0d10a78a15abc40181fd88536f016cf4eaec394e",
  "0x74B9bE845D276E6382081995A61a65da91C76328",
  ["0x1"],
  ["0x1"]
);
Copy
Copied
String alias = "my-first-kip37-contract";

String sender = "0xd9Fe560d3141E78CDd2F617147985e458a529c1E";
String owner = "0xd9Fe560d3141E78CDd2F617147985e458a529c1E";
String to = "0x74B9bE845D276E6382081995A61a65da91C76328";
String id = "0x1";
String amount = "0x1";

Kip37TransactionStatusResponse response = caver.kas.kip37.transfer(alias, sender, owner, to, id, amount);

토큰 전송에 필요한 JSON 데이터는 다음과 같습니다.

  • Sender ( sender ): 토큰을 전송할 Klaytn 계정 주소입니다. 만약 sender 와 owner 가 다를 경우 sender 는 반드시 해당 토큰의 전송 권한을 가지고 있어야 합니다. 토큰 전송 승인 권한 API 를 이용하여 권한을 부여할 수 있습니다.
  • Owner ( owner ): 토큰을 소유한 Klaytn 계정 주소입니다.
  • Recipient ( to ): 토큰을 받는 사람의 주소입니다. 블록체인 특성상 토큰을 전송하면 되돌릴 수 없으니 주의하시기 바랍니다.
  • Token ID ( ids ): 전송할 토큰의 16진수로 표현된 고유번호 리스트입니다. KIP-37에서는 다중 토큰을 전송할 수 있습니다.
  • Amount ( amounts ): 전송할 토큰의 수량 리스트입니다. 수량은 16진수를 사용합니다. ids 와 amounts 의 원소 수는 항상 같아야 합니다.

API 응답

토큰 전송 API를 실행하면 다음과 같은 응답을 받습니다.

cURLJavaScriptJava
Copy
Copied
{
  "transactionHash": "0xe935aa5b7dcd22fc9f3420126d702d23a38ebed8c7eb3f264a930d5377176e18",
  "status": "Submitted"
}
Copy
Copied
{
  status: 'Submitted',
  transactionHash: '0x567483dc5faecc797278f9067224f805156a761baaad5b31fc5f4083697c14df'
}
Copy
Copied
class Kip37TransactionStatusResponse {
    status: Submitted
    transactionHash: 0xe935aa5b7dcd22fc9f3420126d702d23a38ebed8c7eb3f264a930d5377176e18
    transactionId: null
}

전송 결과 조회

API 호출

토큰 전송을 성공했는지 확인하기 위해 특정 계정이 소유한 토큰 목록 조회 API GET /v2/contract/{contract-address-or-alias}/owner/{owner-address}/token를 사용하여 전송한 토큰의 정보가 올바르게 변경되었는지 확인할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/owner/0x74B9bE845D276E6382081995A61a65da91C76328/token'
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}
Copy
Copied
const list = await caver.kas.kip37.getTokenListByOwner(
  "my-first-kip37-contract",
  "0x74B9bE845D276E6382081995A61a65da91C76328"
);
Copy
Copied
String alias = "my-first-kip37-contract";
String owner = "0x74B9bE845D276E6382081995A61a65da91C76328";

Kip37TokenListResponse response = caver.kas.kip37.getTokenListByOwner(alias, owner);

API 응답

토큰 전송이 올바르게 수행되었을 경우 다음과 같이 전송한 토큰의 정보가 변경된 것을 확인할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "balance": "0x1",
      "owner": "0x74b9be845d276e6382081995a61a65da91c76328",
      "tokenAddress": "0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a",
      "tokenId": "0x1",
      "tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
      "totalSupply": "0x110",
      "transactionHash": "0xe935aa5b7dcd22fc9f3420126d702d23a38ebed8c7eb3f264a930d5377176e18",
      "transferFrom": "0xd9fe560d3141e78cdd2f617147985e458a529c1e",
      "transferTo": "0x74b9be845d276e6382081995a61a65da91c76328",
      "updatedAt": 1627980971
    }
  ],
  "cursor": ""
}
Copy
Copied
{
  items: [
    {
      tokenId: '0x1',
      owner: '0x74b9be845d276e6382081995a61a65da91c76328',
      tokenAddress: '0x8d8721edf52766af76c6397fb52c70c9cd7dd292',
      totalSupply: '0x110',
      tokenUri: 'https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json',
      replacedTokenUri: undefined,
      balance: '0x1',
      transactionHash: '0x567483dc5faecc797278f9067224f805156a761baaad5b31fc5f4083697c14df',
      transferFrom: '0x0d10a78a15abc40181fd88536f016cf4eaec394e',
      transferTo: '0x74b9be845d276e6382081995a61a65da91c76328',
      updatedAt: '1633068353'
    }
  ],
  cursor: ''
}
Copy
Copied
class Kip37TokenListResponse {
    items: [class Kip37TokenListResponseItem {
        tokenId: 0x1
        owner: 0x74b9be845d276e6382081995a61a65da91c76328
        tokenAddress: 0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a
        totalSupply: 0x110
        tokenUri: https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json
        replacedTokenUri: null
        balance: 0x1
        transactionHash: 0xe935aa5b7dcd22fc9f3420126d702d23a38ebed8c7eb3f264a930d5377176e18
        transferFrom: 0xd9fe560d3141e78cdd2f617147985e458a529c1e
        transferTo: 0x74b9be845d276e6382081995a61a65da91c76328
        updatedAt: 1627980971
    }]
    cursor:
}

토큰 소각

KIP-37 토큰을 소각하는 API는 DELETE /v2/contract/{contract-address-or-alias}/token입니다.

info

KIP-37 API는 다중(batch) 소각을 허용합니다. 원소가 1개인 경우 function burn(address _account, uint256 _id, uint256 _value) external; 함수를, 여러 개인 경우 function burnBatch(address _account, uint256[] calldata _ids, uint256[] calldata _values) external; 함수를 호출합니다.

API 요청

다음 curl 명령어는 소유 계정(0xd9Fe560d3141E78CDd2F617147985e458a529c1E)이 소유한 my-first-kip37-contract 컨트랙트의 0x1 토큰을 2개(0x2) 소각합니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request DELETE 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key} \
	--data-raw '{
      "from": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
      "ids": [
        "0x1"
      ],
      "amounts": [
        "0x2"
      ]
    }'
Copy
Copied
const result = await caver.kas.kip37.burn(
  "my-first-kip37-contract",
  ["0x1"],
  ["0x2"]
);
Copy
Copied
String alias = "my-first-kip37-contract";
String from = "0xd9Fe560d3141E78CDd2F617147985e458a529c1E";
String id = "0x1";
String amount = "0x2";

Kip37TransactionStatusResponse response = caver.kas.kip37.burn(alias, id, amount, from);

토큰 소각에 필요한 JSON 데이터는 다음과 같습니다.

  • From ( from ): 토큰을 소각할 Klaytn 계정 주소입니다.
  • Token ID ( ids ): 소각할 토큰의 16진수로 표현된 고유번호 리스트입니다. KIP-37에서는 다중 토큰을 소각할 수 있습니다.
  • Amount ( amounts ): 소각할 토큰의 수량 리스트입니다. 수량은 16진수를 사용합니다. ids 와 amounts 의 원소 수는 항상 같아야 합니다.

API 응답

토큰 소각 API를 실행하면 다음과 같은 응답을 받습니다.

cURLJavaScriptJava
Copy
Copied
{
  "transactionHash": "0x1959a49bc76ded2e9705239868043ea0be102c5cc4b17e05248bf9a5e59b6bf1",
  "status": "Submitted"
}
Copy
Copied
{
  status: 'Submitted',
  transactionHash: '0x0eff1ae7e6887e211a7262b43d0670436ac3dd59422b55614f89c4e930ec19be'
}
Copy
Copied
class Kip37TransactionStatusResponse {
    status: Submitted
    transactionHash: 0x1959a49bc76ded2e9705239868043ea0be102c5cc4b17e05248bf9a5e59b6bf1
    transactionId: null
}

소각 결과 조회

API 호출

토큰 소각이 성공했는지 확인하기 위해 토큰 목록 조회 API GET /v2/contract/{contract-address-or-alias}/token를 사용할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET 'https://kip37-api.klaytnapi.com/v2/contract/my-first-kip37-contract/token' \
  --header "x-chain-id: {chain-id}" \
  -u {access-key-id}:{secret-access-key}
Copy
Copied
const list = await caver.kas.kip37.getTokenList("my-first-kip37-contract");
Copy
Copied
String alias = "my-first-kip37-contract";
Kip37TokenInfoListResponse response = caver.kas.kip37.getTokenList(alias);

API 응답

토큰 소각이 올바르게 수행되었을 경우 다음과 같이 totalSupply에서 0x2이 감소한 것을 확인할 수 있습니다.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "tokenId": "0x1",
      "tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
      "totalSupply": "0x10e"
    }
  ],
  "cursor": ""
}
Copy
Copied
{
  items: [
    {
      tokenId: '0x1',
      totalSupply: '0x10e',
      tokenUri: 'https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json'
    }
  ],
  cursor: ''
}
Copy
Copied
class Kip37TokenInfoListResponse {
    items: [class Kip37TokenInfoListResponseItem {
        tokenId: 0x1
        totalSupply: 0x10e
        tokenUri: https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json
    }]
    cursor:
}