NFTRainbow API使用指南

NFTRainbow API为无web3技术栈的web2用户在conflux平台发布自己的NFT提供了方便。本文将从web2用户的角度出发，对如何使用NFTRainbow API做出详细说明。

前置准备

用户注册

进入NFTRinbow API服务页面进行用户注册

在用户注册完毕并登录后, 可以在仪表盘的用户设置页面完善用户的信息：

企业认证

若是用户为企业代表, 可以在右上角的企业认证页面填入相应信息来进行企业认证

创建app

点击dashboard左侧的应用页面，并点击创建应用

填入以下信息后完成创建

app页面如下所示

点击右上角的查看AppKey可以获取到app_id与app_secret

app_id与app_secret用户获取JWT来调用Open APIs。

鉴权

NFTRainbow API是基于JWT来实现用户权限的鉴定的.

获取JWT

在通过Rainbow Console获取到app_id与app_secret后，可以通过调用Login API来获得对应的JWT.具体的有：

curl --request POST \
  --url https://api.nftrainbow.cn/v1/login \
  --header 'Content-Type: application/json' \
  --data `{
    "app_id": "qUUcdueA",
    "app_secret": "zGCaP8kAFEmwanqo"
}

响应结果如下：

{
        "expire": "2022-08-28T16:50:05.7704294+08:00",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjE2NzY2MDUsImlkIjoyLCJvcmlnX2lhdCI6MTY1OTA4NDYwNX0.vEXdWizTUcTtUjHzrJqrOjCLe5PmnR9sHuZqqGICLqw"
}

注意的是，在一个小时的有效时限内, 用户可以利用该JWT去调用Open APIs, 包括Files, Metadata, NFT和contract.

刷新JWT

一旦超出了一个小时, 在五个小时的有效时限内, 用户可以利用该JWT去调用refresh_token，实现JWT的刷新功能. 具体的有:

curl --request GET \
  --url https://api.nftrainbow.cn/v1/refresh_token \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

响应结果如下：

{
        "expire": "2022-08-28T16:50:55.8437443+08:00",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjE2NzY2NTUsImlkIjoyLCJvcmlnX2lhdCI6MTY1OTA4NDY1NX0.8k3JrmgmD20EfEJVGWbZ3gQYH_-Bt80miQXcQscq3MY"
}

铸造NFT流程

铸造NFT的流程如下图所示. 可以看到, NFTRainbow API为用户提供了三种铸造方式，分别为传统方式铸造NFT、上传文件来铸造NFT与创建Metadata来创建NFT。

传统方式铸造NFT需要用户首先创建自己的ERC721或ERC1155合约来获得合约地址contract_address。在成功获得合约地址的基础上, 用户需要上传文件, 并用获得的file_url来创建Metadata从而获取对应的metadata_uri. 最后，用户通过输入metadata_uri与contract_address调用传统方式铸造NFT来实现NFT的铸造。

上传文件来铸造NFT与创建Metadata来铸造NFT为用户提供了更加开放与快捷的方式去实现NFT铸造. 用户无需部署合约对应的合约，而是调用NFTRainbow API服务中已经部署好的合约实现NFT的发行。该合约的地址在测试网的地址为cfxtest:acgraybn1g1upesed09g96vxev79sdhmxjmz7bxzyy

在本节中将为各个接口如何实现进行说明.

上传文件

为了实现传统铸造NFT的功能, 用户需要获得metadata_uri. 而为了获取metadata_uri, 用户需要上传文件来获取相应的file_url。NFTRainbow API为用户获取file_url提供了两种方式，分别为上传文件至服务器与上传文件至OSS。

上传文件至服务器

对于上传文件至服务器，具体的有：

curl --request POST \
  --url https://api.nftrainbow.cn/v1/files \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file=

相应的响应为:

{
        "file_url": "http://dev.nftrainbow/assets/file/1/nft/67c96aee8ee1293594a4b4ded15c60ea7853e49c0a2eb41a4805a01a70bc3111.jpeg",
        "file_size": 11295,
        "file_type": "jpeg",
        "file_name": "fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b"
}

上传文件至OSS

对象存储OSS（Object Storage Service）是阿里提供的云存储服务。具有使用方便快捷、存储空间大、数据可靠等优点。为了实现将文件上传至OSS，具体的需要：

curl --request POST \
  --url https://api.nftrainbow.cn/v1/files/oss \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file=

相应的响应为:

{
    "file_url": "https://nft-rainbow.oss-cn-hangzhou.aliyuncs.com/file/4/nft/377d21aaeddfff1f4f1fa73498df70a462945bb06f5a984358202cec0682c4d2.jpeg",
    "file_size": 11295,
    "file_type": "jpeg",
    "file_name": "377d21aaeddfff1f4f1fa73498df70a462945bb06f5a984358202cec0682c4d2"
}

创建Metadata

在获得了file_url后, 需要调用create_metadata去获得metadata_uri. 具体的有:

curl --request POST
--url https://api.nftrainbow.cn/v1/metadata/ \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json' \
--data '{
  "attributes": [
    {
      "attribute_name": "mouse",
      "display_type": "test hey hey",
      "trait_type": "big",
      "value": "big"
    }
  ],
  "description": "this is a test metadata",
  "image": "http://dev.nftrainbow/assets/file/1/nft/67c96aee8ee1293594a4b4ded15c60ea7853e49c0a2eb41a4805a01a70bc3111.jpeg",
  "name": "test"
}

相应的响应为:

{
        "metadata_uri": "http://dev.nftrainbow/assets/metadata/1/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json"
}

部署合约

目前NFTRainbow API通过NFTFactory合约来进行合约部署。该合约在测试网的合约地址为cfxtest:acdh1unre2bsdtwfuv0enu7tuychw0sm9afxe9f8b0，该合约的对应代码可以参考项目的git仓库.

用户若想要调用该合约去部署自己的ERC721合约或ERC1155合约, 需要使得自己的账户拥有对应的角色，因此需要NFTFactory合约的admin调用合约方法对账户进行赋权。在用户账户拥有了相应的角色后，可以调用NFTRainbow API来进行合约的部署。

NFTRinbow API为用户提供了相应的API, 帮助用户去创建合约, 从而获得合约地址address. 为了部署合约, 可以调用deploy_contract API. 具体的有:

curl --request POST \
  --url https://api.nftrainbow.cn/v1/contracts \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "conflux_test",
    "name": "NFT-name",
    "symbol": "ENFT",
    "owner_address": "cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk",
    "type": "erc721",
    "base_uri": ""
}'

注意的是, type必须为erc721或是erc1155(区分大小写).
相应的响应为:

{
        "id": 1,
        "created_at": "2022-07-29T16:52:44.596+08:00",
        "updated_at": "2022-07-29T16:52:44.596+08:00",
        "deleted_at": null,
        "app_id": 2,
        "chain_type": 1,
        "chain_id": 1,
        "address": "",
        "owner_address": "cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk",
        "type": 1,
        "base_uri": "",
        "name": "NFT-name",
        "symbol": "ENFT",
        "hash": "",
        "tx_id": 1,
        "status": 0
}

在获得上述响应后，可以在conflux scan中查找部署的合约地址。步骤如下：

根据账户地址查找交易列表
根据交易哈希查找对应交易
在对应的交易信息页面中根据事件日志获取合约地址

如下图所示, 红框中的地址是部署后的合约地址

传统方式铸造NFT

在通过创建Metadata与部署合约获得metadata_uri与contract_address后, 可以调用合约中的方法去铸造NFT. NFTRainbow API简化了用户与合约间的交互流程, 用户可以直接调用相应的API去实现与合约的交互. 传统方式铸造NFT, 具体的有:

curl --request POST \
  --url https://api.nftrainbow.cn/v1/mints \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json' \ 
  --data '{
    "chain": "conflux_test",
    "token_id": "",
    "mint_to_address": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
    "contract_address": "cfxtest:acgat1yux2rk0xmk2s8ceferyprgm0u1hetj0w72yf",
    "metadata_uri": "http://dev.nftrainbow/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json"
}'

相应的响应为:

{
    "chain": "conflux_test",
    "name": "123",
    "description": "123",
    "mint_to_address": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
    "contract_address": "cfxtest:acf8m2gzrv8pnfsjbne2d28m4h2ycj569uupgys473",
    "metadata_uri": "http://dev.nftrainbow/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json"
}

上传文件来铸造NFT

除了传统方式铸造NFT外, NFTRainbow API还为用户提供了更加简捷的方法来铸造NFT. 这包括上传文件来铸造NFT与创建Metadata来铸造NFT. 上传文件忽略了上传文件与创建Metadata两步, 用户可以直接调用API来实现NFT的铸造. 具体的有:

curl --request POST \
  --url https://api.nftrainbow.cn/v1/mints/files \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file= \
  --form chain= 'conflux_test' \
  --form description= 'throll description' \ 
  --form mint_to_address= 'cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk' \
  --form name= 'throll'

相应的响应为:

{
        "id": 1,
        "created_at": "2022-07-29T16:53:46.867+08:00",
        "updated_at": "2022-07-29T16:53:46.867+08:00",
        "deleted_at": null,
        "app_id": 2,
        "chain_type": 1,
        "chain_id": 1,
        "contract": "cfxtest:acgraybn1g1upesed09g96vxev79sdhmxjmz7bxzyy",
        "mint_to": "cfxtest:acdh1unre2bsdtwfuv0enu7tuychw0sm9afxe9f8b0",
        "token_uri": "http://dev.nftrainbow/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json",
        "token_id": 0,
        "amount": 1,
        "status": 0,
        "hash": "",
        "tx_id": 1,
        "error": ""
}

创建Metadata来铸造NFT

创建Metadata来铸造NFT忽略了创建Metada, 用户只需要提供由上传文件生成的file_url, 就可以实现NFT的铸造功能. 具体的有：

curl --request POST \
  --url https://api.nftrainbow.cn/mints/urls \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "conflux_test",
    "name": "123",
    "description": "123",
    "mint_to_address": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
    "file_url": "http://dev.nftrainbow/assets/file/1/nft/67c96aee8ee1293594a4b4ded15c60ea7853e49c0a2eb41a4805a01a70bc3111.jpeg"
}'

相应的响应为:

{
        "id": 1,
        "created_at": "2022-07-29T16:54:01.745+08:00",
        "updated_at": "2022-07-29T16:54:01.745+08:00",
        "deleted_at": null,
        "app_id": 2,
        "chain_type": 1,
        "chain_id": 1,
        "contract": "cfxtest:acgraybn1g1upesed09g96vxev79sdhmxjmz7bxzyy",
        "mint_to": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
        "token_uri": "http://dev.nftrainbow/assets/metadata/0/nft/c3e31daa28ab54f6e3cfd650021373411b06a0692d4c4f01ae20be5fcf5cf70d.json",
        "token_id": 0,
        "amount": 1,
        "status": 0,
        "hash": "",
        "tx_id": 1,
        "error": ""
}

至此, 已实现NFT的铸造功能. 可以通过在conflux scan查找用户地址，在数字藏品资产页面下来查看生成的NFT.

为合约设置sponsor

在调用合约的方法去铸造NFT时, 需要花费相应的代币(相当于花钱). 这些代币可以在fluent钱包当中可以查询到. 若用户没有足够的代币, 则没法去铸造NFT. 所幸的是, conflux链中存在sponsor功能. 该功能可以为合约设置一个sponsor, 在该合约白名单当中的用户, 可以免费调用该合约的方法, 而不需要支付相应的代币. 这些代币将由sponsor来代付.

NFTRainbow API提供了相应的API, 帮助用户为部署的合约提供相应的sponsor. 具体的有:

curl --request POST \
  --url https://api.nftrainbow.cn/v1/contracts/:address/sponsor \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为:

{
"success"
}

需要注意的是, 该功能目前只能在conflux的测试网实现.

查询功能

NFTRainbow API为用户提供了相应的信息查询功能.

查询文件列表

在上传完文件后, 用户可以调用query_fileList API去实现文件列表的查询功能.具体的有:

curl --request GET \
  --url https://api.nftrainbow.cn/v1/files \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为：

{
        "count": 3,
        "items": [
            {
                "file_url": "http://dev.nftrainbow/assets/file/2/nft/fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b.jpeg",
                "file_size": 11295,
                "file_type": "jpeg",
                "file_name": "fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b"
            },
            {
                "file_url": "http://dev.nftrainbow/assets/file/2/nft/06edf22f414234ea59c949104a054ca4af27cd71e87170d99401b50d15651cdc.jpeg",
                "file_size": 11295,
                "file_type": "jpeg",
                "file_name": "06edf22f414234ea59c949104a054ca4af27cd71e87170d99401b50d15651cdc"
            },
            {
                "file_url": "http://dev.nftrainbow/assets/file/2/nft/bf822838b7b3a7dadc96bd6f38defcbb21376852284ded6302aac69a71e58027.jpeg",
                "file_size": 11295,
                "file_type": "jpeg",
                "file_name": "bf822838b7b3a7dadc96bd6f38defcbb21376852284ded6302aac69a71e58027"
            }
        ]
}

根据metadata_id查询metadata

在创建metadata后, 用户可以提供metadata_id调用query_metadata API去实现查询metadata的功能. 具体的有:

curl --request GET \
  --url https://localhost:8080/v1/metadata/:metadata_id \
  --header 'Authorization: 'Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为：

{
        "name": "test",
        "description": "this is a test metadata",
        "image": "http://dev.nftrainbow/assets/file/3/nft/02c95850aacd060da60f6fe500ff5bb06d67663682bef8fd490dedf0a0e7b2a7.png",
        "attributes": [
            {
                "attribute_name": "eyes",
                "trait_type": "test trait",
                "display_type": "",
                "value": "big"
            },
            {
                "attribute_name": "mouse",
                "trait_type": "test hey hey",
                "display_type": "",
                "value": "big"
            }
        ]
}

值得注意的是, metadata_id可以通过传回的metadata_uri获得. 如

http://dev.nftrainbow/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json
该metadata的id为：
f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490

查询metadata列表

在创建metadata后, 用户可以调用query_metadata_list API去实现查询metadata列表的功能. 具体的有:

curl --request GET \
  --url https://api.nftrainbow.cn/v1/metadata/ \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为：

{
        "count": 1,
        "items": [
            {
                "metadata": {
                    "name": "test",
                    "description": "this is a test metadata",
                    "image": "http://dev.nftrainbow/assets/file/2/nft/02c95850aacd060da60f6fe500ff5bb06d67663682bef8fd490dedf0a0e7b2a7.png",
                    "attributes": [
                        {
                            "attribute_name": "eyes",
                            "trait_type": "test trait",
                            "display_type": "",
                            "value": "big"
                        },
                        {
                            "attribute_name": "mouse",
                            "trait_type": "test hey hey",
                            "display_type": "",
                            "value": "big"
                        }
                    ]
                },
                "uri": "http://dev.nftrainbow/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json"
            }
        ]
}

查询合约列表

在部署完合约后, 用户可以通过list_contracts API来获取合约列表. 具体的有:

curl --request GET \
  --url https://api.nftrainbow.cn/v1/contracts \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为：

{
        "count": 1,
        "items": [
            {
                "id": 6,
                "created_at": "2022-07-29T16:52:44.596+08:00",
                "updated_at": "2022-07-29T16:53:10.282+08:00",
                "deleted_at": null,
                "app_id": 2,
                "chain_type": 1,
                "chain_id": 1,
                "address": "",
                "owner_address": "cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk",
                "type": 1,
                "base_uri": "",
                "name": "NFT-name",
                "symbol": "ENFT",
                "hash": "",
                "tx_id": 14,
                "status": 2
            }
        ]
}

根据合约地址查询sponsor信息

在为合约设置完sponsor后, 用户可以通过get_contract_sponsor API来获取该sponsor的信息. 具体的有:

curl --request GET \
  --url https://api.nftrainbow.cn/v1/contracts/:address/sponsor \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为：

{
        "gas_sponsor": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
        "gas_sponsor_balance": 10000000000000000000,
        "collateral_sponsor": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
        "collateral_sponsor_balance": 100000000000000000000,
        "is_all_white_listed": true,
        "gas_upper_bound": 5000000000000000
}

查询NFT列表

在铸造完NFT后, 用户可以通过list_mints API来获取铸造的NFT的列表. 具体的有:

curl --request GET \
  --url https://api.nftrainbow.cn/v1/mints \
  --header 'Authorization: Bearer {JWT}' \
  --header 'Content-Type: application/json'

相应的响应为：

{
        "count": 1,
        "items": [
            {
                "id": 1,
                "created_at": "2022-07-29T21:32:54.006+08:00",
                "updated_at": "2022-07-29T21:32:54.006+08:00",
                "deleted_at": null,
                "app_id": 2,
                "chain_type": 1,
                "chain_id": 1,
                "contract": "cfxtest:acf8m2gzrv8pnfsjbne2d28m4h2ycj569uupgys473",
                "mint_to": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
                "token_uri": "http://dev.nftrainbow/assets/metadata/1/nft/46708cf66a806743cfc27b110a41a2ea2e1b7a47fbcfb2efc9cac8fd3bf29cd1.json",
                "token_id": 4514651488,
                "amount": 1,
                "status": 0,
                "hash": "",
                "tx_id": 27,
                "error": ""
            }
        ]
}

参考文献

NFTRainbow 文档
 conflux内置sponsorwhitelistcontrol合约
 NFTRainbow服务

NFTRainbow API使用指南