콘텐츠로 이동

Hive Blockchain API

Hive 블록체인 API는 Hive에서 제공하는 AppID, PlayerID 기반으로 동작하는 웹3 게임 API입니다. 게임 유저가 한 번에 200개까지 발행할 수 있는 대량 발행 기능과 유저별 트랜잭션 로그 조회와 같은 웹3 게임에 최적화된 기능을 제공합니다. Hive 블록체인 API를 이용하면 웹 3 게임의 개발부터 운영 및 관리까지 프로젝트를 효율적으로 관리할 수 있습니다. Hive 블록체인 API는 Polygon 블록체인과 XPLA 블록체인을 지원합니다.

사전 준비: API 인증 토큰 발급하기

Hive 블록체인 API를 호출하려면 API Header에 인증 토큰을 첨부해야 합니다. API 인증 토큰을 발급받는 방법은 다음과 같습니다.

  1. Hive 콘솔에 가입 후 앱센터 > 게임목록 > 새 게임 등록하기에서 게임을 등록합니다.
  2. 앱센터 > AppID 목록 > 새 AppID 등록하기에서 AppID를 생성합니다.
    • AppID 만들기: 웹 로그인 AppID
    • 사용 용도 선택: 블록체인
    • 사용할 AppID 선택: "자동 생성된 AppID" 또는 "자동 생성된 AppID + 추가정보" 선택
  3. Hive 콘솔 > 블록체인 > API 인증키 조회에서 게임명을 선택하고 ID와 인증키(SecretKey)를 발급받습니다.
  4. auth-token API Request Body에 ID와 SecretKey를 넣고 API를 호출합니다.
  5. API 응답값에서data.accessToken이 인증 토큰입니다.

NFT API

NFT 발행

특정 주소(to)로 토큰을 발행하는 트랜잭션을 생성합니다. 발행할 NFT 정보(mintMsg.tokenId, mintMsg.metadata 등)를 배열에 담아 호출합니다. API 호출당 1개 계정에게 XPLA는 최대 200 토큰, Polygon은 최대 50 토큰을 발행할 수 있습니다. from은 발행 권한을 가진 계정이어야 합니다.

Note

API로 발행한 디지털 자산과 자산의 메타데이터(mintMsg.metadata)는 Public IPFS(InterPlanetary File System)에 등록됩니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/nft/{contract}/mint
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/mint
HTTP Method POST
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
contract NFT 컨트랙트 주소 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Request body

필드명 설명 타입 필수 여부
playerId 플레이어 ID string Y
from NFT를 발행하는 계정 주소 string Y
to NFT를 받을 지갑 주소 string Y
isSend true이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 txHash를 받습니다. false이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 data.rawTx를 응답값으로 받습니다. boolean Y
mintMsg 발행 시 필요한 정보 array Y
mintMsg.tokenId NFT ID입니다. NFT 발행자가 지정하며 중복을 허용하지 않습니다.
  • Polygon: 문자열, 정수(0~2256-1)만 사용 가능
  • XPLA: 문자열만 사용 가능
string Y
mintMsg.royaltyPercentage 로열티 비율입니다. NFT가 판매 또는 재판매될 때마다 NFT 작성자 또는 권리를 가진 보유자에게 지불할 금액입니다. 총 판매금액에 로열티로 지불할 비율이 설정됩니다. 아티스트 및 기타 NFT 제작자에게 지속적인 자금을 지원하려는 NFT 마켓 플레이스를 위한 기능입니다. NFT 전송 시 수취인에게 로열티가 자동으로 지불되지 않으며, 마켓 플레이스에서 NFT 로열티를 확인하고 수취인에게 지불합니다. OpenSea에 적용된 기능입니다.
  • Polygon: 소수점 둘째자리까지 허용합니다.
  • XPLA: 소수점을 허용하지 않습니다.
