⚙️

# NFT Settings Configuration

Complete Settings Reference Guide

## 🎯 Settings Overview

The NFT Marketplace settings provide comprehensive control over trading mechanics, fees, verification requirements, and content policies. All settings are stored in flat configuration format with the `nft` prefix and can be modified at runtime without requiring system restart.

Access settings at `/admin/nft/settings` with appropriate admin permissions.

## 💰 Trading Settings

Control which trading types are available to users and configure auction mechanics.

### Enable Fixed-Price Sales

Allow users to list NFTs at fixed prices for immediate purchase.

`boolean`

Configuration Key:

`nftEnableFixedPriceSales`

Default: true
Effect: When disabled, "List for Sale" option hidden from UI and fixed-price endpoints return errors.

### Enable Auctions

Allow users to create timed auctions with bidding mechanics.

`boolean`

Configuration Key:

`nftEnableAuctions`

Default: true
Effect: When disabled, auction listing option removed from UI and auction endpoints blocked.

### Enable Direct Offers

Allow users to make offers on any NFT (even unlisted ones).

`boolean`

Configuration Key:

`nftEnableOffers`

Default: true
Effect: When disabled, "Make Offer" button hidden from NFT details pages.

### Minimum Auction Duration

Shortest allowed auction length in hours.

`number`

Configuration Key:

`nftMinAuctionDuration`

Default: 3600 (1 hour in seconds)
Range: 1 hour - 720 hours (30 days)
Effect: Users cannot create auctions shorter than this duration.

### Maximum Auction Duration

Longest allowed auction length in hours.

`number`

Configuration Key:

`nftMaxAuctionDuration`

Default: 604800 (7 days in seconds)
Range: 1 hour - 720 hours (30 days)
Effect: Users cannot create auctions longer than this duration.

### Minimum Bid Increment

Percentage by which each bid must exceed the current highest bid.

`number`

Configuration Key:

`nftBidIncrementPercentage`

Default: 5 (5%)
Range: 1-50%
Effect: If current bid is 1 ETH and increment is 5%, minimum next bid is 1.05 ETH.

### Enable Anti-Snipe Protection

Automatically extend auction when bids placed near end time.

`boolean`

Configuration Key:

`nftEnableAntiSnipe`

Default: true
Effect: If bid placed within 10 minutes of end, auction extends by configured duration.

### Anti-Snipe Extension Duration

How many seconds to extend auction when late bid is placed.

`number`

Configuration Key:

`nftAntiSnipeExtension`

Default: 300 (5 minutes in seconds)
Range: 60-3600 seconds (1 minute - 1 hour)
Effect: Auction extends by this duration every time a bid is placed near end.

## 💵 Fee Settings

Configure marketplace revenue model and creator royalty limits.

### Marketplace Fee Percentage

Platform commission on each sale (goes to marketplace).

`number`

Configuration Key:

`nftMarketplaceFeePercentage`

Default: 2.5 (2.5%)
Range: 0-10%
Effect: Deducted from sale price. On 1 ETH sale with 2.5% fee, marketplace receives 0.025 ETH.

Note: Industry standard is 2-3%. OpenSea charges 2.5%.

### Maximum Royalty Percentage

Highest royalty percentage creators can set on secondary sales.

`number`

Configuration Key:

`nftMaxRoyaltyPercentage`

Default: 10 (10%)
Range: 0-50%
Effect: Creators cannot set royalties above this limit when creating collections.

Typical Range: 5-10% is standard. Higher percentages may discourage resales.

### Listing Fee

Optional fixed fee charged when listing an NFT (in native token).

`number`

Configuration Key:

`nftListingFee`

Default: 0 (disabled)
Range: 0+ (in native token, e.g., ETH, BNB)
Effect: Users must pay this fee to list NFT. Helps prevent spam listings.

Warning: Non-zero listing fees may reduce listing activity. Most marketplaces use 0.

#### Fee Calculation Example

NFT sells for 1 ETH with 2.5% marketplace fee and 10% royalty:

Sale Price: 1.00 ETH
Marketplace Fee (2.5%): -0.025 ETH
Creator Royalty (10%): -0.100 ETH
Seller Receives: 0.875 ETH

## 🔐 Verification Settings

Configure KYC requirements and high-value transaction protection.

### Require KYC for Creators

Force creators to complete KYC verification before creating collections.

`boolean`

Configuration Key:

`nftRequireKycForCreators`

Default: false
Dependency: Requires KYC extension installed and configured
Effect: When enabled, collection creation blocked until KYC status is APPROVED.

Compliance: Recommended for jurisdictions with strict digital asset regulations.

### Require KYC for High-Value Transactions

Force buyers to complete KYC when purchasing high-value NFTs.

`boolean`

Configuration Key:

`nftRequireKycForHighValue`

Default: true
Dependency: Requires KYC extension and currency price conversion
Effect: Purchases above threshold blocked until KYC APPROVED. System converts crypto price to USD.

Implementation: Uses backend/src/api/(ext)/nft/utils/price-converter.ts for USD conversion via currency table.

### High-Value Transaction Threshold

USD value at which KYC becomes required for purchases.

`number`

Configuration Key:

`nftHighValueThreshold`

Default: 1000 (USD)
Range: 0+ (USD)
Effect: When enabled and purchase exceeds this USD value, KYC required.

Price Conversion: System automatically converts ETH/BNB/MATIC prices to USD using currency table. Stablecoins (USDC, USDT, DAI) = $1 each.

