Getting started

Covering the basics from authentication to minting your first NFT.

What we cover in this guide

In this guide, we will explain how to authenticate to our API service, as well as create your first NFT. We will walk you through several endpoints to help you get started. We will cover the following topics:

  1. Authentication
  2. Creating a Contract
  3. Checking Contract Status
  4. Creating Token-type (NFT template)
  5. Checking Token-type Status
  6. Minting NFT
  7. Checking NFT Mint Status

Prerequisites

  1. You need a Venly business account, if you don't have one, click here to register in our Developer Portal, or follow our step-by-step guide, Getting Started with Venly.
  2. You need an active trial or paid subscription of the NFT-API. You can start a 30-day free trial for the NFT-API as shown below.
  3. You need your Client ID and Client Secret which can be obtained from the Portal as shown below.
Starting a trial subscription and obtaining a Client ID and Client Secret

Starting a trial subscription and obtaining a Client ID and Client Secret

๐Ÿ“˜

All the API calls for this guide run on a sandbox environment. You can test and experiment with API calls without causing any harm to the actual blockchain or data.

There are several ways to run API calls, but for this guide, you can use the API-Reference or Postman to execute the different endpoints.

1. Authenticating

To obtain a bearer token and authorize all API calls, you will need your Client ID and Client Secret. These credentials are necessary for authentication purposes.

๐Ÿ“˜

Click here to learn how to retrieve a bearer token and authenticate API calls.

Please note that the base path for all NFT API endpoints is https://nft-api-sandbox.venly.io

2. Creating a Contract

Let's start by defining your first contract. This contract will represent a collection for the NFTs. We will create a contract on the Polygon (MATIC) testnet chain.

๐Ÿ“˜

As the API calls are running in a sandbox environment, the contract will be created on a testnet chain. In this example we will create an NFT contract on the MATIC testnet chain.

Request Endpoint: reference

 POST /api/v2/contracts/deployments

Request Body:

ParameterDescriptionTypeRequired
nameThe name of your NFT collection/contractStringโœ…
descriptionThe description of your NFT collection/contractStringโœ…
imageThe image URL for your NFT collection/contract that will be displayedStringโœ…
externalUrlThis can be any link such as a link to your website, landing page, etc.Stringโœ…
chainThis is the blockchain on which you want to create the contract onStringโœ…
{
  "name": "NFT Collection",
  "description": "Sample description",
  "image": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
  "externalUrl": "www.venly.io",
  "chain": "MATIC"
}

Response Body:

๐Ÿ“˜

Save the result.id from the response body. This is the Deployment ID used to track the status of the contract creation request.

{
    "success": true,
    "result": {
        "name": "NFT Collection",
        "description": "Sample description",
        "id": "4c1a078e-1b48-4280-882c-d0cd1dbd9a8f",
        "secretType": "MATIC",
        "symbol": "NFCO",
        "externalUrl": "www.venly.io",
        "image": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
        "media": [],
        "transactionHash": "0xf2b1d8c0f993e51954ff7ce965dd5363497083254f3f67c1aafe932a40ccfe8f",
        "status": "PENDING",
        "storage": {
            "type": "cloud",
            "location": "https://metadata-staging.arkane.network/metadata/contracts/64265"
        },
        "contractUri": "https://metadata-staging.arkane.network/metadata/contracts/64265",
        "external_link": "www.venly.io"
    }
}

3. Check the status of the contract/collection

This endpoint is used to check the status of a contract/collection on v2. The {deploymentId} in the path is for tracking the status of contract creation. It is in the response body of the create contract/collection endpoint as result.id.

Request Endpoint: reference

GET /api/v2/contracts/deployments/{deploymentId}

Example Request

GET /api/v2/contracts/deployments/4c1a078e-1b48-4280-882c-d0cd1dbd9a8f

Response Body

๐Ÿ“˜

In the response body look for the result.status parameter. It can have three possible values:

  • SUCCEEDED
  • PENDING
  • FAILED
{
    "success": true,
    "result": {
        "name": "NFT Collection",
        "description": "Sample description",
        "address": "0xa90da02f49880320e4bb237c8ce0d2f4f42bfbd5",
        "id": "4c1a078e-1b48-4280-882c-d0cd1dbd9a8f",
        "secretType": "MATIC",
        "symbol": "NFCO",
        "externalUrl": "www.venly.io",
        "image": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
        "media": [],
        "transactionHash": "0xf2b1d8c0f993e51954ff7ce965dd5363497083254f3f67c1aafe932a40ccfe8f",
        "status": "SUCCEEDED",
        "storage": {
            "type": "cloud",
            "location": "https://metadata-staging.arkane.network/metadata/contracts/64265"
        },
        "contractUri": "https://metadata-staging.arkane.network/metadata/contracts/64265",
        "external_link": "www.venly.io"
    }
}

