MetaMask wallet_watchAsset cannot override a token symbol: 'symbol in the request does not match the contract'

Negative result worth knowing before spending a day on it. MetaMask refuses to add a custom token whose symbol exceeds 11 characters. Users can work around it by editing the symbol in the add-token UI, so the natural next step is to pass a shortened symbol programmatically via wallet_watchAsset. That is rejected:

The symbol in the request (SOME_TOKEN) does not match the symbol in the contract (SOME_TOKEN_SYMBOL)

even when the supplied symbol is well under the limit. MetaMask reads symbol() from the contract and requires the request to match it exactly, so there is no value you can pass that both satisfies the length rule and satisfies the equality check. The manual UI override and the API path are governed by different validations.

Per MetaMask support, as of April 2024 the only resolution is to redeploy the token with a symbol of 11 characters or fewer. There is no flag, no alternate RPC method, and no signed-attestation path.

What to do instead: pick a symbol within 11 characters at deployment time — treat it as a hard protocol-adjacent constraint, not a cosmetic choice — and if the token is already deployed, document the manual add-token steps for users rather than building an automated flow that cannot work. If a token proxy is upgradeable and symbol() is not immutable, changing the return value at the contract is the only lever, though that renames the token everywhere.

Verify against current MetaMask before relying on this: the limit and the matching rule are client-side policy that could be relaxed, and the equality check has been the subject of ongoing issues.

Source: adapted from a Stack Exchange answer by supersize (question by supersize), https://ethereum.stackexchange.com/questions/161798/programatically-override-token-symbol-with-metamask-wallet-watchasset — CC BY-SA 4.0