MT 컨트랙트 배포 및 토큰 발행/전송
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를 사용하여 컨트랙트를 배포하고 토큰을 발급/전송/소각하는 법에 대해 설명하겠습니다. 전체 KIP-37 API에 대한 자세한 사양은 KAS KIP-37 API Reference를 통해 확인하실 수 있습니다.

KIP-37 컨트랙트 배포

KIP-37 API는 KIP-37 표준을 따르는 MT 컨트랙트를 배포하고 제어합니다.
KIP-37 컨트랙트 표준 함수 및 소스코드에 관한 더 자세한 정보는 KIP-37 Standardklaytn/klaytn-contracts을 확인하세요.
KIP-37 컨트랙트의 배포는 다음과 같은 curl 명령어를 실행하여 수행할 수 있습니다.
curl
1
curl --location --request POST "https://kip37-api.klaytnapi.com/v1/contract" \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key} \
4
--data-raw '{
5
"alias": "my-first-kip37-contract",
6
"uri": "https://token-cdn-domain/{id}.json",
7
"options": {
8
"enableGlobalFeePayer": true
9
}
10
}'
Copied!

API 경로와 요청

curl 명령어를 부분으로 나누어 하나씩 살펴보겠습니다. 컨트랙트 배포 APIPOST /v1/contract로 실행할 수 있습니다. KIP-37 API가 https://kip37-api.klaytnapi.com에서 서비스되고 있으니 curl 요청의 URL을 https://kip37-api.klaytnapi.com/v1/contract로, 요청 유형은 POST (—-request POST)로 설정합니다.
컨트랙트 배포 API는 POST 요청을 받아들이며 다음과 같은 JSON 데이터를 요구합니다.
curl
1
{
2
"alias": "my-first-kip37-contract",
3
"uri": "https://token-cdn-domain/{id}.json",
4
"options": {
5
"enableGlobalFeePayer": true
6
}
7
}
Copied!
각각의 필드에 대한 설명은 다음과 같습니다.
    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를 확인하세요.

필수 헤더

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

인증

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

API 응답

컨트랙트 배포 curl 명령어를 실행하면 다음과 같은 결과를 받게 됩니다.
curl
1
{
2
"status": "Submitted",
3
"transactionHash": "0xca97254ab324a5a205538e83b5559c469cdc3f366659f610642021a3febab32f",
4
"options": {
5
"enableGlobalFeepayer": true,
6
"userFeePayer": {
7
"address": "",
8
"krn": ""
9
}
10
}
11
}
Copied!
결과로 받는 transactionHashklay_getTransactionReceipt과 같은 RPC 함수를 실행할 때 사용할 수 있습니다.

결과 확인

KIP-37 API의 컨트랙트 목록 조회 API(GET /v1/contract)를 사용하여 배포한 컨트랙트를 조회할 수 있습니다. 다음 curl 명령어를 실행하여 컨트랙트 목록을 조회합니다.
컨트랙트 정보 조회 API(GET /v1/contract/{contract-address-or-alias})를 사용하여 컨트랙트를 조회할 수 있습니다.
curl
1
curl --location --request GET 'https://kip37-api.klaytnapi.com/v1/contract' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key}
Copied!
컨트랙트가 올바르게 배포되었다면 다음과 같은 응답을 받습니다.
curl
1
{
2
"items": [
3
{
4
"address": "0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a",
5
"alias": "my-first-kip37-contract",
6
"options": {
7
"enableGlobalFeePayer": true,
8
"userFeePayer": {
9
"address": "",
10
"krn": ""
11
}
12
},
13
"status": "deployed",
14
"uri": "https://token-cdn-domain/{id}.json"
15
}
16
],
17
"cursor": ""
18
}
Copied!

KIP-37 토큰 생성

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

토큰 생성 요청

