erc1155_balanceOfBatch

Query multiple ERC1155 token balances for different addresses and token IDs in a single blockchain call to efficiently check ownership across collections.

Input Schema

TableJSON Schema

Name	Required	Description
`tokenAddress`	Yes	The address of the ERC1155 contract
`ownerAddresses`	Yes	Array of addresses to check balances for
`tokenIds`	Yes	Array of token IDs to check balances 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.
`chainId`	No	Optional. The chain ID to use.

Implementation Reference

src/tools/erc1155.ts:152-195 (registration)

Registration of the erc1155_balanceOfBatch tool including inline schema and handler function. This is where the tool is defined and registered with the MCP server.

  "erc1155_balanceOfBatch",
  {
    tokenAddress: contractAddressSchema,
    ownerAddresses: z.array(addressSchema).describe(
      "Array of addresses to check balances for"
    ),
    tokenIds: z.array(tokenIdSchema).describe(
      "Array of token IDs to check balances for"
    ),
    provider: providerSchema,
    chainId: chainIdSchema
  },
  async (params) => {
    try {
      const balances = await ethersService.getERC1155BatchBalances(
        params.tokenAddress,
        params.ownerAddresses,
        params.tokenIds,
        params.provider,
        params.chainId
      );
      
      let resultText = "Batch balances:\n";
      for (let i = 0; i < params.ownerAddresses.length; i++) {
        resultText += `${params.ownerAddresses[i]} - Token ${params.tokenIds[i]}: ${balances[i]}\n`;
      }
      
      return {
        content: [{ 
          type: "text", 
          text: resultText
        }]
      };
    } catch (error) {
      return {
        isError: true,
        content: [{ 
          type: "text", 
          text: `Error getting ERC1155 batch balances: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

src/tools/erc1155.ts:164-194 (handler)

The handler function that executes the tool: fetches batch balances using EthersService and formats the response as text.

async (params) => {
  try {
    const balances = await ethersService.getERC1155BatchBalances(
      params.tokenAddress,
      params.ownerAddresses,
      params.tokenIds,
      params.provider,
      params.chainId
    );
    
    let resultText = "Batch balances:\n";
    for (let i = 0; i < params.ownerAddresses.length; i++) {
      resultText += `${params.ownerAddresses[i]} - Token ${params.tokenIds[i]}: ${balances[i]}\n`;
    }
    
    return {
      content: [{ 
        type: "text", 
        text: resultText
      }]
    };
  } catch (error) {
    return {
      isError: true,
      content: [{ 
        type: "text", 
        text: `Error getting ERC1155 batch balances: ${error instanceof Error ? error.message : String(error)}`
      }]
    };
  }
}

src/tools/erc1155.ts:154-163 (schema)

Zod schema defining input parameters for the tool: contract address, arrays of owners and token IDs, optional provider and chainId.

  tokenAddress: contractAddressSchema,
  ownerAddresses: z.array(addressSchema).describe(
    "Array of addresses to check balances for"
  ),
  tokenIds: z.array(tokenIdSchema).describe(
    "Array of token IDs to check balances for"
  ),
  provider: providerSchema,
  chainId: chainIdSchema
},

src/services/erc/erc1155.ts:96-131 (helper)

Helper function balanceOfBatch that implements the core ERC1155 balanceOfBatch contract call with caching, metrics, error handling. Likely called by EthersService.getERC1155BatchBalances.

export async function balanceOfBatch(
  ethersService: EthersService,
  contractAddress: string,
  ownerAddresses: string[],
  tokenIds: (string | number)[],
  provider?: string,
  chainId?: number
): Promise<string[]> {
  metrics.incrementCounter('erc1155.balanceOfBatch');
  
  return timeAsync('erc1155.balanceOfBatch', async () => {
    try {
      // Validate input lengths
      if (ownerAddresses.length !== tokenIds.length) {
        throw new ERC1155Error(
          'Owner addresses and token IDs arrays must have the same length'
        );
      }
      
      // Get provider from ethers service
      const ethersProvider = ethersService['getProvider'](provider, chainId);
      
      // Create contract instance
      const contract = new ethers.Contract(contractAddress, ERC1155_ABI, ethersProvider);
      
      // Get balances
      const balances = await contract.balanceOfBatch(ownerAddresses, tokenIds);
      
      // Convert to strings
      return balances.map((balance: bigint) => balance.toString());
    } catch (error) {
      logger.debug('Error getting ERC1155 batch balances', { contractAddress, error });
      throw handleTokenError(error, 'Failed to get token balances');
    }
  });
}

MCP Ethers Wallet