通用说明

XUPERASSET API调用遵循HTTP协议。

• 环境域名为 https://xuper.baidu.com

注意：

1. 用于接入的 AK/SK 在 XUPERASSET 的控制台申请准入后获取

2. SK是该APP准入认证密钥，妥善保管，不能泄露。

3. 应用场景接口需要联系平台申请授权才可用，需注意用户也可以取消自己的地址对外使用。

4. 接入环境域名后没有“/” 如添加会返回权限错误

5. 开通“商品登记”服务自动扣费后，平台将赠送20次量包额度，用于接入正式业务前测试开发，如果需要更多的测试次数请联系我们获取

6. 量包额度的扣减具有2分钟左右的延迟，量包用尽后将会自动按次扣费，请留意剩余量包额度

所有request/response body内容均采用UTF-8编码。

SDK下载

目前可提供Golang、JAVA、PHP、Python sdk，具体SDK使用，请参考对应SDK README文件。

SDK完整封装了准入鉴权、账户私钥签名等操作，只需要正确配置SDK，即可直接使用。SDK配置参见各SDK Readme 文件。

1. GO: https://github.com/xuperchain/xasset-sdk-go
2. JAVA: https://github.com/xuperchain/xasset-sdk-java
3. PHP:https://github.com/xuperchain/xasset-sdk-php
4. Python:https://github.com/xuperchain/xasset-sdk-python

实名认证

使用XUPERASSET API的用户需要实名认证，没有通过实名认证的可以前往百度智能云官网控制台中的安全认证下的实名认证中进行认证。没有通过实名认证的用户将无法使用接口XuperAsset

API认证机制

所有API的安全认证一律采用AccessKey与请求签名机制。 Access Key由AccessKey ID和Secret Access Key组成，均为字符串。 对于每个HTTP请求，使用下面所描述算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。认证字符串的格式为

bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}。

• version是正整数。
• timestamp是生成签名时的UTC时间。
• expirationPeriodInSeconds表示签名有效期限。
• signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号（;）分隔，如host;x-bce-date。列表按照字典序排列。（本API签名仅使用host和x-bce-date两个header）
• signature是256位签名的十六进制表示，由64个小写字母组成。 当百度智能云接收到用户的请求后，系统将使用相同的SK和同样的认证机制生成认证字符串，并与用户请求中包含的认证字符串进行比对。如果认证字符串相同，系统认为用户拥有指定的操作权限，并执行相关操作；如果认证字符串不同，系统将忽略该操作并返回错误码。

鉴权认证机制的详细内容请参见鉴权认证。

签名算法复杂，建议直接使用xasset-sdk，不要自己封装，签名需要的AK\SK 通过智能云平台申请获取

通信协议

为了保证数据的安全性，所有接口调用使用HTTPS调用

请求结构说明

• 请求数据request格式为application/x-www-form-urlencoded
• 所有request body内容均采用UTF-8编码
• 所有请求必须在Header中携带以下参数，用于准入鉴权认证

响应结构说明

• 请求数据request格式为application/json
• 所有response body内容均采用UTF-8编码 除非特别说明，所有相应均返回以下应答

幂等性

当调用创建接口时如果遇到了请求超时或服务器内部错误，用户可能会尝试重发使用相同的参数重试调用。

如果需要重复参数调用相同接口，如前一次调用未成功，或者成功未上链，此次调用依然会成功。如果前一次调用上链成功，此次调用会因为双花问题调用失败。

区块链非对称加密算法

上链操作需要用区块链账户私钥对相关内容做签名，确保该操作是由拥有私钥的账户发起。

签名步骤：

1. 对待签名内容sha256后再使用账户私钥进行签名：
2. 使用十六进制将签名结果转成字符串：

签名方法示例：

func XassetSignECDSA(account, msg) （string, error)
{
    1. 对待签名内容做SHA256。
    2. 使用账户ECC私钥做签名。
    3. 对签名转化为16进制字符串返回。
}

SDK都提供了相关的封装，强烈建议直接使用SDK。

浏览器

https://xuper.baidu.com/n/scan

• 可以通过上链交易的txid查询上链交易信息。
• 可以通过asset_id查询资产登记记录。
• 可以通过区块链地址查询用户持有资产信息。查询格式为：address#app_id#1

建议业务产品暴露 区块链地址、asset_id和txid，供用户复制查验。

创建区块链账户

区块链账户是区块链世界里面的身份，通过算法自动生成，一个账户的组成包括：公钥、私钥、助记词、区块链地址。其中：

• 区块链地址相当于账户名
• 公钥负责进行签名验证
• 私钥负责对信息进行签名加密
• 助记词负责恢复丢失的账号

在区块链世界中的重要消息都需要使用账户私钥进行签名，同时搭配公钥验证进行操作、信息内容确权。强烈建议保存账号助记词，重新恢复丢失用户信息，避免用户资产损失。

B端业务平台铸造资产账户，使用完全去中心化的链上账户，确保B端业务平台利益。可信登记SaaS提供的大部分API都是由铸造账户做签名的。

去中心化链上账户创建方法：参考下列示例代码中生成账户的方法

• JAVA: https://github.com/xuperchain/xasset-sdk-java/blob/main/src/main/java/com/baidu/xasset/auth/XchainAccount.java
• Golang: https://github.com/xuperchain/xasset-sdk-go/blob/main/auth/account.go
• PHP: https://github.com/xuperchain/xasset-sdk-php/blob/main/auth/Account.php
• Python：https://github.com/xuperchain/xasset-sdk-python/blob/main/xasset/auth/account.py

注意：

1. 区块链钱包账户是完全去中心化的，无法更换和废弃私钥，切记要安全管理账户助记词和私钥，一旦泄露，相当于银行卡和密码同时泄露。
2. 所有数字商品可信登记平台上使用的区块链账户均使用上述去中心化链上账户创建方法 CreateAccount 方法生成 其他方法生成的账户无法通过鉴权
3. 所有的创建的账户信息都需要保存，如果账户信息丢失，如保存了助记词可以参考下边的通过助记词恢复账户。如助记词也没保存此账号将永久丢失
4. 用户创建的账户,如果后续使用此账户进行创建藏品，那么此账号将有类似此藏品“管理员”的作用，后续对碎片和资产的操作都会用到此账户
5. 授予碎片的账户用同样的方法生成

通过助记词恢复链上账户：参考示例代码中恢复账户的方法

• JAVA: https://github.com/xuperchain/xasset-sdk-java/blob/main/src/main/java/com/baidu/xasset/auth/XchainAccount.java
• Golang: https://github.com/xuperchain/xasset-sdk-go/blob/main/auth/account.go
• PHP: https://github.com/xuperchain/xasset-sdk-php/blob/main/auth/Account.php
• Python：https://github.com/xuperchain/xasset-sdk-python/blob/main/xasset/auth/account.py

注意：

使用此方法可以恢复账户的完成Account对象，包含区块链地址，公钥，私钥等所有敏感信息，请注意安全使用