d-bis/metamask-integration
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
25c96e210a1f038e8137e6d0541945a2fbf8fcbb
metamask-integration/chain138-snap/docs/CHAIN138_SNAP_TROUBLESHOOTING.md
defiQUG 25c96e210a chore: sync submodule state (parent ref update) 
Made-with: Cursor
2026-03-02 12:14:14 -08:00

13 KiB
Raw Blame History

Chain 138 Snap — Troubleshooting (balance, swap, data)

If installation fails (“snap is not on the allowlist”), main balance or USD value is not showing, swap is malfunctioning, or historical/data not loading when using the Chain 138 Snap with MetaMask (including Flask), use this guide.

1. Installation fails: "The snap is not on the allowlist"

What you see: When adding the Snap in MetaMask you get:

  • "Connection failed — Fetching of chain138-snap failed, check your network and try again."
  • "Cannot install version '0.1.2' of snap 'npm:chain138-snap': The snap is not on the allowlist."

Cause: MetaMask only allows installing Snaps that use protected permissions (such as endowment:rpc and endowment:network-access) if the Snap is on their allowlist. The Chain 138 Snap uses those permissions, so it must be allowlisted. The Snap is published on npm and has been submitted for allowlisting; until MetaMask/Consensys approves it, standard MetaMask will block installation.

What you can do:

  1. Use MetaMask Flask (workaround now)
    MetaMask Flask is the development build and does not enforce the allowlist. Install Flask, then add the Snap using the same ID: npm:chain138-snap. The Snap works the same once installed.

  2. Wait for allowlist approval
    Once the Snap is approved, it will be installable in standard MetaMask. No code changes are required on your side.

  3. Operators: If you submitted the allowlist form and it has been pending for a long time, you can follow up via the MetaMask Snaps allowlist process. For new versions (e.g. 0.1.3), use the Snaps Directory Information Update form to add the new version. Pre-filled fields for the submission are in ALLOWLIST_FORM_FIELDS.md.

2. Main balance / USD not showing ($0.00, "No conversion rate available")

What you see: MetaMask shows $0.00 or "No conversion rate available" for ETH (or other tokens) even when you hold a non‑zero balance (e.g. 1,000 ETH).

Cause: The main wallet balance and USD value are provided by MetaMask (Consensys), not by the Snap. MetaMask gets conversion rates from its own providers (e.g. LavaPack). Chain 138 (DeFi Oracle Meta Mainnet) is not in that list, so MetaMask has no price feed for it and shows no USD value.

This is expected for custom chains until Consensys or price providers add support.

