Wallets and Users

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

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.

Good to know: Wallet address and public key mean the same thing!

Creating and Storing UserWallets

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

POST https://api.rareful.io/v1/createOrFindUserWallet

Creates a new wallet or returns existing one

Headers

Name	Type	Description
API_KEY*	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
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.

200 New Non-Custodial Wallet Successfully Created

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

400 Request was malformed or parameters include wrong data types

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

401 Likely wrong or missing API Key

{
    "data": {},
    "status": 401,
    "message": "Not Authorized"
}

200: OK New Custodial Wallet Successfully Created

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

200: OK Existing User Found

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

500: Internal Server Error Something went wrong on our end! Email us at [e-mail]

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

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.

Find wallet credentials for one of your users

POST https://api.rareful.io/v1/findUserWallet

Fetches a user's associated wallet

Headers

Name	Type	Description
API_KEY*	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
user_id*	String	One of your users that has an existing wallet with Rareful (Required)

400: Bad Request Request was malformed or parameters include wrong data types

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

401: Unauthorized Likely wrong or missing API Key

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

200: OK User Found

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

500: Internal Server Error Something went wrong on our end

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

Fetch NFTs that are owned by one of your user's wallets.

POST https://api.rareful.io/v1/getUserWalletNFTs

Fetch a UserWallet's NFTs

Headers

Name	Type	Description
API_KEY*	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*	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*	String	Your user's unique id. Must be provided if public_key is not provided.

200: OK NFTs were found

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

401: Unauthorized Likely wrong or missing API Key

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

400: Bad Request Request was malformed or parameters include wrong data types

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

500: Internal Server Error Something went wrong on our end

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

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

POST https://api.rareful.io/v1/getUserWalletNFTsForSale

Fetch NFTs that are for sale from a specific wallet

Headers

Name	Type	Description
API_KEY*	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*	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

200: OK Listed Items are returned

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

400: Bad Request Request was malformed or parameters include wrong data types

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

401: Unauthorized Likely wrong or missing API Key

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

500: Internal Server Error Something went wrong on our end

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

Retrieve the private key of a custodial wallet

POST 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*	String	Your API Key can found on the dashboard, and will be used to authenticate all requests (Required)
SECRET_API_KEY*	String	Your SECRET_API Key can found on the dashboard, and will be used to authenticate high sensitivity requests (Required)
Content-Type*	String	application/json (Required)

Request Body

Name	Type	Description
user_id*	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

200: OK Wallet Found

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

400: Bad Request Request was malformed or parameters include wrong data types

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

401: Unauthorized Likely wrong or missing API Key

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

500: Internal Server Error Something went wrong on our end

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

Warning! Ensure the unlockUserWallet route is secure, as it provides access to the private keys of your users.

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

POST https://api.rareful.io/v1updateUserWalletKeys

Find and updates a user's wallet keys

Headers

Name	Type	Description
API_KEY*	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*	String	The new public key
user_id*	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

200: OK User Wallet Keys Updated

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

401: Unauthorized Likely wrong or missing API Key

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

400: Bad Request Request was malformed or parameters include wrong data types

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

500: Internal Server Error Something went wrong on our end

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

Updates the user ID for a UserWallet

POST https://api.rareful.io/v1updateUserWalletId

Find and updates a user wallet's ID

Headers

Name	Type	Description
API_KEY*	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*	String	The public key (address) you want to update (Required)
user_id*	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

200: OK User Wallet Keys Updated

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

401: Unauthorized Likely wrong or missing API Key

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

400: Bad Request Request was malformed or parameters include wrong data types

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

500: Internal Server Error Something went wrong on our end

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

Remove a UserWallet from the Rareful Server

POST 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.

Headers

Name	Type	Description
API_KEY*	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*	String	The NFT owner's wallet address. Must be provided if user_id is not provided
user_id*	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

200: OK User deleted

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

401: Unauthorized Likely wrong or missing API Key

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

400: Bad Request Request was malformed or parameters include wrong data types

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

500: Internal Server Error Something went wrong on our end

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