Skip to main content
On-chain endpoints manage barkd’s built-in on-chain bitcoin wallet. This wallet holds funds in standard UTXOs, separate from your Ark balance, and operates under the normal on-chain trust model without involving the Ark server.

​
Get on-chain balance

GET /api/v1/onchain/balance
Returns the current on-chain wallet balance, broken down by confirmation status. The trusted_spendable_sat field is the sum of confirmed_sat and trusted_pending_sat—the balance that can be safely spent without risk of double-spend.

​
Response

{
  "total": 100000,
  "trusted_spendable": 100000,
  "immature": 0,
  "trusted_pending": 0,
  "untrusted_pending": 0,
  "confirmed": 100000
}
Fields:
  • total (integer) - Total balance in satoshis
  • trusted_spendable (integer) - Confirmed plus trusted pending
  • immature (integer) - Coinbase outputs that haven’t matured yet
  • trusted_pending (integer) - Unconfirmed outputs from transactions we created
  • untrusted_pending (integer) - Unconfirmed outputs from external sources
  • confirmed (integer) - Confirmed balance

​
Example

curl http://localhost:3000/api/v1/onchain/balance

​
Generate on-chain address

POST /api/v1/onchain/addresses/next
Generates a new on-chain receiving address. Each call returns the next unused address from the wallet’s HD keychain.

​
Response

{
  "address": "bc1q..."
}

​
Example

curl -X POST http://localhost:3000/api/v1/onchain/addresses/next

​
Send on-chain payment

POST /api/v1/onchain/send
Sends the specified amount to an on-chain address. Broadcasts the transaction immediately at a feerate targeting confirmation within three blocks and returns the transaction ID.

​
Request body

{
  "destination": "bc1q...",
  "amount_sat": 50000
}
Parameters:
  • destination (string, required) - Bitcoin address
  • amount_sat (integer, required) - Amount in satoshis

​
Response

{
  "txid": "abc123..."
}

​
Example

curl -X POST http://localhost:3000/api/v1/onchain/send \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "amount_sat": 50000
  }'

​
Errors

  • 400 - Invalid destination address or address not valid for configured network

​
Send to multiple addresses

POST /api/v1/onchain/send-many
Batches multiple payments into a single on-chain transaction. Each destination is formatted as address:amount. Broadcasts the transaction immediately at a feerate targeting confirmation within three blocks and returns the transaction ID.

​
Request body

{
  "destinations": [
    "bc1q...:10000",
    "bc1q...:20000"
  ]
}
Parameters:
  • destinations (array of strings, required) - Array of address:amount pairs

​
Response

{
  "txid": "abc123..."
}

​
Example

curl -X POST http://localhost:3000/api/v1/onchain/send-many \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [
      "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh:10000",
      "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq:20000"
    ]
  }'

​
Errors

  • 400 - Invalid destination format or invalid address

​
Drain on-chain wallet

POST /api/v1/onchain/drain
Sends the entire on-chain wallet balance to the specified address. The recipient receives the full balance minus transaction fees. Broadcasts immediately at a feerate targeting confirmation within three blocks and returns the transaction ID.

​
Request body

{
  "destination": "bc1q..."
}
Parameters:
  • destination (string, required) - Bitcoin address

​
Response

{
  "txid": "abc123..."
}

​
Example

curl -X POST http://localhost:3000/api/v1/onchain/drain \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }'

​
Errors

  • 400 - Invalid destination address or address not valid for configured network

​
List on-chain UTXOs

GET /api/v1/onchain/utxos
Returns all UTXOs in the on-chain wallet. Each entry includes the outpoint, amount, and confirmation height (if confirmed).

​
Response

[
  {
    "outpoint": "abc123...:0",
    "amount_sat": 50000,
    "confirmation_height": 800000
  },
  {
    "outpoint": "def456...:1",
    "amount_sat": 30000,
    "confirmation_height": null
  }
]
Fields:
  • outpoint (string) - Transaction ID and output index in format txid:vout
  • amount_sat (integer) - Amount in satoshis
  • confirmation_height (integer or null) - Block height where confirmed, or null if unconfirmed

​
Example

curl http://localhost:3000/api/v1/onchain/utxos

​
List on-chain transactions

GET /api/v1/onchain/transactions
Returns all on-chain wallet transactions, ordered from oldest to newest.

​
Response

[
  {
    "txid": "abc123...",
    "sent_sat": 50000,
    "received_sat": 0,
    "fee_sat": 200,
    "confirmation_height": 800000,
    "timestamp": 1709481600
  }
]
Fields:
  • txid (string) - Transaction ID
  • sent_sat (integer) - Amount sent in satoshis
  • received_sat (integer) - Amount received in satoshis
  • fee_sat (integer) - Transaction fee in satoshis
  • confirmation_height (integer or null) - Block height where confirmed, or null if unconfirmed
  • timestamp (integer) - Unix timestamp

​
Example

curl http://localhost:3000/api/v1/onchain/transactions

​
Sync on-chain wallet

POST /api/v1/onchain/sync
Syncs the on-chain wallet state with the chain source. Fetches new blocks and transactions, updates the UTXO set, and re-submits any stale unconfirmed transactions to the mempool.

​
Response

Returns 200 on success with no body.

​
Example

curl -X POST http://localhost:3000/api/v1/onchain/sync

Build docs developers (and LLMs) love

Get started for freeTalk to us