NFT Operations

/**
 * Get NFT metadata for a specific token
 * @param contractAddress - NFT contract address
 * @param tokenId - Token ID to query
 * @param tokenType - Optional token type specification
 * @returns Promise resolving to NFT metadata
 */
getNftMetadata(
  contractAddress: string, 
  tokenId: string, 
  tokenType?: NftTokenType
): Promise<Nft>;

/**
 * Get metadata for multiple NFTs in batch
 * @param nfts - Array of NFT identifiers
 * @returns Promise resolving to array of NFT metadata
 */
getNftMetadataBatch(nfts: NftIdentifier[]): Promise<Nft[]>;

/**
 * Refresh cached NFT metadata
 * @param contractAddress - NFT contract address
 * @param tokenId - Token ID to refresh
 * @returns Promise resolving to refresh status
 */
refreshNftMetadata(contractAddress: string, tokenId: string): Promise<boolean>;

interface Nft {
  contract: NftContract;
  tokenId: string;
  tokenType: NftTokenType;
  title: string;
  description: string;
  timeLastUpdated: string;
  rawMetadata?: object;
  tokenUri?: TokenUri;
  media: Media[];
  spamInfo?: SpamInfo;
}

interface NftContract {
  address: string;
  name: string;
  symbol: string;
  totalSupply?: string;
  tokenType: NftTokenType;
  openSea?: OpenSeaCollectionMetadata;
  contractDeployer?: string;
  deployedBlockNumber?: number;
}

interface NftIdentifier {
  contractAddress: string;
  tokenId: string;
}

enum NftTokenType {
  ERC721 = "ERC721",
  ERC1155 = "ERC1155",
  UNKNOWN = "UNKNOWN",
}

/**
 * Get metadata for an NFT contract/collection
 * @param contractAddress - Contract address to query
 * @returns Promise resolving to contract metadata
 */
getContractMetadata(contractAddress: string): Promise<NftContract>;

/**
 * Get metadata for multiple contracts in batch
 * @param contractAddresses - Array of contract addresses
 * @returns Promise resolving to array of contract metadata
 */
getContractMetadataBatch(contractAddresses: string[]): Promise<NftContract[]>;

/**
 * Get all NFTs in a contract with pagination
 * @param contractAddress - Contract address to query
 * @param options - Query options including pagination
 * @returns Promise resolving to NFTs in the contract
 */
getNftsForContract(
  contractAddress: string, 
  options?: GetNftsForContractOptions
): Promise<NftContractNftsResponse>;

interface GetNftsForContractOptions {
  pageKey?: string;
  limit?: number;
  withMetadata?: boolean;
  startToken?: string;
}

interface NftContractNftsResponse {
  nfts: Nft[];
  pageKey?: string;
}

/**
 * Get all NFTs owned by an address
 * @param owner - Address to query NFTs for
 * @param options - Query options and filters
 * @returns Promise resolving to owned NFTs
 */
getNftsForOwner(
  owner: string, 
  options?: GetNftsForOwnerOptions
): Promise<OwnedNftsResponse>;

/**
 * Get owners of a specific NFT (useful for ERC1155)
 * @param contractAddress - NFT contract address
 * @param tokenId - Token ID to query owners for
 * @returns Promise resolving to list of owners
 */
getOwnersForNft(contractAddress: string, tokenId: string): Promise<GetOwnersForNftResponse>;

/**
 * Get all owners for an entire NFT contract
 * @param contractAddress - Contract address to query
 * @param options - Query options including pagination
 * @returns Promise resolving to contract owners
 */
getOwnersForContract(
  contractAddress: string, 
  options?: GetOwnersForContractOptions
): Promise<GetOwnersForContractResponse>;

/**
 * Check if an address owns specific NFTs
 * @param owner - Address to check ownership for
 * @param nfts - Array of NFTs to check
 * @returns Promise resolving to ownership status
 */
checkNftOwnership(owner: string, nfts: NftIdentifier[]): Promise<boolean[]>;

interface GetNftsForOwnerOptions {
  contractAddresses?: string[];
  excludeFilters?: NftFilters[];
  includeFilters?: NftFilters[];
  pageKey?: string;
  pageSize?: number;
  tokenUriTimeoutInMs?: number;
  orderBy?: NftOrdering;
}

interface OwnedNftsResponse {
  ownedNfts: OwnedNft[];
  pageKey?: string;
  totalCount: number;
  validAt: AlchemyBlockIdentifier;
}

interface OwnedNft extends Nft {
  balance: string;
}

interface GetOwnersForNftResponse {
  owners: string[];
}

interface GetOwnersForContractOptions {
  block?: string;
  pageKey?: string;
}

interface GetOwnersForContractResponse {
  owners: string[];
  pageKey?: string;
}

enum NftFilters {
  SPAM = "SPAM",
  AIRDROPS = "AIRDROPS",
}

enum NftOrdering {
  TRANSFERTIME = "TRANSFERTIME",
}

/**
 * Get NFT sales history
 * @param options - Sales query parameters
 * @returns Promise resolving to sales data
 */
getNftSales(options?: GetNftSalesOptions): Promise<GetNftSalesResponse>;

/**
 * Get floor price for an NFT collection
 * @param contractAddress - Contract address to get floor price for
 * @returns Promise resolving to floor price data
 */
getFloorPrice(contractAddress: string): Promise<GetFloorPriceResponse>;

/**
 * Get NFT activity/events for a collection or token
 * @param params - Activity query parameters
 * @returns Promise resolving to activity data
 */
getNftActivity(params: GetNftActivityParams): Promise<GetNftActivityResponse>;

