跳轉至

合約 API

合約 API 提供以下功能。

  • 註冊、查詢和修改合約資源
  • 部署、查詢、修改合約並執行合約方法

前置條件：獲取 API 認證令牌

要呼叫合約 API，您必須將身份驗證令牌附加到 API 的標頭中。這是獲取您的 API 身份驗證令牌的方法。

  1. 在 Hive 控制台注册，前往 AppCenter > 游戏列表 > 注册新游戏。
  2. 在 AppCenter > AppID 列表 > 注册新 AppID 创建一个新的 AppID。
    • 注册新 AppID：Web 登录 AppID
    • 使用目的：区块链
    • 要使用的 AppID：选择“自动生成的 AppID”或带有“附加信息”的“自动生成的 AppID”
  3. 前往 Hive 控制台 > 区块链 > 搜索 API 身份验证密钥，选择并搜索游戏名称，获取 ID 和密钥。
  4. 将 ID 和密钥插入 auth-token API 的请求体中并调用此 API。
  5. 您可以在 API 响应中获取您的 API 身份验证密钥作为 data.accessToken。

註冊合約資源

註冊合約的資源。註冊合約名稱（contractName）、合約描述（contractDesc）以及合約編譯後生成的字節碼和ABI/方案。

Note
  • 合約資源未在區塊鏈上記錄。
  • 合約必須用 Solidity 或 Rust 編寫。

請求 URL

實時 URL https://bc-api.qpyou.cn/core/v1/contract/resource
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource
HTTP 方法 POST
內容類型 application/json

標頭參數

欄位名稱 描述 類型 必需
Authorization 認證令牌，用於調用 API 字串 是
x-network 區塊鏈網絡 字串 是

請求主體

欄位名稱 描述 類型 必需
from 合約擁有者的地址 字串 Y
contractName 合約名稱 字串 Y
contractDesc 合約的描述 字串 Y
contractAbi 合約編譯時生成的應用程式二進位介面。 檔案 Y
contractBytecode 合約編譯時生成的位元組碼 檔案 Y

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果消息 字串
data API 回應數據 json
data.resourceId 合約資源 ID 數字

請求範例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2...' 
  -H 'Content-Type: multipart/form-data' 
  -F 'from=0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0' 
  -F 'contractName=Com2us Sample Token Contract' 
  -F 'contractDesc=Fungible Token Contract' 
  -F 'contractAbi=@erc20-capped.json;type=application/json' 
  -F 'contractBytecode=@erc20-capped.code'

回應範例

// polygon
{
  "code": 0,
  "message": "success",
  "data": {
    "resourceId": 1
  }
}
// xpla
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f873830138810c8451f4d5c08451f4d5cf83018c0694572f47db51a98...",
    "resourceId": 1
  }
}

查詢合約資源資訊

返回已注册合约资源的信息。

請求網址

實時 URL https://bc-api.qpyou.cn/core/v1/contract/resource
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource
HTTP 方法 GET
內容類型 application/json

標頭參數

欄位名稱 描述 類型 必需
授權 認證令牌，呼叫 API 所需 字串 是
x-network 區塊鏈網絡 字串 是

查詢參數

欄位名稱 描述 類型 必需
resourceId 合約資源 ID 字串 否

回應

欄位名稱 描述 類型
code api 請求結果代碼，0：成功 數字
message 結果消息 字串
data API 回應數據 json
data.resourceId 合約資源 ID 數字
data.network 區塊鏈網絡 字串
data.tenantId 註冊合約資源的人的 ID 字串
data.contractName 合約名稱 字串
data.contractDesc 合約的描述 字串
data.codeId 合約代碼 ID（僅適用於 XPLA 區塊鏈） 字串
data.updatedAt 合約註冊日期 字串
data.createdAt 合約修改日期 字串

請求範例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource?resourceId=1' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb...'

回應範例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "resourceId": 1,
      "network": "polygon",
      "tenantId": "com.com2us.c2xwallet.global.normal",
      "contractName": "Com2us Sample Token Contract",
      "contractDesc": "Fungible Token Contract",
      "codeId": null,
      "updatedAt": "2023-07-27T18:05:25.000Z",
      "createdAt": "2023-07-27T18:05:25.000Z"
    }
  ]
}

修改合約資源

修改已注册的合约资源。修改合约描述（contractDesc）、字节码或ABI/方案。

