Skip to main content
The barkd REST API provides a simple HTTP interface for integrating bitcoin payments into your application. The API supports self-custodial Lightning, Ark, and on-chain payments out of the box.

​
Base URL

All API endpoints are prefixed with /api/v1. For example, if barkd is running on localhost:3000, the full URL for the balance endpoint would be: 
http://localhost:3000/api/v1/wallet/balance

​
Response format

All endpoints return JSON. Amounts are denominated in satoshis.

​
Error responses

The API uses standard HTTP status codes:
  • 200 - Success
  • 400 - Bad request (invalid parameters)
  • 404 - Resource not found
  • 500 - Internal server error
Error responses follow this schema: 
{
  "error": "Error message describing what went wrong"
}

​
Endpoint groups

The API is organized into the following groups:

​
Wallet

The bread and butter for most applications. Manage Ark addresses, balances, VTXOs, and refreshes. Send payments via Ark, Lightning, and on-chain, all funded from your Ark balance. Base path: /api/v1/wallet See Wallet endpoints for details.

​
Lightning

Create BOLT11 invoices to receive payments over Lightning and track receive status. Any application that accepts Lightning payments will use these endpoints alongside the wallet endpoints. Base path: /api/v1/lightning

​
On-chain

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. Base path: /api/v1/onchain See On-chain endpoints for details.

​
Boards

Move on-chain bitcoin onto the Ark protocol to start making off-chain payments. Base path: /api/v1/boards

​
Exits

Unilaterally move bitcoin back on-chain without server cooperation, for when the Ark server is unavailable or uncooperative. Base path: /api/v1/exits See Exit endpoints for details.

​
Bitcoin

Query bitcoin network data such as the current block height. Base path: /api/v1/bitcoin

​
Common patterns

​
Sending a payment

The /wallet/send endpoint accepts multiple destination types:
  • Ark addresses (instant off-chain settlement)
  • BOLT11 invoices
  • BOLT12 offers
  • Lightning addresses
For on-chain bitcoin addresses, use /wallet/send-onchain instead.

​
Checking balances

The /wallet/balance endpoint returns your Ark balance broken down by category:
  • spendable_sat - Available for immediate use
  • pending_round_sat - Pending in an Ark round
  • pending_lightning_outbound_sat - Locked in outgoing Lightning payments
  • pending_lightning_inbound_sat - Locked in incoming Lightning payments
  • pending_board_sat - Awaiting board confirmation
  • pending_exit_sat - In a pending exit

​
Tracking operations

Most operations that involve state changes return immediately but complete asynchronously:
  • Boards: Use /boards/ to list pending boards awaiting confirmation
  • Rounds: Use /wallet/rounds to track Ark round participations (refreshes)
  • Exits: Use /exits/status to monitor exit progress
  • Lightning receives: Use /lightning/receives to track invoice payment status

​
Authentication

The current version of the API does not include authentication. If you’re exposing barkd over a network, ensure you use appropriate network-level security measures.

​
Rate limiting

There is currently no rate limiting on API endpoints.

​
OpenAPI specification

A complete OpenAPI specification is available at /swagger-ui/ when barkd is running.

Build docs developers (and LLMs) love

Get started for freeTalk to us