RecipesWallets
Wallet Management
List All Wallets
const walletsResult = await broadcastRequest({
action: 'get',
resource: '/wallets',
details: {},
})
const wallets = walletsResult.detailsList Wallets with Filters
const filteredResult = await broadcastRequest({
action: 'get',
resource: '/wallets',
details: {
filters: {
name: 'amp', // Filter by name (partial match)
signer_id: signerId, // Filter by signer
user_id: userId, // Filter by user
address: '...', // Filter by address
},
},
})Get User's Wallets
const userWalletsResult = await broadcastRequest({
action: 'get',
resource: `/users/${userId}/wallets`,
details: {},
})Get Single Wallet
const walletResult = await broadcastRequest({
action: 'get',
resource: `/wallets/${walletId}`,
details: {},
})Asset Management (Liquid Network)
Liquid wallets support native asset issuance, transfer, and management.
Issue a New Asset
const issueResult = await broadcastRequest({
action: 'add',
resource: `/wallets/${walletId}/spend-requests`,
details: {
id: uuidv4(),
wallet_id: walletId,
tx_type: 'issue',
request: {
issue_amount: 10000, // Initial supply
reissue_amount: 10000, // Reissuance tokens
coingecko_id: 'bitcoin', // For price tracking (optional)
contract: {
name: 'My Asset',
ticker: 'MYA',
domain: 'myasset.example.com',
version: 0,
precision: 8,
},
},
},
})
const assetId = issueResult.details.asset_idConfigure Asset Restrictions
Control how assets can be transferred and burned:
// Set restrictions for a specific wallet
const restrictionResult = await broadcastRequest({
action: 'edit',
resource: `/assets/${assetId}/wallets/${walletId}/restrictions`,
details: {
can_burn: false, // Disable burning
whitelist: [walletId, otherWalletId], // Allowed recipients
},
})
// Get current restrictions
const getRestrictionResult = await broadcastRequest({
action: 'get',
resource: `/assets/${assetId}/wallets/${walletId}/restrictions`,
})Batch Restriction Updates
const batchResult = await broadcastRequest({
action: 'edit',
resource: `/assets/${assetId}/restrictions`,
details: {
can_burn: true,
wids: [wallet1Id, wallet2Id], // Wallets to update
use_to_whitelist: true,
to_whitelist: [recipientWallet1, recipientWallet2],
},
})Complete Wallet Onboarding Example
import { v4 as uuidv4 } from 'uuid'
async function onboardWallet(
type: 'amp' | 'single_sig' | 'kofn_multisig',
network: 'bitcoin' | 'liquid',
name: string,
) {
const timestamp = Date.now()
// Step 1: Create signer
const signerResult = await broadcastRequest({
action: 'add',
resource: '/signers',
details: {
sid: uuidv4(),
name: `${name}_signer_${timestamp}`,
location: 'hosted',
},
})
const signerId = signerResult.details.sid
// Step 2: Derive XPUB
const xpubResult = await broadcastRequest({
action: 'add',
resource: `/signers/${signerId}/xpubs`,
details: {
id: uuidv4(),
kind: 'bip87',
change: 'receive',
},
})
// Step 3: Create wallet
const walletResult = await broadcastRequest({
action: 'add',
resource: '/wallets',
details: {
id: uuidv4(),
name: `${name}_wallet_${timestamp}`,
type,
network,
value: {
signer_id: signerId,
},
},
})
const walletId = walletResult.details.wid
// Step 4: Generate initial receive address
const addressResult = await broadcastRequest({
action: 'add',
resource: `/wallets/${walletId}/addresses`,
details: {
type: 'receive',
index: 1,
},
})
return {
signerId,
walletId,
address: addressResult.details.address,
descriptor: walletResult.details.descriptor,
}
}
// Usage examples
const ampWallet = await onboardWallet('amp', 'liquid', 'my_amp')
const singleSigWallet = await onboardWallet('single_sig', 'bitcoin', 'my_btc')Exchange Onboarding
TODO: Document exchange onboarding workflow. Exchange integration involves configuring recipients as exchange counterparties, setting up asset exchange rate tracking via CoinGecko integration, and managing spend requests for exchange operations.
Troubleshooting
| Issue | Possible Cause | Solution |
|---|---|---|
| Signer creation fails | Invalid parameters | Verify sid is a valid UUID |
| XPUB derivation fails | Signer not found | Confirm signer ID exists |
| Wallet creation fails | Invalid network/type combination | AMP requires Liquid network |
| Address generation fails | Wallet not initialized | Ensure wallet creation succeeded |
Related Documentation
- API User Onboarding - User authentication setup
- Batch Requests - Batch API operations
K-of-N Multisig Wallet (Bitcoin/Liquid)
K-of-N multisig wallets require multiple signatures to authorize transactions, providing enhanced security and governance.
Roles & Permissions Guide
This guide describes the role-based access control (RBAC) system in the Custody Engine, including roles, permissions, and rules configuration.