get_erc1155_balance
Retrieve the balance of a specific ERC1155 token ID owned by a wallet address across Ethereum-compatible networks. Input includes token contract address, token ID, and wallet address.
Instructions
Get the balance of a specific ERC1155 token ID owned by an address. ERC1155 allows multiple tokens of the same ID, so the balance can be greater than 1.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Network name (e.g., 'ethereum', 'optimism', 'arbitrum', 'base', 'polygon') or chain ID. ERC1155 tokens exist across many networks. Defaults to Ethereum mainnet. | |
| ownerAddress | Yes | The wallet address to check the token balance for (e.g., '0x1234...') | |
| tokenAddress | Yes | The contract address of the ERC1155 token collection (e.g., '0x76BE3b62873462d2142405439777e971754E8E77') | |
| tokenId | Yes | The ID of the specific token to check the balance for (e.g., '1234') |
Implementation Reference
- src/core/tools.ts:1194-1215 (handler)MCP tool handler that takes input parameters, calls the getERC1155Balance service, formats the balance response as JSON, or returns an error message.
async ({ contractAddress, tokenId, address, network = "ethereum" }) => { try { const balance = await services.getERC1155Balance(contractAddress as Address, address as Address, BigInt(tokenId), network); return { content: [{ type: "text", text: JSON.stringify({ network, contract: contractAddress, tokenId, owner: address, balance: balance.toString() }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error fetching ERC1155 balance: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } - src/core/tools.ts:1180-1185 (schema)Zod input schema defining parameters for the get_erc1155_balance tool: contractAddress, tokenId, address, and optional network.
inputSchema: { contractAddress: z.string().describe("The ERC1155 contract address"), tokenId: z.string().describe("The token ID"), address: z.string().describe("The owner address or ENS name"), network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.") }, - src/core/tools.ts:1176-1216 (registration)Registration of the get_erc1155_balance tool with the server, including description, input schema, annotations, and handler function.
server.registerTool( "get_erc1155_balance", { description: "Get ERC1155 token balance for an address", inputSchema: { contractAddress: z.string().describe("The ERC1155 contract address"), tokenId: z.string().describe("The token ID"), address: z.string().describe("The owner address or ENS name"), network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.") }, annotations: { title: "Get ERC1155 Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } }, async ({ contractAddress, tokenId, address, network = "ethereum" }) => { try { const balance = await services.getERC1155Balance(contractAddress as Address, address as Address, BigInt(tokenId), network); return { content: [{ type: "text", text: JSON.stringify({ network, contract: contractAddress, tokenId, owner: address, balance: balance.toString() }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error fetching ERC1155 balance: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } ); - src/core/services/balance.ts:203-219 (helper)Helper function implementing the core logic for fetching ERC1155 token balance using readContract and ERC1155 ABI, supporting ENS resolution.
export async function getERC1155Balance( tokenAddressOrEns: string, ownerAddressOrEns: string, tokenId: bigint, network = 'ethereum' ): Promise<bigint> { // Resolve ENS names to addresses if needed const tokenAddress = await resolveAddress(tokenAddressOrEns, network); const ownerAddress = await resolveAddress(ownerAddressOrEns, network); return readContract({ address: tokenAddress, abi: erc1155Abi, functionName: 'balanceOf', args: [ownerAddress, tokenId] }, network) as Promise<bigint>; }