NFT minting endpoints

NFT minting is a bit more complex than other endpoints, because it implies to write data directly on-chain.

This means that:

• You need a wallet,

• You have to pay chain fees (gas),

• You need to know where you want to mint the NFT you will create.

Glossary

• Minting: Writing new things (wallets, smart contracts, tokens) on-chain.

• Fee: When you mint something, you create a transaction on the chain, and this generate fees (also called "chain fees", "gas fees" or "transaction fees") for using the services.

• Wallet: The blockchain wallet where you funds are stored, and to which your smart contracts are linked.

• Smart contract: A standardised piece of code that will be executed on-chain in order to create transactions. In the present case, you will be using our NFT smart contract in order to generate new NFTs.

• Sender: Your wallet, where the NFTs are created.

• Recipient: The wallet where the NFTs will be minted.

Prerequisites

1. As with all other Socios.com APIs, you need an access to our API manager. If you are not using any other Socios.com APIs, you can authenticate via the OAuth - Client Credentials Flow.

2. You need to inform us, the Socios.com team, that you want to specifically use the NFT minting feature. This way we can generate a wallet for you in order to store the necessary CHZ to pay the fees and start minting you first NFTs.

3. You need to add funds in your wallet to pay the gas fees.

Steps to mint an NFT

1. Create a smart contract

You have two possibilities here:

• mint a smart contract;

• reuse an already minted smart contract.

Usually, for a new collection, we recommend to mint a new smart contract.

Endpoint to get the list of nfts related to Smart Contract

GEThttps://api-public.socios.com/nft/1.0.0/nfts/smartcontract/{smartContractId}

Authorization

default

Path parameters

smartContractId*string (uuid)

Smart Contract Id to look for

Query parameters

Response

200

Successfully retrieved list of nft's (simple paginationMode enabled)

Body

application/json

idstring (uuid)

The Id of the nft

Example: "d6f09e6f-bea5-4db2-9e27-87c42ec08e00"

summaryobject

statusstring

smartContractobject

attributeValuesobject

metadataone of

PaginationWithDetailedPaginationMode (object)PaginationWithSimplePaginationMode (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-public.socios.com/nft/1.0.0/nfts/smartcontract/{smartContractId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "d6f09e6f-bea5-4db2-9e27-87c42ec08e00",
  "summary": {
    "name": "My NFT",
    "description": "My NFT description",
    "imageUrl": "https://foo.bar/baz.png",
    "animationUrl": "https://foo.bar/baz.gif",
    "externalUrl": "https://foo.bar/my-nft",
    "backgroundColor": "51FF00",
    "totalSupply": 10,
    "metadataUrl": "https://foo.bar/my-nft/metadata.json",
    "blockchainTokenId": "text",
    "lastTransferredAt": "text",
    "supplyPosition": 1
  },
  "status": "text",
  "smartContract": {
    "name": "External SmartContract",
    "blockchainType": "DEPRECATED - ethereum_mainnet",
    "networkType": "polygon",
    "isVerified": false,
    "id": "d6f09e6f-bea5-4db2-9e27-87c42ec08e00",
    "createdAt": "2024-11-21T06:27:27.337Z",
    "updatedAt": "2024-11-21T06:27:27.337Z"
  },
  "attributeValues": {
    "id": "d6f09e6f-bea5-4db2-9e27-87c42ec08e00",
    "value": "text",
    "traitType": "text",
    "displayType": "text",
    "applyTo": "text",
    "attribute": []
  },
  "metadata": {
    "total_items": 588,
    "current_page": 2,
    "last_page": 4,
    "cursor": "text"
  }
}

Post a SmartContract

POSThttps://api-public.socios.com/nft/1.0.0/admin/nft/smart-contract

Authorization

default

Body

application/json

JSON payload to create a smartContract

name*string

Name of the SmartContract, will be public

Example: "SmartContract name"

symbol*string

Symbol of the SmartContract, will be public

Example: "SYMBOLNAME"

Response

201

Successfully created a SmartContract

Body

application/json

dataarray of NFTCollectibleDefinitionDTO (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-public.socios.com/nft/1.0.0/admin/nft/smart-contract', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "SmartContract name",
      "symbol": "SYMBOLNAME"
    }),
});
const data = await response.json();

Response

201

{
  "data": [
    {
      "id": "text",
      "attributeValues": [
        {
          "id": "text",
          "attribute": {
            "id": "text",
            "name": "text",
            "fieldName": "text",
            "category": "text",
            "code": "text"
          },
          "value": "text",
          "maxValue": "text",
          "displayType": "text",
          "applyTo": "all"
        }
      ],
      "status": "text",
      "smartContract": {
        "name": "text",
        "blockchainType": "ethereum_mainnet",
        "networkType": "ethereum"
      },
      "createdAt": "2024-11-21T06:27:27.337Z"
    }
  ]
}

