Querying Multiple Wallets

Why Batch Queries?

Many applications need to track multiple wallets together:

DAOs have multiple treasury wallets
Funds manage assets across several addresses
Users may have multiple personal wallets
Teams need consolidated views of shared wallets

Without batch queries, you'd make 10 separate API calls. Batch endpoints give you the same data in one request—faster, cheaper, and with built-in aggregation.

Available Batch Endpoints

Endpoint	Description
`POST /wallets/batch/token-balance`	Token balances for multiple wallets
`POST /wallets/batch/token-balance-ts`	Balance history for multiple wallets
`POST /wallets/batch/nft-balance`	NFT holdings for multiple wallets

All batch endpoints accept up to 10 wallets per request.

Token Balances (Multiple Wallets)

Get current token holdings across multiple wallets with aggregated totals.

Request

curl -X POST "https://api.vybenetwork.com/wallets/batch/token-balance" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      "Wallet1PublicKey...",
      "Wallet2PublicKey...",
      "Wallet3PublicKey..."
    ],
    "onlyVerified": true,
    "minAssetValue": "1"
  }'

Parameters

Parameter	Type	Description
`wallets`	array	Up to 10 wallet addresses (required)
`onlyVerified`	boolean	Only verified tokens
`minAssetValue`	string	Minimum USD value filter

Response

{
  "totalValueUsd": "45678.90",
  "wallets": [
    {
      "ownerAddress": "Wallet1PublicKey...",
      "totalTokenValueUsd": "15234.56",
      "data": [
        {
          "mintAddress": "So11...",
          "symbol": "SOL",
          "amount": "50.5",
          "valueUsd": "9363.71"
        }
      ]
    },
    {
      "ownerAddress": "Wallet2PublicKey...",
      "totalTokenValueUsd": "20444.34",
      "data": [...]
    }
  ],
  "aggregated": {
    "tokens": [
      {
        "mintAddress": "So11...",
        "symbol": "SOL",
        "totalAmount": "150.5",
        "totalValueUsd": "27892.65"
      }
    ]
  }
}

Response Fields

Field	Description
`totalValueUsd`	Combined value across all wallets
`wallets`	Individual wallet breakdowns
`aggregated.tokens`	Tokens summed across all wallets

Balance History (Multiple Wallets)

Track combined portfolio value over time for multiple wallets.

Request

curl -X POST "https://api.vybenetwork.com/wallets/batch/token-balance-ts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      "Wallet1PublicKey...",
      "Wallet2PublicKey..."
    ],
    "days": 14
  }'

Parameters

Parameter	Type	Description
`wallets`	array	Up to 10 wallet addresses
`days`	number	Days of history (1-30)

NFT Balances (Multiple Wallets)

Get NFT holdings across multiple wallets.

Request

curl -X POST "https://api.vybenetwork.com/wallets/batch/nft-balance" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      "Wallet1PublicKey...",
      "Wallet2PublicKey..."
    ],
    "includeNoPriceBalance": false
  }'

Common Use Cases

Use Case	Implementation
DAO Treasury	Aggregate all treasury wallets
Multi-Sig Dashboard	Monitor assets across signers
Fund Tracking	Track fund AUM across wallets
Personal Portfolio	Combine hot + cold wallets
Whale Groups	Monitor related wallet clusters

DAO Treasury Dashboard

Build a complete treasury view:

async function getDAOTreasury(treasuryWallets) {
  const response = await fetch(
    "https://api.vybenetwork.com/wallets/batch/token-balance",
    {
      method: "POST",
      headers: {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        wallets: treasuryWallets,
        onlyVerified: true,
        minAssetValue: "10" // Filter dust
      })
    }
  );
  const data = await response.json();
  
  return {
    totalTreasury: `$${parseFloat(data.totalValueUsd).toLocaleString()}`,
    walletBreakdown: data.wallets.map(w => ({
      wallet: `${w.ownerAddress.slice(0, 4)}...${w.ownerAddress.slice(-4)}`,
      value: `$${parseFloat(w.totalTokenValueUsd).toLocaleString()}`,
      percent: `${(parseFloat(w.totalTokenValueUsd) / parseFloat(data.totalValueUsd) * 100).toFixed(1)}%`
    })),
    topHoldings: data.aggregated.tokens
      .sort((a, b) => parseFloat(b.totalValueUsd) - parseFloat(a.totalValueUsd))
      .slice(0, 10)
      .map(t => ({
        symbol: t.symbol,
        amount: parseFloat(t.totalAmount).toLocaleString(),
        value: `$${parseFloat(t.totalValueUsd).toLocaleString()}`
      }))
  };
}

