Account Timelines

Presents the onchain activity of provided addresses in a simple descriptive summary with references to dynamic elements of the transaction such as tokens, NFTs, and accounts.

accountsTimeline

Takes an array of addresses as input, with optional parameters for network, and spamFilter. It returns chronological on-chain activity.

Example Use Case: Transaction History

Let's say you want to show users their onchain transactions in a human-readable format with network, app information, and detailed token transfer data. Start by passing addresses for the user. The query returns:

• Human-readable transaction descriptions (processedDescription)
• Network information
• App details
• Comprehensive data about tokens or NFTs involved in the transaction (inboundAttachments and outboundAttachments)

This allows you to build rich transaction history views with:

• Formatted descriptions (e.g., "Swapped 400 USDC for 0.2 ETH")
• Complete token details including decimals, addresses, and symbols
• Current market prices for tokens
• NFT collection and token information when relevant

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 ($addresses: [Address!], $realtimeInterpretation: Boolean, $isSigner: Boolean) {
  accountsTimeline(addresses: $addresses, realtimeInterpretation: $realtimeInterpretation, isSigner: $isSigner) {
    edges {
      node {
        transaction {
          fromUser {
            address
            displayName {
              value
            }
          }
          toUser {
            displayName {
              value
            }
          }
        }
        app {
          slug
          name
          imgUrl
        }
        interpretation {
          processedDescription
          inboundAttachments {
            ... on TokenDisplayItem {
              type
              network
              tokenAddress
              amountRaw
              tokenV2 {
                address
                symbol
                decimals
                name
                imageUrl
                marketData {
                  price(currency: USD)
                }
              }
            }
            ... on NFTDisplayItem {
              type
              network
              collectionAddress
              tokenId
              quantity
            }
          }
          outboundAttachments {
            ... on TokenDisplayItem {
              type
              network
              tokenAddress
              amountRaw
              tokenV2 {
                address
                symbol
                decimals
                name
                imageUrl
                marketData {
                  price(currency: USD)
                }
              }
            }
            ... on NFTDisplayItem {
              type
              network
              collectionAddress
              tokenId
              quantity
              nftToken {
                collection {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "accountsTimeline": {
      "edges": [
        {
          "node": {
            "transaction": {
              "fromUser": {
                "address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
                "displayName": {
                  "value": "0xjasper.eth"
                }
              },
              "toUser": {
                "displayName": {
                  "value": "0x0000...3e70"
                }
              }
            },
            "app": {
              "slug": "sound-xyz",
              "name": "Sound.xyz",
              "imgUrl": "https://storage.googleapis.com/zapper-fi-assets/apps%2Fsound-xyz.png"
            },
            "interpretation": {
              "processedDescription": "Minted 1 Sweet Memories",
              "inboundAttachments": [
                {
                  "type": "nft",
                  "network": "BASE_MAINNET",
                  "collectionAddress": "0xab4d845880bfca8016fea84a6f645d2369292514",
                  "tokenId": "8255",
                  "quantity": 1
                }
              ],
              "outboundAttachments": [
                {
                  "type": "token",
                  "network": "BASE_MAINNET",
                  "tokenAddress": "0x0000000000000000000000000000000000000000",
                  "amountRaw": "1554000000000000",
                  "tokenV2": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "ETH",
                    "decimals": 18,
                    "name": "Ethereum",
                    "imageUrl": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
                    "marketData": {
                      "price": 3230.01
                    }
                  }
                }
              ]
            }
          }
        },
      ]
    }
  }
}

Try in sandbox

---

tip

If you want to surface tokens, NFTs, accounts, or other onchain items embedded within the human-readable description of a transaction, you should return description and descriptionDisplayItems in addition to processedDescription. This can be useful for adding links to tokens, NFTs, or accounts (e.g., vitalik.eth swapped 10 USDC...). To learn more about how to use these check out the example for Single Transactions.

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.

Arguments

Argument	Description	Type
network	The network(s) to retreive, 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!

Transaction Fields

Field	Description	Type
fromUser	The initiating address with its details	Account!
toUser	The receiving address with its details	Account!
hash	Transaction hash	String!
nonce	Transaction nonce	Int!
gasPrice	Gas price in wei	String!
gas	Gas limit	Int!

Account Fields

Field	Description	Type
address	The wallet address	Address!
displayName	The account's display name (ENS, Lens, etc.)	DisplayName!

Interpretation Fields

Field	Description	Type
processedDescription	Human-readable description of the transaction	String!
inboundAttachments	Assets received in the transaction	[ActivityFeedDisplayItem!]!
outboundAttachments	Assets sent in the transaction	[ActivityFeedDisplayItem!]!

TokenDisplayItem Fields (in attachments)

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!

TokenV2 Fields

Field	Description	Type
address	Token contract address	Address!
symbol	Token symbol (e.g., "USDC")	String!
decimals	Number of decimal places	Int!
name	Full token name	String!
imageUrl	Token icon URL	String!
marketData	Current market information	MarketData

NFTDisplayItem Fields (in attachments)

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

MarketData Fields

Field	Description	Type
price	Current price in specified currency	Float

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

All fields marked with ! are required fields in the response.