[P1] Build NFT API Suite (Metadata, Ownership, Transfers, Collections)

[BlocksScanIO]

Feature Request: NFT API Suite

Background

Competitor Analysis Reference: Alchemy NFT API, QuickNode NFT API

Alchemy's NFT API is the industry standard for NFT data access. XDC Gateway needs comprehensive NFT endpoints to support marketplaces, wallets, and NFT analytics platforms.

Requirements

Core API Endpoints

1. NFT Metadata

GET /api/v1/nft/:contractAddress/:tokenId/metadata

{
  "contract": {
    "address": "0x...",
    "name": "XDC Punks",
    "symbol": "XDCNFT",
    "type": "XRC721",
    "totalSupply": "10000"
  },
  "tokenId": "1234",
  "tokenType": "XRC721",
  "name": "XDC Punk #1234",
  "description": "A unique XDC punk",
  "image": "https://...",
  "externalUrl": "https://...",
  "attributes": [
    {"trait_type": "Background", "value": "Blue"},
    {"trait_type": "Eyes", "value": "Laser"}
  ],
  "metadata": {
    "raw": "{...}",
    "normalized": {...}
  },
  "updatedAt": "2026-02-26T20:33:00Z"
}

2. NFT Ownership

GET /api/v1/nft/:contractAddress/:tokenId/owners
GET /api/v1/accounts/:address/nfts

{
  "owner": "0x...",
  "balance": "1",
  "acquiredAt": "2026-01-15T10:30:00Z",
  "transactionHash": "0x..."
}

3. NFT Transfers

GET /api/v1/nft/:contractAddress/:tokenId/transfers
GET /api/v1/nft/transfers?fromBlock=1000000&toBlock=latest

{
  "transfers": [
    {
      "transactionHash": "0x...",
      "blockNumber": "12345678",
      "from": "0x...",
      "to": "0x...",
      "tokenId": "1234",
      "contractAddress": "0x...",
      "timestamp": "2026-02-26T20:33:00Z"
    }
  ]
}

4. Collection Data

GET /api/v1/nft/collections/:contractAddress
GET /api/v1/nft/collections/:contractAddress/floor
GET /api/v1/nft/collections/:contractAddress/traits

{
  "address": "0x...",
  "name": "XDC Punks",
  "symbol": "XDCNFT",
  "type": "XRC721",
  "totalSupply": "10000",
  "holders": 5420,
  "floorPrice": {
    "value": "500",
    "currency": "XDC",
    "usd": "25.00"
  },
  "volume": {
    "24h": "50000",
    "7d": "350000",
    "30d": "1200000"
  },
  "traits": {
    "Background": {
      "Blue": {"count": 1500, "percentage": 15},
      "Red": {"count": 1200, "percentage": 12}
    }
  }
}

5. Minting Data

GET /api/v1/nft/:contractAddress/:tokenId/mint
GET /api/v1/nft/mints?contractAddress=0x...

Technical Implementation

Database Schema

-- NFT Contracts
CREATE TABLE nft_contracts (
    address VARCHAR(42) PRIMARY KEY,
    name VARCHAR(255),
    symbol VARCHAR(50),
    type VARCHAR(20) CHECK (type IN ('XRC721', 'XRC1155')),
    total_supply NUMERIC,
    created_at TIMESTAMP,
    verified BOOLEAN DEFAULT FALSE
);

-- NFT Tokens
CREATE TABLE nfts (
    contract_address VARCHAR(42) REFERENCES nft_contracts(address),
    token_id NUMERIC,
    owner VARCHAR(42),
    metadata_uri TEXT,
    metadata JSONB,
    image_url TEXT,
    name VARCHAR(500),
    description TEXT,
    updated_at TIMESTAMP,
    PRIMARY KEY (contract_address, token_id)
);

-- NFT Transfers
CREATE TABLE nft_transfers (
    id SERIAL PRIMARY KEY,
    contract_address VARCHAR(42),
    token_id NUMERIC,
    from_address VARCHAR(42),
    to_address VARCHAR(42),
    transaction_hash VARCHAR(66),
    block_number BIGINT,
    log_index INTEGER,
    timestamp TIMESTAMP,
    value NUMERIC DEFAULT 1 -- For XRC1155
);

-- NFT Owners (XRC1155 balance tracking)
CREATE TABLE nft_balances (
    contract_address VARCHAR(42),
    token_id NUMERIC,
    owner VARCHAR(42),
    balance NUMERIC DEFAULT 0,
    updated_at TIMESTAMP,
    PRIMARY KEY (contract_address, token_id, owner)
);

-- Indexes
CREATE INDEX idx_nfts_owner ON nfts(owner);
CREATE INDEX idx_nft_transfers_contract ON nft_transfers(contract_address);
CREATE INDEX idx_nft_transfers_token ON nft_transfers(contract_address, token_id);
CREATE INDEX idx_nft_transfers_from ON nft_transfers(from_address);
CREATE INDEX idx_nft_transfers_to ON nft_transfers(to_address);

Metadata Fetching Service

package nft

type MetadataFetcher struct {
    httpClient *http.Client
    ipfsClient *ipfs.Client
    cache      *redis.Client
}

func (f *MetadataFetcher) FetchMetadata(uri string) (*Metadata, error) {
    // 1. Check cache
    // 2. Resolve IPFS/Arweave/HTTP
    // 3. Parse JSON
    // 4. Normalize attributes
    // 5. Cache result
}

Indexer Integration

// Event handlers for XRC721/XRC1155
func handleTransfer(event *types.Log) {
    // Parse Transfer/TransferSingle/TransferBatch events
    // Update ownership
    // Record transfer history
    // Queue metadata refresh if new mint
}

Advanced Features

1. Spam Detection

type SpamDetector struct {
    rules []SpamRule
}

// Rules:
// - High mint volume in short period
// - Duplicate metadata across tokens
// - Suspicious contract patterns
// - Community reports

2. Rarity Calculation

func CalculateRarity(token *NFT, collection *Collection) float64 {
    // Calculate trait rarity scores
    // Combine for overall rarity rank
}

3. Price Estimation

func EstimatePrice(contract string, tokenId string) (*PriceEstimate, error) {
    // ML model based on:
    // - Trait rarity
    // - Recent sales
    // - Collection floor
    // - Market trends
}

Batch Operations

POST /api/v1/nft/batch/metadata
{
  "tokens": [
    {"contractAddress": "0x...", "tokenId": "1"},
    {"contractAddress": "0x...", "tokenId": "2"}
  ]
}

WebSocket Events

{
  "event": "nft.transfer",
  "data": {
    "contractAddress": "0x...",
    "tokenId": "1234",
    "from": "0x...",
    "to": "0x...",
    "transactionHash": "0x..."
  }
}

Acceptance Criteria

• All core endpoints functional
• Support for XRC721 and XRC1155
• Metadata caching with TTL
• Spam filtering
• Batch operations (up to 100 tokens)
• WebSocket events for transfers
• <100ms response time for cached data

Competitor Comparison

Feature	Alchemy	QuickNode	XDC Gateway (Target)
NFT API	✅	✅	🔄 Planned
XRC721	✅	✅	✅
XRC1155	✅	✅	✅
Metadata	✅	✅	✅
Spam Filter	✅	❌	✅
Rarity	✅	❌	✅

References

• Alchemy NFT API
• QuickNode NFT API
• OpenSea API

Priority: P1 - Important for NFT ecosystem growth
Estimated Effort: 8 weeks
Labels: enhancement, api, P1, nft