Skip to content

Contract API

Contract API offers the following features.

  • Register, query, and modify contract resources
  • Deploy, query, modify contract and execute contract methods

Pre-requisites: Get API authentication token

To call a Contract API, you have to append an auth token to the header of an API. This is how to get your API auth token.

  1. Sign up at the Hive Console, go to AppCenter > Game List > Register new game.
  2. Create an new AppID at AppCenter > AppID List > Register new AppID.
    • Register new AppID: Web Login AppID
    • Purpose of use: Blockchain
    • AppID to use:Choose “automatically generated AppID” or “automatically generated AppID” with “Additional Information”
  3. Go to the the Hive Console > Blockchain > Search for API Authentication Key, select and search the game name, and get the ID and the Secret key.
  4. Insert the ID and the Secret key in the request body of auth-token APIand call this API.
  5. You can get your API auth key as data.accessToken in the API responses.

Register contract resources

Registers the resources of a contract. Register the contract name (contractName), the contract description (contractDesc), and the bytecode and ABI/Scheme generated after the contract is compiled.

Note
  • The contract resources are not recorded on a blockchain.
  • The contract must be written in Solidity or Rust.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource
HTTP Method POST
Content-Type application/json

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Request body

Field Name Description Type Required
from the address of the contract owner string Y
contractName the contract name string Y
contractDesc the description for the contract string Y
contractAbi the application binary interface that is generated when the contract is compiled. file Y
contractBytecode the byte code that is generated when the contract is compiled file Y

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data API response data json
data.resourceId the contract resource ID number

Request sample

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'

Response sample

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

Query contract resource information

Returns the information of the registered contract resources.

Request URL

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

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Query parameters

Field Name Description Type Required
resourceId the contract resource ID string N

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data API response data json
data.resourceId the contract resource ID number
data.network the blockchain network string
data.tenantId the ID of the one who registered the contract resource string
data.contractName the contract name string
data.contractDesc the description for the contract string
data.codeId the contract code ID (only for XPLA blockchain) string
data.updatedAt the date the contract was registered string
data.createdAt the date the contract was modified string

Request sample

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

Response sample

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

Modify contract resources

Modifies the registered contract resources. Modifies the contract description (contractDesc), the bytecode, or the ABI/Scheme.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP Method PATCH
Content-Type application/json

Path parameters

Field Name Description Type Required
resourceId the contract resource ID string Y

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Request body

Field Name Description Type Required
from the address of the contract owner string Y
contractDesc the description for the contract string N
codeId This is the contract code ID (only for XPLA blockchain). It is obtained when you deploy a contract on the XPLA blockchain. string N
contractAbi the application binary interface that is generated when the contract is compiled. file N
contractBytecode the byte code that is generated when the contract is compiled file N
Note

Send the contract deploying transaction to XPLA blockchain, get txHash, and search it on the XPLA Explorer, and then you can find codeId at the Event Logs.

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data API response data json
data.resourceId the contract resource ID number

Request sample

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'

Response sample

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

Deploy contract

Creates a transaction that can deploy a new contract based on the previously registered contract resources (the bytecode and ABI/Scheme). This API can deploy all types (including NFT and FT, the Fungible Token) of contract.

Request URL

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

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Path parameters

Field Name Description Type Required
resourceId the contract resource ID string Y

Request body

Field Name Description Type Required
from the wallet address that deploys the contract string Y
message the initial configuration information that is required to deploy the contract json Y
encoded whether the returned transaction is encoded or not
* true: Receive the encoded raw transaction string (data.rawTx).
* false: Receive the decoded data.rawTx (JSON).		 boolean N

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data API response data json
data.rawTx the transaction data string or json
data.instanceId the contract instance ID number

Request sample

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

Response sample

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

Get deployed contract information

Returns the contract information deployed on a blockchain.

Request URL

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

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Query parameters

Field Name Description Type Required
instanceId the contract instance ID string N

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data API response data array
data.resourceId the contract resource ID number
data.instanceId the contract instance ID number
data.contractAddress the contract address string
data.initMsg the initial configuration information when deploying the contract json
data.createdAt the date when the contract was recorded on a blockchain string
data.network the blockchain network information string
data.tenantId the ID of the contract deployer string

Request sample

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

Response sample

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

Modify contract instance address

Update the deployed contract address with the contract instance ID (instanceId).

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
HTTP Method PATCH
Content-Type application/json

Path parameters

Field Name Description Type Required
instanceId the contract instance ID string Y

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Query parameters

Field Name Description Type Required
contractAddress the contract address string Y

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message string

Request sample

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

Response sample

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

Query contract method list

Returns the list of the contract methods by the contract resource ID (resourceId).

Request URL

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

Path parameters

Field Name Description Type Required
resourceId the contract resource ID string Y

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data API response data array
data.methodName the contract method name string
data.type the contract method type
* execute: insert data into the contract or modify the existing data in the contract
* query: Get Contract Information		 string

Request sample

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

Response sample

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

Get contract method information

Returns the function signature required to execute contract methods with the contract resource ID (resourceId) and the method name (method).

Request URL

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

Path parameters

Field Name Description Type Required
resourceId the contract resource ID string Y
method the contract method name string Y

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data This is the data required to execute contract methods (the method name and the input parameters of the method). json

Request sample

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

Response sample

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

Execute contract method

Executes the contract method with the method name and the input parameters (message) of the method.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
HTTP Method POST
Content-Type application/json

Path parameters

Field Name Description Type Required
instanceId the contract instance ID string Y

Header parameters

Field Name Description Type Required
Authorization The authentication token required to call APIs string Y
x-network the blockchain networks string Y

Request body

Field Name Description Type Required
from the wallet address that requests executing the contract method string Y
message the contract method name and the input parameters of the method string Y
encoded whether the returned transaction is encoded or not
* true: Receive the encoded raw transaction string (data.rawTx).
* false: Receive the decoded data.rawTx (JSON).		 boolean N

Responses

Field Name Description Type
code api request result code, 0: success number
message the result message String
data the returned value after executing the contract method json

Request sample

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

In general the contract methods are divided into 2 types: the query type and the execute type. The query type method just queries the data, and the execute type method writes new data in the contract or modifies the existing data in the contract. The execute type always returns the raw transaction, not like the query type.  

Response sample: Query type

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

Response sample: Execute type (encoded is true)

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

Response sample: Execute type (encoded is false)

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