2. Create a collection

A collection is like a draft of your minting, where you collect all attributes of your futur NFT.

Take into consideration that creating a smart contract might take some time (approximately 2-3 minutes). If you try to create a collection before your smart contract is created you will receive the error "the smart contract is not enabled". In this case, just wait and try again after a couple of minutes.

Post a CollectibleDefinition

Only the smartContractId, maxSupply and attributeValues are required, the attributeValues can be empty.

The values provided are sanitized to ensure they are valid. For example the value for an url will be checked to ensure it is a well-formed url, starting with https. If the value seems invalid, an error is returned.

The partnerId, name, description, animationUrl and externalUrl are stored as CollectibleAttributeValues.

CollectibleDefinition summary

The most significant information about the CollectibleDefinition are shown in the summary property.

Here we find the CollectibleAttributeValues of importance, like the name, description, imageUrl, animationUrl, externalUrl, backgroundColor, supply and partnerId. If the CollectibleDefinition has no value set for those attributes, they won't show up in the summary.

Alongside these CollectibleAttributeValues, we find other important properties, like the maxSupply and metadataUrl

If a CollectibleAttributeValue shows up in the summary, it is hidden from the list of attributeValues found below in the response.

The CollectibleDefinition summary has an imageUrl and metadataUrl, these values cannot be set, they are generated when creating the CollectibleDefinition, using the id that will be generated.

attributeValues

The attributeValues property is a list of extra CollectibleAttributes values we want to set for this CollectibleDefinition.

For example, we could set the value for the attribute scarcity:

{
     ...
     "attributeValues": [
         {
             "attributeId": "42b6a636-d393-4a9d-aac6-4c759ae8543c", # The actual id may vary
             "value": "rare"
         }
     ]
}

If the CollectibleAttribute value you want to set handles having a max value, the max value can be provided.

If the CollectibleAttribute has a default max value, and if no max value is given in the CollectibleAttributeValue, the CollectibleAttribute's default max value will be used.

Here no CollectibleAttributes are created, only CollectibleAttributeValues are. A CollectibleAttributeValue defines the value of a CollectibleAttribute for a given CollectibleDefinition.

Error codes

• 588f02a6-59c5-4e88-b165-a9036143320a the smart contract does not exist
• e51cdbd3-43c1-4fa6-a2e3-5cddd1df668d the smart contract is not enabled
• a01adced-bbb9-4156-96b4-10d8d7bb217a the smart contract must be owned by the retailer
• 6ce3cb08-5fe6-404c-9d1e-715edce2cfbe the partner does not exist or is inactive
• dde3c06a-ccea-4f2b-9db3-7cbfda55f732 the attribute value cannot be set on the CollectibleDefinition level
• 0cfaf8a3-c998-4adf-87bc-a823e80f2eae the attribute cannot have a maxValue
• 1232769b-5ba0-4156-9698-296a6d43c18a the attribute value sanitization failed, the value is invalid for the attribute

POSThttps://api-public.socios.com/nft/1.0.0/admin/nft/collectible-definition

Authorization

default

Body

application/json

NFT Collectible JSON data to create a new NFT Collectible.

smartContractId*string (uuid)

Id of the Smartcontract to use. Should have the status enabled and belong to the retailer

Example: "b44b6691-ceeb-4b12-8a93-3c962acec538"

partnerIdstring (uuid)

Id of the Partner to use. Should have the status active

Example: "f9d5eaae-230d-4bec-9d8e-51732ad6b664"

namestring

Name of the CollectibleDefinitin, will be stored as a CollectibleAttributeValue

Example: "Definition name"

descriptionstring

Description of the CollectibleDefinition, will be stored as a CollectibleAttributeValue

Example: "Definition description"

animationUrlstring

Link to an animation for the CollectibleDefinition, must have protocol https

Example: "https://nft.chiliz.com/foo-bar.gif"

assetUrlstring

Link that related to the CollectibleDefinition, must have protocol https

Example: "https://chiliz.com/foo-bar"

maxSupply*integer

Number of Collectible that can be minted from this CollectibleDefinition. Must at least 1

Example: 10

commentstring

Comment on the CollectibleDefinition

Example: "Foo bar this is a comment"

attributeValues*array of NFTPostAttributeValue (object)

List of CollectibleAttributeValues to set for CollectibleAttributes

Response

201

