Skip to content

Burn

Burn is a function that allows users to burn issued NFTs and convert them into items that can be used in the game. The process for users to convert NFTs into items is largely as follows.

  1. The user checks their owned NFTs on the NFT viewing page.
  2. The user selects the checked NFT and converts it into an item for reuse in the game (= NFT burning).

Implementation flow of the burn function

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

Note

First, you need to complete the preparation before implementing the Burn feature.

Note

To implement the Burn feature, you need to 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.

Implementing the nft query button

Implement a UI that allows users to open their NFT list in the game client. For example, implement a View Owned NFT List button in the user character's inventory. When this button is pressed, you need to implement the opening of the NFT viewing page according to the content below.

NFT query request

Implement the code that requests the user's NFTs from the game client to the game server. This is to implement the action when the user selects the NFT query button. When the game server receives the game client request, it calls the NFT query page link creation API to show the user's NFT list.

The NFT viewing page is a webpage where users can view the list of NFTs they own. This webpage is provided by the Hive blockchain server. The game server calls the link generation API to obtain this webpage URL (webLinkUrl). When users access this webpage, they can view the list of NFTs they own and burn (destroy) a specific NFT on the blockchain.

Notes

Here are the precautions for developers 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 Verification API or the Result Check API, the game server can use an authentication token (Header Parameters) for the API call, which is optional for the developers. If the authentication token is to be used for the API call, the game server must attach this authentication token as token (Query Parameter) to gameServerUrl and send it to the Hive blockchain server in advance when calling the NFT lookup page link generation API. An example is shown below.

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

A link to a 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 HOME string Y
playerId Player ID number Y
characterId Character ID string Y
gameServerUrl The address to receive success/failure results after item validation and function execution. Send the authentication token as a token Query Parameter to the item validation/result confirmation API header string Y

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": "HOME",
  "playerId": 1276814678,
  "characterId": "zeratu",
  "gameServerUrl": "https://api.com2us.com/hive" //인증 토큰 전송 시: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
}'

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 viewing page with hive SDK

The NFT query page link creation API exposes the webpage URL received as a response using the Hive SDK to open it in an external browser.


Below is an example of the NFT viewing page.

Owned NFT List


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

Note

XPLA Vault is scheduled for support in June 2025.

X-PLANET XPLA Vault

NFT burn execution

On the NFT viewing page, users select an NFT and then execute Burn.

Select NFT to burn from the list Check fee

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 the API endpoint in the form desired by the Hive blockchain server.

The Hive blockchain server requests item verification from the game server to check if the NFTs owned by the user are usable items in the game.

The Hive blockchain server verifies whether the item is usable in the game through the response value delivered by the game server. Once the verification is complete, the Hive blockchain server burns the NFT on the blockchain. If item validation fails, the Hive blockchain server does not burn the NFT.

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 lookup page link creation API.

Authorization header

If the token Query Parameter exists in the gameServerUrl requested from the NFT Query Page Link Creation API, use this token value in Bearer format.

Attributes

When calling the NFT issuance page link creation API, the attributes requested will be included in the item verification API Request Body.

Request URL

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

Item Value
URL {gameServerUrl}/items/validate
HTTP Method POST
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 lookup 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 BURN string Y
itemId NFT item identifier code string Y
playerId Player ID number Y
characterId Character ID string N
webLinkId Web link ID (UUID) string Y
tokenId NFT ID string Y
attributes 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...' \
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "BURN",
    "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"
        }
      ],
    "tokenId": "HIVE#01"
  }'

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 to provide it in the form desired by the Hive blockchain server.

When the Hive blockchain server delivers the NFT burn results to the game server as a Request Body, the game server generates items in the game and then sends the results back to the Hive blockchain server through an API.


The actions the game server will take based on the incineration results are as follows.

  • NFT burn successful
    • Processed to use items in the game (e.g., creating items in the game user's inventory)
  • NFT burn failed
    • No separate processing needed in the game
    • Sends NFT burn failure result if the user cancels the NFT burn or if the time exceeds a certain limit


Below is an example of the NFT burning page screen when the Hive blockchain server successfully communicates the NFT burn.

Notes

Here are some considerations for developers when configuring API endpoints.

Attributes

The attributes requested when calling the NFT issuance page link creation API is included in the result confirmation API Request Body. If the unique code is included in attributes, the item status can be updated with that unique code.

Authorization header

If the token Query Parameter exists in the gameServerUrl requested from the NFT Query Page Link Creation API, use this token value in Bearer format.

Request URL

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

Header Parameters

Field Name Description Type Required
Authorization The authentication token sent as a token Query Parameter in the gameServerUrl of the NFT query page link creation API. 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 BURN 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 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/callback' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "BURN",
    "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

The HTTP status codes are as follows.

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