Troubleshooting Guide: The Embedded Wallet (in-game/in-app)

Login Failure (Social/Email)

1. Browser/Extension conflicts.

Clear Browser Data: Advise the user to clear their default browser's cache and cookies.

Try Incognito Mode: Attempt login in a private/incognito window to isolate extension issues.

2. Ad-blockers or privacy extensions interfering with pop-ups.

Disable Extensions: Temporarily disable all browser extensions, especially ad-blockers, and try the login flow again.

Wallet UI Not Loading

1. Network connectivity issues.

Check Connection: Ensure the user has a stable internet connection. Try switching from Wi-Fi to a mobile network.

Transaction Signing Fails

1. Insufficient native gas token (e.g., ETH, MATIC) to cover the fee.

Check Balance: Confirm the user has enough of the native currency for the chain they are on (e.g., ETH for Ethereum, MATIC for Polygon) to cover the transaction gas fees.

(For Developers) Wallet Fails to Initialize

1. Incorrect SDK configuration.

Verify Config: Double-check your Sequence Project Access Key and the Chain ID are correctly set in your SDK initialization code, as per the Sequence Docs.

MetaMask Pop-up Fails to Appear

1. Multiple browser wallets are enabled.

Disable Other Wallets: Go to the browser's extension settings and disable all other wallet extensions (e.g., Phantom, Coinbase Wallet, etc.) except for MetaMask.

2. MetaMask is locked or not fully loaded.

Unlock & Expand: Instruct the user to unlock their MetaMask. For desktop, have them try to open MetaMask in an Expanded View to ensure the provider is properly injected.

3. Browser Pop-up Blocker.

Allow Pop-ups: Check if the browser's pop-up blocker is preventing the connection window from appearing and allow pop-ups for your domain.

"User Rejected Request" Error

1. User canceled the connection.

Approve Request: The user must explicitly click "Approve" or "Connect" in the MetaMask pop-up to grant permission to your application.

Wrong Account/Network Connected

1. Incorrect selection in MetaMask before connecting.

Switch Account/Network: The user should check their MetaMask extension and manually switch to the correct account and/or the required network before clicking your "Connect" button.

Chain Switching Error

1. The target chain is not configured in the user's MetaMask.

Implement Chain Addition: Ensure your dapp's connection logic uses the wallet_addEthereumChain JSON-RPC method to prompt MetaMask to add the necessary network details.

On-Ramp Widget Fails to Load

1. Temporary API issue with the provider.

Refresh and Retry: Advise the user to refresh the page and try opening the modal again. If the issue is persistent, check the status of the integrated on-ramp provider.

"Service Not Available" / Geoblocked

1. The user's region is restricted by the provider due to regulatory compliance.

Check Restrictions: The user must confirm their country/region is supported by the on-ramp provider. This is an external restriction that cannot be bypassed by Sequence.

KYC (Identity Verification) Failure/Delay

1. Incorrect or incomplete document submission to the provider.

Contact Provider Support: Instruct the user to contact the support team of the specific on-ramp provider they used (e.g., MoonPay Support). Sequence Support cannot resolve KYC issues.

Payment Card Rejected/Bank Block

1. Bank policy or insufficient funds.

Contact Bank: Advise the user to contact their bank to ensure they allow crypto purchases. They should try a different card or alternative payment method if available.

Crypto Not Arriving in Wallet

1. Delay in fiat processing or on-chain transaction confirmation.

Wait for Confirmation: Fiat purchases can take time. The user should check the status update from the on-ramp provider (often sent via email). If the provider confirms the transaction is complete, check the block explorer for the transaction hash.