NFT API Reference

NFT packages provide minting, trading, and marketplace integration capabilities.

Packages

Package	Description
@nirholas/nft-minting	NFT creation and minting
@nirholas/nft-trading	NFT trading operations
@nirholas/nft-marketplace	Marketplace integrations
@nirholas/nft-metadata	Metadata handling
@nirholas/nft-ipfs	IPFS integration

---

NFT Minting

Installation

pnpm add @nirholas/nft-minting

Configuration

import { NFTMinter } from '@nirholas/nft-minting'

const minter = new NFTMinter({
  network: 'ethereum', // or 'polygon', 'base', 'arbitrum'
  privateKey: process.env.PRIVATE_KEY!,
  rpcUrl: process.env.RPC_URL!,
  ipfsGateway: 'https://gateway.pinata.cloud',
  pinataApiKey: process.env.PINATA_API_KEY,
  pinataSecretKey: process.env.PINATA_SECRET_KEY,
})

ERC-721 Minting

deployERC721

Deploy a new ERC-721 collection.

async function deployERC721(config: ERC721Config): Promise<DeployResult>

interface ERC721Config {
  name: string
  symbol: string
  baseUri?: string
  maxSupply?: number
  royaltyBps?: number          // Basis points (250 = 2.5%)
  royaltyReceiver?: string
  ownerMintAllowed?: boolean
  publicMintAllowed?: boolean
  mintPrice?: string           // ETH
}

interface DeployResult {
  contractAddress: string
  transactionHash: string
  explorerUrl: string
}

Example:

const collection = await minter.deployERC721({
  name: 'My NFT Collection',
  symbol: 'MYNFT',
  maxSupply: 10000,
  royaltyBps: 500, // 5%
  royaltyReceiver: '0x...',
  mintPrice: '0.05',
})

console.log(`Collection deployed: ${collection.contractAddress}`)

mint

Mint a single NFT.

async function mint(params: MintParams): Promise<MintResult>

interface MintParams {
  contractAddress: string
  to: string
  tokenUri?: string
  metadata?: NFTMetadata
}

interface MintResult {
  tokenId: string
  transactionHash: string
  tokenUri: string
  explorerUrl: string
}

batchMint

Mint multiple NFTs in one transaction.

async function batchMint(params: BatchMintParams): Promise<BatchMintResult>

interface BatchMintParams {
  contractAddress: string
  to: string
  count: number
  baseUri?: string
  metadata?: NFTMetadata[]
}

---

ERC-1155 Minting

deployERC1155

Deploy a new ERC-1155 collection.

async function deployERC1155(config: ERC1155Config): Promise<DeployResult>

interface ERC1155Config {
  uri: string                  // Metadata URI template
  name?: string
  royaltyBps?: number
  royaltyReceiver?: string
}

mintERC1155

Mint ERC-1155 tokens.

async function mintERC1155(params: ERC1155MintParams): Promise<MintResult>

interface ERC1155MintParams {
  contractAddress: string
  to: string
  tokenId: string
  amount: number
  data?: string
}

---

Metadata Handling

interface NFTMetadata {
  name: string
  description: string
  image: string                // IPFS URI or URL
  external_url?: string
  animation_url?: string       // For video/audio NFTs
  background_color?: string    // Hex color without #
  attributes?: NFTAttribute[]
  properties?: Record<string, unknown>
}

interface NFTAttribute {
  trait_type: string
  value: string | number
  display_type?: 'number' | 'date' | 'boost_number' | 'boost_percentage'
  max_value?: number
}

uploadMetadata

Upload metadata to IPFS.

async function uploadMetadata(metadata: NFTMetadata): Promise<string>

const tokenUri = await minter.uploadMetadata({
  name: 'Cool NFT #1',
  description: 'A very cool NFT',
  image: 'ipfs://QmXxx...',
  attributes: [
    { trait_type: 'Rarity', value: 'Legendary' },
    { trait_type: 'Power', value: 100, display_type: 'number' },
  ],
})

