Overview
The NftService is responsible for detecting and managing NFT (Non-Fungible Token) collections and items across EVM-compatible chains. It automatically fetches NFT metadata, collections, and ownership information.
Key Features
- EVM NFT collection detection
- Automatic metadata fetching
- Support for ERC-721 tokens
- Collection and item mapping
- Batch processing for multiple addresses
Class: NftService
Constructor
constructor(state: KoniState)
The global state object of the extension
Core Methods
fetchEvmCollectionsWithPreview()
Fetches NFT collections with preview items for EVM addresses.
async fetchEvmCollectionsWithPreview(addresses: string[]): Promise<void>
Array of EVM wallet addresses to fetch NFTs for
- Queries NFT detection API for each address
- Maps SDK collection data to internal NFT format
- Handles collection metadata (name, image, item count)
- Processes NFT instances with attributes and properties
- Automatically stores detected NFTs in the extension state
Usage:
const nftService = new NftService(state);
await nftService.fetchEvmCollectionsWithPreview([
'0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
'0x1234567890123456789012345678901234567890'
]);
getFullNftInstancesByCollection()
Retrieves all NFT instances for a specific collection.
async getFullNftInstancesByCollection(
request: NftFullListRequest
): Promise<boolean>
request
NftFullListRequest
required
Request parameters for fetching NFT instancesNFT collection contract address
owners
string | string[]
required
Owner address(es)
true if the operation succeeded, false otherwise
const success = await nftService.getFullNftInstancesByCollection({
chainInfo: chainInfoMap['ethereum'],
contractAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
owners: ['0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb']
});
if (success) {
console.log('Successfully fetched all NFT instances');
}
Data Types
NftItem
Represents an individual NFT.
interface NftItem {
id: string;
chain: string;
collectionId: string;
owner: string;
name: string;
image?: string;
externalUrl?: string;
rarity?: string;
description?: string;
properties: Record<string, string | number | boolean | null> | null;
type: _AssetType.ERC721;
originAsset?: string;
rmrk_ver?: string;
onChainOption?: any;
assetHubType?: any;
}
Chain slug where the NFT exists
Collection contract address
Current owner’s wallet address
NFT image URL (IPFS URLs are automatically parsed)
properties
Record<string, any> | null
NFT attributes and traits
Rarity classification if available
NFT standard type (currently only ERC-721 is supported)
NftCollection
Represents an NFT collection.
interface NftCollection {
collectionId: string;
chain: string;
collectionName: string;
image?: string;
itemCount: number;
externalUrl?: string;
originAsset?: string;
}
Collection contract address
Collection icon/image URL
Number of items in the collection
NftFullListRequest
Request parameters for fetching complete NFT lists.
interface NftFullListRequest {
chainInfo: _ChainInfo;
contractAddress: string;
owners: string | string[];
}
Supported NFT Standards
Currently, the NFT Service supports:
- ERC-721: Standard NFT contract on EVM chains
ERC-1155 (semi-fungible tokens) and other standards are not currently supported.
- Basic Information: Name, description, image
- Attributes: Trait types and values
- Rarity: Rarity classification from attributes
- External Links: Project websites and marketplaces
- Media: Images, videos (IPFS URLs are converted to HTTP gateways)
Detection Flow
- Address Validation: Checks if addresses are valid Ethereum-type addresses
- API Query: Queries the NFT detection API for collections
- Data Mapping: Converts SDK format to internal NFT format
- Metadata Parsing: Extracts and normalizes metadata
- Storage: Stores NFT collections and items in state
- Event Emission: Notifies UI of detected NFTs
Example: NFT Detection Workflow
import NftService from '@subwallet/extension-base/services/nft-service';
// Initialize service
const nftService = new NftService(state);
// Detect NFTs for multiple addresses
const addresses = [
'0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
'0x1234567890123456789012345678901234567890'
];
await nftService.fetchEvmCollectionsWithPreview(addresses);
// NFTs are automatically stored in state and can be accessed via:
// state.handleDetectedNftCollections(collections)
// state.handleDetectedNfts(address, nftItems)
Example: Fetch Complete Collection
// Get all NFTs from a specific collection
const chainInfo = state.chainService.getChainInfoByKey('ethereum');
const success = await nftService.getFullNftInstancesByCollection({
chainInfo,
contractAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', // BAYC
owners: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
});
if (success) {
// All NFT instances have been fetched and stored
console.log('Complete collection data loaded');
}
- NFT detection runs asynchronously to avoid blocking
- Multiple addresses can be processed in parallel
- Duplicate checks prevent re-processing ongoing requests
- Results are cached to reduce API calls
Error Handling
The service handles errors gracefully:
try {
await nftService.fetchEvmCollectionsWithPreview(addresses);
} catch (error) {
console.warn('NFT detection error:', error);
// Service continues operating, individual errors are logged
}
NFT detection requires valid EVM addresses. Non-EVM addresses will be skipped.