NFT API

NFT (Non-Fungible Token) API에 대한 소개 페이지입니다.

NFT API 소개

ChainZ API Service의 NFT API는 ERC721 토큰 기반의 Collection 및 NFT 를 발행하고 관리 할 수 있게 해줍니다.

Collection 의 생성, 조회, NFT 에 올릴 Contents 의 업로드 및 NFT 발행 기능을 제공 합니다.

NFT API 사용

NFT API 가 제공하는 "사용자 계정 신규 생성 API" 를 이용하여, 사용자의 Address 를 생성하고, 이 Address 에 NFT 를 발행 합니다. 각 NFT 는 Collection 별로 구분 될 수 있으며, 만약, Collection이 없다면, 먼저 Collection 을 생성해야합니다.

공통 설정

ChainZ Account API URL: https://nft-api.chainz.biz

공통 HTTP Request

API 를 접근하기 위한, 엑세스 토큰과 API 키를 항상 HTTP Header 에 넣어 주어야 합니다.

curl -X POST \
  "https://{NFT API Url}" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer {엑세스   토큰}" \
  -H  "x-api-key: {API 키}" \
  -H 'Content-Type: application/json' \
  -d '{Json Body}'

1. Collection 생성

여러 Collection 을 생성할 수 있으며, 적어도 하나의 Collection 은 만들어야 합니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/collections

• Request

{
    "chainId": <테스트넷 chain id:2021>,
    "name": <Collection 이름>,
    "symbol": <Collection 심볼>,
    "defaultMinteeAddr": <NFT 발행시 최초 소유 계정주소>    
    "description": <콜렉션 설명>,
    "callbackUrl": <Callback 받을 주소>
}

• Response

{
    "taskId": <Callback 으로 전달하는 결과와 함께 전달되는 ID>
}

• Callback

{
  "result" : {
    "state" : "SUCCESS" // 결과
  },
  "taskId" : <TASK ID>,
  "collectionId" : <생성된 Collection ID>,
  "contractAddr" : <생성된 Collection 의 SmartContract 주소>,
  "adminAddr" : <Collection을 생성한 Admin Address>
}

2. 사용자 등록

사용자에게 NFT 를 발행하기 위해, 사용자를 등록합니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/accounts

• Request

{
    "extUserId": <사용자를 구분할 수 있는 ID>,
    "chainId": <테스트넷 chain id:2021>
}

• Response

{
    "extUserId": <사용자를 구분할 수 있는 ID>,
    "chainId": <테스트넷 chain id:2021>,
    "address": <생성된 Address>
}

3. Digital Contents 업로드

NFT에 담고자 하는 Digital Contents 를 먼저 업로드 합니다. 해당 자료가 NFT화 되거나, 생성한지 오래 되면, 자동으로 삭제 됩니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/content

• Content-Type : multipart/form-data;

• Request Parameter

  • file : Digital Contents 파일

• Response

{
    "id": <Contents ID>,
    "fileName": <File 이름>,
    "contentType": <File 의 Type>,
    "url": <임시 URL, NFT 화 되거나, 생성하고 일정 시간이 지나면, 삭제됨>,
    "storageType": "S3"
}

4. NFT 생성

등록한 사용자에게, NFT 를 발행합니다. 앞 단계에서 생성한 Contents ID 를 사용합니다.

NFT 는 NFT API 내부에서 Asset 으로 명명하고 있습니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/collections/{collection ID}/assets

• Request

{
    "title": <NFT 이름>,
    "author": <생성자 이름>,
    "contentId": <앞단계에서 생성한 Contents ID>,
    "descr": <NFT 설명>,
    "minteeAddr": <발행하고자 하는 Address>,
    "callbackUrl": <Callback 받을 주소>
}

• Response

{
    "taskId": <Callback 으로 전달하는 결과와 함께 전달되는 ID>
}

• Callback

{
  "result" : {
    "state" : "SUCCESS" // 결과
  },
  "taskId" : <TASK ID>,
  "collectionId" : <Collection ID>,
  "assetId" : <Asset ID, 내부 ID>,
  "tokenId" : <NFT Token ID>,
  "contentUrl" : <Contents File Download Link>,
  "tokenUrl" : <Token의 Meta 정보가 있는 Link>
}

5. NFT 소유권 이전

