Skip to main content

Multi-issuers

在秘宝创作者平台注册帐号后，默认会生一个创作者对应的 issuer，该 issuer 的信息即为用户在秘宝创作者平台设置的公开信息。

Open API 允许一个帐号创建多个 issuers，不同 issuer 之间相互独立，即每个 issuer 有独立的 key/secret，可以单独设置独立的创作者信息，用于创作和发行秘宝。

对拥有 multi-issuers 权限的帐号，我们可以称该帐号对应的 API key 为 master_key，将由其创建的 issuer 对应的 API key 为 issuer_key。对于原有接口，只有 master_key 可以正常请求使用；master 拥有 issuer 的所有权限，issuer 仅可以通过指定 API 操作自己创作的秘宝。

注：如需使用该功能，需要单独申请 multi-Issuers 功能权限。用户可以发送邮件到 biz@nervina.io 进行申请，内容必须包含要申请开通 multi-issuers 权限的帐号邮箱地址。

1. Issuers 管理​

Master_key 可以对其创建的所有 issuers 进行增删改查的管理操作，issuer_key 无此权限。

1.1 获取全部 issuers 列表​

Master_key 可以查询该帐号下所有的 issuers 信息。

API 文档：GET /api/v1/issuers

代码示例：

import requests

key = ''
secret = ''
method = 'GET'
endpoint = f'/api/v1/issuers'
content = ''
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=content)

返回示例：

{
  "issuers": [
    {
      "avatar_url": "https://images.pexels.com/photos/3396664/peels-photo-3396664.jpeg",
      "name": "issuer_name",
      "description": "issuer_description",
      "website": "",
      "email": "",
      "weibo": "",
      "uuid": "f0d044c2-9ddb-4406-87b3-b281fbb27a76"
    }
  ]
}

1.2 创建新的 issuer​

Master_key 可以创建新的 issuer。

API 文档：POST /api/v1/issuers

Options：

  • name -- string, required: 新创建的 issuer name，最多 30 个字符；
  • avatar_url -- string, optional：创作者头像图片链接，最多 255 个字符，必须以 https:// 开头，以 png, jpg, jpeg, gif, webp, svg 这六种文件格式之一为后缀结尾；
  • website -- string, optional：创作者官网地址，最多 200 个字符；
  • description -- string, optional: 创作者简介，最多 200 个字符；
  • email -- string, optional：创作者邮箱地址，最多 100 个字符；
  • weibo -- string, optional：创作者社交媒体链接，最多 200 个字符；

请求示例：

import requests

key = ''
secret = ''
method = 'POST'
endpoint = f'/api/v1/issuers'
content = '
{
    "avatar_url": "https://www.avatar.jpg",
    "name": "new issuer name",
    "website": "https://www.website.com",
    "description": "new issuer description",
    "email": "issuer@nervina.io",
    "weibo": "https://weibo.com/xxx"
}
'
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=content)

返回示例：

{
  "avatar_url": "https://www.avatar.jpg",
  "name": "new issuer name",
  "description": "new issuer description",
  "website": "https://www.website.com",
  "email": "issuer@nervina.io",
  "weibo": "https://weibo.com/xxx",
  "uuid": "5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a",
  "api_token": {
    "access_key": "Nkx9gUnpaBwD7gCl",
    "secret": "7226c58ef55f5539fb0fe3afa24978c87581365763abc4f020dbf3a5a379b7de",
    "refresh_token": "53a74a524a769180bc4cf60e863d385ef29d93795cfb0ddbd86970f736baebda"
  }
}

返回信息中的 uuid 为该 issuer 对应的 issuer_uuid，api_token.access_key ， api_token.secret 为该 issuer 进行设计和发行秘宝时的 key/secret， api_token.refresh_token 为 issuer 更新 key-secret 时需要的参数（后边相关 API 会详细介绍）。

warning

api_token 相关信息仅在创建时返回一次，请谨慎保管。

1.3 更新 issuer 信息​

Master_key 可以更新已有 issuer 的相关信息。

API 文档：PUT /api/v1/issuers/{issuer_uuid}