number Y
mintMsg.metadata 메타데이터
  • 메타데이터 입력 시 타입 및 url(animationUrl, youtubeUrl, externalUrl) 포맷을 확인합니다. 정확하지 않은 데이터 전송 시 API가 정상 작동하지 않습니다.
  • 메타데이터가 IPFS에 저장될 때는 OpenSea와 연동 가능한 snake case로 저장됩니다(예시: animationUrl → animation_url)
 json Y
mintMsg.metadata.name NFT 이름 string Y
mintMsg.metadata.description NFT 설명 string N
mintMsg.metadata.image NFT 이미지 주소입니다. IPFS에 업로드하기 위한 외부에서 접근 가능한 웹사이트 주소 또는 Public IPFS 주소입니다. string Y
mintMsg.metadata.animationUrl NFT 관련 애니메이션 주소 string N
mintMsg.metadata.youtubeUrl 유투브 주소 string N
mintMsg.metadata.imageData NFT 이미지 정보 string N
mintMsg.metadata.externalUrl 외부로 연결되는 주소 string N
mintMsg.metadata.backgroundColor OpenSea에서 토큰의 배경색 정보 string N
mintMsg.metadata.attributes 메타데이터 속성 정보입니다. 메타데이터에 명시하지 않았던부가적인 정보입니다. json N
mintMsg.metadata.attributes.traitType attributes를 구성하는 항목명입니다. string N
mintMsg.metadata.attributes.maxValue trait 최대값 number N
mintMsg.metadata.attributes.value trait값입니다.mintMsg.metadata.attributes.maxValue보다 작아야 합니다. mintMsg.metadata.attributes.displayType이 date이면 value에 unix timestamp (seconds)를 입력합니다. string 또는 number N
mintMsg.metadata.attributes.displayType trait 노출 유형입니다. 기본값은 string 타입입니다.
  • number: Number 타입
  • boost_percentage: OpenSea Boosts에 % 정보로 노출
  • boost_number: OpenSea Boosts에 노출
  • date: 날짜 형식으로 노출(예시: Tuesday, January 1st, 2019)
 string N
encoded 반환받을 트랜잭션의 인코딩 여부
  • true: data.rawTx으로 인코딩된 Raw Transaction String을 받습니다.
  • false: data.rawTx으로 인코딩을 디코딩한 JSON 결과값을 받습니다.
 boolean Y
callbackUrl 트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소 string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.rawTx 트랜잭션 데이터입니다.isSend가 false일 때에만 이 값을 받습니다. string 또는 json
data.hashedTx 해시한data.rawTx입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. 1. x-network가 polygon 2. from이 다중 서명 지갑 주소 3. isSend가 false string
data.txhash 트랜잭션 전송 결과로 받는 트랜잭션 해시입니다.isSend가 true일 때만 이 값을 받습니다. string
data.status 전송한 트랜잭션 상태입니다.isSend가 true일 때, 트랜잭션이 잘 전송되었다면 PENDING을 받습니다. isSend가 false이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 WAITING 값을 받습니다. string
data.reqeustId API 요청을 식별할 수 있는 고유값 string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/mint' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20y...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "to": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",
  "isSend": true,
  "royaltyPercentage": 7.5,
  "mintMsg": [
    {
      "tokenId": "1",
      "metadata": {
        "name": "Arbiter'''s Robe",
        "description": "desc",
        "image": "https://image01.c2x.world/equip_92053030.gif",
        "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
        "externalUrl": "https://dex.c2xnft.com/market?key=4423",
        "attributes": [
          {
            "traitType": "Category",
            "value": "Game",
          }
        ]
      }
    }
  ],
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

Response sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

NFT 조회

