tokens

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 ERC-20 tokens with pagination.

Schema Definition

tokens(
  first: Int = 10
  after: Cursor
  where: TokenFilter
  orderBy: TokenOrderBy
  orderDirection: OrderDirection
): TokenList!

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

Return Type

Type	Description
TokenList! object	Paginated list of ERC-20 tokens.

Common Use Cases

• Build token directories and DEX interfaces by listing ERC-20 tokens with filtering and sorting.
• Search for tokens by name or symbol using nameLike and symbolLike for token discovery features.
• Analyze popular tokens by ordering with orderBy: HOLDERS to identify high-adoption tokens.
• Monitor newly deployed tokens by filtering with createdAt: { gte: "..." } to track ecosystem growth.
• Filter tokens by supply range using totalSupply: { gte, lte } for analytics and categorization.
• Combine filters like holdersCount ranges and decimals to create advanced token screening tools.

Example

Query

Find Popular ERC-20 Tokens by Holder Count

query PopularTokens($where: TokenFilter, $first: Int) {
  tokens(where: $where, first: $first, orderBy: HOLDERS, orderDirection: DESC) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      address
      name
      symbol
      decimals
      totalSupply {
        formatted
      }
      holdersCount
      createdAt
    }
  }
}

Variables

{
  "where": {
    "holdersCount": { "gte": 1000 },
    "createdAt": { "gte": "2025-01-01T00:00:00Z" }
  },
  "first": 20
}

Response

{
  "data": {
    "tokens": {
      "totalCount": 347,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6MjB9"
      },
      "entries": [
        {
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "totalSupply": {
            "formatted": "25000000000.000000"
          },
          "holdersCount": 2150000,
          "createdAt": "2025-03-15T08:22:10Z"
        },
        {
          "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
          "name": "Tether USD",
          "symbol": "USDT",
          "decimals": 6,
          "totalSupply": {
            "formatted": "40000000000.000000"
          },
          "holdersCount": 1890000,
          "createdAt": "2025-02-10T14:05:33Z"
        }
      ]
    }
  }
}

Implementation Notes

note

• The tokens query is specifically for ERC-20 fungible tokens. To query NFTs, use the nfts 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.
• Range filters use structured input objects with gte (greater than or equal) and lte (less than or equal) fields — e.g., holdersCount: { gte: 100 }, totalSupply: { gte: "1000000" }.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.
• The nameLike and symbolLike filters perform case-insensitive partial matching, making them ideal for search functionality.
• The totalSupply field returns a TokenAmount object with both raw (base unit string) and formatted (human-readable) values.
• The holdersCount field returns the number of unique addresses holding a non-zero balance.
• Use the holders paginated field on individual Token entries to retrieve the actual list of holder addresses and their balances.