Custodial Wallets

What are Custodial Wallets?

Custodial wallets are platform-managed blockchain wallets where private keys are securely held and managed by the service. Users interact with these wallets through simple API calls without needing wallet software, browser extensions, or blockchain knowledge.

Key Benefits

Simplified UX

No wallet software required. Users interact through your application’s familiar interface.

Secure Key Management

Private keys are encrypted and managed using enterprise-grade security infrastructure.

Whitelist Security

Withdrawals restricted to pre-approved addresses, adding an extra security layer.

Multi-Network Support

Support for multiple blockchains from a single integration point.

Custodial Wallet Types

Internal Wallets

User-specific wallets holding cryptocurrency across various networks. Each user can have multiple internal wallets for different currencies and networks. Capabilities:

Create wallets on supported networks
Receive crypto deposits
Check balances
Link to card for payments
Withdraw to whitelisted addresses

Learn more about Internal Wallets →

Credit Wallets

Platform wallets holding user credits from refunds, transfers, or top-ups. Each user has one credit wallet per supported currency. Capabilities:

View balance
Withdraw to whitelisted addresses (custodial environments)
Use for card payments

Reward Wallets

Platform wallets accumulating cashback, promotions, and incentives. Each user has one reward wallet per supported currency. Capabilities:

View balance
Withdraw to whitelisted addresses (custodial environments)
Use for card payments

Security Model

Custodial wallets implement a whitelist-based security model:

How Whitelisting Works

Add Address: User submits external wallet address with beneficiary details
Verification: Platform validates address format and network compatibility
Approval: Address is added to user’s approved whitelist
Withdrawal: User can only withdraw to addresses on their whitelist
Tracking: All withdrawals are tracked with beneficiary information

Whitelist addresses cannot be modified once added. To change an address, remove the old entry and add a new one. Always verify addresses before whitelisting to prevent loss of funds.

Card Linking

Internal wallets can be linked to cards for seamless cryptocurrency payments:

Create Internal Wallet

Set up an internal wallet for the desired network and currency.

Fund Wallet

Deposit cryptocurrency to the wallet address.

Link to Card

Connect the wallet to the user’s card using the card linking API.

Set Priority

Configure which wallet is charged first when multiple wallets are linked.

Make Payments

Card transactions automatically deduct from linked wallets based on priority.

Learn more about Card Linking →

Supported Networks

Network	Currencies	Memo Required	Notes
Linea	USDC, USDT	No	Primary network, US routing available
Ethereum	USDC, USDT	No	Mainnet support
Solana	USDC, USDT, SOL	No	SPL token support
XRP Ledger	XRP	Yes	Destination tag required for all transactions
Bitcoin	BTC	No	Native Bitcoin support

Networks requiring memos (like XRP Ledger) return both address and addressMemo fields. Both are required for deposits and withdrawals.

Common Workflows

Workflow 1: Simple Deposit and Card Payment

Workflow 2: Withdrawal to External Address

Priority Management

When multiple wallets are linked to a card, priority determines the charge order:

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

How Priority Works:

Card transaction initiated
System attempts to charge wallet with priority 1
If insufficient balance, moves to priority 2
Process continues until transaction succeeds or all wallets exhausted

Learn more about Priority Management →

Transaction History

View transaction history for any custodial wallet:

curl -X GET "https://api.example.com/v1/wallet/history?walletId=098aeb90&walletType=INTERNAL&walletCurrency=usdc&page=0" \
  -H "x-client-key: YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

History returns up to 10 transactions per page. Use the page parameter (zero-indexed) for pagination.

Error Handling

Common error scenarios and how to handle them:

Insufficient Balance

{
  "error": "Insufficient balance",
  "code": "WALLET_INSUFFICIENT_BALANCE",
  "message": "Wallet balance is insufficient for this withdrawal"
}

Solution: Check wallet balance before attempting withdrawal or prompt user to fund wallet.

Address Not Whitelisted

{
  "error": "Address not whitelisted",
  "code": "WALLET_ADDRESS_NOT_WHITELISTED",
  "message": "Withdrawal address must be whitelisted before use"
}