토큰 ID(tokenId)에 해당하는 NFT를 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId}
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId}
HTTP Method POST
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
contract NFT 컨트랙트 주소 string Y
tokenId 토큰 ID string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.nftContract NFT 컨트랙트 주소 string
data.tokenId 토큰 ID string
data.tokenUri 토큰의 IPFS 주소 string
data.gatewayUrl 토큰의 Gateway 주소 string
data.metadata 메타데이터 정보 json
data.metadata.name NFT 이름 string
data.metadata.description NFT 설명 string
data.metadata.image NFT 이미지 주소입니다. 외부에서 접근 가능한 웹사이트 주소 또는 Public IPFS 주소입니다. string
data.metadata.animationUrl NFT 관련 애니메이션 주소 string
data.metadata.youtubeUrl 유투브 주소 string
data.metadata.imageData NFT 이미지 정보 string
data.metadata.externalUrl 외부로 연결되는 주소 string
data.metadata.backgroundColor OpenSea에서 토큰의 배경색 정보 string
data.metadata.attributes 메타데이터 속성 정보입니다. 메타데이터에 명시하지 않았던 부가적인 정보입니다. json
data.metadata.attributes.traitType attributes를 구성하는 항목명입니다. string
data.metadata.attributes.maxValue trait 최대값 string
data.metadata.attributes.value trait값입니다.data.metadata.attributes.maxValue보다 작아야 합니다. data.metadata.attributes.displayType이 date이면 value에 unix timestamp (seconds)를 입력합니다. string 또는 number
data.metadata.attributes.displayType trait 노출 유형입니다. 기본값은 string 타입입니다.
  • number: Number 타입
  • boost_percentage: OpenSea Boosts에 % 정보로 노출
    • boost_number: OpenSea Boosts에 노출
  • date: 날짜 형식으로 노출(예시: Tuesday, January 1st, 2019)
 string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/tokens/1' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "nftContract": "0x31a6854383c81daab14089cba0b9de1d42ecd65f",
    "tokenId": "5",
    "tokenUri": "ipfs://QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",
    "gatewayUrl": "https://test-bc-file.qpyou.cn/ipfs/QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",
    "metadata": {
      "name": "Arbiter's Robe",
      "description": "desc",
      "image": "https://image01.c2x.world/equip_92053030.gif",
      "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
      "externalUrl": "https://dex.c2xnft.com/market?key=4423",
      "backgroundColor": "orange",
      "attributes": [
        {
          "traitType": "Category",
          "value": "Game",
          "displayType": "string"
        }
      ]
    }
  }
}

Lock API

NFT 잠금

NFT 잠금이란 발행한 NFT를 거래할 수 없도록 잠그는 것입니다. 게임 유저가 게임 아이템을 민팅해서 NFT를 얻은 후 다시 게임에서 해당 아이템 사용을 원할 경우 NFT를 거래할 수 없도록 잠급니다. 소유자(owner)는 보유한 NFT(tokenId)를 사용할 수 없도록 잠금 설정 트랜잭션을 생성합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/nft/contract/{contract}/lock
Sandbox URL https://sandbox-bc-api.qpyou.cn/ service/v1/nft/contract/{contract}/lock
HTTP Method POST
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
contract NFT 컨트랙트 주소 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Request body

필드명 설명 타입 필수 여부
playerId 플레이어 ID string Y
from NFT 소유자 지갑 주소 string Y
isSend true이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 txHash를 받습니다. false이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 data.rawTx를 응답값으로 받습니다. boolean Y
lockContract 잠금 컨트랙트 주소 string Y
tokenId NFT ID string Y
encoded 반환받을 트랜잭션의 인코딩 여부<i> true: data.rawTx으로 인코딩된 Raw Transaction String을 받습니다. </i> false: data.rawTx으로 인코딩을 디코딩한 JSON 결과값을 받습니다. boolean Y
callbackUrl 트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소 string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.rawTx 트랜잭션 데이터입니다.isSend가 false일 때에만 이 값을 받습니다. string 또는 json
data.hashedTx 해시한data.rawTx입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. ,
1. x-network가 polygon
2. from이 다중 서명 지갑 주소
3. isSend가 false		 string
data.txhash 트랜잭션 전송 결과로 받는 트랜잭션 해시입니다.isSend가 true일 때만 이 값을 받습니다. string
data.status 전송한 트랜잭션 상태입니다.isSend가 true일 때, 트랜잭션이 잘 전송되었다면 PENDING을 받습니다. isSend가 false이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 WAITING 값을 받습니다. string
data.reqeustId API 요청에 대한 고유 식별 정보 string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/contract/0xebd9144485089ebe248f8490984a60579407c262/lock' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "isSend": true,
  "lockContract": "0x572f47db51a98ae0d51324c2703d9d63ee3c9f03",
  "tokenId": "1",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

