token

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

Look up a fungible token (ERC-20) by its contract address. Returns null if the address is not an ERC-20 token contract.

Schema Definition

token(
  address: AddressString!
): Token

Arguments

Argument	Type	Description
address	AddressString! non-null scalar	The token contract address to look up (0x-prefixed, 42 characters).

Return Type

Type	Description
Token object	A fungible token contract implementing ERC-20 or a compatible standard. Fungible tokens are interchangeable - each unit is identical to every other unit. Examples: USDC, WETH, UNI, LINK.

Common Use Cases

• Display token detail pages showing an ERC-20 token's name, symbol, supply, and holder count.
• Build portfolio views by looking up individual tokens and their totalSupply with both raw and formatted values.
• Analyze token distribution by paginating through the holders field to see top holders and their balances.
• Retrieve deployment provenance via createdAt, createdInBlock, createdByTransaction, and creator for token verification or analytics.
• Check a token contract's on-chain activity using transactionCount and lastActiveAt for health monitoring.
• Access the token contract's own asset holdings through the tokenBalances and nftBalances fields.

Example

Query

Look Up an ERC-20 Token with Supply and Top Holders

query GetTokenDetails($address: AddressString!) {
  token(address: $address) {
    address
    name
    symbol
    decimals
    standards
    totalSupply {
      raw
      formatted
      decimals
    }
    holdersCount
    holders(first: 5, orderBy: BALANCE, orderDirection: DESC) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      entries {
        address {
          address
        }
        balance {
          formatted
        }
      }
    }
    createdAt
    creator {
      address
    }
    transactionCount
    lastActiveAt
  }
}

Variables

{
  "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

Response

{
  "data": {
    "token": {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "standards": ["ERC20"],
      "totalSupply": {
        "raw": "25000000000000000",
        "formatted": "25000000000.000000",
        "decimals": 6
      },
      "holdersCount": 2150000,
      "holders": {
        "totalCount": 2150000,
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "eyJpZCI6NX0"
        },
        "entries": [
          {
            "address": {
              "address": "0x28C6c06298d514Db089934071355E5743bf21d60"
            },
            "balance": {
              "formatted": "3200000000.000000"
            }
          },
          {
            "address": {
              "address": "0x21a31Ee1afC51d94C2eFcCAa2092aD1028285549"
            },
            "balance": {
              "formatted": "1850000000.000000"
            }
          },
          {
            "address": {
              "address": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503"
            },
            "balance": {
              "formatted": "1200000000.000000"
            }
          },
          {
            "address": {
              "address": "0xDFd5293D8e347dFe59E90eFd55b2956a1343963d"
            },
            "balance": {
              "formatted": "980000000.000000"
            }
          },
          {
            "address": {
              "address": "0x5041ed759Dd4aFc3a72b8192C143F72f4724081A"
            },
            "balance": {
              "formatted": "750000000.000000"
            }
          }
        ]
      },
      "createdAt": "2018-08-03T18:28:32Z",
      "creator": {
        "address": "0x95Ba4cF87D6723ad9C0Db21737D862bE44A0E3F0"
      },
      "transactionCount": 245893012,
      "lastActiveAt": "2025-06-10T14:22:08Z"
    }
  }
}

Implementation Notes

note

• The token query looks up a fungible ERC-20 token by its contract address. To look up an NFT, use the nft query instead.
• The query returns null if the address is not an ERC-20 token contract. Always handle the null case in your application.
• The totalSupply field returns a TokenAmount object with raw (base unit string), formatted (human-readable with decimals applied), and decimals values.
• The holders field returns a paginated TokenHolderList. Each entry contains the holder's address and their balance as a TokenAmount. Use orderBy: BALANCE with orderDirection: DESC to retrieve top holders.
• The holdersCount field returns the number of unique addresses holding a non-zero balance of this token.
• Timestamps such as createdAt and lastActiveAt are ISO 8601 formatted strings in UTC (e.g., "2024-01-15T14:30:00Z").
• To search and filter across multiple ERC-20 tokens, use the tokens query with pagination and filtering support.