請求 URL

實時 URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP 方法 PATCH
內容類型 application/json

路徑參數

欄位名稱 描述 類型 必需
resourceId 合約資源 ID 字串 Y

標頭參數

欄位名稱 描述 類型 必需
授權 認證令牌，呼叫 API 所需 字串 Y
x-network 區塊鏈網絡 字串 Y

請求主體

欄位名稱 描述 類型 必需
from 合約擁有者的地址 字串 Y
contractDesc 合約的描述 字串 N
codeId 這是合約代碼ID（僅適用於XPLA區塊鏈）。在XPLA區塊鏈上部署合約時獲得。 字串 N
contractAbi 合約編譯時生成的應用程序二進位介面。 檔案 N
contractBytecode 合約編譯時生成的位元組碼 檔案 N
Note

將合約部署交易發送到 XPLA 區塊鏈，獲取 txHash，並在 XPLA Explorer 上搜索，然後您可以在事件日誌中找到 codeId。

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果消息 字串
data API 回應數據 json
data.resourceId 合約資源 ID 數字

請求範例

curl -X 'PATCH' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/1' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNv...' 
  -H 'Content-Type: multipart/form-data' 
  -F 'from=0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0' 
  -F 'contractDesc=Fungible Token Contract' 
  -F 'codeId=20'

回應範例

{
  "code": 0,
  "message": "success",
  "data": {
    "resourceId": 1
  }
}

部署合約

創建一個交易，可以根據先前註冊的合約資源（字節碼和ABI/方案）部署新的合約。此API可以部署所有類型的合約（包括NFT和FT，即可替代代幣）。

請求 URL

實時網址 https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
沙盒網址 https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP 方法 POST
內容類型 application/json

標頭參數

欄位名稱 描述 類型 必需
Authorization 認證令牌，用於調用 API 字串 是
x-network 區塊鏈網絡 字串 是

路徑參數

欄位名稱 描述 類型 必需
resourceId 合約資源ID 字串 Y

請求主體

欄位名稱 描述 類型 必填
from 部署合約的錢包地址 字串 是
message 部署合約所需的初始配置資訊 json 是
encoded 返回的交易是否已編碼
* true: 接收編碼的原始交易字串 (data.rawTx)。
* false: 接收解碼的 data.rawTx (JSON)。		 布林值 否

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果消息 字串
data API 回應數據 json
data.rawTx 交易數據 字串或 json
data.instanceId 合約實例 ID 數字

請求範例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/2' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "message": {
    "name": "testft",
    "symbol": "tft",
    "decimals": 6,
    "initialSupply": "1000000000"
  },
  "encoded": true
}'

回應範例

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f91c9c830138811a84513619a084513619b...",
    "instanceId": 1
  }
}

獲取已部署合約資訊

返回在區塊鏈上部署的合約信息。

請求 URL

實時 URL https://bc-api.qpyou.cn/core/v1/contract/instance
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance
HTTP 方法 GET
內容類型 application/json

標頭參數

欄位名稱 描述 類型 必需
授權 調用 API 所需的身份驗證令牌 字串 是
x-network 區塊鏈網絡 字串 是

查詢參數

欄位名稱 描述 類型 必填
instanceId 合約實例 ID 字串 否

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果訊息 字串
data API 回應資料 陣列
data.resourceId 合約資源 ID 數字
data.instanceId 合約實例 ID 數字
data.contractAddress 合約地址 字串
data.initMsg 部署合約時的初始配置資訊 json
data.createdAt 合約在區塊鏈上記錄的日期 字串
data.network 區塊鏈網路資訊 字串
data.tenantId 合約部署者的 ID 字串

請求範例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance?instanceId=1' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...'

回應範例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "resourceId": 2,
      "instanceId": 1,
      "contractAddress": null,
      "initMsg": {
        "name": "testft",
        "symbol": "tft",
        "decimals": 6,
        "initialSupply": "1000000000"
      },
      "createdAt": "2023-07-28T17:35:22.000Z",
      "network": "polygon",
      "tenantId": "com.com2us.c2xwallet.global.normal"
    }
  ]
}

修改合約實例地址

使用合約實例 ID (instanceId) 更新已部署的合約地址。

請求 URL

實時 URL https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
HTTP 方法 PATCH
內容類型 application/json

路徑參數

欄位名稱 描述 類型 必需
instanceId 合約實例 ID 字串 Y

