> 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/buying-selling-and-transfers.md).

# Buying, Selling, and Transfers

These endpoints include buying and selling NFTs, as well as listing them for sale, removing them from sale, and transferring them externally

## Buy, Sell, Transfer NFTs

## List an NFT for Sale

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

Lists an NFT for sale. This route is currency agnostic, whatever currency you use in App we will store, simply input a decimal value.&#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<mark style="color:red;">\*</mark> | String | application/json (Required)                                                                       |

#### Request Body

| Name                                                 | Type   | Description                                                                 |
| ---------------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| contract\_address<mark style="color:red;">\*</mark>  | String | The contract address the NFT was minted to (Required)                       |
| token\_id<mark style="color:red;">\*</mark>          | Int    | The token id of the NFT that is being listed for sale (Required)            |
| list\_price<mark style="color:red;">\*</mark>        | Int    | This is a number representing the price of the listed NFT (Required)        |
| blockchain                                           | String | The blockchain this NFT exists on                                           |
| owner\_user\_id<mark style="color:red;">\*</mark>    |        | The user id of the owner. Either user id or public key must be provided.    |
| owner\_public\_key<mark style="color:red;">\*</mark> | String | The public key of the owner. Either user id or public key must be provided. |

{% tabs %}
{% tab title="200 NFT has been listed for sale" %}

```javascript
{
    "data": {
        "for_sale": true,
        "list_price": 120
    },
    "status": 200,
    "message": "NFT has been listed for sale"
}
```

{% 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": "Not Authorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

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

{% endtab %}
{% endtabs %}

## Remove an NFT from Sale

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

Remove an NFT from Sale

#### 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\_address<mark style="color:red;">\*</mark> | string | The contract address the NFT was minted to (Required)            |
| token\_id<mark style="color:red;">\*</mark>         | Int    | The token id of the NFT that is being listed for sale (Required) |
| blockchain                                          | string | The blockchain this NFT exists on                                |

{% tabs %}
{% tab title="200 NFT has been delisted" %}

```javascript
{
    "data": {
        "for_sale": false
    },
    "status": 200,
    "message": "NFT has been delisted"
}
```

{% 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": "Not Authorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The list\_price can be in any currency, including cryptocurrency. Rareful is currency agnostic. We allow our clients to handle payments, but we can store and display the list price for ease of use.
{% endhint %}

## Execute the sale of an NFT including transferring the NFT to buyer

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

Sell NFT to buyer

#### 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 |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json                                                                       |

#### Request Body

| Name                                                     | Type   | Description                                                                   |
| -------------------------------------------------------- | ------ | ----------------------------------------------------------------------------- |
| contract\_address<mark style="color:red;">\*</mark>      | String | The contract address that the NFT was minted to                               |
| token\_id<mark style="color:red;">\*</mark>              | Int    | The token id of the NFT                                                       |
| owner\_user\_id<mark style="color:red;">\*</mark>        | String | The current owner's user id. Either user id or public key must be provided    |
| recipient\_user\_id<mark style="color:red;">\*</mark>    | String | The recipient's user id. Either user id or public key must be provided        |
| sale\_price                                              | String | If none is provided, the default will be the list price of the NFT            |
| blockchain                                               | String | The blockchain this NFT exists on                                             |
| owner\_public\_key<mark style="color:red;">\*</mark>     | String | The current owner's public key. Either user id or public key must be provided |
| recipient\_public\_key<mark style="color:red;">\*</mark> | String | The recipient's public key. Either user id or public key must be provided     |

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

```javascript
{
    "data": {
        "for_sale": false,
        "owner": "0x4e077a6500a18663d22549D812fCd56A700f3193"
    },
    "status": 200,
    "message": "NFT has been sold and transferred to the buyer"
}
```

{% 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 Something went wrong on our end" %}

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

{% endtab %}
{% endtabs %}

## Execute the transfer of an NFT

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

Transfer an NFT from an owner to a recipient. It will be ensured that the owner and recipient addresses input are valid, and that the owner does in fact own the NFT.&#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 |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json                                                                       |

#### Request Body

| Name                                                     | Type   | Description                                                                   |
| -------------------------------------------------------- | ------ | ----------------------------------------------------------------------------- |
| contract\_address<mark style="color:red;">\*</mark>      | String | The contract address that the NFT was minted to                               |
| token\_id<mark style="color:red;">\*</mark>              | Int    | The token id of the NFT                                                       |
| recipient\_user\_id<mark style="color:red;">\*</mark>    | String | The recipient's user id. Either user id or public key must be provided        |
| blockchain                                               | String | The blockchain this NFT exists on                                             |
| recipient\_public\_key<mark style="color:red;">\*</mark> | String | The recipient's public key. Either user id or public key must be provided     |
| owner\_public\_key<mark style="color:red;">\*</mark>     | String | The current owner's public key. Either user id or public key must be provided |
| owner\_user\_id<mark style="color:red;">\*</mark>        | String | The current owner's user id. Either user id or public key must be provided    |

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

```javascript
{
    "data": {
        "for_sale": false,
        "owner": "0x4e077a6500a18663d22549D812fCd56A700f3193"
    },
    "status": 200,
    "message": "NFT has been sold and transferred to the buyer"
}
```

{% 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 Something went wrong on our end" %}

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

{% endtab %}
{% endtabs %}