Options：

  • name -- string, required: issuer name，最多 30 个字符；
  • avatar_url -- string, optional：创作者头像图片链接，最多 255 个字符，必须以 https:// 开头，以 png, jpg, jpeg, gif, webp, svg 这六种文件格式之一为后缀结尾；
  • website -- string, optional：创作者官网地址，最多 200 个字符；
  • description -- string, optional: 创作者简介，最多 200 个字符；
  • email -- string, optional：创作者邮箱地址，最多 100 个字符；
  • weibo -- string, optional：创作者社交媒体链接，最多 200 个字符；

请求示例：

import requests

key = ''
secret = ''
method = 'PUT'
endpoint = f'/api/v1/issuers/5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a'
content = '
{
    "avatar_url": "https://www.avatar.jpg",
    "name": "update new issuer name",
    "website": "https://www.website.com",
    "description": "new issuer description",
    "email": "issuer@nervina.io",
    "weibo": "https://weibo.com/xxx"
}
'
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=content)

返回示例：

{
  "avatar_url": "https://www.avatar.jpg",
  "name": "update new issuer name",
  "description": "new issuer description",
  "website": "https://www.website.com",
  "email": "issuer@nervina.io",
  "weibo": "https://weibo.com/xxx",
  "uuid": "5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a"
}

1.4 获取指定 issuer 信息​

Master_key 可以获取指定 issuer 信息。

API 文档：GET /api/v1/issuers/{issuer_uuid}

请求示例：

import requests

key = ''
secret = ''
method = 'GET'
endpoint = f'/api/v1/issuers/5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a'
content = ''
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=content)

返回实例：

{
  "issuer": {
    "avatar_url": "https://www.avatar.jpg",
    "name": "new issuer name",
    "description": "new issuer description",
    "website": "https://www.website.com",
    "email": "issuer@nervina.io",
    "weibo": "https://weibo.com/xxx",
    "uuid": "5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a"
  }
}

1.5 更新指定 issuer 的 key/secret​

Master 可以更新所有 issuer 的 key/secret；issuer 可以更新自己的 key/secret。

API 文档：POST /api/v1/issuers/{issuer_uuid}/api_tokens

Options:

  • refresh_token -- string, optional: 使用 master 请求 refresh token 时，该参数可以忽略；使用 issuer 请求时，该参数为必须参数

请求示例：

import requests

key = ''
secret = ''
method = 'POST'
endpoint = f'/api/v1/issuers/5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a/refresh_token'
content = '
{
  "refresh_token": "53a74a524a769180bc4cf60e863d385ef29d93795cfb0ddbd86970f736baebda"
}
'
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=content)

返回示例：

{
  "api_token": {
    "access_key": "SgxjJTJZ3MDlFwny",
    "secret": "cc31c0e8fd263b116dfb9cbe3787458cd42cf3e054cdbe522b284c0b77a4d9c9",
    "refresh_token": "ba5dbcf681f006243e79aa7abaf820c003335fad9b90c4b1a76039a9b3de70d4"
  }
}
warning

返回中的 access_key , secret 和 refresh_token 为新的 key/secret ，仅返回一次，请妥善保管。

2. Issuer 创作和发行秘宝​

issuer 可以独立创作和发行秘宝。

2.1 创作秘宝​

API 文档：POST /api/v1/issuers/{issuer_uuid}/token_classes

Options：

  • name -- string, required: NFT 的名称，不能超过 30 个字符（一旦创建，不可修改）；
  • description -- string, required: NFT 的简介，不能超过 200 个字符（一旦创建，不可修改）；
  • total -- string, required: string 类型的非负整数，为 0 时表示 NFT 不限量，其他正整数表示 NFT 限量的数量（一旦创建，不可修改）；
  • renderer -- string, required: NFT 的媒体信息，规则同 POST /api/v1/token_classes；

创建 token class 请求成功后，所创建的 token class 上链操作由创作者平台完成。Issuer 创作秘宝规则与 master 创作秘宝的规则一致，此处仅作创作图片类型 NFT 的示例。

代码示例：

import json
import requests

key = ''
secret = ''
method = 'POST'
issuer_uuid = '620dc081-2790-4952-867f-756bf02981db'
endpoint = f'/api/v1/issuers/{issuer_uuid}/token_classes'
content = {
    'name': 'New Token Class Example',
    'description': 'Create Token Class by Open API',
    'total': '0',
    'renderer': 'https://oss.jinse.cc/production/7ea62f75-bec0-4cdc-b81a-d59d7f40ace1.jpg'
}
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=json.dumps(content))

