NFT 소유권 변동 조회

Token History API를 사용하여 NFT 토큰의 소유권이 변경된 기록을 조회하는 방법을 안내합니다.

튜토리얼에 앞서

여기에서 소개하는 API는 HTTP 방식만을 사용하십시오.
API 호출에 사용되는 x-chain-id 값은 8217 (Mainnet) 또는 1001 (Kairos)입니다.
API 호출에 필요한 필수 파라미터는 각 예시에 설명됩니다.

API 호출 시 사용자가 입력해야 하는 값은 중괄호 1개({})로 표시합니다. 사용자가 입력해야 하는 값은 아래 테이블과 같습니다.

항목	값	비고
chain-id	8217 또는 1001	Kaia 메인넷 또는 Kairos
access-key-id	인증 아이디	KAS Console > [Security] > [Credential]에서 발급받은 `accessKeyId`
secret-access-key	인증 비밀번호	KAS Console > [Security] > [Credential]에서 발급받은 `secretAccessKey`
krn	(optional) 계정 저장소의 ID	기본 계정 저장소 사용 시 불필요

API 인증 키가 있으면 모든 KAS 서비스를 사용할 수 있으며 Wallet API를 호출해 만든 Kaia 계정에 대한 모든 권한을 소유합니다. 모든 권한에는 Kaia 계정의 자산(KAIA 등) 이동이나 트랜잭션 전송 및 실행 권한이 포함됩니다. 만약 API 인증 키에 타인이 접근한다면 Kaia 계정 권한을 탈취당해 원치 않는 트랜잭션이 발생할 수 있습니다.

danger

KAS/Kaia 계정 보안을 위해 KAS API 인증 키(Secret Access Key)를 타인과 함부로 공유하지 말고 주의해 관리하십시오.

특정 NFT 소유권 변경 기록 조회

특정 NFT의 소유권 변경 기록을 조회합니다.

NFT 컨트랙트란 Kaia에 배포되는 스마트 컨트랙트의 일종입니다. 이 컨트랙트는 대체 불가 토큰(Non-Fungible Token, NFT)을 발행, 삭제, 전송하는 기능을 제공합니다.

API 호출

다음과 같이 NFT 소유권 변경 기록을 조회합니다.

쿼리 파라미터

여러분은 커서 방식 페이지네이션을 사용해 API 응답값을 받아올 수 있습니다.

파라미터 이름	설명	예시	필수
size	응답 아이템 개수 (min=1, max=1000, default=100)	`size=100`	False
cursor	페이지네이션으로 다음 요청을 보낼 때 필요한 커서	`cursor=J9Ag...VM6z`	False

cURLJavaScriptJava

Copy

Copied

curl --location --request GET "https://th-api.klaytnapi.com/v2/contract/nft/0x251f622e8b5e713f357e9c4d990e91da2f448134/token/0x1/history?size=100&cursor=J9Ag...VM6z" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}

Copy

Copied

const result = await caver.kas.tokenHistory.getNFTOwnershipHistory(
  "0xbbe63781168c9e67e7a8b112425aa84c479f39aa",
  "0x7b"
);

Copy

Copied

String contractAddress = "0xbbe63781168c9e67e7a8b112425aa84c479f39aa";
String tokenId = "0x7b";

PageableNftOwnershipChanges ownershipChanges = caver.kas.tokenHistory.getNFTOwnershipHistory(contractAddress, tokenId);
System.out.println(ownershipChanges);

nft-address (0x251f622e8b5e713f357e...)는 조회하려는 NFT 컨트랙트의 주소이며 필수 입력값입니다.
token-id (0x1)는 조회하려는 토큰의 식별자이며 필수 입력값입니다.

API 응답

요청이 성공할 경우 다음과 같이 NFT 소유권이 from에서 to로 timestamp시점에 변동되었다는 기록을 응답으로 받습니다.

cURLJavaScriptJava

Copy

Copied

{
  "items": [
    {
      "from": "0x0000000000000000000000000000000000000000",
      "to": "0x36884a060be5438226c4deaf799b0f7de5abd5df",
      "timestamp": 1597226350
    }
  ],
  "cursor": ""
}

Copy

Copied

PageableNftOwnershipChanges {
    items: [
        NftOwnershipChange {
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0x88ab3cdbf31f856de69be569564b751a97ddf5d8',
            timestamp: 1599110780
        },
        NftOwnershipChange {
            from: '0x0000000000000000000000000000000000000000',
            to: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            timestamp: 1599110774
        }
    ],
    cursor: ''
}

Copy

Copied

class PageableNftOwnershipChanges {
    items: [class NftOwnershipChange {
        from: 0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1
        to: 0x88ab3cdbf31f856de69be569564b751a97ddf5d8
        timestamp: 1599110780
    }, class NftOwnershipChange {
        from: 0x0000000000000000000000000000000000000000
        to: 0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1
        timestamp: 1599110774
    }]
    cursor:
}

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