Wallet NFTs

This API endpoint allows you to retrieve a list of NFTs that are present in a specified wallet. The response is not restricted to a single contract and includes various optional parameters to filter and customize the results.

Endpoint Details

Description	Data
API Name	getWalletNftList
HTTP Method	GET
URL	/v1/wallet/nft/list

Request

Headers

Key	Value
Content-Type	application/json
x-api-key	API_KEY

Query Parameters

Parameter	Type	Description
walletAddress	string, optional	One of wallet identifier. A wallet address for an Ethereum wallet - compatible with any EVM-based blockchain.
walletId	string, optional	One of wallet identifier. A unique, anonymized identifier for a user's wallet.
email	string, optional	One of wallet identifier. The email address of the user that is associated with their wallet
phone	string, optional	One of wallet identifier. The phone number of the user that is associated with their wallet. Include a + and the country code.
includeMetadata	Boolean	Default: false. Toggle whether the metadata for each NFT should be included in the response.
contractIds	string	Contract IDs separated by a comma. If this parameter is not specified, then results for all contracts will be returned.
contractAddresses	string, optional	Contract addresses separated by ','
retrieveAll	Boolean	Default: false. Toggle whether all NFTs in the specified wallet should be retrieved, or only ones that you minted to the wallet.

This request is very flexible and can be used to retrieve all NFTs in a wallet, or only NFTs that match a specific set of criteria. You must include one of the following to identify the wallet you want to retrieve the NFTs of:

• email

• phone

• walletId

• walletAddress

Response

The response will contain an array of NFT metadata.

{
    result: INftData[]
    | error?: IResponseError   // Optional error information
}

export interface INftTraits {
  displayType: number,
  traitType: string,
  value?: any
}

export interface INftMetadata {
  externalUrl?: string;
  traits: INftTraits[];
  name: string;
  description: string;
  imageUrl: string;
  thumbnailUrl?: string;
  imageMimeType: string;
  thumbnailMimeType?: string;
}

export interface INftData {
  contract: Address;
  tokenId: string;
  hash: string;
  blockchain: string;
  metadata?: INftMetadata
}

Succefull response

{
  "result": [
    {
      "contract": "0x509ac6e18fe97f7d96fce1a2ac3c7e6c4b9dde6d",
      "nftTokenId": "1",
      "blockchain": "polygon",
      "metadata": {
        "name": "SMOOTH Pass",
        "description": "This pass is your key to unlock rewards and more through Smooth's cutting-edge loyalty platform",
        "imageUrl": "https://assets.nft.zelus.io/Smooth-Collectibles-dev/1/image1.png",
        "imageMimeType": "image/png",
        "thumbnailUrl": "https://assets.nft.zelus.io/Smooth-Collectibles-dev/1/image1.png",
        "thumbnailMimeType": "image/png",
        "externalUrl": "https://zelus.io",
        "traits": [
          {
            "displayType": "number",
            "traitType": "Member Since",
            "value": 2023
          },
          {
            "displayType": "string",
            "traitType": "Member Tier",
            "value": "Pearl"
          }
        ]
      }
    },
    {
      "contract": "0x509ac6e18fe97f7d96fce1a2ac3c7e6c4b9dde6d",
      "nftTokenId": "2",
      "blockchain": "polygon",
      "metadata": {
        "name": "Smooth Reward #1: Cosmetics Discount",
        "description": "The first reward unlocked with your SMOOTH loyalty pass. 5% off on all cosmetics!",
        "imageUrl": "https://assets.nft.zelus.io/Smooth-Collectibles-dev/2/image2.png",
        "imageMimeType": "image/png",
        "thumbnailUrl": "https://assets.nft.zelus.io/Smooth-Collectibles-dev/2/image2.png",
        "thumbnailMimeType": "image/png",
        "externalUrl": "https://zelus.io",
        "traits": [
          {
            "displayType": "string",
            "traitType": "Type",
            "value": "Recurring"
          },
          {
            "displayType": "string",
            "traitType": "Discount",
            "value": "5%"
          },
          {
            "displayType": "string",
            "traitType": "Expires",
            "value": "Never"
          }
        ]
      }
    }
  ]
}

Error Messages

• Validation error

  • { "code: 400, "message": "Validation error: \"value\" must contain at least one of [email, phone, walletId, walletAddress]" }

• Contracts not found

  • { "code: 400, "message": "Contracts not found" }

• User wallet not found

  • { "code: 400, "message": "User wallet not found" }

Examples

CURL

curl -X GET 'https://sandbox.api.labs.zelus.io/v1/wallet/nft/list?walletAddress=yourWalletAddress&retrieveAll=true' \
     -H "x-api-key: YOUR_API_KEY"

Python

import requests

url = "https://sandbox.api.labs.zelus.io/v1/wallet/nft/list"
headers = {
    "x-api-key": "YOUR_API_KEY"
}
params = {
    "walletAddress": "yourWalletAddress",
    "retrieveAll": "true"
}

response = requests.get(url, headers=headers, params=params)
nft_metadata = response.json() # Assuming INftMetadata[]
print(f"NFT Metadata: {nft_metadata}")

NodeJS

const axios = require('axios');

const url = "https://sandbox.api.labs.zelus.io/v1/wallet/nft/list";
const headers = {
    "x-api-key": "YOUR_API_KEY"
};
const params = {
    walletAddress: "yourWalletAddress",
    retrieveAll: "true"
};

axios.get(url, { headers: headers, params: params }).then(response => {
    const nft_metadata = response.data; // Assuming INftMetadata[]
    console.log(`NFT Metadata: ${JSON.stringify(nft_metadata)}`);
}).catch(error => {
    console.error('Error:', error.response.data);
});

Notes

1. Ensure to provide exactly one wallet identifier and appropriately handle the optional parameters based on the requirements.

2. You should set includeMetadata to true if you want to retrieve the metadata of the NFTs (traits, image URL, etc).

3. You should include either contractIds or both contractAddresses and blockchain if you want to filter the response for NFTs on certain contracts.

4. You should set retrieveAll to true if you want NFTs that are in the wallet but that you did not mint to the wallet to be included in the response.