返回：

{
  "name": "New Token Class Example",
  "description": "Create Token Class by Open API",
  "issued": "0",
  "renderer": "https://oss.jinse.cc/production/7ea62f75-bec0-4cdc-b81a-d59d7f40ace1.jpg",
  "uuid": "e6469650-6ac5-4477-a64b-2a97f4168356",
  "total": "0",
  "tags": []
}

返回中的 uuid 即为所创作秘宝的 token class uuid。

2.2 查询指定 issuer 创作的所有 token classes​

相关文档：GET /api/v1/issuers/{issuer_uuid}/token_classes

代码示例：

import requests

key = ''
secret = ''
method = 'GET'
issuer_uuid = '5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a'
endpoint = f'/api/v1/issuers/{issuer_uuid}/token_classes'
content = ''
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers)

返回：

{
  "token_classes": [
    {
      "name": "issuerA-ikey-c001",
      "description": "first nft",
      "issued": "0",
      "renderer": "https://oss.jinse.cc/production/db8b6440-6e26-4a80-8dc7-cfdd022e0b6d.jpg",
      "cover_image_url": "",
      "uuid": "43edf4ba-9c77-466e-807f-d35cb4465c6f",
      "total": "1000",
      "is_banned": false,
      "verified_info": {
        "is_verified": null,
        "verified_title": "",
        "verified_source": ""
      }
    }
  ],
  "meta": {
    "total_count": 1,
    "max_page": 1,
    "current_page": 1
  }
}

2.3 修改指定 issuer 设计的秘宝（token class）​

相关文档：PUT /issuers/{issuer_uuid}/token_classes/{token_class_uuid}

秘宝设计完成后，仅 renderer 和 cover_image_url 可以修改，且 30 天内仅允许修改一次。

  • renderer -- string, required: NFT 的媒体信息，规则同 POST /api/v1/token_classes；
  • cover_image_url -- string, optional: NFT 封面信息，当 NFT 类型为视频或 3D 类型时必须传入；

修改秘宝 token class 会上链，上链操作由平台完成。

请求示例：

import json
import requests

key = ''
secret = ''
method = 'PUT'
issuer_uuid = '5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a'
token_class_uuid = '43edf4ba-9c77-466e-807f-d35cb4465c6f'
endpoint = f'/api/v1/issuers/{issuer_uuid}/token_classes/{token_class_uuid}'
content = {
    'renderer': 'https://game-4m-assets.oss-cn-shanghai.aliyuncs.com/AdobeStock_95598553.jpeg'
}
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn/api/v1{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=json.dumps(content))

返回示例：

{
  "name": "issuerA-ikey-c001",
  "description": "first nft",
  "issued": "0",
  "renderer": "https://game-4m-assets.oss-cn-shanghai.aliyuncs.com/AdobeStock_95598553.jpeg",
  "cover_image_url": null,
  "uuid": "43edf4ba-9c77-466e-807f-d35cb4465c6f",
  "total": "1000"
}

2.4 铸造并发行秘宝​

API 文档：POST /api/v1/issuers/{issuer_uuid}/token_classes/{token_class_uuid}/tokens

Options:

  • token_class_uuid -- string, required: 将被铸造和分发的 NFT token 对应的 token class，token_class_uuid 在创作秘宝时返回；
  • addresses -- string, required: token 分发的目标地址，每个 address 分发一个 token, 如过需要将多个 token 分发到同一地址，则需要填入对应数量的个 address；
  • characteristic -- string, optional: 用于设置 token 的 characteristic 字段，单个请求中的所有 token 的 characteristic 值一致，默认为 0000000000000000;

请求示例：

import json
import requests

key = ''
secret = ''
method = 'POST'
issuer_uuid = '5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a'
token_class_uuid = '43edf4ba-9c77-466e-807f-d35cb4465c6f'
address = 'ckt1q3vvtay34wndv9nckl8hah6fzzcltcqwcrx79apwp2a5lkd07fdxxqycw877rwy0uuwspsh9cteaf8kqp8nzjl0dxfp'
endpoint = f'/api/v1/issuers/{issuer_uuid}/token_classes/{token_class_uuid}/tokens'
content = {
    'addresses': [
        address
    ]
}
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn/api/v1{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=json.dumps(content))

