合约 API

合同API提供以下功能。

注册、查询和修改合同资源
部署、查询、修改合同和执行合同方法

前提条件：获取 API 认证令牌¶

要调用合同 API，您必须将身份验证令牌附加到 API 的头部。这是获取您的 API 身份验证令牌的方法。

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

注册合同资源¶

注册合约的资源。注册合约名称（contractName）、合约描述（contractDesc）以及合约编译后生成的字节码和ABI/方案。

Note

合同资源未记录在区块链上。
合同必须用Solidity或Rust编写。

请求 URL¶

直播网址	https://bc-api.qpyou.cn/core/v1/contract/resource
沙盒网址	https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource
HTTP 方法	POST
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
授权	调用API所需的身份验证令牌	字符串	是
x-network	区块链网络	字符串	是

请求体¶

字段名称	描述	类型	必需
from	合约拥有者的地址	字符串	是
contractName	合约名称	字符串	是
contractDesc	合约的描述	字符串	是
contractAbi	合约编译时生成的应用程序二进制接口。	文件	是
contractBytecode	合约编译时生成的字节码	文件	是

响应¶

字段名称	描述	类型
code	api 请求结果代码，0：成功	number
message	结果消息	String
data	API 响应数据	json
data.resourceId	合同资源 ID	number

请求示例¶

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¶

直播 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

头部参数¶

字段名称	描述	类型	必需
Authorization	调用 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所需的身份验证令牌	字符串	是
x-network	区块链网络	字符串	是

请求体¶

字段名称	描述	类型	必需
from	合约拥有者的地址	字符串	是
contractDesc	合约的描述	字符串	否
codeId	这是合约代码ID（仅适用于XPLA区块链）。在XPLA区块链上部署合约时获得。	字符串	否
contractAbi	合约编译时生成的应用程序二进制接口。	文件	否
contractBytecode	合约编译时生成的字节码	文件	否

Note

将合约部署交易发送到 XPLA 区块链，获取 txHash，并在 XPLA Explorer 上搜索，然后您可以在事件日志中找到 codeId。

回复¶

字段名称	描述	类型
code	api 请求结果代码，0：成功	number
message	结果消息	String
data	API 响应数据	json
data.resourceId	合同资源 ID	number

请求示例¶

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¶

直播 URL	https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
沙盒 URL	https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP 方法	POST
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
Authorization	调用API所需的身份验证令牌	字符串	是
x-network	区块链网络	字符串	是

路径参数¶

字段名称	描述	类型	必需
resourceId	合同资源ID	字符串	是

请求体¶

字段名称	描述	类型	必需
from	部署合约的钱包地址	字符串	是
message	部署合约所需的初始配置信息	json	是
encoded	返回的交易是否被编码 * `true`: 接收编码的原始交易字符串（`data.rawTx`）。 * `false`: 接收解码的 `data.rawTx`（JSON）。	布尔值	否

响应¶

字段名称	描述	类型
code	api 请求结果代码，0：成功	number
message	结果消息	String
data	API 响应数据	json
data.rawTx	交易数据	string 或 json
data.instanceId	合约实例 ID	number

请求示例¶

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¶

直播网址	https://bc-api.qpyou.cn/core/v1/contract/instance
沙盒网址	https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance
HTTP 方法	GET
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
授权	调用API所需的身份验证令牌	字符串	是
x-network	区块链网络	字符串	是

查询参数¶

字段名称	描述	类型	必需
instanceId	合同实例ID	字符串	否

响应¶

字段名称	描述	类型
code	API请求结果代码，0：成功	number
message	结果消息	String
data	API响应数据	array
data.resourceId	合同资源ID	number
data.instanceId	合同实例ID	number
data.contractAddress	合同地址	string
data.initMsg	部署合同时的初始配置信息	json
data.createdAt	合同在区块链上记录的日期	string
data.network	区块链网络信息	string
data.tenantId	合同部署者的ID	string

请求示例¶

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¶

直播 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	字符串	是

头部参数¶

字段名称	描述	类型	必需
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	合同方法名称	字符串	是

头部参数¶

字段名称	描述	类型	必需
Authorization	调用API所需的身份验证令牌	字符串	是
x-network	区块链网络	字符串	是

响应¶

字段名称	描述	类型
code	API请求结果代码，0：成功	number
message	结果消息	String
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	字符串	是

头部参数¶

字段名称	描述	类型	必需
Authorization	调用 API 所需的身份验证令牌	字符串	是
x-network	区块链网络	字符串	是

请求体¶

字段名称	描述	类型	是否必需
from	请求执行合约方法的钱包地址	字符串	是
message	合约方法名称及其输入参数	字符串	是
encoded	返回的交易是否编码 * `true`: 接收编码的原始交易字符串 (`data.rawTx`). * `false`: 接收解码的 `data.rawTx` (JSON).	布尔值	否

响应¶

字段名称	描述	类型
code	api 请求结果代码，0：成功	number
message	结果消息	String
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
    }
  }
}

合约 API

前提条件：获取 API 认证令牌¶

注册合同资源¶

请求 URL¶

头部参数¶

请求体¶

响应¶

请求示例¶

响应示例¶

查询合同资源信息¶

请求 URL¶

头部参数¶

查询参数¶

响应¶

请求示例¶

响应示例¶

修改合同资源¶

请求 URL¶

路径参数¶

头部参数¶

请求体¶

回复¶

请求示例¶

响应示例¶

部署合同¶

请求 URL¶

头部参数¶

路径参数¶

请求体¶

响应¶

请求示例¶

响应示例¶

获取已部署合约信息¶

请求 URL¶

头部参数¶

查询参数¶

响应¶

请求示例¶

响应示例¶

修改合约实例地址¶

请求 URL¶

路径参数¶

头部参数¶

查询参数¶

响应¶

请求示例¶

响应示例¶

查询合约方法列表¶

请求 URL¶

路径参数¶

头部参数¶

回复¶

请求示例¶

响应示例¶

获取合同方法信息¶

请求 URL¶

路径参数¶

头部参数¶

响应¶

请求示例¶

响应示例¶

执行合约方法¶

请求 URL¶

路径参数¶

头部参数¶

请求体¶

响应¶

请求示例¶

响应示例：查询类型¶

响应示例：执行类型（encoded 为 true）¶

响应示例：执行类型（encoded 为 false）¶

响应示例：执行类型（`encoded` 为 `true`）¶

响应示例：执行类型（`encoded` 为 `false`）¶