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 (Mainnet) or 1001 (Kairos).
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	Kaia Mainnet or Kairos
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 Kaia account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KAIA, etc.) of or sending a transaction from a Kaia account. If you shared your API Auth Key with any unauthorized personnel, your Kaia account could be compromised and might cause unwanted transaction execution.

danger

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/Kaia 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 Kaia 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

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...)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.

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

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developers Forum.