Transaction History

Access comprehensive onchain activity with rich transaction details, structured asset deltas, and support for both EOA and smart contract wallets.

Try it now

`transactionHistoryV2`

Key Features

1. Dynamic Transaction Descriptions

One of the most powerful features of the transactionHistoryV2 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

This enables developers to build rich, interactive transaction displays with automatic descriptions that can be customized for different UIs.

2. Enhanced Filtering Options

The new endpoint provides more granular filtering options:

filters: {
  chainIds: [Int!]             # Filter by specific chains
  tokenAddress: [Address!]        # Filter by tokens involved
  receivedFrom: [Address!]        # Filter by sender address (works with account abstraction)
  sentTo: [Address!]              # Filter by recipient address
  categories: [String!]           # Filter by category ["Swap", "Bridge", "Nft_Mint", "Nft_Sale"]
  contractAddress: [Address!]     # Filter by contract interacted with
}

Example Filters

{
  "filters": {
    "chainIds": [8453, 1],
    "tokenAddress": ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"],
    "receivedFrom": ["0x52c8ff44260056f896e20d8a43610dd88f05701b"],
    "sentTo": ["0x9b3a20176d2c5d0a22dae382496416a1a8934b30"],
    "categories": ["Swap", "Bridge", "Nft_Mint", "Nft_Sale"],
    "contractAddress": ["0x03059433bcdb6144624cc2443159d9445c32b7a8"]
  },
}

3. Detailed Asset Deltas

Each transaction includes explicit delta information showing exactly what changed in the user's portfolio:

perspectiveDelta: Returns balance changes for the subject of the transaction (e.g., EOA or contract that signs the transaction)
tokenDeltasV2: Shows token balance changes with positive (received) and negative (sent) amounts
nftDeltasV2: Shows NFT balance changes with collection and token details
deltas: Returns all balances changes for all addresses involved in the transaction

4. Perspective Control

The new perspective parameter gives you control over which transactions to include:

Signer: Only transactions initiated by the subject addresses (default)
Receiver: Only transactions where subject addresses received assets
All: All transactions involving the subject addresses

Example Use Cases

1. Human-readable Transactions

Create rich transaction descriptions with dynamic elements for a user-friendly experience.

Try it now

Example Variables

{
  "subjects": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
  "perspective": "Signer",
  "first": 20,
  "after": null,
  "filters": {
    "chainIds": [8453]
  }
}

Example Query

