Coleções

Resumo

As coleções estão diretamente ligadas às Comunidades e as Empresas, elas representam os Smart Contracts, que podem ser contratos pré existentes ou contratos que serão criados na Blockchain a partir desta API.

É aqui que vamos definir as informações da Coleção como o tipo de contrato ex: ERC1155, ERC721, ERC20. Rede Blockchain usada, e as informações relativas ao contrato, no caso de um contrato de Venda de NFT's por exemplo, dados como Descrição, BaseURI das Imagem, Preço de Venda, Split de Pagamento e Distribuição de Royalties (caso haja).

Exemplo de alguns tipos de Coleções:

  • Token de Pagamento

  • Leilão de NFTs

  • Leilão de NFTs reverso

  • Vendas de NFTs

  • Airdrop de NFTs e/ou Tokens de Pagamento

  • POAP

  • Outros

É na coleção também que vamos associar os benefícios que os membros terão acesso.

Como funciona

Um usuário com a devida autorização poderá criar Coleções atreladas a uma Comunidade. Caso o contrato dessa coleção ainda não exista na Blockchain, será necessário executar o Deploy do contrato pela API. Para tal o usuário em questão precisa ter saldo em carteira pois essa operação irá criar transações na Blockchain.

Gestão em Massa de Tokens da Coleção

Com o objetivo de facilitar as operações relativas aos tokens, alguns endpoints permitem a manipulação de tokens em lote, assim como a execução do Mint dos tokens criados pode ser feita em lote através de uma única chamada em API.

Gestão do contrato Web3

Todas as operações web3 são enviadas para uma fila e processadas de forma assincrona. Comandos de deploy criam o contrato uma única vez na rede definida no cadastro. O comando de mint-batch de tokens executa o mint da diferença de tokens entre o cadastro e a blockchain.

Objeto Collection

Exemplo de Objeto de Coleção
{
    "id": "8798wdefs",
    "communityId": "8798wdefs",
    "companyId": "sd21fs5",
    "name": "Airdrop NFT",
    "description": "Distribuição de tokens não fungíveis",
    "symbol":"Um símbolo para o contrato",
    "image":"URL de uma imagem para ficar como capa da coleção",
    "type": "airdrop" | "sale" | "auction" | <others>,
    "startDate": "2021-01-01T00:00:00Z",
    "expirationDate": "2021-12-31T23:59:59Z",
    "mainCurrency": "USD" | "BRL" | "ETH" | "MATIC" | <others>,
    "tags": ["ambiental", "arte", "empreeendedorismo"]
    "contract": {
        "address": "0x1234567890abcdef12345678sssbcdef12345678",
        "network": "ethereum_mainnet" | "polygon_mainnet" | <others>,
        "pattern": "ERC20" | "ERC721" | "ERC1155" | <others>,
        "ownerAddress": "0x1234567890abcdef12345678sssbcdef12345678",
        "bytecode": /*Bytecode do contrato usada no deploy, apenas para contratos customizados*/,
        "abi": [/*ABI completa do contrato usada no deploy*/],
        "metadataCID": {
            "en": "ipfs://efauiyose.pinata.cloud",
            "pt": "ipfs://rgwqpmkiura.pinata.cloud"
        },
        "methods": {
            "deploy": {
                "args": [/* argumentos do construtor do contrato em ordem e com tipo compatível */],
            },
            "balanceOf": {
                "methodABI": {/* ABI do método balanceOf */},            
            }        
        },
        "royalties": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
            }
        ],
        "split": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
            }
        ],
    }
    "status": "active",
    "statusWeb3": "active"
}

Endpoints

  • Coleções

    • GET /v1/collections

    • GET /v1/collections/:collectionId

    • GET /v1/collections/:collectionId/tokens

  • Gestão de Coleções

    • GET /v1/collections/manage

    • POST /v1/collections/manage

    • GET /v1/collections/:collectionId/manage

    • PATCH /v1/collections/:collectionId/manage

  • Gestão em Massa de Tokens da Coleção

    • GET /v1/collections/:collectionId/tokens/manage

    • POST /v1/collections/:collectionId/tokens/manage

  • Gestão do contrato Web3

    • POST /v1/collections/:collectionId/manage/web3/deploy

    • POST /v1/collections/:collectionId/manage/web3/stop

    • POST /v1/collections/:collectionId/manage/web3/start

    • GET /v1/collections/:collectionId/manage/web3/methods

    • GET /v1/collections/:collectionId/manage/web3/:method-name

    • POST /v1/collections/:collectionId/manage/web3/:method-name

