tokens

The tokens query retrieves a paginated list of NFTs with comprehensive filtering, sorting, and pagination capabilities.

It returns a TokenList object containing an array of Token objects with detailed token data including contract information, token IDs, names, mint and burn transactions, associated media, metadata, and current holder information.

Schema Definition

tokens(
  first: Int = 10
  skip: Int = 0
  where: TokenFilter
  orderBy: TokenOrderBy
  orderDirection: Ordering
): TokenList!

Arguments

Argument	Type	Description
first	Int = 10 scalar	Maximum number of tokens to retrieve per page. Maximum value is 100.
skip	Int = 0 scalar	Number of tokens to bypass before assembling the page. Set to the first value from the previous page for offset pagination.
where	TokenFilter input	Specifies subsets of token data to be retrieved.
orderBy	TokenOrderBy enum	Sets how the list of tokens is ordered.
orderDirection	Ordering enum	Sets the direction in which the list of tokens is ordered.

Return Type

TokenList object

Common Use Cases

• Browse and display collections of NFTs by filtering on contract addresses to show all tokens within a specific collection.
• Search for tokens by name using nameLike to build token discovery features and marketplace search functionality.
• Track token ownership and history by examining holders, mintTransaction, and burnTransaction data.
• Filter tokens by their burn status to identify active vs. burned tokens, useful for supply tracking and analytics.
• Combine filters like contract and tokenId ranges to create custom collection views or rarity-based displays.
• Query tokens with specific media or metadata properties to find tokens matching certain characteristics or traits.

Example

Query

Find All Tokens in a Collection with Media

query CollectionTokens($where: TokenFilter, $first: Int) {
  tokens(where: $where, first: $first, orderBy: TOKEN_ID, orderDirection: ASC) {
    numEntries
    cursor
    entries {
      tokenId
      name
      contract {
        name
        symbol
        address
      }
      media {
        url
        contentType
        thumbnails(where: { preset: MEDIUM }) {
          url
          width
          height
        }
      }
      holders
    }
  }
}

Variables

{
  "where": {
    "contract": {
      "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
    },
    "burned": false
  },
  "first": 20
}

Response

{
  "data": {
    "tokens": {
      "numEntries": 20,
      "cursor": "20",
      "entries": [
        {
          "tokenId": "1",
          "name": "Bored Ape #1",
          "contract": {
            "name": "BoredApeYachtClub",
            "symbol": "BAYC",
            "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
          },
          "media": [
            {
              "url": "ipfs://QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ",
              "contentType": "image/png",
              "thumbnails": [
                {
                  "url": "https://media.onesource.io/thumbnails/medium/...",
                  "width": 512,
                  "height": 512
                }
              ]
            }
          ],
          "holders": ["0x1234567890abcdef1234567890abcdef12345678"]
        }
      ]
    }
  }
}

Implementation Notes

note

• The default first value is 10 transactions. OneSource enforces a maximum first value of 100. Adjust based on your UI needs.
• Use skip for offset-based pagination. To get the next page, use a skip value equal to the previous first value.
• All range filters use Gte (greater than or equal to) and Lte (less than or equal to) suffixes for inclusive ranges.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.
• The tokenId field uses the UInt256 type to support the full range of possible token IDs in ERC-721 and ERC-1155 contracts.
• The burned filter helps distinguish between active tokens and tokens that have been permanently removed from circulation.
• The holders array returned by the Token object contains wallet addresses currently holding the token. For ERC-721 tokens, this will typically be a single address. For ERC-1155 tokens, multiple addresses may hold the same token ID.
• Use nested filtering with ContractFilter, MediaFilter, and MetadataFiler to create sophisticated token queries.
• The nameLike filter performs case-insensitive partial matching, making it ideal for search functionality.