Response sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

NFT 잠금 해제

소유자(owner)가 NFT(tokenId)를 사용할 수 있도록 잠금 설정을 해제하는 트랜잭션을 생성합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock
HTTP Method POST
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
contract 잠금 컨트랙트 주소 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Request body

필드명 설명 타입 필수 여부
playerId 플레이어 ID string Y
nftContract NFT 컨트랙트 주소 string Y
from 잠금 컨트랙트 소유주 지갑 주소 string Y
isSend true이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 txHash를 받습니다. false이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 data.rawTx를 응답값으로 받습니다. boolean Y
tokenId NFT ID string Y
encoded 반환받을 트랜잭션의 인코딩 여부
  • true: data.rawTx으로 인코딩된 Raw Transaction String을 받습니다.
  • false: data.rawTx으로 인코딩을 디코딩한 JSON 결과값을 받습니다.
boolean Y
callbackUrl 트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소 string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.rawTx 트랜잭션 데이터입니다.isSend가 false일 때에만 이 값을 받습니다. string 또는 json
data.hashedTx 해시한data.rawTx입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다.
1. x-network가 polygon
2. from이 다중 서명 지갑 주소
3. isSend가 false		 string
data.txhash 트랜잭션 전송 결과로 받는 트랜잭션 해시입니다.isSend가 true일 때만 이 값을 받습니다. string
data.status 전송한 트랜잭션 상태입니다.isSend가 true일 때, 트랜잭션이 잘 전송되었다면 PENDING을 받습니다. isSend가 false이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 WAITING 값을 받습니다. string
data.reqeustId API 요청을 식별할 수 있는 고유값 string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/0x572f47db51a98ae0d51324c2703d9d63ee3c9f03/unlock' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2ZXNka...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "isSend": true,
  "nftContract": "0xebd9144485089ebe248f8490984a60579407c262",
  "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "tokenId": "2",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

Response sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

Convert API

게임 재화와 게임 토큰을 교환

게임 토큰과 게임 재화를 교환합니다.

  • to-token: 게임 재화(gameCurrencyCode)를 게임 토큰(gameToken)으로 교환합니다.
  • to-currency: 게임 토큰(gameToken)을 게임 재화(gameCurrencyCode)로 교환합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/convert/{type}
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/convert/{type}
HTTP Method POST
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
type 컨버트 타입
  • to-token: 게임 재화(gameCurrencyCode)를 게임 토큰(gameToken)으로 교환합니다.
  • to-currency: 게임 토큰(gameToken)을 게임 재화(gameCurrencyCode)로 교환합니다.
 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Request body

필드명 설명 타입 필수 여부
playerId 플레이어 ID string Y
isSend true이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 txHash를 받습니다. false이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 data.rawTx를 응답값으로 받습니다. boolean Y
owner 사용자의 지갑 주소 string Y
convertPool 컨버트풀 주소 string Y
gameTokenAmount 게임 토큰 수량 string Y
gameCurrencyCode 게임 재화 코드 string Y
gameCurrencyAmount 게임 재화 수량 string Y
encoded 반환받을 트랜잭션의 인코딩 여부<i> true: data.rawTx으로 인코딩된 Raw Transaction String을 받습니다. </i> false: data.rawTx으로 인코딩을 디코딩한 JSON 결과값을 받습니다. boolean Y
callbackUrl 트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소 string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.rawTx 트랜잭션 데이터입니다.isSend가 false일 때에만 이 값을 받습니다. string 또는 json
data.hashedTx 해시한data.rawTx입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다.
1. x-network가 polygon
2. from이 다중 서명 지갑 주소
3. isSend가 false		 string
data.txhash 트랜잭션 전송 결과로 받는 트랜잭션 해시입니다.isSend가 true일 때만 이 값을 받습니다. string
data.status 전송한 트랜잭션 상태입니다.isSend가 true일 때, 트랜잭션이 잘 전송되었다면 PENDING을 받습니다. isSend가 false이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 WAITING 값을 받습니다. string
data.reqeustId API 요청을 식별할 수 있는 고유값 string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/convert/to-token' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "isSend": true,
  "owner": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",
  "convertPool": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "gameTokenAmount": "1",
  "gameCurrencyCode": "A39539HFTGOLD0001",
  "gameCurrencyAmount": "1000",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