Coleções

Lista as coleções públicas

GET https://goblockchain.io/gotokens-api/v1/collections

Nível de autorização necessário: qualquer

Query Parameters

NameTypeDescription

name

String

Nome da Coleção

limit

String

Limite de resultados na busca

offset

String

Posição inicial da busca

communityId

String

ID da Comunidade

companyId

String

ID da Empresa

tags

Array

Tags da Coleção

{
    "collections": [
        {
            "id": "8798wdefs",
            "communityId": "8798wdefs",
            "companyId": "sd21fs5",
            "name": "Airdrop NFT",
            "description": "Distribuição de tokens não fungíveis",
            "startDate": "2021-01-01T00:00:00Z",
            "expirationDate": "2021-12-31T23:59:59Z",
            "type": "airdrop" | "sale" | "auction" | <others>,
            "mainCurrency": "USD | BRL | ETH | MATIC | <others>",
            "tags": ["ambiental", "arte", "empreeendedorismo"]
        }
    ]

Lista as informações de uma coleção pública

GET https://goblockchain.io/gotokens-api/v1/collections/:collectionId

Nível de permissionamento necessário: qualquer

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

{
    "id": "8798wdefs",
    "communityId": "8798wdefs",
    "companyId": "sd21fs5",
    "name": "Airdrop NFT",
    "description": "Distribuição de tokens não fungíveis",
    "startDate": "2021-01-01T00:00:00Z",
    "expirationDate": "2021-12-31T23:59:59Z",
    "type": "airdrop" | "sale" | "auction" | <others>,
    "mainCurrency": "USD | BRL | ETH | MATIC | <others>",
    "tags": ["ambiental", "arte", "empreeendedorismo"]
}

Lista os tokens públicos associadas à uma coleção

GET https://goblockchain.io/gotokens-api/v1/collections/:collectionId/tokens

Nível de permissionamento necessário: qualquer

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Query Parameters

NameTypeDescription

limit

String

Limite de resultados na busca

offset

String

Quantidade de resultados para avançar da busca

tags

Array

Tags do Token

[
    {
      "id":"5hws4eb18t0q",
      "tokenId": "1",
      "collectionId": "321",
      "supply": "10",
      "displayMediaUrl": "http://url.com/token",
      "displayMediaType": "image",
      "owners": [
        {
          "address": "0xer7s89gf4ger987tes978f",
          "quantity": "3"
        }
      ],
      "transactionType": "airdrop",
      "tags": ["ambiental", "arte", "empreeendedorismo"]
    },
    {
      "id":"a8rt9red1vb",
      "tokenId": "2",
      "collectionId": "321",
      "supply": "5",
      "displayMediaUrl": "http://url.com/token",
      "displayMediaType": "gif",
      "owners": [
        {
          "address": "0x73w49f8we1fwe849f8fea",
          "quantity": "1"
        },
        {
          "address": "0x36lutsmerkug87fsQ4R",
          "quantity": "2"
        }
      ],
      "transactionType": "airdrop",
      "tags": ["ambiental", "arte", "empreeendedorismo"]
    },
]

Gestão de Coleções

(JWT) Lista as coleções que o usuário tem direito de edição

GET https://goblockchain.io/gotokens-api/v1/collections/manage

Nível de autorização necessário: company_admin, company_moderator, community_admin, community_moderator

Caso queira, você pode realizar a pesquisa apenas com o JWT no Header.

Query Parameters

NameTypeDescription

name

String

Nome da Coleção

id

String

ID da Coleção

limit

String

Limite de resultados na busca

offset

String

Posição inicial da busca

communityId

String

ID da Comunidade

companyId

String

ID da Empresa

tags

Array

Tags da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

[
    {
        "id": "8798wdefs",
        "communityId": "8798wdefs",
        "companyId": "sd21fs5",
        "name": "Airdrop NFT",
        "description": "Distribuição de tokens não fungíveis",
        "type": "airdrop" | "sale" | "auction" | <others>,
        "contract": {
            "address": "0x1234567890abcdef12345678sssbcdef12345678",
            "network": "ethereum_mainnet | polygon_mainnet | <others>",
            "pattern" : "ERC20" | "ERC721" | "ERC1155" | <others>,
            "ownerAddress": "0x1234567890abcdef12345678sssbcdef12345678",
            "methods": {
                "deploy": {
                    "args": [/* argumentos do construtor do contrato em ordem e com tipo compatível */],
                },
                "balanceOf": {
                    "methodABI": {/* ABI do método balanceOf */},            
                }        
            },
            "royalties": [
                {
                    "id": "2343d23d234",
                    "address": "0x1234567890abcdef1....78sssbcdef12345678",
                    "percent": 20
                },
                {
                    "id": "2343ds3d234",
                    "address": "0x1234567890abcdef1....78sssbcdef12345678",
                    "percent": 80
                }
            ],
            "split": [
                {
                    "id": "2343d23d234",
                    "address": "0x1234567890abcdef1....78sssbcdef12345678",
                    "percent": 20
                },
                {
                    "id": "2343ds3d234",
                    "address": "0x1234567890abcdef1....78sssbcdef12345678",
                    "percent": 80
                }
            ],
        }    
        "expirationDate": "2021-12-31T23:59:59Z",
        "startDate": "2021-01-01T00:00:00Z",
        "mainCurrency": "USD | BRL | ETH | MATIC | <others>",
        "tags": ["ambiental", "arte", "empreeendedorismo"],
        "status": "private",
        "statusWeb3": "private"
    }
]

(JWT) Cria coleção para a qual tem a devida autorização

POST https://goblockchain.io/gotokens-api/v1/collections/manage

Nível de autorização necessário: company_admin, company_moderator, community_admin

Headers

NameTypeDescription

authorization*

Bearer

JWT

Request Body

NameTypeDescription

name*

String

Nome da Coleção

description*

String

Descrição da Coleção

communityId*

String

ID da Comunidade

companyId*

String

ID da Empresa

contract*

Object

Dados relativos ao contrato

type*

String

Tipo de distribuição dos Tokens da Coleção

expirationDate

DateTime

Data de fim da distribuição de Tokens da Coleção

startDate

DateTime

Data de inicio da distribuição de Tokens da Coleção

mainCurrency

String

Moeda principal da Coleção

status*

String

Status de publicação da Coleção

statusWeb3*

String

Status de publicação da Coleção na blockchain

tags

Array

Tags da Coleção

image*

String

URL para a imagem de capa da Coleção

symbol*

String

Símbolo da Coleção

{
    "id": "8798wdefs",
    "communityId": "8798wdefs",
    "companyId": "sd21fs5",
    "name": "Airdrop NFT",
    "description": "Distribuição de tokens não fungíveis",
    "symbol":"Um símbolo para o contrato",
    "image":"URL de uma imagem para ficar como capa da coleção",
    "type": "airdrop" | "sale" | "auction" | <others>,
    "contract": {
        "address": "0x1234567890abcdef12345678sssbcdef12345678",
        "network": "ethereum_mainnet" | "polygon_mainnet" | <others>,
        "pattern" : "ERC20" | "ERC721" | "ERC1155" | <others>,
        "ownerAddress": "0x1234567890abcdef12345678sssbcdef12345678",
        "methods": {
            "deploy": {
                "args": [/* argumentos do construtor do contrato em ordem e com tipo compatível */],
            },
            "balanceOf": {
                "methodABI": {/* ABI do método balanceOf */},            
            }        
        },
        "royalties": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
             }
        ],
        "split": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
             }
        ],
    }    
    "expirationDate": "2021-12-31T23:59:59Z",
    "startDate": "2021-01-01T00:00:00Z",
    "mainCurrency": "USD" | "BRL" | "ETH" | "MATIC" | <others>,
    "tags": ["ambiental", "arte", "empreeendedorismo"],
    "status": "private",
    "statusWeb3": "private"
    }
}