What you can do:

  • Trust the token quantity: Your on‑chain balance (e.g. "1,000 ETH") is correct; only the USD conversion is missing in the wallet UI.
  • Use the Snap for prices: Open the Snap companion site (e.g. https://explorer.d-bis.org/snap/) and use "Show market data" or "Fetch market summary". Those use the token‑aggregation API (see §5) and can show USD prices for Chain 138 tokens.
  • Long‑term: Submit Chain 138 and tokens to CoinGecko/CMC and/or Consensys so native MetaMask USD may be supported later (see project docs, e.g. COINGECKO_SUBMISSION_GUIDE, Consensys outreach).

3. "We could not fetch any historical data"

What you see: In the token/asset detail view, MetaMask shows a raccoon mascot and "We could not fetch any historical data" with time range buttons (1D, 1W, 1M, etc.).

Cause: Historical price/chart data is also supplied by MetaMask’s portfolio/price providers, which do not support Chain 138.

What you can do: This is a MetaMask UI limitation. Use the Snap’s market data (companion site) or external explorers/APIs for historical data on Chain 138.

4. Swap malfunctioning (in‑wallet Swap button)

What you see: Clicking Swap in MetaMask on Chain 138 fails or shows errors (e.g. "No XChain Swaps native asset found for chainId: eip155:138").

Cause: MetaMask’s in‑wallet Swap feature does not support Chain 138. It only supports chains in their native Swaps list.

What you can do:

  • Send ETH on Chain 138: Use the dedicated Send on Chain 138 page:
    https://explorer.d-bis.org/snap/send
    It uses eth_sendTransaction from the dApp context and works on Chain 138 (see packages/site/src/pages/send.tsx).
  • Swap quotes via Snap: On the Snap companion site, use the Swap quote card: enter token In/Out and amount, then "Get quote" or "Show quote in Snap". This uses the token‑aggregation API. Executing the actual swap must be done in your dApp or a DEX that supports Chain 138, not via MetaMask’s Swap button.
  • WETH display quirk: If you see wrong WETH balance formatting (e.g. "6,000,000,000.0T WETH"), see METAMASK_WETH9_DISPLAY_BUG.md (token list / decimals).

5. Snap market data / swap quote / bridge not loading

What you see: On the companion site (e.g. https://explorer.d-bis.org/snap/), "Show market data", "Fetch market summary", "Get quote" / "Show quote in Snap", or bridge routes show an error or "Set GATSBY_SNAP_API_BASE_URL".

Cause: Those features need a token‑aggregation–compatible API. The Snap calls:

  • GET {apiBaseUrl}/api/v1/networks
  • GET {apiBaseUrl}/api/v1/tokens?chainId=138&limit=...
  • GET {apiBaseUrl}/api/v1/quote?chainId=138&tokenIn=...&tokenOut=...&amountIn=...
  • GET {apiBaseUrl}/api/v1/bridge/routes
  • etc.

The companion site passes apiBaseUrl from GATSBY_SNAP_API_BASE_URL at build time. If that URL does not serve the token‑aggregation API (see smom-dbis-138/services/token-aggregation and REST_API_REFERENCE.md), those calls fail.

What you can do:

  1. If you build with GATSBY_SNAP_API_BASE_URL=https://explorer.d-bis.org
    Then explorer.d-bis.org must expose the token‑aggregation API. The explorer’s normal Blockscout/Go APIs do not implement /api/v1/networks, /api/v1/tokens, /api/v1/quote, etc. You must either:

    • Deploy the token‑aggregation service (from smom-dbis-138/services/token-aggregation) and proxy its routes under https://explorer.d-bis.org/api/v1/.... On the explorer VM (VMID 5000), run explorer-monorepo/scripts/apply-nginx-token-aggregation-proxy.sh (or ensure the nginx config includes a location /api/v1/ proxy to the token‑aggregation port, e.g. 3000). The script fix-nginx-conflicts-vmid5000.sh in the same repo already adds this proxy when applied.
    • Or use a separate API host (see below).

  2. If the token‑aggregation service runs elsewhere (e.g. https://api.d-bis.org or an internal URL):
    Build the Snap site with that base URL:

    export GATSBY_SNAP_API_BASE_URL=https://your-token-aggregation-host
bash scripts/build-snap-site-for-explorer.sh

    Deploy the built packages/site/public/ to /var/www/html/snap/ (or your Snap host). Then the companion site will pass the correct apiBaseUrl to the Snap and market/swap/bridge can work.

  3. Local development: Set GATSBY_SNAP_API_BASE_URL in packages/site/.env to your token‑aggregation base URL (e.g. http://localhost:3001 if the service runs there). See FAQ.md (“The companion site shows ‘Set GATSBY_SNAP_API_BASE_URL’”).

6. No icons or tokens showing in MetaMask Flask

What you see: MetaMask Flask shows no token icons, no chain icons, or no tokens from the token list when viewing Chain 138 or ALL Mainnet.

Cause: MetaMask does not auto-load tokens from the Snap. Chain 138 is not in MetaMask’s built-in token detection (which only covers Ethereum, Polygon, Arbitrum, etc.). You must add the token list URL manually. Icons come from logoURI (per token) and iconUrls (per network) in the API responses; if those URLs are missing or unreachable, MetaMask shows no icons.

What you can do:

  1. Get and add the token list URL

    • Open the Snap companion site (e.g. https://explorer.d-bis.org/snap/).
    • Connect MetaMask Flask and install the Snap.
    • Click "Show dynamic info" (requires GATSBY_SNAP_API_BASE_URL to be set at build time).
    • The Snap dialog shows the Token list URL (e.g. https://explorer.d-bis.org/api/v1/report/token-list).
    • Add that URL in MetaMask: Settings → Security & Privacy → Token list (or equivalent), if your MetaMask version supports custom token list URLs.

  2. If MetaMask does not support custom token list URLs

    • Add tokens manually: Tokens tab → Import tokens → Custom token → enter the token contract address for Chain 138 (e.g. cUSDC, cUSDT from the explorer or CHAIN138_TOKEN_ADDRESSES).

  3. Ensure apiBaseUrl is set and reachable

    • The companion site must be built with GATSBY_SNAP_API_BASE_URL pointing at the token-aggregation API.
    • Verify: curl "https://explorer.d-bis.org/api/v1/report/token-list?chainId=138" returns valid JSON with tokens and each token has logoURI.

  4. Icons not showing

    • Token icons: Each token in the token list must have a valid logoURI. The token-aggregation API provides these from canonical-tokens.ts (Trust Wallet assets).
    • Network icons: GET /api/v1/networks must return iconUrls for each chain. Each network has a primary URL (e.g. explorer.d-bis.org/favicon.ico) and a fallback (Trust Wallet ETH logo). If the primary 404s, MetaMask uses the fallback. Operators: add favicon.ico to explorer and alltra sites if missing.
    • If logo URLs (e.g. raw.githubusercontent.com) are blocked or return 404, operators can host logos locally and update canonical-tokens.ts or networks.ts.

Operators: See PRE_PUBLISH_TESTING.md §4.3 (token list logoURI) and §4.4 (network iconUrls) for verification steps.

7. Permissions and connected site

The Snap needs:

  • Access the internet — to call the token‑aggregation API.
  • Display dialog windows in MetaMask — for market data, swap quote, bridge dialogs.
  • Allow websites to communicate directly with Chain 138 — so the companion site (e.g. explorer.d-bis.org) can invoke the Snap.

If market/swap work on the companion site but not from another origin, ensure that site is connected in MetaMask (Snap settings → Connected sites) and that you’re using the same Snap origin (e.g. npm:chain138-snap) and correct apiBaseUrl.

8. Quick reference

Issue Cause Action
Installation: "snap is not on the allowlist" Snap not yet approved on MetaMask allowlist Use MetaMask Flask to install now; or wait for allowlist approval
No icons or tokens in MetaMask Flask Token list not added; Chain 138 not in built-in detection Use "Show dynamic info" to get token list URL; add in MetaMask Settings → Token list; or add tokens manually
Main balance USD = $0.00 / no conversion rate MetaMask has no price feed for Chain 138 Use Snap “Show market data” or accept quantity-only in wallet
Historical data not loading MetaMask portfolio doesn’t support Chain 138 Use Snap/explorer or external APIs
In‑wallet Swap fails MetaMask Swap doesn’t support Chain 138 Use Send on Chain 138; get swap quotes from Snap companion site and execute swap in dApp/DEX
Snap market/swap/bridge errors apiBaseUrl not set or not serving token‑aggregation API Set GATSBY_SNAP_API_BASE_URL to token‑aggregation host; ensure /api/v1/... is available there (or proxy it under explorer.d-bis.org)

Related docs

Reference in New Issue View Git Blame Copy Permalink