Mint

Mint는 게임 아이템을 NFT로 발행하는 기능입니다. Hive 콘솔에서 블록체인 > XPLA > NFT 메뉴 유저발행 탭에 설정한 내용을 기반으로 NFT를 발행합니다.

Mint 기능 구현 흐름¶

아래는 Mint 기능 구현 과정입니다. Mint 기능을 구현하려면 아래 흐름도 이미지와 가이드 내용을 따라 따라 게임 클라이언트(Hive SDK, 게임 클라이언트)와 게임 서버 영역에서 코드를 구현하세요. 아래 그림에서 파란색 별표가 붙어있는 부분이 개발사에서 작업해야 할 부분입니다. 주요 작업에 관한 자세한 내용은 아래 가이드를 참고하세요.

Note

사전 준비를 마친 후 Mint 기능을 구현해야 합니다.

Note

Mint 기능을 구현하려면 Hive SDK를 사용해야 합니다.

Hive SDK에서 로그인 구현¶

Hive SDK 인증 기능을 사용해 사용자가 IdP 로그인을 할 수 있도록 게임 클라이언트에서 코드를 구현합니다. 로그인 수단으로 웹 로그인도 지원합니다.

NFT 발행 버튼 구현¶

게임 클라이언트에서 사용자가 NFT 발행 페이지를 열 수 있는 UI를 구현합니다. 예를 들어 사용자가 게임 접속 후 캐릭터 인벤토리에서 아이템을 선택했을 때, 아이템을 NFT로 변환 버튼 등이 나타나야 합니다. 이 버튼을 누르면 아래 내용을 따라 NFT 발행 페이지를 열도룩 구현해야 합니다.

아이템을 NFT로 변환 요청¶

게임 클라이언트에서 게임 서버로 사용자 게임 아이템을 NFT로 발행 요청하는 코드를 구현합니다. 사용자가 NFT 발행 버튼을 선택했을 때 동작을 구현하는 것입니다. 게임 서버는 게임 클라이언트 요청을 받으면 NFT로 발행할 게임 아이템을 확인한 후, 아이템을 NFT로 발행하기 위해 NFT 발행 페이지 링크 생성 API를 호출합니다.

NFT 발행 페이지 링크 생성 API 호출¶

NFT 발행 페이지는 사용자가 보유한 아이템을 NFT로 변환할 수 있는 웹페이지입니다. 이 웹페이지는 Hive 블록체인 서버가 제공합니다. 게임 서버는 링크 생성 API를 호출해 이 웹페이지 URL(webLinkUrl)을 받아옵니다. 사용자가 이 웹페이지에 접속하면 사용자는 인게임 아이템을 블록체인상에서 NFT로 발행(Mint)할 수 있습니다.

유의 사항¶

개발사가 API 호출 시 유의할 사항입니다.

gameServerUrl¶

gameServerUrl은 Hive 블록체인 서버가 게임 서버를 호출하는 API(아이템 검증 API와 결과 확인 API)의 Request URL로 사용됩니다.

gameServerUrl과 token¶

Hive 블록체인 서버가 아이템 검증 API 또는 결과 확인 API를 호출할 때, 게임 서버는 API 호출에 인증 토큰(Header Parameters)을 사용하도록 할 수 있으며 이는 개발사 선택 사항입니다. API 호출에 인증 토큰을 사용하도록 할 경우, 게임 서버는 NFT 발행 페이지 링크 생성 API 호출 시 이 인증 토큰을 token(Query Paramter)으로 gameServerUrl에 붙여서 Hive 블록체인 서버에 미리 전달해놔야 합니다. 예시는 아래와 같습니다.

"gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."

attributes¶

attributes는 Hive 블록체인 서버가 게임 서버로 아이템 검증 API와 결과 확인 API를 호출할 때 Request Body로 사용합니다.

attributes에 아이템 고유코드를 담아 API를 호출하면, 고유코드는 결과 확인 API Request Body attributes에도 포함할 수 있습니다. 이 경우, 해당 고유코드로 아이템 상태를 업데이트할 수 있습니다.

NFT 발행 페이지 링크 유효 시간¶

한번 생성한 페이지 링크는 최초 접근한 세션 기준으로 10분 동안만 유효합니다.

Request URL¶

항목	값
Live URL	https://bc-platform-api.withhive.com/web3/v1/web-link
Sandbox URL	https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link
HTTP Method	POST
Content-Type	application/json

Header Parameters¶

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y

Request Body¶

필드명	설명	타입	필수 여부
type	`MINT`	string	Y
playerId	플레이어 ID	number	Y
characterId	캐릭터 ID	string	Y
gameServerUrl	아이템 검증 및 기능 수행 후 성공/실패 결과를 전달 받을 주소. `token` Query Parameter로 인증 토큰 전송 시 아이템 검증/결과 확인 API 헤더로 인증 토큰 전송	string	Y
data	type에 따른 요청 파라미터 정보	json	N