다음은 앞서 예제에서 사용된 alias my-first-kip37-contract을 사용하여 토큰 생성 API를 호출하는 curl 명령어입니다.
토큰 생성 API를 이용하면 실제 컨트랙트의 function create(uint256 _id, uint256 _initialSupply, string calldata _uri) external returns (bool); 함수를 호출합니다.
curl
1
curl --location --request POST 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key} \
4
--data-raw '{
5
"sender": "",
6
"id": "0x1",
7
"initialSupply": "0x100",
8
"uri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json"
9
}'
Copied!
필수 헤더, 인증 정보 등은 컨트랙트 배포 API와 동일하며 location, request와 같은 정보는 토큰 발행 API(POST /v1/contract/{contract-address-or-alias}/token)에 맞추어 입력합니다.
토큰 발행 API는 다음과 같은 JSON 데이터를 요구합니다.
curl
1
{
2
"sender": "",
3
"id": "0x1",
4
"initialSupply": "0x100",
5
"uri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json"
6
}
Copied!
    Sender (sender): 토큰을 생성할 Klaytn 계정 주소로써 Minter 권한이 있어야 합니다. 생략 시 컨트랙트를 배포한 계정으로 토큰을 생성합니다. 컨트랙트 배포 계정(deployer)은 컨트랙트 배포 기본 계정 조회를 통해 확인 가능합니다.
    Token ID (id): 생성할 토큰의 16진수로 표현된 고유번호입니다. 이미 발행되어있는 토큰의 고유번호는 사용할 수 없습니다. 단, 소각된 토큰의 고유번호는 재사용할 수 있습니다.
    Initial Supply (initialSupply): 16진수로 표현된 토큰의 발행량입니다.
    Token URI (uri): 토큰 정보를 담은 JSON 파일의 위치를 URI로 표현한 값입니다. 해당 토큰의 정보, 속성 등을 기록하여 URI로 표현될 수 있는 위치에 사전 배포한 뒤 토큰 발행 시 해당 URI를 포함시킵니다. URI 링크의 유효성 여부는 확인하지 않으니 주의하여 입력 부탁드립니다.
Klaytn 계정의 주소는 16진수로 표현됩니다. 길이는 20-byte로, 접두사 "0x"를 포함하여 16진수 42자로 표현됩니다.

토큰 발행 응답과 발행 결과 확인

토큰 발행 curl을 수행하면 다음과 같은 응답을 받을 수 있습니다.
curl
1
{
2
"transactionHash": "0x354aed16b2dbf43b32ab6fdd259c9d3d7b244236870658979a8a2b34fa7b579b",
3
"status": "Submitted"
4
}
Copied!
응답의 status를 눈여겨 보셨다면 "Success"나 "Completed"가 아닌 "Submitted"인 것을 확인할 수 있습니다. Klaytn을 비롯한 모든 블록체인은 요청에 대한 응답이 즉시 돌아오지 않는 비동기 형태로 동작하기 때문에 요청이 성공했는지 바로 확인할 수 없습니다. 특히 토큰 발행과 같이 요청값에 따라 요청이 실패할 수 있는 경우가 존재하기 때문에, 토큰 목록 조회 실행 등을 통해 명시적으로 확인해야 합니다.
컨트랙트 배포를 실행했을 때와 같은 형식의 응답이 오는 것을 확인할 수 있습니다.
토큰이 잘 발행되었는지 확인하려면 토큰 목록 조회 API GET /v1/contract/{contract-address-or-alias}/token를 사용하여 새로 발행한 토큰이 컨트랙트에 추가되었는지 확인합니다.
다음 curl 명령어를 사용하여 my-first-kip37-contract 컨트랙트의 토큰 목록을 조회할 수 있습니다.
curl
1
curl --location --request GET 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key}
Copied!
토큰이 성공적으로 발행되었다면 다음과 같은 응답을 받을 수 있습니다.
curl
1
{
2
"items": [
3
{
4
"tokenId": "0x1",
5
"tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
6
"totalSupply": "0x100"
7
}
8
],
9
"cursor": ""
10
}
Copied!

토큰 추가 발행

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

토큰 추가 발행 요청

