BlockBee's Self-Custodial Wallet is an advanced feature that gives you full control over your cryptocurrency funds while maintaining enterprise-grade security. This system is designed for users who need automated payouts and advanced fund management capabilities.
What is Self-Custodial Wallet?
The Self-Custodial Wallet is your own cryptocurrency wallet managed by BlockBee with advanced security features. Unlike traditional custodial solutions, you maintain full control over your funds while benefiting from BlockBee's infrastructure and security.
At BlockBee, our steadfast belief has always been in empowering our customers with full control over their funds, firmly upholding a no-control policy on our end. The Self-Custodial Wallet represents our solution to provide automated payouts while maintaining this fundamental principle.
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
By integrating Threshold Signature Scheme (TSS) cryptography, we've struck an optimal balance between ensuring security, maintaining our foundational principle of non-control over customer funds, and providing a seamless experience.
The Three-Share System
When you upgrade to API Key V2, our system generates three shares, with at least two required for transaction signatures:
- BlockBee's Encrypted Share: We securely store one encrypted share
- Your API Key: One of your two shares
- Your Recovery Key: Your second share for emergency access
This encryption covers all addresses across supported chains for your payout wallet, effectively meeting our three primary objectives:
- Autonomy Over Funds: Our platform is designed to be incapable of accessing your funds without explicit consent
- Automated Payouts: Facilitate payouts through a simple API call, requiring just your API key to access funds
- Secure Recovery: With the safeguarding of your recovery key, access to your funds remains secure, even if you lose your API key
With Great Power Comes Great Responsibility: This innovation necessitates a significant compromise: the impossibility of fund recovery should both your API key and recovery key be lost. The onus is on you to meticulously secure these keys, as their loss equates to irrevocable fund loss.
Getting Started
1. Upgrade to API Key V2
To begin using Self-Custodial Wallet, upgrade to API Key V2 via your API key settings:
- Log into your BlockBee Dashboard
- Navigate to API Keys section
- Generate a new API Key V2
- 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.
For direct BlockBee payment receipts, a "Set Self-Custodial Wallet" option has been added, enabling fund redirection to your Payouts wallet seamlessly.
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
Prior to payout execution, you can review available balances and estimated blockchain fees, ensuring informed transactions:
// 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);Important: Sufficient funds must cover both the payout and the associated blockchain fees, as our system does not subsidize these expenses. For token transfers over networks like Ethereum, adequate ETH (or the respective base blockchain coin) is necessary to cover transaction fees, else payout attempts will fail.
Use Cases
Automated Payouts
Send payments to multiple addresses automatically through our comprehensive payout system. Payouts may be conducted via the Payouts page or through our API endpoints, supporting payout executions to up to 100 addresses in a single request.
For detailed information about payout workflows, API endpoints, and code examples, see our Payouts Guide.
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
Your funds are protected by advanced TSS cryptography, ensuring maximum security while maintaining your autonomy over funds.
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)
CRITICAL If you lose both your API Key V2 and Recovery Key, you will permanently lose access to your Self-Custodial Wallet. BlockBee cannot access your wallet without these keys.
Secure Infrastructure
BlockBee's infrastructure is designed with security-first principles, including:
- Encrypted storage
- Secure key management
- Regular security audits
- Compliance with industry standards
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, you will permanently lose access to your Self-Custodial Wallet
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.
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:
- Generate API Key V2 in your dashboard
- Update your code to use the new API key
- Test with small amounts to ensure everything works
- Gradually migrate your operations to V2
- Keep V1 active during transition period
- Deactivate V1 once migration is complete
Troubleshooting
For detailed information about common errors and their solutions, see our Error Handling Guide.
Recovery Key Issues
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 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?