interface GetNftSalesOptions {
  fromBlock?: number | string;
  toBlock?: number | string;
  order?: SortingOrder;
  marketplace?: NftSaleMarketplace;
  contractAddress?: string;
  tokenId?: string;
  taker?: string;
  seller?: string;
  buyer?: string;
  pageKey?: string;
  limit?: number;
}

interface GetNftSalesResponse {
  nftSales: NftSale[];
  validAt: AlchemyBlockIdentifier;
  pageKey?: string;
}

interface NftSale {
  marketplace: NftSaleMarketplace;
  contractAddress: string;
  tokenId: string;
  quantity: string;
  buyerAddress: string;
  sellerAddress: string;
  taker: NftSaleTakerType;
  sellerFee: NftSaleFeeData;
  protocolFee?: NftSaleFeeData;
  royaltyFee?: NftSaleFeeData;
  blockNumber: number;
  logIndex: number;
  bundleIndex: number;
  transactionHash: string;
}

interface GetFloorPriceResponse {
  openSea: FloorPriceMarketplace;
  looksRare: FloorPriceMarketplace;
}

interface FloorPriceMarketplace {
  floorPrice: number;
  priceCurrency: string;
  collectionUrl: string;
  retrievedAt: string;
}

enum NftSaleMarketplace {
  SEAPORT = "seaport",
  LOOKSRARE = "looksrare",
  X2Y2 = "x2y2",
  WYVERN = "wyvern",
  CRYPTOPUNKS = "cryptopunks",
  UNKNOWN = "unknown",
}

/**
 * Compute rarity for an NFT based on its attributes
 * @param contractAddress - NFT contract address
 * @param tokenId - Token ID to compute rarity for
 * @returns Promise resolving to rarity data
 */
computeRarity(
  contractAddress: string, 
  tokenId: string
): Promise<ComputeRarityResponse>;

/**
 * Check if a contract is flagged as spam
 * @param contractAddress - Contract address to check
 * @returns Promise resolving to spam status
 */
isSpamContract(contractAddress: string): Promise<IsSpamContractResponse>;

/**
 * Get list of spam contracts
 * @returns Promise resolving to spam contracts list
 */
getSpamContracts(): Promise<GetSpamContractsResponse>;

/**
 * Report a contract as spam
 * @param contractAddress - Contract address to report
 * @returns Promise resolving to report status
 */
reportSpam(contractAddress: string): Promise<void>;

/**
 * Classify NFT type and characteristics
 * @param contractAddress - NFT contract address
 * @param tokenId - Token ID to classify
 * @returns Promise resolving to classification data
 */
classifyNft(contractAddress: string, tokenId: string): Promise<ClassifyNftResponse>;

/**
 * Get summary of NFT attributes for a collection
 * @param contractAddress - Contract address to analyze
 * @returns Promise resolving to attribute summary
 */
summarizeNftAttributes(contractAddress: string): Promise<NftAttributesResponse>;

interface ComputeRarityResponse {
  rarityScore: number;
  rarityRank: number;
  totalSupply: number;
  prevalence: number;
}

interface IsSpamContractResponse {
  isSpamContract: boolean;
}

interface GetSpamContractsResponse {
  contractAddresses: string[];
}

interface ClassifyNftResponse {
  classification: NftClassification;
}

interface NftAttributesResponse {
  summary: Record<string, NftAttributeSummary>;
  contractAddress: string;
  totalSupply: number;
}

interface NftAttributeSummary {
  values: NftAttributeValueSummary[];
}

interface NftAttributeValueSummary {
  value: string;
  prevalence: number;
  count: number;
}

enum NftClassification {
  COLLECTIBLE = "collectible",
  GAMING = "gaming",
  ART = "art",
  UTILITY = "utility",
  PFPS = "pfps",
  UNKNOWN = "unknown",
}

/**
 * Search for NFT contracts by name
 * @param query - Search query string
 * @returns Promise resolving to matching contracts
 */
searchContractMetadata(query: string): Promise<SearchContractMetadataResponse>;

interface SearchContractMetadataResponse {
  contracts: NftContract[];
}

interface Media {
  gateway: string;
  thumbnail?: string;
  raw: string;
  format: string;
  bytes?: number;
}

interface TokenUri {
  gateway: string;
  raw: string;
}

interface OpenSeaCollectionMetadata {
  floorPrice: number;
  collectionName: string;
  safelistRequestStatus: string;
  imageUrl: string;
  description: string;
  externalUrl: string;
  twitterUsername: string;
  discordUrl: string;
  lastIngestedAt: string;
}

interface SpamInfo {
  isSpam: string;
  classifications: string[];
}

import { Alchemy, Network, NftFilters } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: "your-api-key",
  network: Network.ETH_MAINNET,
});

// Get NFT metadata
const nft = await alchemy.nft.getNftMetadata(
  "0x...", // contract address
  "1234"   // token ID
);

// Get all NFTs owned by an address
const ownedNfts = await alchemy.nft.getNftsForOwner("0x...", {
  excludeFilters: [NftFilters.SPAM],
  pageSize: 50,
});

// Get NFT sales history
const sales = await alchemy.nft.getNftSales({
  contractAddress: "0x...",
  limit: 100,
});

// Get collection floor price
const floorPrice = await alchemy.nft.getFloorPrice("0x...");

// Compute rarity for an NFT
const rarity = await alchemy.nft.computeRarity("0x...", "1234");

// Check if contract is spam
const spamCheck = await alchemy.nft.isSpamContract("0x...");

// Get contract metadata
const collection = await alchemy.nft.getContractMetadata("0x...");

// Search for collections
const searchResults = await alchemy.nft.searchContractMetadata("Bored Ape");