Response sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

컨버트 풀 확인

컨버트 풀이란 게임사가 발행한 게임 토큰과 게임 재화을 서로 교환할 수 있는 곳입니다. 컨버트 풀의 잔여 토큰 수량과 게임 재화 수량을 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
HTTP Method GET
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
convertPool 컨버트풀 주소 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/0xdcd51770d06B54204abd8c30A25b4583D4cABa39' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' 
  -d ''

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "convertPoolAmount": "1000000000",
    "gameCurrency": [
      {
        "goodsCode": "A39539HFTBRONZE0003",
        "goodsAmount": "10000000000"
      },
      {
        "goodsCode": "A39539HFTGOLD0001",
        "goodsAmount": "1000000000000"
      },
      {
        "goodsCode": "A39539HFTSILVER0002",
        "goodsAmount": "100000000000"
      }
    ]
  }
}

Transaction API

Txhash 등록

어떤 트랜잭션을 생성했을 때(mint, convert, lock API 등) 응답값으로 받은 requestId와, 이 트랜잭션을 블록체인에 기록하고 받은 txHash를 등록 합니다. 트랜잭션 생성 요청이 정상적으로 완료되었는지 추적하기 위한 절차입니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/tx/hash
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash
HTTP Method PATCH
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Request body

필드명 설명 타입 필수 여부
requestId API 요청을 식별할 수 있는 고유값 string Y
txHash 트랜잭션 해쉬 string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json

Request sample

curl -X 'PATCH' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImN...' 
  -H 'Content-Type: application/json' 
  -d '{
  "requestId": "538d0ca4-9d8b-4b8c-ab02-c68bc1623ed3",
  "txHash": "0x99a93c8ba06865bd7054835d5f9abe57424289dca15ea61fe55a33a0651b058c"
}'

Response sample

{
  "code": 0,
  "message": "success"
}

트랜잭션 목록 조회

요청한 트랜잭션들 목록을 조회합니다. 요청한 트랜잭션이 블록체인에 잘 기록되면 트랜잭션 상태(transactions.txStatus)가 성공으로 업데이트됩니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/tx
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/tx
HTTP Method GET
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Query parameters

