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
Headers
Content-Type
application/json
x-api-key
API_KEY
Query Parameters
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.
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
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 -X GET 'https://sandbox.api.labs.zelus.io/v1/wallet/nft/list?walletAddress=yourWalletAddress&retrieveAll=true' \
-H "x-api-key: YOUR_API_KEY"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}")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
Ensure to provide exactly one wallet identifier and appropriately handle the optional parameters based on the requirements.
You should set
includeMetadatatotrueif you want to retrieve the metadata of the NFTs (traits, image URL, etc).You should include either
contractIdsor bothcontractAddressesandblockchainif you want to filter the response for NFTs on certain contracts.You should set
retrieveAlltotrueif you want NFTs that are in the wallet but that you did not mint to the wallet to be included in the response.
Last updated
Was this helpful?