등록한 사용자에게, NFT 소유권을 이전 할 수 있습니다. Collection ID, Asset ID 를 기준으로 NFT 를 지정하며, 기존 소유자의 Address, 이전받을 사용자의 Address 가 필요합니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/collections/{collection Id}/assets/{asset Id}/transfers

• Request

{
    "senderAddr": <기존 소유자의 Address>,
    "recipientAddr": <받을 사용자의 Address>,
    "callbackUrl": <Callback 받을 주소>
}

• Response

{
    "taskId": <Callback 으로 전달하는 결과와 함께 전달되는 ID>
}

• Callback

{
  "result" : {
    "state" : "SUCCESS" // 결과
  },
  "taskId" : <TASK ID>,
  "assetId" : <Assect ID, 내부 ID>
}

6. Mirror Collection 등록

ChainZ 네트워크에 생성한 NFT를 이더리움 네트워크로 반출할 수 있습니다. 이를 위하여 먼저 이더리움 네트워크에 Collection을 등록해야 합니다. 기존에 ChainZ 네트워크에 생성한 Collection의 ID를 지정하면 해당 Collection이 이더리움 네트워크에도 생성됩니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/collections/{collectionId}/mirrors

• Request

{
    "callbackUrl": <Callback 받을 주소>
}

• Response

{
    "taskId": <Callback 으로 전달하는 결과와 함께 전달되는 ID>
}

• Callback

{
  "result" : {
    "state" : "SUCCESS" // 결과
  },
  "taskId" : <TASK ID>,
  "originCollectionChainId" : <Collection이 등록되어 있는 ChainZ 네트워크의 Chain ID>,
  "originCollectionId" : <Collection ID, 내부 ChainZ ID>,
  "mirrorCollectionChainId" : <Mirror Collection이 등록되어 있는 이더리움 네트워크의 Chain ID>,
  "mirrorContractAddr" : <이더리움 네트워크에 배포되어 있는 Contract 주소>,
  "mirrorContractAdminAddrs" : [ <이더리움 네트워크에 배포되어 있는 Contract의 관리자 주소 리스트> ]
}

7. NFT 반출

ChainZ 네트워크에 생성한 NFT를 이더리움 네트워크로 반출합니다. 반출 대상 네트워크의 Chain ID와 반출 시 NFT를 소유할 사용자의 Address가 필요합니다. 반출하려는 NFT의 Collection은 사전에 반출 대상 네트워크의 Chain ID에 Mirror Collection으로 등록되어 있어야 합니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/collections/{collection Id}/assets/{asset Id}/export

• Request

{
    "toChainId" : <반출 대상 네트워크 Chain ID>,
    "toMinteeAddr" : <NFT 반출 시 소유 계정주소>,
    "callbackUrl" : <Callback 받을 주소>
}

• Response

{
    "taskId": <Callback 으로 전달하는 결과와 함께 전달되는 ID>
}

• Callback

{
  "result" : {
    "state" : "SUCCESS" // 결과
  },
  "taskId" : <TASK ID>,
  "originCollectionId" : <Collection ID, 내부 ChainZ ID>,
  "originAssetId" : <Assect ID, 내부 ChainZ ID>,
  "originTokenId" : <Token ID, 내부 ChainZ ID>,
  "mirrorContractAddr" : <이더리움 네트워크에 배포되어 있는 Contract 주소>,
  "newTokenId" : <Token ID, 외부 이더리움 네트워크 ID>
}

8. Task 상태 조회

API Response로 받은 Task ID를 지정하여 해당 Task의 현재 상태를 조회할 수 있습니다.

• HTTP Method : POST

• URL : https://nft-api.chainz.biz/api/v1/tasks/{taskId}

• Response

{
    "taskId": <TASK ID>,
    "type": <TASK 타입>,
    "statusType": <TASK 현재 상태>,
    "reason": [Optional] <TASK 상태가 FAIL인 경우, 실패 이유>
    "callbackData": [Optional] <TASK 상태가 SUCCESS, SUCCESS_BUT_NOT_DELIVERY인 경우, Callback 데이터>,
    "startedAt": <TASK 시작 일시>,
    "finishedAt": [Optional] <TASK 상태가 PREPARING이 아닌 경우, TASK 종료 일시>
}

NFT API 목록

space