#### ⚠️ KYC Requirements

To use KYC-based settings:

- 1. Install and activate KYC extension
- 2. Configure KYC verification workflow
- 3. Set up currency price updates (for high-value threshold)
- 4. Test with various purchase amounts

## 📋 Content Settings

Configure metadata validation and content integrity policies.

### Require Metadata Validation

Validate IPFS metadata and images when creating NFT listings.

`boolean`

Configuration Key:

`nftRequireMetadataValidation`

Default: true
Effect: When enabled, system validates:

- • IPFS URL format correctness
- • Metadata JSON structure (ERC-721 compliance)
- • Image URL accessibility
- • Required fields presence (name, description, image)

Implementation: Uses backend/src/api/(ext)/nft/utils/metadata-validator.ts with IPFS gateway fetching and JSON validation.

#### Supported IPFS URL Formats:

`ipfs://QmHash...` Standard IPFS protocol
`https://ipfs.io/ipfs/QmHash...` IPFS.io gateway
`https://gateway.pinata.cloud/ipfs/QmHash...` Pinata gateway
`https://cloudflare-ipfs.com/ipfs/QmHash...` Cloudflare gateway

## 🔗 Integration Settings

Configure blockchain and cross-chain features.

### Enable Cross-Chain Support

Allow users to create and trade NFTs on multiple blockchains.

`boolean`

Configuration Key:

`nftEnableCrossChain`

Default: true
Effect: When enabled, users can select different blockchains during collection creation. When disabled, only primary chain available.

Supported Chains: Ethereum, BSC, Polygon, Arbitrum, Optimism (when marketplace contracts deployed).

## 💾 Settings Storage & Management

### Configuration Format

All NFT settings are stored in the flat configuration system with consistent naming:

#### Naming Convention:

`nft + PascalCaseName`

Examples:

- • nftEnableFixedPriceSales
- • nftMarketplaceFeePercentage
- • nftRequireKycForHighValue

### Complete Settings List

Key | Type | Default
--- | --- | ---
nftEnableFixedPriceSales | boolean | true
nftEnableAuctions | boolean | true
nftEnableOffers | boolean | true
nftMinAuctionDuration | number | 3600 (seconds)
nftMaxAuctionDuration | number | 604800 (seconds)
nftBidIncrementPercentage | number | 5 (%)
nftEnableAntiSnipe | boolean | true
nftAntiSnipeExtension | number | 300 (seconds)
nftMarketplaceFeePercentage | number | 2.5 (%)
nftMaxRoyaltyPercentage | number | 10 (%)
nftListingFee | number | 0
nftRequireKycForCreators | boolean | false
nftRequireKycForHighValue | boolean | true
nftHighValueThreshold | number | 1000 (USD)
nftRequireMetadataValidation | boolean | true
nftEnableCrossChain | boolean | true

#### 💡 Runtime Updates

All settings can be changed via admin panel and take effect immediately without system restart. Settings are cached in frontend store with configurable refresh intervals.

## 💡 Configuration Best Practices

### Launch Configuration

- ✓ Start with default settings
- ✓ Enable all trading types initially
- ✓ Set marketplace fee to 2-3%
- ✓ Limit royalties to 10%
- ✓ Enable anti-snipe protection
- ✓ Disable KYC initially (enable later)
- ✓ Enable metadata validation
- ✓ Keep listing fees at 0

### Compliance Settings

- ✓ Enable creator KYC in regulated markets
- ✓ Set high-value threshold (e.g., $10,000)
- ✓ Enable metadata validation always
- ✓ Monitor for suspicious activity
- ✓ Document all policy changes
- ✓ Review settings quarterly

### Auction Settings

- ✓ Min duration: 1 hour (reduce spam)
- ✓ Max duration: 7 days default (can extend to 30 days)
- ✓ Bid increment: 5% (prevents penny bidding)
- ✓ Anti-snipe: Always enabled
- ✓ Extension: 5 minutes standard

### Fee Optimization

- ✓ Marketplace fee: 2-3% competitive
- ✓ Royalties: 5-10% encourages resales
- ✓ Avoid listing fees (reduces activity)
- ✓ Test fee changes on testnet first
- ✓ Monitor revenue vs. volume tradeoff

## 🔧 Settings Troubleshooting

Settings not taking effect

- • Clear frontend cache and reload page
- • Check settings save confirmation message
- • Verify no browser console errors
- • Test in incognito mode
- • Check backend logs for save errors

KYC settings not working

- • Verify KYC extension is installed and active
- • Check KYC workflow is configured
- • Ensure currency price data is updating
- • Test with APPROVED KYC user
- • Check backend logs for KYC check errors

Metadata validation failing unexpectedly

- • Verify IPFS gateway is accessible
- • Check IPFS URL format is correct
- • Ensure metadata JSON is valid
- • Test with known-good IPFS URL
- • Check firewall allows IPFS gateway access
- • Temporarily disable to isolate issue

Fee calculations incorrect

- • Verify fee percentage values (should be 0-100, not decimals)
- • Check smart contract fee configuration matches
- • Review transaction receipts for actual fees
- • Test with simple round numbers
- • Check blockchain explorer for contract fees

## 🚀 Next Steps

### 📦 Installation

Setup and deployment guide

### 👨‍💼 Admin Features

Management and moderation tools

### 👥 User Features

User workflows and features

### 💬 Need Help?

For configuration assistance or questions about specific settings, visit our support portal or contact the support team.