Overview
When users delegate multiple wallets, priority determines the order in which wallets are evaluated for funding card transactions. When a transaction is initiated, the platform checks wallets sequentially in priority order (1, 2, 3…). The first wallet with sufficient balance and allowance to cover the entire transaction cost is used. Only one wallet funds each transaction - multi-funding is not supported.Priority is a simple numeric value where lower numbers = higher priority. Priority 1 is checked before Priority 2, which is checked before Priority 3, etc.
How Priority Works
Sequential Wallet Evaluation
When a user makes a card purchase, the platform evaluates wallets in priority order to find one that can fund the entire transaction:1
Check Priority 1 Wallet
Platform checks the highest priority wallet (priority: 1) for sufficient balance and allowance to cover the ENTIRE transaction amount
2
Use or Skip
- Sufficient Balance: Transaction is funded entirely from Priority 1 wallet. Process complete.
- Insufficient Balance: Priority 1 wallet is skipped entirely (no partial funding). Platform moves to Priority 2.
3
Check Next Priority
If Priority 1 was insufficient, check Priority 2 for sufficient balance. If sufficient, use Priority 2 for the entire transaction. If insufficient, skip to Priority 3.
4
Success or Failure
Process continues through priority list until a wallet with sufficient balance is found (transaction succeeds) or all wallets exhausted (transaction fails).
Why Wallets Are Skipped
A wallet is skipped and the next priority wallet is evaluated when:- Insufficient balance: Wallet doesn’t have enough tokens to cover the ENTIRE purchase amount
- Insufficient allowance: Remaining delegated amount is less than the full purchase amount
- Network unavailable: Blockchain network is experiencing issues
- Transaction timeout: Blockchain confirmation takes too long
Get Current Priority
Retrieve the priority order of all delegated wallets for a user.API Request
GET /v1/wallet/external/priority
Response
Response Fields
| Field | Type | Description |
|---|---|---|
id | number | Unique wallet identifier (required for updates) |
address | string | Wallet address |
currency | string | Token currency (usdc, usdt) |
network | string | Blockchain network (linea, ethereum, solana) |
priority | number | Charging priority (lower = higher priority) |
Update Priority
Reorder wallet priority to change which wallets are charged first.API Request
PUT /v1/wallet/external/priority
Request Body
You must include ALL wallets in the update request. Any wallet not included will not have its priority changed.
Validation Rules
- All priorities must be unique: No two wallets can have the same priority
- Continuous numbering: Priorities should typically be 1, 2, 3, etc. (gaps are allowed but not recommended)
- Valid wallet IDs: All IDs must belong to the user’s delegated wallets
- Complete update: Include all wallets you want to manage
Use Cases
1. Gas Fee Optimization
Route transactions through lower-fee networks first. The platform will check wallets in this order and use the first one with sufficient balance for the entire transaction:2. Balance Management
Use wallets with smaller balances first to consolidate funds:3. Network Preference
Prefer specific networks for faster confirmations or better UX:4. Backup Wallet Strategy
Keep high-balance wallet as backup, use smaller wallets first. Each wallet must have enough balance to fund full transactions on its own:5. Currency Routing
Prefer specific stablecoins based on availability or preference:UI Implementation Examples
Drag-and-Drop Priority Management
Quick Actions
Best Practices
Priority Strategy Guidelines
Start Simple
Start Simple
Begin with a straightforward priority order based on your primary use case (e.g., lowest gas fees). You can always adjust later.
Monitor Balances
Monitor Balances
Regularly check wallet balances and adjust priority to prevent transaction failures. Set up alerts when balances run low.
Consider Gas Costs
Consider Gas Costs
For frequent small purchases, prioritizing lower-fee networks can save significant amounts over time.
Maintain Backups
Maintain Backups
Always keep at least one wallet with sufficient balance as a lower priority backup to prevent declined transactions.
Test Changes
Test Changes
After updating priority, make a small test purchase to ensure the new order works as expected.
Document Strategy
Document Strategy
Keep notes on why you’ve set specific priorities, especially for business accounts with multiple administrators.
Automation Opportunities
Consider building automated priority management:Troubleshooting
All Wallets Being Skipped
All Wallets Being Skipped
Symptoms: Transactions failing across all walletsCommon Causes:
- All wallets have insufficient balance to cover the ENTIRE transaction amount
- All allowances exhausted (need redelegation)
- Network issues on all blockchains (rare)
- Check balances:
GET /v1/wallet/external - Ensure at least ONE wallet has sufficient balance for the full transaction
- Top up wallets or redelegate with higher allowances
- Verify network status on block explorers
Unexpected Wallet Being Charged
Unexpected Wallet Being Charged
Symptoms: Lower priority wallet charged instead of higher priorityCommon Causes:
- Higher priority wallet has insufficient balance/allowance to cover the ENTIRE transaction (was skipped)
- Recent priority update not yet reflected
- Cached priority data
- Verify current priority:
GET /v1/wallet/external/priority - Check wallet balances and allowances - ensure Priority 1 has enough for typical transaction sizes
- Make test transaction to verify behavior
Priority Update Not Taking Effect
Priority Update Not Taking Effect
Symptoms: Priority update succeeds but charging order unchangedCommon Causes:
- Update request malformed (missing wallets)
- Duplicate priorities in request
- API error not caught
- Fetch current priority after update to verify
- Ensure all wallet IDs are included in update
- Check API response for errors
