NFT Holdings & Balances

Why NFT Balance Data Matters

NFTs are a significant part of many Solana portfolios. Without NFT data, portfolio trackers show incomplete net worth. The NFT balance endpoint provides:

Complete holdings: Every NFT in a wallet with metadata
Floor price valuations: Automatic pricing based on collection floors
Collection grouping: See NFTs organized by collection
Attribute data: Trait information for rarity analysis
Portfolio totals: Aggregate NFT value in USD and SOL

Whether you're building a portfolio tracker, verifying NFT ownership for access control, or monitoring whale NFT activity, this endpoint gives you everything you need.

Endpoint

GET /wallets/{ownerAddress}/nft-balance

Parameters

Parameter	Type	Description
`ownerAddress`	string	Wallet public key (required)
`sortByAsc`	string	Sort ascending: `amount`, `value`
`sortByDesc`	string	Sort descending: `amount`, `value`
`limit`	number	Results per page (max 1000)
`page`	number	Page number (0-indexed)
`includeNoPriceBalance`	boolean	Include NFTs without floor prices

Example Request

curl "https://api.vybenetwork.com/wallets/7Tar8QZTrRPwoGY5Ke9Vfwf6CmpBfekrNofERxgReza/nft-balance?sortByDesc=value" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "ownerAddress": "7Tar8QZTrRPwoGY5Ke9Vfwf6CmpBfekrNofERxgReza",
  "totalNftValueUsd": "4521.30",
  "totalNftValueSol": "24.42",
  "data": [
    {
      "mintAddress": "NFTMint123abc...",
      "name": "Mad Lad #1234",
      "collectionAddress": "J1S9H3QjnRtBbbuD4HjPV6RpRhwuk4zKbxsnCHuTgh9w",
      "collectionName": "Mad Lads",
      "imageUrl": "https://arweave.net/...",
      "floorPriceUsd": "1250.00",
      "floorPriceSol": "6.75",
      "attributes": [
        { "trait_type": "Background", "value": "Blue" },
        { "trait_type": "Eyes", "value": "Laser" },
        { "trait_type": "Headwear", "value": "Crown" }
      ]
    },
    {
      "mintAddress": "NFTMint456def...",
      "name": "Okay Bear #5678",
      "collectionAddress": "3saAedkM9o5g1u5DCqsuMZuC4GRqPB4TuMkvSsSVvGQ3",
      "collectionName": "Okay Bears",
      "imageUrl": "https://arweave.net/...",
      "floorPriceUsd": "890.50",
      "floorPriceSol": "4.81",
      "attributes": [...]
    }
  ]
}

Response Fields

Field	Description
`totalNftValueUsd`	Sum of all NFT floor prices in USD
`totalNftValueSol`	Sum of all NFT floor prices in SOL
`mintAddress`	Unique NFT mint address
`name`	NFT name
`collectionAddress`	Collection identifier
`collectionName`	Human-readable collection name
`imageUrl`	NFT image URL
`floorPriceUsd`	Collection floor price in USD
`floorPriceSol`	Collection floor price in SOL
`attributes`	NFT traits/attributes

Common Use Cases

Use Case	Implementation
NFT Portfolio	Display holdings with floor valuations
Token Gating	Verify collection ownership for access
Gallery App	Show user's NFT collection
Whale Tracking	Monitor high-value NFT holders
Complete Portfolio	Add NFTs to token balance for full net worth

Token Gating Example

Verify a user owns an NFT from a specific collection:

async function verifyNFTAccess(wallet, requiredCollection) {
  const response = await fetch(
    `https://api.vybenetwork.com/wallets/${wallet}/nft-balance`,
    { headers: { "X-API-Key": API_KEY } }
  );
  const { data } = await response.json();
  
  // Check if any NFT matches the required collection
  const hasAccess = data.some(nft => 
    nft.collectionAddress === requiredCollection
  );
  
  // Get the specific NFTs they hold from this collection
  const ownedFromCollection = data.filter(nft => 
    nft.collectionAddress === requiredCollection
  );
  
  return {
    hasAccess,
    ownedCount: ownedFromCollection.length,
    ownedNfts: ownedFromCollection.map(nft => ({
      name: nft.name,
      image: nft.imageUrl
    }))
  };
}

