# ERC-20 Token Info API
> Live ERC-20 token metadata, read straight off the blockchain. Give it any token contract address and it returns the token's name, symbol, decimals and total supply — both as the raw on-chain integer and as a human-formatted number — by calling the ERC-20 contract directly via the chain's public JSON-RPC node (eth_call), confirming first that the address is really a contract. The USD Coin contract resolves to "USD Coin", symbol USDC, 6 decimals; Wrapped BTC on Polygon to "(PoS) Wrapped BTC", symbol WBTC, 8 decimals. The balance endpoint reads any wallet's holding of any token — pass the token contract and an owner address and it returns the balance raw and formatted with the token's own decimals and symbol. It works across seven EVM chains — Ethereum, Polygon, BNB Smart Chain, Arbitrum, Optimism, Base and Avalanche — with friendly aliases (eth, matic, bnb, arb, op, avax). This is the token-metadata and token-balance layer every wallet, DEX, portfolio tracker, block explorer and DeFi dashboard needs: turn a bare 0x… contract into a named, decimalled token, and resolve any holder's balance, in one call. Read live from the chain, no key on the data source, nothing cached. Distinct from native-coin balance and market-price APIs — this is on-chain ERC-20 contract data read directly from the blockchain. 4 endpoints across 7 chains.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tokeninfo-api/..."
```

## Pricing
- **Free** (Free) — 8,000 calls/Mo, 3 req/s
- **Starter** ($13/Mo) — 100,000 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 520,000 calls/Mo, 15 req/s
- **Scale** ($72/Mo) — 2,600,000 calls/Mo, 30 req/s

## Endpoints

### Token

#### `GET /v1/balance` — Wallet token balance

**Parameters:**
- `token` (query, required, string) — Token contract address (0x…) Example: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- `owner` (query, required, string) — Wallet address (0x…) Example: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`
- `chain` (query, optional, string) — Chain (default ethereum) Example: `ethereum`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokeninfo-api/v1/balance?token=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&owner=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum"
```

**Response:**
```json
{
    "data": {
        "chain": "ethereum",
        "owner": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "symbol": "USDC",
        "balance": "31.127137",
        "decimals": 6,
        "balance_raw": "31127137"
    },
    "meta": {
        "timestamp": "2026-06-09T03:01:59.364Z",
        "request_id": "33d82ed9-f22d-4c7e-960b-8d9cb0b81598"
    },
    "status": "ok",
    "message": "Balance retrieved successfully",
    "success": true
}
```

#### `GET /v1/token` — ERC-20 token metadata

**Parameters:**
- `address` (query, required, string) — Token contract address (0x…) Example: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- `chain` (query, optional, string) — Chain (default ethereum) Example: `ethereum`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokeninfo-api/v1/token?address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&chain=ethereum"
```

**Response:**
```json
{
    "data": {
        "name": "USD Coin",
        "chain": "ethereum",
        "symbol": "USDC",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "decimals": 6,
        "explorer": "https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "is_contract": true,
        "total_supply": "52157174570.131874",
        "total_supply_raw": "52157174570131874"
    },
    "meta": {
        "timestamp": "2026-06-09T03:01:59.519Z",
        "request_id": "11a1aa7a-6d4e-40cc-b7de-2557d988e112"
    },
    "status": "ok",
    "message": "Token retrieved successfully",
    "success": true
}
```

### Reference

#### `GET /v1/chains` — Supported chains

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokeninfo-api/v1/chains"
```

**Response:**
```json
{
    "data": {
        "count": 7,
        "chains": [
            {
                "key": "ethereum",
                "name": "Ethereum"
            },
            {
                "key": "polygon",
                "name": "Polygon"
            },
            {
                "key": "bsc",
                "name": "BNB Smart Chain"
            },
            {
                "key": "arbitrum",
                "name": "Arbitrum One"
            },
            {
                "key": "optimism",
                "name": "Optimism"
            },
            {
                "key": "base",
                "name": "Base"
            },
            {
                "key": "avalanche",
                "name": "Avalanche C-Chain"
            }
        ],
        "aliases": {
            "op": "optimism",
            "arb": "arbitrum",
            "bnb": "bsc",
            "eth": "ethereum",
            "pol": "polygon",
            "avax": "avalanche",
            "matic": "polygon",
            "binance": "bsc"
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:01:59.600Z",
        "request_id": "8f0d2f48-e14e-447f-8d60-9d411750e885"
    },
    "status": "ok",
    "message": "Chains retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokeninfo-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "chains": [
            "ethereum",
            "polygon",
            "bsc",
            "arbitrum",
            "optimism",
            "base",
            "avalanche"
        ],
        "source": "Public chain RPC (publicnode) eth_call ERC-20 interface (live)",
        "service": "tokeninfo-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/token": "ERC-20 metadata: name, symbol, decimals, total supply (address=0x…token, chain=ethereum).",
            "GET /v1/chains": "Supported chains and aliases.",
            "GET /v1/balance": "A wallet's token balance (token=0x…, owner=0x…, chain=)."
        },
        "description": "Live ERC-20 token metadata read on-chain via eth_call: for any token contract address, its name, symbol, decimals and total supply (raw and formatted), plus any wallet's token balance. Across Ethereum, Polygon, BSC, Arbitrum, Optimism, Base and Avalanche. Live, no key. Distinct from native-balance and market-price APIs — this is on-chain ERC-20 contract data read directly from the blockchain.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:01:59.713Z",
        "request_id": "eb7a474e-5c98-4af9-a7b2-e95627acd9da"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/tokeninfo-api
OpenAPI spec: https://www.oanor.com/api/tokeninfo-api/openapi.json