필드명 설명 타입 필수 여부
playerId 플레이어 ID string N
startDate 트랜잭션 생성 일자 검색 조건(시작일, yyyy-mm-dd) string N
endDate 트랜잭션 생성 일자 검색 조건(종료일, yyyy-mm-dd) string N
page 현재 페이지 번호 number N
limit 1개 페이지에 노출될 트랜잭션 건수 number N

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
transactions 트랜잭션 정보 array
transactions.appid 앱센터에서 등록한 앱 고유 식별 코드 string
transactions.playerId 플레이어 ID number
transactions.address 트랜잭션을 생성한 지갑의 주소 string
transactions.contract 요청 트랜잭션의 컨트랙트 주소 string
transactions.requestId API 호출에 대한 고유코드 string
transactions.requestParams API 호출 파라미터 json
transactions.txType 트랜잭션 유형 string
transactions.txStatus 트랜잭션 상태 string
transactions.txHash 트랜잭션 Hash string
transactions.createdAt 트랜잭션 생성일자 string
transactions.updatedAt 트랜잭션 업데이트일자 string
meta 페이지네이션 정보 json
meta.totalItems 총 건수 number
meta.itemCount 노출 건수 number
meta.itemsPerPage 페이지당 노출될 건수 number
meta.totalPages 총 페이지 수 number
meta.currentPage 현재 페이지 번호 number

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/tx?playerId=1324&startDate=2023-08-10&endDate=2023-08-10' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "transactions": [
      {
        "appid": "com.com2us.hivesdk.c2xwallet.hivepc.kr.test",
        "address": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
        "contract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",
        "requestId": "1643105b-7669-4260-8679-ca967660df41",
        "requestParams": {
          "encoded": true,
          "tokenId": "1",
          "playerId": 1324,
          "callbackUrl": "https://withhive.com/",
          "nftContract": "0xa3fd0377a12b75ac2f70d5f69550332c96582b00",
          "lockContract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",
          "lockContractOwner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765"
        },
        "txType": "UNLOCK",
        "txStatus": "SUCCESS",
        "txHash": "0x78889d58613816c16389a7031634cc781fc725c3b3a88999524c92f67be89236",
        "createdAt": "2023-08-10T07:23:05.000Z",
        "updatedAt": "2023-08-10T07:25:00.000Z"
      }
    ],
    "meta": {
      "totalItems": 11,
      "itemCount": 1,
      "itemsPerPage": 1,
      "totalPages": 11,
      "currentPage": 1
    }
  }
}

Token API

토큰 잔액 조회

토큰 소유자 계정 주소(from)의 현재 토큰 잔고를 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
HTTP Method GET
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
contract 토큰 컨트랙트 주소 string Y
from 토큰 소유자 계정 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.value 토큰 잔액 string
data.rawValue data.decimals을 적용하지 않은 토큰 잔액 string
data.decimals 토큰 소수점 최대 자리수 number
data.symbol 토큰 심볼 string
data.symbolUri 토큰 심볼 이미지 URI string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/ft/0x94853BdC9c6AdD50D7842D1A3117fab385457470/account/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765/balance' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6I...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "value": "999998999",
    "symbol": "ST",
    "decimals": 18,
    "rawValue": "999998999000000000000000000"
  }
}

Contract API

컨트랙트 조회

컨트랙트를 배포한 계정 주소(owner)에서 배포한 컨트랙트를 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/service/v1/contract/owner/{owner}
Sandbox URL https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/{owner}
HTTP Method GET
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
owner 컨트랙트를 배포한 계정 주소 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y
x-appid 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다. string Y

Query parameters

필드명 설명 타입 필수 여부
contractType 컨트랙트 종류 string N
page 현재 페이지 번호 number N
limit 1개 페이지에 노출할 컨트랙트 개수 number N

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.contracts 컨트랙트 정보 array
data.contracts.network 체인정보 string
data.contracts.owner 컨트랙트 배포한 계정주소 string
data.contracts.address 컨트랙트 주소 string
data.contracts.type 컨트랙트 종류 string
data.contracts.name 컨트랙트 이름 string
data.contracts.gameIndex 게임 인덱스 number
data.contracts.gameName 게임 이름 string
data.contracts.symbol 컨트랙트 심볼 이미지 URI string
data.contracts.symbolUri 컨트랙트 심볼 이미지 URI string
data.contracts.createdAt 컨트랙트 등록일자 string
meta 페이지네이션 정보 json
meta.totalItems 총 건수 number
meta.itemCount 노출 건수 number
meta.itemsPerPage 페이지 당 노출될 건수 number
meta.totalPages 총 페이지 수 number
meta.currentPage 현재 페이지 번호 number

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765?contractType=FT&limit=1' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydX...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "contracts": [
      {
        "gameIndex": 539,
        "gameName": "HIVE SDK(en)",
        "owner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
        "address": "0x05524fd875255ebd9c5f8871015ccc37b7fb20de",
        "name": "Fungible Token",
        "type": "FT",
        "symbol": "Fungible Token",
        "symbolUri": "https://sandbox-bc-file.qpyou.cn/ipfs/QmfJ9oT8Yb69bGr9bKozoYFYDQ4e1qPy31q4W3xsxfVw9L",
        "createdAt": "2023-08-10T01:09:59.000Z",
        "network": "polygon"
      }
    ],
    "meta": {
      "totalItems": 5,
      "itemCount": 1,
      "itemsPerPage": 1,
      "totalPages": 5,
      "currentPage": 1
    }
  }
}

