erc1155_balanceOf
Check the balance of a specific ERC1155 token for a given owner address and token ID using the Ethereum blockchain. Ideal for verifying token holdings or managing asset tracking.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chainId | No | Optional. The chain ID to use. | |
| ownerAddress | Yes | The address to check balance for | |
| provider | No | Optional. Either a network name or custom RPC URL. Use getAllNetworks to see available networks and their details, or getNetwork to get info about a specific network. You can use any network name returned by these tools as a provider value. | |
| tokenAddress | Yes | The address of the ERC1155 contract | |
| tokenId | Yes | The ID of the token to query |
Implementation Reference
- src/tools/erc1155.ts:46-88 (registration)Primary registration of the erc1155_balanceOf MCP tool, including input schema (Zod validation) and the handler function that executes the tool logic by calling the EthersService and formatting the response."erc1155_balanceOf", { contractAddress: contractAddressSchema, tokenAddress: tokenAddressSchema.optional(), // Deprecated ownerAddress: addressSchema.describe("The address to check balance for"), tokenId: tokenIdSchema, provider: providerSchema, chainId: chainIdSchema }, async (params) => { // Map deprecated parameters const mapped = mapParameters(params); try { const contractAddr = mapped.contractAddress || params.tokenAddress; if (!contractAddr) { throw new Error('Either contractAddress or tokenAddress must be provided'); } const balance = await ethersService.getERC1155Balance( contractAddr, mapped.ownerAddress, params.tokenId, mapped.provider, mapped.chainId ); return { content: [{ type: "text", text: `Balance of token ${params.tokenId} for ${mapped.ownerAddress} is ${balance}` }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error getting ERC1155 balance: ${error instanceof Error ? error.message : String(error)}` }] }; } } );
- src/tools/index.ts:26-26 (registration)Top-level registration call in tools index that invokes the ERC1155 tools registration, including erc1155_balanceOf.registerERC1155Tools(server, ethersService);
- src/services/erc/erc1155.ts:37-83 (helper)Supporting helper function balanceOf that implements the core ERC1155 balance query logic using ethers.js, caching, metrics, and error handling. Called indirectly via EthersService.getERC1155Balance from the tool handler.export async function balanceOf( ethersService: EthersService, contractAddress: string, ownerAddress: string, tokenId: string | number, provider?: string, chainId?: number ): Promise<string> { metrics.incrementCounter('erc1155.balanceOf'); return timeAsync('erc1155.balanceOf', async () => { try { // Create cache key const cacheKey = createTokenCacheKey( CACHE_KEYS.ERC1155_BALANCE, contractAddress, ownerAddress, tokenId, chainId ); // Check cache first const cachedBalance = balanceCache.get(cacheKey); if (cachedBalance) { return cachedBalance; } // Get provider from ethers service const ethersProvider = ethersService['getProvider'](provider, chainId); // Create contract instance const contract = new ethers.Contract(contractAddress, ERC1155_ABI, ethersProvider); // Get balance const balance = await contract.balanceOf(ownerAddress, tokenId); const balanceStr = balance.toString(); // Cache result for future use (30 second TTL) balanceCache.set(cacheKey, balanceStr, { ttl: 30000 }); return balanceStr; } catch (error) { logger.debug('Error getting ERC1155 balance', { contractAddress, ownerAddress, tokenId, error }); throw handleTokenError(error, 'Failed to get token balance'); } }); }