Non-Custodial Wallets - Baanx API Documentation

What are Non-Custodial Wallets?

Non-custodial wallets are user-controlled blockchain wallets where users maintain full custody of their private keys and assets. The platform never has access to private keys. Instead, users grant spending authority through blockchain-based delegation, allowing the platform to charge their wallets for card payments while users retain complete control.

Key Benefits

Self-Custody

Users maintain full control of their private keys and assets. No trust required in platform custody.

Web3 Native

Seamless integration with existing Web3 wallets (MetaMask, Phantom, WalletConnect).

Flexible Withdrawals

Withdraw credit and rewards directly to any user-controlled external wallet.

On-Chain Transparency

All spending authority is recorded on-chain with verifiable allowances.

How It Works

Non-custodial wallet integration uses delegation to enable card payments:

Delegation Flow

User Connects Wallet

User connects their Web3 wallet (MetaMask, Phantom, etc.) through your application.

Request Delegation Token

Your backend requests a delegation token from the API.

Approve On-Chain

User approves blockchain transaction granting spending authority to platform smart contract.

Submit Proof

Your backend submits transaction proof to complete wallet registration.

Card Payments Enabled

User can now make card payments, with funds deducted from their delegated wallet.

Complete Delegation Guide →

External Wallets vs Credit/Reward Withdrawals

Non-custodial mode supports two types of operations:

External Wallets (Card Funding)

User-controlled wallets that fund card payments via delegation: Capabilities:

Delegate spending authority for card payments
View balance and allowance
Manage priority order for multiple wallets
Automatically charged for card transactions

Learn more about External Wallets →

Credit/Reward Withdrawals

Platform-held credits and rewards can be withdrawn to user’s external wallets: Capabilities:

View credit and reward balances
Estimate withdrawal fees
Withdraw to registered external wallets
Automatic routing to highest priority wallet

In non-custodial environments, credit and reward withdrawals go to user-registered external wallets, not whitelisted addresses. Priority determines which external wallet receives the funds.

Supported Networks

Network	Currencies	Type	Delegation Method
Linea	USDC, USDT	EVM	ERC-20 approve()
Ethereum	USDC, USDT	EVM	ERC-20 approve()
Solana	USDC, USDT	Non-EVM	Token account delegation

For US-based users, Linea operations automatically route to US-specific infrastructure when the x-us-env: true header or region=us parameter is used.

Delegation Security Model

Delegation provides controlled spending authority while maintaining user custody:

What Users Control

Private Keys

Users always control their private keys. Platform never has access.

Spending Limits

Users set maximum allowance when delegating. Platform cannot exceed this limit.

Revocation

Users can revoke delegation at any time by interacting with blockchain directly.

Asset Custody

Funds remain in user’s wallet until card transaction occurs.

What Platform Can Do

Charge for Card Transactions

Platform can deduct funds up to the delegated allowance for approved card purchases. Each charge is recorded on-chain.

What Platform Cannot Do

The platform cannot:

Access private keys
Transfer funds beyond delegated allowance
Withdraw funds without card transaction
Change allowance without user approval

Common Workflows

Workflow 1: Initial Wallet Delegation

Workflow 2: Credit Withdrawal to External Wallet

Allowance Management

When users delegate spending authority, they set an allowance (spending limit):

How Allowances Work

Set During Delegation: User specifies maximum amount platform can spend
Decreases with Use: Each card transaction reduces available allowance
On-Chain Record: Allowance is recorded and enforced by blockchain smart contracts
User-Controlled: Only users can increase allowance through redelegation

curl -X GET "https://api.example.com/v1/wallet/external" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

In this example:

User delegated 5000 USDC initially
Platform has spent 1500 USDC on card transactions
Remaining allowance: 3500 USDC

When allowance runs low, prompt users to redelegate with a higher amount. The redelegation process follows the same flow as initial delegation.

Redelegation

Users need to redelegate when:

Allowance Exhausted

When card transactions have consumed the full delegated allowance, users must redelegate to continue using card payments.When to Prompt: Alert users when allowance drops below 10% of original amount or a threshold you define.

Increase Spending Limit

Users may want to increase their allowance for convenience or to accommodate larger purchases.Example: User initially delegated

500 but wants to increase to

2000 for an upcoming trip.

Smart Contract Upgrade

When platform upgrades smart contracts, users must redelegate to the new contract address.Notification: Platform will notify integrators of contract upgrades with migration timeline.

Network Migration

If user wants to switch from one network to another (e.g., Ethereum to Linea for lower fees).Process: Delegate from wallet on new network. Old delegation remains until allowance exhausted.

Redelegation Process: Identical to initial delegation. Follow the Delegation Guide with updated allowance amount.

Priority Management

When users have multiple external wallets registered, priority determines:

Which wallet is charged for card transactions
Which wallet receives credit/reward withdrawals

curl -X GET "https://api.example.com/v1/wallet/external/priority" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

Priority Rules:

Lower numbers = higher priority (1 is used before 2)
For card payments: Platform charges priority 1 wallet first, moves to 2 if insufficient
For withdrawals: Platform sends to priority 1 wallet first, moves to 2 if transaction fails

Learn more about Priority Management →

Credit and Reward Wallets

In non-custodial environments, credit and reward wallets work differently from custodial mode:

Viewing Balances

curl -X GET "https://api.example.com/v1/wallet/credit" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

Withdrawing to External Wallets

Estimate Fees
Execute Withdrawal