(JWT) Lista as informações de uma coleção

GET https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage

Nível de permissionamento necessário: company_admin, company_moderator, community_admin, community_moderator

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

{
    "id": "8798wdefs",
    "communityId": "8798wdefs",
    "companyId": "sd21fs5",
    "name": "Airdrop NFT",
    "description": "Distribuição de tokens não fungíveis",
    "type": "airdrop" | "sale" | "auction" | <others>,
    "contract": {
        "address": "0x1234567890abcdef12345678sssbcdef12345678",
        "network": "ethereum_mainnet" | "polygon_mainnet" | <others>,
        "pattern" : "ERC20" | "ERC721" | "ERC1155" | <others>,
        "ownerAddress": "0x1234567890abcdef12345678sssbcdef12345678",
        "methods": {
            "deploy": {
                "args": [/* argumentos do construtor do contrato em ordem e com tipo compatível */],
            },
            "balanceOf": {
                "methodABI": {/* ABI do método balanceOf */},            
            }        
        },
        "royalties": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
             }
        ],
        "split": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
             }
        ],
    }    
    "expirationDate": "2021-12-31T23:59:59Z",
    "startDate": "2021-01-01T00:00:00Z",
    "mainCurrency": "USD" | "BRL" | "ETH" | "MATIC" | <others>,
    "tags": ["ambiental", "arte", "empreeendedorismo"],
    "status": "private",
    "statusWeb3": "private"
    }
}

