Skip to main content

​
Introduction

The platform supports two distinct wallet management models, each designed for different use cases and user experiences. Understanding these models is essential for choosing the right integration approach for your application.

​
Wallet Models

Custodial Wallets

Platform-managed keys with simplified UX. Ideal for users who want convenience without managing private keys.

Non-Custodial Wallets

User-controlled keys with full self-custody. Perfect for users who want complete control of their assets.

​
Custodial vs Non-Custodial

FeatureCustodialNon-Custodial
Key ManagementPlatform manages private keysUser controls private keys
User ExperienceSimple, no wallet software neededRequires wallet software (MetaMask, Phantom)
Security ModelPlatform-secured, whitelist-basedUser-secured, delegation-based
WithdrawalsWhitelist addresses onlyAny address (subject to allowance)
Card PaymentsDirect wallet linkingDelegation approval required
Best ForMainstream users, simplified onboardingCrypto-native users, DeFi integration

​
When to Use Each Model

​
Choose Custodial When:

  • Your users are new to cryptocurrency
  • You want the simplest possible user experience
  • You need to control withdrawal destinations
  • Your users don’t want to manage wallet software
  • Compliance requires strict address whitelisting

​
Choose Non-Custodial When:

  • Your users are cryptocurrency-experienced
  • Self-custody is a core value proposition
  • Users need flexibility in withdrawal destinations
  • You’re integrating with existing Web3 applications
  • Users demand full control over their private keys

​
Environment-Specific Features

Both wallet models support environment-specific configuration through the x-us-env header or region=us query parameter:
Default environment. All wallet operations route to global infrastructure.
GET /v1/wallet/internal
Headers:
  x-client-key: YOUR_PUBLIC_KEY
  Authorization: Bearer USER_ACCESS_TOKEN
The x-us-env: true header or region=us parameter automatically routes Linea network operations to the US-specific Linea environment. This ensures compliance with regional requirements.

​
Wallet Types

Both custodial and non-custodial models support multiple wallet types:

​
Internal Wallets (Custodial)

Platform-managed wallets holding user crypto assets. Support multiple networks and currencies. Can be linked to cards for payments. Key Operations:
  • Create new internal wallets
  • View balances across networks
  • Link wallets to cards
  • Withdraw to whitelisted addresses
Learn more about Internal Wallets →

​
External Wallets (Non-Custodial)

User-controlled wallets registered via delegation. Users maintain full custody while granting spending authority for card payments. Key Operations:
  • Register external wallets via delegation
  • View allowances and balances
  • Manage withdrawal priority
  • Withdraw credit/rewards to external wallets
Learn more about External Wallets →

​
Credit Wallets

Platform wallets holding user credits from various sources (refunds, top-ups, transfers). Available in both custodial and non-custodial environments. Key Operations:
  • View credit balance
  • Withdraw to whitelisted addresses (custodial)
  • Withdraw to registered external wallets (non-custodial)

​
Reward Wallets

Platform wallets accumulating cashback, incentives, and promotional credits. Similar to credit wallets but specifically for earned rewards. Key Operations:
  • View reward balance
  • Withdraw to whitelisted addresses (custodial)
  • Withdraw to registered external wallets (non-custodial)

​
Supported Networks and Currencies

The platform supports multiple blockchain networks and cryptocurrencies:
NetworkCurrenciesTypeNotes
LineaUSDC, USDTEVMPrimary network, US routing available
EthereumUSDC, USDTEVMMainnet support
SolanaUSDC, USDTNon-EVMSPL token support
XRP LedgerXRPNon-EVMRequires destination tags (memo)
Network and currency availability may vary by environment and configuration. Contact support to confirm specific network availability for your integration.

​
Common Operations

​
Transaction History

View transaction history for any wallet type: 
GET /v1/wallet/history?walletId={id}&walletType=INTERNAL&page=0
API Reference: GET /v1/wallet/history Supported Wallet Types:
  • CREDIT - Credit wallet transactions
  • REWARD - Reward wallet transactions
  • INTERNAL - Internal wallet transactions (requires walletCurrency parameter)
Response: 
[
  {
    "name": "Card purchase",
    "amount": "25.50",
    "currency": "usdc",
    "sign": "debit",
    "date": "2024-02-02T15:01:09.091Z"
  },
  {
    "name": "Wallet deposit",
    "amount": "100.00",
    "currency": "usdc",
    "sign": "credit",
    "date": "2024-02-01T10:30:00.000Z"
  }
]
Transaction history is paginated with 10 transactions per page. Use the page parameter (zero-indexed) to navigate through history.

​
Priority Management

Both custodial and non-custodial models support priority ordering for multiple wallets: Custodial: Control which linked wallet is charged first for card transactions. Non-Custodial: Control which external wallet receives credit/reward withdrawals first. Priority works the same way in both models:
  • Lower numbers = higher priority (1 is charged/paid before 2)
  • Platform attempts wallets in priority order
  • Insufficient balance/allowance triggers next priority wallet

​
Security Best Practices

​
Custodial Model Security

Whitelist Management

Only whitelist addresses you control. Verify each address carefully before adding to prevent loss of funds.

Beneficiary Verification

Ensure beneficiary names match the actual owner of withdrawal addresses for compliance tracking.

​
Non-Custodial Model Security

Delegation Limits

Set appropriate allowance limits when delegating. You can always increase limits later through redelegation.

Signature Verification

Never share private keys. The platform only requires transaction signatures, not private key access.

​
Next Steps

Custodial Wallets

Explore custodial wallet operations including internal wallets, card linking, whitelists, and withdrawals.

Non-Custodial Wallets

Learn about external wallet registration, delegation, and priority management.

Delegation Guide

Detailed guide on implementing the delegation flow for non-custodial wallets.

API Reference

Complete API documentation for all wallet endpoints.