Skip to main content

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

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

Example Use Case: Rich Transaction History

Let's build a comprehensive transaction history with interactive elements, that works seamlessly with both EOA and smart contract wallets.

Example Variables

{
"subjects": "0xc693c0856e4a874138f4330afb885419eead017d",
"perspective": "Signer",
"first": 10,
"filters": {
"network": "BASE_MAINNET"
},
}

Example Query

query TransactionHistoryV2($subjects: [Address!]!, $perspective: TransactionHistoryV2Perspective, $first: Int, $filters: TransactionHistoryV2FiltersArgs) {
# Fetch transaction history for specified wallets with account abstraction support
transactionHistoryV2(subjects: $subjects, perspective: $perspective, first: $first, filters: $filters) {
edges {
node {
... on TimelineEventV2 {
# Transaction method details
methodSignature # Method Used
methodSighash # Function signature hash (first 4 bytes)

# Transaction metadata
transaction {
blockNumber
gas
gasPrice
hash
network
timestamp
nonce

# Sender details with identity (note: this is different than the signer for smart wallets)
fromUser {
address
displayName {
value
source
}
farcasterProfile {
fid
username
}
}

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

# 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
priceChange5m
priceChange1h
priceChange24h
volume24h
totalLiquidity
marketCap
}
}
}

# NFT information
... on NFTDisplayItem {
type
collectionAddress
tokenId
quantity
isMint
isBurn
network
}

# Account information
... on ActorDisplayItem {
type
address
account {
displayName {
value
source
}
farcasterProfile {
fid
username
metadata {
imageUrl
}
}
}
}

# Network information
... on NetworkDisplayItem {
type
chainId
networkMetadata {
name
}
}

# NFT collection information
... on NFTCollectionDisplayItem {
type
collectionAddress
network
quantity
nftCollection {
displayName
floorPrice {
valueUsd
valueWithDenomination
denomination {
symbol
}
}
}
}

# Numeric and string values
... on NumberDisplayItem {
type
numberValue
}
... on StringDisplayItem {
type
stringValue
}
}
}

# Balance changes for the perspective account
perspectiveDelta {
account {
address
displayName {
value
source
}
farcasterProfile {
fid
username
metadata {
imageUrl
}
}
}
nftDeltasCount
tokenDeltasCount

# NFT balance changes
nftDeltasV2(first: 5) {
edges {
node {
collectionAddress
tokenId
amount
nft {
estimatedValue {
valueUsd
valueWithDenomination
denomination {
address
symbol
}
}
collection {
displayName
floorPrice {
valueUsd
}
}
}
}
}
}

# Token balance changes
tokenDeltasV2(first: 5) {
edges {
node {
address
amount
amountRaw
token {
symbol
imageUrlV2
priceData {
price
priceChange24h
}
}
}
}
}
}

# Unique identifier for events within a transaction
eventHash
}
}
}
}
}

Example Response

