--- name: public.zapper.xyz description: public.zapper.xyz provides read-only data access to Zapper's indexed EVM blockchain data, covering token prices (current and historical), NFT metadata and balances, wallet portfolio totals, and on-chain social identity resolution. All endpoints are single-shot queries against Zapper's aggregated multi-chain dataset. No write operations, trading, or streaming feeds are available. host: public.zapper.xyz --- # public.zapper.xyz Zapper's public API host serves agents that need structured, aggregated EVM portfolio and market data without building direct RPC or indexer infrastructure. It covers fungible token pricing, NFT collection and token metadata, wallet-level portfolio summaries across chains, and social identity lookups tied to 0x addresses. It is distinct from raw blockchain RPC hosts in that it returns pre-aggregated USD valuations, social graph data, and NFT floor prices rather than raw on-chain state. ## When to use this host Use public.zapper.xyz when an agent needs aggregated EVM portfolio data (multi-chain USD totals, NFT holdings with valuations), NFT collection or token metadata, current or historical fungible token prices, or on-chain social identity resolution for 0x addresses. Do not use this host for: non-EVM chains; streaming or real-time continuous price feeds (all endpoints are single-shot); write operations such as swaps or transfers; per-app DeFi position breakdowns beyond network-level totals (fetch-portfolio-totals returns network aggregates only, not individual protocol positions); or reverse identity lookups (name to address). For raw on-chain state or contract calls, prefer a direct RPC host. For DeFi protocol-specific position details, a dedicated DeFi data API would be more appropriate. ## Capabilities ### Token Pricing Provides current and historical price data for EVM fungible tokens by contract address and chain, including market cap, volume, and price change metrics. - **`fetch-token-price`** — Returns real-time price, market cap, 24h volume, liquidity, and short-term price changes for a token given its contract address and chain ID. - **`fetch-historical-token-price`** — Returns a token's price at a specific historical timestamp on a given EVM chain, denominated in the requested currency. ### NFT Data Covers the full NFT data surface: collection-level stats (floor price, market cap, holders, recent events) and individual token metadata (traits, media, estimated value, holder info). - **`fetch-nft-collection-metadata`** — Returns NFT collection metadata including name, network, floor price, market cap, holder count, top holders, recent events, and sample NFTs for one or more EVM collections. - **`fetch-nft-token-metadata`** — Returns detailed metadata, traits, media URLs, holder info, estimated value, and collection floor price for a specific NFT token on a given EVM chain. ### Wallet Portfolio Returns aggregated portfolio data for one or more EVM wallets, including cross-chain USD totals broken down by tokens, DeFi apps, and NFTs, as well as per-token NFT holdings with estimated valuations. - **`fetch-portfolio-totals`** — Returns aggregated token, app, and NFT balances broken down by network for one or more EVM wallet addresses, with optional chain filtering. - **`fetch-nft-balances`** — Returns NFT holdings, estimated USD valuations, and collection metadata for one or more EVM wallet addresses, with optional chain and pagination filters. ### Social Identity Resolution Resolves a 0x wallet address to its associated on-chain social identities including ENS, Farcaster, Lens, and Basenames. - **`resolve-wallet-social-identity`** — Resolves on-chain social identities (ENS, Farcaster, Lens, Basenames) for a given 0x wallet address via Zapper. ## Workflows ### NFT Portfolio Valuation with Collection Context *Use when an agent needs to enumerate a wallet's NFT holdings and enrich each collection with floor price, market cap, and holder statistics beyond what the balance endpoint returns.* 1. **`fetch-nft-balances`** — Retrieve all NFT tokens held by the target wallet(s), including per-token estimated USD values and collection addresses. 2. **`fetch-nft-collection-metadata`** — For each distinct collection address returned, fetch floor price, market cap, holder count, and recent events to provide richer context. ### Historical P&L Snapshot *Use when an agent needs to calculate the USD value of a wallet's token holdings at a specific past date, such as for tax reporting or period-over-period performance analysis.* 1. **`fetch-portfolio-totals`** — Retrieve the current cross-chain portfolio composition to identify which tokens and networks the wallet holds. 2. **`fetch-historical-token-price`** — For each token of interest, fetch its price at the target historical timestamp to compute point-in-time valuations. ### Wallet Identity and Portfolio Lookup *Use when an agent needs to display a human-readable identity alongside a wallet's portfolio summary, such as in a user-facing dashboard or social context.* 1. **`resolve-wallet-social-identity`** — Resolve the 0x address to ENS, Farcaster, Lens, or Basename for display purposes. 2. **`fetch-portfolio-totals`** — Fetch the wallet's cross-chain USD portfolio totals to accompany the resolved identity. ### NFT Token Deep Dive *Use when an agent needs both collection-level context and individual token details for a specific NFT, such as comparing a token's estimated value against the collection floor.* 1. **`fetch-nft-collection-metadata`** — Fetch collection floor price, market cap, and holder stats to establish the collection baseline. 2. **`fetch-nft-token-metadata`** — Fetch the specific token's traits, estimated value, last sale, and media to compare against the collection context. ## Skill reference ### `fetch-historical-token-price` **Token Price Snapshot** — Returns a token's price at a specific historical timestamp on a given EVM chain, denominated in the requested currency. *Use when:* Use when an agent needs the price of an EVM token at a past point in time, such as for portfolio valuation, P&L calculation, or tax reporting at a specific date. *Not for:* Do not use for real-time or streaming price data; use a current-price endpoint instead. Not suitable for tokens without historical price data on Zapper. **Inputs:** - `address` (string, required) — The 0x contract address of the token on the specified chain. - `chainId` (integer, required) — The EVM chain ID where the token contract is deployed (e.g. 8453 for Base, 1 for Ethereum mainnet). - `timestamp` (integer, required) — Unix timestamp in milliseconds for the historical price lookup. - `currency` (string) — Currency code for the returned price (default: USD). **Returns:** Returns a fungibleTokenV2 object with token metadata (name, symbol, decimals, imageUrlV2) and a historicalPrice object containing the price in USD and the nearest available timestamp. **Example:** `{"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": 8453, "currency": "USD", "timestamp": 1719897600000}` --- ### `fetch-nft-collection-metadata` **Zapper NFT Collection Metadata** — Returns NFT collection metadata including name, network, floor price, market cap, holder count, top holders, recent events, and sample NFTs for one or more EVM collections. *Use when:* Use when an agent needs on-chain NFT collection stats such as floor price in USD, market cap, holder count, sample token images, or recent transfer/sale events for a given contract address and chain ID. *Not for:* Do not use for individual NFT token lookups by token ID, wallet portfolio queries, or non-EVM chains. Not suitable for real-time streaming price feeds — this is a single-shot metadata fetch. **Inputs:** - `collections` (array, required) — Array of collection objects, each with an EVM contract address and chain ID. Multiple collections can be queried in one request. **Returns:** Returns a nftCollectionsV2 array where each entry contains the collection name, network, address, NFT standard, supply, holdersCount, marketCap, floorPrice in USD, topOfferPrice, logo/banner media URLs, social links, and paginated sample NFTs with traits and sale data. **Example:** `{"collections": [{"address": "0xa449b4f43d9a33fcdcf397b9cc7aa909012709fd", "chainId": 8453}]}` --- ### `resolve-wallet-social-identity` **Social Identity Resolver** — Resolves on-chain social identities (ENS, Farcaster, Lens, Basenames) for a given 0x wallet address via Zapper. *Use when:* Use when an agent needs to look up the social identity of a wallet address, such as finding a user's ENS name, Farcaster username/fid, Lens handle, or Basename from their 0x address. *Not for:* Do not use for reverse lookups (name to address); this resolves address to identity only. Not suitable for bulk address resolution or streaming identity updates. **Inputs:** - `address` (string, required) — The 0x wallet address to resolve identity for. **Returns:** Returns a data.account object with displayName (value+source), ensRecord.name, basename, farcasterProfile (username+fid), and lensProfile.handle for the given wallet address. **Example:** `{"address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"}` --- ### `fetch-nft-token-metadata` **Zapper NFT Token Metadata** — Returns detailed metadata, traits, media URLs, holder info, estimated value, and collection floor price for a specific NFT token on a given EVM chain. *Use when:* Use when an agent needs full metadata for a single NFT token — including its traits, image URLs, current holder, last sale price, estimated value, and parent collection details — identified by contract address, token ID, and chain. *Not for:* Do not use for bulk collection-level queries or listing all tokens in a collection; this endpoint resolves exactly one token at a time. **Inputs:** - `chainId` (integer, required) — The Chain ID of the network where the NFT lives (e.g. 1 for Ethereum Mainnet, 8453 for Base). - `collectionAddress` (string, required) — The 0x contract address of the NFT collection. - `tokenId` (string, required) — The specific token ID within the collection to fetch metadata for. **Returns:** Returns a nftTokenV2 object with name, description, traits array, mediasV3 image/animation URLs, collection floor price and social links, holder wallet with ENS/Farcaster info, estimated value in USD and ETH, and lastSale (null if none). **Example:** `{"chainId": 8453, "collectionAddress": "0xa449b4f43d9a33fcdcf397b9cc7aa909012709fd", "tokenId": "1"}` --- ### `fetch-nft-balances` **Zapper NFT Balances** — Returns NFT holdings, estimated USD valuations, and collection metadata for one or more EVM wallet addresses, with optional chain and pagination filters. *Use when:* Use when an agent needs to enumerate NFTs held by one or more 0x wallet addresses, including per-token estimated USD values, collection details, and total portfolio USD balance, optionally filtered to specific chains. *Not for:* Do not use for fungible token (ERC-20) balances; use a token-balances endpoint instead. Not suitable for real-time floor price feeds — values are point-in-time estimates. **Inputs:** - `addresses` (array, required) — Array of 0x wallet addresses to scan for NFT holdings. - `first` (integer) — Number of NFT tokens to return per page. Defaults to 10. - `sortBy` (string) — Sort order for results. Accepted values: "USD_WORTH", "NETWORK", "COLLECTION". Defaults to "USD_WORTH". - `chainIds` (array) — Optional list of EVM chain IDs to filter results by (e.g. 1 for Ethereum mainnet, 8453 for Base). **Returns:** Returns totalBalanceUSD (~171120 USD), totalTokensOwned, and a byToken.edges array of NFT nodes each with tokenId, name, estimatedValue.valueUsd, collection name/address, and media URLs. **Example:** `{"addresses":["0x402Feee072D655B85e08f1751AF9ddbCd249521f","0xd8da6bf26964af9d7eed9e03e53415d37aa96045"],"first":25,"sortBy":"USD_WORTH","chainIds":[8453]}` --- ### `fetch-portfolio-totals` **Cross-Chain Portfolio Totals** — Returns aggregated token, app, and NFT balances broken down by network for one or more EVM wallet addresses, with optional chain filtering. *Use when:* Use when an agent needs a cross-chain USD portfolio summary for one or more wallet addresses, including per-network token balances, DeFi app balances, and NFT balances. *Not for:* Do not use for per-token or per-app position details; this endpoint returns network-level totals only. Not suitable for non-EVM (non-0x) addresses. **Inputs:** - `addresses` (array, required) — Array of 0x wallet addresses to aggregate portfolio totals for. - `chainIds` (array) — Optional list of EVM chain IDs to filter results by (e.g. [1, 8453] for Ethereum and Base). Omit to return all chains. **Returns:** Returns portfolioV2 with tokenBalances, appBalances, and nftBalances, each containing a totalBalanceUSD and a byNetwork edges array with per-chain USD values. **Example:** `{"addresses": ["0xd8da6bf26964af9d7eed9e03e53415d37aa96045"], "chainIds": [1, 8453]}` --- ### `fetch-token-price` **Zapper Token Price** — Returns real-time price, market cap, 24h volume, liquidity, and short-term price changes for a token given its contract address and chain ID. *Use when:* Use when an agent needs current price data, market cap, or recent price change percentages for a specific EVM token identified by its contract address and chain ID. *Not for:* Do not use for streaming or continuous price feeds; this is a single-shot lookup. Not suitable for retrieving wallet balances or portfolio values — use a portfolio API instead. **Inputs:** - `address` (string, required) — The 0x contract address of the token. - `chainId` (integer, required) — The EVM chain ID where the token is deployed (e.g. 8453 for Base, 1 for Ethereum mainnet). - `currency` (string) — Currency for price data. Defaults to USD. **Returns:** Returns a fungibleTokenV2 object with token name, symbol, decimals, image URL, and a priceData block containing price, market cap, 24h volume, 5m/1h/24h price changes, and total liquidity figures. **Example:** `{"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": 8453, "currency": "USD"}` ---