# NFT Collections

## Create a new NFT Collection

<mark style="color:green;">`POST`</mark> `https://api.nfty.dev/v1/collections`

This endpoint creates a new Collection of NFTs. NFTYverse will upload and host all the metadata and optionally the images and media as well. If you prefer to host the metadata and media yourself, please see the "Self-Hosted" version below.\
\
This will deploy a new ERC721 or ERC1155 smart contract for the NFTs and can be thought of as a logical grouping for all your NFTs. Most apps will create a single Collection such as "My App NFTs", but you could also create multiple different collections, such as "App Badges", "App Coins", "App Cards", etc.

#### Headers

| Name          | Type   | Description              |
| ------------- | ------ | ------------------------ |
| Authorization | string | Your authorization token |

#### Request Body

| Name                       | Type    | Description                                                                                                                                                                                                                                                                    |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mint\_supply\_count        | integer | Maximum number of NFTs that can be minted in this collection. Use it to limit supply and creating scarcity. ONLY applies to ERC721 tokens and is ignored for ERC1155 tokens. Passing in `0` or omitting this means you can mint an infinite number of NFTs in this collection. |
| name                       | string  | The name of this NFT Collection.                                                                                                                                                                                                                                               |
| symbol                     | string  | A symbol for this NFT Collection. Usually 3 or more capital letters.                                                                                                                                                                                                           |
| description                | string  | Contract-level metadata as defined here: <https://docs.opensea.io/docs/contract-level-metadata>                                                                                                                                                                                |
| image                      | string  | Contract-level metadata as defined here: <https://docs.opensea.io/docs/contract-level-metadata>                                                                                                                                                                                |
| external\_link             | string  | Contract-level metadata as defined here: <https://docs.opensea.io/docs/contract-level-metadata>                                                                                                                                                                                |
| seller\_fee\_basis\_points | integer | Contract-level metadata as defined here: <https://docs.opensea.io/docs/contract-level-metadata>                                                                                                                                                                                |
| fee\_recipient             | string  | Contract-level metadata as defined here: <https://docs.opensea.io/docs/contract-level-metadata>                                                                                                                                                                                |
| type                       | string  | The type of NFT contract you want to create. Either `ERC721` or `ERC1155`.                                                                                                                                                                                                     |
| new\_owner                 | String  | Specify the address of an optional new owner for the smart contract for this Collection. This allows you to control and manage the smart contract outside of NFTYverse. Make sure you have full control of the owner if you decide to use this parameter.                      |

