Agent EVM State Batch

Product Guide · Read-Only EVM Data

One Request.
Up to 100 Chain Reads.

This API is built for customer software agents and bots. The agent supplies the wallet, token, contract, or block checks its task needs; this service reads live chain state and returns one result per submitted check. Each chain’s reads in a batch share one captured block snapshot.

From $0.05 USDCPer Request · Paid in Base Using x402

Where the Data Comes From

For each request, this service routes live JSON-RPC reads through dRPC public nodes and returns successful provider responses. It queries current chain state when your batch runs; it does not sell a precomputed archive. The free dRPC tier uses public nodes, which can be slower or less reliable than paid endpoints. The dRPC key stays server-side and is sent in the Drpc-Key authentication header.

Ethereumlb.drpc.live/ethereum (authenticated)
Baselb.drpc.live/base (authenticated)
Arbitrumlb.drpc.live/arbitrum (authenticated)
Optimismlb.drpc.live/optimism (authenticated)
Polygonlb.drpc.live/polygon (authenticated)

Data Quality: these are provider-reported chain reads, not cryptographic proofs. If an upstream read fails or is malformed, the batch fails as a whole; partial results are not delivered as a successful response.

Pick the Batch Size

Standard · Up to 25 Checks$0.05 USDC · maximum 25 · POST /v1/state-batch
Medium · Up to 50 Checks$0.10 USDC · maximum 50 · POST /v1/state-batch/50
Large · Up to 100 Checks$0.15 USDC · maximum 100 · POST /v1/state-batch/100

Each route has a fixed price for one batch: up to 25 checks costs $0.05, up to 50 costs $0.10, and up to 100 costs $0.15. The selected route sets the fixed price and maximum size. You can submit fewer checks, but the full tier price still applies; unused capacity does not carry forward. The calling agent chooses checks and target addresses/contracts; the service returns one result per submitted check and never adds filler. Each batch is one request and one payment.

  • Native token balance
  • ERC-20 token balance
  • ERC-20 allowance
  • Whether an address has contract code
  • Current block height
  • Bounded read-only eth_call

The endpoints accept up to 25, 50, or 100 checks across the five listed chains. The checkout page has guided builders for native wallet balances, ERC-20 balance watchlists, allowance watchlists, and contract deployment checks; each turns real wallet, token, spender, and contract targets into distinct reads without requiring JSON editing. Customers still choose the data relevant to their task—this service does not invent target addresses or add filler. The builder previews the check count and price before the free quote. API clients submit the same check objects directly and consume the returned JSON programmatically. Reads are capped, timed out, and pinned to a captured block. The endpoint rejects state-changing transaction methods.

Measure Marketplace Discovery

For browser referrals, link to the homepage or checkout with an allow-listed utm_source, such as https://evmstate.com/checkout.html?tier=50&utm_source=x402-list. API clients can send X-Discovery-Source: x402-list on both quote and paid requests. Supported labels include Agentic Market, x402 List, Market402, Agent402, x402scan, CDP Bazaar, x402dash, x402.new, SwarmBazaar, PayAPI, and 402.ad. Labels are caller-supplied analytics, not verified referrals; directory impressions and search rank are not visible to this service.

Start With a Useful Agent Task

Begin with the task the agent already needs to do. The wallet snapshot needs only one wallet address; token and allowance reads use the token and spender targets already present in the agent’s task or configuration. Each generated row is one check. Use the smallest route that fits.

Preset: Five-Chain Wallet Snapshot

const chains = ["ethereum", "base", "arbitrum", "optimism", "polygon"];
const walletChecks = chains.map((chain) => ({
  id: chain + "-native-balance",
  chain,
  type: "native_balance",
  address: walletAddress
}));

One wallet address creates five native-balance reads. This is ready for the $0.05 route, which supports up to 25 submitted checks.

Preset: Token Balance Watchlist

const tokenChecks = tokenTargets.map(({ chain, token }, index) => ({
  id: "token-balance-" + (index + 1),
  chain,
  type: "erc20_balance",
  token,
  owner: walletAddress
}));

