튜토리얼에 앞서
여기에서 소개하는 API는 HTTP 방식만을 사용하십시오.
API 호출에 사용되는 x-chain-id
값은 8217(Cypress) 또는 1001(Baobab)입니다.
API 호출에 필요한 필수 파라미터는 각 예시에 설명됩니다.
API 호출 시 사용자가 입력해야 하는 값은 중괄호 1개({}
)로 표시합니다. 사용자가 입력해야 하는 값은 아래 테이블과 같습니다.
Cypress(Klaytn 메인넷) 또는 Baobab(Klaytn 테스트넷)
KAS 콘솔 - Security - Credential에서 발급받은 accessKeyId
KAS 콘솔 - Security - Credential에서 발급받은 secretAccessKey
API 인증 키가 있으면 모든 KAS 서비스를 사용할 수 있으며 Wallet API를 호출해 만든 Klaytn 계정에 대한 모든 권한을 소유합니다. 모든 권한에는 Klaytn 계정의 자산(KLAY 등) 이동이나 전송 및 실행 권한이 포함됩니다. 만약 API 인증 키에 타인이 접근한다면 Klaytn 계정 권한을 탈취당해 원치 않는 트랜잭션이 발생할 수 있습니다.
KAS/Klaytn 계정 보안을 위해 KAS API 인증 키(Secret Access Key)를 타인과 함부로 공유하지 말고 주의해 관리하십시오.
Preset으로 토큰 송/수신 기록 조회
Preset
Preset이란 KAS에서 1개 이상의 토큰 송/수신 기록을 조회하기 위해 필요한 정보입니다. 에서 Preset을 등록하면 KAS는 Preset에 속한 여러 토큰의 송/수신 기록을 계속 모니터링하며 여러분이 송/수신 기록을 조회할 때 한 번에 불러올 수 있도록 합니다. Preset에는 EOA, FT 컨트랙트 주소, NFT 컨트랙트 주소를 등록할 수 있습니다. 이 API는 Preset에 있는 정보를 따라 토큰을 주고 받은 기록을 조회합니다.
Preset 예시 1: EOA
다음은 EOA만을 등록한 Preset의 예시입니다.
Copy {
"addresses": [
"0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a",
"0xa308064ad41e46310b7e463b610ae642a5007086"
]
}
Preset 예시 2: FT 컨트랙트 주소
다음은 FT 컨트랙트 주소만을 등록한 Preset의 예시입니다.
Copy {
"ftContractAddresses": [
"0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 토큰 컨트랙트 주소값이 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d
인 FT 토큰을 주고 받은 모든 기록을 응답으로 받습니다.
Preset 예시 3: EOA와 FT 컨트랙트 주소
다음은 EOA와 FT 컨트랙트 주소를 등록한 Preset의 예시입니다.
Copy {
"addresses": [
"0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a"
],
"ftContractAddresses":[
"0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 토큰 컨트랙트 주소값이 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d
인 FT 토큰을 주고 받은 모든 기록 중에서 from
, 또는 to
가 0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a
인 기록만 응답으로 받습니다.
Preset 예시 4: NFT 컨트랙트 주소
FT 컨트랙트 주소와 같은 방법으로 NFT 컨트랙트 주소를 다음과 같이 Preset에 저장할 수 있습니다.
Copy {
"nftContractAddresses": [
"0x462e90a68328662163189c3b35fafeea3f6b29e8"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 토큰 컨트랙트 주소값이 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d
인 NFT 토큰을 주고 받은 모든 기록을 응답으로 받습니다. NFT 컨트랙트 주소 또한 위 예시 3과 같이 EOA와 복합적으로 사용될 수 있습니다.
모든 트랜잭션은 하나의 블록체인에 기록되며 송신인(from), 수신인(to)에 따라 거래내역을 송신 또는 수신으로 해석할 수 있습니다. Token History API는 블록체인 트랜잭션을 거래내역으로 저장하며 사용자 요청에 맞는 형태로 거래내역들을 반환합니다.
API 호출
다음과 같이 Preset을 사용해서 토큰 송/수신 기록을 조회합니다.
쿼리 파라미터
[“klay”, “ft”, “nft”] 중 포함 할 유형
값이 지정 안 될 경우 모든 유형을 조회
kind=klay 또는 kind=klay,ft,nft
조회 범위 지정 (블록번호 또는 Unix time)
블록번호는 16진수로, unix time은 10자리 숫자로 입력
range=0x1,0x2
또는 range=1592360291,15991809920
응답 아이템 개수 (min=1, max=1000, default=100)
페이지네이션으로 다음 요청을 보낼 때 필요한 커서
Copy curl --location --request GET "https://th-api.klaytnapi.com/v2/transfer?kind=klay,ft,nft&presets=65,68&range=1592360291,15991809920" \
--header "x-chain-id: {chain-id}" \
-u {access-key-id}:{secret-access-key}
Copy const query = {
kind: [caver.kas.tokenHistory.queryOptions.kind.KLAY],
size: 1,
range: '1593529200,1599145200',
}
const result = await caver.kas.tokenHistory.getTransferHistory([80], query)
Copy TokenHistoryQueryOptions options = new TokenHistoryQueryOptions();
options.setSize((long)1);
options.setRange("1584583000", "1584583388");
options.setKind("ft");
PageableTransfers result = caver.kas.tokenHistory.getTransferHistory(82, options);
System.out.println(result);
API 응답
요청이 성공할 경우 다음과 같은 응답을 받습니다.
Copy {
"items": [
{
"transferType": "klay",
"from": "0xfee21dec2936f4cf7714080559db1c53ce639e07",
"fee": "0x2114b6e5980400",
"status": 1,
"to": "0xe33337cb6fbb68954fe1c3fde2b21f56586632cd",
"transactionHash": "0xa0f6663d713bf173e9e2563f588ab11dc09df34970ae60c5e7bf5c383a8bc17c",
"transactionIndex": 0,
"typeInt": 48,
"timestamp": 1596025548,
"value": "0x218ae196b8d4f300000",
"feePayer": "",
"feeRatio": 10
},
{
"transferType": "klay",
"from": "0xe83d131a941b767594262f1e7d635260b2facc61",
"fee": "0x2c0dbbfb37000",
"status": 1,
"to": "0xfee21dec2936f4cf7714080559db1c53ce639e07",
"transactionHash": "0x61f1e0b317b0bbb2d29a58c1791b8290210188b5422f53b135f3cbb993140876",
"transactionIndex": 0,
"typeInt": 9,
"timestamp": 1596025448,
"value": "0x218ae3cf27fbef10000",
"feePayer": "0x10f0eaa52a474f0605afbb8c17bb9189e6ed006c",
"feeRatio": 10
}
],
"cursor": ""
}
Copy PageableTransfers {
items: [
TransferItem {
feePayer: '',
feeRatio: 0,
fee: '0x48ba158a44a00',
from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
to: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
transactionHash: '0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad',
transactionIndex: 0,
transferType: 'klay',
typeInt: 48,
value: '0x0'
}
],
cursor: 'qrX1b6xwlmk9PJea2XLzoN30gKQAYGxbvro0Qk97dx5WAvJBpaKw6lPR1VLbVEzQV2P6XtYuNjgzVXe1DL4MGEbmO823NqYZWlk4rqdpVwm51B86ZD7EOM2WeDNBPQKE'
}
Copy class PageableTransfers {
items: class TransferArray {
[class FtTransfer {
contract: class FtContract {
address: 0x770b5c4854497d7c5abe3e5d6ed2dbaf3eac2a77
decimals: 18
name: SummerToken_20200319110306
symbol: JUN
status: null
}
formattedValue: 0.00000001
from: 0x4df3ee7caf91a7ab60a37815de3c6db4a008d8c0
to: 0x278868807791af859cee547a016bd339eb86ec98
transaction: class Transaction {
feePayer:
feeRatio: 0
fee: 0x0
from: 0x4df3ee7caf91a7ab60a37815de3c6db4a008d8c0
timestamp: 1584583388
transactionHash: 0xd3eb91c71f99ec7451f1908e147ffbfd1e25a9179837d025196825d7e6716200
typeInt: 48
value: 0x0
}
transferType: ft
value: 0x2540be400
}]
}
cursor: lv4WNYedqPJM1N38XZwpKq5JoQ9PmYledPZqmXb5r4V26Y81gx0lLWDRbEuOGWJ20rl40GTWyJav37MQAokw9ENGKzeBdpOgr2zLV0B7DOAx4avEGW6bkkLg7AOb53Za
}
트랜잭션 해시로 토큰 송/수신 기록 조회
토큰을 송, 수신하는 트랜잭션의 트랜잭션 해시값이 있을 때, 이 트랜잭션 해시로 토큰을 주고 받은 기록을 조회합니다.
API 호출
다음과 같이 트랜잭션 해시 기반 토큰 송/수신 기록을 조회합니다.
Copy curl --location --request GET "https://th-api.klaytnapi.com/v2/transfer/tx/0x9fb236689b26fc8b8a938a8eb2b7e5a6afc1c7a837c61751f08eac7358db8d73" \
--header "x-chain-id: {chain-id}" \
-u {access-key-id}:{secret-access-key}
Copy const result = await caver.kas.tokenHistory.getTransferHistoryByTxHash('0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad')
Copy String txHash = "0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb";
Transfers transfers = caver.kas.tokenHistory.getTransferHistoryByTxHash(txHash);
System.out.println(transfers);
transaction-hash
(0x9fb236689b2...ac7358db8d73)는 블록체인에 포함된 트랜잭션의 32-byte 해시이며 필수 입력값입니다.
API 응답
요청이 성공할 경우 다음과 같은 응답을 받습니다.
Copy {
"items": [
{
"transferType": "ft",
"transaction": {
"from": "0x5bf30ff4a1a3a905531c5e1b52c635892a9fc28d",
"fee": "0x48abe561cf400",
"transactionHash": "0x9fb236689b26fc8b8a938a8eb2b7e5a6afc1c7a837c61751f08eac7358db8d73",
"typeInt": 49,
"timestamp": 1597649114,
"value": "0x0",
"feePayer": "0xacb22916b804ac088c61c8711ec196b518f2e7fc",
"feeRatio": 10
},
"contract": {
"address": "0xb1a7abe0c5a9e06cc7585a435e74976d2dee07f3",
"name": "BlockchainPetToken",
"symbol": "BPT",
"decimals": 2
},
"from": "0x5bf30ff4a1a3a905531c5e1b52c635892a9fc28d",
"to": "0xeb7f7926cc4f866cec135728d35a7531c1d12791",
"value": "0x3e8",
"formattedValue": "10"
},
{
"transferType": "klay",
"from": "0x5bf30ff4a1a3a905531c5e1b52c635892a9fc28d",
"fee": "0x48abe561cf400",
"status": 1,
"to": "0xb1a7abe0c5a9e06cc7585a435e74976d2dee07f3",
"transactionHash": "0x9fb236689b26fc8b8a938a8eb2b7e5a6afc1c7a837c61751f08eac7358db8d73",
"transactionIndex": 1,
"typeInt": 49,
"timestamp": 1597649114,
"value": "0x0",
"feePayer": "0xacb22916b804ac088c61c8711ec196b518f2e7fc",
"feeRatio": 10
}
]
}
Copy Transfers {
items: [
TransferItem {
feePayer: '',
feeRatio: 0,
fee: '0x48ba158a44a00',
from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
to: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
transactionHash: '0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad',
transactionIndex: 0,
transferType: 'klay',
typeInt: 48,
value: '0x0'
}
]
}
Copy class Transfers {
items: class TransferArray {
[class KlayTransfer {
feePayer:
feeRatio: 0
fee: 0x0
from: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
to: 0x770b5c4854497d7c5abe3e5d6ed2dbaf3eac2a77
transactionHash: 0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb
transactionIndex: 0
transferType: klay
typeInt: 48
value: 0x0
}, class FtTransfer {
contract: class FtContract {
address: 0x770b5c4854497d7c5abe3e5d6ed2dbaf3eac2a77
decimals: 18
name: SummerToken
symbol: JUN
status: null
}
formattedValue: 0.000000000000000001
from: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
to: 0xdc0586196d01579e08218bb46f861071241a3238
transaction: class Transaction {
feePayer:
feeRatio: 0
fee: 0x0
from: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
timestamp: 1584583410
transactionHash: 0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb
typeInt: 48
value: 0x0
}
transferType: ft
value: 0x1
}]
}
}
EOA로 토큰 송/수신 기록 조회
특정 EOA가 토큰을 주고 받은 기록을 조회합니다.
API 호출
다음과 같이 EOA 기반 토큰 송/수신 기록을 조회합니다.
쿼리 파라미터
[“klay”, “ft”, “nft”] 중 포함 할 유형
지정안될 경우 모든 유형을 조회 (i.e., klay,ft,nft)
kind=klay 또는 kind=klay,ft,nft
조회 범위 지정 (블록번호 또는 Unix time)
블록번호는 16진수로, unix time은 10자리 숫자로 입력
range=0x1,0x2
또는 range=1592360291,15991809920
응답 아이템 개수 (min=1, max=1000, default=100)
페이지네이션으로 다음 요청을 보낼 때 필요한 커서
Copy curl --location --request GET "https://th-api.klaytnapi.com/v2/transfer/account/0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f?kind=klay,ft,nft&range=1592360291,15991809920" \
--header "x-chain-id: {chain-id}" \
-u {access-key-id}:{secret-access-key}
Copy const query = {
kind: [caver.kas.tokenHistory.queryOptions.kind.NFT],
size: 1,
range: '1593529200,1599145200',
caFilter: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
}
const result = await caver.kas.tokenHistory.getTransferHistoryByAccount('0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1', query)
Copy String account = "0x74f630bfcf6f3e8d7523b39de821b876446adbd4";
String caFilter = "0xdb71dd9e38af6cb8fdd7cfe498c2337864d5a0f6";
TokenHistoryQueryOptions options = new TokenHistoryQueryOptions();
options.setKind("nft");
options.setRange("1584583430", "1584583500");
options.setSize((long)1);
options.setCaFilter(caFilter);
PageableTransfers transfers = caver.kas.tokenHistory.getTransferHistoryByAccount(account, options);
System.out.println(transfers);
address
는 조회하려는 EOA이며 필수 입력값입니다.
API 호출 예시에 사용된 0xc060...d48f
는 임의의 값입니다.
API 응답
요청이 성공할 경우 다음과 같은 응답을 받습니다.
Copy {
"items": [
{
"transferType": "klay",
"from": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
"fee": "0x6b7cf1b09bc00",
"status": 1,
"to": "0xd07453030abc0e37ee81371e2505bf55e0be6440",
"transactionHash": "0x8771b0bbf25c19dc0d4be3e4a536830a26f4a06e129b34f49b4ac765bf9d6185",
"transactionIndex": 3,
"typeInt": 48,
"timestamp": 1598855708,
"value": "0x0",
"feePayer": "",
"feeRatio": 10
},
{
"transferType": "ft",
"transaction": {
"from": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
"fee": "0x6b7cf1b09bc00",
"transactionHash": "0x8d9c23f2a9381243062b5f5b15f9d4793942bc74d7f6a3ac9bbb294e693c1540",
"typeInt": 48,
"timestamp": 1582622881,
"value": "0x0",
"feePayer": "",
"feeRatio": 10
},
"contract": {
"address": "0x46f307b58bf05ff089ba23799fae0e518557f87c",
"name": "Airbloc",
"symbol": "ABL",
"decimals": 18
},
"from": "0xd07453030abc0e37ee81371e2505bf55e0be6440",
"to": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
"value": "0xde0b6b3a7640000",
"formattedValue": "1"
},
...
,
{
"transferType": "klay",
"from": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
"fee": "0x449e582f0cc00",
"status": 1,
"to": "0xd07453030abc0e37ee81371e2505bf55e0be6440",
"transactionHash": "0xc93453af98297b953afb34f8aed92ae2acc3d96cd5291e9fc43bfea1fedfc076",
"transactionIndex": 0,
"typeInt": 0,
"timestamp": 1582254900,
"value": "0x0",
"feePayer": "",
"feeRatio": 10
}
],
"cursor": "18G42d0gY531Z2pzqEVrDWMLmQ9kz2epXE8JZwadKGrOqW3oVRxN6PAJX73aKMgTKW6LBZJe2OvvT2nDL6Pxgb9m4YQv5AM0NlB17ePxoOK8vk74wbG6NaBAJlX309vK"
}
Copy PageableTransfers {
items: [
TransferItem {
from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
to: '0x88ab3cdbf31f856de69be569564b751a97ddf5d8',
transferType: 'nft',
contract: [FtContract],
transaction: [Transaction],
tokenId: '0x7b'
}
],
cursor: 'bk8XJaEYv0P46ZA8kXLewmDBJVOKWzQ3dL3wPG8EYJDxqN5O9r2M4B0jLBubuAx1AZdbeJ6EbypQlaKVWZbd7vX1kAeozgm6r0G1qEalMN59pPY7bgxvo29BwxN1oArm'
}
Copy class PageableTransfers {
items: class TransferArray {
[class NftTransfer {
contract: class NftContract {
address: 0xdb71dd9e38af6cb8fdd7cfe498c2337864d5a0f6
name: GX_CARD_20200319110355
symbol: GXC
status: null
}
from: 0x0000000000000000000000000000000000000000
to: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
transaction: class Transaction {
feePayer:
feeRatio: 0
fee: 0x0
from: 0x34d962ddf56101f2203fe4f5818b3b3117259489
timestamp: 1584583438
transactionHash: 0x233eb685f778d0ed1f5d081cc278943f9e9d60f2a1b215786250f5943088aa7f
typeInt: 48
value: 0x0
}
transferType: nft
tokenId: 0xba873
}]
}
cursor: OMxbp2v3Qq4DlQ94KGkxM15mAYgpNbO6XK6NXmYopkZJQrlOA7LVaMGy26ueuzroaED9KEZJyx842BW39zEebDP1dwq50vg8daz7qBPEJVrZ0w2WoeL3vwE815WXK0Z9
}