{% tabs %}
{% tab title="200 Collection creation successfully initiated with the returned request id.

Since this is a blockchain transaction, the creation may not complete right away. You will receive a request id in the response, which you can save. Once the contract is deployed on the blockchain, you will receive a separate Webhook Event with the same request id. At that point, you can consider the transaction completed and update your product UI as needed. Before receiving the Webhook Event, you should consider the transaction as pending. You can also use the Requests API to check on the status." %}

```
{"request_id":"53e5079d941f14db8a24a8e8647e93071fdff93de9e424796010549fd3e573aa"}
```

{% endtab %}

{% tab title="422 Could not create Collection. Please make sure that the fields are correct." %}

```
{"error_code":"", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request POST \
     --url https://api.nfty.dev/v1/collections \
     --header 'Content-Type: application/json' \
     --header 'authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ==' \
     --data '{
       "name": "Token Name",
  	   "symbol": "TKN",
       "description": "This is a description of my NFT collection.",
       "image": "https://domain.com/image.png",
       "external_link": "https://mywebsite.com",
       "mint_supply_count": 1000,
  	   "type": "ERC721"
       }'

```

#### Example Response:

```
{"request_id":"96c71219efed57b38068fc3fe3fcdbb9e4f41041f5d1fe8ea8b830dd3bd19586"}
```

## Create a new NFT Collection (Self-Hosted)

<mark style="color:green;">`POST`</mark> `https://api.nfty.dev/v1/collections`

This endpoint creates a new "Self-Hosted" Collection of NFTs. "Self-Hosted" means that you will be hosting the metadata and images yourself and will pass in the URIs (`base_uri` and `collection_uri`) to the API. If you prefer that we host the metadata for you, please see above.\
\
This will deploy a new ERC721 or ERC1155 smart contract for the NFTs and can be thought of as a logical grouping for all your NFTs. Most apps will create a single Collection such as "My App NFTs", but you could also create multiple different collections, such as "App Badges", "App Coins", "App Cards", etc.

#### Headers

| Name          | Type   | Description              |
| ------------- | ------ | ------------------------ |
| Authorization | string | Your authorization token |

#### Request Body

| Name                  | Type    | Description                                                                                                                                                                                                                                                                    |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mint\_supply\_account | integer | Maximum number of NFTs that can be minted in this collection. Use it to limit supply and creating scarcity. ONLY applies to ERC721 tokens and is ignored for ERC1155 tokens. Passing in `0` or omitting this means you can mint an infinite number of NFTs in this collection. |
| name                  | string  | The name for this NFT Collection.                                                                                                                                                                                                                                              |
| symbol                | string  | A symbol for this NFT Collection. Usually 3 or more capital letters.                                                                                                                                                                                                           |
| base\_uri             | string  | For ERC721 NFTs, this is the base URI for the token metadata. It is prepended to the token ID to generate each token's unique metadata URI. For ERC1155 NFTs, you should include the string `{id}` in the base\_uri where you want the token ID to be inserted.                |
| collection\_uri       | string  | This is the URI to the metadata for this NFT Collection.                                                                                                                                                                                                                       |
| type                  | string  | The type of NFT contract you want to create. Either `ERC721` or `ERC1155`.                                                                                                                                                                                                     |
| new\_owner            | String  | Specify the address of an optional new owner for the smart contract for this Collection. This allows you to control and manage the smart contract outside of NFTYverse. Make sure you have full control of the owner if you decide to use this parameter.                      |

{% tabs %}
{% tab title="200 Collection creation successfully initiated with the returned request id.

Since this is a blockchain transaction, the creation may not complete right away. You will receive a request id in the response, which you can save. Once the contract is deployed on the blockchain, you will receive a separate Webhook Event with the same request id. At that point, you can consider the transaction completed and update your product UI as needed. Before receiving the Webhook Event, you should consider the transaction as pending. You can also use the Requests API to check on the status." %}

```
{"request_id":"53e5079d941f14db8a24a8e8647e93071fdff93de9e424796010549fd3e573aa"}
```

{% endtab %}

{% tab title="422 Could not create Collection. Please make sure that the fields are correct." %}

```
{"error_code":"", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request POST \
     --url https://api.nfty.dev/v1/collections \
     --header 'Content-Type: application/json' \
     --header 'authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ==' \
     --data '{
       "name": "Token Name",
  	   "symbol": "TKN",
       "base_uri": "https://base.com/",
       "collection_uri": "https://contract.com/721",
  	   "type": "ERC721"
       }'

```

#### Example Response:

```
{"request_id":"96c71219efed57b38068fc3fe3fcdbb9e4f41041f5d1fe8ea8b830dd3bd19586"}
```

## View your NFT Collections

<mark style="color:blue;">`GET`</mark> `https://api.nfty.dev/v1/collections`

This endpoint allows you to see all of your successfully created Collections. If you recently created a Collection and it is not listed yet, then the blockchain transaction may still be pending.

#### Headers

| Name          | Type   | Description              |
| ------------- | ------ | ------------------------ |
| Authorization | string | Your authorization token |

{% tabs %}
{% tab title="200 Returns a list of Collections that have been created." %}

```
[
  {
    "address":"0xb9bf61b55f66afc64fd7fbf7fa4fea4e2e4c5fdd",
    "name":"ERC721 Token",
    "symbol":"TKN",
    "base_uri":"https://base.com/",
    "collection_uri":"https://contract.com/721",
    "type":"ERC721",
    "timestamp":"2021-08-30T07:34:17.516Z"
  },
  {
    "address":"0xcbec1a2ae881487fa642041cbd1bfe4b690af269",
    "name":"ERC1155 Tokens",
    "symbol":"TKNS",
    "base_uri":"https://base.com/{id}",
    "collection_uri":"https://contract.com/1155",
    "type":"ERC1155",
    "timestamp":"2021-08-30T07:35:26.151Z"
  }
]
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request GET \
     --url https://api.nfty.dev/v1/collections \
     --header 'Content-Type: application/json' \
     --header 'authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ=='
```

#### Example Response:

```
[
  {
    "address":"0xb9bf61b55f66afc64fd7fbf7fa4fea4e2e4c5fdd",
    "name":"ERC721 Token",
    "symbol":"TKN",
    "base_uri":"https://base.com/",
    "collection_uri":"https://contract.com/721",
    "mint_supply_count":1000, 
    "type":"ERC721",
    "timestamp":"2021-08-30T07:34:17.516Z"
  },
  {
    "address":"0xcbec1a2ae881487fa642041cbd1bfe4b690af269",
    "name":"ERC1155 Tokens",
    "symbol":"TKNS",
    "base_uri":"https://base.com/{id}",
    "collection_uri":"https://contract.com/1155",
    "mint_supply_count":0,
    "type":"ERC1155",
    "timestamp":"2021-08-30T07:35:26.151Z"
  }
]
```

## List NFTs in a Collection

<mark style="color:blue;">`GET`</mark> `https://api.nfty.dev/v1/collections/:address`

This endpoint returns the NFT items currently in this NFT Collection. The address must be associated with a Collection that you created.

#### Path Parameters

| Name                                      | Type   | Description                |
| ----------------------------------------- | ------ | -------------------------- |
| address<mark style="color:red;">\*</mark> | string | Address of this Collection |

#### Query Parameters

| Name   | Type    | Description                                              |
| ------ | ------- | -------------------------------------------------------- |
| limit  | integer | How many results to return. The maximum is 30.           |
| offset | integer | The offset of the returned results. So you can paginate. |

#### Headers

| Name                                            | Type   | Description               |
| ----------------------------------------------- | ------ | ------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Your authentication token |

{% tabs %}
{% tab title="200 List of NFTs in this wallet, with metadata link information. For ERC1155 tokens, the amount is also included. If you mint a certain ERC1155 token\_id multiple times, each minting will be shown as a separate entry." %}

```
# For ERC721 tokens, there is no "amount"
{
"address":"0xb9bf61b55f66afc64fd7fbf7fa4fea4e2e4c5fdd",
"assets":
 [
  {"token_id":1,"token_url":"https://nfty.com/1","timestamp":"2021-08-30T07:35:26.151Z"},
  {"token_id":2,"token_url":"https://nfty.com/2","timestamp":"2021-08-30T07:35:26.151Z"},
  {"token_id":3,"token_url":"https://nfty.com/3","timestamp":"2021-08-30T07:35:26.151Z"}
 ]
}

# For ERC1155 tokens, "amount" is also included
{
"address":"0xcbec1a2ae881487fa642041cbd1bfe4b690af269",
"assets":
 [
  {"token_id":1,"amount":50,"token_url":"https://base.com/{id}","timestamp":"2021-08-30T07:43:13.602Z"},
  {"token_id":1,"amount":50,"token_url":"https://base.com/{id}","timestamp":"2021-08-30T07:45:04.029Z"},
  {"token_id":2,"amount":50,"token_url":"https://base.com/{id}","timestamp":"2021-08-30T07:46:04.029Z"}
 ]
}
```

{% endtab %}

{% tab title="422 Could not list the contents of this wallet - with error information. Make sure that the address given is in fact associated with an NFT Wallet that your app controls." %}

```
{"error_code":"", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request GET \
     --url https://api.nfty.dev/v1/collections/0xb9bf61b55f66afc64fd7fbf7fa4fea4e2e4c5fdd \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ=='
```

#### Example Response:

```
{
"address":"0xb9bf61b55f66afc64fd7fbf7fa4fea4e2e4c5fdd",
"assets":
 [
  {"token_id":1,"token_url":"https://nfty.com/1","timestamp":"2021-08-30T07:35:26.151Z"},
  {"token_id":2,"token_url":"https://nfty.com/2","timestamp":"2021-08-30T07:35:26.151Z"},
  {"token_id":3,"token_url":"https://nfty.com/3","timestamp":"2021-08-30T07:35:26.151Z"}
 ]
}
```