Token Owner API Enhancements

Firekeeper

Token Owners Endpoint (/v1/tokens/{chainId}/{address}/owners)

• Multi-standard Support: Now supports ERC-20, ERC-721, and ERC-1155 token contracts (previously ERC-20 only)
• NFT Collection Owners: Query all owners of an NFT collection without specifying a token ID
• Specific NFT Token Owners: Query owners of a specific NFT token by providing the tokenId parameter

Request Parameters

• Added optional tokenId parameter to filter NFT owners by specific token ID
  • When provided: Returns owners of the specific NFT token
  • When omitted: Returns collection-level owners for NFTs, or token holders for ERC-20, automatically detecting what kind of token it is.

Response Format

• Added optional tokenId field to owner objects in responses
  • Present for NFT queries (ERC-721/ERC-1155)
  • Absent for ERC-20 token queries

Response Behavior by Token Type

• ERC-20: Returns token holders with their balance amounts
• ERC-721 Collection: Returns owners with their token IDs and amount "1"
• ERC-721 Specific: Returns owners of the specified token ID
• ERC-1155 Collection: Returns owners with their token IDs and balance amounts
• ERC-1155 Specific: Returns owners of the specified token ID with their balance amounts

• Automatic Token Standard Detection: The API automatically detects whether a contract is ERC-20, ERC-721, or ERC-1155 using ERC-165
• Enhanced Error Handling: Better error messages specific to each token standard
• Consistent Pagination: All token types now return consistent pagination metadata (hasMore, limit, page)

• Updated OpenAPI specifications with examples for all supported token standards
• Clarified what the amount field represents for different token types