DeFi portfolio app and Zapper Protocol — a single GraphQL API for token balances, NFT positions, DeFi positions, prices, and human-readable transaction history across 60+ chains. Powers portfolio dashboards in CoinGecko, Rainbow, Uniswap, and many more.
- 01wallet portfolio dashboards
- 02DeFi position decoding (LP, lending, staking, vesting)
- 03NFT portfolio with valuations
- 04human-readable transaction feeds
- 05cross-chain net worth aggregation
- pnpm add graphql graphql-request
| Variable | Scope | Description |
|---|---|---|
| ZAPPER_API_KEY | Server | Zapper Protocol API key from https://protocol.zapper.xyz/dashboard. Sent as the `x-zapper-api-key` header. Server-side only — exposing it lets anyone burn your credit balance. |
Use Zapper Protocol's GraphQL API from a server route. Endpoint: `https://public.zapper.xyz/graphql` with header `x-zapper-api-key: ${ZAPPER_API_KEY}`. Core query is `portfolioV2(addresses: [Address!]!, networks: [Network!]) { tokenBalances { byToken { edges { node { name symbol balance balanceUSD imgUrlV2 } } } } appBalances { ... } nftBalances { ... } }` — one call returns tokens, DeFi positions, and NFTs across all selected chains. Other useful queries: `fungibleToken(address, network)` for live prices, `transactionHistoryV2(addresses, networks)` for human-readable tx feed, `nftToken` for NFT metadata + floor price. Each query consumes credits proportional to the work — measure cost on the dashboard before fanning out and cache per-address responses (30–60s TTL) since portfolio data only refreshes a few times per minute upstream.
- ⚑Auth header is the custom `x-zapper-api-key` (not `Authorization: Bearer`) — many AI-generated snippets get this wrong and silently 401.
- ⚑Legacy REST API at api.zapper.fi was deprecated in favor of the GraphQL endpoint at public.zapper.xyz/graphql — ignore older blog posts and SDK examples that still reference REST `/v2/balances/apps`.
- ⚑Each query costs credits, with deeply nested portfolioV2 fans out cost-multiplying — request only the subfields you actually render and avoid `nftBalances` unless the UI shows NFTs.
- ⚑DeFi position decoding can lag 10–60s after on-chain events; never present Zapper balances as 'live' for trading or transaction confirmations — pair with a wallet RPC for hot reads.
- ⚑Network enum values are Zapper-specific (e.g. `ETHEREUM_MAINNET`, `BASE_MAINNET`) — fetch the supported list from `network` introspection and don't hardcode chain IDs.
- ⚑PII/privacy: portfolio responses include token+NFT contents which can deanonymize a user — never log the raw response server-side without redaction, and never expose another user's portfolio without their explicit consent.