NFT Ownership

This page introduces how to get the change of NFT ownership with Token History API.

Before Getting Started

• API introduced in here should only be used with HTTP Request.

• The x-chain-id value for calling the API is 8217 (Cypress) or 1001 (Baobab).

• Essential parameters for calling APIs are described in individual examples.

Values that a user needs to enter for calling APIs will be represented with one pair of braces ({}). A user must enter the following values.

Item	Description	Note
chain-id	8217 or 1001	Cypress(Klaytn mainnet) or Baobab(Klaytn testnet
access-key-id	Auth ID	accessKeyId obtained from KAS Console - Security - Credential
secret-access-key	Auth Password	secretAccessKey obtained from KAS Console - Security - Credential
krn	(optional) ID of Account Pool	Unnecessary when using Default Account Pool

A KAS API Authentication Key (API Auth Key) provides access to all KAS services and all the rights to a Klaytn account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KLAY, etc.) of or sending a transaction from a Klaytn account. If you shared your API Auth Key with any unauthorized personnel, your Klaytn account could be compromised and might cause unwanted transaction execution.

DO NOT share your API Auth Key (Secret AccessKey or Authorization) with any unauthorized personnel. DO PUT efforts necessary to keep your API Auth Key safe for the security of your KAS/Klaytn account.

Get Records of NFT Ownership Change

Search for the ownership change history of specific NFT.

NFT contract is a type of smart contract deployed to Klaytn that allows users to issue, delete, and send Non-fungible Token (Non-Fungible Token, NFT).

API Request

Search for the NFT ownership changes history as follows.

Query Parameter

You can receive API response values with Cursor-based Pagination.

Parameter	Description	Example	Required or Not
size	the number of items in the API response (min=1, max=1000, default=100)	size=100	False
cursor	the cursor required to get the next batch of response items	cursor=J9Ag...VM6z	False

curl

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}

javascript

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

java

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

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

• nft-address(0x251f622e8b5e713f357e...)is a required input value that stands for an address of the NFT contract to be searched.

• token-id(0x1) is a required input value and an identifier of the token to be searched.

API Response

The record stating that the NFT ownership was changed from “from” to “to” at the “timestamp” point will be displayed as follows if the request is successful.

curl

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

javascript

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

java

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

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.