Transaction History
Access comprehensive onchain activity with rich transaction details, structured asset deltas, and support for both EOA and smart contract wallets.
Try it nowtransactionHistoryV2
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 thesubject
of the transaction (e.g., EOA or contract that signs the transaction)tokenDeltasV2
: Shows token balance changes with positive (received) and negative (sent) amountsnftDeltasV2
: Shows NFT balance changes with collection and token detailsdeltas
: 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 assetsAll
: 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 nowExample 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 nowExample 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 |
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 |
Best Practices
- Use Delta Information:
deltas
provide 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:
Signer
for user-initiated transactions (properly attributes account abstraction transactions)Receiver
for incoming transactionsAll
for 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
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.
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.