Overview
External wallets are user-controlled blockchain wallets registered through the delegation process. Users maintain full custody of their private keys while granting spending authority to the platform for card payments. The platform can view balance and allowance information but never has access to private keys.Viewing External Wallets
Retrieve all external wallets registered by the authenticated user:Response Fields
| Field | Type | Description |
|---|---|---|
address | string | Blockchain wallet address controlled by user |
currency | string | Currency delegated from this wallet |
balance | string | Current wallet balance (on-chain) |
allowance | string | Remaining spending authority granted to platform |
network | string | Blockchain network (linea, ethereum, solana) |
Understanding Balance vs Allowance
External wallet data includes two critical values:- Balance
- Allowance
Balance is the total amount of cryptocurrency in the user’s wallet on the blockchain.
- Retrieved directly from blockchain
- Updated in real-time
- Includes all funds, not just delegated amount
- User controls this completely
balance value.Key Relationship: Allowance can never exceed balance. Even if user delegated 5000 USDC but only has 2000 USDC remaining in wallet, maximum chargeable amount is 2000 USDC.
Interpreting Wallet Status
Different balance/allowance combinations indicate different states:Healthy Wallet
Healthy Wallet
Low Allowance
Low Allowance
Low Balance
Low Balance
Exhausted Allowance
Exhausted Allowance
Empty Wallet
Empty Wallet
Registering External Wallets
External wallets are registered through the delegation process. Users cannot be added directly via the API.1
User Initiates Delegation
User clicks “Connect Wallet” or “Add External Wallet” in your application.
2
Request Delegation Token
Your backend calls
GET /v1/delegation/token to obtain a single-use token.3
Frontend Wallet Interaction
User connects Web3 wallet and approves blockchain transaction granting spending authority.
4
Submit Delegation Proof
Your backend calls blockchain-specific endpoint to finalize registration:
POST /v1/delegation/evm/post-approvalfor Linea/EthereumPOST /v1/delegation/solana/post-approvalfor Solana
5
Verify Registration
Call
GET /v1/wallet/external to confirm wallet appears in user’s registered wallets.Network-Specific Details
EVM Networks (Linea, Ethereum)
- Address Format
- Delegation Method
- Gas Considerations
- Length: 42 characters
- Format: Hexadecimal starting with “0x”
- Example:
0x3a11a86cf218c448be519728cd3ac5c741fb3424 - Checksum: Case-sensitive checksummed addresses
Solana
- Address Format
- Delegation Method
- Transaction Speed
- Length: 32-44 characters
- Format: Base58-encoded public key
- Example:
DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK
Implementation Examples
Display External Wallets
Wallet Status Component
Monitoring and Alerts
Implement proactive monitoring to alert users before issues occur:Allowance Monitoring
50% Threshold
50% Threshold
Alert when allowance drops below 50% of original delegation.Message: “Your allowance is half-used. Consider redelegating soon.”
20% Threshold
20% Threshold
Stronger alert when allowance drops below 20%.Message: “Your allowance is running low. Redelegate now to avoid payment issues.”
Exhausted
Exhausted
Critical alert when allowance reaches 0.Message: “Card payments blocked. Redelegate immediately to continue.”
Balance Monitoring
Low Balance
Low Balance
Alert when balance drops below minimum threshold (e.g., $100).Message: “Your wallet balance is low. Add funds to enable purchases.”
Empty Wallet
Empty Wallet
Alert when balance reaches 0.Message: “Your wallet is empty. Add funds to resume card payments.”
Use Cases
Multi-Network Spending
Multi-Network Spending
Register wallets on different networks to optimize for fees or speed:
- Linea for daily spending (low fees)
- Ethereum for large purchases (more liquidity)
- Solana for fast transactions (quick confirmations)
Currency Diversification
Currency Diversification
Register wallets with different currencies:
- USDC wallet for stable value
- USDT wallet as backup
- Multiple stablecoins for redundancy
DeFi Integration
DeFi Integration
Users can keep majority of funds in DeFi protocols while maintaining delegated wallet for card payments:
- Delegate small amount for daily spending
- Keep bulk in yield-earning protocols
- Transfer and redelegate as needed
Business Expense Separation
Business Expense Separation
Register separate wallets for personal vs. business spending:
- Personal wallet with priority 1
- Business wallet with priority 2
- Clear separation for accounting
Best Practices
Poll for Updates
External wallet data is retrieved from blockchain in real-time. Poll this endpoint periodically (every 30-60 seconds) when user is viewing wallet information to show current status.
Show Effective Limit
Display
min(balance, allowance) as the actual spendable amount. This is the real limit for card transactions.Proactive Redelegation Prompts
Alert users when allowance drops below 20% and provide one-click redelegation flow. Don’t wait until allowance is exhausted.
Network Fee Information
Display approximate network fees for each blockchain to help users choose cost-effective options when registering multiple wallets.
Blockchain Explorer Links
Provide links to blockchain explorers (Etherscan, Solscan) so users can verify wallet state independently.
Security Reminders
Remind users that they control their private keys and should secure their wallet software properly. Platform never has access to keys.
