- Priority 1: Hardware wallet (secure long-term storage)
- Priority 2: Hot wallet (not used for withdrawals)
Overview
Priority management determines the order in which external wallets are evaluated for funding transactions. When users have multiple registered external wallets, priority controls:- Card Payments: Which wallet funds card purchases
- Credit/Reward Withdrawals: Which wallet receives platform credits and rewards
How Priority Works
Sequential Wallet Evaluation
The platform checks each wallet in order until it finds one that can cover the full transaction amount. If no single wallet has enough balance, the transaction fails.Viewing Current Priority
Get the current priority order for all registered external wallets:Response Fields
| Field | Description |
|---|---|
id | Wallet identifier (required for updating priority) |
address | Blockchain wallet address |
currency | Currency in this wallet |
network | Blockchain network |
priority | Current priority order (lower = higher precedence) |
Updating Priority
Change the priority order of external wallets:Request Parameters
| Field | Required | Description |
|---|---|---|
wallets | Yes | Array of all wallets with new priority assignments |
wallets[].id | Yes | Wallet identifier from GET priority response |
wallets[].priority | Yes | New priority value (must be sequential: 1, 2, 3…) |
Priority Use Cases
For Card Payments
Priority determines the order in which wallets are evaluated when a card transaction occurs. The first wallet with sufficient balance to cover the entire purchase amount is used. Only one wallet is charged per transaction.Fee Optimization
Fee Optimization
Set lower-fee networks to higher priority to minimize transaction costs.Example:
- Priority 1: USDC on Linea (fees: $0.01-0.05)
- Priority 2: USDC on Ethereum (fees: $2-5)
- Priority 3: USDC on Solana (fees: $0.0001)
Balance Management
Balance Management
Spend from smaller balance wallets first to consolidate funds.Example:
- Priority 1: Wallet with $200 balance (spend this first)
- Priority 2: Wallet with $1000 balance (backup)
- Priority 3: Wallet with $5000 balance (emergency reserve)
Currency Preference
Currency Preference
Prefer spending one stablecoin over another based on personal preference or market conditions.Example:
- Priority 1: USDC wallet
- Priority 2: USDT wallet
- Priority 3: DAI wallet
Network Reliability
Network Reliability
Prioritize more reliable networks during periods of high congestion.Example During Ethereum Congestion:
- Priority 1: Solana wallet (fast, cheap)
- Priority 2: Linea wallet (moderate)
- Priority 3: Ethereum wallet (congested)
For Credit/Reward Withdrawals
Priority determines which wallet receives credit and reward withdrawals. For withdrawals, the priority 1 wallet always receives the funds (if it has sufficient capacity). If priority 1 wallet cannot receive the funds, the transaction will fail.Primary Holding Wallet
Primary Holding Wallet
Receive all credits and rewards in your main holding wallet.Example:
DeFi Deployment
DeFi Deployment
Automatically route rewards to wallet connected to DeFi protocols.Example:
- Priority 1: DeFi wallet (earning yield)
- Priority 2: Spending wallet (daily use)
Network Selection
Network Selection
Receive withdrawals on preferred network for lower fees or faster processing.Example:
- Priority 1: Linea wallet (low withdrawal fees)
- Priority 2: Ethereum wallet (backup)
Transaction Flow Examples
Example 1: Card Payment with Multiple Wallets
Setup:- Priority 1: USDC Linea (50 allowance)
- Priority 2: USDT Ethereum (200 allowance)
- Priority 3: USDC Solana (1000 allowance)
1
Check Priority 1 (Linea)
Platform checks Linea wallet. Balance: 75 purchase. Wallet skipped entirely.
2
Check Priority 2 (Ethereum)
Platform checks Ethereum wallet. Balance: 75 transaction.
3
Transaction Complete
Purchase approved. Ethereum wallet balance now $125. Solana wallet (Priority 3) was never checked. Only Ethereum wallet was used.
Example 2: Credit Withdrawal
Setup:- Priority 1: Linea wallet (0x3a11…)
- Priority 2: Ethereum wallet (0x7b22…)
- User has $100 credit balance
1
User Requests Withdrawal
User calls
POST /v1/wallet/credit/withdraw with amount: “100”2
Platform Selects Priority 1 Wallet
Platform identifies Priority 1 wallet (Linea) as the withdrawal destination. Priority 2 and 3 wallets are NOT considered for withdrawals.
3
Execute On-Chain Transfer
Platform sends the entire $100 USDC to Priority 1 Linea wallet address
4
Return Transaction Hash
API returns
txHash for blockchain verificationImplementation Examples
Get and Display Priority
Update Priority
Priority Management UI
Priority Best Practices
Start with Fee Optimization
Set lowest-fee networks (Linea, Solana) to priority 1 for cost-effective card payments. Higher-fee networks (Ethereum) as backup.
Consider Transaction Speed
For time-sensitive purchases, prioritize faster networks (Solana: 5-30s, Linea: 1-2min) over slower ones (Ethereum: 5-15min).
Balance Distribution
Don’t over-concentrate funds in Priority 1. Maintain balances across multiple priorities for redundancy.
Update Dynamically
Allow users to easily adjust priority based on changing needs (travel, large purchase upcoming, network congestion).
Show Fallback Behavior
Clearly communicate that Priority 2 and 3 are backups, only used if Priority 1 has insufficient balance for the entire transaction. Each wallet must be able to fund the full transaction amount.
Withdrawal Clarity
Inform users that credit/reward withdrawals always go to Priority 1 wallet ONLY. Make this explicit in UI. Priority 2+ wallets are never used for withdrawals.
Error Handling
All Wallets Insufficient
Invalid Wallet IDs
Non-Sequential Priority
Missing Wallets in Update
Network-Specific Considerations
Linea Priority Strategy
Recommended: Priority 1 for daily spending Reasons:- Low fees ($0.01-0.05 per transaction)
- Fast confirmations (1-2 minutes)
- US environment support
- Optimal for frequent card use
Ethereum Priority Strategy
Recommended: Priority 2 or 3 (backup) Reasons:- Higher fees ($2-10 depending on congestion)
- Slower confirmations (5-15 minutes)
- Best as fallback, not primary
- Network congestion low (weekends, off-hours)
- Large balance only on Ethereum
- Participating in Ethereum-specific rewards
Solana Priority Strategy
Recommended: Priority 1 for speed-sensitive or Priority 3 for backup Reasons:- Extremely low fees (~$0.0001)
- Very fast confirmations (5-30 seconds)
- Occasional network instability
- Cost is paramount
- Speed is critical
- Network is stable
