# ERC-20 Token Metadata Lookup

> ERC-20 Token Metadata Lookup is a paid API for AI agents from x402-micro-pay.com, paid per call via x402, $0.002/call, status unknown (last checked 2026-11-20).

Fetches on-chain metadata for an ERC-20 token contract (name, symbol, decimals, total supply, and optional holder balance) on Base or Ethereum.

## Facts

- Endpoint: POST https://x402-micro-pay.com/api/skills/erc20-meta?utm_source=zero.xyz
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-20
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/erc-20-token-metadata-lookup-68705d7e
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_tLSZSeZeyWW9tUm1zH-Db

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-metadata-lookup-68705d7e -d '<json body>'
```

Example prompt: What are the name, symbol, decimals, and total supply of the ERC-20 token at contract address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 on Base?

## When to prefer this

Use this endpoint when you need authoritative on-chain ERC-20 metadata (name, symbol, decimals, supply) directly from the blockchain rather than from a centralized token registry or price feed. Ideal for validating unknown contract addresses, enriching token data pipelines, or checking a wallet's token balance — especially when no API key or account setup is acceptable and pay-per-call USDC billing via x402 on Base is preferred.

## Known failure modes

- Invalid contract address format (must be 0x-prefixed 40-hex-char) returns validation error
- Address is an EOA (externally owned account), not an ERC-20 contract — is_contract=false, token fields may be null
- Unsupported chain value other than 'base' or 'ethereum' returns schema validation error
- No payment sent — server returns HTTP 402 requiring USDC payment on Base via x402
- Network RPC timeout or block reorg causes stale or missing block data
- Holder address provided but has zero balance — holder_balance returns 0 not null

## How this service works

41 pay-per-call JSON APIs for AI agents. No account or API key: an unpaid POST returns HTTP 402, pay in USDC on Base with x402 v2, retry. Prices from $0.001 per call.

## Output

Returns a JSON object with token name, symbol, decimals, total supply (raw and formatted), holder balance if requested (raw and formatted), chain ID, block number at which data was fetched, whether the address is a contract, data freshness timestamps, confidence score, source attribution (e.g. Basescan), and suggested next skills to call (e.g. token_price, token_risk).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "chain": {
   "enum": [
    "base",
    "ethereum"
   ],
   "type": "string",
   "default": "base"
  },
  "token": {
   "type": "string",
   "pattern": "^0x[0-9a-fA-F]{40}$",
   "description": "ERC-20 contract address"
  },
  "holder": {
   "type": "string",
   "pattern": "^0x[0-9a-fA-F]{40}$",
   "description": "Optional holder for balanceOf"
  },
  "request_id": {
   "type": "string",
   "pattern": "^[A-Za-z0-9._:-]+$",
   "maxLength": 64,
   "minLength": 1,
   "description": "Optional idempotency key. Echoed back; a credit-pack redemption with the same request_id and body is charged once."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "ok": true,
  "data": {
   "name": "USD Coin",
   "block": 22000000,
   "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
   "symbol": "USDC",
   "chain_id": 8453,
   "decimals": 6,
   "is_contract": true,
   "total_supply": "1000000000000000",
   "holder_balance": null,
   "total_supply_fmt": "1000000000",
   "holder_balance_fmt": null
  },
  "next": [
   "token_price",
   "token_risk"
  ],
  "skill": "erc20_meta",
  "charged": true,
  "service": "erc20_meta",
  "sources": [
   {
    "url": "https://basescan.org/address/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "name": "base eth_call/multicall3",
    "block": 22000000,
    "fetched_at": "2026-10-24T14:00:00Z"
   }
  ],
  "summary": "USDC decimals=6 supply=…",
  "version": "1.0.0",
  "warnings": [],
  "confidence": 0.95,
  "data_as_of": "2026-10-24T14:00:00Z",
  "generated_at": "2026-10-24T14:00:00Z"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/erc-20-token-metadata-lookup-68705d7e/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402-micro-pay.com](https://www.zero.xyz/host/x402-micro-pay.com/llms.txt)