다음은 앞서 예제에서 사용된 alias my-first-kip37-contract, token id 0x1를 사용하여 토큰 추가 발행 API를 호출하는 curl 명령어입니다.
토큰 추가 API를 이용하면 실제 컨트랙트의 function mint(uint256 _id, address _to, uint256 _value) external;(단일), function mintBatch(address _to, uint256[] calldata _ids, uint256[] calldata _values)(다중) 함수를 호출합니다.
curl
1
curl --location --request POST 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token/mint' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key} \
4
--data-raw '{
5
"sender": "",
6
"to": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
7
"ids": [
8
"0x1"
9
],
10
"amounts": [
11
"0x10"
12
]
13
}'
Copied!
    Sender (sender): 토큰을 추가 발행할 Klaytn 계정 주소로써 Minter 권한이 있어야 합니다. 생략 시 컨트랙트를 배포한 계정으로 토큰을 생성합니다. 컨트랙트 배포 계정(deployer)은 컨트랙트 배포 기본 계정 조회를 통해 확인 가능합니다.
    Recipient (to): 토큰을 받는 사람의 Klaytn 계정 주소입니다. 토큰 추가 발행 API는 지정된 주소로 추가 발행합니다.
    Token ID (ids): 추가 발행할 토큰의 고유번호 리스트입니다. KIP-37에서는 다중 토큰을 추가 발행할 수 있습니다.
    Amount (amounts): 추가 발행할 토큰의 수량 리스트입니다. 수량은 16진수를 사용합니다. idsamounts의 원소 수는 항상 같아야 합니다.

토큰 추가 응답과 결과 확인

토큰 추가 발행 curl을 수행하면 다음과 같은 응답을 받을 수 있습니다.
curl
1
{
2
"status": "Submitted",
3
"transactionHash": "0x63172503a362566aeed9e64271830ddc090affe7612f99e5f2415caaa379a7f3"
4
}
Copied!
토큰 생성과 마찬가지로 토큰 목록 조회 API GET /v1/contract/{contract-address-or-alias}/token를 사용하여 토큰 발행량(totalSupply)을 확인할 수 있습니다.
curl
1
curl --location --request GET 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key}
Copied!
1
{
2
"items": [
3
{
4
"tokenId": "0x1",
5
"tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
6
"totalSupply": "0x110"
7
}
8
],
9
"cursor": ""
10
}
Copied!

KIP-37 토큰 전송

KIP-37 토큰을 전송하는 APIPOST /v1/contract/{contract-address-or-alias}/token/transfer입니다.
이 예제는 KAS 사용자가 KAS Wallet Account Pool에 등록한 계정이 이미 존재한다고 가정합니다.
계정 생성과 관리는 여기를 참조해주시기 바랍니다.
KIP-37 API로 토큰을 전송하려면 토큰을 보내는 사람의 계정의 (cryptographic) key가 KAS Wallet Account Pool에 등록되어 있어야 합니다. 만약 Key가 Default Account Pool에 등록되어 있지 않을 경우 해당 Pool의 KRN을 x-krn 헤더에 직접 입력해야합니다.
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; 함수를 호출합니다.

토큰 전송 요청

다음 curl 명령어는 소유 계정(0xd9Fe560d3141E78CDd2F617147985e458a529c1E)이 소유한 my-first-kip37-contract 컨트랙트의 0x1 토큰을 수령 계정(0x74B9bE845D276E6382081995A61a65da91C76328)으로 1개(0x1) 전송합니다.
curl
1
curl --location --request POST 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token/transfer' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key} \
4
--data-raw '{
5
"sender": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
6
"owner": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
7
"to": "0x74B9bE845D276E6382081995A61a65da91C76328",
8
"ids": [
9
"0x1"
10
],
11
"amounts": [
12
"0x1"
13
]
14
}'
Copied!
토큰 전송에 필요한 JSON 데이터는 다음과 같습니다.
    Sender (sender): 토큰을 전송할 Klaytn 계정 주소입니다. 만약 senderowner가 다를 경우 sender는 반드시 해당 토큰의 전송 권한을 가지고 있어야 합니다. 토큰 전송 승인 권한 API를 이용하여 권한을 부여할 수 있습니다.
    Owner (owner): 토큰을 소유한 Klaytn 계정 주소입니다.
    Recipient (to): 토큰을 받는 사람의 주소입니다. 블록체인 특성상 토큰을 전송하면 되돌릴 수 없으니 주의하시기 바랍니다.
    Token ID (ids): 전송할 토큰의 16진수로 표현된 고유번호 리스트입니다. KIP-37에서는 다중 토큰을 전송할 수 있습니다.
    Amount (amounts): 전송할 토큰의 수량 리스트입니다. 수량은 16진수를 사용합니다. idsamounts의 원소 수는 항상 같아야 합니다.

