NFT Holdings

Get NFT holdings for any wallet address and collection metadata across chains.

Try it Live

Open in Swagger UI → to test these endpoints interactively.

Endpoints

Endpoint	Description	Price
`GET /api/nfts/{address}`	Wallet NFT holdings	$0.02
`GET /api/nft/collection/{address}`	Collection metadata	$0.01

GET /api/nfts/{address}

Get all NFT holdings for a wallet address.

Request

curl "https://api.web3identity.com/api/nfts/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum"

Query Parameters

Parameter	Type	Default	Description
`chain`	string	`ethereum`	Chain: ethereum, polygon, arbitrum, optimism, base
`limit`	number	100	Max NFTs returned
`offset`	number	0	Pagination offset
`includeMetadata`	boolean	`true`	Include NFT metadata
`includeFloorPrice`	boolean	`false`	Include collection floor prices

Response

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "totalNFTs": 42,
  "totalCollections": 15,
  "nfts": [
    {
      "tokenId": "1234",
      "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
      "collection": {
        "name": "Bored Ape Yacht Club",
        "symbol": "BAYC",
        "verified": true,
        "floorPrice": 28.5,
        "floorPriceUSD": 65478.90
      },
      "metadata": {
        "name": "Bored Ape #1234",
        "description": "A bored ape from the yacht club",
        "image": "ipfs://QmYx...ABC/1234.png",
        "imageUrl": "https://ipfs.io/ipfs/QmYx...ABC/1234.png",
        "attributes": [
          {
            "trait_type": "Background",
            "value": "Blue"
          },
          {
            "trait_type": "Fur",
            "value": "Golden Brown"
          },
          {
            "trait_type": "Mouth",
            "value": "Bored"
          },
          {
            "trait_type": "Eyes",
            "value": "Sad"
          }
        ]
      },
      "lastSale": {
        "price": 32.5,
        "priceUSD": 74750.00,
        "date": "2025-12-15T10:30:00Z",
        "marketplace": "OpenSea"
      },
      "ownership": {
        "acquiredAt": "2024-06-10T15:20:00Z",
        "acquiredPrice": 45.2,
        "acquiredPriceUSD": 103960.00
      }
    },
    {
      "tokenId": "5678",
      "contractAddress": "0x49cF6f5d44E70224e2E23fDcdd2C053F30aDA28B",
      "collection": {
        "name": "CloneX",
        "symbol": "CLONEX",
        "verified": true,
        "floorPrice": 0.85,
        "floorPriceUSD": 1955.25
      },
      "metadata": {
        "name": "CloneX #5678",
        "description": "Clone by RTFKT",
        "image": "https://clonex-assets.rtfkt.com/images/5678.png",
        "imageUrl": "https://clonex-assets.rtfkt.com/images/5678.png",
        "attributes": [
          {
            "trait_type": "DNA",
            "value": "Human"
          },
          {
            "trait_type": "Eye Color",
            "value": "Blue"
          }
        ]
      }
    }
  ],
  "collections": [
    {
      "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
      "name": "Bored Ape Yacht Club",
      "symbol": "BAYC",
      "count": 3,
      "floorPrice": 28.5,
      "totalValue": 85.5,
      "totalValueUSD": 196436.70
    },
    {
      "contractAddress": "0x49cF6f5d44E70224e2E23fDcdd2C053F30aDA28B",
      "name": "CloneX",
      "symbol": "CLONEX",
      "count": 2,
      "floorPrice": 0.85,
      "totalValue": 1.7,
      "totalValueUSD": 3910.50
    }
  ],
  "totalValue": {
    "eth": 87.2,
    "usd": 200347.20
  }
}

GET /api/nft/collection/{address}

Get detailed metadata for an NFT collection.

Request

curl "https://api.web3identity.com/api/nft/collection/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D?chain=ethereum"

Query Parameters

Parameter	Type	Default	Description
`chain`	string	`ethereum`	Chain name

Response

