HackMD
Open API 教程与最佳实践
1. 准备工作
1.1 注册
在使用 open API 前，首先需要在金色传说（主网环境：https://v.mibao.net/ ，测试网环境：https://staging.nervina.cn ）上进行注册，该帐号将会成为通过 open API 设计和发行秘宝的创作者，相关数据可以通过在金色传说平台登录该帐号进行查看。
-
正式环境请求地址为：https://goldenlegend.nervina.cn/api/v1/
-
创作者平台正式环境：https://v.mibao.net/
-
创作者平台测试环境：https://staging.nervina.cn
-
秘宝账户正式环境：https://mibao.net/explore
-
秘宝账户测试环境：https://wallet.staging.nervina.cn
1.2 设置公开信息
完成注册后，必须首先设置创作者（issuer）公开信息才可以进行后续操作。这里设置的公开信息会在链上公开存储，上链操作由金色传说平台自动完成，设计和发行秘宝均置后于该步骤，因此注册后必须执行此操作。
1.3 申请 open API 的 key 和 secret
open API 的鉴权需要响应的 key-secret，在完成上述两步操作之后，可以发送邮件到 biz@nervina.io 进行申请，内容必须包含要申请 key-secret 的帐号的注册邮箱。
1.4 能量点充值
在金色传说平台设计和分发秘宝都需要消耗能量点（设计秘宝消耗 1 能量点；每分发一个秘宝消耗 1 能量点）；在进行创作和发行前需要进行能量点充值。
完成上述操作后，即可通过 open API 在金色传说平台进行操作。
2. 开放 API 签名算法
为了保证安全性，用户在 HTTP 请求中增加 Authorization 的 Header 来包含签名信息，表明这个消息已被授权。
2.1 Authorization 字段计算的方法
AccessKeyId即为通过邮件申请获取到的 open API 的 keyAccessKeySecret即为通过邮件申请获取到的 open API 的 secretVERB表示请求的 method，包括 GET、POST、PUT 等\n表示换行符FULLPATH表示请求的 endpoint，如果有 query-string，也需要包含在内Content-MD5表示请求内容数据的 MD5 值，对消息内容（不包括头部）计算 MD5 值获得 128 比特位数字，然后对该数字进行 base64 编码即可得到。该请求头可用于消息合法性的检查（消息内容是否与发送时一致）；当正文为空时，Content-MD5 留空即可。详情可参看 RFC2616 Content-MD5Content-Type表示请求内容的类型，如application/json，也可以为空Date表示此次操作的时间，必须为 GMT 格式，如Sun, 22 Nov 2015 08:16:38 GMT
上述 headers 中，Date、Content-Type和Authorization为必须包含的字段，且Date中的时间和金色传说服务器的时间相差不能超过 10 分钟，否则金色传说服务器将拒绝该请求，并返回 401 错误。
在计算签名时， Content-Type 和 Content-MD5 可以为空字符，但不能省略。
2.2 计算规则
- 签名的字符串必须为
UTF-8格式，含有中文字符的签名字符串必须先进行UTF-8编码，再进行后续计算。 - 签名的方法为 RFC 2014 中定义的
HMAC-SHA1方法，其中 key 为AccessKeySecret Content-Type和Content-MD5在请求中不是必须的，如果为空时，留空即可
2.3 Python 代码示例
Python 版本为 3.9.1。示例中， AccessKeyId = '44CF9590006BF252F707' ， AccessKeySecret = 'OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV'
Python 代码如下：
得到 auth 后，最终的请求为：
2.4 常见错误
- 请求的 Header 中缺少
Content-Type、Date或Authorization，返回Missing Content-Type/Date/Authorization in header - 请求中使用了错误的 key，返回
Cannot find access key - 请求计算签名使用了错误的 secret 或者计算签名有误，返回
Signature mismatch，并返回string_to_sign，为该请求用来计算签名的 message，方便排查计算签名遇到的问题 - 请求 header 中的
Authorization格式应为NFT key:signature，格式错误时返回Cannot find access key - 请求中的时间与服务器时间相差超过 10 分钟，返回
Time expired
3. 术语说明
token_class: 可以理解为秘宝的模具，包含秘宝的基本信息，将会在链上存储；一个秘宝必须先被设计出秘宝模具，通过秘宝模具才能进行铸造和分发。uuid: 为了方便使用而被创建出来的一种 id，其中包括：token_class_uuid: 关联到对应的token_classtoken_uuid: 关联到具体的 NFT Tokentx_uuid: 关联分发和转让的交易
address: ckb 地址nft_type_args: NFT Token Cell 的 Type Script 中的args字段
4. 设计秘宝、铸造和分发秘宝
相关代码可以参考： https://github.com/nervina-labs/nft_open_api_demo_python
4.1 设计秘宝
设计秘宝必须包含以下字段：
- name: 秘宝的名称，不超过 30 个字符（一旦创建，不可修改）
- description: 秘宝的简介，不超过 200 个字符（一旦创建，不可修改）
- total: string 类型的非负整数，为 0 时，表示秘宝不限量；大于 0 时，表示秘宝限量的数量（一旦创建，不可修改）
- renderer: 秘宝的媒体信息，必须为以
https://开头、媒体信息有效的 url，且不超过 255 字符（秘宝设计完成后，30 天内可修改一次 renderer）- renderer 为图片：支持格式为 png, jpg, jpeg, gif, webp 和 svg 6 种格式，必须以
https://开头，且结尾为png | jpg | jpeg | gif | webp | svg。 - renderer 为视频或 3D：支持格式为 mp4, webm, glb 和 gltf 6 种格式，必须以
https://开头，且结尾为mp3 | wav | mp4 | webm | glb | gltf。当 renderer 为音视频或 3D 时，同时需要传入参数cover_image_url用于设置 NFT 封面，校验规则与图片格式的 renderer 一致。 - 设计的秘宝 token class 会上链，上链操作由平台完成。
- renderer 为图片：支持格式为 png, jpg, jpeg, gif, webp 和 svg 6 种格式，必须以
代码示例：
返回：
其中， uuid 为平台生成的唯一标识 token class id
- 在设计秘宝时提供可选参数
configure，用于设置 NFT class cell 的configure，金色传说平台默认设置为11000000， 相关信息可参考：https://talk.nervos.org/t/rfc-multi-purpose-nft-draft-spec/5434。configure格式应为类似11000000的 8 位二进制字符串，否则会返回configure field format error
请求示例：
4.1.1 创建音频类型秘宝
秘宝创作者平台支持以专辑的形式创建音频类型秘宝，每个音频类型秘宝支持上传设置 10 首单曲。同时创作者可以自定义设置仅持有人可以播放或所有人都可以播放。
创建音频类型秘宝时，除了创建秘宝时需要传入的必要参数外，还需要传入以下参数：
renderer: 音频类型的renderer必须为图片，支持 png, jpg, jpeg, gif, webp 和 svg 6 种格式；album_attributes: 是一个 json object，用于设置音频内容，包括：album_attributes.is_private:true表示仅持有人才可以播放音频内容；false表示所有人可以播放音频内容；album_attributes.audios_attributes: json array，用于设置音频内容，最多支持设置 10 首音频，音频仅支持mp3格式；
请求示例：
返回示例:
- 已创建的音频秘宝，
renderer及album_attributes支持修改，但 30 天内仅限修改一次
4.2 查询 token class
相关文档：GET /token_classes/{uuid}
查询字段：
uuid: 在创建 token class 时返回的 uuid
代码示例：
返回：
4.3 查询金色传说账户下所有的 token class
相关文档：GET /token_classes
代码示例：
返回：
4.4 铸造并分发秘宝
相关文档：POST /token_classes/{token_class_uuid}/tokens
查询字段：
-
token_class_uuid: 设计秘宝时返回的 token class uuid
请求字段： -
addresses: 一个由 ckb 地址组成的列表
代码示例：
返回：
其中， uuid 是具体的 NFT token id
- 铸造并分发秘宝时可以通过传入可选参数
characteristic来为 token 设置不同的characteristic，默认为0000000000000000，characteristic相关信息可以参考：https://talk.nervos.org/t/rfc-multi-purpose-nft-draft-spec/5434 。characteristic参数格式应为类似'0123456789abcdef'的十六位十六进制字符串，否则会返回the characteristic of token is invalid错误。如果在一次请求中分发了多个 token，则每个 token 的characteristic均为传入参数设置的值。请求示例如下：
每个 token 的 characteristic 可以在分发的返回或 token 相关查询接口的返回中获取。
4.5 查询 NFT token
查询参数：
token_uuid: 铸造并分发秘宝时返回的 token uuid
代码示例：
返回：
4.6 根据 token id 查询持有者地址
相关文档：GET /tokens/{token_uuid}/address
查询参数：
token_uuid: 铸造并分发后返回的 token uuid
代码示例：
返回：
5. NFT 持有者相关查询
5.1 查询地址所持有的 NFT
相关文档：GET /indexer/holder_tokens/{address}
查询参数：
address: 要查询的 ckb 地址
代码示例：
返回：
5.2 查询 nft type args 对应的 token
相关文档：GET /indexer/tokens/{nft_type_args}
查询参数：
nft_type_args: 在对应的 CKB Cell 的 Type Script 中的 args
代码示例：
返回：
5.3 查询 token class 对应的 token
相关文档：GET /indexer/token_classes/{token_class_uuid}/tokens
查询参数：
holder_address: 查询某个地址是否持有该 token class 中的 tokenlimit: 可选参数，分页参数，单次查询返回 token 列表的数量，最大为 20，page: 可选参数，分页参数，指定查询返回的 token 范围
代码实例：
返回：
6. 转让交易
创作者完成铸造和分发秘宝之后，持有者可以通过自己的密钥签名发起转让交易。
此处要求应用的开发人员自己使用 CKB 的 SDK 来生成地址，并在自己的系统中存储公私钥（金色传说平台不涉及持有人的密钥管理），并使用密钥在转账交易中进行签名。
6.1 生成转让交易
相关文档：GET /tx/token_transfers/new
查询参数：
from_address: token 持有者的地址，同时也是需要对生成交易签名的私钥持有者to_address: 转让交易的目标地址，一旦转让，交易无法撤回token_uuid: 要转让 token 的 uuidnft_type_args: token 对应 cell 的 type script args
注意：token_uuid和nft_type_args两者必须满足有且仅有一个
代码示例：
返回：
6.2 对签名后的交易发送上链
查询参数：
from_address: NFT token 持有者地址，也是需要对交易签名的私钥持有者to_address: 转让交易的目标地址token_uuid: token 在金色传说平台对应的唯一 uuid（可选参数）nft_type_args: token 对应 cell 的 type script args（可选参数）signed_tx: 签名完成的交易字符串
注意：token_uuid和nft_type_args两个参数中至少需要一个，同时传入时会接受token_uuid进行后续操作
代码示例：
返回：
返回的 tx_hash 为该交易在链上的交易哈希，可在浏览器对应查看； uuid 即为该交易在金色传说平台对应的交易 id，通过其他接口可查询交易状态。
6.3 查询交易状态
相关文档：GET /tx/token_transfers/{uuid}
查询参数：
uuid: 交易的 tx uuid
代码示例：
返回：
7. Multi-Issuers
创作者默认对应一个 issuer，该 issuer 的信息即为用户在秘宝创作平台设置的公开信息。
Open API 允许一个帐号创建多个 issuer，不同 issuer 之间相互独立，即每个 issuer 有独立的 key-secret，可以单独设置创作者信息，以及设计和发行秘宝。
对拥有 multi-Issuers 权限的帐号，我们可以称该帐号对应的 API key 为 master_key，由其创建的 issuer 对应的 API key 为 issuer_key。对于原有接口，只有 master_key 可以正常请求使用；issuer_key 仅有权限进行设计秘宝、铸造和发行秘宝及其对应的查询请求。
注：如需使用该功能，需要单独申请 multi-Issuers 功能权限。用户可以发送邮件到 biz@nervina.io 进行申请，内容必须包含要申请开通 multi-Issuers 权限的帐号邮箱地址。
7.1 Issuers 管理
master_key 可以对其创建的所有 issuers 进行管理，issuer_key 无此权限。
7.1.1 获取全部 issuers 列表
master_key 可以查询该帐号下所有的 issuer 信息。
API 文档：GET /issuers
代码示例：
返回示例：
7.1.2 创建新的 issuer
master_key 可以创建新的 issuer。
API 文档：POST /issuers
必要参数：
-
name: 新创建的 issuer name，最多 30 个字符
可选参数： -
avatar_url：创作者头像图片链接，最多 255 个字符，必须以 https:// 开头，以 png, jpg, jpeg, gif, webp, svg 这六种文件格式之一为后缀结尾 -
website：创作者官网地址，最多 200 个字符 -
description: 创作者简介，最多 200 个字符 -
email：创作者邮箱地址，最多 100 个字符 -
weibo：创作者社交媒体链接，最多 200 个字符
代码示例：
返回示例：
返回信息中的 uuid 为该 issuer 对应的 uuid，api_token.access_key ， api_token.secret 即为该 issuer 进行设计和发行秘宝时的 key-secret， api_token.refresh_token 为 issuer 更新 key-secret 时需要的参数（后边相关 API 会详细介绍）。
api_token 相关信息仅在创建时返回一次，请谨慎保管。
7.1.3 更新 issuer 信息
master_key 可以更新已有 issuer 的相关信息。
API 文档：PUT /issuers/{issuer_uuid}
必要参数：
-
name: issuer name，最多 30 个字符
可选参数： -
avatar_url：创作者头像图片链接，最多 255 个字符，必须以 https:// 开头，以 png, jpg, jpeg, gif, webp, svg 这六种文件格式之一为后缀结尾 -
website：创作者官网地址，最多 200 个字符 -
description: 创作者简介，最多 200 个字符 -
email：创作者邮箱地址，最多 100 个字符 -
weibo：创作者社交媒体链接，最多 200 个字符
代码示例：
返回示例：
7.1.4 获取指定 issuer 信息
master_key 可以获取指定 issuer 信息。
API 文档：GET /issuers/{issuer_uuid}
代码实例：
返回实例：
7.1.5 更新指定 issuer 的 key/secret/refresh_token
master 可以更新所有 issuer 的 key-secret；issuer 可以更新自己的 key-secret。
API 文档：POST /issuers/{issuer_uuid}/api_tokens
参数：
refresh_token: 使用 master 请求 refresh token 时，该参数可以忽略；使用 issuer 请求时，该参数为必须参数
代码实例：
返回实例：
返回中的 access_key , secret 和 refresh_token 为新的 key-secret ，仅返回一次，请妥善保管。
7.2 设计和发行秘宝相关接口
issuer 可以独立设计、更新秘宝。
7.2.1 设计秘宝
相关文档：POST /issuers/{issuer_uuid}/token_classes
设计秘宝必须包含以下字段：
- name: 秘宝的名称，不超过 30 个字符（一旦创建，不可修改）
- description: 秘宝的简介，不超过 200 个字符（一旦创建，不可修改）
- total: 非负整数，为 0 时，表示秘宝不限量；大于 0 时，表示秘宝限量的数量
- renderer: 秘宝的媒体信息，必须为以
https://开头、媒体信息有效的 url，且不超过 255 字符（秘宝设计完成后，30 天内可修改一次 renderer）- renderer 为图片：支持格式为 png, jpg, jpeg, gif, webp 和 svg 6 种格式，必须以
https://开头，且结尾为png | jpg | jpeg | gif | webp | svg。 - renderer 为视频：支持格式为 mp4 和 webm 2 种格式，必须以
https://开头，且结尾为mp4 | webm。当 renderer 为音视频时，同时需要传入参数cover_image_url用于设置 NFT 封面，校验规则与图片格式的 renderer 一致。
设计的秘宝 token class 会上链，上链操作由平台完成。
- renderer 为图片：支持格式为 png, jpg, jpeg, gif, webp 和 svg 6 种格式，必须以
代码示例：
返回：
其中， uuid 为平台生成的唯一标识 token class id
- 在设计秘宝时提供可选参数
configure，用于设置 NFT class cell 的configure，金色传说平台默认设置为11000000， 相关信息可参考：https://talk.nervos.org/t/rfc-multi-purpose-nft-draft-spec/5434。configure格式应为类似11000000的 8 位二进制字符串，否则会返回configure field format error
请求示例：
7.2.2 查询指定 issuer 创作的所有 token classes
相关文档：GET /issuers/{issuer_uuid}/token_classes
代码示例：
返回：
7.2.3 修改指定 issuer 设计的秘宝（token class）
相关文档：PUT /issuers/{issuer_uuid}/token_classes/{token_class_uuid}
秘宝设计完成后，仅 renderer 部分可以修改
- renderer: 秘宝的媒体信息，必须为以
https://开头、媒体信息有效的 url，且不超过 255 字符（秘宝设计完成后，30 天内可修改一次 renderer）- renderer 为图片：支持格式为 png, jpg, jpeg, gif, webp 和 svg 6 种格式，必须以
https://开头，且结尾为png | jpg | jpeg | gif | webp | svg。 - renderer 为音频或视频：支持格式为 mp3, wav, mp4 和 webm 4 种格式，必须以
https://开头，且结尾为mp3 | wav | mp4 | webm。当 renderer 为音视频时，同时需要传入参数cover_image_url用于设置 NFT 封面，校验规则与图片格式的 renderer 一致。
修改秘宝 token class 会上链，上链操作由平台完成。
- renderer 为图片：支持格式为 png, jpg, jpeg, gif, webp 和 svg 6 种格式，必须以
代码示例：
返回：
7.2.4 铸造并发行秘宝
相关文档：POST /issuers/{issuer_uuid}/token_classes/{token_class_uuid}/tokens
查询字段：
-
token_class_uuid: 设计秘宝时返回的 token class uuid
请求字段： -
addresses: 一个由 ckb 地址组成的列表
代码示例：
返回：
其中， uuid 是具体的 NFT token id
7.2.5 获取指定 issuer 创建的 token class 对应的全部 tokens
相关文档：GET /issuers/{issuer_uuid}/token_classes/{token_class_uuid}/tokens
查询字段：
token_class_uuid: 设计秘宝时返回的 token class uuid
代码示例：
返回：
