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

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.
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.
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

/nfts/smartcontract/{smartContractId}

Authorizations

OAuth2implicitRequired

Authorization URL:

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)

application/json

get

/nfts/smartcontract/{smartContractId}

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": "2026-05-07T17:00:50.028Z",
    "updatedAt": "2026-05-07T17:00:50.028Z"
  },
  "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

/admin/nft/smart-contract

Authorizations

OAuth2implicitRequired

Authorization URL:

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

post

/admin/nft/smart-contract

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": "2026-05-07T17:00:50.028Z"
    }
  ]
}

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

/admin/nft/collectible-definition

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

OAuth2implicitRequired

Authorization URL:

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

post

/admin/nft/collectible-definition

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": "2026-05-07T17:00:50.028Z"
    }
  ]
}

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

/admin/nft/{collectibleId}/asset-upload

Authorizations

OAuth2implicitRequired

Authorization URL:

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

post

/admin/nft/{collectibleId}/asset-upload

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": "2026-05-07T17:00:50.028Z",
      "updatedAt": "2026-05-07T17:00:50.028Z",
      "imageVariations": [],
      "imageType": {
        "type": "text",
        "description": "text",
        "createdAt": "2026-05-07T17:00:50.028Z",
        "updatedAt": "2026-05-07T17:00:50.028Z"
      }
    }
  ]
}

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

/admin/nft/{collectibleDefinition}/mint

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

OAuth2implicitRequired

Authorization URL:

Path parameters

collectibleDefinitionstring · uuidRequired

Collectible Definition to mint

Body

Responses

201

Successfully minted new Collectibles

application/json

400

Bad Request

application/json

put

/admin/nft/{collectibleDefinition}/mint

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 1 year ago

hashtagGlossary

hashtagPrerequisites

hashtagSteps to mint an NFT

hashtag1. Create a smart contract

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

hashtagDEPRECATED - Post a SmartContract

hashtag2. Create a collection

hashtagDEPRECATED - Post a CollectibleDefinition

CollectibleDefinition summary

attributeValues

hashtag3. Upload your asset(s) to the collection

hashtagDEPRECATED - Endpoint to create an upload request

hashtag4. Mint the collection

hashtagDEPRECATED - Mint a CollectibleDefinition

Glossary

Prerequisites

Steps to mint an NFT

1. Create a smart contract

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

DEPRECATED - Post a SmartContract

2. Create a collection

DEPRECATED - Post a CollectibleDefinition

3. Upload your asset(s) to the collection

DEPRECATED - Endpoint to create an upload request

4. Mint the collection

DEPRECATED - Mint a CollectibleDefinition