For a complete request generator, run node examples/build-request.mjs from the repository with CHECK_PRESET=token-balances, WALLET_ADDRESS, and TOKEN_TARGETS_JSON set. The JSON must contain entries such as [{"chain":"base","token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}]. It prints the exact route, fixed price, fresh request ID, and checks; it does not sign or submit payment. The API returns raw ERC-20 values; use token decimals from trusted metadata to format units.

Preset: Token Allowance Watchlist

const allowanceChecks = allowanceTargets.map(({ chain, token, spender }, index) => ({
  id: "allowance-" + (index + 1),
  chain,
  type: "allowance",
  token,
  owner: walletAddress,
  spender
}));

Run node examples/build-request.mjs with CHECK_PRESET=allowances, WALLET_ADDRESS, and ALLOWANCE_TARGETS_JSON set to a JSON array of {"chain":"base","token":"0x…","spender":"0x…"} entries from the task. It prints a valid request and the least expensive tier that fits. This reads the allowance; it does not label a spender safe or unsafe, change an allowance, or move funds.

Connect Through Coinbase Bazaar MCP

Install the client packages, configure a dedicated agent wallet, search Bazaar for this service, and set BAZAAR_TOOL_NAME to the matching tool name returned by search. This example asks for approval in the terminal for each payment and rejects any network other than Base.

npm install @x402/mcp @x402/fetch @x402/evm viem @modelcontextprotocol/sdk
import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { createX402MCPClient } from "@x402/mcp";
import { x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const terminal = createInterface({ input: stdin, output: stdout });
const paymentClient = new x402Client();
const privateKey = process.env.X402_PRIVATE_KEY;
if (!privateKey) throw new Error("Set X402_PRIVATE_KEY in a secret manager or protected environment variable");
const signer = privateKeyToAccount(privateKey);
registerExactEvmScheme(paymentClient, { signer });

const mcp = new Client({ name: "evm-state-agent", version: "1.0.0" });
await mcp.connect(new StreamableHTTPClientTransport(new URL(
  "https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp"
)));
const client = createX402MCPClient(mcp, paymentClient, {
  autoPayment: true,
  onPaymentRequested: async (request) => {
    console.log("Payment requested: " + request.price + " on " + request.network);
    if (request.network !== "eip155:8453") return false;
    return (await terminal.question("Approve this payment? Type yes: ")).trim().toLowerCase() === "yes";
  }
});

const matches = await client.callTool("search_resources", {
  query: "multi-chain wallet balance snapshot"
});
console.dir(matches, { depth: null });
const toolName = process.env.BAZAAR_TOOL_NAME;
if (!toolName) throw new Error("Set BAZAAR_TOOL_NAME to the matching tool name from Bazaar search");
const walletAddress = process.env.WALLET_ADDRESS;
if (!walletAddress || !/^0x[0-9a-fA-F]{40}$/.test(walletAddress)) throw new Error("Set WALLET_ADDRESS to the wallet being checked");
const request = {
  requestId: crypto.randomUUID(),
  checks: ["ethereum", "base", "arbitrum", "optimism", "polygon"].map((chain) => ({
    id: chain + "-native-balance", chain, type: "native_balance", address: walletAddress
  }))
};
try {
  const result = await client.callTool("proxy_tool_call", { toolName, body: request });
  console.dir(result, { depth: null });
} catch (error) {
  const recovery = await fetch("https://evmstate.com/v1/results/" + request.requestId);
  if (recovery.ok) console.dir(await recovery.json(), { depth: null });
  else throw new Error("No confirmed result yet. Keep request ID " + request.requestId + " and recover it before considering another payment.", { cause: error });
} finally {
  terminal.close();
  await mcp.close();
}

Payment Safety: store X402_PRIVATE_KEY in a secret manager, use a dedicated wallet with only the approved balance, and keep the explicit approval prompt or replace it with a policy that enforces a per-call and daily limit. Never use a production wallet key in source code.

Result Freshness: each returned row includes its block number, and snapshotBlocks records the captured height for each chain. Reads on a chain use that same height. Heights are captured when the batch runs; the response does not include a capture timestamp. Compare a returned height with that chain’s current head if the task needs an age estimate. Results are provider-reported JSON-RPC responses, not cryptographic proofs.

Agent Workflow: Coinbase Bazaar exposes search_resources and proxy_tool_call; @x402/mcp handles payment-required and retry. Pass the discovered tool name and the complete request as body. The search result supplies the tool name; review its listed price and schema before enabling payment. See the Coinbase Bazaar MCP setup guide.

Payment and Delivery

  1. Send a valid request to the route for its maximum size. The service validates it and returns a free x402 quote; the quote contains no result data.
  2. Your wallet or agent reviews the selected route’s fixed Base USDC amount in the quote: 50,000 atomic units ($0.05) for up to 25 checks, 100,000 ($0.10) for up to 50, or 150,000 ($0.15) for up to 100. The amount stays the same if you submit fewer checks.
  3. After payment verification, the service runs the live reads, saves the exact response, and asks the facilitator to settle.
  4. Once settled, the response is available and can be recovered for 30 days using the same request ID.

Capacity or Service Error: the admission gate can return HTTP 503 with a retry delay before payment verification. That request is not settled. Keep the same request ID when retrying; if a payment outcome is unclear, recover first instead of paying again.

Turn Snapshots Into Change Reports

Run the same wallet, token, or allowance checks again and compare them with a prior paid receipt. The response reports which values changed and gives exact integer balance differences where safe. Your agent can schedule the next run and ask for approval each time.

  1. Complete a first snapshot and keep its private request ID.
  2. On a later run, use a new requestId, send the exact same checks, and add compareToRequestId with the earlier request ID.
  3. Review the free quote; the selected tier’s ordinary fixed price applies to this new batch. Approve each payment separately.
  4. Read comparison.changedCount, comparison.checks, and each result’s current value and block number. Store the new request ID as the baseline for the next run.
{
  "requestId": "52345678-1234-4234-9234-123456789abc",
  "compareToRequestId": "12345678-1234-4234-9234-123456789abc",
  "checks": [
    { "id": "base-wallet", "chain": "base", "type": "native_balance", "address": "0x…" }
  ]
}

Boundaries: the service does not run a background monitor or automatically charge a wallet. The agent/operator chooses its schedule and authorizes each run. Baselines are private bearer receipt IDs stored for 30 days; anyone with one can retrieve or compare against that receipt. A missing, expired, legacy, or mismatched baseline fails validation before a payment quote. Only compare check targets you intend to reuse. Results remain provider-reported RPC reads, not cryptographic proofs.

Developer Quick Start

Integrate once. Your agent builds the checks from its task; the x402 fetch client handles the free quote, payment signature, and retry, then your code reads the JSON result. The example makes one native-balance read on each of five EVM chains for $0.05. It expects walletAddress to come from your agent’s configured wallet or current task; it does not guess a wallet.

npm install @x402/fetch @x402/core @x402/evm viem
// save as agent.mjs; set X402_PRIVATE_KEY in your environment
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

const key = process.env.X402_PRIVATE_KEY;
if (!key) throw new Error("Set X402_PRIVATE_KEY first");
const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(key) });
const paidFetch = wrapFetchWithPayment(fetch, client);

const walletAddress = process.env.WALLET_ADDRESS;
if (!walletAddress || !/^0x[0-9a-fA-F]{40}$/.test(walletAddress)) throw new Error("Set WALLET_ADDRESS to the target public address");
const chains = ["ethereum", "base", "arbitrum", "optimism", "polygon"];
const walletChecks = chains.map((chain) => ({
  id: chain + "-native-balance", chain, type: "native_balance", address: walletAddress
}));

const requestId = crypto.randomUUID();
const response = await paidFetch("https://evmstate.com/v1/state-batch", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    requestId,
    checks: walletChecks
  })
});
let data;
if (response.ok) data = await response.json();
else {
  const recovered = await fetch("https://evmstate.com/v1/results/" + requestId);
  if (recovered.ok) data = await recovered.json();
  else throw new Error("Batch returned HTTP " + response.status + ". Retain requestId " + requestId + " and use the recovery URL before considering a retry.");
}
console.log(data);

