Guides

Get Users NFTs

Suggest Edits

📘

Full code example

GraphQL API Full Example

This query allows you to find what NFTs a user owns. It also allows you to query what they own by contract address to see which specific NFTs a user owns in a given collection and even to search by collection name or symbol. Data for NFT tokens and collections is fetched onchain and indexed by the API. If any NFTs are missing, it means they haven't been indexed (yet).

API details

  • If you are using testnet this endpoint will only allow you to query Polygon Amoy (chainId: 80002)
  • If you are using mainnet this endpoint will only allow you to query ethereum mainnet (chainId: 1) and polygon mainnet (chainId: 137)

Below is the overview of the entire interface but we dig into specific queries below.

{
  "data": {
    "nfts": {
      "items": [
        {
          "contract": {
            "address": "0x54439D4908A3E19356F876aa6022D67d0b3B12d6",
            "chainId": 80002
          },
          "contractType": "ERC721",
          "totalSupply": "1",
          "tokenId": "5742",
          "owner": {
              "amount": 1,
              "address": "0x54BE3a794282C030b15E43aE2bB182E14c409C5e"
            }
          ],
          "collection": {
            "name": "Origin Stories 1: Mad Clown, Sad Town",
          	"symbol": "ORIGIN1"
          },
          "metadata" {
            "name": "Origin Stories 1: Mad Clown, Sad Town",
            "description": "Before she was a tough-as-nails lead member of the PUNKS crew, Courtney had humble beginnings. Okay, she was always tough as nails, but to follow her dreams she had to carve her own path. Coming from a small town, Courtney had to go it alone, overcome major fears and doubts, and finally take a major leap of faith to make it in… ORIGIN CITY.",
            "externalURL": "ipfs://QmP7vzEULM45qZkYnTdejrDhprEM9xmCNHztaNgffEZvcm",
            "attributes": [],
            "image": "ipfs://QmP7vzEULM45qZkYnTdejrDhprEM9xmCNHztaNgffEZvcm"
          }
        }
      ],
      "pageInfo": {
        "prev": null,
        "next": null
      }
    }
  }
}

type Query { 
	nfts(request: NFTsRequest!): NFTsResult!
}

input NftsRequestWhere {
  # used to query for the NFT name or symbol
  query: String
  # filter by profile
  forProfileId: ProfileId
  # filter by evm address, one of forProfileId or forAddress is required!
  forAddress: EvmAddress
  # the chain ids to look for NFTs in (defaults to polygon and ethereum)
  chainIds: [ChainId!]
  # whether to exclude follower NFTs or not (defaults to true)
  excludeFollowers: Boolean
  # search only for nfts of specific collections 
  includeCollections: [NetworkAddressInput!]
  # exclude collections from results (note you can only use only *one* of include and exclude filters
  excludeCollections: [NetworkAddressInput!]
}  

input NftsRequest {
  where: NftsRequestWhere!,
  limit: Int,
  cursor: Cursor
}

input NetworkAddressInput {
  address: EvmAddress!
  chainId: ChainId!
}

# Paginated nft results
type PaginatedNftsResult {
  items: [Nft!]!
  pageInfo: PaginatedResultInfo!
}

# The nft type
type Nft {
  tokenId: TokenId!
  contentURI: URI!
  contract: NetworkAddress!
  contractType: NftContractType!
  totalSupply: String!
  collection: NftCollection!
  metadata: NftMetadata!
  owner: Owner!
}

# Nft Collection type
type NftCollection {
  # The contract info, address and chain id
  contract: NetworkAddress!

  # Collection name
  name: String!

  # Collection symbol
  symbol: String!

  # Collection base URI for token metadata
  baseUri: URI

  # Collection ERC type
  contractType: NftContractType!

  # Collection verified status
  verified: Boolean!
}

Now you see the base query let's look at how we can use different request parameters to request different NFTs for the user.

Get all NFTs a profile owns

To do this just set forProfileId to the profileId you want to query for their NFTs.

query Nfts {
  nfts(request: {
    where: {
    	forProfileId: "0x01"
      chainIds:[ 1, 137 ]
      excludeFollowers:true
    }
  }
) {
    items {
      tokenId
      contentURI
      contract {
        address
        chainId
      }
      tokenId
      contractType
      totalSupply
      collection {
        contract {
          address
          chainId
        }
        name
        symbol
        baseUri
        contractType
        verified
      }
      metadata {
        name
        description
        externalURL
        attributes {
          displayType
          traitType
          value
        }
        image {
          rawURI
          optimized {
            url
            mimeType
            width
            height
          }
        }
        animationUrl
      }
      owner {
        amount
        address
      }
    }
  }
}

