토큰 송수신 기록 조회

이 페이지는 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 컨트랙트란 Klaytn에 배포되는 스마트 컨트랙트의 일종입니다. 이 컨트랙트는 대체 가능 토큰(Fungible Token, FT)을 발행, 삭제, 전송하는 기능을 제공합니다. NFT 컨트랙트란 Klaytn에 배포되는 스마트 컨트랙트의 일종입니다. 이 컨트랙트는 대체 불가 토큰(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(Klaytn 계정 주소)가 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

Was this helpful?