標頭參數

欄位名稱 描述 類型 必填
授權 呼叫 API 所需的身份驗證令牌 字串 是
x-network 區塊鏈網絡 字串 是

查詢參數

欄位名稱 描述 類型 必需
contractAddress 合約地址 字串 Y

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果消息 字串

請求範例

curl -X 'PATCH' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/1?contractAddress=0x78ce8698bd69fc96d425a82ae6813f553a673e63' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJp...'

回應範例

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

查詢合約方法列表

根據合約資源 ID (resourceId) 返回合約方法的列表。

請求網址

實時 URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/methods
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/methods
HTTP 方法 GET
內容類型 application/json

路徑參數

欄位名稱 描述 類型 必需
resourceId 合約資源ID 字串 Y

標頭參數

欄位名稱 描述 類型 必需
Authorization 認證令牌，用於調用API 字串 是
x-network 區塊鏈網絡 字串 是

回應

欄位名稱 描述 類型
code api 請求結果代碼，0: 成功 數字
message 結果消息 字串
data API 回應數據 陣列
data.methodName 合約方法名稱 字串
data.type 合約方法類型
* execute: 將數據插入合約或修改合約中的現有數據
* query: 獲取合約信息		 字串

請求範例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/1/methods' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...'

回應範例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "methodName": "allowance",
      "type": "query"
    },
    {
      "methodName": "totalSupply",
      "type": "query"
    },
    ...
  ]
}

獲取合約方法資訊

返回執行合約方法所需的函數簽名，包含合約資源 ID（resourceId）和方法名稱（method）。

請求 URL

實時 URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/method/{method}
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/method/{method}
HTTP 方法 GET
內容類型 application/json

路徑參數

欄位名稱 描述 類型 必需
resourceId 合約資源 ID 字串 是
method 合約方法名稱 字串 是

標頭參數

欄位名稱 描述 類型 必需
授權 認證令牌，用於調用API 字串 是
x-network 區塊鏈網絡 字串 是

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果消息 字串
data 這是執行合約方法所需的數據（方法名稱和方法的輸入參數）。 json

請求範例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/2/method/balanceOf' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...'

回應範例

{
  "code": 0,
  "message": "success",
  "data": {
    "balanceOf": {
      "account": "address"
    }
  }
}

執行合約方法

執行合約方法，使用方法名稱和方法的輸入參數（message）。

請求 URL

實時 URL https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
沙盒 URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
HTTP 方法 POST
內容類型 application/json

路徑參數

欄位名稱 描述 類型 必填
instanceId 合約實例 ID 字串 Y

標頭參數

欄位名稱 描述 類型 必需
授權 認證令牌，呼叫 API 所需 字串 Y
x-network 區塊鏈網絡 字串 Y

請求主體

欄位名稱 描述 類型 必需
from 請求執行合約方法的錢包地址 字串 Y
message 合約方法名稱及方法的輸入參數 字串 Y
encoded 返回的交易是否已編碼
* true: 接收編碼的原始交易字串 (data.rawTx)。
* false: 接收解碼的 data.rawTx (JSON)。		 布林值 N

回應

欄位名稱 描述 類型
code API 請求結果代碼，0：成功 數字
message 結果消息 字串
data 執行合約方法後返回的值 json

請求範例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/1/query' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb2...' 
  -H 'Content-Type: application/json' 
  -d '{
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "message": {
    "balanceOf": {
      "account": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0"
    }
  },
  "encoded": true
}'

一般來說，合約方法分為兩種類型：查詢類型和執行類型。查詢類型方法僅查詢數據，而執行類型方法則在合約中寫入新數據或修改合約中的現有數據。執行類型始終返回原始交易，而不是像查詢類型那樣。

回應範例：查詢類型

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

回應範例：執行類型（encoded 為 true）

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8738301388181c2846fc23ac0846fc23ad882cdc49494853bdc9c6add50d7...",
  }
}

回應範例：執行類型（encoded 為 false）

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
      "to": "0x94853BdC9c6AdD50D7842D1A3117fab385457470",
      "data": "0xa9059cbb000000000000000000000000fbd488d1b00604d3b05124d80e35fea...",
      "nonce": 224,
      "chainId": 80001,
      "gas": 52676,
      "maxFeePerGas": 1575000048,
      "maxPriorityFeePerGas": 1575000000
    }
  }
}