data 객체¶

필드명	설명	타입	필수 여부
itemId	유저 NFT 템플릿 식별값 (콘솔등록)	string	Y
attributes	토큰 별 추가로 적용할 메타데이터 속성값(예를 들어 아이템 고유코드, 힘, 민첩성 등 NFT에 포함될 속성값)	json array	N
attributes.traitType	attributes를 구성하는 항목명	string	N
attributes.value	trait 값	string	N

Request Sample¶

curl -X 'POST' \
  'https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "MINT",
  "playerId": 1276814678,
  "characterId": "zeratu",
  "gameServerUrl": "https://api.com2us.com/hive" //인증 토큰 전송 시: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
  "data": {
    "itemId": "HIVE",
    "attributes": [
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  },
}'

Responses¶

필드명	설명	타입
code	API 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.webLinkId	웹 링크 아이디(UUID)	string
data.webLinkUrl	생성된 일회성 웹 링크(URL)	string
data.expiration	웹 링크 만료 일시(ISO 8601)	string

Response Sample¶

{
  "code": 0,
  "message": "success",
  "data": {
    "webLinkid": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "webLinkUrl": "https://sandbox-xpla-platform.withhive.com/api/v1/web-link/redirect?token=b256c85c-aee8-4837-b54d-9a03fe8a7435.f94140b71c9ebf058956547753131adde9968a0266f208d7e3059bbb6dd0c7bc",
    "expiration": "2024-08-05T08:33:15.448Z"
  }
}

Hive SDK로 NFT 발행 페이지 열기 구현¶

NFT 발행 페이지 링크 생성 API 응답값으로 전달받은 웹페이지 URL을 Hive SDK를 사용해 외부 브라우저로 노출합니다.

아래는 NFT 발행 페이지 예시입니다.

NFT로 발행할 아이템 정보

NFT 발행 페이지를 열면 X-PLANET 지갑 또는 XLPA Vault에 로그인하는 창이 나타납니다. 사용자는 X-PLANET 지갑 또는 XLPA Vault에서 로그인 후, Mint 또는 Burn을 수행할 특정 지갑 주소를 반드시 선택해야 합니다.

Note

XPLA Vault는 2025년 6월 지원 예정입니다.

X-PLANET	XPLA Vault

NFT 발행(Mint 실행)¶

NFT 발행 페이지에서 사용자는 아이템을 선택 후 Mint를 실행합니다.

수수료 확인 후 NFT 발행

아이템 검증 API 호출 (Hive 블록체인 서버 → 게임 서버)¶

Note

이 API는 게임 서버가 Hive 블록체인 서버를 호출하는 API가 아니라, Hive 블록체인 서버가 게임 서버를 호출하는 API입니다. 따라서 게임 서버는 Hive 블록체인 서버가 원하는 형태로 API 엔드포인트를 구성해 제공해야 합니다.

게임 아이템을 NFT로 변환하기 전에 Hive 블록체인 서버가 게임 서버로 아이템 검증을 요청합니다. Hive 블록체인 서버는 게임 서버가 전달한 응답값에서 아이템 정보를 확인 후, 블록체인상에서 NFT를 발행합니다. 만약 아이템 검증에 실패하면 Hive 블록체인 서버는 NFT를 발행하지 않습니다.

Note

게임 서버에서는 결과 확인 API로 NFT 발행 결과를 전달받기 전까지는, 게임 내에서 검증 완료한 아이템을 사용할 수 없게 제한해야 합니다.

유의 사항¶

개발사가 API 엔드포인트 구성 시 유의할 사항입니다.

gameServerUrl¶

이 API는 NFT 발행 페이지 링크 생성 API에서 요청한 gameServerUrl을 사용해 게임 서버에 검증을 요청합니다.

Authorization Header¶

NFT 발행 페이지 링크 생성 API에서 요청한 gameServerUrl에 token Query Parameter가 존재한다면, 이 token 값을 Bearer 형태로 사용합니다.

attributes¶

NFT 발행 페이지 링크 생성 API Request Body에 있는 attributes를 요청에 포함합니다.

Request URL¶

다음은 게임 서버에서 준비해야 하는 API 엔드포인트 정보입니다.

항목	값
URL	{gameServerUrl}/items/validate
HTTP Method	POST
Content-Type	application/json

Header Parameters¶

필드명	설명	타입	필수 여부
Authorization	NFT 발행 페이지 링크 생성 API의 `gameServerUrl`에 `token` Query Parameter로 전송한 인증 토큰입니다. Bearer ${token} 형태로 호출합니다.	Bearer	N
User-Agent	HiveBlockchain/1.0	string	Y

Request Body¶