{
  "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
  "chain": "ethereum",
  "name": "Bored Ape Yacht Club",
  "symbol": "BAYC",
  "description": "The Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs",
  "verified": true,
  "standard": "ERC721",
  "totalSupply": 10000,
  "holders": 5678,
  "holderPercentage": 56.78,
  "floorPrice": {
    "eth": 28.5,
    "usd": 65478.90,
    "change24h": -2.5,
    "change7d": 5.2
  },
  "volume": {
    "total": 1234567.89,
    "totalUSD": 2837906209.47,
    "24h": 456.78,
    "24hUSD": 1049959.02,
    "7d": 2345.67,
    "7dUSD": 5390012.31
  },
  "sales": {
    "total": 98765,
    "24h": 23,
    "7d": 167
  },
  "marketCap": {
    "eth": 285000,
    "usd": 654789000
  },
  "royalty": {
    "percentage": 2.5,
    "recipient": "0x..."
  },
  "links": {
    "website": "https://boredapeyachtclub.com",
    "twitter": "https://twitter.com/BoredApeYC",
    "discord": "https://discord.gg/bayc",
    "opensea": "https://opensea.io/collection/boredapeyachtclub"
  },
  "creator": {
    "address": "0xABa931f8EAeaf4b0d22AfDB5Ec97747BE935e76B",
    "name": "Yuga Labs"
  },
  "deployedAt": {
    "block": 12287507,
    "timestamp": "2021-04-22T22:40:39Z"
  }
}

NFT Standards

Standard	Description	Chains
ERC-721	Single NFT per token ID	All EVM chains
ERC-1155	Multi-token standard	All EVM chains
SPL	Solana NFT standard	Solana
Metaplex	Solana NFT metadata	Solana

SDK Examples

JavaScript

import { Web3IdentityClient } from '@web3identity/sdk';

const client = new Web3IdentityClient();

// Get wallet NFTs
const nfts = await client.getWalletNFTs(
  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  { chain: 'ethereum', includeFloorPrice: true }
);

console.log(`Total NFTs: ${nfts.totalNFTs}`);
console.log(`Collections: ${nfts.totalCollections}`);
console.log(`Portfolio Value: $${nfts.totalValue.usd.toLocaleString()}`);

// Group by collection
console.log('\nCollections:');
nfts.collections.forEach(collection => {
  console.log(`  ${collection.name}: ${collection.count} NFTs`);
  console.log(`    Floor: ${collection.floorPrice} ETH`);
  console.log(`    Value: $${collection.totalValueUSD.toLocaleString()}`);
});

// Find rare NFTs
const rareNFTs = nfts.nfts.filter(nft => {
  const rarityTraits = nft.metadata.attributes.filter(
    attr => attr.value.includes('Rare') || attr.value.includes('Legendary')
  );
  return rarityTraits.length > 0;
});

console.log(`\nRare NFTs found: ${rareNFTs.length}`);

// Get collection details
const bayc = await client.getNFTCollection(
  '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
  { chain: 'ethereum' }
);

console.log(`\n${bayc.name}:`);
console.log(`  Floor: ${bayc.floorPrice.eth} ETH ($${bayc.floorPrice.usd.toLocaleString()})`);
console.log(`  24h Volume: ${bayc.volume['24h']} ETH`);
console.log(`  Holders: ${bayc.holders} (${bayc.holderPercentage}%)`);

Python

from web3identity import Client

client = Client()

# Get wallet NFTs
nfts = client.get_wallet_nfts(
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    chain='ethereum',
    include_floor_price=True
)

print(f"Total NFTs: {nfts['totalNFTs']}")
print(f"Portfolio Value: ${nfts['totalValue']['usd']:,.2f}")

# Analyze collections
print("\n📊 Collection Breakdown:")
for collection in nfts['collections']:
    value_pct = (collection['totalValueUSD'] / nfts['totalValue']['usd']) * 100
    print(f"  {collection['name']}: {collection['count']} NFTs ({value_pct:.1f}% of portfolio)")

# Find NFTs below floor
below_floor = []
for nft in nfts['nfts']:
    if nft.get('lastSale'):
        collection = next(c for c in nfts['collections'] 
                         if c['contractAddress'] == nft['contractAddress'])
        if nft['lastSale']['price'] < collection['floorPrice']:
            below_floor.append(nft)

print(f"\n💎 NFTs bought below current floor: {len(below_floor)}")

# Get collection stats
def analyze_collection(address, chain='ethereum'):
    collection = client.get_nft_collection(address, chain=chain)
    
    return {
        'name': collection['name'],
        'floor': collection['floorPrice']['eth'],
        'volume_24h': collection['volume']['24h'],
        'holders': collection['holders'],
        'sales_24h': collection['sales']['24h'],
        'avg_sale_24h': collection['volume']['24h'] / collection['sales']['24h'] if collection['sales']['24h'] > 0 else 0
    }

bayc_stats = analyze_collection('0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D')
print(f"\nBAYC Stats:")
print(f"  Floor: {bayc_stats['floor']} ETH")
print(f"  Avg sale (24h): {bayc_stats['avg_sale_24h']:.2f} ETH")

cURL Examples

# Get wallet NFTs on Ethereum
curl "https://api.web3identity.com/api/nfts/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum"

# Include floor prices
curl "https://api.web3identity.com/api/nfts/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum&includeFloorPrice=true"

