Onchain Search

Get comprehensive search results across multiple chains and entity types with a single query. The search endpoint allows you to find tokens, NFT collections, apps, users, transactions, and more.

`search`

Takes a search input and optional filters. Returns search results across multiple entity types and networks simultaneously.

Cross-chain search across all supported networks
Multi-entity results (tokens, NFTs, apps, users, transactions)
Category filtering for targeted searches
Configurable results limit per category

Example Use Case: NFT Collection Search

Search specifically for NFT collections across all networks:

Try it now

Example Variables

{
  "input": {
    "search": "azuki",
    "categories": ["NFT_COLLECTION"],
    "maxResultsPerCategory": 5
  }
}

Example Query

query NFTCollectionSearch ($input: SearchPublicInput!) {
  search(input: $input) {
    results {
      # NFT Collection-specific fields
      ... on NftCollectionResult {
        category
        address
        network
        collection {
          displayName
          symbol
          description
          nftStandard
          deployedAt

          floorPrice {
            valueUsd
          }
          topOfferPrice {
            valueUsd
          }
          medias {
            logo {
              fileSize
              height
              width
              mimeType
              predominantColor
              blurhash
              thumbnail
              medium
              large
              original
            }
          }

        }
      }
    }
  }
}

Example Response

{
  "data": {
    "search": {
      "results": [
        {
          "category": "NFT_COLLECTION",
          "address": "0xed5af388653567af2f388e6224dc7c4b3241c544",
          "network": "ETHEREUM_MAINNET",
          "collection": {
            "displayName": "Azuki",
            "symbol": "AZUKI",
            "description": "Take the red bean to join the garden. View the collection at [azuki.com/gallery](https://azuki.com/gallery).\r\n\r\nAzuki starts with a collection of 10,000 avatars that give you membership access to The Garden: a corner of the internet where artists, builders, and web3 enthusiasts meet to create a decentralized future. Azuki holders receive access to exclusive drops, experiences, and more. Visit [azuki.com](https://azuki.com) for more details.\r\n\r\nWe rise together. We build together. We grow together.",
            "nftStandard": "ERC_721",
            "deployedAt": 1641791997000,
            "floorPrice": {
              "valueUsd": 4718.868
            },
            "topOfferPrice": {
              "valueUsd": 4611.621
            },
            "medias": {
              "logo": {
                "fileSize": 1215,
                "height": 250,
                "width": 250,
                "mimeType": "image/png",
                "predominantColor": "#c15661",
                "blurhash": "U6MDKU].8w]:].jZayj[00ae.mWB[roLofjZ",
                "thumbnail": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xed5af388653567af2f388e6224dc7c4b3241c544/logo.png&width=100&checksum=w-UhZ2YEVfAIHMJb9HzttVOJmiRMKXRV1k7UhiyHNPQ",
                "medium": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fcollections%2Fethereum%2F0xed5af388653567af2f388e6224dc7c4b3241c544%2Flogo.png&width=250&checksum=5af3d",
                "large": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fcollections%2Fethereum%2F0xed5af388653567af2f388e6224dc7c4b3241c544%2Flogo.png&width=500&checksum=d31de",
                "original": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xed5af388653567af2f388e6224dc7c4b3241c544/logo.png&width=100&checksum=w-UhZ2YEVfAIHMJb9HzttVOJmiRMKXRV1k7UhiyHNPQ"
              }
            }
          }
        },
        {
          "category": "NFT_COLLECTION",
          "address": "0xb6a37b5d14d502c3ab0ae6f3a0e058bc9517786e",
          "network": "ETHEREUM_MAINNET",
          "collection": {
            "displayName": "Azuki Elementals",
            "symbol": "ELEM",
            "description": "Azuki Elementals are a collection of 20,000 characters within the four domains of the Garden.\r\n\r\nTake the red bean. azuki.com/elementals/reveal",
            "nftStandard": "ERC_721",
            "deployedAt": 1687207415000,
            "floorPrice": {
              "valueUsd": 451.1345055
            },
            "topOfferPrice": {
              "valueUsd": 434.35035
            },
            "medias": {
              "logo": {
                "fileSize": 1766,
                "height": 250,
                "width": 250,
                "mimeType": "image/png",
                "predominantColor": "#454545",
                "blurhash": "U67^}Wof00of-;fQM{j[00WB~qWB00j[-;WB",
                "thumbnail": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb6a37b5d14d502c3ab0ae6f3a0e058bc9517786e/logo.png&width=100&checksum=8RouYg1m_3Az8qWepjFiOm71Q9Sh01qoTziIHNyzl1U",
                "medium": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb6a37b5d14d502c3ab0ae6f3a0e058bc9517786e/logo.png&width=250&checksum=8RouYg1m_3Az8qWepjFiOm71Q9Sh01qoTziIHNyzl1U",
                "large": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fcollections%2Fethereum%2F0xb6a37b5d14d502c3ab0ae6f3a0e058bc9517786e%2Flogo.png&width=500&checksum=f63e8",
                "original": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0xb6a37b5d14d502c3ab0ae6f3a0e058bc9517786e/logo.png&width=100&checksum=8RouYg1m_3Az8qWepjFiOm71Q9Sh01qoTziIHNyzl1U"
              }
            }
          }
        },
        {
          "category": "NFT_COLLECTION",
          "address": "0x3af2a97414d1101e2107a70e7f33955da1346305",
          "network": "ETHEREUM_MAINNET",
          "collection": {
            "displayName": "Azuki Elemental Beans",
            "symbol": "MBEAN",
            "description": "Azuki Elemental Beans can be consumed to take you into the Garden, revealing your Azuki Elemental. Reveal available immediately after the sale closes. \r\n\r\nFind your domain. Be in your element.\r\n\r\nazuki.com/elementals",
            "nftStandard": "ERC_721",
            "deployedAt": 1686804431000,
            "floorPrice": {
              "valueUsd": 1519.3325
            },
            "topOfferPrice": {
              "valueUsd": 1108.219
            },
            "medias": {
              "logo": {
                "fileSize": 1239176,
                "height": 250,
                "width": 250,
                "mimeType": "image/gif",
                "predominantColor": "#ae2954",
                "blurhash": "U5J{-G]oIj]n]qjuS0jsEGfP-aa},Bjs$moM",
                "thumbnail": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fcollections%2Fethereum%2F0x3af2a97414d1101e2107a70e7f33955da1346305%2Flogo.gif&width=100&checksum=12d6e",
                "medium": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0x3af2a97414d1101e2107a70e7f33955da1346305/logo.gif&width=250&checksum=kderNeJHMC04NyU-sDe_Tzmm2GSIjHAJM6PMsiURbUk",
                "large": "https://zapper.xyz/z/images/?url=https%3A%2F%2Fstorage.googleapis.com%2Fzapper-fi-assets%2Fnfts%2Fcollections%2Fethereum%2F0x3af2a97414d1101e2107a70e7f33955da1346305%2Flogo.gif&width=500&checksum=fd375",
                "original": "https://images.zapper.xyz/z/?path=zapper-fi-assets/nfts/collections/ethereum/0x3af2a97414d1101e2107a70e7f33955da1346305/logo.gif&width=100&checksum=kderNeJHMC04NyU-sDe_Tzmm2GSIjHAJM6PMsiURbUk"
              }
            }
          }
        }
      ]
    }
  }
}