4. Creating Token-type

Next, we will create a token-type which serves as a template for minting NFTs. This means you just have to define the NFT template once with parameters like its name, image, attributes, etc, and then you can mint multiple NFTs directly to your end-users wallets.

Defining token types helps structure the information such as attributes and animationUrls.

Request Endpoint: reference

POST /api/v2/token-types/creations

Request Body:

ParameterDescriptionTypeRequired
secretTypeThe blockchain of the contractStringโœ…
contractAddressThe contract address under which you want to create the token-typeStringโœ…
creationsAn array of objects that can define one or multiple token-type detailsArray of objectsโœ…
creations.nameThe name of the token-typeStringโœ…
creations.descriptionThe description of the token-typeStringโŒ
creations.imageThe image URL for the token-type that will be displayedStringโŒ
{
  "secretType": "MATIC",
  "contractAddress": "0xf5b11b4f458cc12a7989a146c5db2e7d500e2241",
  "creations": [
    {
      "name": "My first NFT Token-type",
      "description": "Venly",
      "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png"
    }
  ]
}

Response Body:

๐Ÿ“˜

  • Save the result.creations.id from the response body. This is the token Creation ID and it's used to track the status of the token-type creation request.
  • The status attribute indicates the token-type creation status.
{
  "success": true,
  "result": {
    "creations": [
      {
        "id": "45cf858a-cb0d-4e31-b6e1-b3bf4c65d014",
        "status": "PENDING",
        "tokenTypeId": 5,
        "metadata": {
          "name": "My first NFT Token-type",
          "description": "Venly",
          "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
          "imagePreview": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
          "imageThumbnail": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
          "animationUrls": [],
          "attributes": [
            {
              "type": "system",
              "name": "tokenTypeId",
              "value": "5",
              "traitType": "Token Type ID",
              "trait_type": "Token Type ID"
            }
          ],
          "contract": {
            "address": "0xf5b11b4f458cc12a7989a146c5db2e7d500e2241",
            "name": "Test",
            "symbol": "TE",
            "image": "string",
            "imageUrl": "string",
            "image_url": "string",
            "description": "Testing",
            "externalLink": "www.venly.io",
            "external_link": "www.venly.io",
            "externalUrl": "www.venly.io",
            "external_url": "www.venly.io",
            "media": [],
            "type": "ERC_1155"
          },
          "fungible": false
        }
      }
    ]
  }
}

5. Check the status of token-type

This endpoint is used to check the status of token-type creation. The {creationId} in the path is for tracking the status of token-type creation. It is in the response body of the create token-type endpoint as result.id.

Request Endpoint: reference

GET /api/v2/token-types/creations/{creationId}

Example Request

GET /api/v2/token-types/creations/45cf858a-cb0d-4e31-b6e1-b3bf4c65d014

Response Body

๐Ÿ“˜

In the response body look for the result.status parameter. It can have three possible values:

  • SUCCEEDED
  • PENDING
  • FAILED
{
  "success": true,
  "result": {
    "id": "45cf858a-cb0d-4e31-b6e1-b3bf4c65d014",
    "status": "SUCCEEDED",
    "transactionHash": "0xd8a7677dadfb308be606746d6fd522f9b3361a6e81c09f41ceabd7abb2593407",
    "tokenTypeId": 5,
    "mints": [],
    "metadata": {
      "name": "My first NFT Token-type",
      "description": "Venly",
      "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
      "imagePreview": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
      "imageThumbnail": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
      "animationUrls": [],
      "attributes": [
        {
          "type": "system",
          "name": "tokenTypeId",
          "value": "5",
          "traitType": "Token Type ID",
          "trait_type": "Token Type ID"
        }
      ],
      "contract": {
        "address": "0xf5b11b4f458cc12a7989a146c5db2e7d500e2241",
        "name": "Test",
        "symbol": "TE",
        "image": "string",
        "imageUrl": "string",
        "image_url": "string",
        "description": "Testing",
        "externalLink": "www.venly.io",
        "external_link": "www.venly.io",
        "externalUrl": "www.venly.io",
        "external_url": "www.venly.io",
        "media": [],
        "type": "ERC_1155"
      },
      "fungible": false
    }
  }
}

6. Minting an NFT

Request Endpoint: reference

 POST /api/v2/contracts/deployments

Request Body:

ParameterParam TypeDescriptionTypeRequired
contractAddressBodyThe contract addressStringโœ…
secretTypeBodyThe blockchain of the contractStringโœ…
tokenTypeIdBodyThis is the ID of the token-type. You can get it from the response body when you create a token-type.Stringโœ…
destinationsBodyThe array which includes all the wallet addresses and the number of NFTs to mint per wallet addressArray of objectsโœ…
destinations.addressBodyThe wallet address to mint and send the NFTStringโœ…
destinations.amountBodyThe number of NFTs you want to mint and sendIntegerโœ…
{
  "contractAddress": "0xa90da02f49880320e4bb237c8ce0d2f4f42bfbd5",
  "secretType": "MATIC",
  "tokenTypeId": "1",
  "destinations": [
    {
      "address": "0x9282fc38931A3a613b8566b3E6a1027e49ABb712",
      "amount": 1
    }
  ]
}

๐Ÿ“˜

  • Make sure the destinations.address (wallet address) has the same chain as the contract. In this case, it should be a Polygon wallet(MATIC).
  • NOTE: The contractAddress, secretType (blockchain), and the tokenTypeId are defined in the request body.

Response Body:

๐Ÿ“˜

  • Under the mints array, you can find the id (mintId) for each minted NFT listed with the wallet address. This unique id can be used to track the status of the mint request.
  • The status attribute indicates the on-chain token mint status.
{
    "success": true,
    "result": {
        "mints": [
            {
                "id": "037d23c9-9163-4e16-894e-338e5b1628fe",
                "status": "PENDING",
                "destination": {
                    "address": "0x9282fc38931A3a613b8566b3E6a1027e49ABb712",
                    "amount": 1
                }
            }
        ],
        "metadata": {
            "name": "My first NFT Token-type",
            "description": "Venly",
            "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
            "imagePreview": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
            "imageThumbnail": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
            "animationUrls": [],
            "attributes": [
                {
                    "type": "system",
                    "name": "tokenTypeId",
                    "value": "1",
                    "traitType": "Token Type ID",
                    "trait_type": "Token Type ID"
                }
            ],
            "contract": {
                "address": "0xa90da02f49880320e4bb237c8ce0d2f4f42bfbd5",
                "name": "NFT Collection",
                "symbol": "NFCO",
                "image": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
                "imageUrl": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
                "image_url": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
                "description": "Sample description",
                "externalLink": "www.venly.io",
                "external_link": "www.venly.io",
                "externalUrl": "www.venly.io",
                "external_url": "www.venly.io",
                "media": [],
                "type": "ERC_1155"
            },
            "fungible": false
        }
    }
}

7. Check the status of NFT mints

This endpoint is used to check the status of NFT mints. The {mintId} in the path is for tracking the status of the NFT mint. It is in the response body of the Mint Fungible or Non-Fungible Tokens endpoint as result.mints.id.

Request Endpoint: reference

GET /api/v2/tokens/mints/{mintId}

Example Request

GET /api/v2/tokens/mints/037d23c9-9163-4e16-894e-338e5b1628fe

Response Body

๐Ÿ“˜

  • You can get the tokenId in the response body.
  • In the response body look for the result.status parameter. It can have three possible values:
    • SUCCEEDED
    • PENDING
    • FAILED
{
    "success": true,
    "result": {
        "id": "037d23c9-9163-4e16-894e-338e5b1628fe",
        "tokenId": 2,
        "status": "SUCCEEDED",
        "transactionHash": "0xafcf35390cb5dcfde8aad4e14cb15d7bdcb1ba9888430cd6d22bab37bf788183",
        "destination": {
            "address": "0x9282fc38931A3a613b8566b3E6a1027e49ABb712",
            "amount": 1
        },
        "metadata": {
            "name": "My first NFT Token-type",
            "description": "Venly",
            "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
            "imagePreview": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
            "imageThumbnail": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/StickFigureHi.png",
            "animationUrls": [],
            "attributes": [
                {
                    "type": "system",
                    "name": "tokenTypeId",
                    "value": "1",
                    "traitType": "Token Type ID",
                    "trait_type": "Token Type ID"
                },
                {
                    "type": "property",
                    "name": "mintNumber",
                    "value": "1",
                    "traitType": "Mint Number",
                    "trait_type": "Mint Number"
                }
            ],
            "contract": {
                "address": "0xa90da02f49880320e4bb237c8ce0d2f4f42bfbd5",
                "name": "NFT Collection",
                "symbol": "NFCO",
                "image": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
                "imageUrl": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
                "image_url": "https://techround.co.uk/wp-content/uploads/2022/01/Venly-logo.png",
                "description": "Sample description",
                "externalLink": "www.venly.io",
                "external_link": "www.venly.io",
                "externalUrl": "www.venly.io",
                "external_url": "www.venly.io",
                "media": [],
                "type": "ERC_1155"
            },
            "fungible": false
        }
    }
}