uploadImage

Upload an image to IPFS.

async function uploadImage(
  file: Buffer | ReadableStream,
  filename: string
): Promise<string>

const imageUri = await minter.uploadImage(
  fs.readFileSync('./image.png'),
  'nft-image.png'
)

---

NFT Trading

Installation

pnpm add @nirholas/nft-trading

Configuration

import { NFTTrader } from '@nirholas/nft-trading'

const trader = new NFTTrader({
  network: 'ethereum',
  privateKey: process.env.PRIVATE_KEY!,
  rpcUrl: process.env.RPC_URL!,
})

Transfer Operations

transfer

Transfer an NFT to another address.

async function transfer(params: TransferParams): Promise<TransferResult>

interface TransferParams {
  contractAddress: string
  tokenId: string
  to: string
  tokenType?: 'ERC721' | 'ERC1155'
  amount?: number              // For ERC1155
}

safeTransfer

Transfer with receiver validation.

async function safeTransfer(params: TransferParams): Promise<TransferResult>

---

Approval Management

approve

Approve an address to transfer a specific token.

async function approve(params: ApproveParams): Promise<ApproveResult>

interface ApproveParams {
  contractAddress: string
  tokenId: string
  operator: string
}

setApprovalForAll

Approve an operator for all tokens.

async function setApprovalForAll(params: ApprovalForAllParams): Promise<void>

interface ApprovalForAllParams {
  contractAddress: string
  operator: string
  approved: boolean
}

isApprovedForAll

Check if an operator is approved.

async function isApprovedForAll(
  contractAddress: string,
  owner: string,
  operator: string
): Promise<boolean>

---

Query Functions

getOwner

Get the owner of an NFT.

async function getOwner(
  contractAddress: string,
  tokenId: string
): Promise<string>

getBalance

Get NFT balance for an address.

async function getBalance(
  contractAddress: string,
  owner: string,
  tokenId?: string            // Required for ERC1155
): Promise<number>

getTokenUri

Get the token URI.

async function getTokenUri(
  contractAddress: string,
  tokenId: string
): Promise<string>

getMetadata

Fetch and parse token metadata.

async function getMetadata(
  contractAddress: string,
  tokenId: string
): Promise<NFTMetadata>

---

Marketplace Integration

Installation

pnpm add @nirholas/nft-marketplace

OpenSea Integration

import { OpenSeaClient } from '@nirholas/nft-marketplace'

const opensea = new OpenSeaClient({
  apiKey: process.env.OPENSEA_API_KEY!,
  network: 'ethereum', // or 'polygon'
})

listForSale

List an NFT for sale.

async function listForSale(params: ListingParams): Promise<Listing>

interface ListingParams {
  contractAddress: string
  tokenId: string
  price: string               // In ETH/MATIC
  expirationTime?: number     // Unix timestamp
  currency?: string           // Default: native token
}

interface Listing {
  orderId: string
  orderHash: string
  price: string
  expirationTime: number
  makerAddress: string
}

cancelListing

Cancel an existing listing.

async function cancelListing(orderId: string): Promise<void>

buyNFT

Purchase an NFT.

async function buyNFT(params: BuyParams): Promise<PurchaseResult>

interface BuyParams {
  orderId: string
  // Or
  contractAddress: string
  tokenId: string
}

interface PurchaseResult {
  transactionHash: string
  tokenId: string
  price: string
  explorerUrl: string
}

makeOffer

Make an offer on an NFT.

async function makeOffer(params: OfferParams): Promise<Offer>

interface OfferParams {
  contractAddress: string
  tokenId: string
  price: string
  currency?: string          // WETH by default
  expirationTime?: number
}

acceptOffer

Accept an offer on your NFT.

async function acceptOffer(offerId: string): Promise<PurchaseResult>

---

Collection Queries

getCollection

Get collection details.

async function getCollection(slug: string): Promise<Collection>