Payment Safety: this client automatically signs and retries the quote. Use a dedicated agent wallet, keep only its approved spending balance there, and add your own per-call and daily limits. Never put a real key in source code or commit it.

To request more data, have the agent append the relevant distinct checks to checks. The API validates the full batch and returns the matching price before it is paid. The selected route has a fixed price even when the request contains fewer checks than its limit.

Request Shape

A customer agent sends a fresh UUIDv4 as requestId and one check object for each value it needs. For example, it can create a wallet-balance check using the address configured for its current task. The operator configures the agent; the agent calls this API and processes the JSON response.

{
  "requestId": "12345678-1234-4234-9234-123456789abc",
  "checks": [
    {
      "id": "wallet-balance",
      "chain": "base",
      "type": "native_balance",
      "address": "0x0000000000000000000000000000000000000000"
    },
    { "id": "base-height", "chain": "base", "type": "block_number" }
  ]
}

Response fields include the request ID, each check’s result and block number, the per-chain snapshot heights, and a recovery URL. Each result echoes its normalized check target so you can match the returned value to the wallet, token, and spender you actually requested. It keeps the exact provider response in value and adds an optional interpretation object where conversion is safe. Native balances include an exact decimal amount, native unit, decimal count, and base-unit string. For ERC-20 balances and allowances, the service reads the token’s decimals() and symbol() at the same block when those methods return usable values, then formats the amount alongside exact base units. Those values are reported by the token contract and are not independently verified; if metadata is missing or malformed, exact base units remain available. Block heights include a decimal form, contract-code reads include deployed status and byte length, and eth_call stays ABI-encoded with a decode note. The sample output is illustrative, not live wallet data. See the API Schema for required fields and validation limits.