Credit

curl -X GET "https://api.example.com/v1/wallet/credit/withdraw-estimation" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

Reward

curl -X GET "https://api.example.com/v1/wallet/reward/withdraw-estimation" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

Response

{
  "wei": "6219123007416",
  "eth": "0.000006219123007416",
  "usdc": "0.01644666445335518319452825472"
}

Platform covers gas fees. User receives full withdrawal amount.

Credit

curl -X POST "https://api.example.com/v1/wallet/credit/withdraw" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100"}'

Reward

curl -X POST "https://api.example.com/v1/wallet/reward/withdraw" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": "50"}'

Response

{
  "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638"
}

Funds are sent to highest priority external wallet registered by the user.

Credit and reward withdrawals currently support Linea network only. Funds are sent to the user’s highest priority Linea external wallet.

Error Handling

Insufficient Allowance

{
  "error": "Insufficient allowance",
  "code": "WALLET_INSUFFICIENT_ALLOWANCE",
  "message": "Delegated allowance is insufficient for this transaction"
}

Solution: Prompt user to redelegate with higher allowance.

No External Wallet Registered

{
  "error": "No external wallet",
  "code": "WALLET_NO_EXTERNAL",
  "message": "User has not registered an external wallet"
}

Solution: Guide user through delegation flow to register their first external wallet.

Allowance Expired

{
  "error": "Delegation expired",
  "code": "WALLET_DELEGATION_EXPIRED",
  "message": "Wallet delegation has expired and must be renewed"
}

Solution: Prompt user to redelegate. Follow standard delegation flow.

Best Practices

Proactive Allowance Monitoring

Monitor allowance levels and alert users when allowance drops below 20% of original amount. Suggest redelegation before complete exhaustion.

Clear Delegation UX

Explain delegation clearly: users grant spending authority but maintain custody. Use analogies like “credit card limit” to make the concept accessible.

Display Allowance Visually

Show allowance status with progress bars or percentage indicators. Make it easy for users to understand their remaining spending capacity.

Support Multiple Wallets

Allow users to register multiple external wallets for redundancy and flexibility. Implement priority management to let users control preferences.

Transparent Fee Display

Show withdrawal fee estimates before users confirm credit/reward withdrawals. Transparency builds trust.

Blockchain Explorer Links

Provide blockchain explorer links for delegation transactions and withdrawals so users can verify on-chain activity.

Security Considerations

Smart Contract Risk: While delegation is enforced by blockchain smart contracts, users should verify contract addresses before approving. Display contract addresses clearly in your UI.

Allowance Limit Strategy: Recommend users start with conservative allowances (1-3 months of expected spending) and increase as needed. This limits exposure if private keys are compromised.

Wallet Software Security: Users are responsible for securing their Web3 wallet software and seed phrases. Provide educational resources about wallet security best practices.

US Environment Routing

For US-based users, route requests to the US environment:

Header Method
Query Parameter Method

curl -X GET "https://api.example.com/v1/wallet/external" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "x-us-env: true"

curl -X GET "https://api.example.com/v1/wallet/external?region=us" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

The US environment automatically routes Linea network operations to US-specific infrastructure.

Next Steps

Delegation Guide

Complete guide to implementing wallet delegation

External Wallets

View and manage registered external wallets

Priority Management

Control wallet priority for payments and withdrawals

API Reference

Complete API documentation

Getting Started

OAuth 2.0 & Authentication

User Management

Wallet Management

Non-Custodial Wallet Delegation

Card Operations

​What are Non-Custodial Wallets?

​Key Benefits

Self-Custody

Web3 Native

Flexible Withdrawals

On-Chain Transparency

​How It Works

​Delegation Flow

​External Wallets vs Credit/Reward Withdrawals

​External Wallets (Card Funding)

​Credit/Reward Withdrawals

​Supported Networks

​Delegation Security Model

​What Users Control

Private Keys

Spending Limits

Revocation

Asset Custody

​What Platform Can Do

Charge for Card Transactions

​What Platform Cannot Do

​Common Workflows

​Workflow 1: Initial Wallet Delegation

​Workflow 2: Credit Withdrawal to External Wallet

​Allowance Management

​How Allowances Work

​Redelegation

​Priority Management

​Credit and Reward Wallets

​Viewing Balances

​Withdrawing to External Wallets

​Error Handling

​Insufficient Allowance

​No External Wallet Registered

​Allowance Expired

​Best Practices

Proactive Allowance Monitoring

Clear Delegation UX

Display Allowance Visually

Support Multiple Wallets

Transparent Fee Display

Blockchain Explorer Links

​Security Considerations

​US Environment Routing

​Next Steps

Delegation Guide

External Wallets

Priority Management

API Reference

What are Non-Custodial Wallets?

Key Benefits

How It Works

Delegation Flow

External Wallets vs Credit/Reward Withdrawals

External Wallets (Card Funding)

Credit/Reward Withdrawals

Supported Networks

Delegation Security Model

What Users Control

What Platform Can Do

What Platform Cannot Do

Common Workflows

Workflow 1: Initial Wallet Delegation

Workflow 2: Credit Withdrawal to External Wallet

Allowance Management

How Allowances Work

Redelegation

Priority Management

Credit and Reward Wallets

Viewing Balances

Withdrawing to External Wallets

Error Handling

Insufficient Allowance

No External Wallet Registered

Allowance Expired

Best Practices

Security Considerations

US Environment Routing

Next Steps