note

Resolving accounts, NFT collections, ERC20 tokens, and app metadata on top of search results adds the cost of those queries. Pricing for those queries are available in the pricing section.

Example Use Case: Chain Specific Token Search

Search for tokens across one or multiple specified networks:

Try it now

Example Variables

{
  "input": {
    "search": "dog",
    "networks": ["BASE_MAINNET"],
    "categories": ["ERC20_TOKEN"],
    "maxResultsPerCategory": 5
  }
}

Example Query

query ChainSpecificTokenSearch ($input: SearchPublicInput!) {
  search(input: $input) {
    results {
      # Token-specific fields
      ... on Erc20TokenResult {
        category
        address
        symbol
        name
        erc20 {
          priceData {
            price
            priceChange24h
          }
          imageUrlV2
          networkV2 {
            name
          }
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "search": {
      "results": [
        {
          "category": "ERC20_TOKEN",
          "address": "0x6921b130d297cc43754afba22e5eac0fbf8db75b",
          "symbol": "doginme",
          "name": "doginme",
          "erc20": {
            "priceData": {
              "price": 0.0005908429488639462,
              "priceChange24h": -37.67233610683073
            },
            "imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x6921b130d297cc43754afba22e5eac0fbf8db75b.png",
            "networkV2": {
              "name": "Base"
            }
          }
        },
        {
          "category": "ERC20_TOKEN",
          "address": "0x3b916b8f6a710e9240ff08c1dd646dd8e8ed9e1e",
          "symbol": "DOG",
          "name": "Base Dog",
          "erc20": {
            "priceData": {
              "price": 182.12161884938496,
              "priceChange24h": -6.182620347036616
            },
            "imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x3b916b8f6a710e9240ff08c1dd646dd8e8ed9e1e.png",
            "networkV2": {
              "name": "Base"
            }
          }
        },
        {
          "category": "ERC20_TOKEN",
          "address": "0x942632921aa4a3bde3930c0311337520047a1cc5",
          "symbol": "KEYDOG",
          "name": "Keyboard DOG",
          "erc20": {
            "priceData": {
              "price": 0.00003544760565474463,
              "priceChange24h": 89.47560106512309
            },
            "imageUrlV2": null,
            "networkV2": {
              "name": "Base"
            }
          }
        },
        {
          "category": "ERC20_TOKEN",
          "address": "0xda977a3393106fed8190fdf5ed3686a518da609b",
          "symbol": "BASEDOGE",
          "name": "BASEDOGE",
          "erc20": {
            "priceData": {
              "price": 0.05007083936696972,
              "priceChange24h": -6.182620347036616
            },
            "imageUrlV2": null,
            "networkV2": {
              "name": "Base"
            }
          }
        },
        {
          "category": "ERC20_TOKEN",
          "address": "0xafb89a09d82fbde58f18ac6437b3fc81724e4df6",
          "symbol": "DOG",
          "name": "The Doge NFT",
          "erc20": {
            "priceData": {
              "price": 0.0008773050600356786,
              "priceChange24h": -6.654191019963984
            },
            "imageUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0xafb89a09d82fbde58f18ac6437b3fc81724e4df6.png",
            "networkV2": {
              "name": "Base"
            }
          }
        }
      ]
    }
  }
}

Example Use Case: Global Search

Let's create a global search component that returns relevant results across multiple entity types:

Try it now

Example Variables

{
  "input": {
    "search": "dog",
    "maxResultsPerCategory": 3
  }
}

Example Query

query GlobalSearchExample ($input: SearchPublicInput!) {
  search(input: $input) {
    results {
      # App-specific fields
      ... on AppResult {
        category
        appId
        app {
          displayName
          description
          url
          imgUrl
        }
      }
      
      # Token-specific fields
      ... on Erc20TokenResult {
        category
        address
        symbol
        name
        erc20 {
          priceData {
            price
            priceChange24h
          }
          imageUrlV2
          networkV2 {
            name
          }
        }
      }

      
      # NFT Collection-specific fields
      ... on NftCollectionResult {
        category
        address
        network
        collection {
          displayName
          description
          floorPrice {
            valueUsd
          }
          medias {
            logo {
              thumbnail
              medium
              blurhash
            }
          }
        }
      }
      
      # User-specific fields
      ... on UserResult {
        category
        address
        account {
          displayName {
            value
          }
          farcasterProfile {
            username
            fid
            metadata {
              imageUrl
              displayName
            }
          }
        }
      }
      ... on UnifiedErc20TokenResult {
        category
        name
        symbol
        imageUrl
        groupedFungibleTokens {
          address
          networkV2 {
            chainId
            name
          }
          priceData {
            price
            priceChange24h
          }
        }
      }
      ... on UnifiedGasTokenResult {
        category
        name
        symbol
        imageUrl
        groupedGasTokens {
          address
          networkV2 {
            chainId
            name
          }
          priceData {
            price
            priceChange24h
          }
        }
      }
    }
  }
}

Best Practices

When implementing the search functionality in your application, consider these best practices:

Implement Debouncing

To avoid sending too many requests as users type their search query, implement a debounce function:

// Example debounce implementation for search input
function debounce(func, wait) {
  let timeout;
  return function(...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), wait);
  };
}

// Usage
const debouncedSearch = debounce((searchTerm) => {
  // Execute your GraphQL search query here
  executeSearchQuery(searchTerm);
}, 300); // Wait 300ms after the user stops typing

// Attach to input
searchInput.addEventListener('input', (e) => {
  debouncedSearch(e.target.value);
});

Minimum Query Length

Consider requiring a minimum number of characters (typically 2-3) before triggering a search to avoid overly broad results:

function handleSearch(searchTerm) {
  if (searchTerm.length < 2) return; // Only search when input has at least 2 characters
  
  // Execute your search query
  executeSearchQuery(searchTerm);
}

Loading States

Always show loading indicators to provide feedback while search results are being fetched:

// React example
function SearchComponent() {
  const [loading, setLoading] = useState(false);
  const [results, setResults] = useState([]);
  
  const handleSearch = async (term) => {
    setLoading(true);
    try {
      const data = await executeSearchQuery(term);
      setResults(data.search.results);
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <div>
      <input onChange={(e) => handleSearch(e.target.value)} />
      {loading && <LoadingSpinner />}
      {results.map(result => <ResultItem key={result.id} data={result} />)}
    </div>
  );
}

Arguments

Argument	Description	Type	Required
`input.search`	Search query string	`String!`	Yes
`input.networks`	Networks to search on	`[Network!]`	No
`input.categories`	Entity types to search for	`[OnchainSearchCategory!]`	No
`input.maxResultsPerCategory`	Maximum results per category	`Float`	No (Default: 3)

Response Fields

Field	Description	Type
`results`	Array of search results	`[OnchainSearchResultObject!]!`

Each result object includes these common fields:

Field	Description	Type
`id`	Unique identifier for the result	`String!`
`category`	Entity type of the result	`SearchResultCategory!`
`title`	Display title for the result	`String!`
`imageUrl`	URL for result image/icon	`String`
`score`	Relevance score	`String`

Category-Specific Fields

Each result type has additional fields relevant to its category:

App Results

appId: App identifier
name: App name
networks: Networks the app is available on
app: Detailed app information

Token Results (ERC20_TOKEN)

address: Token contract address
symbol: Token symbol
name: Token name
decimals: Token decimals
network: Network where token exists
erc20: Detailed token information

Unified Token Results (UNIFIED_ERC20_TOKEN)

symbol: Token symbol
name: Token name
groupId: Token group identifier
perNetworkInfo: Network-specific information
groupedFungibleTokens: Associated tokens

NFT Collection Results

address: Collection contract address
name: Collection name
network: Network where collection exists
nftStandard: NFT standard (ERC721, ERC1155)
collection: Detailed collection information

User Results

address: User address
ens: ENS domain (if available)
lens: Lens handle (if available)
farcaster: Farcaster username (if available)
account: Detailed account information

Transaction Results

hash: Transaction hash
network: Network of transaction

Enums

enum OnchainSearchCategory {
  APP
  FARCASTER_PROFILE
  GAS_TOKEN
  UNIFIED_GAS_TOKEN
  ERC20_TOKEN
  NFT_COLLECTION
  UNIFIED_ERC20_TOKEN
  USER
  TRANSACTION
}

search​

Example Use Case: NFT Collection Search​

Example Variables​

Example Query​

Example Response​

Example Use Case: Chain Specific Token Search​

Example Variables​

Example Query​

Example Response​

Example Use Case: Global Search​

Example Variables​

Example Query​

Best Practices​

Implement Debouncing​

Minimum Query Length​

Loading States​

Arguments​

Response Fields​

Category-Specific Fields​

App Results​

Token Results (ERC20_TOKEN)​

Unified Token Results (UNIFIED_ERC20_TOKEN)​

NFT Collection Results​

User Results​

Transaction Results​

Enums​

`search`

Example Use Case: NFT Collection Search

Example Variables

Example Query

Example Response

Example Use Case: Chain Specific Token Search

Example Variables

Example Query

Example Response

Example Use Case: Global Search

Example Variables

Example Query

Best Practices

Implement Debouncing

Minimum Query Length

Loading States

Arguments

Response Fields

Category-Specific Fields

App Results

Token Results (ERC20_TOKEN)

Unified Token Results (UNIFIED_ERC20_TOKEN)

NFT Collection Results

User Results

Transaction Results

Enums