Skip to content

Mint

Mint is a feature that issues game items as NFTs. It issues NFTs based on the configured content in the user issuance tab of the Blockchain > XPLA > NFT menu in the Hive console.

Implementation flow of mint function

Below is the implementation process for the Mint feature. To implement the Mint feature, please follow the flowchart image and guide content below to implement the code in the game client (Hive SDK, game client) and game server area. The parts marked with blue asterisks in the image below are the areas that the developers need to work on. For more details on the main tasks, please refer to the guide below.

Note

After completing the preparation, you need to implement the Mint feature.

Note

To implement the Mint feature, you must use the Hive SDK.

Implementing login in hive SDK

Implement code in the game client to allow users to log in using IdP login with the Hive SDK authentication feature. Web login is also supported as a login method.

NFT minting button implementation

Implement a UI in the game client that allows users to open the NFT issuance page. For example, when a user selects an item from the character inventory after accessing the game, a Convert Item to NFT button should appear. When this button is pressed, the NFT issuance page should be opened according to the content below.

Request to convert item to NFT

Implement the code that requests the issuance of user game items as NFTs from the game client to the game server. This is to implement the action when the user selects the NFT issuance button. When the game server receives the request from the game client, it checks the game items to be issued as NFTs and then calls the NFT issuance page link creation API to issue the items as NFTs.

The NFT issuance page is a webpage that allows users to convert their owned items into NFTs. This webpage is provided by the Hive blockchain server. The game server calls the link generation API to retrieve this webpage URL (webLinkUrl). When users access this webpage, they can mint in-game items as NFTs on the blockchain.

Notes

These are the precautions that developers should take when making API calls.

Gameserverurl

gameServerUrl is used as the Request URL for the APIs that the Hive blockchain server calls to the game server (Item Validation API and Result Check API).

Gameserverurl and token

When the Hive blockchain server calls the Item Validation API or the Result Confirmation API, the game server can optionally use an authentication token (Header Parameters) for the API call, which is at the discretion of the developer. If the authentication token is to be used for the API call, the game server must pre-attach this authentication token as token (Query Parameter) to gameServerUrl when calling the NFT issuance page link generation API and send it to the Hive blockchain server. An example is shown below.

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

Attributes

attributes is used as the Request Body when the Hive blockchain server calls the item validation API and result confirmation API to the game server.

When you call the API with the item unique code in attributes, the unique code can also be included in the Request Body attributes of the Result Check API. In this case, you can update the item status with the corresponding unique code.

The link to the page created once is valid for 10 minutes only based on the first accessed session.

Request URL

Item Value
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

Field Name Description Type Required
Authorization Authentication token for API calls string Y

Request Body

Field Name Description Type Required
type MINT string Y
playerId Player ID number Y
characterId Character ID string Y
gameServerUrl The address to receive success/failure results after item verification and function execution. Send the authentication token via the token Query Parameter for item verification/result confirmation API header string Y
data Request parameter information according to type json N

Data object

Field Name Description Type Required
itemId User NFT template identifier (console registration) string Y
attributes Additional metadata attributes to be applied per token (for example, unique item code, strength, agility, etc. attributes to be included in the NFT) json array N
attributes.traitType Item name that makes up attributes string N
attributes.value Trait value 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" // When sending authentication token: "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

Field Name Description Type
code API call result code, 0: success number
message Result message string
data API response data json
data.webLinkId Web link ID (UUID) string
data.webLinkUrl Generated one-time web link (URL) string
data.expiration Web link expiration date (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"
  }
}

Implementing the NFT issuance page with hive SDK

The NFT issuance page link creation API exposes the webpage URL received as a response to be opened in the in-game browser using the Hive SDK.


Below is an example of the NFT issuance page.

Item information to be issued as NFT


When you open the NFT issuance page, a login window for X-PLANET wallet or XLPA Vault will appear. Users must select a specific wallet address to perform Mint or Burn after logging in to the X-PLANET wallet or XLPA Vault.

X-PLANET XPLA Vault XPLA Games

NFT minting (executing mint)

On the NFT issuance page, users select an item and then execute Mint.

Check fee before NFT issuance

Item validation API call (hive blockchain server → game server)

Note

This API is not an API that the game server calls the Hive blockchain server, but rather an API that the Hive blockchain server calls the game server. Therefore, the game server must configure and provide the API endpoint in the form that the Hive blockchain server requires.