{
"data": {
"transactionHistoryV2": {
"edges": [
{
"node": {
"methodSignature": "swapAndTransferUniswapV3Native((uint256,uint256,address,address,address,uint256,bytes16,address,bytes,bytes),uint24)",
"methodSighash": "0x8bf122da",
"transaction": {
"blockNumber": 27161406,
"gas": 306461,
"gasPrice": "2426453",
"hash": "0x98455ae7e6b236d71467f2f175ba5b876a764d4bd2eecac6f205e7178ded1831",
"network": "BASE_MAINNET",
"timestamp": 1741112159000,
"nonce": 1958,
"fromUser": {
"address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
"displayName": {
"value": "0xjasper.eth",
"source": "ENS"
},
"farcasterProfile": {
"fid": 177,
"username": "jasper"
}
},
"toUser": {
"address": "0x03059433bcdb6144624cc2443159d9445c32b7a8",
"displayName": {
"value": "0x0305...b7a8",
"source": "ADDRESS"
},
"farcasterProfile": null
}
},
"interpretation": {
"processedDescription": "Swapped 0.0021 ETH for 4.455 USDC and transferred to 0x9b3a...4b30",
"description": "Swapped $1 for $2 and transferred to $3",
"descriptionDisplayItems": [
{
"type": "token",
"tokenAddress": "0x0000000000000000000000000000000000000000",
"amountRaw": "2108250382006340",
"network": "BASE_MAINNET",
"tokenV2": {
"decimals": 18,
"symbol": "ETH",
"name": "Ether",
"imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
"priceData": {
"price": 2193.02,
"priceChange5m": 0.3334503550135537,
"priceChange1h": 0.24088764855445532,
"priceChange24h": 2.5226014912818284,
"volume24h": 1709361.375,
"totalLiquidity": 56453154.54727115,
"marketCap": null
}
}
},
{
"type": "token",
"tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"amountRaw": "4455000",
"network": "BASE_MAINNET",
"tokenV2": {
"decimals": 6,
"symbol": "USDC",
"name": "USD Coin",
"imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.png",
"priceData": {
"price": 0.99999803,
"priceChange5m": 0.17923303517666245,
"priceChange1h": 0.43945707785084664,
"priceChange24h": 0,
"volume24h": 618261760,
"totalLiquidity": 80022151.00641671,
"marketCap": 157451622.3996868
}
}
},
{
"type": "actor",
"address": "0x9b3a20176d2c5d0a22dae382496416a1a8934b30",
"account": {
"displayName": {
"value": "0x9b3a...4b30",
"source": "ADDRESS"
},
"farcasterProfile": null
}
}
]
},
"perspectiveDelta": {
"account": {
"address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
"displayName": {
"value": "0xjasper.eth",
"source": "ENS"
},
"farcasterProfile": {
"fid": 177,
"username": "jasper",
"metadata": {
"imageUrl": "https://i.seadn.io/gae/GGk8oCF1aOIhymm-IRnJj4GuL7oajAwCXA9uJgxmkVk-aVhfSB2OrOVdnT88OnIg5XQWj1YhHGcPEbTXJeaiTtZdNZPuZd_enYb6qEw?w=500&auto=format"
}
}
},
"nftDeltasCount": 0,
"tokenDeltasCount": 1,
"nftDeltasV2": {
"edges": []
},
"tokenDeltasV2": {
"edges": [
{
"node": {
"address": "0x0000000000000000000000000000000000000000",
"amount": -0.00210825038200634,
"amountRaw": "-2108250382006340",
"token": {
"symbol": "ETH",
"imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
"priceData": {
"price": 2193.02,
"priceChange24h": 2.5226014912818284
}
}
}
}
]
}
},
"eventHash": "8bdc655f"
}
},
]
}
}
}

Key Features

1. Account Abstraction Support

The endpoint handles account abstraction by focusing on the actual signer of transactions. This provides:

  • Attribution of smart contract wallet transactions (Safe, Argent, etc.) to their owners
  • Correct representation of multi-signature transactions
  • Proper tracking of transactions through account abstraction infrastructure
  • Support for modern wallet infrastructure and ERC-4337 compliant smart accounts

This creates a user-centric view of transaction history regardless of which wallet implementation is being used.

This grouping helps organize related transactions together, making it easier to understand complex operations that involve multiple onchain actions.

2. Enhanced Filtering Options

The new endpoint provides more granular filtering options:

filters: {
network: [Network!] # Filter by specific networks
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, mint, NFT sale, etc.)
contractAddress: [Address!] # Filter by contract interacted with
}

This allows for more targeted queries such as "Show me all Uniswap V3 transactions" or "Show me all transactions where I received ETH from a specific address."

3. Detailed Asset Deltas

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

  • tokenDeltasV2: Shows token balance changes with positive (received) and negative (sent) amounts
  • nftDeltasV2: Shows NFT balance changes with collection and token details

This makes it much clearer to visualize what happened in each transaction instead of having to infer from attachments.

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

Arguments

ArgumentDescriptionType
subjectsList of addresses to query (required)[Address!]!
perspectiveTransaction perspective filterTransactionHistoryV2Perspective = Signer
firstNumber of results to returnInt = 10
afterCursor for paginationString
filtersAdditional filtering optionsTransactionHistoryV2FiltersArgs

Fields

Root Response Fields

FieldDescriptionType
edgesList of transaction entries[TimelineV2EntryEdge!]!
pageInfoPagination informationPageInfo!
totalCountTotal number of transactions in result setInt!

