> For the complete documentation index, see [llms.txt](https://rareful.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rareful.gitbook.io/documentation/reference/api-reference/smart-contracts-and-collections.md).

# Smart Contracts and Collections

{% hint style="info" %}
**How we do it:** You are the owner of every smart contract created with the Rareful API. You can find your wallet details in the profile page of the dashboard.
{% endhint %}

## Working with Smart Contracts

## Deploy a new smart contract

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/deployContract`

Creates a new smart contract.

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json (Required)                                                                       |

#### Request Body

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contract\_name   | string | The name of the contract. ie. "Bored Ape Yacht Club".  (If none provided, the contract\_name is "Our Web3 Collection")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| contract\_symbol | string | The symbol that represents the contract. ie. "BAYC". (If none provided, the contract\_symbol is "OWC")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| contract\_type   | int    | <p>All contracts are standard ERC-721 compatible, but have different permissions and operators. Please refer to the "Our Smart Contracts" page to learn about the contracts in our library: <a href="https://rareful.gitbook.io/rareful-documentation/reference/about-nfts-and-smart-contracts/our-smart-contracts"><https://rareful.gitbook.io/rareful-documentation/reference/about-nfts-and-smart-contracts/our-smart-contracts></a></p><p>(If none provided, the contract\_type defaults to 1)</p><p></p>                                                                                                                                                                         |
| is\_default      | bool   | If is\_default is True, this contract becomes your default contract. This means it shows up first on your dashboard, and minting without specifying a contract address automatically mints to this default contract. (If none provided, is\_default defaults to False)                                                                                                                                                                                                                                                                                                                                                                                                                |
| description      | String | <p>The description for your contract/collection. This is not saved on the blockchain, but is useful to store if you want to describe the collection in your application. </p><p>ie. "A 10,000 item interstellar themed art collection." </p><p>(If none provided, the description defaults to "".)</p>                                                                                                                                                                                                                                                                                                                                                                                |
| cover\_url       | String | <p>A link to an image that acts as the background/cover of your contract/collection. This is not saved on the blockchain, but is useful to provide if you want to visually represent the collection in your application.  </p><p>ie. <a href="https://rareful-bucket.s3.us-east-2.amazonaws.com/public/4dTerrain.jpg"><https://rareful-bucket.s3.us-east-2.amazonaws.com/public/4dTerrain.jpg></a> </p><p>(If none provided, defaults to <a href="https://rareful-bucket.s3.us-east-2.amazonaws.com/public/QmbhQ5EftwTf8bmT5Pt9SriVQez9JfpY9XSZXfZEKucu4C.png"><https://rareful-bucket.s3.us-east-2.amazonaws.com/public/QmbhQ5EftwTf8bmT5Pt9SriVQez9JfpY9XSZXfZEKucu4C.png></a>)</p> |
| profile\_url     | String | <p>A link to an image that acts as the profile photo of your contract/collection. This is mostly for internal use. ie: </p><p><a href="https://rareful-bucket.s3.us-east-2.amazonaws.com/public/purple_ape.jpeg"><https://rareful-bucket.s3.us-east-2.amazonaws.com/public/purple_ape.jpeg></a>. </p><p>(If none provided, defaults to <a href="https://rareful-bucket.s3.us-east-2.amazonaws.com/public/QmZbbLJrH6DqRagT52x9aRtapuYjUsEw5rmzgqi6xmHreu.png"><https://rareful-bucket.s3.us-east-2.amazonaws.com/public/QmZbbLJrH6DqRagT52x9aRtapuYjUsEw5rmzgqi6xmHreu.png></a>)</p>                                                                                                   |
| blockchain       | String | <p>The blockchain/network the contract will be deployed on. The options are "polygon" or "ethereum". </p><p>(If none provided, the default is "polygon")</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

{% tabs %}
{% tab title="200 Contract Successfully deployed" %}

```javascript
{
    "data": {
        "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
        "owner_public_key": "0x582b7cb2B054A09b8Ee36f95Db285AB34EECED03",
        "transaction_hash": "0x61032bf9c94f2b76499ecf8bf0e26c1c27966fc1cf3deb31a92319b32c7841d4"
    },
    "status": 200,
    "message": "Contract Successfully deployed"
}
```

{% endtab %}

{% tab title="400 Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401 Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

## Get contracts you have deployed

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/getAllContracts`

Retrieve all the contracts you have deployed

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json (Required)                                                                       |

{% tabs %}
{% tab title="200: OK Contracts are found" %}

```javascript
{
    "data": {
        "contracts": [
            {
                "contract_address": "0x17F4F06f59D3328b23dED316359b18e141473851",
                "contract_name": "Community Collection",
                "cover_url": "https://gateway.pinata.cloud/ipfs/QmbhQ5EftwTf8bmT5Pt9SriVQez9JfpY9XSZXfZEKucu4C",
                "creation_date": "2022-07-06T16:57:03.310Z",
                "description": "My app's community collection",
                "owner_public_key": "0x7d23Ca0FCbE3cdabBa60251f25a1B7f17E9BDcc7",
                "profile_url": "https://gateway.pinata.cloud/ipfs/QmZbbLJrH6DqRagT52x9aRtapuYjUsEw5rmzgqi6xmHreu"
            },
            {
                "contract_address": "0x5A78801521Cb0A76BEda19494a3a7c91340C5F53",
                "contract_name": "Independent Collection",
                "cover_url": "https://gateway.pinata.cloud/ipfs/QmbhQ5EftwTf8bmT5Pt9SriVQez9JfpY9XSZXfZEKucu4C",
                "creation_date": "2022-07-06T16:54:58.854Z",
                "description": "A user's collection",
                "owner_public_key": "0x7d23Ca0FCbE3cdabBa60251f25a1B7f17E9BDcc7",
                "profile_url": "https://gateway.pinata.cloud/ipfs/QmZbbLJrH6DqRagT52x9aRtapuYjUsEw5rmzgqi6xmHreu"
            }
        ]
    },
    "status": 200,
    "message": "Contracts found"
}
```

{% endtab %}

{% tab title="400: Bad Request Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401: Unauthorized Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

## Fetch contract NFTs

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/getContractNFTs`

Fetch NFTs in a contract and return associated metadata and image links.&#x20;

#### Headers

| Name                                       | Type   | Description                                                                                       |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark> | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type                               | String | application/json (Required)                                                                       |

#### Request Body

| Name                                                | Type   | Description                                                                   |
| --------------------------------------------------- | ------ | ----------------------------------------------------------------------------- |
| contract\_address<mark style="color:red;">\*</mark> | String | The contract address for which you are fetching NFTs and metadata. (Required) |
| blockchain                                          | String | The blockchain this contract was minted on                                    |

{% tabs %}
{% tab title="200: OK Contract was found" %}

```javascript
{
    "data": {
        "blockchain": "polygon",
        "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
        "cover_photo": "https://gateway.pinata.cloud/ipfs/QmbhQ5EftwTf8bmT5Pt9SriVQez9JfpY9XSZXfZEKucu4C",
        "description": "",
        "item_count": 4,
        "items": [
            {
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "list_price": 0,
                "metadata": "https://ipfs.io/ipfs/QmYfeFRtg4tq3upwsPw6xvrP75MYSqyv8E7wpkxNxE4EWr",
                "name": "Awesome NFT 5",
                "owner_history": [
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff"
                ],
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "price_history": [
                    10
                ],
                "token_id": "45018383"
            },
            {
                "image": "https://ipfs.io/ipfs/QmcEfLMz7gyA7eKrmxBtHsfQWSXnCt5EztGbfAM9NN3Q1x",
                "list_price": 0,
                "metadata": "https://ipfs.io/ipfs/QmTPphzmuE1G6N1yNuzCFKLcVijUpBUaU4F2h96So6wPEd",
                "name": "My New NFT",
                "owner_history": [
                    "0x4e077a6500a18663d22549D812fCd56A700f3193"
                ],
                "owner_public_key": "0x4e077a6500a18663d22549D812fCd56A700f3193",
                "price_history": [
                    0
                ],
                "token_id": "67014279"
            },
            {
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "list_price": 0,
                "metadata": "https://ipfs.io/ipfs/QmVRrSZN82ZaLQahsCteJRUE3CiHgAsb6Bu1udMT7E5wUs",
                "name": "Awesome NFT",
                "owner_history": [
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff"
                ],
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "price_history": [
                    10
                ],
                "token_id": "58509816"
            },
            {
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "list_price": 0,
                "metadata": "https://nftgo.mypinata.cloud/ipfs/QmVRrSZN82ZaLQahsCteJRUE3CiHgAsb6Bu1udMT7E5wUs",
                "name": "Awesome NFT",
                "owner_history": [
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                    "0x4e077a6500a18663d22549D812fCd56A700f3193",
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff"
                ],
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "price_history": [
                    0,
                    10,
                    20
                ],
                "token_id": "48265175"
            }
        ],
        "name": "Magic Bear Syndicate",
        "owner": "0x582b7cb2B054A09b8Ee36f95Db285AB34EECED03",
        "profile_photo": "https://gateway.pinata.cloud/ipfs/QmZbbLJrH6DqRagT52x9aRtapuYjUsEw5rmzgqi6xmHreu",
        "symbol": "MBS"
    },
    "status": 200,
    "message": "Contract Found"
}
```

{% endtab %}

{% tab title="401: Unauthorized Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="400: Bad Request Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

## Fetch contract NFTs

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/getContractNFTsForSale`

Fetch all NFTs in a contract that are currently for sale.&#x20;

#### Headers

| Name                                       | Type   | Description                                                                                       |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark> | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type                               | String | application/json (Required)                                                                       |

#### Request Body

| Name                                                | Type   | Description                                                        |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------ |
| contract\_address<mark style="color:red;">\*</mark> | String | The contract address for which you are fetching NFTs and metadata. |

{% tabs %}
{% tab title="200: OK Contract was found" %}

```javascript
{
    "data": {
        "blockchain": "polygon",
        "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
        "cover_photo": "https://gateway.pinata.cloud/ipfs/QmbhQ5EftwTf8bmT5Pt9SriVQez9JfpY9XSZXfZEKucu4C",
        "description": "",
        "item_count": 4,
        "items": [
            {
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "list_price": 0,
                "metadata": "https://ipfs.io/ipfs/QmYfeFRtg4tq3upwsPw6xvrP75MYSqyv8E7wpkxNxE4EWr",
                "name": "Awesome NFT 5",
                "owner_history": [
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff"
                ],
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "price_history": [
                    10
                ],
                "token_id": "45018383"
            },
            {
                "image": "https://ipfs.io/ipfs/QmcEfLMz7gyA7eKrmxBtHsfQWSXnCt5EztGbfAM9NN3Q1x",
                "list_price": 0,
                "metadata": "https://ipfs.io/ipfs/QmTPphzmuE1G6N1yNuzCFKLcVijUpBUaU4F2h96So6wPEd",
                "name": "My New NFT",
                "owner_history": [
                    "0x4e077a6500a18663d22549D812fCd56A700f3193"
                ],
                "owner_public_key": "0x4e077a6500a18663d22549D812fCd56A700f3193",
                "price_history": [
                    0
                ],
                "token_id": "67014279"
            },
            {
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "list_price": 0,
                "metadata": "https://ipfs.io/ipfs/QmVRrSZN82ZaLQahsCteJRUE3CiHgAsb6Bu1udMT7E5wUs",
                "name": "Awesome NFT",
                "owner_history": [
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff"
                ],
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "price_history": [
                    10
                ],
                "token_id": "58509816"
            },
            {
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "list_price": 0,
                "metadata": "https://nftgo.mypinata.cloud/ipfs/QmVRrSZN82ZaLQahsCteJRUE3CiHgAsb6Bu1udMT7E5wUs",
                "name": "Awesome NFT",
                "owner_history": [
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                    "0x4e077a6500a18663d22549D812fCd56A700f3193",
                    "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff"
                ],
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "price_history": [
                    0,
                    10,
                    20
                ],
                "token_id": "48265175"
            }
        ],
        "name": "Magic Bear Syndicate",
        "owner": "0x582b7cb2B054A09b8Ee36f95Db285AB34EECED03",
        "profile_photo": "https://gateway.pinata.cloud/ipfs/QmZbbLJrH6DqRagT52x9aRtapuYjUsEw5rmzgqi6xmHreu",
        "symbol": "MBS"
    },
    "status": 200,
    "message": "Contract Found"
}
```

{% endtab %}

{% tab title="401: Unauthorized Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="400: Bad Request Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}