contracts

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 smart contracts with pagination.

Schema Definition

contracts(
  first: Int = 10
  after: Cursor
  where: ContractFilter
  orderBy: ContractOrderBy
  orderDirection: OrderDirection
): ContractList!

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	ContractFilter input	Filter criteria for contracts.
orderBy	ContractOrderBy enum	Field to sort results by.
orderDirection	OrderDirection enum	Sort direction (ascending or descending).

Return Type

Type	Description
ContractList! object	Paginated list of smart contracts.

Common Use Cases

• Browse all ERC-20 tokens by filtering with standards: [ERC20] to build token directories or DEX interfaces.
• Monitor newly deployed contracts by filtering with createdAt: { gte: "..." } to track ecosystem growth.
• Search for specific contracts by name or symbol using nameLike and symbolLike filters for discovery features.
• Analyze popular contracts by ordering with orderBy: HOLDERS to identify trending tokens and high-adoption projects.
• Track NFT collections by filtering with standards: [ERC721] or standards: [ERC1155] to build NFT marketplaces or galleries.
• Combine filters like createdBlock: { gte, lte } and holdersCount: { gte, lte } to create advanced analytics and reporting tools.
• Find contracts deployed by a specific address using the creator filter.

Example

Query

Find Popular ERC-20 Contracts Created Recently

query FindPopularContracts(
  $first: Int
  $where: ContractFilter
  $orderBy: ContractOrderBy
  $orderDirection: OrderDirection
) {
  contracts(
    first: $first
    where: $where
    orderBy: $orderBy
    orderDirection: $orderDirection
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      ... on Token {
        address
        name
        symbol
        decimals
        holdersCount
        totalSupply {
          formatted
        }
        createdAt
        standards
      }
      ... on NFTContract {
        address
        name
        symbol
        holdersCount
        nftCount
        createdAt
        standards
      }
      ... on Contract {
        address
        name
        symbol
        createdAt
        standards
      }
    }
  }
}

Variables

{
  "first": 10,
  "where": {
    "standards": ["ERC20"],
    "createdAt": { "gte": "2025-11-01T00:00:00Z" },
    "holdersCount": { "gte": 100 }
  },
  "orderBy": "HOLDERS",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "contracts": {
      "totalCount": 234,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6MTB9"
      },
      "entries": [
        {
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "holdersCount": 2150000,
          "totalSupply": {
            "formatted": "25000000000.000000"
          },
          "createdAt": "2025-11-05T12:34:56Z",
          "standards": ["ERC20"]
        },
        {
          "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
          "name": "Dai Stablecoin",
          "symbol": "DAI",
          "decimals": 18,
          "holdersCount": 890000,
          "totalSupply": {
            "formatted": "3500000000.000000000000000000"
          },
          "createdAt": "2025-11-22T09:15:30Z",
          "standards": ["ERC20"]
        }
      ]
    }
  }
}

Implementation Notes

note

• The contracts query returns a ContractList containing IContract entries, which may resolve to Token (ERC-20), NFTContract (ERC-721/ERC-1155), or Contract (generic). Use inline fragments (... on Token, ... on NFTContract) to access type-specific fields.
• 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.
• Filter by token standard using standards: [ERC20], standards: [ERC721], or standards: [ERC1155]. A contract can implement multiple standards.
• Range filters use structured input objects with gte and lte fields — e.g., holdersCount: { gte: 100 }, createdAt: { gte: "2025-01-01T00:00:00Z" }, createdBlock: { gte: 18000000, lte: 19000000 }.
• Use orderBy and orderDirection (ASC or DESC) to ensure consistent ordering when paginating through large result sets.
• Available orderBy values are ADDRESS, CREATED_AT, CREATED_BLOCK, NAME, SYMBOL, HOLDERS, and NONCE.
• The nameLike and symbolLike filters perform case-insensitive partial matching, making them ideal for search functionality.
• Use the creator filter to find all contracts deployed by a specific address.
• To look up a single contract directly by address, use the contract query instead.