Self-Custodial Wallet Payouts

BlockBee's Self-Custodial Wallet system allows you to automate sending cryptocurrency payments to multiple addresses. This system requires API Key V2 and provides you with full control over your funds while maintaining security through advanced cryptography.

Overview

Key Concepts

Self-Custodial Wallet: Your own cryptocurrency wallet managed by BlockBee with advanced security features
Payout Request: Individual payment instruction (address + amount) for a specific cryptocurrency
Payout: Collection of Payout Requests that are processed together
API Key V2: Required authentication for Self-Custodial Wallet operations

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.

How It Works

Create Payout Requests: Define the addresses and amounts you want to send
Process Payouts: Send the requests to be executed by your Self-Custodial Wallet
Monitor Status: Track the progress and completion of your payouts
Manage Balance: Check your wallet balance and address

Prerequisites

API Key V2: You must upgrade from API Key V1 to V2 to use Self-Custodial Wallet
Sufficient Balance: Ensure your Self-Custodial Wallet has enough funds for payouts + fees
Supported Cryptocurrencies: Check our cryptocurrencies page for supported tickers

Recommended Workflow

1. Create and Process Payouts

You have two approaches for creating payouts:

Option A: Bulk Process (Recommended)

Use the bulk process endpoint to create and send multiple payouts efficiently in one request:

const payoutData = {
  outputs: {
    '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.2,
    '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1
  }
};

const response = await fetch('https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY_V2'
  },
  body: JSON.stringify(payoutData)
});

const result = await response.json();
const payoutId = result.payout_info.id;
console.log('Payout ID:', payoutId);

Using Our Official Libraries

For a simpler integration, you can also use our official libraries. Here's how you would create a bulk payout:

// Using the official Node.js library
const BlockBee = require('@blockbee/api');

const requests = {
  '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.2,
  '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1
};

const payout = await BlockBee.createPayout('btc', requests, 'YOUR_API_KEY_V2', true);
// payout.payout_info.id

You can find the full documentation for our libraries here:

Option B: Individual Requests + Batch Processing (Exchange-style)

Create individual payout requests and then combine them into a single payout for batch processing, similar to how exchanges handle withdrawals. This approach is ideal for platforms that need to:

Create withdrawals when users request them
Create payout requests for each withdrawal
Batch process when enough requests accumulate or after a time period
Create and process payouts to execute all pending withdrawals

// Step 1: Create individual payout requests (when users request withdrawals)
const payoutRequests = [
  {
    address: '0x1234567890123456789012345678901234567890',
    amount: 0.2
  },
  {
    address: '0x0987654321098765432109876543210987654321',
    amount: 0.1
  }
];

// Create multiple payout requests at once
const bulkRequests = {
  requests: payoutRequests
};

const bulkResponse = await fetch('https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY_V2'
  },
  body: JSON.stringify(bulkRequests)
});

const bulkResult = await bulkResponse.json();
const requestIds = bulkResult.request_ids; // Array of request IDs

// Step 2: Create payout from individual requests (batch processing)
const payoutResponse = await fetch('https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY_V2'
  },
  body: JSON.stringify({
    payout_request_ids: requestIds.join(',')
  })
});

const payoutResult = await payoutResponse.json();
const payoutId = payoutResult.payout_info.id;
console.log('Payout ID:', payoutId);

// Step 3: Process the payout (execute all withdrawals)
const processResponse = await fetch(`https://api.blockbee.io/payout/process/${payoutId}/?apikey=YOUR_API_KEY_V2`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY_V2'
  }
});

const processResult = await processResponse.json();
console.log('Payout processed:', processResult.status);

Using Our Official Libraries

You can also use our official libraries for the exchange-style workflow:

// Using the official Node.js library
const BlockBee = require('@blockbee/api');

// Step 1: Create individual payout requests
const requests = {
  '0x1234567890123456789012345678901234567890': 0.2,
  '0x0987654321098765432109876543210987654321': 0.1
};