Before converting game items to NFTs, the Hive blockchain server requests item verification from the game server. The Hive blockchain server issues the NFT on the blockchain after confirming the item information from the response provided by the game server. If the item verification fails, the Hive blockchain server will not issue the NFT.

Note

In the game server, until you receive the NFT issuance result through the result confirmation API, you must restrict the use of items that have been verified in the game.

Notes

Here are some considerations for developers when configuring API endpoints.

Gameserverurl

This API requests verification from the game server using the gameServerUrl requested from the NFT issuance page link creation API.

Authorization header

If the token Query Parameter exists in the gameServerUrl requested from the NFT issuance page link creation API, use this token value in Bearer form.

Attributes

Includes attributes in the API Request Body for generating the NFT issuance page link.

Request URL

Here is the API endpoint information that needs to be prepared on the game server.

Item Value
URL {gameServerUrl}/items/validate
HTTP Method POST
PORT 80, 443
Content-Type application/json

Header Parameters

Field Name Description Type Required
Authorization The authentication token sent as a token Query Parameter to the gameServerUrl of the NFT issuance page API. It is called in Bearer ${token} format. Bearer N
User-Agent HiveBlockchain/1.0 string Y

Request Body

Field Name Description Type Required
type MINT string Y
itemId NFT item identification code string Y
playerId Player ID number Y
characterId Character ID string N
webLinkId Web link ID (UUID) string Y
tokenId NFT ID string N
attributes Additional metadata properties to be applied per token (e.g., unique item code, strength, agility, etc. properties included in the NFT) json array N
attributes.traitType Item name that makes up attributes string N
attributes.value Trait value string N

Request sample

curl -X 'POST' \
  'https://api.com2us.com/hive/items/validate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // When using authentication token
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "MINT",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "attributes": [ // Attributes when generating NFT issuance page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

Responses

The HTTP status codes are as follows.

  • Success
    • 200
  • Failure
    • 4xx: Error status code for bad requests
    • 5xx: Error status code for server errors

Result check API call (hive blockchain → game server)

Note

This API is not an API that the game server calls the Hive blockchain server, but rather an API that the Hive blockchain server calls the game server. Therefore, the game server must configure the API endpoint in the form desired by the Hive blockchain server.

When the Hive blockchain server delivers the NFT issuance result to the game server in the Request Body, the game server processes it so that the items cannot be used in the game, and then sends the result back to the Hive blockchain server via an API.


The actions the game server will perform based on the issuance results are as follows.

  • NFT issuance successful
    • Processed to prevent the use of items in the game (e.g., delete items from the game user's inventory)
  • NFT issuance failed
    • Processed to allow the use of items in the game (e.g., lift usage restrictions to allow items to be reused in the game user's inventory)
    • Sends NFT issuance failure results if the user cancels the NFT issuance or if the time limit is exceeded
Warning

You must restrict the use of the corresponding item in the game on the game server until you receive the NFT issuance result.


Below is an example of the NFT issuance page screen when the game server responds with a successful NFT issuance.

Notes

Here are the considerations for developers when configuring API endpoints.

Attributes

By including the unique item code in attributes, you can call the NFT issuance page link creation API and also include the unique code in the Request Body attributes. In this case, you can update the item status with the corresponding unique code.

Authorization header

If the token Query Parameter exists in the gameServerUrl requested from the NFT issuance page link creation API, use this token value in Bearer form.

Request URL

Item Value
URL {gameServerUrl}/items/callback
HTTP Method POST
PORT 80, 443
Content-Type application/json

Header Parameters

Field Name Description Type Required
Authorization The authentication token sent as a token Query Parameter in the NFT issuance page link creation API's gameServerUrl. It is called in the form of Bearer ${token}. Bearer N
User-Agent HiveBlockchain/1.0 string Y

Request Body

Field Name Description Type Required
type MINT string Y
itemId NFT item identification code string Y
playerId Player ID number Y
characterId Character ID string N
webLinkId Web link ID (UUID) string Y
tokenId NFT ID (included if successful) string N
status Transaction result (success, failure) string Y
attributes Additional metadata properties to apply per token (e.g., unique code, strength, agility, etc. properties included in the NFT) json array N
attributes.traitType Item name that makes up attributes string N
attributes.value Trait value string N

Request 샘플

curl -X 'POST' \
  'https://api.com2us.com/hive/items/callback' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \  // When using authentication token
  -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": [ // Attributes when generating NFT issuance page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

Responses

The HTTP status codes are as follows.

  • Success
    • 200
  • Failure
    • 4xx: Error status code for bad requests
    • 5xx: Error status code for server errors