Skip to main content

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:

  1. Query the farcasterProfile endpoint to get connected addresses
  2. Use the resolved addresses to query the transactionHistoryV2 endpoint

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​

  1. Cache resolved Farcaster addresses to minimize API calls
  2. Implement proper error handling for invalid profiles
  3. Use pagination for loading transaction history
  4. Handle missing or null fields in transaction data