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.

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/Klaytn account.

Get List of NFT Tokens

Search the NFT list that is issued by a specific labeled NFT contract.

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

Label is a marker put on a specific token contract by KAS for tracking its information. KAS only tracks labeled token contracts. This API requests for the list of labeled FT contracts. For details about labeling, please visit here.

API Request

Search the NFT list as follows.

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/0x90d535c434e967ec6e9accb0de5dcb34010865e0/token?size=100&cursor=J9Ag...VM6z" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}
Copy
Copied
const query = { size: 1 };
const result = await caver.kas.tokenHistory.getNFTList(
  "0xbbe63781168c9e67e7a8b112425aa84c479f39aa",
  query
);
Copy
Copied
String contractAddress = "0xbbe63781168c9e67e7a8b112425aa84c479f39aa";
TokenHistoryQueryOptions options = new TokenHistoryQueryOptions();
options.setSize((long)1);

PageableNfts nfts = caver.kas.tokenHistory.getNFTList(contractAddress, options);
System.out.println(nfts);
  • nft-address (0x90d535c434e967ec...) is a required input value that stands for an address of the NFT contract to be searched.

API Response

The NFT list will be received as a response as follows if the request is successful.

cURLJavaScriptJava
Copy
Copied
{
    "items": [
        {
            "tokenId": "0xa",
            "owner": "0x5160e376db4c5a445438d3a1998d2cf6a982adf2",
            "previousOwner": "0x0000000000000000000000000000000000000000",
            "tokenUri": "",
            "transactionHash": "0x671cd9b3f7f990830fa4f39b8c3b7f926b92b2fd8a1b8e512f5bdc29ccd40831",
            "createdAt": 1597748688,
            "updatedAt": 1597748688
        },
        {
            "tokenId": "0x9",
            "owner": "0x5160e376db4c5a445438d3a1998d2cf6a982adf2",
            "previousOwner": "0x0000000000000000000000000000000000000000",
            "tokenUri": "",
            "transactionHash": "0xe0c0132274d90d5d81bcbd125943d1c82d5ea03c344888bc1384e48b75501663",
            "createdAt": 1597748685,
            "updatedAt": 1597748685
        },
        ...,
        {
            "tokenId": "0x1",
            "owner": "0x6058233f589dbe86f38bc64e1a77cf16cf3c6c7e",
            "previousOwner": "0x0000000000000000000000000000000000000000",
            "tokenUri": "",
            "transactionHash": "0x435385996ad7508d57fd495cd2a1aeeb314372ddb35b559c759021c8c6ac9a61",
            "createdAt": 1597743760,
            "updatedAt": 1597743760
        }
    ],
    "cursor": ""
}
Copy
Copied
PageableNfts {
    items: [
        Nft {
            owner: '0x88ab3cdbf31f856de69be569564b751a97ddf5d8',
            previousOwner: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            tokenId: '0x7b',
            tokenUri: 'https://game.example/item-id-8u5h2m.json',
            transactionHash: '0x5f38d4bbb9a54550a9d070901ebdc714acdec67db34c658e5eb1ad6647b0f4d2',
            createdAt: 1599110774,
            updatedAt: 1599110780
        }
    ],
    cursor: 'PdOALgqNme5a9vJ6KDBAZ4gzwx6alLo1Q5mX7q2Oz2d7e8PrK1Jpwbm9LZ6D0lRxNnvx4BMAVXNE5Qao3kqgWGYOp9rW8Y3GEDM0deNPbKvkJVEz4oXVrY0Wxk1lbp7B'
}
Copy
Copied
class PageableNfts {
    items: [class Nft {
        owner: 0x88ab3cdbf31f856de69be569564b751a97ddf5d8
        previousOwner: 0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1
        tokenId: 0x7b
        tokenUri: https://game.example/item-id-8u5h2m.json
        transactionHash: 0x5f38d4bbb9a54550a9d070901ebdc714acdec67db34c658e5eb1ad6647b0f4d2
        createdAt: 1599110774
        updatedAt: 1599110780
    }]
    cursor: PdOALgqNme5a9vJ6KDBAZ4gzwx6alLo1Q5mX7q2Oz2d7e8PrK1Jpwbm9LZ6D0lRxNnvx4BMAVXNE5Qao3kqgWGYOp9rW8Y3GEDM0deNPbKvkJVEz4oXVrY0Wxk1lbp7B
}

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

Get List of NFT Tokens by EOA

Search for the NFT list owned by a specific EOA. A labeled token contract must have issued this token.

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

Label is a marker put on a specific token contract by KAS for tracking its information. KAS only tracks labeled token contracts. This API requests for the list of labeled FT contracts. For details about labeling, please visit here.

API Request

Load the list of all tokens of a specific EOA as follows.

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/owner/0xe5389503156ee02775ee18552f0c9d9846b66a91size=100&cursor=J9Ag...VM6z" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}
Copy
Copied
const contractAddress = "0xbbe63781168c9e67e7a8b112425aa84c479f39aa";
const ownerAddress = "0xa1c56175bbafaeaac2da534bed2c50079c63344a";
const query = {
  size: 1,
  cursor:
    "PdOALgqNme5a9vJ6KDBAZ4gzwx6alLo1Q5mX7q2Oz2d7e8PrK1Jpwbm9LZ6D0lRxNnvx4BMAVXNE5Qao3kqgWGYOp9rW8Y3GEDM0deNPbKvkJVEz4oXVrY0Wxk1lbp7B",
};
const result = await caver.kas.tokenHistory.getNFTListByOwner(
  contractAddress,
  ownerAddress,
  query
);
Copy
Copied
String contractAddress = "0xbbe63781168c9e67e7a8b112425aa84c479f39aa";
String owner = "0x88ab3cdbf31f856de69be569564b751a97ddf5d8";