토큰 전송 응답과 결과 확인

토큰 전송 API를 실행하면 다음과 같은 응답을 받습니다.
curl
1
{
2
"transactionHash": "0xe935aa5b7dcd22fc9f3420126d702d23a38ebed8c7eb3f264a930d5377176e18",
3
"status": "Submitted"
4
}
Copied!
토큰 전송을 성공했는지 확인하기 위해 특정 계정이 소유한 토큰 목록 조회 API GET /v1/contract/{contract-address-or-alias}/owner/{owner-address}/token를 사용하여 전송한 토큰의 정보가 올바르게 변경되었는지 확인할 수 있습니다.
curl
1
curl --location --request GET 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/owner/0x74B9bE845D276E6382081995A61a65da91C76328/token'
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key}
Copied!
토큰 전송이 올바르게 수행되었을 경우 다음과 같이 전송한 토큰의 정보가 변경된 것을 확인할 수 있습니다.
1
{
2
"items": [
3
{
4
"balance": "0x1",
5
"owner": "0x74b9be845d276e6382081995a61a65da91c76328",
6
"tokenAddress": "0x52914186f3a7324ba1f0172b2d33c8e8712cdd9a",
7
"tokenId": "0x1",
8
"tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
9
"totalSupply": "0x110",
10
"transactionHash": "0xe935aa5b7dcd22fc9f3420126d702d23a38ebed8c7eb3f264a930d5377176e18",
11
"transferFrom": "0xd9fe560d3141e78cdd2f617147985e458a529c1e",
12
"transferTo": "0x74b9be845d276e6382081995a61a65da91c76328",
13
"updatedAt": 1627980971
14
}
15
],
16
"cursor": ""
17
}
Copied!

KIP-37 토큰 소각

KIP-37 토큰을 소각하는 APIDELETE /v1/contract/{contract-address-or-alias}/token입니다.
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; 함수를 호출합니다.

토큰 소각 요청

다음 curl 명령어는 소유 계정(0xd9Fe560d3141E78CDd2F617147985e458a529c1E)이 소유한 my-first-kip37-contract 컨트랙트의 0x1 토큰을 2개(0x2) 소각합니다.
curl
1
curl --location --request DELETE 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key} \
4
--data-raw '{
5
"from": "0xd9Fe560d3141E78CDd2F617147985e458a529c1E",
6
"ids": [
7
"0x1"
8
],
9
"amounts": [
10
"0x2"
11
]
12
}'
Copied!
토큰 소각에 필요한 JSON 데이터는 다음과 같습니다.
    From (from): 토큰을 소각할 Klaytn 계정 주소입니다.
    Token ID (ids): 소각할 토큰의 16진수로 표현된 고유번호 리스트입니다. KIP-37에서는 다중 토큰을 소각할 수 있습니다.
    Amount (amounts): 소각할 토큰의 수량 리스트입니다. 수량은 16진수를 사용합니다. idsamounts의 원소 수는 항상 같아야 합니다.

토큰 소각 응답과 결과 확인

토큰 소각 API를 실행하면 다음과 같은 응답을 받습니다.
curl
1
{
2
"transactionHash": "0x1959a49bc76ded2e9705239868043ea0be102c5cc4b17e05248bf9a5e59b6bf1",
3
"status": "Submitted"
4
}
Copied!
토큰 소각이 성공했는지 확인하기 위해 토큰 목록 조회 API GET /v1/contract/{contract-address-or-alias}/token를 사용할 수 있습니다.
curl
1
curl --location --request GET 'https://kip37-api.klaytnapi.com/v1/contract/my-first-kip37-contract/token' \
2
--header "x-chain-id: {chain-id}" \
3
-u {access-key-id}:{secret-access-key}
Copied!
토큰 소각이 올바르게 수행되었을 경우 다음과 같이 totalSupply에서 0x2이 감소한 것을 확인할 수 있습니다.
1
{
2
"items": [
3
{
4
"tokenId": "0x1",
5
"tokenUri": "https://token-cdn-domain/0000000000000000000000000000000000000000000000000000000000000001.json",
6
"totalSupply": "0x10e"
7
}
8
],
9
"cursor": ""
10
}
Copied!
Last modified 1mo ago