> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegation Overview

> Understanding non-custodial wallet delegation for card payments

## What is Delegation?

Delegation enables users with non-custodial wallets to grant spending authority to the platform for card payments while maintaining full custody of their assets.

In traditional custodial systems, users transfer funds to the platform, giving up control. With delegation, users keep their private keys and assets in their own wallets, only granting permission for the platform to spend up to a specified limit.

<Note>
  Users maintain full custody of their funds. The platform can only spend within approved limits, and users can revoke access at any time through their blockchain wallet.
</Note>

## Why Delegation?

### Non-Custodial Benefits

<CardGroup cols={2}>
  <Card title="User Maintains Control" icon="shield-check">
    Users keep their private keys and full custody of funds. No need to transfer assets to the platform.
  </Card>

  <Card title="Transparent Spending" icon="chart-line">
    All transactions are on-chain and verifiable. Users can monitor spending limits and transaction history.
  </Card>

  <Card title="Reduced Platform Risk" icon="lock">
    Platform doesn't hold user funds, reducing regulatory complexity and security liability.
  </Card>

  <Card title="Revocable Access" icon="rotate-left">
    Users can revoke or modify spending authority at any time through their wallet.
  </Card>
</CardGroup>

## Key Concepts

### External Wallet

A user-controlled wallet where private keys are managed by the user through wallet applications like:

* **EVM Chains**: MetaMask, WalletConnect, Coinbase Wallet, Rainbow Wallet
* **Solana**: Phantom, Solflare, Backpack

The platform never has access to private keys or full control over these wallets.

### Allowance

The maximum amount the platform can spend from a delegated wallet. This is set by the user during the delegation process.

**Example**: User approves a 5,000 USDC allowance. The platform can charge up to 5,000 USDC for card purchases, but no more.

<Tip>
  Users can increase or decrease their allowance by redelegating their wallet with a new amount.
</Tip>

### Priority

When users delegate multiple wallets, priority determines the order in which wallets are charged for transactions.

* **Lower number = Higher priority** (Priority 1 is charged before Priority 2)
* Platform attempts wallets in order until transaction succeeds
* Useful for managing balances across multiple wallets or optimizing gas fees

**Example Priority Configuration**:

```
Priority 1: Linea USDC wallet (5,000 USDC)
Priority 2: Ethereum USDT wallet (2,000 USDT)
Priority 3: Solana USDC wallet (10,000 USDC)
```

### Spending Authority

On-chain approval that grants the platform's smart contracts permission to transfer tokens from the user's wallet up to the allowance limit.

* **EVM Chains**: Implemented via ERC20 `approve()` function
* **Solana**: Implemented via SPL Token delegation

## Supported Networks and Currencies

<Tabs>
  <Tab title="Linea">
    **Network**: Linea (Layer 2)
    **Chain ID**: 59144
    **Currencies**: USDC, USDT

    Primary network for most integrations. Low gas fees and fast transactions.

    <Note>
      For US-specific routing, set the `x-us-env: true` header or `region=us` query parameter.
    </Note>
  </Tab>

  <Tab title="Ethereum">
    **Network**: Ethereum Mainnet
    **Chain ID**: 1
    **Currencies**: USDC, USDT

    Standard Ethereum mainnet with broader wallet support.
  </Tab>

  <Tab title="Solana">
    **Network**: Solana Mainnet
    **Currencies**: USDC, USDT

    High-performance blockchain with low transaction costs.
  </Tab>
</Tabs>

## Use Cases

### Personal Card Payments

Enable users to make card purchases directly from their non-custodial wallets without depositing funds to the platform.

1. User delegates wallet with 5,000 USDC allowance
2. User makes \$50 purchase with physical/virtual card
3. Platform charges \$50 from delegated wallet
4. Remaining allowance: 4,950 USDC

### Multi-Wallet Management

Users can delegate multiple wallets and set priorities for flexible fund management.