返回示例：

[
  {
    "uuid": "27b03ca5-abbe-4c82-9416-c37c2462d630",
    "oid": "83d1ab0dd73c408ecf4d4ae7dd88172b",
    "version": 0,
    "characteristic": "0000000000000000",
    "issuer_id": 1760,
    "token_class_id": 2348,
    "state": "pending",
    "configure": 192,
    "n_issuer_id": "0xb69cb79760a0a1a187af8c3b94643776237d5899",
    "n_state": 0,
    "created_at": "2021-10-25T15:36:13.674+08:00",
    "updated_at": "2021-10-25T15:36:13.674+08:00"
  }
]

其中， uuid 为对应 NFT token 的 token_uuid

7.2.5 查询指定 issuer 创建的 token class 对应的全部 tokens​

相关文档：GET /api/v1/issuers/{issuer_uuid}/token_classes/{token_class_uuid}/tokens

Options:

  • token_class_uuid : 设计秘宝时返回的 token_class_uuid

请求示例：

import json
import requests

key = ''
secret = ''
method = 'GET'
issuer_uuid = '5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a'
token_class_uuid = '43edf4ba-9c77-466e-807f-d35cb4465c6f'
address = 'ckt1q3vvtay34wndv9nckl8hah6fzzcltcqwcrx79apwp2a5lkd07fdxxqycw877rwy0uuwspsh9cteaf8kqp8nzjl0dxfp'
endpoint = f'/api/v1/issuers/{issuer_uuid}/token_classes/{token_class_uuid}/tokens'
content = ''
content_type = 'application/json'

url = f'https://goldenlegend.staging.nervina.cn{endpoint}'
signature, gmt = get_signature_and_gmt(secret, method, endpoint, content, content_type)
headers = {
    'Content-Type': content_type,
    'Date': gmt,
    'Authorization': f'NFT {key}:{signature}'
}

requests.request(method, url, headers=headers, data=json.dumps(content))

返回示例：

{
  "tokens": [
    {
      "name": "issuerA-ikey-c001",
      "description": "first nft",
      "issued": "1",
      "total": "1000",
      "bg_image_url": "https://game-4m-assets.oss-cn-shanghai.aliyuncs.com/AdobeStock_95598553.jpeg",
      "issuer_info": {
        "name": "update new name",
        "avatar_url": "",
        "uuid": "5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a",
        "issuer_follows": 0,
        "issuer_followed": false
      },
      "tx_state": "submitting",
      "class_uuid": "43edf4ba-9c77-466e-807f-d35cb4465c6f",
      "from_address": "5f4ebad3-38a1-44d2-8e9d-0212a09f9c5a",
      "to_address": "ckt1q3vvtay34wndv9nckl8hah6fzzcltcqwcrx79apwp2a5lkd07fdxxqycw877rwy0uuwspsh9cteaf8kqp8nzjl0dxfp",
      "is_class_banned": false,
      "is_issuer_banned": false,
      "n_token_id": 0,
      "verified_info": {
        "is_verified": null,
        "verified_title": "",
        "verified_source": ""
      },
      "class_likes": 0,
      "class_liked": false,
      "uuid": "27b03ca5-abbe-4c82-9416-c37c2462d630",
      "created_at": "2021-10-25T15:36:13.674+08:00",
      "distribution_method": "send",
      "tx_hash": "0x89ed628e5fbe2e4585d486a61b531dc7cd479cdeb04b5ed187851af9290e9f82",
      "tx_uuid": "c4a9fe74-3f14-48d7-a154-ff013062626d",
      "renderer_type": "image",
      "renderer": "https://game-4m-assets.oss-cn-shanghai.aliyuncs.com/AdobeStock_95598553.jpeg",
      "class_card_back_content_exist": false,
      "class_card_back_content": null,
      "id": 21711,
      "is_redeemed": false
    }
  ],
  "meta": {
    "total_count": 1,
    "max_page": 1,
    "current_page": 1
  }
}