contracts

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

It returns a ContractList object containing an array of Contract objects containing all contract metadata, token standard implementations, holder counts, creation details, and associated token information.

Schema Definition

contracts(
  first: Int = 10
  skip: Int = 0
  where: ContractFilter
  orderBy: ContractOrderBy
  orderDirection: Ordering
): ContractList!

Arguments

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

Return Type

ContractList object

Common Use Cases

• Display all ERC-20 tokens by filtering with isERC20: true to build token directories or DEX interfaces.
• Monitor newly deployed contracts by filtering with createdAtGte and createdAtLte parameters to track ecosystem growth.
• Search for specific tokens by name or symbol using nameLike and symbolLike filters for token discovery features.
• Analyze popular contracts by ordering with orderBy: HOLDERS to identify trending tokens and high-adoption projects.
• Track NFT collections by filtering with isERC721: true or isERC1155: true to build NFT marketplaces or galleries.
• Combine filters like createdBlockGte/createdBlockLte and holdersGte/holdersLte to create advanced analytics and reporting tools.

Example

Query

Find Popular ERC-20 Tokens Created Recently

query FindPopularTokens(
  $first: Int
  $where: ContractFilter
  $orderBy: ContractOrderBy
  $orderDirection: Ordering
) {
  contracts(
    first: $first
    where: $where
    orderBy: $orderBy
    orderDirection: $orderDirection
  ) {
    numEntries
    cursor
    entries {
      address
      name
      symbol
      decimals
      holders
      createdAt
      createdBlock
    }
  }
}

Variables

{
  "first": 10,
  "where": {
    "isERC20": true,
    "createdAtGte": "2025-11-01T00:00:00Z",
    "holdersGte": 100
  },
  "orderBy": "HOLDERS",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "contracts": {
      "numEntries": 10,
      "cursor": "10",
      "entries": [
        {
          "address": "0xabc123...",
          "name": "Example Token",
          "symbol": "EXT",
          "decimals": 18,
          "holders": 1500,
          "createdAt": "2025-11-05T12:34:56Z",
          "createdBlock": 12345678
        },
        // More contract entries...
      ]
    }
  }
}

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 nameLike and symbolLike filters support case-insensitive partial matching for flexible searches.
• The decimals field returned by the ContractList object is only relevant for ERC-20 token contracts and indicates how many decimal places the token uses (typically 18).
• The holders field returned by the ContractList object represents the total count of unique addresses holding tokens from this contract.