// Usage
const access = await verifyNFTAccess(userWallet, "J1S9H3QjnRtBbbuD4HjPV6RpRhwuk4zKbxsnCHuTgh9w");
if (access.hasAccess) {
  // Grant access to gated content
}

NFT Portfolio Dashboard

Build a complete NFT portfolio view:

async function getNFTPortfolio(wallet) {
  const response = await fetch(
    `https://api.vybenetwork.com/wallets/${wallet}/nft-balance?sortByDesc=value`,
    { headers: { "X-API-Key": API_KEY } }
  );
  const portfolio = await response.json();
  
  // Group by collection
  const byCollection = portfolio.data.reduce((acc, nft) => {
    const key = nft.collectionName || 'Unknown Collection';
    if (!acc[key]) {
      acc[key] = {
        collectionAddress: nft.collectionAddress,
        floorPrice: parseFloat(nft.floorPriceSol),
        nfts: []
      };
    }
    acc[key].nfts.push(nft);
    return acc;
  }, {});
  
  // Calculate collection totals
  const collections = Object.entries(byCollection).map(([name, data]) => ({
    name,
    collectionAddress: data.collectionAddress,
    count: data.nfts.length,
    floorPrice: `${data.floorPrice} SOL`,
    totalValue: `${(data.floorPrice * data.nfts.length).toFixed(2)} SOL`,
    nfts: data.nfts
  })).sort((a, b) => b.count - a.count);
  
  return {
    totalValueUsd: `$${parseFloat(portfolio.totalNftValueUsd).toLocaleString()}`,
    totalValueSol: `${parseFloat(portfolio.totalNftValueSol).toFixed(2)} SOL`,
    totalNfts: portfolio.data.length,
    collections
  };
}

Collection Holders

Find all wallets holding NFTs from a specific collection:

GET /collections/{collectionAddress}/owners

curl "https://api.vybenetwork.com/collections/J1S9H3QjnRtBbbuD4HjPV6RpRhwuk4zKbxsnCHuTgh9w/owners?limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

Use Cases for Collection Holders

Airdrop targeting: Find holders of a collection for rewards
Community analysis: See holder distribution
Whale identification: Find the biggest collectors
Cross-collection analysis: Find wallets holding multiple collections

Multi-Wallet NFT Query

Query NFTs across multiple wallets at once:

POST /wallets/batch/nft-balance

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
  }'

Complete Portfolio Example

Combine tokens, NFTs, and DeFi for total net worth:

async function getCompletePortfolio(wallet) {
  const headers = { "X-API-Key": API_KEY };
  
  const [tokens, nfts, defi] = await Promise.all([
    fetch(`https://api.vybenetwork.com/wallets/${wallet}/token-balance`, { headers }),
    fetch(`https://api.vybenetwork.com/wallets/${wallet}/nft-balance`, { headers }),
    fetch(`https://api.vybenetwork.com/wallets/${wallet}/defi-positions`, { headers })
  ].map(p => p.then(r => r.json())));
  
  const tokensUsd = parseFloat(tokens.totalTokenValueUsd || 0);
  const nftsUsd = parseFloat(nfts.totalNftValueUsd || 0);
  const defiUsd = parseFloat(defi.totalDefiValueUsd || 0);
  const totalUsd = tokensUsd + nftsUsd + defiUsd;
  
  return {
    wallet,
    breakdown: {
      tokens: { value: `$${tokensUsd.toLocaleString()}`, percent: `${(tokensUsd/totalUsd*100).toFixed(1)}%` },
      nfts: { value: `$${nftsUsd.toLocaleString()}`, percent: `${(nftsUsd/totalUsd*100).toFixed(1)}%` },
      defi: { value: `$${defiUsd.toLocaleString()}`, percent: `${(defiUsd/totalUsd*100).toFixed(1)}%` }
    },
    totalNetWorth: `$${totalUsd.toLocaleString()}`
  };
}

Related Endpoints

Token Balances - SPL token holdings
DeFi Positions - LP and staking positions
Batch Queries - Multi-wallet queries