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 uses TSS cryptography so BlockBee cannot access your funds without your API key.

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:

Get notified instead of polling. Configure a payout webhook URL in your dashboard payout settings, and BlockBee pushes a notification when a payout completes (done) or needs attention (error or expired). See the Payout Webhook reference for the payload, signature verification, and retry behavior.

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: The settlement transaction is being executed and confirmed on-chain
Done: Confirmed on-chain. txid and blockchain_fee are set
Rejected: You rejected the payout in your BlockBee dashboard, or it had no valid outputs, so it will not be processed
Expired: The settlement transaction was dropped by the network before confirming. No funds left your wallet and the batch is intact. Retry it with the same payout_id (see Expired payouts), or create a new payout
Error: The attempt failed with no live transaction remaining. Recovered the same way as expired

Expired Payouts

In rare cases a broadcast transaction is dropped by the network and never confirms. BlockBee monitors every settlement transaction; when one is deemed dead the payout is marked expired, and its error field explains why:

Payout expired: transaction not found on any node, please retry or issue a new payout
Payout expired: transaction unconfirmed after 72 hours, please retry or issue a new payout

No funds have left your wallet, and the batch is intact. Both expired and error payouts are recovered the same way: call Process Payout by ID again with the same payout_id. There is no deadline, so an expired payout stays retryable indefinitely.

Before re-sending anything, BlockBee verifies every previous attempt on-chain:

If an earlier settlement confirmed, nothing is re-sent. The payout completes (done) with its txid and blockchain_fee.
If an earlier settlement is still pending in a mempool, nothing is re-sent. The payout resolves when it does.
Only when every previous attempt is provably dead is a fresh transaction broadcast.

A retry can never pay the same outputs twice. If you prefer, create a new payout with new requests instead. Both paths are safe.

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

Expired Payouts

Error Handling

Security Considerations

Relevant API Endpoints

Testing

Testing Workflow

Test with Litecoin

In this page