# ERC Detector API
> Tell what kind of contract an address actually is — live, by asking the chain itself. It probes the contract over the public JSON-RPC (eth_call, no key): an ERC-165 interface sweep (ERC-721, ERC-1155 and their metadata/enumerable/royalty extensions) plus an ERC-20 function probe (name, symbol, decimals, totalSupply), and classifies the address as an ERC-20 token, an NFT (ERC-721), a multi-token (ERC-1155), a plain contract or an externally-owned account. A dedicated endpoint returns a token's live on-chain ERC-20 metadata — working for ANY token, including brand-new ones no token list has yet indexed. The "what is this address" primitive every wallet, explorer, scanner and security tool needs, across Ethereum, Base, Arbitrum, Optimism, BNB, Polygon and more. Reads straight from the chain; live, short cache only.

## 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/ercdetector-api/..."
```

## Pricing
- **Free** (Free) — 5,800 calls/Mo, 3 req/s
- **Starter** ($10/Mo) — 125,000 calls/Mo, 8 req/s
- **Pro** ($37/Mo) — 760,000 calls/Mo, 20 req/s
- **Business** ($108/Mo) — 4,900,000 calls/Mo, 50 req/s

## Endpoints

### Detect

#### `GET /v1/detect` — Classify an address: ERC-20 / ERC-721 / ERC-1155 / contract / EOA

**Parameters:**
- `address` (query, required, string) — Contract or wallet address (0x + 40 hex) Example: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- `chain` (query, optional, string) — Chain name or id (ethereum, base, arbitrum, optimism, bsc, polygon...) Example: `ethereum`

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

**Response:**
```json
{
    "data": {
        "note": "Classification from a live ERC-165 interface sweep plus an ERC-20 function probe via eth_call. erc20 holds the token metadata when the address behaves like an ERC-20.",
        "type": "ERC-20 (token)",
        "chain": "ethereum",
        "erc20": {
            "name": "USD Coin",
            "symbol": "USDC",
            "decimals": 6,
            "total_supply": "51367842183271264"
        },
        "erc165": false,
        "source": "public JSON-RPC (publicnode)",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "standards": [
            "ERC-20"
        ],
        "interfaces": [],
        "is_contract": true
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:10.808Z",
        "request_id": "c973555b-20f6-4eae-947d-f225549a8a7f"
    },
    "status": "ok",
    "message": "Contract type detected successfully",
    "success": true
}
```

#### `GET /v1/erc20` — Live on-chain ERC-20 metadata for any token

**Parameters:**
- `address` (query, required, string) — Token contract address (0x + 40 hex) Example: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- `chain` (query, optional, string) — Chain name or id Example: `ethereum`

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

**Response:**
```json
{
    "data": {
        "name": "USD Coin",
        "note": "Live on-chain ERC-20 metadata read via eth_call (name/symbol/decimals/totalSupply). Works for any token, including ones no token list has indexed. total_supply is the raw integer — divide by decimals.",
        "chain": "ethereum",
        "source": "public JSON-RPC (publicnode)",
        "symbol": "USDC",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "decimals": 6,
        "total_supply": "51367842183271264"
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:10.896Z",
        "request_id": "0913d88c-2b58-484d-bfea-c4c2bf91b291"
    },
    "status": "ok",
    "message": "ERC-20 metadata retrieved successfully",
    "success": true
}
```

### Reference

#### `GET /v1/interfaces` — Known ERC-165 interface ids and ERC-20 selectors checked

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

**Response:**
```json
{
    "data": {
        "note": "Known ERC-165 interface ids checked by /v1/detect, plus the ERC-20 function selectors probed.",
        "count": 9,
        "source": "static reference",
        "interfaces": [
            {
                "name": "ERC-165",
                "interface_id": "0x01ffc9a7"
            },
            {
                "name": "ERC-721",
                "interface_id": "0x80ac58cd"
            },
            {
                "name": "ERC-721 Metadata",
                "interface_id": "0x5b5e139f"
            },
            {
                "name": "ERC-721 Enumerable",
                "interface_id": "0x780e9d63"
            },
            {
                "name": "ERC-721 Receiver",
                "interface_id": "0x150b7a02"
            },
            {
                "name": "ERC-4906 (Metadata Update)",
                "interface_id": "0x49064906"
            },
            {
                "name": "ERC-1155",
                "interface_id": "0xd9b67a26"
            },
            {
                "name": "ERC-1155 Metadata URI",
                "interface_id": "0x0e89341c"
            },
            {
                "name": "ERC-2981 (Royalties)",
                "interface_id": "0x2a55205a"
            }
        ],
        "erc20_selectors": {
            "name": "0x06fdde03",
            "symbol": "0x95d89b41",
            "decimals": "0x313ce567",
            "totalSupply": "0x18160ddd"
        }
    },
    "meta": {
        "times
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata, supported chains & live sample

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

**Response:**
```json
{
    "data": {
        "chains": [
            "ethereum",
            "base",
            "arbitrum",
            "optimism",
            "bsc",
            "polygon",
            "avalanche",
            "gnosis",
            "fantom",
            "linea",
            "scroll",
            "blast"
        ],
        "sample": {
            "type": "ERC-20 (token)",
            "chain": "ethereum",
            "symbol": "USDC"
        },
        "source": "public JSON-RPC nodes (publicnode.com) via eth_call / eth_getCode; decoding computed locally",
        "service": "ercdetector-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/erc20": "Live ERC-20 metadata (name/symbol/decimals/totalSupply) for any token (chain, address).",
            "GET /v1/detect": "Classify an address: ERC-20 / ERC-721 / ERC-1155 / contract / EOA (chain, address).",
            "GET /v1/interfaces": "Known ERC-165 interface ids and ERC-20 selectors checked."
        },
        "description": "Detect what kind of contract an address is — ERC-20 token, ERC-721 NFT, ERC-1155 multi-token or plain contract — live, by probing it over eth_call (ERC-165 interface sweep + ERC-20 function probe). A dedicated endpoint returns live on-chain ERC-20 metadata for any token. The 'what is this address' primitive for wallets, scanners and security tooling. Live, short cache only.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-14T
…(truncated, see openapi.json for full schema)
```


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