송/수신 기록 조회

이 페이지는 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}

const query = {
    kind: [caver.kas.tokenHistory.queryOptions.kind.KLAY],
    size: 1,
    range: '1593529200,1599145200',
}
const result = await caver.kas.tokenHistory.getTransferHistory([80], query)

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 응답

요청이 성공할 경우 다음과 같은 응답을 받습니다.

{
    "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": ""
}

PageableTransfers {
    items: [ 
        TransferItem {
            feePayer: '',
            feeRatio: 0,
            fee: '0x48ba158a44a00',
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
            transactionHash: '0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad',
            transactionIndex: 0,
            transferType: 'klay',
            typeInt: 48,
            value: '0x0'
        }
    ],
    cursor: 'qrX1b6xwlmk9PJea2XLzoN30gKQAYGxbvro0Qk97dx5WAvJBpaKw6lPR1VLbVEzQV2P6XtYuNjgzVXe1DL4MGEbmO823NqYZWlk4rqdpVwm51B86ZD7EOM2WeDNBPQKE'
}

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
}

typeInt 변수는 트랜잭션 종류를 구별하는 값입니다. 트랜잭션의 종류에 관한 자세한 내용은 다음을 확인하십시오.

이 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}

const result = await caver.kas.tokenHistory.getTransferHistoryByTxHash('0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad')

String txHash = "0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb";

Transfers transfers = caver.kas.tokenHistory.getTransferHistoryByTxHash(txHash);
System.out.println(transfers);

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
        }
    ]
}

Transfers {
    items: [
        TransferItem {
            feePayer: '',
            feeRatio: 0,
            fee: '0x48ba158a44a00',
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
            transactionHash: '0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad',
            transactionIndex: 0,
            transferType: 'klay',
            typeInt: 48,
            value: '0x0'
        }
    ]
}

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
        }]
    }
}

typeInt 변수는 트랜잭션 종류를 구별하는 값입니다. 트랜잭션의 종류에 관한 자세한 내용은 다음을 확인하십시오.

이 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}

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)

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 응답

요청이 성공할 경우 다음과 같은 응답을 받습니다.

{
    "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"
}

PageableTransfers {
    items: [
        TransferItem {
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0x88ab3cdbf31f856de69be569564b751a97ddf5d8',
            transferType: 'nft',
            contract: [FtContract],
            transaction: [Transaction],
            tokenId: '0x7b' 
        }
    ],
    cursor: 'bk8XJaEYv0P46ZA8kXLewmDBJVOKWzQ3dL3wPG8EYJDxqN5O9r2M4B0jLBubuAx1AZdbeJ6EbypQlaKVWZbd7vX1kAeozgm6r0G1qEalMN59pPY7bgxvo29BwxN1oArm'
}

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
}

typeInt 변수는 트랜잭션 종류를 구별하는 값입니다. 트랜잭션의 종류에 관한 자세한 내용은 다음을 확인하십시오.

이 API에 관한 자세한 내용은 다음을 확인하십시오. 이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.

Previous토큰 정보 조회 Next토큰 컨트랙트 조회

Last updated 2 years ago