Bitcoin & UTXO

API Endpoints

1. Fetch UTXOs

POST /transactions/utxos - Get available UTXOs before creating transactions

2. Create Bitcoin Transaction

POST /transactions - Create and send Bitcoin transactions

Fetch Available UTXOs

Before creating raw Bitcoin transactions using custom select UTXOs, you can fetch available UTXOs (Unspent Transaction Outputs) to understand your available funds and select specific inputs.

Endpoint

POST /transactions/utxos

Request Headers

Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <encodedToken>

Parameters

Parameter	Type	Required	Description
`chain`	string	Yes	Must be "BITCOIN"
`accountId`	string	Yes	Account UID to fetch UTXOs from
`subAccountId`	string	No	Sub-account UID
`fromAddresses`	array	No	Specific addresses to fetch UTXOs from
`amount`	string	No	Minimum amount to fetch UTXOs for

Example Request

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions/utxos \
     -H 'content-type: application/x-www-form-urlencoded' \
     -H 'authorization: Bearer <encodedToken>' \
     -d 'chain=BITCOIN&accountId=2333-33&fromAddresses[]=tb1qe92jn2a75zkkvmxj5ynp2sy6zapuj4hcpvyww8&amount=0.0001'

Response Format

{
  "status": "success",
  "data": [
    {
      "txHash": "9065bafa0973b67aac7de3d4bda561e2f2812a8b6aadbbe71092f4c1cf6be5d1",
      "hash": "9065bafa0973b67aac7de3d4bda561e2f2812a8b6aadbbe71092f4c1cf6be5d1",
      "index": 1,
      "address": "tb1qe92jn2a75zkkvmxj5ynp2sy6zapuj4hcpvyww8",
      "amount": 0.00033825
    },
    {
      "txHash": "5d3c0e049cd9d43c136b479f4c26f49582df74b34894ed2b88313232b7fdfe18",
      "hash": "5d3c0e049cd9d43c136b479f4c26f49582df74b34894ed2b88313232b7fdfe18",
      "index": 0,
      "address": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
      "amount": 0.00001
    }
  ]
}

Bitcoin Transaction Parameters

Core Parameters

Parameter	Type	Required	Description
`walletId`	string	Yes	Unique identifier for the wallet
`assetType`	string	Yes	Must be "BTC"
`tos`	array	Yes	Array of destination objects
`fromUtxo`	array	No	Array of specific UTXOs to spend
`changeAddress`	string	No	Address to receive change
`fee`	string	No	Fixed transaction fee in BTC

Advanced Bitcoin Parameters

Parameter	Type	Description
`satsPerByte`	number	Fee rate in satoshis per byte (1-50+ typical range)
`minUtxoValue`	string	Minimum value of UTXOs to use
`maxUtxoValue`	string	Maximum value of UTXOs to use
`doubleSpend`	boolean	Override previous transaction (Replace-By-Fee)
`changeAddressType`	string	Type of change address (segwit, wrappedsegwit, legacy)

UTXO Object Structure

Parameter	Type	Required	Description
`address`	string	Yes	Address containing the UTXO
`txHash`	string	Yes	Transaction hash of the UTXO
`index`	number	Yes	Output index in the transaction

Output Object Structure

Parameter	Type	Required	Description
`address`	string	Yes	Recipient Bitcoin address
`value`	number	Yes	Amount to send in BTC

Bitcoin Transaction Types

1. Basic Bitcoin Transaction

Send Bitcoin Transaction.

Legacy Format (Deprecated)

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "8648a91-2413-43dc-a139-667432b8ff",
          "assetType": "BTC",
          "cryptoAmount": "0.00001",
          "address": "2MtQsUJqJz4wiY5WnBXPwrsMbJxm9QsT14i",
          "description": "Basic Bitcoin transfer",
          "fee": "0.00000547"
      }'

Modern Format (Recommended)

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "8648a91-2413-43dc-a139-667432b8ff",
          "assetType": "BTC",
          "tos": [{
              "address": "2MtQsUJqJz4wiY5WnBXPwrsMbJxm9QsT14i",
              "value": "0.00001"
          }],
          "description": "Basic Bitcoin transfer",
          "satsPerByte": 5
      }'

2. Bitcoin Transaction with Custom Change Address