(JWT) Altera coleção para a qual tem a devida autorização

PATCH https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage

Nível de autorização necessário: company_admin, company_moderator, community_admin, community_moderator

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

Request Body

NameTypeDescription

name

String

Nome da Coleção

description

String

Descrição da Coleção

communityId

String

ID da Comunidade

companyId

String

ID da Empresa

contract

Object

Dados relativos ao contrato

type

String

Tipo de distribuição dos Tokens da Coleção

expirationDate

DateTime

Data de fim da distribuição de Tokens da Coleção

startDate

DateTime

Data de inicio da distribuição de Tokens da Coleção

mainCurrency

String

Moeda principal da Coleção

status

String

Status de publicação da Coleção

statusWeb3

String

Status de publicação da Coleção na blockchain

tags

Array

Tags da Coleção

{
    "id": "8798wdefs",
    "communityId": "8798wdefs",
    "companyId": "sd21fs5",
    "name": "Airdrop NFT",
    "description": "Distribuição de tokens não fungíveis",
    "type": "airdrop" | "sale" | "auction" | <others>,
    "contract": {
        "address": "0x1234567890abcdef12345678sssbcdef12345678",
        "network": "ethereum_mainnet" | "polygon_mainnet" | <others>,
        "pattern" : "ERC20" | "ERC721" | "ERC1155" | <others>,
        "ownerAddress": "0x1234567890abcdef12345678sssbcdef12345678",
        "methods": {
            "deploy": {
                "args": [/* argumentos do construtor do contrato em ordem e com tipo compatível */],
            },
            "balanceOf": {
                "methodABI": {/* ABI do método balanceOf */},            
            }        
        },
        "royalties": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
             }
        ],
        "split": [
            {
                "id": "2343d23d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 20
            },
            {
                "id": "2343ds3d234",
                "address": "0x1234567890abcdef1....78sssbcdef12345678",
                "percent": 80
             }
        ],
    }    
    "expirationDate": "2021-12-31T23:59:59Z",
    "startDate": "2021-01-01T00:00:00Z",
    "mainCurrency": "USD" | "BRL" | "ETH" | "MATIC" | <others>,
    "tags": ["ambiental", "arte", "empreeendedorismo"],
    "status": "private",
    "statusWeb3": "private"
    }
}

Gestão em Massa de Tokens da Coleção

Lista todos os tokens associadas à uma coleção

GET https://goblockchain.io/gotokens-api/v1/collections/:collectionId/tokens/manage

Nível de permissionamento necessário: company_admin, company_moderator, community_admin, community_moderator

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Query Parameters

NameTypeDescription

limit

String

Limite de resultados na busca

offset

String

Quantidade de resultados para avançar da busca

tags

Array

Tags do Token

