Wallet Detection
When using Protocol v2 on EVM chains, you need to detect whether your user’s wallet is an EOA (Externally Owned Account) or a Smart Wallet to properly set theexplicitDeposit
parameter in your quote requests.
Understanding Wallet Types
EOAs (Externally Owned Accounts) are regular wallets controlled by a private key, like MetaMask, Coinbase Wallet, and hardware wallets. These wallets can only execute one transaction at a time and cannot batch multiple operations together. Smart Wallets are contract-based wallets that can execute multiple operations in a single transaction. Examples include Gnosis Safe, Argent, and ERC-4337 compatible wallets. Smart wallets can batch approvals and deposits atomically, making multi-step flows more user-friendly.The Problem
Protocol v2 uses the Relay Depository contracts to enable trustless cross-chain payments. For ERC20 token deposits, there are two possible transaction flows: Explicit Deposits (2 transactions):- User approves the Relay Depository contract to spend their tokens
- User calls the
depositErc20
function to transfer tokens with an order ID
- User transfers tokens directly to the solver with order ID encoded in transaction calldata
The Solution
By detecting wallet type, you can set theexplicitDeposit
parameter to choose
the optimal flow:
explicitDeposit: false
- Enables implicit deposits for EOAs (1 transaction)explicitDeposit: true
- Uses explicit approval flow for smart wallets (2 transactions, can be batched)- Default:
true
(safe fallback for all wallet types)
When to Use Wallet Detection
You should implement wallet detection when:- Using
protocolVersion: "v2"
or"preferV2"
- User is on an EVM chain
- User is depositing ERC20 tokens (not native ETH)
- You want to optimize transaction flow for your users
Detection Methods
1. Smart Wallet Capabilities (EIP-5792)
Check if the wallet advertises smart wallet capabilities:2. Contract Code Detection
Check if the wallet address has deployed contract code:3. EIP-7702 Delegation Detection
Check if the wallet uses EIP-7702 delegation (code starts with0xef01
):
explicitDeposit: true
for reliable batching and execution.
Final Determination
Safety Checks
Zero Native Balance Check
If the user has zero native currency (ETH, MATIC, etc.), forceexplicitDeposit: true
to avoid failed transactions due to insufficient gas:
Low Transaction Count Check
If the wallet has 1 or fewer transactions on the source chain, forceexplicitDeposit: true
as this may indicate a new wallet requiring explicit
handling:
Implementation Example
Here’s a complete implementation for detecting wallet types:Example Scenarios
Wallet Type | Detection Result | explicitDeposit | User Experience |
---|---|---|---|
Regular EOA (MetaMask, Coinbase) | EOA detected | false | 1 transaction |
Smart Wallet (Gnosis Safe, Argent) | Smart wallet detected | true | 2 transactions (can be batched) |
EIP-7702 Delegated EOA | Smart wallet detected | true | 2 transactions (can be batched) |
Detection Error | Unknown | true | 2 transactions (safe fallback) |
API Usage
Include theexplicitDeposit
parameter in your quote requests:
Expected User Experience
For EOA Users (explicitDeposit: false
)
For Smart Wallet Users (explicitDeposit: true
)
Best Practices
- Handle errors gracefully - Return
{ isEOA: false, isEIP7702Delegated: false }
on errors (safer default) - Add timeout - Detection should timeout after ~1 second to avoid blocking UX
- Cache results - Cache detection results per wallet/chain combination to avoid repeated calls
- Include safety checks - Always check native balance and transaction count as additional safety measures
- Only use with Protocol v2 - The
explicitDeposit
parameter is only relevant for Protocol v2
Troubleshooting
Detection Returns Incorrect Results
- Ensure you’re using the correct chain ID
- Verify the RPC endpoint is returning accurate data
- Check that wallet capabilities API is properly supported
Quote Requests Failing
- Verify
explicitDeposit
is only included when using v2 protocol - Ensure user has sufficient native currency for gas
- Check that the wallet address is valid