Successfully created a CollectibleDefinition

Body

application/json

dataarray of NFTCollectibleDefinitionDTO (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-public.socios.com/nft/1.0.0/admin/nft/collectible-definition', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "attributeValues": [
        {
          "attributeId": "7c7cc6da-f16d-4b92-aa0a-fc482b5c395c",
          "value": "Attribute value"
        }
      ],
      "maxSupply": 10,
      "smartContractId": "b44b6691-ceeb-4b12-8a93-3c962acec538"
    }),
});
const data = await response.json();

Response

201

{
  "data": [
    {
      "id": "text",
      "attributeValues": [
        {
          "id": "text",
          "attribute": {
            "id": "text",
            "name": "text",
            "fieldName": "text",
            "category": "text",
            "code": "text"
          },
          "value": "text",
          "maxValue": "text",
          "displayType": "text",
          "applyTo": "all"
        }
      ],
      "status": "text",
      "smartContract": {
        "name": "text",
        "blockchainType": "ethereum_mainnet",
        "networkType": "ethereum"
      },
      "createdAt": "2024-11-21T06:27:27.337Z"
    }
  ]
}

3. Upload your asset(s) to the collection

Once the collection is created, you can attach your media asset(s) (images or video) to it.

Endpoint to create an upload request

POSThttps://api-public.socios.com/nft/1.0.0/admin/nft/{collectibleId}/asset-upload

Authorization

default

Path parameters

collectibleId*string

Body

application/json

NFT Collectible asset upload

assetUrl*string

Link that related to the CollectibleDefinition, must have protocol https

Example: "https://chiliz.com/foo-bar.jpg"

imageType*enum

imageType

Example: "image/jpeg"

image/jpegimage/jpg,image/png,image/webp,image/gif,image/svg+xml,

Response

201

Successfully uploaded asset

Body

application/json

dataarray of NFTUploadRequestDTO (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-public.socios.com/nft/1.0.0/admin/nft/{collectibleId}/asset-upload', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "assetUrl": "https://chiliz.com/foo-bar.jpg",
      "imageType": "image/jpeg"
    }),
});
const data = await response.json();

Response

201

{
  "data": [
    {
      "id": "text",
      "imageSourceId": "text",
      "entityName": "text",
      "entityId": "text",
      "mimeType": "text",
      "url": "text",
      "width": "text",
      "height": "text",
      "createdAt": "2024-11-21T06:27:27.337Z",
      "updatedAt": "2024-11-21T06:27:27.337Z",
      "imageVariations": [],
      "imageType": {
        "type": "text",
        "description": "text",
        "createdAt": "2024-11-21T06:27:27.337Z",
        "updatedAt": "2024-11-21T06:27:27.337Z"
      }
    }
  ]
}

4. Mint the collection

Now that everything is reading, you can mint the collection on your wallet or your user's wallet(s) depending of your needs.

Mint a CollectibleDefinition

Triggers the creation of the actual Collectibles (NFTs).

The payload is a list of recipients for the Collectible, and the number of Collectible to mint for this recipient.

The CollectibleDefinition can be seen as a template, or mold, from which we can create 1 or multiple Collectibles.

The number of Collectibles that can be minted from a CollectibleDefinition is defined by its maxSupply.

The response is the list of the newly created Collectibles, they will be actually minted by the blockchain a bit later, at this point the Collectible status will move to minted

PUThttps://api-public.socios.com/nft/1.0.0/admin/nft/{collectibleDefinition}/mint

Authorization

default

Path parameters

collectibleDefinition*string (uuid)

Collectible Definition to mint

Body

application/json

recipientsarray of object

Response

201400

Successfully minted new Collectibles

Body

application/json

dataNFTMintCollectibleResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-public.socios.com/nft/1.0.0/admin/nft/{collectibleDefinition}/mint', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201400

{
  "data": {
    "mintedCollectibles": {
      "count": 1,
      "collectibles": [
        {
          "id": "text",
          "summary": {
            "name": "text",
            "description": "text",
            "imageUrl": "text",
            "animationUrl": "text",
            "externalUrl": "text",
            "backgroundColor": "text",
            "blockchainTokenId": "text"
          },
          "status": "text",
          "smartContract": {
            "name": "text",
            "blockchainType": "ethereum_mainnet",
            "networkType": "ethereum"
          },
          "currentOwner": {
            "blockchainType": "ethereum_mainnet",
            "blockchainAddress": "0xCdAf105009F5b00Ab0211628473296Be03886F7B",
            "type": "external",
            "networkType": "ethereum"
          }
        }
      ]
    }
  }
}