Fund Performance Tracker

Track fund AUM and performance over time:

async function trackFundPerformance(fundWallets) {
  // Get current balances and history in parallel
  const [current, history] = await Promise.all([
    fetch("https://api.vybenetwork.com/wallets/batch/token-balance", {
      method: "POST",
      headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ wallets: fundWallets, onlyVerified: true })
    }),
    fetch("https://api.vybenetwork.com/wallets/batch/token-balance-ts", {
      method: "POST",
      headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ wallets: fundWallets, days: 30 })
    })
  ].map(p => p.then(r => r.json())));
  
  // Calculate performance metrics
  const historyData = history.data.reverse(); // Chronological order
  const startValue = parseFloat(historyData[0].totalValueUsd);
  const endValue = parseFloat(current.totalValueUsd);
  const returnPercent = ((endValue - startValue) / startValue * 100);
  
  // Chart data
  const chartData = historyData.map(day => ({
    date: day.date,
    aum: parseFloat(day.totalValueUsd)
  }));
  
  return {
    currentAUM: `$${endValue.toLocaleString()}`,
    thirtyDayReturn: `${returnPercent >= 0 ? '+' : ''}${returnPercent.toFixed(2)}%`,
    walletCount: fundWallets.length,
    chartData,
    allocation: current.aggregated.tokens
      .map(t => ({
        symbol: t.symbol,
        value: parseFloat(t.totalValueUsd),
        percent: (parseFloat(t.totalValueUsd) / endValue * 100).toFixed(1)
      }))
      .sort((a, b) => b.value - a.value)
  };
}

Multi-Wallet Portfolio View

Combine personal wallets (hot wallet, cold storage, etc.):

async function getUnifiedPortfolio(userWallets) {
  // Get tokens, NFTs, and DeFi for all wallets
  const [tokens, nfts] = await Promise.all([
    fetch("https://api.vybenetwork.com/wallets/batch/token-balance", {
      method: "POST",
      headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ wallets: userWallets, onlyVerified: true })
    }),
    fetch("https://api.vybenetwork.com/wallets/batch/nft-balance", {
      method: "POST",
      headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ wallets: userWallets })
    })
  ].map(p => p.then(r => r.json())));
  
  // Note: DeFi positions need to be fetched individually
  // (no batch endpoint for DeFi yet)
  
  const tokensUsd = parseFloat(tokens.totalValueUsd || 0);
  const nftsUsd = parseFloat(nfts.totalNftValueUsd || 0);
  const totalUsd = tokensUsd + nftsUsd;
  
  return {
    totalNetWorth: `$${totalUsd.toLocaleString()}`,
    breakdown: {
      tokens: `$${tokensUsd.toLocaleString()}`,
      nfts: `$${nftsUsd.toLocaleString()}`
    },
    byWallet: userWallets.map((addr, i) => ({
      label: `Wallet ${i + 1}`,
      address: addr,
      tokens: tokens.wallets[i]?.totalTokenValueUsd || "0",
      nfts: nfts.wallets?.[i]?.totalNftValueUsd || "0"
    })),
    topHoldings: tokens.aggregated.tokens.slice(0, 10)
  };
}

Limits & Best Practices

Limit	Value
Max wallets per request	10
Rate limits	Same as single-wallet endpoints

Tips

Use onlyVerified: true to filter scam tokens
Use minAssetValue: "1" to filter dust
Batch requests count as 1 API call (not 10)
Results include both individual and aggregated data

Related Endpoints

Token Balances - Single wallet queries
Balance History - Single wallet history
NFT Balances - Single wallet NFTs