XPLA Platform API

XPLA Platform API는 XPLA 블록체인을 기반으로 게임과 연동하여 웹페이지 URL을 제공하는 API입니다. 사용자는 XPLA Platform API를 통해 게임 재화와 게임토큰(XPLA) 간의 Mint, Convert, Lock, Unlock, Burn 기능을 수행할 수 있습니다.

사용자는 XPLA Web Link 생성 요청 후 응답받은 웹페이지(actionLink)에 접속하여 아래와 같은 블록체인 기능을 수행할 수 있습니다.

  • Mint: 아이템을 NFT로 발행하는 기능으로 아이템에 대한 고유한 값으로 NFT ID(tokenId)를 설정, NFT가 발행되면 인게임 아이템은 비활성화 처리가 필요
  • Convert: 게임재화와 XPLA 또는 게임토큰 간 교환하는 기능으로 Hive 콘솔에서 등록한 게임재화 코드(gameCurrencyCode)가 필요, 게임재화와 토큰(XPLA)간 교환이 끝나면 인게임 게임재화 수량 업데이트가 필요
  • Lock: 발행된 NFT를 잠금하고 다시 인게임에서 사용하는 기능으로 인게임 내 아이템 활성화가 필요, (Lock 후 인게임에서 사용가능한 아이템은 게임 내 교환 또는 제거되지 않아야 Unlock이 가능)
  • Unlock: 인게임에서 사용중인 아이템을 다시 사용자 지갑에서 사용할 수 있도록 NFT 잠금해제하는 기능으로 아이템에 대한 고유한 값 NFT ID(tokenId)가 요구되고 NFT를 잠금(Lock)한 계정과 지갑에서만 잠금해제(Unlock) 가능, Unlock이 수행되면 인게임 아이템은 비활성화 처리가 필요
  • Burn: 발행된 NFT를 소멸시키고 인게임에서 해당 아이템을 사용하는 기능으로 Burn 후 인게임에서 아이템 교환 및 제거가 가능

Mint, Convert, Lock, Unlock, Burn 기능 수행 후 callbackUrl을 통해 결과를 전달합니다.

Note

한번 생성된 XPLA Web Link는 5분간 유효하며 5분이 지나거나 해당 기능 수행이 완료되면 더이상 사용할 수 없습니다.

Responses

필드명 설명 타입
code API 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.id XPLA Web Link의 고유ID string
data.actionType 블록체인 기능에 대한 구분 string
data.info actionType별 응답 정보 json
data.info.serviceFee 블록체인 기능사용에 대한 서비스 수수료비용 number
data.appid 블록체인 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록 에서 확인할 수 있습니다. json
data.gameAppid 게임앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록 에서 확인할 수 있습니다. string
data.playerId 플레이어 ID number
data.language 언어코드 string
data.callbackUrl 트랜잭션을 블록체인에 기록 후 성공/실패 결과를 전달 받을 주소 string
data.company 회사 고유 번호 number
data.gameindex 게임 인덱스 number
data.appindex Hive 앱센터에서 부여한 앱 고유 번호 number
data.actionLink 블록체인 기능을 수행할 수 있는 웹페이지 링크 string
data.result XPLA Web Link의 처리결과 string
data.createdAt XPLA Web Link 생성일자 string
data.updatedAt XPLA Web Link 수정일자 string

CallbackUrl API

