# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rareful.gitbook.io/documentation/reference/api-reference/smart-contracts-and-collections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.