TimelineEventV2Entries Fields

FieldDescriptionType
idUnique identifierID!
entriesList of transaction events[TimelineEventV2!]!

TimelineEventV2 Fields

FieldDescriptionType
idUnique identifierID!
hashTransaction hashString!
networkNetwork where transaction occurredNetwork!
timestampTransaction timestamp (in milliseconds)Timestamp!
fromAddressSender accountAccount!
toAddressRecipient accountAccount
methodSighashMethod signature hashString!
methodSignatureHuman-readable method signatureString
appAssociated applicationApp
interpretationHuman-readable descriptionActivityInterpretation!
perspectiveTransaction perspectiveString!
deltasAsset changes in this transactionActivityAccountDeltaConnection!

ActivityAccountDeltaEntries Fields

FieldDescriptionType
idUnique identifierID!
entriesList of activity delta events[ActivityTimelineEventDelta!]!

ActivityTimelineEventDelta Fields

FieldDescriptionType
transactionHashTransaction hashString!
networkNetwork where transaction occurredNetwork!
transactionBlockTimestampBlock timestamp (in milliseconds)Timestamp!
nftCountNumber of NFTs involvedInt!
fungibleCountNumber of tokens involvedInt!
perspectiveAccountAccount perspectiveAccount!
fromSender accountAccount!
toRecipient accountAccount

Token Delta Fields

FieldDescriptionType
addressToken contract addressString!
amountToken amount (positive for received, negative for sent)Float
tokenToken detailsFungibleToken

NFT Delta Fields

FieldDescriptionType
collectionAddressCollection contract addressString!
tokenIdNFT IDString!
amountNFT quantityFloat!
nftNFT detailsNftToken

TransactionHistoryV2Perspective Enum

ValueDescription
SignerOnly include transactions signed by subject addresses (default)
ReceiverOnly include transactions where subjects received assets
AllInclude all transactions involving subject addresses

Common Use Cases

1. Basic Transaction History

For a simple transaction list showing what happened:

query {
transactionHistoryV2(subjects: ["0xYourAddress"]) {
edges {
node {
... on TimelineEventV2Entries {
entries {
hash
timestamp
fromAddress { displayName { value } }
toAddress { displayName { value } }
interpretation { processedDescription }
}
}
}
}
}
}

2. Token Transfer History

To focus only on specific token transfers:

query {
transactionHistoryV2(
subjects: ["0xYourAddress"],
filters: {
tokenAddress: ["0xTokenAddress"]
}
) {
edges {
node {
... on TimelineEventV2Entries {
entries {
hash
timestamp
interpretation { processedDescription }
deltas {
edges {
node {
tokenDeltasV2 {
edges {
node {
address
amount
token { symbol }
}
}
}
}
}
}
}
}
}
}
}
}

3. Activity From Specific Contracts

To track interactions with specific contracts:

query {
transactionHistoryV2(
subjects: ["0xYourAddress"],
filters: {
contractAddress: ["0xContractAddress"]
}
) {
edges {
node {
... on TimelineEventV2Entries {
entries {
hash
app { name }
interpretation { processedDescription }
}
}
}
}
}
}

Best Practices

  1. Use Delta Information: deltas provide the most accurate picture of what changed in a wallet, clearly showing assets sent and received
  2. Consider Perspective: Choose the appropriate perspective based on your use case:
    • Signer for user-initiated transactions (properly attributes account abstraction transactions)
    • Receiver for incoming transactions
    • All for complete history
  3. Leverage Account Abstraction Support: Take advantage of the improved signer attribution when working with smart contract wallets and account abstraction frameworks
  4. Optimize Query Size: Only request the fields you need to reduce response size
  5. Utilize Filtering: Use the enhanced filters to narrow down results for specific use cases

The endpoint provides accurate transaction attribution for users of smart contract wallets (Safe, Argent, ZeroDev, etc.) and those using account abstraction frameworks like ERC-4337.

note

Transactions are presented from the perspective specified in the perspective parameter. The default is Signer, which shows transactions from the point of view of the initiating address.

tip

When working with token amounts in deltas, the amount field is already adjusted for decimals, making it ready for display. Positive values indicate tokens received, negative values indicate tokens sent.