PageableNfts nfts = caver.kas.tokenHistory.getNFTListByOwner(contractAddress, owner);
System.out.println(nfts);
  • nft-address is a required input value that stands for an address of the NFT contract to be searched.
  • owner-address is a required input value that stands for the EOA to be searched.

API Response

If the API request was successful, you would get the list of tokens as follows.

cURLJavaScriptJava
Copy
Copied
{
    "items": [
        {
            "tokenId": "0x7",
            "owner": "0xe5389503156ee02775ee18552f0c9d9846b66a91",
            "previousOwner": "0x0000000000000000000000000000000000000000",
            "tokenUri": "http://example.mynft.com/meta/item7",
            "transactionHash": "0x9b9d553d8b3141eabdc6ececd44958475366b1bc289088248b2b3dadcecf8ab4",
            "createdAt": 1597308968,
            "updatedAt": 1597308968
        },
        {
            "tokenId": "0x6",
            "owner": "0xe5389503156ee02775ee18552f0c9d9846b66a91",
            "previousOwner": "0x0000000000000000000000000000000000000000",
            "tokenUri": "http://example.mynft.com/meta/item6",
            "transactionHash": "0x441c617bfc1e0baee363bc495617579a4e3eb2a6ddd6249ad3ece5363e3faee2",
            "createdAt": 1597308146,
            "updatedAt": 1597308146
        },
        ...,
        {
            "tokenId": "0x2",
            "owner": "0xe5389503156ee02775ee18552f0c9d9846b66a91",
            "previousOwner": "0x0000000000000000000000000000000000000000",
            "tokenUri": "http://example.mynft.com/meta/item2",
            "transactionHash": "0xc7d07066e4e42a7d896c34420ed43568ba44ae15a8ef771b13ba1f6f2d2820c4",
            "createdAt": 1597304701,
            "updatedAt": 1597304701
        }
    ],
    "cursor": ""
}
Copy
Copied
PageableNfts {
    items: [
        Nft {
            owner: '0xa1c56175bbafaeaac2da534bed2c50079c63344a',
            previousOwner: '0x0000000000000000000000000000000000000000',
            tokenId: '0x3a',
            tokenUri: '',
            transactionHash: '0xb819548c03454a897b092282b1be877c6ebe90ce9006f09cb153e47fdeffdeac',
            createdAt: 1599102035,
            updatedAt: 1599102035
        }
    ],
    cursor: 'eNoAzq5E6Lwa7WYZMpbpELGg8dMPaWo0KNV2kqY74A0QVJXNodeqKp3BYG92aDy23RWP7bExZ8v1O5zl6MrmwLgkwQmOJex3rlZzB9A4DX16v5PlK10D29kVJX3bgmQ4'
}
Copy
Copied
class PageableNfts {
    items: [class Nft {
        owner: 0x88ab3cdbf31f856de69be569564b751a97ddf5d8
        previousOwner: 0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1
        tokenId: 0x7b
        tokenUri: https://game.example/item-id-8u5h2m.json
        transactionHash: 0x5f38d4bbb9a54550a9d070901ebdc714acdec67db34c658e5eb1ad6647b0f4d2
        createdAt: 1599110774
        updatedAt: 1599110780
    }]
    cursor:
}

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

Get NFT Token Information

Search for specific NFT information.

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 specific NFT information.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET "https://th-api.klaytnapi.com/v2/contract/nft/0x251f622e8b5e713f357e9c4d990e91da2f448134/token/0x2" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}
Copy
Copied
const contractAddress = "0xbbe63781168c9e67e7a8b112425aa84c479f39aa";
const tokenId = "0x7b";
const result = await caver.kas.tokenHistory.getNFT(contractAddress, tokenId);
Copy
Copied
String contractAddress = "0xbbe63781168c9e67e7a8b112425aa84c479f39aa";
String tokenId = "0x7b";

Nft nft = caver.kas.tokenHistory.getNFT(contractAddress, tokenId);
System.out.println(nft);
  • nft-address is a required input value that stands for an address of the NFT contract to be searched.
  • token-id is a required input value and an identifier of the token to be searched.

API Response

The NFT information will be received as a response as follows if the request is successful.

cURLJavaScriptJava
Copy
Copied
{
  "tokenId": "0x2",
  "owner": "0xe5389503156ee02775ee18552f0c9d9846b66a91",
  "previousOwner": "0x0000000000000000000000000000000000000000",
  "tokenUri": "http://example.mynft.com/meta/item2",
  "transactionHash": "0xc7d07066e4e42a7d896c34420ed43568ba44ae15a8ef771b13ba1f6f2d2820c4",
  "createdAt": 1597304701,
  "updatedAt": 1597304701
}
Copy
Copied
Nft {
    owner: '0x88ab3cdbf31f856de69be569564b751a97ddf5d8',
    previousOwner: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
    tokenId: '0x7b',
    tokenUri: 'https://game.example/item-id-8u5h2m.json',
    transactionHash: '0x5f38d4bbb9a54550a9d070901ebdc714acdec67db34c658e5eb1ad6647b0f4d2',
    createdAt: 1599110774,
    updatedAt: 1599110780
}
Copy
Copied
class Nft {
    owner: 0x88ab3cdbf31f856de69be569564b751a97ddf5d8
    previousOwner: 0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1
    tokenId: 0x7b
    tokenUri: https://game.example/item-id-8u5h2m.json
    transactionHash: 0x5f38d4bbb9a54550a9d070901ebdc714acdec67db34c658e5eb1ad6647b0f4d2
    createdAt: 1599110774
    updatedAt: 1599110780
}

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