nfts

API Context

Endpoint: https://api.onesource.io/federation/{chain}/graphql Auth Header: x-bp-token: BP-{YOUR_API_KEY} Method: POST | Content-Type: application/json

Search and filter NFTs across all contracts with pagination. Supports cross-contract search by name.

Schema Definition

nfts(
  first: Int = 10
  after: Cursor
  where: NFTFilter
  orderBy: NFTOrderBy
  orderDirection: OrderDirection
): NFTList!

Arguments

Argument	Type	Description
first	Int scalar	Maximum number of results to return (default: 10, max: 100).
after	Cursor scalar	Cursor for pagination. Pass the endCursor from a previous query to get the next page.
where	NFTFilter input	Filter criteria for NFTs, including contract filters for cross-contract search.
orderBy	NFTOrderBy enum	Field to sort results by.
orderDirection	OrderDirection enum	Sort direction (ascending or descending).

Return Type

Type	Description
NFTList! object	Paginated list of individual NFTs.

Common Use Cases

• Build NFT marketplace browse pages by listing NFTs across collections with filtering, sorting, and pagination.
• Search for NFTs by name using nameLike for discovery features and search bars.
• Browse a specific collection's NFTs by filtering with contract: { address: "0x..." } to build collection detail pages.
• Filter NFTs by token standard using standard: ERC721 or standard: ERC1155 to separate single-owner and multi-owner NFTs.
• Display NFT galleries with optimized media by selecting media and thumbnails fields for performant image rendering.
• Perform cross-contract NFT search by combining contract: { nameLike: "..." } with NFT-level filters for broad discovery.

Example

Query

Browse NFTs in a Collection with Media

query BrowseCollectionNFTs(
  $where: NFTFilter
  $first: Int
  $orderBy: NFTOrderBy
  $orderDirection: OrderDirection
) {
  nfts(
    where: $where
    first: $first
    orderBy: $orderBy
    orderDirection: $orderDirection
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      tokenId
      name
      standard
      contract {
        address
        name
        symbol
      }
      metadata {
        description
        attributes {
          traitType
          value
        }
      }
      media {
        url
        contentType
        thumbnails(preset: MEDIUM) {
          url
          width
          height
        }
      }
      ... on SingleHolderNFT {
        holder {
          address
        }
        burned
      }
      ... on MultiHolderNFT {
        totalSupply
        holdersCount
      }
    }
  }
}

Variables

{
  "where": {
    "contract": {
      "address": "0xC9041f80DCe73721A5f6a779672Ec57EF255d27c"
    },
    "standard": "ERC721"
  },
  "first": 20,
  "orderBy": "TOKEN_ID",
  "orderDirection": "ASC"
}

Response

{
  "data": {
    "nfts": {
      "totalCount": 12480,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6MjB9"
      },
      "entries": [
        {
          "tokenId": "0",
          "name": "Chromie Squiggle #0",
          "standard": "ERC721",
          "contract": {
            "address": "0xC9041f80DCe73721A5f6a779672Ec57EF255d27c",
            "name": "Art Blocks",
            "symbol": "BLOCKS"
          },
          "metadata": {
            "description": "Simple and easily identifiable, each squiggle embodies the soul of the Art Blocks platform.",
            "attributes": [
              {
                "traitType": "Color Spread",
                "value": "7"
              },
              {
                "traitType": "Steps Between",
                "value": "20"
              }
            ]
          },
          "media": [
            {
              "url": "https://media.onesource.io/nft/1/0.png",
              "contentType": "image/png",
              "thumbnails": [
                {
                  "url": "https://media.onesource.io/thumbnails/medium/1/0.png",
                  "width": 300,
                  "height": 300
                }
              ]
            }
          ],
          "holder": {
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2"
          },
          "burned": false
        },
        {
          "tokenId": "1",
          "name": "Chromie Squiggle #1",
          "standard": "ERC721",
          "contract": {
            "address": "0xC9041f80DCe73721A5f6a779672Ec57EF255d27c",
            "name": "Art Blocks",
            "symbol": "BLOCKS"
          },
          "metadata": {
            "description": "Simple and easily identifiable, each squiggle embodies the soul of the Art Blocks platform.",
            "attributes": [
              {
                "traitType": "Color Spread",
                "value": "5"
              },
              {
                "traitType": "Steps Between",
                "value": "15"
              }
            ]
          },
          "media": [
            {
              "url": "https://media.onesource.io/nft/1/1.png",
              "contentType": "image/png",
              "thumbnails": [
                {
                  "url": "https://media.onesource.io/thumbnails/medium/1/1.png",
                  "width": 300,
                  "height": 300
                }
              ]
            }
          ],
          "holder": {
            "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
          },
          "burned": false
        }
      ]
    }
  }
}

Implementation Notes

note

• The nfts query searches across all NFT contracts. To browse NFTs within a single collection, filter with contract: { address: "0x..." }. To look up a single NFT directly, use the nft query instead.
• The default first value is 10. OneSource enforces a maximum first value of 100. Adjust based on your needs.
• Use cursor-based pagination with after and pageInfo.endCursor to page through results. Check pageInfo.hasNextPage to determine if more pages exist.
• The NFTFilter supports nested contract filtering using a ContractFilter, enabling cross-contract search — e.g., contract: { nameLike: "Art" } finds NFTs across all collections with "Art" in the name.
• Available orderBy values are TOKEN_ID, NAME, TOTAL_SUPPLY, and HOLDERS. The TOTAL_SUPPLY and HOLDERS options are primarily useful for ERC-1155 NFTs.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.
• Entries in the result implement the NFT interface. Use inline fragments (... on SingleHolderNFT, ... on MultiHolderNFT) to access standard-specific fields like holder or holdersCount.
• The nameLike filter performs case-insensitive partial matching, making it ideal for search functionality.
• Additional filters include media and metadata sub-filters for querying by media properties or metadata content.