NFT Holdings

Query individual NFTs owned by specific addresses, with detailed token information and filtering capabilities.

`nftUsersTokens`

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.

note

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

nftUsersTokens​

Example Use Case: User's NFT Gallery​

Example Variables​

Example Query​

Example Response​

Arguments​

Fields​

NftUserTokenConnection​

NftToken (node)​

Enums​

Notes​