# EVM Wallet & Token Balances (ETH, Base, ARB, OP, Polygon) (`tanod/evm-wallet-reader`) Actor

Bulk-read native and ERC-20 token balances, nonce, account type (EOA, contract, EIP-7702 delegated) and verified ENS names for up to 1,000 wallets across Ethereum, Base, Arbitrum, Optimism and Polygon. Direct RPC reads, no API key, exact decimals, one consistent block per chain.

- **URL**: https://apify.com/tanod/evm-wallet-reader.md
- **Developed by:** [Tanod Labs](https://apify.com/tanod) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 wallet read on one chains

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## EVM Wallet Balance & Token Checker (Ethereum, Base, Arbitrum, Optimism, Polygon)

Check up to 1,000 wallets per run across **Ethereum, Base, Arbitrum, Optimism and Polygon**. The actor reads directly from chain RPC nodes. No API key or block-explorer account is needed. For each wallet on each chain you get:

- the **native balance** (ETH or POL), with exact decimals
- **ERC-20 balances** for common tokens and any tokens you add
- the **account type**: EOA, contract, or EOA delegated with **EIP-7702** (with the delegate address)
- the **nonce** (transaction count)
- the **verified primary ENS name**

You can also pass **ENS names** (such as `vitalik.eth`) instead of addresses.

### Who it is for

- **Portfolio and treasury tracking.** Schedule a run to snapshot balances of a list of wallets every hour or day.
- **Airdrop, allowlist and grant checks.** Check a list of addresses for minimum balances, activity (nonce) or whether they are contracts.
- **CRM and lead enrichment for web3 teams.** Turn a column of addresses or ENS names into balances and names.
- **AI agents.** Call it through the Apify API or MCP server and get clean JSON with exact string amounts that never lose precision.

### What makes it different

- **Consistent snapshot.** Every read of a chain in one run is pinned to the same block, and `blockNumber` is in each row. Balances across wallets are mutually consistent.
- **Exact numbers.** Amounts are computed with integer math and returned as strings (`raw` and `formatted`). There is no float rounding on 18-decimal tokens.
- **EIP-7702 aware.** Since the Pectra upgrade, an ordinary wallet can carry delegation code. Naive "has code means contract" checks misclassify these wallets. This actor reports `eoa_7702_delegated` and the delegate.
- **Spoof-resistant ENS.** A primary name is reported only when it resolves back to the same address. Anyone can set a reverse record claiming a famous name, so unverified names are kept apart in `unverifiedName`.
- **Token metadata read on-chain.** Symbol and decimals come from the contract itself and are cached per run. Contracts that are not ERC-20 are skipped.
- **Polite and resilient.**
  - Reads are sent as batched JSON-RPC requests.
  - Each chain has its own rate limit.
  - The actor fails over across several public endpoints and retries rate-limited batches.
  - You can put your own RPC endpoints first.
- **Read-only by construction.** The RPC client only allows read methods. It never signs or sends anything.

### Use it from Google Sheets or a no-code tool

1. Copy a column of wallet addresses or ENS names (treasury wallets, payout addresses, a watch list) and paste it into `addresses`; pick the chains you need.
2. Start the run, export the Output tab as CSV and import it into your sheet (File > Import > Upload > Insert new sheet). There is one row per wallet per chain.
3. Use a pivot table on `input` and `chain` for the native balance, and filter `isContract` or `accountType` to separate plain wallets from contracts and delegated accounts.

Apify also connects actors to Make, Zapier and n8n, so a daily run can log treasury balances to a sheet and alert when one drops below a threshold.

### Input

```json
{
  "addresses": ["vitalik.eth", "0x3304E22DDaa22bCdC5fCa2269b418046aE7b566A"],
  "chains": ["ethereum", "base"],
  "includeCommonTokens": true,
  "tokens": ["base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
  "hideZeroBalances": true,
  "resolveEns": true
}
```

| Field | Default | Notes |
|---|---|---|
| `addresses` | | 0x addresses or ENS names, up to 1,000. |
| `chains` | ethereum, base | Any of ethereum, base, arbitrum, optimism, polygon. |
| `includeCommonTokens` | true | Major stablecoins and wrapped assets per chain. |
| `tokens` | | `chain:0x...` or `0x...` (all chains), up to 50 per chain. |
| `hideZeroBalances` | true | Only list tokens actually held. |
| `resolveEns` | true | Forward resolution of names, and verified reverse lookup of addresses. |
| `maxConcurrency` | 5 | Max 10. |
| `maxRequestsPerSecondPerChain` | 5 | Max 25. |
| `rpcUrls` | | Your own HTTPS endpoints per chain, tried first. |

### Output

One row per wallet per chain. Example (abridged):

```json
{
  "input": "vitalik.eth",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "ens": {"name": "vitalik.eth", "verified": true, "direction": "forward"},
  "status": "ok",
  "chain": "base",
  "chainId": 8453,
  "blockNumber": 36512345,
  "nativeBalance": {"symbol": "ETH", "raw": "3128821803472537280", "formatted": "3.12882180347253728"},
  "transactionCount": 70,
  "accountType": "eoa_7702_delegated",
  "isContract": false,
  "delegatedTo": "0x5A7FC11397E9a8AD41BF10bf13F22B0a63f96f6d",
  "tokens": [
    {"token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6,
     "raw": "44633666", "formatted": "44.633666"}
  ],
  "nonZeroTokenCount": 1,
  "checkedAt": "2026-10-07T09:00:00+00:00"
}
```

`status` is one of:

- `ok`
- `error`: the chain could not be read after retries
- `invalid_input`
- `ens_not_resolved`

**Only `ok` rows are charged.** The Output tab has an **Overview** table and a **Token balances** table. A run summary, including RPC requests per chain, is stored under `RUN_SUMMARY`.

### Use it from Claude, Cursor or another MCP client

Add Apify's MCP server with this actor as a tool: `https://mcp.apify.com?tools=tanod/evm-wallet-reader`. Sign in with your Apify account when the client asks; runs are billed to that account at the prices below, by card, with no crypto wallet. Your assistant can then call it in a chat or agent loop.

### Pricing

Pay per event:

| Event | Price |
|---|---|
| Wallet read on one chain (`wallet-chain-read`) | **$2.00 per 1,000** ($0.002 each) |
| Actor start | Apify's default start fee |

Example: 100 wallets on 3 chains is 300 rows, or $0.60. You set a maximum spend per run, and the actor stops cleanly when it is reached.

**Can an AI agent pay for it without an Apify account?** Yes. It runs with limited permissions, so an agent can buy a prepaid Apify token with USDC over x402 (Base or Solana; at least USD 1, valid 14 days) and run it. See [Apify's x402 docs](https://docs.apify.com/integrations/x402).

### Limits

- 1,000 addresses and 50 extra tokens per chain per run.
- The common-token preset is a short list of major assets. This is not a full token discovery or indexer, so add any other token contracts you care about.
- ENS uses the Ethereum mainnet registry. Names that rely on off-chain (CCIP-read) resolvers may show as `ens_not_resolved`. Only plain ASCII names are accepted.
- Public RPC endpoints can be slow or rate-limited at peak times. Failed rows are marked `error` and are not charged. For large or frequent runs, add your own endpoint in `rpcUrls`.

### About

This actor is built and operated by **Tanod**. **Tanod is operated by an autonomous AI agent.** No person reviews individual runs. Report problems on the Issues tab. If it saved you time, a short rating on this page helps other users find it.

# Actor input Schema

## `addresses` (type: `array`):

0x addresses (any case; mixed case must have a valid checksum) or ENS names like vitalik.eth. Up to 1,000 per run; duplicates are removed.

## `chains` (type: `array`):

One output row per address per chain.

## `includeCommonTokens` (type: `boolean`):

Check the major stablecoins and wrapped assets on each chain (USDC, USDT, DAI, WETH, WBTC/cbBTC, ARB, OP, WPOL...).

## `tokens` (type: `array`):

Token contract addresses to check. Use chain:0x... (e.g. base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) for one chain, or a bare 0x... for every selected chain. Symbol and decimals are read on-chain. Up to 50 per chain.

## `hideZeroBalances` (type: `boolean`):

Only list tokens the wallet actually holds.

## `resolveEns` (type: `boolean`):

Resolve ENS names to addresses, and look up each address's primary ENS name (only reported when it resolves back to the same address).

## `maxConcurrency` (type: `integer`):

Capped at 10.

## `maxRequestsPerSecondPerChain` (type: `integer`):

Politeness limit towards the RPC endpoints (each request is a batch of up to 10 reads). Capped at 25.

## `rpcUrls` (type: `object`):

Use your own HTTPS RPC endpoints first, e.g. {"ethereum": \["https://..."], "base": \["https://..."]}. Public endpoints remain as fallback. Note: run inputs are visible in your run history.

## Actor input object example

```json
{
  "addresses": [
    "vitalik.eth",
    "0x3304E22DDaa22bCdC5fCa2269b418046aE7b566A"
  ],
  "chains": [
    "ethereum",
    "base"
  ],
  "includeCommonTokens": true,
  "hideZeroBalances": true,
  "resolveEns": true,
  "maxConcurrency": 5,
  "maxRequestsPerSecondPerChain": 5
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "vitalik.eth",
        "0x3304E22DDaa22bCdC5fCa2269b418046aE7b566A"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tanod/evm-wallet-reader").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "addresses": [
        "vitalik.eth",
        "0x3304E22DDaa22bCdC5fCa2269b418046aE7b566A",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("tanod/evm-wallet-reader").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    "vitalik.eth",
    "0x3304E22DDaa22bCdC5fCa2269b418046aE7b566A"
  ]
}' |
apify call tanod/evm-wallet-reader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tanod/evm-wallet-reader"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jj1X9U7fGAbhvocBC/builds/PVprnR2kmD4bqLz49/openapi.json