Chiliz ChainChiliz Labs

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.

Deprecated

DEPRECATED - Endpoint to get the list of nfts related to Smart Contract

get
Authorizations
Path parameters
smartContractIdstring · uuidRequired

Smart Contract Id to look for

Query parameters
locales[]string[]Optional

Locales used to translate the current entity. Using the Locale HTTP header should be preferred. The HTTP header version is used in priority if it is given

Default: ["en"]
pageinteger · integerOptional
limitinteger · integerOptional
orderBystring · enumOptionalPossible values:
cursorstringOptional
directionstring · enumOptionalPossible values:
paginationModestring · enumOptionalPossible values:
Responses
200
Successfully retrieved list of nft's ([simple paginationMode enabled](https://bookstack.chiliz.com/books/development-guides/page/pagination))
application/json
Responseall of
get
GET /nft/1.0.0/nfts/smartcontract/{smartContractId} HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

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

{
  "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": true,
    "id": "d6f09e6f-bea5-4db2-9e27-87c42ec08e00",
    "createdAt": "2025-07-01T04:11:25.884Z",
    "updatedAt": "2025-07-01T04:11:25.884Z"
  },
  "attributeValues": {
    "id": "d6f09e6f-bea5-4db2-9e27-87c42ec08e00",
    "value": "text",
    "maxValue": 1,
    "traitType": "text",
    "displayType": "text",
    "applyTo": "text",
    "attribute": []
  },
  "metadata": {
    "total_items": 588,
    "current_page": 2,
    "last_page": 4,
    "cursor": "text"
  }
}
Deprecated

DEPRECATED - Post a SmartContract

post
Authorizations
Body

Payload to create a SmartContract

namestringRequired

Name of the SmartContract, will be public

Example: SmartContract name
symbolstringRequired

Symbol of the SmartContract, will be public

Example: SYMBOLNAME
Responses
201
Successfully created a SmartContract
application/json
Responseall of
post
POST /nft/1.0.0/admin/nft/smart-contract HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "name": "SmartContract name",
  "symbol": "SYMBOLNAME"
}
201

Successfully created a SmartContract

{
  "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": "2025-07-01T04:11:25.884Z"
    }
  ]
}

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.

Deprecated

DEPRECATED - Post a CollectibleDefinition

post

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
Authorizations
Body

Payload to create a CollectibleDefinition

smartContractIdstring · uuidRequired

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

Example: b44b6691-ceeb-4b12-8a93-3c962acec538
partnerIdstring · uuidOptional

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

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

Name of the CollectibleDefinitin, will be stored as a CollectibleAttributeValue

Example: Definition name
descriptionstringOptional

Description of the CollectibleDefinition, will be stored as a CollectibleAttributeValue

Example: Definition description
animationUrlstringOptional

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

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

Link that related to the CollectibleDefinition, must have protocol https

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

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

Example: 10
commentstringOptional

Comment on the CollectibleDefinition

Example: Foo bar this is a comment
Responses
201
Successfully created a CollectibleDefinition
application/json
Responseall of
post
POST /nft/1.0.0/admin/nft/collectible-definition HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 437

{
  "smartContractId": "b44b6691-ceeb-4b12-8a93-3c962acec538",
  "partnerId": "f9d5eaae-230d-4bec-9d8e-51732ad6b664",
  "name": "Definition name",
  "description": "Definition description",
  "animationUrl": "https://nft.chiliz.com/foo-bar.gif",
  "assetUrl": "https://chiliz.com/foo-bar",
  "maxSupply": 10,
  "comment": "Foo bar this is a comment",
  "attributeValues": [
    {
      "attributeId": "7c7cc6da-f16d-4b92-aa0a-fc482b5c395c",
      "value": "Attribute value",
      "maxValue": "text"
    }
  ]
}
201

Successfully created a CollectibleDefinition

{
  "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": "2025-07-01T04:11:25.884Z"
    }
  ]
}

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.

Deprecated

DEPRECATED - Endpoint to create an upload request

post
Authorizations
Path parameters
collectibleIdstringRequired
Body

Payload to create a CollectibleDefinition

assetUrlstringRequired

Link that related to the CollectibleDefinition, must have protocol https

Example: https://chiliz.com/foo-bar.jpg
imageTypestring · enumRequired

imageType

Example: image/jpegPossible values:
Responses
201
Successfully uploaded asset
application/json
Responseall of
post
POST /nft/1.0.0/admin/nft/{collectibleId}/asset-upload HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "assetUrl": "https://chiliz.com/foo-bar.jpg",
  "imageType": "image/jpeg"
}
201

Successfully uploaded asset

{
  "data": [
    {
      "id": "text",
      "imageSourceId": "text",
      "entityName": "text",
      "entityId": "text",
      "mimeType": "text",
      "url": "text",
      "width": "text",
      "height": "text",
      "createdAt": "2025-07-01T04:11:25.884Z",
      "updatedAt": "2025-07-01T04:11:25.884Z",
      "imageVariations": [],
      "imageType": {
        "type": "text",
        "description": "text",
        "createdAt": "2025-07-01T04:11:25.884Z",
        "updatedAt": "2025-07-01T04:11:25.884Z"
      }
    }
  ]
}

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.

Deprecated

DEPRECATED - Mint a CollectibleDefinition

put

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

Authorizations
Path parameters
collectibleDefinitionstring · uuidRequired

Collectible Definition to mint

Body
Responses
201
Successfully minted new Collectibles
application/json
put
PUT /nft/1.0.0/admin/nft/{collectibleDefinition}/mint HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "recipients": [
    {
      "blockchainAddress": "text",
      "count": 1
    }
  ]
}
{
  "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"
          }
        }
      ]
    }
  }
}

Last updated