Transaction History

Presents the onchain activity of provided addresses with rich, dynamic transaction descriptions and detailed transfer data.

`transactionHistory`

Takes an array of addresses as input and returns chronological on-chain activity with both human-readable descriptions and structured data about transferred assets.

Dynamic Transaction Descriptions

One of the most powerful features of the transactionHistory endpoint is its ability to provide both simple text descriptions and dynamic, interactive elements for each transaction. This is handled through three complementary fields:

processedDescription: A plain text, human-readable summary (e.g. "Swapped 400 USDC for 0.2 ETH")
description: A templated version that includes reference tokens (e.g. "Swapped $1 for $2")
descriptionDisplayItems: Structured data for each referenced element in the description

The description fields work alongside (but separate from) the inboundAttachments and outboundAttachments which provide comprehensive data about all assets involved in the transaction.

Example Use Case: Rich Transaction History

Let's say you want to show users their onchain transactions with interactive elements.

Example Variables

{
  "addresses": ["0x52c8ff44260056f896e20d8a43610dd88f05701b"],
  "isSigner": true,
  "realtimeInterpretation": true
}

tip

When isSigner is set to true it only returns transactions initiated from the specified address. When this is set to false, it returns every transaction that this address was a part of.

Example Query

query transactionHistory($addresses: [Address!], $realtimeInterpretation: Boolean, $isSigner: Boolean) {
  transactionHistory(addresses: $addresses, realtimeInterpretation: $realtimeInterpretation, isSigner: $isSigner) {
    edges {
      node {
        transaction {
          fromUser {
            address
            displayName {
              value
            }
          }
          toUser {
            displayName {
              value
            }
          }
        }
        app {
          slug
          name
          imgUrl
        }
        interpretation {
          # Basic text description
          processedDescription
          # Templated description with reference tokens
          description
          # Structured data for referenced elements
          descriptionDisplayItems {
            ... on TokenDisplayItem {
              type
              network
              tokenAddress
              amountRaw
              tokenV2 {
                address
                symbol
                decimals
                name
                imageUrl
                onchainMarketData {
                  price(currency: USD)
                  priceChange24h
                  marketCap
                }
              }
            }
            ... on NFTDisplayItem {
              type
              network
              collectionAddress
              tokenId
              quantity
              nftToken {
                collection {
                  name
                }
              }
            }
            ... on ActorDisplayItem {
              type
              address
              account {
                address
                displayName {
                  value
                }
                farcasterProfile {
                  username
                  fid
                }
              }
            }
            ... on NFTCollectionDisplayItem {
              collectionAddress
              network
              nftCollection {
                displayName
                medias {
                  logo {
                    thumbnail
                  }
                }
              }
            }
            ... on StringDisplayItem {
              stringValue
              type
            }
            ... on NetworkDisplayItem {
              chainId
              type
              networkMetadata {
                name
              }
            }
          }
        }
      }
    }
  }
}

tip

Include fragments for all possible descriptionDisplayItems types in your query - they'll only be returned when used as variables in the description. For example, if the description is "Sent $1 to $2", you'll receive the TokenDisplayItem and ActorDisplayItem data for those specific references.

Example Response

{
  "data": {
    "transactionHistory": {
      "edges": [
        {
          "node": {
            "transaction": {
              "fromUser": {
                "address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
                "displayName": {
                  "value": "0xjasper.eth"
                }
              },
              "toUser": {
                "displayName": {
                  "value": "LI.FI: LiFi Diamond"
                }
              }
            },
            "app": {
              "slug": "lifi",
              "name": "Li.Fi",
              "imgUrl": "https://storage.googleapis.com/zapper-fi-assets/apps%2Flifi.png"
            },
            "interpretation": {
              "processedDescription": "Swapped 0.015 ETH for 3,933.0058 B3",
              "description": "Swapped $1 for $2",
              "descriptionDisplayItems": [
                {
                  "type": "token",
                  "network": "BASE_MAINNET",
                  "tokenAddress": "0x0000000000000000000000000000000000000000",
                  "amountRaw": "15000000000000000",
                  "tokenV2": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "ETH",
                    "decimals": 18,
                    "name": "Ethereum",
                    "imageUrl": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
                    "onchainMarketData": {
                      "price": 2728.31,
                      "priceChange24h": 1.3804510953515203,
                      "marketCap": null
                    }
                  }
                },
                {
                  "type": "token",
                  "network": "BASE_MAINNET",
                  "tokenAddress": "0xb3b32f9f8827d4634fe7d973fa1034ec9fddb3b3",
                  "amountRaw": "3933005790210873157867",
                  "tokenV2": {
                    "address": "0xb3b32f9f8827d4634fe7d973fa1034ec9fddb3b3",
                    "symbol": "B3",
                    "decimals": 18,
                    "name": "B3 (Base)",
                    "imageUrl": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0xb3b32f9f8827d4634fe7d973fa1034ec9fddb3b3.png",
                    "onchainMarketData": {
                      "price": 0.008344709674145174,
                      "priceChange24h": 0.48220918679768854,
                      "marketCap": 834470967.4145174
                    }
                  }
                }
              ]
            }
          }
        },
      ]
    }
  }
}

