erc721_balanceOf
Check how many ERC721 NFTs a specific address owns from a given smart contract. Use this tool to verify NFT ownership balances on Ethereum networks.
Instructions
Get the number of ERC721 NFTs owned by a specific address. Alternative naming for compatibility with MCP client tests.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tokenAddress | Yes | The address of the ERC721 contract | |
| ownerAddress | Yes | The address to check balance for | |
| provider | No | Optional. The provider to use. If not provided, the default provider is used. | |
| chainId | No | Optional. The chain ID to use. |
Implementation Reference
- src/tools/erc721.ts:189-218 (handler)Handler function that implements the core logic of the erc721_balanceOf tool by fetching owned tokens via ethersService and computing the balance as the token count.
async (params) => { try { // Get the tokens owned by this address const tokens = await ethersService.getERC721TokensOfOwner( params.tokenAddress, params.ownerAddress, false, params.provider, params.chainId ); // The balance is the number of tokens const balance = tokens.length.toString(); return { content: [{ type: "text", text: `${params.ownerAddress} has ${balance} NFTs from contract ${params.tokenAddress}` }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error getting NFT balance: ${error instanceof Error ? error.message : String(error)}` }] }; } } - src/tools/erc721.ts:179-219 (registration)Registration of the erc721_balanceOf tool on the MCP server, including name, description, input schema, and inline handler function.
// Client test compatible version - erc721_balanceOf server.tool( "erc721_balanceOf", "Get the number of ERC721 NFTs owned by a specific address. Alternative naming for compatibility with MCP client tests.", { tokenAddress: contractAddressSchema.describe("The address of the ERC721 contract"), ownerAddress: addressSchema.describe("The address to check balance for"), provider: providerSchema.describe("Optional. The provider to use. If not provided, the default provider is used."), chainId: chainIdSchema.describe("Optional. The chain ID to use.") }, async (params) => { try { // Get the tokens owned by this address const tokens = await ethersService.getERC721TokensOfOwner( params.tokenAddress, params.ownerAddress, false, params.provider, params.chainId ); // The balance is the number of tokens const balance = tokens.length.toString(); return { content: [{ type: "text", text: `${params.ownerAddress} has ${balance} NFTs from contract ${params.tokenAddress}` }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error getting NFT balance: ${error instanceof Error ? error.message : String(error)}` }] }; } } ); - src/tools/erc721.ts:184-188 (schema)Input schema definition for the erc721_balanceOf tool parameters: tokenAddress, ownerAddress, provider, chainId.
tokenAddress: contractAddressSchema.describe("The address of the ERC721 contract"), ownerAddress: addressSchema.describe("The address to check balance for"), provider: providerSchema.describe("Optional. The provider to use. If not provided, the default provider is used."), chainId: chainIdSchema.describe("Optional. The chain ID to use.") },