interface Collection {
  slug: string
  name: string
  description: string
  imageUrl: string
  bannerImageUrl: string
  externalUrl: string
  twitterUsername: string
  discordUrl: string
  stats: CollectionStats
  paymentTokens: PaymentToken[]
  royalty: {
    bps: number
    recipient: string
  }
}

interface CollectionStats {
  totalSupply: number
  totalSales: number
  totalVolume: number
  floorPrice: number
  averagePrice: number
  numOwners: number
  marketCap: number
}

getCollectionNFTs

Get NFTs in a collection.

async function getCollectionNFTs(params: CollectionNFTsParams): Promise<NFT[]>

interface CollectionNFTsParams {
  slug: string
  limit?: number
  cursor?: string
  sortBy?: 'price' | 'rarity' | 'tokenId'
  sortDirection?: 'asc' | 'desc'
}

interface NFT {
  tokenId: string
  name: string
  description: string
  imageUrl: string
  animationUrl?: string
  traits: NFTAttribute[]
  rarity?: {
    rank: number
    score: number
  }
  lastSale?: {
    price: string
    currency: string
    timestamp: number
  }
  currentPrice?: string
}

getFloorPrice

Get collection floor price.

async function getFloorPrice(slug: string): Promise<FloorPrice>

interface FloorPrice {
  price: string
  currency: string
  listing: Listing
}

---

User Queries

getUserNFTs

Get NFTs owned by a user.

async function getUserNFTs(
  address: string,
  options?: UserNFTsOptions
): Promise<NFT[]>

interface UserNFTsOptions {
  collection?: string
  limit?: number
  cursor?: string
}

getUserListings

Get active listings by a user.

async function getUserListings(address: string): Promise<Listing[]>

getUserOffers

Get offers made by a user.

async function getUserOffers(address: string): Promise<Offer[]>

---

IPFS Integration

Installation

pnpm add @nirholas/nft-ipfs

IPFS Client

import { IPFSClient } from '@nirholas/nft-ipfs'

const ipfs = new IPFSClient({
  provider: 'pinata', // or 'infura', 'nft.storage', 'web3.storage'
  apiKey: process.env.IPFS_API_KEY!,
  apiSecret: process.env.IPFS_API_SECRET,
})

upload

Upload a file to IPFS.

async function upload(
  content: Buffer | ReadableStream | string,
  options?: UploadOptions
): Promise<IPFSResult>

interface UploadOptions {
  filename?: string
  contentType?: string
  pin?: boolean
}

interface IPFSResult {
  cid: string
  uri: string          // ipfs://...
  httpUrl: string      // https://gateway.../ipfs/...
  size: number
}

uploadDirectory

Upload a directory to IPFS.

async function uploadDirectory(
  files: FileEntry[],
  options?: DirectoryOptions
): Promise<IPFSResult>

interface FileEntry {
  path: string
  content: Buffer | string
}

fetch

Fetch content from IPFS.

async function fetch(cid: string): Promise<Buffer>
async function fetchJSON<T>(cid: string): Promise<T>

pin / unpin

Manage pinned content.

async function pin(cid: string): Promise<void>
async function unpin(cid: string): Promise<void>
async function getPins(): Promise<PinInfo[]>

---

Error Types

class NFTError extends Error {
  code: string
}

// Minting errors
class DeploymentError extends NFTError {}
class MintError extends NFTError {}
class MaxSupplyReachedError extends NFTError {}
class InsufficientFundsError extends NFTError {}

// Trading errors
class NotOwnerError extends NFTError {}
class NotApprovedError extends NFTError {}
class TransferError extends NFTError {}

// Marketplace errors
class ListingNotFoundError extends NFTError {}
class OfferExpiredError extends NFTError {}
class InsufficientBalanceError extends NFTError {}
class MarketplaceAPIError extends NFTError {}

// IPFS errors
class IPFSUploadError extends NFTError {}
class IPFSFetchError extends NFTError {}
class PinningError extends NFTError {}