Types

This section documents the GraphQL types available in the OneSource Web3 API. Types define the structure of data you can query, including objects like Token, Contract, and paginated lists like Tokens or Balances.

Balance

Description

The Balance type represents a user's or contract's holdings of a specific token/NFT. This type provides crucial ownership details, including the token amount held, associated smart contract information, and token metadata where applicable.

Use Cases

• Displaying all tokens in a user's wallet.
• Checking ownership of specific NFTs.
• Calculating total holdings of a particular token.
• Building portfolio dashboards.

Example

query Query($owner: ID!, $contract: ID!) {
  balance(owner: $owner, contract: $contract) {
    value
    token {
      name
    }
    contractType
    owner
    contract {
      decimals
    }
  }
}

Fields

Field Name	Type	Description
owner	String!	The address of the owner of the balance.
contractType	ContractType!	The type of contract (ERC-721, ERC-1155, ERC-20).
contract	Contract!	The contract object.
token	Token	The token object (if applicable).
value	String!	The balance value.

Understanding the value Field

The value field returns ERC-20 token balances exactly as stored on the Ethereum blockchain - as a raw, unformatted integer string representing the smallest unit of the token. This preserves full precision without decimal approximation.

You will need to convert the value to its decimal format using the token's decimals.

// Requires knowing the token's decimals
const formatted = value / (10 ** tokenDecimals);

The ether.js and web3.js libraries can also help with these conversions.

Implementation Notes

• The value field returns strings to support arbitrary precision.
• For ERC-20 tokens, token will be null.
• Use with the Balances type for paginated results.
• Combine with the Tokens type to get complete metadata when displaying NFT collections.

Balances

Description

The Balances type provides a paginated, cursor-based list of token/NFT holdings (Balance objects) for a given user or contract address. It enables efficient traversal of large balance dataset while tracking pagination state via cursor and remaining fields.

Use Cases

• Displaying all owned NFTs/tokens.
• Calculating holdings across a collection.
• Paginated UIs (lazy-loading balances in chunks).

Example

query GetBalances($owner: String!, $cursor: String) {
  balances(owner: $owner, first: 10, after: $cursor) {
    balances { owner, value, contract { id } }
    remaining
    cursor
  }
}

Fields

Field Name	Type	Description
count	UInt64!	Total balances matching the query.
remaining	UInt64!	Count of balances not yet returned in the current query.
cursor	String	Pagination key for fetching the next batch (null if no more results).
balances	[Balance!]!	List of individual token balances.

Contract

Description

The Contract type represents a contract address deployed on-chain. It contains comprehensive details about the smart contract.

Use Cases

• Contract audits (fetch comprehensive details about a contract).
• Track total holders for community growth metrics.
• NFT discovery (filter contracts by token standard, name, etc.).

Example

query AuditContract($contractId: ID!) {
  contract(id: $contractId) {
    id
    type
    name
    symbol
    holders
    createdAt
  }
}

Fields

Field Name	Type	Description
id	ID!	The contract address.
type	ContractType!	The type of contract.
isERC20	Boolean!	Whether the contract is an ERC-20 contract.
isERC721	Boolean!	Whether the contract is an ERC-721 contract.
isERC1155	Boolean!	Whether the contract is an ERC-1155 contract.
name	String	The name of the contract.
symbol	String	The symbol of the contract.
decimals	Int	The number of decimals (for ERC-20).
supportsMetadata	Boolean!	Whether the contract supports metadata.
createdAt	Time!	When the contract was created.
createdBlock	Int!	The block number at which the contract was created.
holders	Int!	The number of holders.
tokens	Tokens!	The tokens in this contract.

Contracts

Description

The Contracts type provides a paginated, cursor-based list of smart contracts (Contract objects). It enables efficient traversal of large contract datasets while tracking pagination state via cursor and remaining fields.

Use Cases

• Contract discovery (browse all contracts on a given chain and filter by type).
• Analytics dashboards (track holder distribution and contract deployment).
• Multi-Contract UIs (display ranked lists on a marketplace frontend).

Example

{"field": "value"}

Fields

Field Name	Type	Description
count	UInt64!	Total contracts matching query.
remaining	UInt64!	Contracts left to fetch.
cursor	String	Pagination key (null if no more results).
contracts	[Contract!]!	List of contracts with full details.

Token

Description

The Token type represents a single NFT. It provides comprehensive on-chain data, metadata, ownership details, and lifecycle events.

Use Cases

• NFT Marketplaces (show NFT details like image, name, description).
• Wallet Dashboards (retrieve metadata and NFT media for display).
• Token Analytics (track mint/burn rates across collections).

Example

query Query($contract: ID!, $tokenId: ID!) {
  token(contract: $contract, tokenID: $tokenId) {
    metadataContent
    name
    tokenID
    tokenURI
    description
    holders {
      balances {
        owner
      }
    }
  }
}

Fields

Field Name	Type	Description
contract	Contract!	The contract this minted this token.
tokenID	String!	The token ID.
tokenURI	String	The token URI.
tokenURIStatus	TokenURIStatus	The status of the token URI.
image	Image	The image associated with this token.
metadataStatus	MetadataStatus	The status of the metadata.
metadataContent	String	The metadata content.
metadataContentType	String	The content type of the metadata.
createdAt	Time!	When the token was created.
createdBlock	Int!	The block number at which the token was created.
burnedAt	Time	When the token was burned (if applicable).
burnedBlock	Int	The block number at which the token was burned (if applicable).
errorMsg	String	Error message (if any).
name	String	The name of the token.
description	String	The description of the token.
expired	Boolean	Whether the token has expired.
holders	Balances!	The quantity of holders of this token.

Tokens

Description

The Tokens type provides a paginated, cursor-based list of NFTs (Token objects). It enables efficient traversal of large NFT datasets while tracking pagination state via cursor and remaining fields.

Use Cases

• NFT Marketplaces (display token listings with metadata).
• Wallet Dashboards (show owned tokens across collections).
• Analytics Tools (analyze token distribution in a collection).

Example

query Tokens($where: TokenFilter, $whereContract: ContractFilter, $first: Int) {
  tokens(where: $where, whereContract: $whereContract, first: $first) {
    tokens {
      name
      tokenID
      tokenURI
      metadataContent
      metadataContentType
      contract {
        name
        symbol
        type
      }
    }
  }
}

Fields

Field Name	Type	Description
count	UInt64!	The total number of tokens
cursor	String	The cursor for pagination
tokens	[Token!]!	The list of token objects
timing	String	Timing information