Try in sandbox

Arguments

Argument	Description	Type
`network`	The network(s) to retrieve, input as an array	`Network!`
`realtimeInterpretation`	Human-readable transactions, default is on	`Boolean = true`
`addresses`	The address(s) that is being queried, input as an array	`Address!`
`tokenAddresses`	Filter by token address(s), input as an array. Maximum 20 token addresses per query	`Address!`
`isSigner`	Filter by signer	`Boolean`
`spamFilter`	Filter for spam, default is on	`Boolean = true`
`first`	Used for pagination	`Int!`
`after`	Used for pagination	`String!`

Fields

Main Fields

Field	Description	Type
`key`	A unique identifier	`String!`
`network`	Network on which the transaction happened	`Network!`
`timestamp`	Unix timestamp in milliseconds	`Timestamp!`
`transaction`	Contains detailed onchain transaction information	`OnChainTransaction!`
`app`	The associated application details	`ActivityFeedApp!`
`interpretation`	Contains human-readable descriptions and asset transfers	`ActivityInterpretation!`

Interpretation Fields

Field	Description	Type
`processedDescription`	Plain text description of the transaction	`String!`
`description`	Templated description with reference tokens	`String!`
`descriptionDisplayItems`	Structured data for elements referenced in description	`[ActivityFeedDisplayItem!]!`
`inboundAttachments`	Assets received in the transaction	`[ActivityFeedDisplayItem!]!`
`outboundAttachments`	Assets sent in the transaction	`[ActivityFeedDisplayItem!]!`

TokenDisplayItem Fields

Field	Description	Type
`type`	Type identifier for the display item	`String!`
`network`	Network of the token	`Network!`
`tokenAddress`	Contract address of the token	`Address!`
`amountRaw`	Raw token amount (requires decimal adjustment)	`String!`
`tokenV2`	Detailed token information	`FungibleToken!`

NFTDisplayItem Fields

Field	Description	Type
`type`	Type identifier for the display item	`String!`
`network`	Network of the NFT	`Network!`
`collectionAddress`	Contract address of the NFT collection	`Address!`
`tokenId`	Unique identifier of the NFT	`String!`
`quantity`	Number of NFTs transferred	`Float`

ActorDisplayItem Fields

Field	Description	Type
`address`	Address of the actor	`Address!`
`account`	Account details	`Account!`
`account.address`	Ethereum address	`Address!`
`account.displayName`	Primary identifier (ENS, address, etc.)	`DisplayName!`
`account.description`	Account description	`Description`
`account.ens`	ENS name if available	`String`
`account.ensRecord`	Full ENS record data	`EnsRecord`
`account.basename`	Basename if available	`String`
`account.label`	Custom label if set	`String`
`account.avatar`	Avatar image data	`AccountAvatar!`
`account.farcasterProfile`	Farcaster profile data	`FarcasterProfile`
`account.farcasterProfile.username`	Farcaster username	`String!`
`account.farcasterProfile.fid`	Farcaster ID	`Int!`
`account.farcasterProfile.metadata.displayName`	Farcaster display name	`String`
`account.farcasterProfile.metadata.description`	Farcaster bio	`String`
`account.farcasterProfile.metadata.imageUrl`	Farcaster profile image	`String`
`account.farcasterProfile.metadata.warpcast`	Warpcast profile URL	`String`
`account.lensProfile`	Lens profile data	`LensProfile`
`account.lensProfile.handle`	Lens handle	`String!`
`account.lensProfile.metadata.name`	Lens display name	`String`
`account.lensProfile.metadata.description`	Lens bio	`String`
`account.lensProfile.metadata.imageUrl`	Lens profile image	`String`
`account.socialLinks`	Array of social media links	`[AccountSocialLink!]!`
`account.isContract`	Whether address is a contract	`Boolean!`

For all possible descriptionDisplayItems, review the reference.

tip

When working with token amounts, remember to divide amountRaw by 10^decimals to get the human-readable amount. For example, an amountRaw of "21211050963" with 6 decimals represents 21,211.051 tokens.

note

Textual description of each transaction is presented from the perspective of the signer. Events with descriptions such as "Did something with …" indicate that an interpreter for that type of onchain interaction has not yet been curated through interpretation.