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 목록을 조회합니다.

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

라벨(Label)이란 KAS가 어떤 토큰 컨트랙트 정보를 추적하기 위해 토큰 컨트랙트에 붙인 표식입니다. KAS는 라벨링된 토큰 컨트랙트만을 계속 추적합니다. 이 API는 라벨링된 FT 컨트랙트 목록을 불러옵니다. 라벨링에 관한 자세한 내용은 다음을 확인하십시오.

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/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...)는 조회하려는 NFT 컨트랙트의 주소이며 필수 입력값입니다.

API 응답

요청이 성공할 경우 다음과 같이 NFT 목록을 응답으로 받게됩니다.

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
}

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

특정 EOA가 가진 모든 NFT 토큰 조회

특정 EOA가 가진 NFT 목록을 조회합니다. 이 토큰은 라벨링된 토큰 컨트랙트에서 발행한 것이어야 합니다.

API 호출

다음과 같이 특정 EOA가 가진 모든 토큰 목록을 불러옵니다.

쿼리 파라미터 여러분은 커서 방식 페이지네이션 을 사용해 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/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 는 조회하려는 NFT 컨트랙트의 주소이며 필수 입력값입니다.
owner-address 는 조회하려는 EOA이며 필수 입력값입니다.

API 응답

요청이 성공할 경우 다음과 같이 토큰 목록을 응답으로 받게됩니다.

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

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

특정 NFT 정보 조회

특정 NFT 정보를 조회합니다.

API 호출

다음과 같이 NFT 정보를 조회합니다.

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 는 조회하려는 NFT 컨트랙트의 주소이며 필수 입력값입니다.
token-id 는 조회하려는 토큰의 식별자이며 필수 입력값입니다.

API 응답

요청이 성공할 경우 다음과 같이 NFT 정보를 응답으로 받게됩니다.

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
}

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