Skip to main content

@elizaos/plugin-zapper

A plugin for Eliza that allows users to fetch portfolio data using the Zapper API.

Features​

Installation​

npm install @elizaos/plugin-zapper

Configuration​

  1. Get your API key from Zapper

  2. Set up your environment variables:

ZAPPER_API_KEY=your_api_key
  1. Register the plugin in your Eliza configuration:
import { zapperPlugin } from '@elizaos/plugin-zapper';

// In your Eliza configuration
plugins: [
  zapperPlugin,
  // ... other plugins
];

Usage​

The plugin responds to natural language queries about wallet data. Here are some examples:

"Show me the holdings of @vitalik.eth"
"Show me the portfolio of these wallets 0xd8d...045, 0xadd...077"
"Get wallet holdings for HN7cA...WrH"

Available Actions​

portfolio​

Fetch the current portfolio of provided addresses.

// Example response format
portfolio: {
  tokenBalances: Array<{
    address: string;
    network: string;
    token: {
      balance: number;
      balanceUSD: number;
      baseToken: {
        name: string;
        symbol: string;
      };
    };
  }>;
  nftBalances: Array<{
    network: string;
    balanceUSD: number;
  }>;
  totals: {
    total: number;
    totalWithNFT: number;
    totalByNetwork: Array<{
      network: string;
      total: number;
    }>;
    holdings: Array<{
      label: string;
      balanceUSD: number;
      pct: number;
    }>;
  }
}

farcasterPortfoio​

Fetch the portfolio of addresses attached to Farcaster profiles.

// Example response format
farcasterProfile: {
username: string;
fid: number;
metadata: {
  displayName: string;
  description: string;
  imageUrl: string;
  warpcast: string;
};
connectedAddresses: string[];
custodyAddress: string;
};

Development Guide​

Setting up the development environment​

  1. Clone the repository.
  2. Install dependencies:
bun install
  1. Build the plugin:
bun build

API Reference​

Environment Variables​

VariableDescriptionRequired
ZAPPER_API_KEYYour Zapper API keyYes

Types​

export type ZapperPortfolioResponse = {
  data: {
    portfolio: {
      tokenBalances: Array<{
        address: string;
        network: string;
        token: {
          balance: number;
          balanceUSD: number;
          baseToken: {
            name: string;
            symbol: string;
          };
        };
      }>;
      nftBalances: Array<{
        network: string;
        balanceUSD: number;
      }>;
      totals: {
        total: number;
        totalWithNFT: number;
        totalByNetwork: Array<{
          network: string;
          total: number;
        }>;
        holdings: Array<{
          label: string;
          balanceUSD: number;
          pct: number;
        }>;
      };
    };
  };
};

export type ZapperFarcasterResponse = {
  data: {
    accounts: Array<{
      farcasterProfile: {
        username: string;
        fid: number;
        metadata: {
          displayName: string;
          description: string;
          imageUrl: string;
          warpcast: string;
        };
        connectedAddresses: string[];
        custodyAddress: string;
      };
    }>;
  };
};