Solution: Add address to whitelist first using POST /v1/wallet/whitelist.

Invalid Network

{
  "error": "Unsupported network",
  "code": "WALLET_UNSUPPORTED_NETWORK",
  "message": "The specified network is not supported"
}

Solution: Verify network name against supported networks list and ensure proper environment configuration.

Maximum Linked Wallets

{
  "error": "Maximum linked wallets reached",
  "code": "WALLET_MAX_LINKED",
  "message": "User has reached the maximum number of linked wallets (5)"
}

Solution: Unlink an existing wallet before linking a new one, or prompt user to manage their linked wallets.

Best Practices

Always Verify Addresses

Before adding an address to the whitelist, verify it’s correct and on the intended network. Blockchain transactions are irreversible.

Use Descriptive Whitelist Names

Give each whitelisted address a clear, descriptive name (e.g., “Coinbase Main Account” or “Hardware Wallet #1”) to help users identify addresses later.

Implement Balance Checks

Check wallet balance before initiating withdrawals to provide better user feedback and avoid failed transactions.

Handle Network-Specific Requirements

Some networks (like XRP) require memos/destination tags. Always include these fields when present.

Set Sensible Priority Orders

Configure wallet priority based on user preferences or fee optimization. Update priority when users change their preferences.

Display Transaction History

Show transaction history to help users track their activity and verify transactions.

Implement Withdrawal Limits

Consider implementing daily/monthly withdrawal limits for additional security, especially for high-value accounts.

US Environment Routing

For US-based users and compliance requirements, use the US environment:

Header Method
Query Parameter Method

curl -X GET "https://api.example.com/v1/wallet/internal" \
  -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/internal?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 while maintaining full API compatibility.

Next Steps

Internal Wallets

Learn how to create and manage internal wallets

Card Linking

Connect wallets to cards for seamless payments

Whitelist Management

Manage approved withdrawal addresses

Withdrawals

Execute withdrawals to external addresses

Getting Started

OAuth 2.0 & Authentication

User Management

Wallet Management

Non-Custodial Wallet Delegation

Card Operations

What are Custodial Wallets?

Key Benefits

Simplified UX

Secure Key Management

Whitelist Security

Multi-Network Support

Custodial Wallet Types

Internal Wallets

Credit Wallets

Reward Wallets

Security Model

How Whitelisting Works

Card Linking

Supported Networks

Common Workflows

Workflow 1: Simple Deposit and Card Payment

Workflow 2: Withdrawal to External Address

Priority Management

Transaction History

Error Handling

Insufficient Balance

Address Not Whitelisted

Invalid Network

Maximum Linked Wallets

Best Practices

US Environment Routing

Next Steps

Internal Wallets

Card Linking

Whitelist Management

Withdrawals

Getting Started

OAuth 2.0 & Authentication

User Management

Wallet Management

Non-Custodial Wallet Delegation

Card Operations

​What are Custodial Wallets?

​Key Benefits

Simplified UX

Secure Key Management

Whitelist Security

Multi-Network Support

​Custodial Wallet Types

​Internal Wallets

​Credit Wallets

​Reward Wallets

​Security Model

​How Whitelisting Works

​Card Linking

​Supported Networks

​Common Workflows

​Workflow 1: Simple Deposit and Card Payment

​Workflow 2: Withdrawal to External Address

​Priority Management

​Transaction History

​Error Handling

​Insufficient Balance

​Address Not Whitelisted

​Invalid Network

​Maximum Linked Wallets

​Best Practices

​US Environment Routing

​Next Steps

Internal Wallets

Card Linking

Whitelist Management

Withdrawals

What are Custodial Wallets?

Key Benefits

Custodial Wallet Types

Internal Wallets

Credit Wallets

Reward Wallets

Security Model

How Whitelisting Works

Card Linking

Supported Networks

Common Workflows

Workflow 1: Simple Deposit and Card Payment

Workflow 2: Withdrawal to External Address

Priority Management

Transaction History

Error Handling

Insufficient Balance

Address Not Whitelisted

Invalid Network

Maximum Linked Wallets

Best Practices

US Environment Routing

Next Steps