Skip to content

docs: MetaMask nativeCurrency must use decimals:18 / symbol:"ETH" even though Arc gas token is USDC — undocumented and confusing #95

@osr21

Description

@osr21

Summary

When a user adds Arc Testnet to MetaMask using wallet_addEthereumChain, the nativeCurrency
field must use decimals: 18 because MetaMask only supports 18-decimal native currencies.
However, Arc's gas token is USDC with 6 decimals for ERC-20 operations — so developers must
pass { name: "ETH", symbol: "ETH", decimals: 18 } to avoid wallet rejection, even though
the actual gas token is USDC.

This is confusing and has two visible consequences for users:

  1. MetaMask shows gas costs in "ETH" — e.g., "0.000000021 ETH" instead of the correct
    USDC display
  2. Developers passing the correct symbol "USDC" with decimals 18 get wrong balance display
    MetaMask will show 10^12× the correct USDC balance

There is no current documentation explaining why Arc DApps pass "ETH" as the native currency
symbol, or why this is necessary.

Reproduction

// ❌ This looks correct but shows balance as 10^12x too high in MetaMask
await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{ chainId: "0x4CEF52", nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 18 } }]
});

// ✅ Correct workaround — MetaMask displays "ETH" but transactions work correctly
await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{ chainId: "0x4CEF52", nativeCurrency: { name: "ETH", symbol: "ETH", decimals: 18 } }]
});

Suggested fix

Document this MetaMask limitation in the Arc developer guides so that DApp developers
know why they should use "ETH" as the symbol in the wallet_addEthereumChain call,
and how to display correct USDC gas estimates in their own UI.

Environment: MetaMask browser extension (latest), Arc Testnet (chainId 5042002)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions