# ERC-20 Token Total Supply On-Chain Lookup

> ERC-20 Token Total Supply On-Chain Lookup is a paid API for AI agents from agent402.tools, paid per call via x402, $0.001/call, status unknown (last checked 2026-09-14).

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.

## Facts

- Endpoint: GET https://agent402.tools/api/chain/total-supply
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/erc-20-token-total-supply-on-chain-lookup-b3542c08
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_RWpwJ_-w_2mndYEA6IdoZ

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability erc-20-token-total-supply-on-chain-lookup-b3542c08
```

Example prompt: 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?

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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"
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "network": "base",
  "contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "decimals": 6,
  "totalSupply": "4182993441205067",
  "totalSupplyFormatted": "4182993441.205067"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/erc-20-token-total-supply-on-chain-lookup-b3542c08/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent402.tools](https://www.zero.xyz/host/agent402.tools/llms.txt)