BaseLens / Guides

Base wallet balance API: ETH, tokens and account type

Agents often need a quick picture of an address on Base: how much ETH, which common tokens and whether it is a wallet or a contract.

The problem

A balance lookup needs several JSON-RPC calls (eth_getBalance, one balanceOf per token, eth_getCode, eth_getTransactionCount) and then decimal formatting for each token. Telling an ordinary wallet from a contract, or from an account that has delegated to code under EIP-7702, takes a look at the account's code.

How /wallet answers it

GET /wallet?address=0x... batches those calls and returns ethBalance as a decimal string, the nonce (the number of transactions sent), a type of EOA, EOA (EIP-7702 delegated) or contract, and balances for USDC, USDbC, WETH, cbBTC, cbETH, DAI, EURC and AERO. Only non-zero balances are listed in tokenBalances; tokensChecked tells you which tokens were looked at. Values are already divided by each token's decimals.

Request and response

Example using the WETH contract address as a stand-in.

$ curl -i "https://baselens.imac2014ville.workers.dev/wallet?address=0x4200000000000000000000000000000000000006"
HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi4uLn0=   # base64 JSON: scheme "exact", network eip155:8453,
                                                  # asset USDC, amount 5000 (= $0.005)
# An x402 client signs the payment, then retries with a PAYMENT-SIGNATURE header.

The paid response (balances change constantly; sample abridged):

{
  "address": "0x4200000000000000000000000000000000000006",
  "network": "base",
  "ethBalance": "274905.48019398954712961",
  "nonce": 0,
  "type": "contract",
  "tokenBalances": { "USDC": "167.551481", "WETH": "1.860275962927391218", "cbBTC": "0.01885231" },
  "tokensChecked": ["USDC","USDbC","WETH","cbBTC","cbETH","DAI","EURC","AERO"]
}

JavaScript with @x402/fetch

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.PRIVATE_KEY); // wallet holding USDC on Base
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(signer) }],
});
const res = await pay("https://baselens.imac2014ville.workers.dev/wallet?address=" + address);
const w = await res.json();
console.log(w.type, w.ethBalance, w.tokenBalances.USDC ?? "0");

Pricing

/wallet costs $0.005 per call. There is no API key and no account: each request is paid in USDC on Base over x402. Malformed input returns 400 and failed lookups return a non-2xx status, so those are not charged.

Limitations

More guides

BaseLens overview/openapi.jsonllms.txt

Sister services