[
    {
      "id":"5hws4eb18t0q",
      "tokenId": "1",
      "collectionId": "321",
      "supply": "10",
      "displayMediaUrl": "http://url.com/token",
      "displayMediaType": "image",
      "owners": [
        {
          "address": "0xer7s89gf4ger987tes978f",
          "quantity": "3"
        }
      ],
      "transactionType": "airdrop",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "status": "public",
      "statusWeb3": "deployed"
    },
    {
      "id":"a8rt9red1vb",
      "tokenId": "2",
      "collectionId": "321",
      "supply": "5",
      "displayMediaUrl": "http://url.com/token",
      "displayMediaType": "gif",
      "owners": [
        {
          "address": "0x73w49f8we1fwe849f8fea",
          "quantity": "1"
        },
        {
          "address": "0x36lutsmerkug87fsQ4R",
          "quantity": "2"
        }
      ],
      "transactionType": "airdrop",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "status": "private",
      "statusWeb3": "private"
    },
]

(JWT) Cadastro de tokens em massa para uma coleção

POST https://goblockchain.io/gotokens-api/v1/collections/:collectionId/tokens/manage

Nível de autorização necessário: company_admin, company_moderator, community_admin

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

Request Body

NameTypeDescription

tokens*

Array

Lista com tokens a serem cadastrados

[
    {
      "id":"5hws4eb18t0q",
      "tokenId": "1",
      "collectionId": "321",
      "supply": "10",
      "displayMediaUrl": "http://url.com/token",
      "displayMediaType": "image",
      "owners": [
        {
          "address": "0xer7s89gf4ger987tes978f",
          "quantity": "3"
        }
      ],
      "transactionType": "airdrop",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "status": "private",
      "statusWeb3": "private"
    },
    {
      "id":"a8rt9red1vb",
      "tokenId": "2",
      "collectionId": "321",
      "supply": "5",
      "displayMediaUrl": "http://url.com/token",
      "displayMediaType": "gif",
      "owners": [
        {
          "address": "0x73w49f8we1fwe849f8fea",
          "quantity": "1"
        },
        {
          "address": "0x36lutsmerkug87fsQ4R",
          "quantity": "2"
        }
      ],
      "transactionType": "airdrop",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "status": "private",
      "statusWeb3": "private"
    },
]

Gestão do contrato Web3

(JWT/Wallet) Deploy de Contrato na Web3

POST https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage/web3/deploy

Nível de autorização necessário: company_admin

É necessário um carteira com saldo vinculada ao usuário e a carteira precisa ter permissão de execução do método no contrato. Caso o contrato não possua campos próprios para owner no construtor, essa carteira será o primeiro owner do contrato.

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

(JWT/Wallet) Mint em lote de Tokens na Web3

POST https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage/web3/mint-batch

Nível de autorização necessário: company_admin

É necessário um carteira com saldo vinculada ao usuário e a carteira precisa ter permissão de execução do método no contrato. Caso o método não possua campos próprios para owner dos tokens recém criados, eles serão propriedade do contrato e será gerenciado pela carteira do owner do contrato.

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

(JWT/Wallet) Pausar um contrato na Web3

POST https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage/web3/stop

Nível de autorização necessário: company_admin

É necessário um carteira com saldo vinculada ao usuário. É necessário que o contrato possua esse método e a carteira precisa ter permissão de execução do método no contrato

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

(JWT/Wallet) Libera um contrato pausado na Web3

POST https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage/web3/start

Nível de autorização necessário: company_admin

É necessário um carteira com saldo vinculada ao usuário, é necessário que o contrato possua esse método e a carteira precisa ter permissão de execução do método no contrato.

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

Headers

NameTypeDescription

authorization*

Bearer

JWT

(JWT) Lista de métodos web3 disponíveis no contrato

GET https://goblockchain.io/gotokens-api/v1/collections/:collectionId/manage/web3/methods

Nível de autorização necessário: company_admin, community_admin

Path Parameters

NameTypeDescription

collectionId*

String

ID da Coleção

{
    "methods": {
        "balanceOf": {
            "methodABI": {/* ABI do método balanceOf */},
            "args": {
                "name": "walletAddress",
                "type": "string" 
        }        
    },
}