{"uid":"cap_RWpwJ_-w_2mndYEA6IdoZ","slug":"erc-20-token-total-supply-on-chain-lookup-b3542c08","name":"ERC-20 Token Total Supply On-Chain Lookup","description":"The circulating total supply of an ERC-20, read from the token contract itself rather than from an aggregator, so it is the number the chain holds at the block you asked for. Returns the raw uint256 and the same figure formatted with the token's own decimals. A contract that does not implement totalSupply answers 422 rather than a fabricated zero. EVM chains: ethereum, base, polygon, arbitrum, optimism.","url":"https://agent402.tools/api/chain/total-supply","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"],"properties":{"network":{"type":"string","description":"ethereum | base | polygon | arbitrum | optimism (default base)"},"contract":{"type":"string","description":"0x ERC-20 token contract address"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["contract","network","totalSupply","decimals","totalSupplyFormatted"],"properties":{"network":{"type":"string"},"contract":{"type":"string"},"decimals":{"type":"integer"},"totalSupply":{"type":"string"},"totalSupplyFormatted":{"type":"string"}}}}}}},"responseSchema":{"type":"json","example":{"network":"base","contract":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","decimals":6,"totalSupply":"4182993441205067","totalSupplyFormatted":"4182993441.205067"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.001","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.001/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.001","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.001","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_mvKLDsGtzBWZm5dfmXZoz","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.001","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the on-chain total supply of an ERC-20 token contract, in both raw uint256 and human-readable formatted form, for a specified EVM network.","exampleAgentPrompt":"What is the current total supply of the USDC token at contract 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 on Base — give me both the raw number and the human-readable formatted amount with its decimals?","exampleUseCases":[{"title":"DeFi token supply audit","prompt":"Can you pull the on-chain total supply for the token at contract 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 on Ethereum and give me the formatted number with decimals? I want to verify it against what CoinGecko shows."},{"title":"Stablecoin circulation tracker","prompt":"What's the current total supply of USDC at 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 on Base, directly from the contract — both raw and formatted?"},{"title":"Multi-chain token supply comparison","prompt":"Check the total supply of the token at contract 0x4200000000000000000000000000000000000042 on Optimism and tell me the formatted supply using the token's own decimals."}],"resultDescription":"A JSON object containing the network name, contract address, token decimals, raw total supply as a uint256 string (e.g. '4182993441205067'), and a formatted total supply string with the token's own decimal precision applied (e.g. '4182993441.205067'). Returns a 422 error if the contract does not implement totalSupply.","failureModes":["422 returned when contract address does not implement the ERC-20 totalSupply function","Invalid or malformed contract address causes an error response","Unsupported network name results in an error","Contract address on wrong network returns unexpected or empty data","Transient RPC node issues may cause intermittent lookup failures"],"whenToPreferThis":"Use this endpoint when you need the authoritative on-chain total supply figure for an ERC-20 token, read directly from the contract rather than from a third-party aggregator or indexer. It is ideal when accuracy at a specific block is important, when aggregator data may be stale or incorrect, or when auditing token supply figures. Supports five major EVM chains: Ethereum, Base, Polygon, Arbitrum, and Optimism.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T06:42:12.732Z","isFirstParty":false}