# Get NFTs on Polygon
curl "https://api.web3identity.com/api/nfts/0xYourAddress?chain=polygon"

# Pagination
curl "https://api.web3identity.com/api/nfts/0xYourAddress?chain=ethereum&limit=50&offset=50"

# Get BAYC collection info
curl "https://api.web3identity.com/api/nft/collection/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D?chain=ethereum"

# Get CloneX collection info
curl "https://api.web3identity.com/api/nft/collection/0x49cF6f5d44E70224e2E23fDcdd2C053F30aDA28B?chain=ethereum"

Rate Limits

Tier	Rate Limit	Notes
Free	100 requests/day	No payment required
Paid	Unlimited	$0.01-$0.02 per call via x402

Common Use Cases

NFT Portfolio Tracker

// Build NFT portfolio dashboard
async function trackNFTPortfolio(address, chains = ['ethereum', 'polygon']) {
  const portfolios = await Promise.all(
    chains.map(chain =>
      client.getWalletNFTs(address, { chain, includeFloorPrice: true })
    )
  );
  
  const combined = {
    totalNFTs: portfolios.reduce((sum, p) => sum + p.totalNFTs, 0),
    totalCollections: portfolios.reduce((sum, p) => sum + p.totalCollections, 0),
    totalValueUSD: portfolios.reduce((sum, p) => sum + p.totalValue.usd, 0),
    byChain: portfolios.map((p, i) => ({
      chain: chains[i],
      nfts: p.totalNFTs,
      value: p.totalValue.usd
    })),
    topCollections: portfolios
      .flatMap(p => p.collections)
      .sort((a, b) => b.totalValueUSD - a.totalValueUSD)
      .slice(0, 10)
  };
  
  return combined;
}

const portfolio = await trackNFTPortfolio('0xYourAddress');
console.log(`Total NFT Value: $${portfolio.totalValueUSD.toLocaleString()}`);

Floor Price Alerts

// Monitor collection floor prices
async function monitorFloorPrices(collections, thresholds) {
  const alerts = [];
  
  for (const [address, targetPrice] of Object.entries(thresholds)) {
    const collection = await client.getNFTCollection(address);
    
    if (collection.floorPrice.eth <= targetPrice) {
      alerts.push({
        collection: collection.name,
        floor: collection.floorPrice.eth,
        target: targetPrice,
        message: `${collection.name} floor hit ${collection.floorPrice.eth} ETH (target: ${targetPrice})`
      });
    }
  }
  
  return alerts;
}

const alerts = await monitorFloorPrices({
  '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D': 25.0,  // BAYC
  '0x49cF6f5d44E70224e2E23fDcdd2C053F30aDA28B': 0.8    // CloneX
});

if (alerts.length > 0) {
  console.log('🔔 Floor price alerts:', alerts);
}

NFT Rarity Checker

// Check NFT rarity based on traits
async function checkRarity(contractAddress, tokenId, chain = 'ethereum') {
  const collection = await client.getNFTCollection(contractAddress, { chain });
  const nfts = await client.getWalletNFTs('0xYourAddress', { chain }); // Or use specific endpoint
  
  const nft = nfts.nfts.find(n =>
    n.contractAddress === contractAddress && n.tokenId === tokenId
  );
  
  if (!nft) return null;
  
  // Calculate trait rarity (simplified)
  const traitScores = nft.metadata.attributes.map(attr => {
    // In reality, you'd query trait distribution from collection data
    return {
      trait: attr.trait_type,
      value: attr.value,
      rarity: 'TBD' // Would calculate from collection trait distribution
    };
  });
  
  return {
    tokenId: nft.tokenId,
    name: nft.metadata.name,
    collection: collection.name,
    traits: traitScores
  };
}

Wallet Balances — Token balances
Transaction History — Wallet activity
Token Approvals — NFT approvals
Token Prices — ETH/token prices

Endpoints​

GET /api/nfts/{address}​

Request​

Query Parameters​

Response​

GET /api/nft/collection/{address}​

Request​

Query Parameters​

Response​

NFT Standards​

SDK Examples​

JavaScript​

Python​

cURL Examples​

Rate Limits​

Common Use Cases​

NFT Portfolio Tracker​

Floor Price Alerts​

NFT Rarity Checker​

Related Endpoints​

Endpoints

GET /api/nfts/{address}

Request

Query Parameters

Response

GET /api/nft/collection/{address}

Request

Query Parameters

Response

NFT Standards

SDK Examples

JavaScript

Python

cURL Examples

Rate Limits

Common Use Cases

NFT Portfolio Tracker

Floor Price Alerts

NFT Rarity Checker

Related Endpoints