const payout = await BlockBee.createPayout('btc', requests, 'YOUR_API_KEY_V2', false);
const requestIds = payout.request_ids; // Array of request IDs

// Step 2: Create payout from individual requests
const payoutResult = await BlockBee.createPayoutByIds('YOUR_API_KEY_V2', requestIds);
const payoutId = payoutResult.payout_info.id;

// Step 3: Process the payout
const processResult = await BlockBee.processPayout('YOUR_API_KEY_V2', payoutId);

Exchange Workflow Example

Here's how a typical exchange would implement this workflow:

User requests withdrawal → Create payout request immediately
Accumulate requests → Store payout request IDs
Batch processing → When threshold reached or time passed, create payout
Execute withdrawals → Process the payout to send all transactions

Alternative: Create Multiple Requests at Once You can also create multiple payout requests in one call using the bulk endpoint:

JavaScript

// Create multiple payout requests at once
const bulkRequests = {
  requests: [
    { address: '0x1234567890123456789012345678901234567890', amount: 0.2 },
    { address: '0x0987654321098765432109876543210987654321', amount: 0.1 }
  ]
};

const bulkResponse = await fetch('https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY_V2'
  },
  body: JSON.stringify(bulkRequests)
});

const bulkResult = await bulkResponse.json();
const requestIds = bulkResult.request_ids; // Array of request IDs

2. Monitor Payout Status

Track the progress of your payouts using the payout ID:

const statusData = {
  payout_id: payoutId
};

const statusResponse = await fetch('https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY_V2'
  },
  body: JSON.stringify(statusData)
});

const status = await statusResponse.json();
console.log('Payout status:', status.payout_info.status);

Using Our Official Libraries

You can also check payout status using our official libraries:

// Using the official Node.js library
const BlockBee = require('@blockbee/api');

const status = await BlockBee.checkPayoutStatus('YOUR_API_KEY_V2', payoutId);
// status.payout_info.status

Payout Statuses

Created: Payout has been created and is queued for processing
Processing: Payout is being processed by the blockchain
Done: Payout has been successfully completed
Error: Payout failed (check the error message for details)

Error Handling

For detailed information about common errors and their solutions, see our Error Handling Guide.

Security Considerations

API Key V2 Security: Use advanced security practices for API Key V2
Recovery Key: Safely store your recovery key for emergency access
Address Validation: Always verify destination addresses before creating payouts
HTTPS Only: Always use HTTPS for API requests in production

Relevant API Endpoints

For detailed information about all payout-related endpoints, see our API Reference. Key endpoints include:

Payout Management: Create, process, and monitor payouts
Wallet Operations: Check balance, get addresses
Request Management: Create and manage payout requests
Status Tracking: Monitor payout and request status

Testing

Test with Small Amounts: Before using Self-Custodial Wallet in production, test with small amounts of Litecoin (LTC) to ensure everything works correctly.

Testing Workflow

Get Test LTC: Add a small amount of Litecoin to your Self-Custodial Wallet
Create Test Payouts: Use the examples above with small amounts (0.001 LTC)
Monitor Results: Check payout status and verify transactions
Scale Up: Once testing is successful, increase amounts gradually

Test with Litecoin

Litecoin is ideal for testing because:

Low fees: Minimal transaction costs
Fast confirmations: Quick transaction processing
Widely supported: Available on most exchanges
Stable network: Reliable for testing purposes

Use the ticker ltc in your API calls for Litecoin testing.

Dashboard Management: You can also manage your Self-Custodial Wallet through the BlockBee Dashboard.

Self-Custodial Wallet Payouts

Overview

Key Concepts

How It Works

Prerequisites

Recommended Workflow

1. Create and Process Payouts

Option A: Bulk Process (Recommended)

Option B: Individual Requests + Batch Processing (Exchange-style)

Exchange Workflow Example

2. Monitor Payout Status

Payout Statuses

Error Handling

Security Considerations

Relevant API Endpoints

Testing

Testing Workflow

Test with Litecoin

In this page