**Scenario**: User has funds across multiple networks

* High-priority wallet for frequent transactions (Linea USDC)
* Backup wallet for when primary runs low (Ethereum USDC)
* Long-term holdings wallet with higher limits (Solana USDC)

### Business Expense Cards

Companies can delegate corporate wallets to employee cards with controlled spending limits.

* Each employee gets a card linked to company wallet
* Spending limits enforced on-chain
* All transactions transparent and auditable
* Company maintains full custody of funds

## How Delegation Works

<Steps>
  <Step title="Backend: Request Token">
    Your backend calls [`GET /v1/delegation/token`](/api-reference/delegation/token) to generate a single-use delegation token.
  </Step>

  <Step title="Frontend: Wallet Interaction">
    Your frontend application:

    1. Connects user's wallet (MetaMask, Phantom, etc.)
    2. Requests blockchain approval transaction
    3. User signs message to prove wallet ownership
    4. Collects transaction data for next step
  </Step>

  <Step title="Backend: Submit Proof">
    Your backend submits the delegation proof to finalize registration using [`POST /v1/delegation/evm/post-approval`](/api-reference/delegation/evm-post-approval) for Linea/Ethereum or [`POST /v1/delegation/solana/post-approval`](/api-reference/delegation/solana-post-approval) for Solana.
  </Step>

  <Step title="Verify Registration">
    Confirm wallet was successfully registered using [`GET /v1/wallet/external`](/api-reference/wallet/external).
  </Step>
</Steps>

<Note>
  See the [Implementation Guide](/guides/delegation/implementation) for detailed step-by-step instructions with code examples.
</Note>

## Security Model

### What the Platform CAN Do

* Charge up to the approved allowance for card transactions
* Initiate transactions from delegated wallet within spending limit
* View wallet balance and allowance on-chain

### What the Platform CANNOT Do

* Access or store private keys
* Transfer more than the approved allowance
* Move funds outside of approved use cases
* Prevent user from revoking access

<Warning>
  The platform operates within strict on-chain constraints. All spending authority is enforced by smart contracts, not the platform.
</Warning>

## Next Steps

Ready to implement delegation? Here's your learning path:

<CardGroup cols={2}>
  <Card title="Implementation Guide" icon="code" href="/guides/delegation/implementation">
    Complete 3-step implementation with code examples for backend and frontend.
  </Card>

  <Card title="EVM Chains (Linea/Ethereum)" icon="ethereum" href="/guides/delegation/evm-chains">
    EVM-specific implementation details including ERC20 approve and SIWE signing.
  </Card>

  <Card title="Solana Implementation" icon="circle-s" href="/guides/delegation/solana">
    Solana-specific implementation with SPL Token delegation examples.
  </Card>

  <Card title="Priority Management" icon="ranking-star" href="/guides/delegation/priority">
    Learn how to manage and optimize wallet charging priority.
  </Card>
</CardGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can users revoke delegation?">
    Yes, users can revoke spending authority at any time directly through their wallet by setting the allowance to zero or switching to a different spender address.
  </Accordion>

  <Accordion title="What happens if allowance runs out?">
    Transactions will fail if the remaining allowance is insufficient. Users will need to redelegate their wallet with a higher allowance to continue making purchases.
  </Accordion>

  <Accordion title="Can users delegate the same wallet to multiple platforms?">
    Yes, but each platform would need its own approval. ERC20 approvals are per-spender, so multiple platforms can have different allowances for the same wallet.
  </Accordion>

  <Accordion title="Are there gas fees for delegation?">
    Yes, users pay standard gas fees for the approval transaction on their chosen blockchain. Linea typically has lower gas fees than Ethereum mainnet.
  </Accordion>

  <Accordion title="How long does delegation take?">
    The entire process typically takes 2-5 minutes, depending on blockchain confirmation times and network congestion.
  </Accordion>
</AccordionGroup>