Control where change funds are sent instead of generating a new address.

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "4522efe5-1d0a-41ae-9d7f-b22374063332",
          "assetType": "BTC",
          "tos": [{
              "address": "tb1q4qs2y4ex67sxgqfyydqysa78506awdw6nafdfj",
              "value": 0.0001
          }],
          "changeAddress": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
          "changeAddressType": "segwit",
          "satsPerByte": 8,
          "description": "Transaction with custom change address"
      }'

3. Bitcoin Transaction with Specific UTXOs

Use exact UTXOs as inputs for complete transaction control.

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "4522efe5-1d0a-41ae-9d7f-b22374063332",
          "assetType": "BTC",
          "fromUtxo": [{
              "address": "tb1qe92jn2a75zkkvmxj5ynp2sy6zapuj4hcpvyww8",
              "txHash": "9065bafa0973b67aac7de3d4bda561e2f2812a8b6aadbbe71092f4c1cf6be5d1",
              "index": 1
          }, {
              "address": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
              "txHash": "5d3c0e049cd9d43c136b479f4c26f49582df74b34894ed2b88313232b7fdfe18",
              "index": 0
          }],
          "tos": [{
              "address": "tb1q4qs2y4ex67sxgqfyydqysa78506awdw6nafdfj",
              "value": 0.0001
          }],
          "changeAddress": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
          "satsPerByte": 10,
          "description": "Transaction with specific UTXOs"
      }'

4. Double Spend Transaction (Replace-By-Fee)

Override an unconfirmed transaction using the same UTXOs with a higher fee. This implements Replace-By-Fee (RBF) to speed up or modify pending transactions.

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "4522efe5-1d0a-41ae-9d7f-b22374063332",
          "assetType": "BTC",
          "fromUtxo": [{
              "address": "tb1qe92jn2a75zkkvmxj5ynp2sy6zapuj4hcpvyww8",
              "txHash": "9065bafa0973b67aac7de3d4bda561e2f2812a8b6aadbbe71092f4c1cf6be5d1",
              "index": 1
          }],
          "tos": [{
              "address": "tb1q4qs2y4ex67sxgqfyydqysa78506awdw6nafdfj",
              "value": 0.0001
          }],
          "doubleSpend": true,
          "satsPerByte": 15,
          "changeAddress": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
          "description": "RBF transaction with higher fee"
      }'

Important Notes:

The UTXOs must be from a currently unconfirmed transaction
The new transaction must pay a higher fee rate than the original
RBF allows you to "replace" a stuck transaction with a faster one

5. Speed Up Transaction

Accelerate a pending transaction by including its transaction hash as a UTXO input and adding additional UTXOs to increase the total fee.

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "4522efe5-1d0a-41ae-9d7f-b22374063332",
          "assetType": "BTC",
          "fromUtxo": [{
              "address": "tb1qe92jn2a75zkkvmxj5ynp2sy6zapuj4hcpvyww8",
              "txHash": "pending_transaction_hash_to_speed_up",
              "index": 0
          }, {
              "address": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
              "txHash": "additional_utxo_for_higher_fee",
              "index": 0
          }],
          "tos": [{
              "address": "tb1q4qs2y4ex67sxgqfyydqysa78506awdw6nafdfj",
              "value": 0.0001
          }],
          "satsPerByte": 20,
          "changeAddress": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
          "description": "Accelerate pending transaction"
      }'

How it works:

Include the pending transaction's UTXO as an input
Add additional UTXOs to increase available funds for fees
Set a higher satsPerByte rate for faster confirmation
The increased fee incentivizes miners to confirm faster

6. Bitcoin Transaction with Custom Sats Per Byte

Control transaction priority and confirmation speed by specifying the exact fee rate.

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "4522efe5-1d0a-41ae-9d7f-b22374063332",
          "assetType": "BTC",
          "tos": [{
              "address": "tb1q4qs2y4ex67sxgqfyydqysa78506awdw6nafdfj",
              "value": 0.0001
          }],
          "satsPerByte": 25,
          "changeAddress": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
          "description": "High priority transaction - 25 sats/byte"
      }'

Fee Priority Guidelines:

1-3 sats/byte: Low priority (slower confirmation, 1-6+ hours)
4-10 sats/byte: Medium priority (30 minutes - 2 hours)
11-20 sats/byte: High priority (10-30 minutes)
21+ sats/byte: Very high priority (next few blocks)

7. Bitcoin Transaction with UTXO Value Constraints

