> 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/wallets-and-users.md).

# Wallets and Users

Endpoints cover creating new wallets, retrieving wallet credentials, fetching NFTs in a wallet, etc.

{% hint style="info" %}
**How we do it:** Each unique wallet public key on Rareful is tied to one unique user id. This is the UserWallet we will be referring to below. 
{% endhint %}

{% hint style="success" %}
**Good to know:** Wallet address and public key mean the same thing!
{% endhint %}

## Creating and Storing UserWallets

## Create a new user-wallet, or retrieve an existing one if the user id already has a wallet

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

Creates a new wallet or returns existing one

#### 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                                                                                                                                                                                                                                                                                                                                                           |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| user\_id      | string | A unique identifier for the user. For example an email address, a uuid, etc. This allows you to incorporate your existing user management system into Rareful. If provided, the wallet is generated and stored with this user id. In other routes you can retrieve wallet credentials with only a user id. If none is provided, one is generated and returned to you. |
| is\_custodial | Bool   | If True, the generated wallet will be custodial, and the private key will be securely stored on the Rareful server. Otherwise, the private key of the new wallet will be returned once, and it will be your responsibility to store it. If not provided, the default value is true.                                                                                   |
| force\_create | Bool   | If True, a new user will always be created, and any existing user-wallet will be replaced. Take care! This could result in a private key being lost.                                                                                                                                                                                                                  |

{% tabs %}
{% tab title="200 New Non-Custodial Wallet Successfully Created" %}

```javascript
{
    "data": {
        "public_key": "0xb7E18B77E7A64DaAB5C9F4A861184AEEb6F893C8",
        "user_id": "gkh9bH8MP1nEzW-_o6e0YQ",
        "private_key": "87445tvGRTVlwWECRwergvhrgvHBTrgttg4h6fd8f"
    },
    "status": 200,
    "message": "New User Created"
}
```

{% 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="200: OK New Custodial Wallet Successfully Created" %}

```javascript
{
    "data": {
        "public_key": "0xb7E18B77E7A64DaAB5C9F4A861184AEEb6F893C8",
        "user_id": "gkh9bH8MP1nEzW-_o6e0YQ",
        "private_key": "in_custody"
    },
    "status": 200,
    "message": "New User Created"
}
```

{% endtab %}

{% tab title="200: OK Existing User Found" %}

