# Self-Custodial Wallet

The Self-Custodial Wallet lets you hold your own private keys while BlockBee handles payment routing and automated payouts. BlockBee never has access to your funds.

## What is Self-Custodial Wallet?

The Self-Custodial Wallet is a cryptocurrency wallet where you control the private keys. BlockBee provides the infrastructure for receiving payments and sending payouts, but cannot move your funds without your API key.

### Key Features

- **Full Fund Control**: You own and control your private keys
- **Automated Payouts**: Send payments to multiple addresses automatically
- **Advanced Security**: Multi-layer cryptography and recovery mechanisms
- **Real-time Monitoring**: Track all transactions and balances
- **Multi-Cryptocurrency Support**: Manage multiple cryptocurrencies in one wallet

## How Self-Custodial Wallet Works

BlockBee uses **Threshold Signature Scheme (TSS) cryptography** so that no single party — including BlockBee — can move funds unilaterally.

### The Three-Share System

When you upgrade to API Key V2, our system generates **three shares**, with at least **two required for transaction signatures**:

1. **BlockBee's Encrypted Share**: We securely store one encrypted share
2. **Your API Key**: One of your two shares
3. **Your Recovery Key**: Your second share for emergency access

This covers all addresses across supported chains for your payout wallet, and achieves three goals:

- **BlockBee cannot access funds unilaterally** — your API key is required for every transaction
- **Automated payouts** — send a payout with a single API call using your API key
- **Recovery** — if you lose your API key, use your Recovery Key to regenerate it

> **WARNING**
>If you lose both your API Key V2 and Recovery Key, your Self-Custodial Wallet funds are permanently inaccessible. BlockBee cannot recover them. Store both keys securely before using this feature.


## Getting Started

### 1. Upgrade to API Key V2

To begin using Self-Custodial Wallet, upgrade to API Key V2 via your API key settings:

1. Log into your [BlockBee Dashboard](https://dash.blockbee.io/)
2. Navigate to API Keys section
3. Generate a new API Key V2
4. **Securely store both your new API key and recovery key** - especially the recovery key, which is crucial for API key resetting if needed

### 2. Access Your Self-Custodial Wallet

Once you have API Key V2, navigate to [Wallet](https://dash.blockbee.io/wallet) to view and fund your blockchain-specific addresses for payouts, or opt to directly receive your BlockBee payments.

To route incoming BlockBee payments directly to your Payouts wallet, use the "Set Self-Custodial Wallet" option on that page.

### 3. Fund Your Wallet

Send cryptocurrency to your Self-Custodial Wallet address:

```javascript
// Get your wallet address
const response = await fetch('https://api.blockbee.io/btc/payout/address/?apikey=YOUR_API_KEY_V2');
const walletInfo = await response.json();
console.log('Your wallet address:', walletInfo.address);
```

### 4. Check Your Balance

Check available balances and estimated blockchain fees before sending a payout:

```javascript
// Check balance
const balanceResponse = await fetch('https://api.blockbee.io/btc/payout/balance/?apikey=YOUR_API_KEY_V2');
const balance = await balanceResponse.json();
console.log('Available balance:', balance.balance);
```

> **WARNING**
>Your balance must cover both the payout amount and the blockchain fee. For token transfers on Ethereum and similar networks, you also need the native coin (ETH, BNB, etc.) in your wallet to pay gas. Payouts fail if either balance is insufficient.


## Use Cases

### Automated Payouts
Send payments to multiple addresses automatically. Run payouts from the dashboard or via the API — up to **100 addresses in a single request**.

> **INFO**
>For detailed information about payout workflows, API endpoints, and code examples, see our [Payouts Guide](/get-started/payouts).


### Platform Fund Distribution
Perfect for platforms that need to distribute funds to users:

- **Gaming Platforms**: Reward distribution to players
- **Freelance Platforms**: Payment to contractors
- **Investment Platforms**: Dividend distributions
- **Content Platforms**: Creator payments

### Business Operations
Streamline business cryptocurrency operations:

- **Payroll**: Automated salary payments in cryptocurrency
- **Vendor Payments**: Regular payments to suppliers
- **Refunds**: Automated refund processing
- **Rewards**: Customer loyalty and referral programs

## Security Features

### Threshold Signature Scheme (TSS) Cryptography
Transactions require at least two of the three key shares. BlockBee holds one share; you hold two. No single party can move funds alone.

### Three-Share Recovery System
The system generates three shares with at least two required for transaction signatures:
- BlockBee's encrypted share (securely stored)
- Your API key (one of your shares)
- Your recovery key (your second share for emergency access)

> **WARNING**
>If you lose both your API Key V2 and Recovery Key, access to your Self-Custodial Wallet is permanently lost. BlockBee cannot recover it.


### Secure Infrastructure
BlockBee stores its key share encrypted and runs regular security audits across all infrastructure.

## Best Practices

### 1. Secure API Key Management
- Store API Key V2 securely
- Never expose it in client-side code
- Use environment variables in production

### 2. Recovery Key Safety
- **Store both API Key V2 and Recovery Key securely** - You need both to maintain access
- Consider using a hardware security module (HSM) for maximum security
- Test recovery procedures periodically

> **WARNING**
>If you lose both keys, access to your Self-Custodial Wallet is permanently lost.


### 3. Balance Management
- Always maintain sufficient balance for operations
- Monitor fees and transaction costs
- Set up alerts for low balance

### 4. Transaction Monitoring
- Regularly check payout status
- Monitor for failed transactions
- Set up webhooks for real-time updates

## Supported Cryptocurrencies

This feature is available on all **Ethereum Virtual Machine (EVM) compatible chains**, **Tron**, as well as on the **Bitcoin (BTC)**, **Litecoin (LTC)**, and **Bitcoin Cash (BCH)** networks.

> **WARNING**
>**Note**: This feature is not available on Doge network due to technical limitations of the Doge node.


## Migration from API Key V1

If you're currently using API Key V1, here's how to migrate:

1. **Generate API Key V2** in your dashboard
2. **Update your code** to use the new API key
3. **Test with small amounts** to ensure everything works
4. **Gradually migrate** your operations to V2
5. **Keep V1 active** during transition period
6. **Deactivate V1** once migration is complete

## Troubleshooting

For detailed information about common errors and their solutions, see our [Error Handling Guide](/get-started/error-handling).

### Recovery Key Issues

> **WARNING**
>**CRITICAL** If you lose your Recovery Key, you will not be able to regenerate your API Key V2. If you lose both your API Key V2 and Recovery Key, you will permanently lose access to your Self-Custodial Wallet as BlockBee cannot access it without these keys.


If you've lost your Recovery Key but still have your API Key V2, contact BlockBee support immediately for assistance.

### Getting Help

- **Documentation**: Check our [API Reference](/api/create-payment-address) for detailed endpoint information
- **Support**: Contact our support team for assistance
- **Community:** Join our [Discord server](https://discord.gg/pQaJ32SGrR) for tips and discussions

## Next Steps

Ready to get started with Self-Custodial Wallet?

1. [Upgrade to API Key V2](/get-started/authentication)
2. [Learn about Payouts](/get-started/payouts)
3. [Explore API Endpoints](/api/get-wallet-address)
4. [Check Supported Cryptocurrencies](https://blockbee.io/cryptocurrencies)