Single NFT Holdings
Query individual NFTs owned by specific addresses, with detailed token information and filtering capabilities.
Try it nownftUsersTokens
Takes an array of addresses
as input, with optional parameters for network
, standard
, and minEstimatedValueUsd
. It returns comprehensive NFT holdings data including:
- Individual NFT tokens owned
- Balance and quantity information
- Collection metadata
- Current valuations
- Ownership history
- Media/trait details
Example Use Case: User's NFT Gallery
Let's say you want to display all NFTs owned by a user or group of users. Start by passing the owners
addresses you want to query. Then return details about each NFT including its collection
information, mediasV3
for displaying images, and the current estimatedValue
. You can filter results by network
or minimum value, and use pagination with first
and after
arguments to load results in batches.
If you notice some NFTs are not returned, this is likely due to Zapper's internal spam detection — which is conservative and enabled by default. To bypass this and get all NFTs, set bypassHidden
to true
.
Example Variables
{
"owners": ["0x52c8ff44260056f896e20d8a43610dd88f05701b" ],
"network": "ETHEREUM_MAINNET",
"first": 12
}
Example Query
query UserNftTokens(
$owners: [Address!]!
$network: Network
$first: Int = 24
$after: String
$search: String
$minEstimatedValueUsd: Float
) {
nftUsersTokens(
owners: $owners
network: $network
first: $first
after: $after
search: $search
minEstimatedValueUsd: $minEstimatedValueUsd
) {
edges {
node {
# Basic token information
tokenId
name
description
# Collection information
collection {
name
address
network
nftStandard
type
supply
holdersCount
floorPrice {
valueUsd
valueWithDenomination
denomination {
symbol
network
address
}
}
medias {
logo {
thumbnail
}
}
}
# Media assets
mediasV3 {
images(first: 3) {
edges {
node {
original
thumbnail
blurhash
large
width
height
mimeType
fileSize
}
}
}
animations(first: 1) {
edges {
node {
original
mimeType
}
}
}
}
# Value and pricing information
estimatedValue {
valueUsd
valueWithDenomination
denomination {
symbol
network
}
}
lastSale {
valueUsd
valueWithDenomination
denomination {
symbol
}
}
# Traits/attributes
traits {
attributeName
attributeValue
supplyPercentage
supply
}
}
# Ownership information
balance
balanceUSD
ownedAt
balances {
balance
account {
address
displayName {
value
}
}
}
# Valuation strategy information
valuationStrategy
}
# Pagination information
pageInfo {
hasNextPage
endCursor
startCursor
hasPreviousPage
}
}
}
Example Response
{
"data": {
"nftUsersTokens": {
"edges": [
{
"node": {
"tokenId": "10407",
"name": "Lil Pudgy #10407",
"description": "Lil Pudgys are a collection of 22,222 randomly generated NFTs minted on Ethereum.",
"collection": {
"name": "LilPudgys",
"address": "0x524cab2ec69124574082676e6f654a18df49a048",
"network": "ETHEREUM_MAINNET",
"nftStandard": "ERC_721",
"type": "GENERAL",
"supply": "21904",
"holdersCount": "9973",
"floorPrice": {
"valueUsd": 1766.4198588442998,
"valueWithDenomination": 0.94242,
"denomination": {
"symbol": "ETH",
"network": "ethereum",
"address": "0x0000000000000000000000000000000000000000"
}
},
"medias": {
"logo": {
"thumbnail": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fcollections%2Fethereum%2F0x524cab2ec69124574082676e6f654a18df49a048%2Flogo.png&width=100&checksum=2ec79"
}
}
},
"mediasV3": {
"images": {
"edges": [
{
"node": {
"original": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fmedias%2Ffa856d9f7907ea90f93067a80cfe2a84be04242e834306ddcbe25876438a8684.png&checksum=9b5f8",
"thumbnail": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fmedias%2Ffa856d9f7907ea90f93067a80cfe2a84be04242e834306ddcbe25876438a8684.png&width=100&checksum=dd923",
"blurhash": "UPQ4c{$j_$+^{0n%CRX8s;jtS0bFtlbHv#n%",
"large": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fmedias%2Ffa856d9f7907ea90f93067a80cfe2a84be04242e834306ddcbe25876438a8684.png&width=500&checksum=1d489",
"width": 2700,
"height": 2700,
"mimeType": "image/png",
"fileSize": 181886
}
}
]
},
"animations": {
"edges": []
}
},
"estimatedValue": {
"valueUsd": 2043.0356381871,
"valueWithDenomination": 1.09,
"denomination": {
"symbol": "ETH",
"network": "ethereum"
}
},
"lastSale": {
"valueUsd": 29.98951395504,
"valueWithDenomination": 0.016,
"denomination": {
"symbol": "ETH"
}
},
"traits": [
{
"attributeName": "Skin",
"attributeValue": "Volcanic Tan",
"supplyPercentage": 7.213294375456537,
"supply": "1580"
},
{
"attributeName": "Right Flipper",
"attributeValue": "None",
"supplyPercentage": 127.9309715120526,
"supply": "28022"
},
{
"attributeName": "Background",
"attributeValue": "Red",
"supplyPercentage": 16.50383491599708,
"supply": "3615"
},
{
"attributeName": "Left Flipper",
"attributeValue": "None",
"supplyPercentage": 180.52867056245435,
"supply": "39543"
},
{
"attributeName": "Body",
"attributeValue": "Turtleneck Blue",
"supplyPercentage": 2.049853907962016,
"supply": "449"
},
{
"attributeName": "Head",
"attributeValue": "Flat Cap Blue",
"supplyPercentage": 2.5200876552227904,
"supply": "552"
},
{
"attributeName": "Face",
"attributeValue": "Cute",
"supplyPercentage": 35.8427684441198,
"supply": "7851"
}
]
},
"balance": 1,
"balanceUSD": 2038.627,
"ownedAt": null,
"balances": [
{
"balance": "1",
"account": {
"address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
"displayName": {
"value": "0xjasper.eth"
}
}
}
],
"valuationStrategy": "ESTIMATED_VALUE"
}
],
"pageInfo": {
"hasNextPage": true,
"endCursor": "MjAzOC42MjcwMDAwLTYyMzEyMzk1",
"startCursor": "MjAzOC42MjcwMDAwLTYyMzEyMzk1",
"hasPreviousPage": false
}
}
}
}
Arguments
Argument | Description | Type | Required |
---|---|---|---|
owners | Array of addresses to query NFTs for | [Address!]! | Yes |
network | Filter NFTs by specific network | Network | No |
minEstimatedValueUsd | Minimum USD value threshold for NFTs | Float | No |
search | Search string to filter NFTs | String | No |
collectionIds | Array of specific collection IDs to include | [ID!] | No |
standard | Filter by NFT standard (ERC721/ERC1155) | NftStandard | No |
onlyHidden | Show only hidden NFTs | Boolean | No |
first | Number of NFTs to return (default: 24) | Int | No |
after | Cursor for pagination | String | No |
withOverrides | Include value overrides | Boolean | No |
Fields
NftUserTokenConnection
Field | Description | Type |
---|---|---|
edges | Array of NFT edges | [NftUserTokenEdge!]! |
pageInfo | Pagination information | PageInfo! |
NftToken (node)
Field | Description | Type |
---|---|---|
id | Unique identifier | ID! |
tokenId | Token ID within collection | String! |
name | Token name | String! |
description | Token description | String |
supply | Total token supply | BigDecimal! |
circulatingSupply | Circulating supply | BigDecimal! |
holdersCount | Number of token holders | BigDecimal! |
socialLinks | Social media links | [SocialLink!]! |
collection | Parent collection data | NftCollection! |
traits | Token attributes | [NftTrait!]! |
mediasV2 | Legacy media assets | [NftMediaV2!]! |
mediasV3 | Current media assets | NftMedias! |
estimatedValue | Current value estimate | NftValueDenomination |
lastSale | Last sale details | NftValueDenomination |
rarityRank | Token rarity ranking (deprecated) | Int |
lastSaleEth | Last sale in ETH (deprecated) | BigDecimal |
estimatedValueEth | Estimated value in ETH (deprecated) | BigDecimal |
isHidden | Hidden status | Boolean! |
Enums
enum NftValuationStrategy {
TOP_OFFER
ESTIMATED_VALUE
OVERRIDE
}
Notes
- Supports pagination for handling large NFT collections
- Filter by network, value, and NFT standard
- Returns comprehensive token metadata including estimated values
- Includes ownership information and acquisition dates
- Supports both ERC721 and ERC1155 tokens