Transaction History
Access a chronological feed of onchain transactions for any Farcaster user by first resolving their addresses through their FID or username, then using those addresses to query their transaction history.
Overview
This process involves two steps:
- Query the
farcasterProfileendpoint to get connected addresses - Use the resolved addresses to query the
transactionHistoryV2endpoint
Typical Usage
Step 1: Resolve Farcaster Addresses
First, query the farcasterProfile endpoint using either FIDs or Farcaster usernames to get associated addresses.
Example Variables
{
"fids": [177], // Query by FID
"farcasterUsernames": ["jasper"] // Or query by username
}
Example Accounts Query
query GetFarcasterProfile($username: String) {
farcasterProfile(username: $username) {
username
fid
metadata {
displayName
description
imageUrl
warpcast
}
custodyAddress
connectedAddresses
}
}
Step 2: Fetch Transaction History
Using the connectedAddresses and custodyAddress obtained from Step 1, query the transactionHistory endpoint to get a chronological feed of transactions. This will provide detailed information about each transaction including human-readable descriptions and complete token/NFT transfer data.
Dynamic Transaction Descriptions
One of the most powerful features of the transactionHistory 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
The description fields work alongside (but separate from) the inboundAttachments and outboundAttachments which provide comprehensive data about all assets involved in the transaction.
Example transactionHistory Variables
{
"addresses": [
// Connected addresses
"0xab123bddc9441df7edc6fd681b705f552f2e20ef",
"0xe39528a0627d5aa8f8423172fabb14f77b640595",
"0x52c8ff44260056f896e20d8a43610dd88f05701b",
// Custody address
"0x95e1981ec66ff91c7b4cea7b7287bd620dbd8fcc"
],
"isSigner": true,
"spamFilter": true,
"first": 10
}
Example transactionHistory 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"
}
},
]
}
}
}
tip
When displaying token amounts, remember to adjust amountRaw using the token's decimals value. For example, with 6 decimals, an amountRaw of "1000000" represents 1.0 tokens.
Error Handling
Common scenarios to handle:
- Invalid or non-existent Farcaster username/FID
- Missing optional fields in transaction data
- Pagination limits
Best Practices
- Cache resolved Farcaster addresses to minimize API calls
- Implement proper error handling for invalid profiles
- Use pagination for loading transaction history
- Handle missing or null fields in transaction data