Bitcoin & UTXO Chains
Bitcoin and UTXO-based chains (Litecoin, Dogecoin, Bitcoin Cash, Dash) use a fundamentally different transaction model than account-based chains. Each transaction consumes previous unspent outputs (UTXOs) and creates new ones.
Address Types
Bitcoin supports multiple address formats. Specify the type when creating an address:
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": "eFjwUQXB8CMnrTHSgYzaL6",
"network": "bitcoin-mainnet",
"name": "BTC Deposits",
"type": "p2wpkh"
}' \
https://api.carabaas.com/api/v1/addresses
| Type | Format | Description | Recommended |
|---|---|---|---|
p2wpkh | bc1q... | Native SegWit | Yes |
p2pkh | 1... | Legacy | No |
Use p2wpkh (Native SegWit) for lower transaction fees and better compatibility with modern wallets.
Multiple Deposit Addresses
Unlike account-based chains, Bitcoin addresses are designed for single use. Generate a unique address per customer or per transaction for better privacy and deposit attribution:
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": "pQ3rS5tU7vW9xY1zAbCdEf",
"network": "bitcoin-mainnet",
"name": "customer-12345"
}' \
https://api.carabaas.com/api/v1/addresses
Sending BTC
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"orderId": "c9d0e1f2-a3b4-4c5d-6e7f-8a9b0c1d2e3f",
"vaultId": "kR7mNpX2wQvL9sYhBjD4eT",
"destination": "bc1qRecipient...",
"network": "bitcoin-mainnet",
"asset": "c0",
"amount": "0.01",
"feePriority": "medium"
}' \
https://api.carabaas.com/api/v1/transactions
Source Selection
For UTXO chains, the source field determines where the platform collects unspent outputs (UTXOs) from:
| Source | UTXOs collected from | Change address |
|---|---|---|
addressId | Single address only | Same address (default) — or specify changeAddress in options |
accountId | All addresses in the account | Required — specify changeAddress in options |
vaultId | All addresses in the vault | Required — specify changeAddress in options |
Change Address
When sending from accountId or vaultId, you must specify where the change (remaining UTXOs) should go:
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"orderId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
"accountId": "eFjwUQXB8CMnrTHSgYzaL6",
"destination": "bc1qRecipient...",
"network": "bitcoin-mainnet",
"asset": "c0",
"amount": "0.5",
"feePriority": "medium",
"options": {
"changeAddress": "gMP71sR5sNUnGdKFTsNzp6"
}
}' \
https://api.carabaas.com/api/v1/transactions
When sending from a single addressId, the change goes back to the same address by default — no changeAddress needed.
Fee Management
Bitcoin fees are based on transaction size (in vbytes), not a fixed gas price.
| Priority | Behavior |
|---|---|
low | Lower fee rate, may take several blocks |
medium | Targets confirmation within ~3 blocks |
high | Targets next-block confirmation |
Replace-By-Fee (RBF)
If a Bitcoin transaction is stuck in the mempool due to low fees, replace it:
curl -X PATCH \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "feePriority": "high" }' \
https://api.carabaas.com/api/v1/transactions/{txId}/replace
Confirmation Tracking
Bitcoin requires more confirmations than account-based chains for security. Configure confirmation thresholds per vault:
curl -X PUT \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "bitcoin-mainnet": 6 }' \
https://api.carabaas.com/api/v1/subscriptions/{vaultId}/confirmations
| Threshold | Use Case |
|---|---|
| 1 | Low-value, speed-sensitive |
| 3 | Standard operations |
| 6 | Maximum (highest security) |
Applicable Chains
| Chain | Asset ID | Native Asset | Address Formats |
|---|---|---|---|
| Bitcoin | c0 | BTC | p2wpkh, p2pkh |
| Bitcoin Cash | c145 | BCH | — |
| Litecoin | c2 | LTC | p2wpkh, p2pkh |
| Dogecoin | c3 | DOGE | — |
| Dash | c5 | DASH | — |