contract

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 smart contract by its address. Returns the appropriate contract type (Token, NFTContract, or Contract) based on detected standards. Returns null if the address is not a contract.

Schema Definition

contract(
  address: AddressString!
): IContract

Arguments

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

Return Type

Type	Description
IContract interface	Base interface for smart contracts deployed on chain. Extends the Address interface with contract-specific metadata including deployment information and token standards.

Common Use Cases

• Build contract detail pages by looking up a specific smart contract to display its name, symbol, deployment info, and token standards.
• Determine whether a contract is an ERC-20 token, NFT collection (ERC-721/ERC-1155), or generic contract to customize UI rendering and available actions.
• Retrieve deployment provenance by accessing createdAt, createdInBlock, createdByTransaction, and creator for contract verification or audit tools.
• Display holder counts and total supply for a known token contract address in portfolio or analytics views.
• Access a contract's token balances, NFT balances, and transaction history through the nested paginated fields on the returned type.
• Check contract activity status using lastActiveAt and transactionCount for monitoring or alerting dashboards.

Example

Query

Look Up a Smart Contract by Address

query ContractDetails($address: AddressString!) {
  contract(address: $address) {
    ... on Token {
      address
      name
      symbol
      decimals
      holdersCount
      totalSupply {
        raw
        formatted
      }
      standards
      createdAt
      createdInBlock {
        number
      }
      creator {
        address
      }
      nonce
      lastActiveAt
      transactionCount
    }
    ... on NFTContract {
      address
      name
      symbol
      holdersCount
      nftCount
      standards
      createdAt
      createdInBlock {
        number
      }
      creator {
        address
      }
      nonce
      lastActiveAt
      transactionCount
    }
    ... on Contract {
      address
      name
      symbol
      standards
      createdAt
      createdInBlock {
        number
      }
      creator {
        address
      }
      nonce
      lastActiveAt
      transactionCount
    }
  }
}

Variables

{
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

Response

{
  "data": {
    "contract": {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "holdersCount": 2150000,
      "totalSupply": {
        "raw": "25000000000000000",
        "formatted": "25000000000.000000"
      },
      "standards": ["ERC20"],
      "createdAt": "2018-08-03T18:25:43Z",
      "createdInBlock": {
        "number": 6082465
      },
      "creator": {
        "address": "0x95Ba4cF87D6723ad9C0Db21737D862bE44e917A2"
      },
      "nonce": 1,
      "lastActiveAt": "2026-02-13T10:30:00Z",
      "transactionCount": 289450000
    }
  }
}

Implementation Notes

note

• The contract query returns null if the given address is not a smart contract (i.e., it is an EOA or has never been seen on-chain). Always handle the null case in your application.
• The return type is IContract, which may resolve to Token (ERC-20), NFTContract (ERC-721/ERC-1155), or Contract (generic). Use GraphQL inline fragments (... on Token, ... on NFTContract, ... on Contract) to access type-specific fields.
• The createdInBlock, createdByTransaction, and creator fields return full objects (Block, Transaction, and Address respectively), not scalar values. Select the specific sub-fields you need.
• The tokenBalances, nftBalances, and transactions fields are paginated sub-queries available on the returned contract, each with their own first, after, where, orderBy, and orderDirection parameters.
• If you already know the contract is an ERC-20 token, consider using the token query instead for a more targeted return type.
• To search and filter across multiple contracts, use the contracts query with pagination and filtering support.
• To look up any address (including EOAs), use the address query instead.