```javascript
{
    "data": {
        "public_key": "0xb7E18B77E7A64DaAB5C9F4A861184AEEb6F893C8",
        "user_id": "gkh9bH8MP1nEzW-_o6e0YQ",
        "private_key": "not stored"
    },
    "status": 200,
    "message": "User Found"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end! Email us at <dev@rareful.com>" %}

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

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Good to know:** If a user id is passed in that already has an associated wallet address the existing address will be returned unless you force a create.
{% endhint %}

## Find wallet credentials for one of your users

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

Fetches a user's associated wallet

#### 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                                                           |
| ------------------------------------------ | ------ | --------------------------------------------------------------------- |
| user\_id<mark style="color:red;">\*</mark> | String | One of your users that has an existing wallet with Rareful (Required) |

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

```javascript
{
    "data": {},
    "message": "User ID not provided",
    "status": 400
}
```

{% endtab %}

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

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

{% endtab %}

{% tab title="200: OK User Found" %}

```javascript
{
    "data": {
        "public_key": "0xb7E18B77E7A64DaAB5C9F4A861184AEEb6F893C8",
        "user_id": "gkh9bH8MP1nEzW-_o6e0YQ",
        "private_key": "in_custody"
    },
    "status": 200,
    "message": "User Found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Fetch NFTs that are owned by one of your user's wallets.&#x20;

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

Fetch a UserWallet's NFTs

#### 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                                                                                                                    |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| public\_key<mark style="color:red;">\*</mark> | String | The NFT owner's wallet address. Must be provided if user\_id is not provided.                                                  |
| blockchain                                    | String | The blockchain the NFTs are on. Options are \["binance", "polygon"], if none provided all NFTs across blockchains are fetched. |
| user\_id<mark style="color:red;">\*</mark>    | String | Your user's unique id. Must be provided if public\_key is not provided.                                                        |

{% tabs %}
{% tab title="200: OK NFTs were found" %}

```javascript
{
    "data": {
        "items": [
            {
                "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "metadata": "https://ipfs.io/ipfs/QmYfeFRtg4tq3upwsPw6xvrP75MYSqyv8E7wpkxNxE4EWr",
                "name": "Awesome NFT 5",
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "token_id": "45018383"
            },
            {
                "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "metadata": "https://ipfs.io/ipfs/QmVRrSZN82ZaLQahsCteJRUE3CiHgAsb6Bu1udMT7E5wUs",
                "name": "Awesome NFT",
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "token_id": "58509816"
            },
            {
                "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
                "image": "https://nftgo.mypinata.cloud/ipfs/QmXq4BBd4QTjSX8DEDN4Nj7kwmGL8fDndSrVpxukoesiyw",
                "metadata": "https://nftgo.mypinata.cloud/ipfs/QmVRrSZN82ZaLQahsCteJRUE3CiHgAsb6Bu1udMT7E5wUs",
                "name": "Awesome NFT 6",
                "owner_public_key": "0x899825b3c2339A2A3d738a933920E7C4F0d001Ff",
                "token_id": "48265175"
            }
        ]
    },
    "status": 200,
    "message": "NFTs were 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 Something went wrong on our end" %}

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

{% endtab %}
{% endtabs %}

## Fetch NFTs from one of your user's wallets that are currently for sale

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

Fetch NFTs that are for sale from a specific wallet

#### 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                                                                                        |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| public\_key<mark style="color:red;">\*</mark> | String | The NFT owner's wallet address. Must be provided if user\_id is not provided                       |
| network                                       | String | The network/blockchain the NFTs are on. Options are \["binance", "polygon"]. Defaults to "polygon" |
| user\_id                                      | String | Your user's unique id. Must be provided if public\_key is not provided                             |

{% tabs %}
{% tab title="200: OK Listed Items are returned" %}

```javascript
{
    "data": {
        "item": {
            "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"
        }
    },
    "status": 200,
    "message": "NFTs were 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 Something went wrong on our end" %}

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

{% endtab %}
{% endtabs %}

## Retrieve the private key of a custodial wallet

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

Pass in a user id or public key to find their associated private key

#### 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)                      |
| SECRET\_API\_KEY<mark style="color:red;">\*</mark> | String | Your SECRET\_API Key can found on the dashboard, and will be used to authenticate high sensitivity requests (Required) |
| Content-Type<mark style="color:red;">\*</mark>     | String | application/json (Required)                                                                                            |

#### Request Body

| Name                                       | Type   | Description                                                                  |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| user\_id<mark style="color:red;">\*</mark> | String | Your user's unique id. Must be provided if public\_key is not provided       |
| public\_key                                | String | The NFT owner's wallet address. Must be provided if user\_id is not provided |

{% tabs %}
{% tab title="200: OK Wallet Found" %}

```javascript
{
    "data": {
        "private_key": "0x97323019975ef7f7d9f9a725fac1d3281ad670b11d6d822b0b8208da5dedb6ff",
        "public_key": "0x4e077a6500a18663d22549D812fCd56A700f3193"
    },
    "status": 200,
    "message": "Handle this data with care!"
}
```

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

{% hint style="danger" %}
Warning! Ensure the unlockUserWallet route is secure, as it provides access to the private keys of your users.&#x20;
{% endhint %}

## Updates the wallet (private/public keys) for one of your users

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

Find and updates a user's wallet keys

#### 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                                                              |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| public\_key<mark style="color:red;">\*</mark> | String | The new public key                                                       |
| user\_id<mark style="color:red;">\*</mark>    | String | Your user's unique id whose wallet you want to update                    |
| force\_update                                 | Bool   | If True, any exists private key will be overwritten. (Defaults to False) |
| private\_key                                  | String | The new private key                                                      |

{% tabs %}
{% tab title="200: OK User Wallet Keys Updated" %}

```javascript
{
    "data": {
        "public_key": "0xF17196934cf2D4929F86FFe5F0091B4Fd00872da",
        "user_id": "7M6ShzLzaQ5AN9Gy-y2fwg"
    },
    "message": "success",
    "status": 200
}
```

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

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

{% endtab %}
{% endtabs %}

## Updates the user ID for a UserWallet

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

Find and updates a user wallet's ID

#### 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                                                                        |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------------- |
| public\_key<mark style="color:red;">\*</mark> | String | The public key (address) you want to update (Required)                             |
| user\_id<mark style="color:red;">\*</mark>    | String | The new user ID (Required)                                                         |
| force\_update                                 | Bool   | If True, if there is any existing user with the same UID, they will be overwritten |

{% tabs %}
{% tab title="200: OK User Wallet Keys Updated" %}

```javascript
{
    "data": {
        "public_key": "0x22e903502497fDf46eDdacC698d7584b5e87a39B",
        "user_id": "7M6ShzLzaQ5AN9Gy-y2fwe"
    },
    "message": "User id successfuly updated",
    "status": 200
}
```

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

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

{% endtab %}
{% endtabs %}

## Remove a UserWallet from the Rareful Server

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

Finds and deletes a UserWallet. Custodial users (private key stored) will not be deleted unless force\_delete is passed as True.&#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                                                                  |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| public\_key<mark style="color:red;">\*</mark> | String | The NFT owner's wallet address. Must be provided if user\_id is not provided |
| user\_id<mark style="color:red;">\*</mark>    | String | Your user's unique id. Must be provided if public\_key is not provided       |
| force\_delete                                 | Bool   | If True, the user will be deleted even if they have a stored private key     |

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

```javascript
{
    "data": {},
    "message": "success",
    "status": 200
}
```

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

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

{% endtab %}
{% endtabs %}