{
  "data": {
    "nfts": {
       "items": [
        {
          "contract": {
            "address": "0x54439D4908A3E19356F876aa6022D67d0b3B12d6",
            "chainId": 80001
          },
          "contractType": "ERC721",
          "totalSupply": "1",
          "tokenId": "5742",
          "owner": {
              "amount": 1,
              "address": "0x54BE3a794282C030b15E43aE2bB182E14c409C5e"
            }
          ],
          "collection": {
            "name": "Origin Stories 1: Mad Clown, Sad Town",
          	"symbol": "ORIGIN1"
          },
          "metadata" {
            "name": "Origin Stories 1: Mad Clown, Sad Town",
            "description": "Before she was a tough-as-nails lead member of the PUNKS crew, Courtney had humble beginnings. Okay, she was always tough as nails, but to follow her dreams she had to carve her own path. Coming from a small town, Courtney had to go it alone, overcome major fears and doubts, and finally take a major leap of faith to make it in… ORIGIN CITY.",
            "externalURL": "ipfs://QmP7vzEULM45qZkYnTdejrDhprEM9xmCNHztaNgffEZvcm",
            "attributes": [],
            "image": "ipfs://QmP7vzEULM45qZkYnTdejrDhprEM9xmCNHztaNgffEZvcm"
          }
        }
      ],
      "pageInfo": {
        "prev": null,
        "next": null
      }
    }
  }
}

Get NFTs of a collection a wallet address owns

To do this just set the forAddress to the ethereum address you want to query for their NFTs and set the contractAddress of the NFT you wish to filter it on.

query Nfts($request: NFTsRequest!) {
  nfts(request: {
    where: {
      forAddress: "0x54be3a794282c030b15e43ae2bb182e14c409c5e",
      includeCollections: ["0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"],
      chainIds: [1]
    }   
    limit: 10,
  }) {
    items {
      tokenId
      contentURI
      contract {
        address
        chainId
      }
      tokenId
      contractType
      totalSupply
      collection {
        contract {
          address
          chainId
        }
        name
        symbol
        baseUri
        contractType
        verified
      }
      metadata {
        name
        description
        externalURL
        attributes {
          displayType
          traitType
          value
        }
        image {
          rawURI
          optimized {
            url
            mimeType
            width
            height
          }
        }
        animationUrl
      }
      owner {
        amount
        address
      }
    }
  }
}

{
  "data": {
    "nfts": {
       "items": [
        {
          "contract": {
            "address": "0x54439D4908A3E19356F876aa6022D67d0b3B12d6",
            "chainId": 80001
          },
          "contractType": "ERC721",
          "totalSupply": "1",
          "tokenId": "5742",
          "owner": {
              "amount": 1,
              "address": "0x54BE3a794282C030b15E43aE2bB182E14c409C5e"
            }
          ],
          "collection": {
            "name": "Origin Stories 1: Mad Clown, Sad Town",
          	"symbol": "ORIGIN1"
          },
          "metadata" {
            "name": "Origin Stories 1: Mad Clown, Sad Town",
            "description": "Before she was a tough-as-nails lead member of the PUNKS crew, Courtney had humble beginnings. Okay, she was always tough as nails, but to follow her dreams she had to carve her own path. Coming from a small town, Courtney had to go it alone, overcome major fears and doubts, and finally take a major leap of faith to make it in… ORIGIN CITY.",
            "externalURL": "ipfs://QmP7vzEULM45qZkYnTdejrDhprEM9xmCNHztaNgffEZvcm",
            "attributes": [],
            "image": "ipfs://QmP7vzEULM45qZkYnTdejrDhprEM9xmCNHztaNgffEZvcm"
          }
        }
      ],
      "pageInfo": {
        "prev": null,
        "next": null
      }
    }
  }
}

Search a profile's NFTs by collection name

query Nfts($request: NFTsRequest!) {
  nfts(request: {
    where: {
      forAddress: "0x54be3a794282c030b15e43ae2bb182e14c409c5e",
      query: "Apes"
      chainIds: [1]
    }   
    limit: 10,
  }) {
    items {
      tokenId
      contentURI
      contract {
        address
        chainId
      }
      tokenId
      contractType
      totalSupply
      collection {
        contract {
          address
          chainId
        }
        name
        symbol
        baseUri
        contractType
        verified
      }
      metadata {
        name
        description
        externalURL
        attributes {
          displayType
          traitType
          value
        }
        image {
          rawURI
          optimized {
            url
            mimeType
            width
            height
          }
        }
        animationUrl
      }
      owner {
        amount
        address
      }
    }
  }
}

Using LensClient SDK

Example use.

const result = await lensClient.nfts.fetch({
  where: {
    chainIds: [80002],
    forAddress: '0xa5653e88D9c352387deDdC79bcf99f0ada62e9c6',
  }
  limit: 10,
}),

Updated 13 days ago