query TransactionHistoryV2(
  $subjects: [Address!]!
  $perspective: TransactionHistoryV2Perspective
  $first: Int
  $filters: TransactionHistoryV2FiltersArgs
) {
  transactionHistoryV2(subjects: $subjects, perspective: $perspective, first: $first, filters: $filters) {
    edges {
      node {
        ... on TimelineEventV2 {
          # Transaction method details
          methodSignature
          methodSighash

          # Transaction metadata
          transaction {
            blockNumber
            hash
            network
            timestamp

            # Sender details with identity
            fromUser {
              address
              displayName {
                value
                source
              }
              farcasterProfile {
                fid
                username
              }
            }

            # Recipient details with identity
            toUser {
              address
              displayName {
                value
                source
              }
            }
          }

          # Human-readable transaction information
          interpretation {
            processedDescription # Text description
            description # Templated description
            # Display items referenced in description
            descriptionDisplayItems {
              # Token information
              ... on TokenDisplayItem {
                type
                tokenAddress
                amountRaw
                network
                tokenV2 {
                  decimals
                  symbol
                  name
                  imageUrlV2
                  priceData {
                    price
                    priceChange24h
                  }
                }
              }

              # Account information
              ... on ActorDisplayItem {
                type
                address
                account {
                  displayName {
                    value
                    source
                  }
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Example Response

{
  "data": {
    "transactionHistoryV2": {
      "edges": [
        {
          "node": {
            "methodSignature": "transfer(address,uint256)",
            "methodSighash": "0xa9059cbb",
            "transaction": {
              "blockNumber": 29598605,
              "hash": "0x69a1f72b4603e72304e2636cc6138402b8f97430622b800275808b5c0d9e15a4",
              "network": "BASE_MAINNET",
              "timestamp": 1745986557000,
              "fromUser": {
                "address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
                "displayName": {
                  "value": "0xjasper.eth",
                  "source": "ENS"
                },
                "farcasterProfile": {
                  "fid": 177,
                  "username": "jasper"
                }
              },
              "toUser": {
                "address": "0x1bff6cbd036162e3535b7969f63fd8043ccc1433",
                "displayName": {
                  "value": "0x1bff...1433",
                  "source": "ADDRESS"
                }
              }
            },
            "interpretation": {
              "processedDescription": "Sent 1,143.944 BARMSTRONG to 0x32bd...689c",
              "description": "Sent $1 to $2",
              "descriptionDisplayItems": [
                {
                  "type": "token",
                  "tokenAddress": "0x1bff6cbd036162e3535b7969f63fd8043ccc1433",
                  "amountRaw": "1143943988872272227099",
                  "network": "BASE_MAINNET",
                  "tokenV2": {
                    "decimals": 18,
                    "symbol": "BARMSTRONG",
                    "name": "Barmstrong",
                    "imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x1bff6cbd036162e3535b7969f63fd8043ccc1433.png",
                    "priceData": {
                      "price": 0.00497470302555712,
                      "priceChange24h": 2.0383762988015475
                    }
                  }
                },
                {
                  "type": "actor",
                  "address": "0x32bd1c7be081e7ac7f03396ee0839523eae6689c",
                  "account": {
                    "displayName": {
                      "value": "0x32bd...689c",
                      "source": "ADDRESS"
                    }
                  }
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "endCursor": "MTc0NTk4NjU1N3x8YmFzZXx8MHg2OWExZjcyYjQ2MDNlNzIzMDRlMjYzNmNjNjEzODQwMmI4Zjk3NDMwNjIyYjgwMDI3NTgwOGI1YzBkOWUxNWE0",
        "hasNextPage": true
      }
    }
  }
}

2. Asset Deltas

Track detailed token and NFT balance changes across transactions.

Try it now

Example Variables

{
  "subjects": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
  "perspective": "Signer",
  "first": 20,
  "after": null,
  "filters": {
    "chainIds": [8453]
  }
}

Example Query

query TransactionHistoryV2(
  $subjects: [Address!]!
  $perspective: TransactionHistoryV2Perspective
  $first: Int
  $filters: TransactionHistoryV2FiltersArgs
  $after: String
) {
  transactionHistoryV2(
    subjects: $subjects
    perspective: $perspective
    first: $first
    filters: $filters
    after: $after
  ) {
    edges {
      node {
        ... on TimelineEventV2 {
          hash
          network
          timestamp
          value

          # Deltas for signed transactions
          deltas {
            totalCount
            edges {
              node {
                account {
                  address
                  isContract
                }
                tokenDeltasCount
                tokenDeltasV2 {
                  edges {
                    node {
                      amount
                      amountRaw
                      token {
                        address
                        credibility
                        decimals
                        symbol
                        imageUrlV2
                        priceData {
                          price
                          priceChange24h
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }

        # Transaction data for perspective: "Receiver"
        ... on ActivityTimelineEventDelta {
          transactionHash
          transactionBlockTimestamp
          network
          networkObject {
            name
            chainId
          }
          subject
          from {
            address
            isContract
          }
          to {
            address
            isContract
          }

          # Deltas for perspective: "Receiver"
          fungibleCount
          fungibleDeltas {
            amount
            amountRaw
            token {
              address
              credibility
              decimals
              symbol
              imageUrlV2
              priceData {
                price
                priceChange24h
              }
            }
          }
        }
      }
      cursor
    }
    totalCount
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}

Example Response

{
  "data": {
    "transactionHistoryV2": {
      "edges": [
        {
          "node": {
            "hash": "0x69a1f72b4603e72304e2636cc6138402b8f97430622b800275808b5c0d9e15a4",
            "network": "BASE_MAINNET",
            "timestamp": 1745986557000,
            "value": "0",
            "deltas": {
              "totalCount": 2,
              "edges": [
                {
                  "node": {
                    "account": {
                      "address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
                      "isContract": false
                    },
                    "tokenDeltasCount": 1,
                    "tokenDeltasV2": {
                      "edges": [
                        {
                          "node": {
                            "amount": -1143.9439888722723,
                            "amountRaw": "-1143943988872272227099",
                            "token": {
                              "address": "0x1bff6cbd036162e3535b7969f63fd8043ccc1433",
                              "credibility": null,
                              "decimals": 18,
                              "symbol": "BARMSTRONG",
                              "imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x1bff6cbd036162e3535b7969f63fd8043ccc1433.png",
                              "priceData": {
                                "price": 0.004944035913116251,
                                "priceChange24h": 0.22935723083206128
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                },
                {
                  "node": {
                    "account": {
                      "address": "0x32bd1c7be081e7ac7f03396ee0839523eae6689c",
                      "isContract": false
                    },
                    "tokenDeltasCount": 1,
                    "tokenDeltasV2": {
                      "edges": [
                        {
                          "node": {
                            "amount": 1143.9439888722723,
                            "amountRaw": "1143943988872272227099",
                            "token": {
                              "address": "0x1bff6cbd036162e3535b7969f63fd8043ccc1433",
                              "credibility": null,
                              "decimals": 18,
                              "symbol": "BARMSTRONG",
                              "imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x1bff6cbd036162e3535b7969f63fd8043ccc1433.png",
                              "priceData": {
                                "price": 0.004944035913116251,
                                "priceChange24h": 0.22935723083206128
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              ]
            }
          },
          "cursor": "MTc0NTk4NjU1N3x8YmFzZXx8MHg2OWExZjcyYjQ2MDNlNzIzMDRlMjYzNmNjNjEzODQwMmI4Zjk3NDMwNjIyYjgwMDI3NTgwOGI1YzBkOWUxNWE0"
        }
      ],
      "totalCount": 0,
      "pageInfo": {
        "endCursor": "MTc0NTk4NjU1N3x8YmFzZXx8MHg2OWExZjcyYjQ2MDNlNzIzMDRlMjYzNmNjNjEzODQwMmI4Zjk3NDMwNjIyYjgwMDI3NTgwOGI1YzBkOWUxNWE0",
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "MTc0NTk4NjU1N3x8YmFzZXx8MHg2OWExZjcyYjQ2MDNlNzIzMDRlMjYzNmNjNjEzODQwMmI4Zjk3NDMwNjIyYjgwMDI3NTgwOGI1YzBkOWUxNWE0"
      }
    }
  }
}

Arguments

Argument	Description	Type
`subjects`	List of addresses to query (required)	`[Address!]!`
`perspective`	Transaction perspective filter	`TransactionHistoryV2Perspective = Signer`
`first`	Number of results to return	`Int = 10`
`after`	Cursor for pagination	`String`
`filters`	Additional filtering options	`TransactionHistoryV2FiltersArgs`