사용자가 Action 기능(MINT, LOCK, UNLOCK, BURN, CONVERT) 사용 후 callbackUrl를 요청하면 Action 수행 결과를 전달받을 수 있습니다.

Header Parameters

필드명 설명 타입 필수 여부
Authorization callbackUrl에 token 쿼리 파라미터가 존재: Bearer ${token}
쿼리 파라미터가 없을 경우: 생략		 string N
X-Request-ID XPLA Web Link 생성 요청 시 발급받은 ID string Y
User-Agent XplaPlatform/1.0 string Y

Request Body (MINT, LOCK, UNLOCK, BURN 사용 시 CallbackUrl)

Mint, Lock, Unlock, Burn 수행에 대한 액션 상태(result.actionStatus)와 인게임에서 업데이트가 필요한 아이템 사용 가능 여부(result.isAvailableItem)를 전달합니다.

사용자(data.user.playerId)가 보유한 아이템(data.nft.tokenId) 업데이트가 필요합니다.

필드명 설명 타입 필수 여부
result XPLA Web Link에서 교환 후 처리된 결과 json Y
result.actionStatus 액션 상태 string Y
result.actionType XPLA Web Link 유형 MINT, BURN, LOCK, UNLOCK json Y
result.txHash 트랜잭션 해시 string Y
result.isAvailableItem 게임 내 아이템 사용 가능 여부 boolean Y
data XPLA Web Link에서 처리된 내용 json Y
data.user XPLA Web Link에서 처리된 사용자 정보 json Y
data.user.playerId 플레이어 ID string Y
data.user.wallet 플레이어 지갑주소 string Y
data.nft XPLA Web Link 처리된 nft 정보 json Y
data.nft.nftContract NFT 컨트랙트 주소 string Y
data.nft.tokenId NFT ID string Y
data.serviceFeeAmount 유저가 지불한 서비스 수수료 (XPLA) number Y

Request Body (CONVERT 사용 시 CallbackUrl)

Convert 수행에 대한 액션상태(result.actionStatus)와 인게임에서 업데이트가 필요한 게임 재화 수량(result.amount)을 전달합니다.

게임 재화 코드(result.amount.currencyCode)에 해당하는 사용자가 보유한 게임 재화 수량(result.amount) 업데이트가 필요합니다.

필드명 설명 타입 필수 여부
result XPLA Web Link에서 교환 후 처리된 결과 json Y
result.actionStatus 액션 상태 string Y
result.actionType XPLA Web Link 유형 CONVERT json Y
result.txHash 트랜잭션 해시 string Y
result.amount 컨버트 결과 수량 정보 json Y
result.amount.changeUserAmount 유저의 게임재화 변경 수량 (+, -) number Y
result.amount.changePoolAmount 컨버트 풀의 게임재화 변경 수량 (+, -) number Y
result.amount.currencyCode 게임 재화 코드 string Y
data XPLA Web Link에서 처리된 내용 json Y
data.user XPLA Web Link에서 처리된 사용자 정보 json Y
data.user.playerId 플레이어 ID string Y
data.user.wallet 플레이어 지갑주소 string Y
data.convert XPLA Web Link에서 처리된 convert 정보 json Y
data.convert.type 컨버트 유형 (CONVERT_TO_TOKEN, CONVERT_TO_CURRENCY) string Y
data.convert.convertPool 컨버트 풀 주소 string Y
data.convert.ftContract 토큰 주소 (또는 XPLA) string Y
data.convert.currencyCode 게임 재화 코드 string Y
data.in 컨버트풀에 유입되는 수량정보 json Y
data.in.amount 유저가 요청한 토큰(재화) 수량 number Y
data.in.txFeeAmount 유저가 지불한 트랜잭션 수수료 number Y
data.in.txFeeType XPLA 또는 CURRENCY string Y
data.out 컨버트풀에서 유출되는 수량정보 json Y
data.out.amout 유저가 지급받을 토큰(재화) 수량 number Y
data.serviceFeeAmount 유저가 지불한 서비스 수수료 (XPLA) number Y