Transaction History
Access comprehensive onchain activity with rich transaction details, structured asset deltas, and support for both EOA and smart contract wallets.
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
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) amountsnftDeltasV2: 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 assetsAll: All transactions involving the subject addresses
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 |
Fields
Root Response Fields
| Field | Description | Type |
|---|---|---|
edges | List of transaction entries | [TimelineV2EntryEdge!]! |
pageInfo | Pagination information | PageInfo! |
totalCount | Total number of transactions in result set | Int! |
TimelineEventV2Entries Fields
| Field | Description | Type |
|---|---|---|
id | Unique identifier | ID! |
entries | List of transaction events | [TimelineEventV2!]! |
TimelineEventV2 Fields
| Field | Description | Type |
|---|---|---|
id | Unique identifier | ID! |
hash | Transaction hash | String! |
network | Network where transaction occurred | Network! |
timestamp | Transaction timestamp (in milliseconds) | Timestamp! |
fromAddress | Sender account | Account! |
toAddress | Recipient account | Account |
methodSighash | Method signature hash | String! |
methodSignature | Human-readable method signature | String |
app | Associated application | App |
interpretation | Human-readable description | ActivityInterpretation! |
perspective | Transaction perspective | String! |
deltas | Asset changes in this transaction | ActivityAccountDeltaConnection! |
ActivityAccountDeltaEntries Fields
| Field | Description | Type |
|---|---|---|
id | Unique identifier | ID! |
entries | List of activity delta events | [ActivityTimelineEventDelta!]! |
ActivityTimelineEventDelta Fields
| Field | Description | Type |
|---|---|---|
transactionHash | Transaction hash | String! |
network | Network where transaction occurred | Network! |
transactionBlockTimestamp | Block timestamp (in milliseconds) | Timestamp! |
nftCount | Number of NFTs involved | Int! |
fungibleCount | Number of tokens involved | Int! |
perspectiveAccount | Account perspective | Account! |
from | Sender account | Account! |
to | Recipient account | Account |
Token Delta Fields
| Field | Description | Type |
|---|---|---|
address | Token contract address | String! |
amount | Token amount (positive for received, negative for sent) | Float |
token | Token details | FungibleToken |
NFT Delta Fields
| Field | Description | Type |
|---|---|---|
collectionAddress | Collection contract address | String! |
tokenId | NFT ID | String! |
amount | NFT quantity | Float! |
nft | NFT details | NftToken |
TransactionHistoryV2Perspective Enum
| Value | Description |
|---|---|
Signer | Only include transactions signed by subject addresses (default) |
Receiver | Only include transactions where subjects received assets |
All | Include 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
- Use Delta Information:
deltasprovide the most accurate picture of what changed in a wallet, clearly showing assets sent and received - Consider Perspective: Choose the appropriate perspective based on your use case:
Signerfor user-initiated transactions (properly attributes account abstraction transactions)Receiverfor incoming transactionsAllfor complete history
- Leverage Account Abstraction Support: Take advantage of the improved signer attribution when working with smart contract wallets and account abstraction frameworks
- Optimize Query Size: Only request the fields you need to reduce response size
- 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.