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

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

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

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

NFT API

NFT 발행

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

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~2²⁵⁶-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`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `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/"
}'

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"
  }
}

// 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...'

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"
        }
      ]
    }
  }
}

{

"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	반환받을 트랜잭션의 인코딩 여부 `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`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `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/"
}'

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"
  }
}

// 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`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `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/"
}'

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"
  }
}

// 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

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

컨버트 타입

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

string

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	반환받을 트랜잭션의 인코딩 여부 `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`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `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/"
}'

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 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 ''

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"
      }
    ]
  }
}

{

"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"
}'

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"
}

{

"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...'

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
    }
  }
}

{

"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...'

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"
  }
}

{

"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...'

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
    }
  }
}

{

"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

}

Actions API

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

Action 생성 API

사용자는 Action 생성 요청 후 응답받은 웹페이지(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을 통해 결과를 전달합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/xpla-platform/v1/actions
Sandbox URL	https://sandbox-bc-api.qpyou.cn/xpla-platform/v1/actions
HTTP Method	POST
Content-Type	application/json

Header Parameters

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

Request Body

필드명	설명	타입	필수 여부
actionType	블록체인 기능에 대한 구분 {MINT \| CONVERT \| LOCK \| UNLOCK \| BURN}	string	Y
info	블록체인 기능별 옵션 정보	json	Y
appid	블록체인 앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y
gameAppid	게임앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y
playerId	플레이어 ID	number	Y
callbackUrl	트랜잭션을 블록체인에 기록 후 성공/실패 결과를 전달 받을 주소	string	Y
language	언어코드	string	Y

actionType별 request body info에 담기는 각 원소 정보

MINT

필드명	설명	타입
nftContract	NFT 컨트랙트 주소	string
itemName	인게임 아이템 이름	string
tokenId	NFT 식별값 (아이템 고유 값)	string
metadata	메타데이터 (NFT 발행 API request body 참조)	json

CONVERT

필드명	설명	타입
convertPool	컨버트풀 계정주소	string
gameCurrencyCode	게임재화 코드	string
userGameCurrencyAmount	유저가 교환할 게임재화 수량	number
minCurrencyAmount	교환 가능한 게임재화의 최소 수량	number
maxCurrencyAmount	교환 가능한 게임재화의 최대 수량	number
totalExchangedCurrencyAmount	유저가 현재까지 교환한 게임재화 수량	number

LOCK

필드명 설명 타입

nftContract NFT 컨트랙트 주소 string

lockContract 락 컨트랙트 주소 string
UNLOCK

필드명 설명 타입

nftContract NFT 컨트랙트 주소 string

lockContract 락 컨트랙트 주소 string

tokenId NFT 식별값 (아이템 고유 값) string
BURN

필드명 설명 타입

nftContract NFT 컨트랙트 주소 string

Responses

필드명	설명	타입
code	API 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.id	Action의 고유ID	string
data.actionType	블록체인 기능에 대한 구분 {MINT \| CONVERT \| LOCK \| UNLOCK \| BURN}	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	Action의 처리결과	string
data.createdAt	Action 등록일자	string
data.updatedAt	Action 수정일자	string

actionType별 response data info에 담기는 각 원소 정보

MINT: request body info의 MINT와 동일

CONVERT

필드명	설명	타입
convertPool	컨버트풀 계정주소	string
gameCurrencyCode	게임재화 코드	string
userGameCurrencyAmount	유저가 교환할 게임재화 수량	number
minCurrencyAmount	교환 가능한 게임재화의 최소 수량	number
maxCurrencyAmount	교환 가능한 게임재화의 최대 수량	number
totalExchangedCurrencyAmount	유저가 현재까지 교환한 게임재화 수량	number
currencyName	게임재화이름	string
currencyLogoUrl	게임재화로고 URL	string
assetType	토큰유형 {token \| coin}	string
ftContract	게임토큰주소	string
tokenName	게임토큰이름	string
tokenLogoUrl	게임토큰로고 URL	string

LOCK: request body info의 LOCK과 동일
UNLOCK: request body info의 UNLOCK과 동
BURN: request body info의 BURN과 동일

Request Sample

	curl -X 'POST' \
  'https://sandbox-bc-api.qpyou.cn/xpla-platform/v1/actions' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
  -H 'Content-Type: application/json' \
  -d '{

// MINT--------------------------------------------------------------------------------------------
  "actionType": "MINT",
  "info": {
    "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
    "itemName": "아비터의 로브",
    "tokenId": "A1234",
    "metadata": {
      "name": "Arbiter'\''s Robe",
      "description": "A robe worn by the arbiter of the world.",
      "image": "https://image01.c2x.world/equip_92053030.gif",
      "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
      "youtubeUrl": "https://www.youtube.com/watch?v=gmdexWtuzAE&pp=ygUEeHBsYQ%3D%3D",
      "externalUrl": "https://dex.c2xnft.com/market?key=4423",
      "attributes": [
        {
          "traitType": "Category",
          "value": "Game"
        }
      ]
    }
  },

// CONVERT--------------------------------------------------------------------------------------------

   "actionType": "CONVERT",
   "info": {
      "convertPool": "xpla1zaztjwm0tequ8rf70vk6f5qsen55zsy2445j94",
      "gameCurrencyCode": "J94597FISHGOLD0001",

      "userGameCurrencyAmount": 1000,
      "minCurrencyAmount": 100,
      "maxCurrencyAmount": 100000,
      "totalExchangedCurrencyAmount": 100
   },

// LOCK--------------------------------------------------------------------------------------------

   "actionType": "lock",
   "info": {
     "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s", 
     "lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp"
   },

// UNLOCK--------------------------------------------------------------------------------------------

   "actionType": "unlock",
    "info": {
     "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s", 
     "tokenId": "283ed-8b23-e4a", 
     "lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp"
   },

// BURN--------------------------------------------------------------------------------------------

   "actionType": "burn",
   "info": {"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s"},

// -------------------------------------------------------------------------------------------------
  "appid": "com.gcp.stepbystep.pcweb.blockchain",
  "gameAppid": "com.gcp.stepbystep.pcweb.blockchain",
  "playerId": 1,
  "callbackUrl": "https://sandbox-bc-api.qpyou.cn/sample/v1/backend/callback",
  "language": "ko"
}'

curl -X 'POST' \

'https://sandbox-bc-api.qpyou.cn/xpla-platform/v1/actions' \

-H 'accept: application/json' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \

-H 'Content-Type: application/json' \

-d '{

// MINT--------------------------------------------------------------------------------------------

"actionType": "MINT",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"itemName": "아비터의 로브",

"tokenId": "A1234",

"metadata": {

"name": "Arbiter'\''s Robe",

"description": "A robe worn by the arbiter of the world.",

"image": "https://image01.c2x.world/equip_92053030.gif",

"animationUrl": "https://image01.c2x.world/equip_92053030.gif",

"youtubeUrl": "https://www.youtube.com/watch?v=gmdexWtuzAE&pp=ygUEeHBsYQ%3D%3D",

"externalUrl": "https://dex.c2xnft.com/market?key=4423",

"attributes": [

{

"traitType": "Category",

"value": "Game"

}

]

}

// CONVERT--------------------------------------------------------------------------------------------

"actionType": "CONVERT",

"info": {

"convertPool": "xpla1zaztjwm0tequ8rf70vk6f5qsen55zsy2445j94",

"gameCurrencyCode": "J94597FISHGOLD0001",

"userGameCurrencyAmount": 1000,

"minCurrencyAmount": 100,

"maxCurrencyAmount": 100000,

"totalExchangedCurrencyAmount": 100

// LOCK--------------------------------------------------------------------------------------------

"actionType": "lock",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp"

// UNLOCK--------------------------------------------------------------------------------------------

"actionType": "unlock",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"tokenId": "283ed-8b23-e4a",

"lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp"

// BURN--------------------------------------------------------------------------------------------

"actionType": "burn",

"info": {"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s"},

// -------------------------------------------------------------------------------------------------

"appid": "com.gcp.stepbystep.pcweb.blockchain",

"gameAppid": "com.gcp.stepbystep.pcweb.blockchain",

"playerId": 1,

"callbackUrl": "https://sandbox-bc-api.qpyou.cn/sample/v1/backend/callback",

"language": "ko"

Response Sample

	// MINT

	{
		 "code": 0,
		 "message": "success",
		 "data": {
	// MINT--------------------------------------------------------------------------------------------
				"actionType": "MINT",
				"info": {
				 "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
				 "itemName": "아비터의 로브",
				 "tokenId": "A1234",
				 "metadata": {
						"name": "Arbiter's Robe",
						"description": "A robe worn by the arbiter of the world.",
						"image": "https://image01.c2x.world/equip_92053030.gif",
						"animationUrl": "https://image01.c2x.world/equip_92053030.gif",
						"youtubeUrl": "https://www.youtube.com/watch?v=gmdexWtuzAE&pp=ygUEeHBsYQ%3D%3D",
						"externalUrl": "https://dex.c2xnft.com/market?key=4423",
						"attributes": [
							 {
									"traitType": "Category",
									"value": "Game"
							 }
						]
				 },
				 "serviceFee": 0.2
				},
				"id": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
				"actionLink": "https://sandbox-xpla-platform.withhive.com/games/mint?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",
	// CONVERT--------------------------------------------------------------------------------------------
				"actionType": "CONVERT",
				"info": {
				 "convertPool": "xpla1zaztjwm0tequ8rf70vk6f5qsen55zsy2445j94",
				 "gameCurrencyCode": "J94597FISHGOLD0001",
	
				"userGameCurrencyAmount": 1000,
				 "minCurrencyAmount": 100,
				 "maxCurrencyAmount": 100000,
				 "totalExchangedCurrencyAmount": 100,
				 "currencyName": "GOLD",
				 "currencyLogoUrl": "https://sandbox-bc-file.qpyou.cn/ipfs/QmdqBYarCoFpPzkG9tgQJoe9NqcLuP9rBnVWn8tRo51uTR",
				 "assetType": "token",
				 "ftContract": "xpla1dhwmvf876g4fwhg28x6ep7jmulrreu8ztrhfk6wmp83f9y3xjstsz78pzy",
				 "tokenName": "FISH",
				 "tokenLogoUrl": "https://sandbox-bc-file.qpyou.cn/ipfs/QmbLRYXgk57KeanzmKuxjv2TtvXwt4DrFoFFYTH1MPkCgU",
				 "serviceFee": 10
				},
				"id": "81c705ac-2e03-4fa7-bb10-feb533b5e754",
				"actionLink": "https://sandbox-xpla-platform.withhive.com/games/convert?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=81c705ac-2e03-4fa7-bb10-feb533b5e754&lang=ko",
	// LOCK--------------------------------------------------------------------------------------------
				"actionType": "LOCK",
				"info": {
					"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
					"lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp",
					"serviceFee": 0.1
				},
				"id": "20cf84b8-af60-4ad4-9251-babf1a6778c3",
				"actionLink": "https://sandbox-xpla-platform.withhive.com/games/convert?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=81c705ac-2e03-4fa7-bb10-feb533b5e754&lang=ko",
	// UNLOCK--------------------------------------------------------------------------------------------
				"actionType": "UNLOCK",
				"info": {
					"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
					"tokenId": "283ed-8b23-e4a",
					"lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp",
					"serviceFee": 0.1
				},
				"id": "8e701ff2-d37b-473a-bdd7-886e40e18d7c",
				"actionLink": "https://sandbox-xpla-platform.withhive.com/games/unlock?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",
	// BURN--------------------------------------------------------------------------------------------
				"actionType": "BURN",
				"info": {
					"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
					"serviceFee": 0.1
				},
				"id": "8fb0c236-71a3-4b40-9ba0-d558f351757a",
				"actionLink": "https://sandbox-xpla-platform.withhive.com/games/burn?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",
	// --------------------------------------------------------------------------------------------------
				"appid": "com.gcp.stepbystep.pcweb.blockchain",
				"gameAppid": "com.gcp.stepbystep.android.google",
				"pid": 1,
				"language": "ko",
				"callbackUrl": "https://sandbox-bc-api.qpyou.cn/sample/v1/backend/callback",
				"company": 3,
				"gameindex": 597,
				"appindex": 21001,
				"result": null,
				"createdAt": "2024-08-05T08:33:15.448Z",
				"updatedAt": "2024-08-05T08:33:15.448Z"
		 }
	}

// MINT

{

"code": 0,

"message": "success",

"data": {

// MINT--------------------------------------------------------------------------------------------

"actionType": "MINT",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"itemName": "아비터의 로브",

"tokenId": "A1234",

"metadata": {

"name": "Arbiter's Robe",

"description": "A robe worn by the arbiter of the world.",

"image": "https://image01.c2x.world/equip_92053030.gif",

"animationUrl": "https://image01.c2x.world/equip_92053030.gif",

"youtubeUrl": "https://www.youtube.com/watch?v=gmdexWtuzAE&pp=ygUEeHBsYQ%3D%3D",

"externalUrl": "https://dex.c2xnft.com/market?key=4423",

"attributes": [

{

"traitType": "Category",

"value": "Game"

}

]

"serviceFee": 0.2

"id": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",

"actionLink": "https://sandbox-xpla-platform.withhive.com/games/mint?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",

// CONVERT--------------------------------------------------------------------------------------------

"actionType": "CONVERT",

"info": {

"convertPool": "xpla1zaztjwm0tequ8rf70vk6f5qsen55zsy2445j94",

"gameCurrencyCode": "J94597FISHGOLD0001",

"userGameCurrencyAmount": 1000,

"minCurrencyAmount": 100,

"maxCurrencyAmount": 100000,

"totalExchangedCurrencyAmount": 100,

"currencyName": "GOLD",

"currencyLogoUrl": "https://sandbox-bc-file.qpyou.cn/ipfs/QmdqBYarCoFpPzkG9tgQJoe9NqcLuP9rBnVWn8tRo51uTR",

"assetType": "token",

"ftContract": "xpla1dhwmvf876g4fwhg28x6ep7jmulrreu8ztrhfk6wmp83f9y3xjstsz78pzy",

"tokenName": "FISH",

"tokenLogoUrl": "https://sandbox-bc-file.qpyou.cn/ipfs/QmbLRYXgk57KeanzmKuxjv2TtvXwt4DrFoFFYTH1MPkCgU",

"serviceFee": 10

"id": "81c705ac-2e03-4fa7-bb10-feb533b5e754",

"actionLink": "https://sandbox-xpla-platform.withhive.com/games/convert?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=81c705ac-2e03-4fa7-bb10-feb533b5e754&lang=ko",

// LOCK--------------------------------------------------------------------------------------------

"actionType": "LOCK",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp",

"serviceFee": 0.1

"id": "20cf84b8-af60-4ad4-9251-babf1a6778c3",

"actionLink": "https://sandbox-xpla-platform.withhive.com/games/convert?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=81c705ac-2e03-4fa7-bb10-feb533b5e754&lang=ko",

// UNLOCK--------------------------------------------------------------------------------------------

"actionType": "UNLOCK",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"tokenId": "283ed-8b23-e4a",

"lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp",

"serviceFee": 0.1

"id": "8e701ff2-d37b-473a-bdd7-886e40e18d7c",

"actionLink": "https://sandbox-xpla-platform.withhive.com/games/unlock?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",

// BURN--------------------------------------------------------------------------------------------

"actionType": "BURN",

"info": {

"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",

"serviceFee": 0.1

"id": "8fb0c236-71a3-4b40-9ba0-d558f351757a",

"actionLink": "https://sandbox-xpla-platform.withhive.com/games/burn?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",

// --------------------------------------------------------------------------------------------------

"appid": "com.gcp.stepbystep.pcweb.blockchain",

"gameAppid": "com.gcp.stepbystep.android.google",

"pid": 1,

"language": "ko",

"callbackUrl": "https://sandbox-bc-api.qpyou.cn/sample/v1/backend/callback",

"company": 3,

"gameindex": 597,

"appindex": 21001,

"result": null,

"createdAt": "2024-08-05T08:33:15.448Z",

"updatedAt": "2024-08-05T08:33:15.448Z"

}

callbackUrl API

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

Request URL

URL	사용자 지정
HTTP Method	POST
Content-Type	application/json

Header Parameters

필드명	설명	타입	필수 여부
Authorization	callbackUrl에 token 쿼리 파라미터가 존재: Bearer ${token} 쿼리 파라미터가 없을 경우 생략	string	N
X-Request-ID	Action 요청 시 발급받은 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	Action 수행 결과	json	Y
result.actionStatus	액션 상태 {SUCCESS, FAILRUE, EXPIRATION, CANCELLATION}	string	Y
result.actionType	Action의 유형MINT, BURN, LOCK, UNLOCK	json	Y
result.txHash	트랜잭션 해시	string	Y
result.isAvailableItem	게임 내 아이템 사용 가능 여부	boolean	Y
data	Action 수행 내용	json	Y
data.user	Action 수행에 사용된 사용자 정보	json	Y
data.user.playerId	플레이어 ID	string	Y
data.user.wallet	플레이어 지갑주소	string	Y
data.nft	Action 수행에 사용된 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	Action 수행 결과	json	Y
result.actionStatus	액션 상태 {SUCCESS, FAILRUE, EXPIRATION, CANCELLATION}	string	Y
result.actionType	Action의 유형 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	Action 수행 내용	json	Y
data.user	Action 수행에 사용된 사용자 정보	json	Y
data.user.playerId	플레이어 ID	string	Y
data.user.wallet	플레이어 지갑주소	string	Y
data.convert	Action 수행에 사용된 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

Hive Blockchain API

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

NFT API

NFT 발행

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

NFT 조회

Request URL

Path Parameters

Header Parameters

Responses

Request Sample

Response Sample

Lock API

NFT 잠금

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

NFT 잠금 해제

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

Convert API

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

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

컨버트 풀 확인

Request URL

Path Parameters

Header Parameters

Responses

Request Sample

Response Sample

Transaction API

Txhash 등록

Request URL

Header Parameters

Request Body

Responses

Request Sample

Response Sample

트랜잭션 목록 조회

Request URL

Header Parameters

Query Parameters

Responses

Request Sample

Response Sample

Token API

토큰 잔액 조회

Request URL

Path Parameters

Header Parameters

Responses

Request Sample

Response Sample

Contract API

컨트랙트 조회

Request URL

Path Parameters

Header Parameters

Query Parameters