合约 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
头部参数
请求体
响应
请求示例
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
头部参数
查询参数
响应
请求示例
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
路径参数
头部参数
请求体
Note
将合约部署交易发送到 XPLA 区块链，获取 txHash，并在 XPLA Explorer 上搜索，然后您可以在事件日志中找到 codeId。
回复
请求示例
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
头部参数
路径参数
请求体
响应
请求示例
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
头部参数
查询参数
响应
请求示例
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
路径参数
头部参数
查询参数
响应
请求示例
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
路径参数
头部参数
回复
请求示例
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
路径参数
头部参数
响应
请求示例
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
路径参数
头部参数
请求体
响应
请求示例
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
}
}
}