송/수신 기록 조회
이 페이지는 Token History API를 사용하여 KLAY, FT, NFT 토큰의 송/수신 기록을 조회하는 방법을 안내합니다.
튜토리얼에 앞서
여기에서 소개하는 API는 HTTP 방식만을 사용하십시오.
API 호출에 사용되는
x-chain-id
값은 8217(Cypress) 또는 1001(Baobab)입니다.API 호출에 필요한 필수 파라미터는 각 예시에 설명됩니다.
API 호출 시 사용자가 입력해야 하는 값은 중괄호 1개({}
)로 표시합니다. 사용자가 입력해야 하는 값은 아래 테이블과 같습니다.
항목
값
비고
chain-id
8217 또는 1001
Cypress(Klaytn 메인넷) 또는 Baobab(Klaytn 테스트넷)
access-key-id
인증 아이디
KAS 콘솔 - Security - Credential에서 발급받은 accessKeyId
secret-access-key
인증 비밀번호
KAS 콘솔 - Security - Credential에서 발급받은 secretAccessKey
krn
(optional) 계정 저장소의 ID
기본 계정 저장소 사용 시 불필요
API 인증 키가 있으면 모든 KAS 서비스를 사용할 수 있으며 Wallet API를 호출해 만든 Klaytn 계정에 대한 모든 권한을 소유합니다. 모든 권한에는 Klaytn 계정의 자산(KLAY 등) 이동이나 트랜잭션 전송 및 실행 권한이 포함됩니다. 만약 API 인증 키에 타인이 접근한다면 Klaytn 계정 권한을 탈취당해 원치 않는 트랜잭션이 발생할 수 있습니다.
KAS/Klaytn 계정 보안을 위해 KAS API 인증 키(Secret Access Key)를 타인과 함부로 공유하지 말고 주의해 관리하십시오.
Preset으로 토큰 송/수신 기록 조회
Preset
Preset이란 KAS에서 1개 이상의 토큰 송/수신 기록을 조회하기 위해 필요한 정보입니다. KAS 콘솔에서 Preset을 등록하면 KAS는 Preset에 속한 여러 토큰의 송/수신 기록을 계속 모니터링하며 여러분이 송/수신 기록을 조회할 때 한 번에 불러올 수 있도록 합니다. Preset에는 EOA, FT 컨트랙트 주소, NFT 컨트랙트 주소를 등록할 수 있습니다. 이 API는 Preset에 있는 정보를 따라 토큰을 주고 받은 기록을 조회합니다.
FT 컨트랙트란 클레이튼에 배포되는 스마트 컨트랙트의 일종입니다. 이 컨트랙트는 대체 가능 토큰(Fungible Token, FT)을 발행, 삭제, 전송하는 기능을 제공합니다. NFT 컨트랙트란 클레이튼에 배포되는 스마트 컨트랙트의 일종입니다. 이 컨트랙트는 대체 불가 토큰(Non-Fungible Token, NFT)을 발행, 삭제, 전송하는 기능을 제공합니다.
이 API를 사용하려면 반드시 KAS 콘솔에서 Preset을 먼저 등록해야 합니다. 등록한 Preset들의 Preset ID는 KAS 콘솔에서 확인할 수 있습니다. Preset의 생성방법과 ID 확인에 관한 자세한 내용은 다음을 확인하십시오.
Preset 예시 1: EOA
다음은 EOA만을 등록한 Preset의 예시입니다.
{
"addresses": [
"0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a",
"0xa308064ad41e46310b7e463b610ae642a5007086"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 Preset에 등록한 EOA(클레이튼 계정 주소)가 KLAY/NFT/FT를 주고 받은 기록만을 API 응답으로 받습니다. 예를 들어, KLAY 전송 트랜잭션에서 from
, 또는 to
가 0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a
또는 0xa308064ad41e46310b7e463b610ae642a5007086
인 KLAY 송, 수신 기록만을 응답으로 받습니다.
Preset 예시 2: FT 컨트랙트 주소
다음은 FT 컨트랙트 주소만을 등록한 Preset의 예시입니다.
{
"ftContractAddresses": [
"0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 토큰 컨트랙트 주소값이 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d
인 FT 토큰을 주고 받은 모든 기록을 응답으로 받습니다.
Preset 예시 3: EOA와 FT 컨트랙트 주소
다음은 EOA와 FT 컨트랙트 주소를 등록한 Preset의 예시입니다.
{
"addresses": [
"0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a"
],
"ftContractAddresses":[
"0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 토큰 컨트랙트 주소값이 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d
인 FT 토큰을 주고 받은 모든 기록 중에서 from
, 또는 to
가 0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a
인 기록만 응답으로 받습니다.
Preset 예시 4: NFT 컨트랙트 주소
FT 컨트랙트 주소와 같은 방법으로 NFT 컨트랙트 주소를 다음과 같이 Preset에 저장할 수 있습니다.
{
"nftContractAddresses": [
"0x462e90a68328662163189c3b35fafeea3f6b29e8"
]
}
위 Preset만을 KAS 콘솔에 등록하고 이 API를 호출하면 토큰 컨트랙트 주소값이 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d
인 NFT 토큰을 주고 받은 모든 기록을 응답으로 받습니다. NFT 컨트랙트 주소 또한 위 예시 3과 같이 EOA와 복합적으로 사용될 수 있습니다.
모든 트랜잭션은 하나의 블록체인에 기록되며 송신인(from), 수신인(to)에 따라 거래내역을 송신 또는 수신으로 해석할 수 있습니다. Token History API는 블록체인 트랜잭션을 거래내역으로 저장하며 사용자 요청에 맞는 형태로 거래내역들을 반환합니다.
API 호출
다음과 같이 Preset을 사용해서 토큰 송/수신 기록을 조회합니다.
쿼리 파라미터
여러분은 거래 토큰 유형(kind), 조회 범위(range), 응답 크기(size), 조회에 사용할 Preset 등을 지정하여 거래내역을 조회할 수 있습니다. 또 커서 방식 페이지네이션을 사용해 API 응답값을 받아올 수 있습니다.
파라미터 이름
설명
예시
필수
kind
[“klay”, “ft”, “nft”] 중 포함 할 유형 값이 지정 안 될 경우 모든 유형을 조회
kind=klay 또는 kind=klay,ft,nft
False
range
조회 범위 지정 (블록번호 또는 Unix time) 블록번호는 16진수로, unix time은 10자리 숫자로 입력
range=0x1,0x2
또는 range=1592360291,15991809920
False
size
응답 아이템 개수 (min=1, max=1000, default=100)
size=100
False
cursor
페이지네이션으로 다음 요청을 보낼 때 필요한 커서
cursor=J9Ag...VM6z
False
presets
검색에 사용할 Preset ID들
presets=65,68
True
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}
API 응답
요청이 성공할 경우 다음과 같은 응답을 받습니다.
{
"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": ""
}
이 API에 관한 자세한 내용은 다음을 확인하십시오. 이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
트랜잭션 해시로 토큰 송/수신 기록 조회
토큰을 송, 수신하는 트랜잭션의 트랜잭션 해시값이 있을 때, 이 트랜잭션 해시로 토큰을 주고 받은 기록을 조회합니다.
API 호출
다음과 같이 트랜잭션 해시 기반 토큰 송/수신 기록을 조회합니다.
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}
transaction-hash
(0x9fb236689b2...ac7358db8d73)는 블록체인에 포함된 트랜잭션의 32-byte 해시이며 필수 입력값입니다.
API 응답
요청이 성공할 경우 다음과 같은 응답을 받습니다.
{
"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
}
]
}
이 API에 관한 자세한 내용은 다음을 확인하십시오. 이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
EOA로 토큰 송/수신 기록 조회
특정 EOA가 토큰을 주고 받은 기록을 조회합니다.
API 호출
다음과 같이 EOA 기반 토큰 송/수신 기록을 조회합니다.
쿼리 파라미터
사용자는 거래 토큰 유형(kind), 조회 범위(range), 응답 크기(size), 특정 컨트랙트 주소(ca-filter) 등을 지정하여 거래내역을 조회할 수 있습니다. 또 커서 방식 페이지네이션을 사용해 API 응답값을 받아올 수 있습니다.
파라미터 이름
설명
예시
필수
kind
[“klay”, “ft”, “nft”] 중 포함 할 유형 지정안될 경우 모든 유형을 조회 (i.e., klay,ft,nft)
kind=klay 또는 kind=klay,ft,nft
False
range
조회 범위 지정 (블록번호 또는 Unix time) 블록번호는 16진수로, unix time은 10자리 숫자로 입력
range=0x1,0x2
또는 range=1592360291,15991809920
False
size
응답 아이템 개수 (min=1, max=1000, default=100)
size=100
False
cursor
페이지네이션으로 다음 요청을 보낼 때 필요한 커서
cursor=J9Ag...VM6z
False
ca-filter
조회할 FT 또는 NFT 컨트랙트의 주소
ca-filter=0xc756...1118
False
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}
address
는 조회하려는 EOA이며 필수 입력값입니다.API 호출 예시에 사용된
0xc060...d48f
는 임의의 값입니다.
API 응답
요청이 성공할 경우 다음과 같은 응답을 받습니다.
{
"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"
}
이 API에 관한 자세한 내용은 다음을 확인하십시오. 이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
Last updated
Was this helpful?