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

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
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 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:

// 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:

// 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);

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.

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)

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

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.

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.

Recovery Key Issues

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 for detailed endpoint information
• Support: Contact our support team for assistance
• Community: Join our Discord server for tips and discussions

Next Steps

Ready to get started with Self-Custodial Wallet?

1. Upgrade to API Key V2
2. Learn about Payouts
3. Explore API Endpoints
4. Check Supported Cryptocurrencies