home / skills / openclaw / skills / openclaw-zapper-api

openclaw-zapper-api skill

safe

This skill queries DeFi portfolios, tokens, NFTs, and prices via Zapper to answer wallet balances, positions, and transaction histories across 50+ chains.

npx playbooks add skill openclaw/skills --skill openclaw-zapper-api

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

3.4 KB

---
name: zapper-api
description: Query DeFi portfolios, token holdings, NFTs, transactions, and prices via Zapper API. Supports 50+ chains. Use when user asks about wallet balances, DeFi positions, NFT collections, token prices, or transaction history.
homepage: https://zapper.xyz
metadata: {"openclaw":{"emoji":"🟪","requires":{"bins":["python3"]},"primaryEnv":"ZAPPER_API_KEY"}}
---

# Zapper API

Query DeFi portfolios, NFTs, and transactions across 50+ chains using Zapper's GraphQL API.

## Setup

1. Get API key from [Zapper Dashboard](https://zapper.xyz/developers) (free tier available)
2. Configure in `~/.config/zapper/addresses.json`:
   ```json
   {
     "apiKey": "your-api-key",
     "wallets": [
       {"label": "Main", "address": "0x..."},
       {"label": "DeFi", "address": "0x..."}
     ]
   }
   ```

Or set environment variable: `export ZAPPER_API_KEY="your-api-key"`

## Commands

| Command | Description | Example |
|---------|-------------|---------|
| `portfolio <address>` | Token + DeFi totals | `zapper.py portfolio 0x123...` |
| `tokens <address>` | Detailed token holdings | `zapper.py tokens 0x123...` |
| `apps <address>` | DeFi positions (LPs, lending, staking) | `zapper.py apps 0x123...` |
| `nfts <address>` | NFT holdings by value | `zapper.py nfts 0x123...` |
| `tx <address>` | Recent transactions (30 days) | `zapper.py tx 0x123...` |
| `price <symbol>` | Token price lookup | `zapper.py price ETH` |
| `claimables <address>` | Unclaimed rewards | `zapper.py claimables 0x123...` |
| `config` | Show configuration | `zapper.py config` |

## Options

| Flag | Commands | Description |
|------|----------|-------------|
| `--24h` | portfolio, tokens | Show 24h price changes |
| `--short` | portfolio | Output only total value |
| `--per-wallet` | portfolio | Show each configured wallet separately |
| `--json` | all | Output raw JSON |
| `--limit N` | most | Max items to display |

## Usage

```bash
# Portfolio summary
python3 scripts/zapper.py portfolio 0xADDRESS

# With 24h price changes
python3 scripts/zapper.py portfolio 0xADDRESS --24h

# Just total value
python3 scripts/zapper.py portfolio 0xADDRESS --short

# Per-wallet breakdown
python3 scripts/zapper.py portfolio --per-wallet

# Token holdings with prices
python3 scripts/zapper.py tokens 0xADDRESS --24h

# DeFi positions
python3 scripts/zapper.py apps 0xADDRESS

# NFT holdings
python3 scripts/zapper.py nfts 0xADDRESS

# Recent transactions
python3 scripts/zapper.py tx 0xADDRESS

# Token price
python3 scripts/zapper.py price ETH

# Unclaimed rewards
python3 scripts/zapper.py claimables 0xADDRESS

# JSON output
python3 scripts/zapper.py portfolio 0xADDRESS --json
```

## Wallet Labels

Use configured wallet labels instead of addresses:

```bash
python3 scripts/zapper.py portfolio "Main"
python3 scripts/zapper.py tokens "DeFi"
```

## Supported Tokens (price command)

ETH, WETH, USDC, USDT, DAI, WBTC, LINK, UNI, AAVE, MKR

## Supported Chains

Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, BNB Chain, Avalanche, zkSync, Linea, Scroll, Blast, and 40+ more.

## Notes

- Free tier API key available at [zapper.xyz/developers](https://zapper.xyz/developers)
- Rate limits apply - avoid rapid repeated requests
- NFT valuations based on floor prices
- Transaction history limited to 30 days

## References

- [API.md](references/API.md) - GraphQL query examples
- [Zapper Docs](https://build.zapper.xyz/docs/api/) - Official API documentation

Overview

This skill queries DeFi portfolios, token holdings, NFTs, transactions, and token prices using the Zapper GraphQL API across 50+ chains. It provides quick portfolio summaries, per-wallet breakdowns, DeFi positions, NFT valuations, recent transactions, and unclaimed reward data. Use an API key (free tier available) or set an environment variable to authenticate.

How this skill works

The skill sends GraphQL queries to Zapper's API to fetch consolidated wallet data: aggregated token balances, DeFi app positions (LPs, lending, staking), NFT holdings with floor valuations, and recent transactions (30-day window). Commands support filters and output formats (short, per-wallet, JSON) and can include 24h price changes, limits, and chain coverage. Rate limits apply, so requests are batched or throttled when possible.

When to use it

Get a quick total value of a wallet across chains or per configured wallet label.
Inspect detailed token balances and price changes over 24 hours.
Review DeFi positions like liquidity pools, lending, and staking in one view.
Check NFT holdings by estimated floor value and overall NFT exposure.
Fetch recent transactions for on-chain activity and troubleshooting.
Look up current token prices for common assets (ETH, USDC, WBTC, etc.).

Best practices

Provide a configured wallet label or a full address; labels make repeated queries easier.
Use the --json flag for downstream processing or automated scripts.
Avoid rapid repeated queries to respect API rate limits; add delays or use caching.
Use --limit to restrict large responses and --24h only when you need price-change context.
Store your API key in ~/.config/zapper/addresses.json or ZAPPER_API_KEY environment variable.

Example use cases

Generate a daily portfolio summary for a multisig by running portfolio with --per-wallet.
Audit a DeFi position before withdrawing liquidity by inspecting apps for LP and staking details.
Estimate NFT collection exposure by running nfts to get floor-based valuations.
Investigate recent outgoing transactions from an address using tx for a 30-day activity log.
Fetch a quick token price for trading decisions using the price command.

FAQ

Do I need an API key to use the skill?

Yes. You can get a free tier key from Zapper's developer dashboard and set it in the config file or ZAPPER_API_KEY.

Which chains and tokens are supported?

The skill supports 50+ chains including Ethereum, Polygon, Arbitrum, Optimism, Solana, BNB Chain, Avalanche, zkSync, and more; price lookups cover common tokens like ETH, WBTC, USDC, USDT, DAI, LINK, UNI, AAVE, and MKR.