필드명	설명	타입	필수 여부
type	`MINT`	string	Y
itemId	NFT 이이템 식별 코드	string	Y
playerId	플레이어 ID	number	Y
characterId	캐릭터 ID	string	N
webLinkId	웹 링크 아이디(UUID)	string	Y
tokenId	NFT 아이디	string	N
attributes	토큰 별 추가로 적용할 메타데이터 속성값(예를 들어 아이템 고유코드, 힘, 민첩성 등 NFT에 포함될 속성값)	json array	N
attributes.traitType	attributes를 구성하는 항목명	string	N
attributes.value	trait 값	string	N

Request Sample¶

curl -X 'POST' \
  'https://api.com2us.com/hive/items/validate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // 인증 토크 사용 시
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "MINT",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "attributes": [ // NFT 발행 페이지 링크 생성 시 attributes
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

Responses¶

HTTP 상태 코드는 아래와 같습니다.

성공
- 200
실패
- 4xx: 잘못된 요청에 대한 에러 상태 코드
- 5xx: 서버 오류에 대한 에러 상태 코드

결과 확인 API 호출 (Hive 블록체인 → 게임 서버)¶

Note

이 API는 게임 서버가 Hive 블록체인 서버를 호출하는 API가 아니라, Hive 블록체인 서버가 게임 서버를 호출하는 API입니다. 따라서 게임 서버는 Hive 블록체인 서버가 원하는 형태로 API 엔드포인트를 구성해 제공해야 합니다.

Hive 블록체인 서버가 NFT 발행 결과를 Request Body로 게임 서버에 전달하면, 게임 서버는 게임내에서 아이템을 사용할 수 없도록 처리한 후 그 결과를 Hive 블록체인 서버로 전달하는 API입니다.

발행 결과에 따라 게임 서버가 수행할 작업은 아래와 같습니다.

NFT 발행 성공
- 게임에서 아이템을 사용할 수 없도록 처리(예: 게임 사용자 인벤토리 내에서 아이템을 삭제)
NFT 발행 실패
- 게임에서 아이템을 사용할 수 있도록 처리(예: 게임 사용자 인벤토리 내에서 아이템을 다시 사용할 수 있도록 사용 제한 해제 처리)
- 사용자가 NFT 발행을 취소하거나 일정 시간을 초과한 경우에도 NFT 발행 실패 결과를 보냄

Warning

NFT 발행 결과를 받기 전까지는 게임 서버에서 게임 내 해당 아이템 사용을 반드시 제한해야 합니다.

아래는 게임 서버가 NFT 발행 성공을 응답했을 때, NFT 발행 페이지 화면 예시입니다.

유의 사항¶

개발사가 API 엔드포인트 구성 시 유의할 사항입니다.

attributes¶

attributes에 아이템 고유코드를 담아 NFT 발행 페이지 링크 생성 API를 호출하면, 고유코드를 Request Body attributes에도 포함할 수 있습니다. 이 경우, 해당 고유코드로 아이템 상태를 업데이트할 수 있습니다.

Authorization Header¶

NFT 발행 페이지 링크 생성 API에서 요청한 gameServerUrl에 token Query Parameter가 존재한다면, 이 token 값을 Bearer 형태로 사용합니다.

Request URL¶

항목	값
URL	{gameServerUrl}/items/callback
HTTP Method	POST
Content-Type	application/json

Header Parameters¶

필드명	설명	타입	필수 여부
Authorization	NFT 발행 페이지 링크 생성 API의 `gameServerUrl`에 `token` Query Parameter로 전송된 인증 토큰입니다. Bearer ${token} 형태로 호출합니다.	Bearer	N
User-Agent	HiveBlockchain/1.0	string	Y

Request Body¶

필드명	설명	타입	필수 여부
type	`MINT`	string	Y
itemId	NFT 이이템 식별 코드	string	Y
playerId	플레이어 ID	number	Y
characterId	캐릭터 ID	string	N
webLinkId	웹 링크 아이디(UUID)	string	Y
tokenId	NFT 아이디 (성공일 경우 포함)	string	N
status	트랜잭션 결과 (success, failure)	string	Y
attributes	토큰 별 추가로 적용할 메타데이터 속성값(예를 들어 아이템 고유코드, 힘, 민첩성 등 NFT에 포함될 속성값)	json array	N
attributes.traitType	attributes를 구성하는 항목명	string	N
attributes.value	trait 값	string	N

Request Sample¶

curl -X 'POST' \
  'https://api.com2us.com/hive/items/callback' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \  // 인증 토크 사용 시
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "MINT",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "tokenId": "HIVE#348",
    "status": "success",
    "attributes": [ // NFT 발행 페이지 링크 생성 시 attributes
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

Responses¶

HTTP 상태 코드는 아래와 같습니다.

성공
- 200
실패
- 4xx: 잘못된 요청에 대한 에러 상태 코드
- 5xx: 서버 오류에 대한 에러 상태 코드