[TypeScript] ERC-20 actions return "Could not fetch token details" and hide the cause on chains without `contracts.multicall3` (custom chains, local Anvil)

Start in typescript/agentkit/src/action-providers/erc20/utils.ts at getTokenDetails and then inspect erc20ActionProvider.ts callers. Reproduce the missing multicall3 case with the provided Anvil example, then add coverage for the fallback and surfaced error cause in the ERC-20 action tests. Done means valid tokens work on chains without multicall3 and failures distinguish the underlying cause.

Language Affected

• Python
• TypeScript

Describe the bug

getTokenDetails() reads name, decimals and balanceOf with viem's publicClient.multicall() and turns every exception into null:

• erc20/utils.ts#L28-L71: multicall() inside try, catch { return null; }.

viem's multicall() throws ChainDoesNotSupportContract when the chain definition has no contracts.multicall3. This is the case for viem's foundry chain (local Anvil) and for any custom chain that does not declare it. So on those chains get_balance, transfer, approve and get_allowance (all call getTokenDetails, see erc20ActionProvider.ts) always return an error string and send nothing, however valid the token is. The string says the token address may be wrong ("Please verify the token address is correct."), and the real reason is dropped, so neither the user nor an LLM driving the action can tell what is wrong.

Reproduction (needs a local Anvil on port 18545; AgentKit's analytics request to cca-lite.coinbase.com is answered locally by a fetch override installed before the import, so nothing is sent; the "token" is a stand-in contract installed with anvil_setCode that answers name(), decimals() and balanceOf(address) like an ERC-20, so no compiler is needed)

anvil --port 18545 &
npm init -y && npm i @coinbase/[email protected] [email protected]
node repro-multicall.mjs

repro-multicall.mjs:

// Run with a local Anvil on 127.0.0.1:18545: node repro-multicall.mjs
// Block AgentKit analytics (cca-lite.coinbase.com) before AgentKit is imported; answer an empty 200.
const realFetch = globalThis.fetch;
let blocked = 0;
globalThis.fetch = async (url, init) => {
  if (String(url?.url ?? url).includes("cca-lite.coinbase.com")) {
    blocked++;
    return new Response("{}", { status: 200 });
  }
  return realFetch(url, init);
};

const { ViemWalletProvider, erc20ActionProvider } = await import("@coinbase/agentkit");
const { createWalletClient, createPublicClient, http, erc20Abi } = await import("viem");
const { privateKeyToAccount } = await import("viem/accounts");
const { foundry } = await import("viem/chains");

console.log("foundry chain contracts.multicall3:", foundry.contracts?.multicall3); // undefined

const rpc = "http://127.0.0.1:18545";
// Stand-in ERC-20: runtime code answering name() / decimals() / balanceOf(address) like a token.
const hex = n => n.toString(16).padStart(2, "0");
const nameDest = 55, decDest = 44; // jump targets, asserted below
const code =
  "600035" + "60e01c" +                   // 00: selector
  "80" + "6306fdde03" + "14" + "60" + hex(nameDest) + "57" + // 03..: name -> nameDest
  "80" + "63313ce567" + "14" + "60" + hex(decDest) + "57" +  // decimals -> decDest
  "683635c9adc5dea00000" + "6000" + "52" + "6020" + "6000" + "f3" + // default: balanceOf = 1000e18
  "5b" + "6012" + "6000" + "52" + "6020" + "6000" + "f3" +  // decDest: 18
  "5b" + "6020" + "6000" + "52" + "6004" + "6020" + "52" + "6354455354" + "60e0" + "1b" + "6040" + "52" + "6060" + "6000" + "f3"; // nameDest: "TEST"
const bytes = code.length / 2;
const decAt = code.indexOf("5b6012") / 2, nameAt = code.indexOf("5b6020") / 2;
console.log("jump targets expected", decDest, nameDest, "actual", decAt, nameAt, "total bytes", bytes);
if (decAt !== decDest || nameAt !== nameDest) throw new Error("fix offsets");

const token = "0x00000000000000000000000000000000000000aa";
const pub = createPublicClient({ chain: foundry, transport: http(rpc) });
await pub.request({ method: "anvil_setCode", params: [token, "0x" + code] });

// Anvil test key 0 (public, well-known).
const account = privateKeyToAccount("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80");
const walletProvider = new ViemWalletProvider(
  createWalletClient({ account, chain: foundry, transport: http(rpc) }),
);

// 1. The token itself is fine: plain eth_call reads work.
const read = c => pub.readContract({ address: token, abi: erc20Abi, functionName: c, args: c === "balanceOf" ? [account.address] : [] });
console.log("direct readContract:", await read("name"), await read("decimals"), await read("balanceOf"));

// 2. The AgentKit actions.
const actions = Object.fromEntries(erc20ActionProvider().getActions(walletProvider).map(a => [a.name, a]));
console.log("action names:", Object.keys(actions).join(", "));
console.log("get_balance ->", await actions["ERC20ActionProvider_get_balance"].invoke({ tokenAddress: token }));
console.log("transfer    ->", await actions["ERC20ActionProvider_transfer"].invoke({ amount: "1", tokenAddress: token, destinationAddress: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" }));
console.log("approve     ->", await actions["ERC20ActionProvider_approve"].invoke({ amount: "1", tokenAddress: token, spenderAddress: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" }));

// 3. The call getTokenDetails() makes, without its try/catch.
try {
  await walletProvider.getPublicClient().multicall({ contracts: [{ address: token, abi: erc20Abi, functionName: "name" }] });
} catch (e) {
  console.log("underlying error:", e.name, "|", e.shortMessage ?? e.message.split("\n")[0]);
}
console.log("analytics requests blocked:", blocked);

Output (ANSI colors removed):

foundry chain contracts.multicall3: undefined
jump targets expected 44 55 actual 44 55 total bytes 82
direct readContract: TEST 18 1000000000000000000000n
action names: ERC20ActionProvider_get_balance, ERC20ActionProvider_transfer, ERC20ActionProvider_approve, ERC20ActionProvider_get_allowance, ERC20ActionProvider_get_erc20_token_address
get_balance -> Error: Could not fetch token details for 0x00000000000000000000000000000000000000aa
transfer    -> Error: Could not fetch token details for 0x00000000000000000000000000000000000000aa. Please verify the token address is correct.
approve     -> Error: Could not fetch token details for 0x00000000000000000000000000000000000000aa. Please verify the token address is correct.
underlying error: ChainDoesNotSupportContract | Chain "Foundry" does not support contract "multicall3".
analytics requests blocked: 4

After the run, eth_blockNumber on the Anvil was still 0x0, so no transaction was sent. The token itself is fine: the plain readContract calls in the output succeed. The last line before the counter shows what getTokenDetails swallows: ChainDoesNotSupportContract: Chain "Foundry" does not support contract "multicall3".

Expected: the actions work on any chain where the token can be read, or at least report the actual error.

Possible fix (source reading, not run):

1. In getTokenDetails, when the chain has no contracts.multicall3 (or when multicall() throws ChainDoesNotSupportContract), fall back to three readContract calls (Promise.all), or construct the client with batch: { multicall: false } for that read.
2. Independently of that, do not drop the exception: log it, or return it to the callers so the action string includes the cause (for example Error: Could not fetch token details for 0x...: Chain "Foundry" does not support contract "multicall3".). The current null conflates "not an ERC-20", "RPC failure" and "chain lacks multicall3". In transfer the same null is also used to decide that the destination is not an ERC-20 contract (L110-L117), so on such a chain that guardrail ("refuse to send to an ERC-20 contract") would silently pass once the first read is made to work, unless the fallback also covers it. This last point is inferred from reading the code, I did not run it.

I am happy to open a PR for the fallback and the error message, with unit tests, if that direction is acceptable.

Versions

$ node --version
v24.21.0
$ npm list @coinbase/agentkit viem
├── @coinbase/[email protected]
└── [email protected]

Reproduced on 0.10.4 (the latest release on npm); the multicall() that fails is made by AgentKit's own nested viem 2.38.3 public client. Source links are to main at 2e6dbaf, where utils.ts is unchanged in the relevant lines. I searched open and closed issues and PRs for multicall3, "token details" and getTokenDetails and found no report of this.