{"uid":"cap_-XzpUp_kY3wSU_JuZ3RDu","slug":"erc-1155-token-balance-lookup-8d3d0a4c","name":"ERC-1155 Token Balance Lookup","description":"How many of one ERC-1155 token id an account holds, read straight from the contract. ERC-1155 is the multi-token standard behind most game items, editions and passes, where a single contract holds many ids and a balance is a quantity rather than ownership of one thing. Returns the balance as a decimal string. EVM chains: ethereum, base, polygon, arbitrum, optimism.","url":"https://agent402.tools/api/chain/erc1155-balance","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["contract","address","tokenId"],"properties":{"address":{"type":"string","description":"0x holder address"},"network":{"type":"string","description":"ethereum | base | polygon | arbitrum | optimism (default base)"},"tokenId":{"type":"string","description":"Token id, decimal or 0x hex"},"contract":{"type":"string","description":"0x ERC-1155 contract address"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["contract","address","tokenId","network","balance"],"properties":{"address":{"type":"string"},"balance":{"type":"string"},"network":{"type":"string"},"tokenId":{"type":"string"},"contract":{"type":"string"}}}}}}},"responseSchema":{"type":"json","example":{"address":"0xabf4fabd7c416fb67202e5f9002389fc75e2a9d0","balance":"0","network":"polygon","tokenId":"1","contract":"0x2953399124f0cbb46d2cbacd8a89cf0599974963"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.002","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.002/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_WTts5GICBRf95_ThDhnNJ","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.002","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the balance (quantity) of a specific ERC-1155 token ID held by a given wallet address on a specified EVM chain","exampleAgentPrompt":"How many of token ID 42 does the wallet 0xabf4fabd7c416fb67202e5f9002389fc75e2a9d0 hold in the ERC-1155 contract 0x2953399124f0cbb46d2cbacd8a89cf0599974963 on Polygon?","exampleUseCases":[{"title":"Game item ownership verification","prompt":"Check how many of token ID 7 the wallet 0x1234567890abcdef1234567890abcdef12345678 holds in the game items contract 0xabc123def456abc123def456abc123def456abc1 on Arbitrum — I need to confirm they have enough to enter the tournament."},{"title":"NFT edition pass gating","prompt":"Does the address 0xabf4fabd7c416fb67202e5f9002389fc75e2a9d0 hold any of token ID 1 from the membership pass contract 0x2953399124f0cbb46d2cbacd8a89cf0599974963 on Polygon? I want to gate access to a community channel."},{"title":"On-chain portfolio audit","prompt":"What's the balance of token ID 100 in the ERC-1155 contract 0xdef456abc123def456abc123def456abc123def4 for wallet 0x9876543210fedcba9876543210fedcba98765432 on Base?"}],"resultDescription":"Returns a JSON object containing the wallet address, ERC-1155 contract address, token ID, network name, and the token balance as a decimal string (e.g. '5' meaning the address holds 5 units of that token ID)","failureModes":["Invalid contract address returns an error or zero balance","Contract address is not an ERC-1155 contract — call may fail or return unexpected data","Invalid wallet address format returns a validation error","Unsupported network name returns an error","Token ID not found in contract returns balance of '0'","Rate limiting or payment failure results in HTTP 402 response"],"whenToPreferThis":"Use this endpoint when you need to query the quantity of a specific ERC-1155 multi-token ID held by a wallet on Ethereum, Base, Polygon, Arbitrum, or Optimism. Prefer this over ERC-721 balance checks when the token standard is ERC-1155 (multi-token, where balances are quantities not single ownership). Ideal for game item gating, edition pass verification, or any scenario requiring knowledge of how many units of a specific token ID a wallet holds.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T06:45:00.361Z","isFirstParty":false}