Display Items Reference

Display items are structured data objects that represent different types of entities in a consistent, type-safe way. They are used throughout the API to represent everything from tokens and NFTs to network information and numeric values.

tip

To learn more about how this can be used within an application, read the documentation on the transactionHistoryV2 endpoint.

Overview

All display items share a common type field that identifies their specific type. The API uses a union type ActivityFeedDisplayItem that encompasses all possible display item types:

union ActivityFeedDisplayItem =
  | ActorDisplayItem
  | AppDisplayItem
  | AppContractNetworkDisplayItem
  | ChatChannelDisplayItem
  | CompositeDisplayItem
  | ImageDisplayItem
  | NetworkDisplayItem
  | NFTCollectionDisplayItem
  | NFTDisplayItem
  | NumberDisplayItem
  | ProposalDisplayItemObject
  | StringDisplayItem
  | TokenContractDisplayItem
  | TokenDisplayItem
  | TransactionDisplayItem

Display Item Types

ActorDisplayItem

Represents a blockchain actor such as a user, wallet, or smart contract. Useful for displaying information about addresses involved in transactions.

type ActorDisplayItem {
  type: String!          # Always "actor"
  address: Address!      # The blockchain address
  account: Account! {    # Detailed account information
    address
    displayName {
      value              # ENS name or formatted address
      source            # Source of the display name (ENS, LENS, etc.)
    }
    avatar {
      value {
        url             # Avatar image URL
      }
    }
    farcasterProfile {
      username
      fid              # Farcaster ID
    }
    description {
      value           # Account description if available
    }
    socialLinks {     # Associated social media links
      name           # e.g. TWITTER, GITHUB
      url
    }
  }
}

Example usage:

query {
  descriptionDisplayItems {
    ... on ActorDisplayItem {
      type
      address
      account {
        displayName {
          value
        }
        avatar {
          value {
            url
          }
        }
      }
    }
  }
}

TokenDisplayItem

Represents a specific amount of a token. Essential for displaying token transfers and balances.

type TokenDisplayItem {
  type: String!           # Always "token"
  network: Network!       # The blockchain network
  tokenAddress: Address!  # Token contract address
  amountRaw: String!     # Raw token amount (needs decimal adjustment)
  tokenV2: FungibleToken {
    address
    symbol              # Token symbol (e.g., "ETH")
    decimals           # Number of decimals for the token
    name               # Full token name
    imageUrl          # Token icon URL
    onchainMarketData {
      price(currency: USD)
      priceChange24h
      marketCap
    }
  }
}

Working with Token Amounts

To convert amountRaw to a human-readable amount:

const amount = BigNumber(amountRaw)
  .div(10 ** decimals)
  .toString();

For example, if amountRaw is "1000000000000000000" and decimals is 18, the actual amount is 1.0.

NFTDisplayItem

Represents a specific NFT token. Used for displaying NFT transfers and holdings.

type NFTDisplayItem {
  type: String!               # Always "nft"
  network: Network!           # The blockchain network
  collectionAddress: Address! # Collection contract address
  tokenId: String!           # Token identifier
  quantity: Float            # Optional quantity for ERC1155 tokens
  nftToken: NftToken {       # Detailed token information
    name
    description
    collection {
      name
      address
    }
    mediasV3 {               # NFT media assets
      images {
        edges {
          node {
            url
            mimeType
            width
            height
          }
        }
      }
    }
  }
  isMint: Boolean           # Whether this is a mint transaction
  isBurn: Boolean          # Whether this is a burn transaction
}

NFTCollectionDisplayItem

Represents an entire NFT collection. Useful for collection-wide operations and displays.

type NFTCollectionDisplayItem {
  type: String!               # Always "nftCollection"
  network: Network!           # The blockchain network
  collectionAddress: Address! # Collection contract address
  quantity: Float            # Optional quantity of NFTs
  nftCollection: NftCollection {
    displayName
    description
    floorPrice {              # Current floor price
      valueUsd
      valueWithDenomination
    }
    medias {
      logo {
        thumbnail            # Collection logo URL
      }
    }
    supply                   # Total supply of the collection
    holdersCount            # Number of unique holders
  }
}

AppDisplayItem

Represents a decentralized application (dApp).

type AppDisplayItem {
  type: String!         # Always "app"
  id: ID!              # Unique identifier
  network: Network!    # The blockchain network
  app: ActivityFeedApp {
    slug              # Unique app identifier
    name             # Display name
    imgUrl           # App logo URL
    description     # App description
    url             # App website
    tags            # Categories/tags for the app
  }
}

NetworkDisplayItem

Represents a blockchain network.

type NetworkDisplayItem {
  type: String!                # Always "network"
  chainId: Float!             # Network chain ID
  networkType: NetworkIndexerType! # Type of network indexer
  networkMetadata: NetworkMetadata {
    name                     # Network name
    url                     # Network URL
    chainId                # Chain ID
  }
}

StringDisplayItem

Represents a simple text string.

type StringDisplayItem {
  type: String! # Always "string"
  stringValue: String! # The text value
}

NumberDisplayItem

Represents a numeric value.

type NumberDisplayItem {
  type: String! # Always "number"
  numberValue: Float! # The numeric value
}

TokenContractDisplayItem

Represents a token contract without a specific amount.

type TokenContractDisplayItem {
  type: String!         # Always "tokenContract"
  network: Network!    # The blockchain network
  address: Address!   # Token contract address
  token: FungibleToken {
    symbol
    decimals
    name
    imageUrl
  }
}

AppContractNetworkDisplayItem

Represents a specific contract deployment of an app on a network.

type AppContractNetworkDisplayItem {
  type: String! # Always "appContractNetwork"
  address: String! # Contract address
  network: Network! # The blockchain network
  app: ActivityFeedApp # Associated application details
}

ChatChannelDisplayItem

Represents a chat channel.

type ChatChannelDisplayItem {
  type: String! # Always "chatChannel"
  channelId: String! # Unique channel identifier
}

ProposalDisplayItemObject

Represents a governance proposal.

type ProposalDisplayItemObject {
  type: String! # Always "proposal"
  id: ID! # Unique identifier
  network: Network! # The blockchain network
  platform: String! # Governance platform name
}

TransactionDisplayItem

Represents a blockchain transaction with its full event data.

type TransactionDisplayItem {
  type: String!          # Always "transaction"
  event: ActivityEvent! {
    key                 # Unique transaction identifier
    network            # Network where transaction occurred
    timestamp         # Transaction timestamp
    transaction {     # Detailed transaction information
      hash
      from
      to
      value
    }
  }
}

Best Practices

1. Fragments: Use GraphQL fragments to request specific fields for each display item type:

2. Handling Missing Data: Some fields might be null, especially for pending or failed transactions. Always implement proper null checks:

3. Amount Formatting: For TokenDisplayItem, always format amounts using the token's decimals.