Transaction Timeline

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 accounts endpoint to resolve Farcaster addresses
2. Use the resolved addresses to query the accountsTimeline endpoint

Typical Usage

Step 1: Resolve Farcaster Addresses

First, query the accounts 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 GetFarcasterAddresses($fids: [Float!], $farcasterUsernames: [String!]) {
  accounts(fids: $fids, farcasterUsernames: $farcasterUsernames) {
    farcasterProfile {
      username
      fid
      connectedAddresses
      custodyAddress
    }
  }
}

Step 2: Fetch Transaction Timeline

Using the connectedAddresses and custodyAddress obtained from Step 1, query the accountsTimeline 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.

Example Timeline Variables

{
  "addresses": [
    // Connected addresses
    "0xab123bddc9441df7edc6fd681b705f552f2e20ef",
    "0xe39528a0627d5aa8f8423172fabb14f77b640595",
    "0x52c8ff44260056f896e20d8a43610dd88f05701b",
    // Custody address
    "0x95e1981ec66ff91c7b4cea7b7287bd620dbd8fcc"
  ],
  "isSigner": true,
  "spamFilter": true,
  "first": 10
}

Example Timeline Query

query GetFarcasterTimeline(
  $addresses: [Address!], 
  $isSigner: Boolean = true
) {
  accountsTimeline(
    addresses: $addresses
    isSigner: $isSigner
    spamFilter: true
  ) {
    edges {
      node {
        timestamp
        transaction {
          hash
          network
          fromUser {
            address
            displayName {
              value
            }
          }
          toUser {
            displayName {
              value
            }
          }
        }
        app {
          name
          imgUrl
          tags
        }
        interpretation {
          processedDescription
          inboundAttachments {
            ... on TokenDisplayItem {
              type
              network
              tokenAddress
              amountRaw
              tokenV2 {
                symbol
                decimals
                imageUrl
                marketData {
                  price(currency: USD)
                }
              }
            }
            ... on NFTDisplayItem {
              type
              network
              collectionAddress
              tokenId
              quantity
              nftToken {
                collection {
                  name
                }
              }
            }
          }
          outboundAttachments {
            ... on TokenDisplayItem {
              type
              network
              tokenAddress
              amountRaw
              tokenV2 {
                symbol
                decimals
                imageUrl
                marketData {
                  price(currency: USD)
                }
              }
            }
            ... on NFTDisplayItem {
              type
              network
              collectionAddress
              tokenId
              quantity
              nftToken {
                collection {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "accountsTimeline": {
      "edges": [
        {
          "node": {
            "timestamp": 1736796083000,
            "transaction": {
              "hash": "0x0ba83ae9291cd4f58f082c226eedd5a5fd2fd0dd175fce3e891302b1d7f72cb4",
              "network": "BASE_MAINNET",
              "fromUser": {
                "address": "0x52c8ff44260056f896e20d8a43610dd88f05701b",
                "displayName": {
                  "value": "0xjasper.eth"
                }
              },
              "toUser": {
                "displayName": {
                  "value": "0x0000...3e70"
                }
              }
            },
            "app": {
              "name": "Sound.xyz",
              "imgUrl": "https://storage.googleapis.com/zapper-fi-assets/apps%2Fsound-xyz.png",
              "tags": ["nft-marketplace"]
            },
            "interpretation": {
              "processedDescription": "Minted 1 Sweet Memories",
              "inboundAttachments": [
                {
                  "type": "nft",
                  "network": "BASE_MAINNET",
                  "collectionAddress": "0xab4d845880bfca8016fea84a6f645d2369292514",
                  "tokenId": "8255",
                  "quantity": 1,
                  "nftToken": null
                }
              ],
              "outboundAttachments": [
                {
                  "type": "token",
                  "network": "BASE_MAINNET",
                  "tokenAddress": "0x0000000000000000000000000000000000000000",
                  "amountRaw": "1554000000000000",
                  "tokenV2": {
                    "symbol": "ETH",
                    "decimals": 18,
                    "imageUrl": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
                    "marketData": {
                      "price": 3334.19
                    }
                  }
                }
              ]
            }
          }
        }
        // Additional transactions omitted for brevity
      ]
    }
  }
}

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