Control which UTXOs are automatically selected by specifying minimum and maximum value limits.

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "4522efe5-1d0a-41ae-9d7f-b22374063332",
          "assetType": "BTC",
          "tos": [{
              "address": "tb1q4qs2y4ex67sxgqfyydqysa78506awdw6nafdfj",
              "value": 0.0001
          }],
          "minUtxoValue": "0.00005",
          "maxUtxoValue": "0.001",
          "satsPerByte": 8,
          "changeAddress": "tb1qsjrjq7y8k47uc3ts7073h3s8empxzwf55gs6uv",
          "description": "Transaction using medium-sized UTXOs only"
      }'

Use Cases:

minUtxoValue: Avoid dust UTXOs that increase transaction size and fees
maxUtxoValue: Preserve larger UTXOs for future transactions or emergency use
Combined: Use only UTXOs within a specific range for optimal fee management and privacy

Transaction Response Format

All Bitcoin transaction requests return a standardized response.

{
  "status": "success",
  "data": {
    "hash": "1b6dff5b430a8b0b4bc604a23dda5aa4d7979dd11dbc25d9345bd88889ad8297",
    "status": "PENDING",
    "amount": "0.00012741",
    "uid": "6680c116-c803-4e46-aa99-2f261cd216ac",
    "assetType": "BTC",
    "chain": "BITCOIN",
    "fee": "0.00003034",
    "ref": "BTP-Up5Ubzb0ot#H4LtW2VbdrxoxMt7Wy1",
    "gasLimit": null,
    "gasPrice": null,
    "network": "TESTNET"
  }
}

Response Fields

Field	Type	Description
`hash`	string	Bitcoin transaction hash
`status`	string	Transaction status (PENDING, CONFIRMED, FAILED)
`amount`	string	Amount sent in BTC
`uid`	string	Unique BitPowr transaction identifier
`assetType`	string	Always "BTC" for Bitcoin
`chain`	string	Always "BITCOIN"
`fee`	string	Transaction fee paid in BTC
`ref`	string	BitPowr reference number
`network`	string	Network type (MAINNET or TESTNET)

Bitcoin Workflow Examples

1. Basic Bitcoin Workflow

1. Create transaction with tos array
2. Specify satsPerByte for fee control
3. Let system handle UTXO selection automatically

2. Advanced UTXO Management Workflow

1. Fetch UTXOs → POST /transactions/utxos
2. Analyze available UTXOs and amounts
3. Create transaction with specific fromUtxo array
4. Specify changeAddress for remaining funds

3. Replace-By-Fee (RBF) Workflow

1. Create initial transaction with moderate fee
2. Monitor transaction status (if slow)
3. Create new transaction with same UTXOs
4. Set doubleSpend: true and higher satsPerByte

4. Transaction Acceleration Workflow

1. Identify slow pending transaction
2. Fetch additional UTXOs for extra fees
3. Create new transaction including:
   - Original transaction hash in fromUtxo
   - Additional UTXOs for higher fees
   - Higher satsPerByte rate

Best Practices

Fee Management

Check Network Conditions: Use fee estimation tools to check current network congestion
Start Conservative: Begin with moderate fees (5-10 sats/byte) and use RBF if needed
Emergency Priority: For urgent transactions, use 20+ sats/byte

UTXO Management

Avoid Dust: Set minUtxoValue to avoid very small UTXOs that increase fees
Preserve Large UTXOs: Use maxUtxoValue to save larger UTXOs for when you need them
Consolidation: Periodically combine small UTXOs when network fees are low

Security & Privacy

Change Addresses: Always specify a changeAddress from your wallet
UTXO Selection: Use specific fromUtxo for better privacy control
Address Types: Prefer SegWit addresses (changeAddressType: "segwit") for lower fees

Error Handling

Insufficient Funds: Check UTXO availability before creating transactions
Fee Too Low: Monitor transaction status and use RBF if stuck
Network Issues: Implement retry logic with exponential backoff

Address Format Support

BitPowr supports all standard Bitcoin address formats:

Legacy (P2PKH): Addresses starting with 1
Script Hash (P2SH): Addresses starting with 3
Bech32 (P2WPKH): Addresses starting with bc1q (mainnet) or tb1q (testnet)
Bech32m (P2TR): Addresses starting with bc1p (mainnet) or tb1p (testnet)

Recommendation: Use Bech32 (SegWit) addresses when possible for lower transaction fees.