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 transactionHistory 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 transactionHistory($addresses: [Address!], $realtimeInterpretation: Boolean, $isSigner: Boolean) {
  transactionHistory(addresses: $addresses, realtimeInterpretation: $realtimeInterpretation, isSigner: $isSigner) {
    edges {
      node {
        transaction {
          fromUser {
            address
            displayName {
              value
            }
          }
          toUser {
            displayName {
              value
            }
          }
        }
        app {
          slug
          name
          imgUrl
        }
        interpretation {
          # Basic text description
          processedDescription
          # Templated description with reference tokens
          description
          # Structured data for referenced elements
          descriptionDisplayItems {
            ... on TokenDisplayItem {
              type
              network
              tokenAddress
              amountRaw
              tokenV2 {
                address
                symbol
                decimals
                name
                imageUrl
                onchainMarketData {
                  price(currency: USD)
                  priceChange24h
                  marketCap
                }
              }
            }
            ... on NFTDisplayItem {
              type
              network
              collectionAddress
              tokenId
              quantity
              nftToken {
                collection {
                  name
                }
              }
            }
            ... on ActorDisplayItem {
              type
              address
              account {
                address
                displayName {
                  value
                }
                farcasterProfile {
                  username
                  fid
                }
              }
            }
            ... on NFTCollectionDisplayItem {
              collectionAddress
              network
              nftCollection {
                displayName
                medias {
                  logo {
                    thumbnail
                  }
                }
              }
            }
            ... on StringDisplayItem {
              stringValue
              type
            }
            ... on NetworkDisplayItem {
              chainId
              type
              networkMetadata {
                name
              }
            }
          }
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "transactionHistory": {
      "edges": [
        {
          "node": {
            "transaction": {
              "fromUser": {
                "address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
                "displayName": {
                  "value": "0xjasper.eth"
                }
              },
              "toUser": {
                "displayName": {
                  "value": "LI.FI: LiFi Diamond"
                }
              }
            },
            "app": {
              "slug": "lifi",
              "name": "Li.Fi",
              "imgUrl": "https://storage.googleapis.com/zapper-fi-assets/apps%2Flifi.png"
            },
            "interpretation": {
              "processedDescription": "Swapped 0.015 ETH for 3,933.0058 B3",
              "description": "Swapped $1 for $2",
              "descriptionDisplayItems": [
                {
                  "type": "token",
                  "network": "BASE_MAINNET",
                  "tokenAddress": "0x0000000000000000000000000000000000000000",
                  "amountRaw": "15000000000000000",
                  "tokenV2": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "ETH",
                    "decimals": 18,
                    "name": "Ethereum",
                    "imageUrl": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
                    "onchainMarketData": {
                      "price": 2728.31,
                      "priceChange24h": 1.3804510953515203,
                      "marketCap": null
                    }
                  }
                },
                {
                  "type": "token",
                  "network": "BASE_MAINNET",
                  "tokenAddress": "0xb3b32f9f8827d4634fe7d973fa1034ec9fddb3b3",
                  "amountRaw": "3933005790210873157867",
                  "tokenV2": {
                    "address": "0xb3b32f9f8827d4634fe7d973fa1034ec9fddb3b3",
                    "symbol": "B3",
                    "decimals": 18,
                    "name": "B3 (Base)",
                    "imageUrl": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0xb3b32f9f8827d4634fe7d973fa1034ec9fddb3b3.png",
                    "onchainMarketData": {
                      "price": 0.008344709674145174,
                      "priceChange24h": 0.48220918679768854,
                      "marketCap": 834470967.4145174
                    }
                  }
                }
              ]
            }
          }
        },
      ]
    }
  }
}

Available Fields

Timeline Query Parameters

Field	Description	Type	Default
addresses	Array of addresses to fetch transactions for	[Address!]	-
isSigner	Only return transactions initiated by these addresses	Boolean	true
spamFilter	Filter out spam transactions	Boolean	true
first	Number of transactions to return	Int	25
after	Cursor for pagination	String	-

Transaction Fields

Field	Description	Type
timestamp	Unix timestamp in milliseconds	Timestamp!
hash	Transaction hash	String!
network	Network where transaction occurred	Network!

App Fields

Field	Description	Type
databaseId	Unique application ID	Int!
displayName	The typical display name of the application	String!
description	Description of the application	String!
url	Application website	String
imgUrl	Application image URL	String!
slug	Unique application slug	String!
links	Application links	AppLinks
categoryId	Category ID	Int
category	Application category	AppCategoryObject

Transfer Fields

Field	Description	Type
type	Type of transfer ("token" or "nft")	String!
network	Network of the asset	Network!
tokenAddress	Contract address (for tokens)	String
amountRaw	Raw amount (for tokens)	String
collectionAddress	Collection address (for NFTs)	String
tokenId	Token ID (for NFTs)	String
quantity	Number of NFTs transferred	Float

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.

note

The isSigner parameter determines whether you see all transactions involving the addresses or only transactions initiated by them. Set to true to see only outgoing transactions.

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

Try in sandbox