Example Response for the Five-Chain Snapshot

{
  "requestId": "12345678-1234-4234-9234-123456789abc",
  "results": [
    { "id": "ethereum-native-balance", "chain": "ethereum", "type": "native_balance", "check": { "id": "ethereum-native-balance", "chain": "ethereum", "type": "native_balance", "address": "0x0000000000000000000000000000000000000000" }, "blockNumber": "0x1234", "blockNumberDecimal": "4660", "value": "0xde0b6b3a7640000", "interpretation": { "kind": "native_balance", "amount": "1", "unit": "ETH", "decimals": 18, "baseUnits": "1000000000000000000" } },
    { "id": "base-native-balance", "chain": "base", "type": "native_balance", "check": { "id": "base-native-balance", "chain": "base", "type": "native_balance", "address": "0x0000000000000000000000000000000000000000" }, "blockNumber": "0x1234", "blockNumberDecimal": "4660", "value": "0x0", "interpretation": { "kind": "native_balance", "amount": "0", "unit": "ETH", "decimals": 18, "baseUnits": "0" } },
    { "id": "arbitrum-native-balance", "chain": "arbitrum", "type": "native_balance", "check": { "id": "arbitrum-native-balance", "chain": "arbitrum", "type": "native_balance", "address": "0x0000000000000000000000000000000000000000" }, "blockNumber": "0x1234", "blockNumberDecimal": "4660", "value": "0x0", "interpretation": { "kind": "native_balance", "amount": "0", "unit": "ETH", "decimals": 18, "baseUnits": "0" } },
    { "id": "optimism-native-balance", "chain": "optimism", "type": "native_balance", "check": { "id": "optimism-native-balance", "chain": "optimism", "type": "native_balance", "address": "0x0000000000000000000000000000000000000000" }, "blockNumber": "0x1234", "blockNumberDecimal": "4660", "value": "0x0", "interpretation": { "kind": "native_balance", "amount": "0", "unit": "ETH", "decimals": 18, "baseUnits": "0" } },
    { "id": "polygon-native-balance", "chain": "polygon", "type": "native_balance", "check": { "id": "polygon-native-balance", "chain": "polygon", "type": "native_balance", "address": "0x0000000000000000000000000000000000000000" }, "blockNumber": "0x1234", "blockNumberDecimal": "4660", "value": "0x0", "interpretation": { "kind": "native_balance", "amount": "0", "unit": "POL", "decimals": 18, "baseUnits": "0" } }
  ],
  "snapshotBlocks": {
    "ethereum": "0x1234", "base": "0x1234", "arbitrum": "0x1234",
    "optimism": "0x1234", "polygon": "0x1234"
  },
  "snapshotBlocksDecimal": { "ethereum": "4660", "base": "4660", "arbitrum": "4660", "optimism": "4660", "polygon": "4660" },
  "verification": "each result is a successful JSON-RPC response",
  "recoveryUrl": "https://evmstate.com/v1/results/12345678-1234-4234-9234-123456789abc",
  "expiresAt": "2026-11-01T00:00:00.000Z"
}

Each check has its own blockNumber; snapshotBlocks groups the corresponding captured height per chain. These sample heights and balances are illustrative. Zero is a valid balance for the requested address, not an error marker; the sample includes 1 ETH to show how a nonzero raw value maps to a decimal amount.

The service stores request fingerprints, completed response JSON, payment transaction metadata, and timestamps in its dedicated D1 database. Unpaid quote analytics contain only a one-way request-ID hash, endpoint, and timestamps for up to 90 days. It does not store wallet private keys. Plain-Text Agent Instructions are available for software clients.

Terms · Privacy

Contact Support

Send us a message. Include an email address if you would like a reply.