barkd Daemon

barkd is an Ark wallet that runs as a daemon and exposes a REST API over HTTP. It’s well-suited for power users and automation use cases like web shops, bots, and integrations.

Overview

The daemon mode provides:

REST API: Full HTTP API for wallet operations
Background operation: Runs continuously as a service
Automatic maintenance: Handles syncing and VTXO management
Multi-language support: Use TypeScript, C#, or any HTTP client
Hot wallet creation: Create wallets on-demand via API

Installation

See the Installation guide for installation instructions.

Starting the Daemon

With Existing Wallet

If you already created a wallet with bark create, start the daemon:

barkd

With custom datadir:

barkd --datadir /path/to/wallet

Without Wallet

You can start barkd without a wallet and create one via the REST API:

barkd

The server will start without a wallet loaded. Use the /wallet/create endpoint to create one.

Command-Line Options

barkd [OPTIONS]

Option	Environment Variable	Default	Description
`--datadir <PATH>`	`BARKD_DATADIR`	`~/.bark`	The datadir of the bark wallet
`--port <PORT>`	`BARKD_PORT`	`3000`	The port to listen on
`--host <HOST>`	`BARKD_HOST`	`127.0.0.1`	The host to listen on
`-v, --verbose`	`BARK_VERBOSE`	`false`	Enable verbose logging
`-q, --quiet`	`BARK_QUIET`	`false`	Disable all terminal logging
`--version`	-	-	Print version information
`--help`	-	-	Print help information

Configuration Examples

barkd

REST API Endpoints

The daemon exposes a comprehensive REST API. Key endpoints include:

Wallet Management

POST /wallet/create - Create a new wallet
GET /wallet/config - Get wallet configuration
GET /wallet/balance - Get wallet balance
GET /wallet/address - Get a receive address

Payments

POST /send - Send payment (Ark/Lightning/on-chain)
POST /send-onchain - Send on-chain payment
POST /board - Board funds into Ark
POST /offboard - Offboard VTXOs to on-chain

VTXOs

GET /vtxos - List VTXOs
POST /refresh - Refresh expiring VTXOs
GET /history - Get payment history

Lightning

POST /lightning/invoice - Create invoice
POST /lightning/pay - Pay invoice
GET /lightning/invoices - List invoices
POST /lightning/claim - Claim payment

Exits

POST /exit/start - Start unilateral exit
POST /exit/progress - Progress exit
GET /exit/status/:vtxoId - Get exit status
GET /exit/list - List all exits

See the OpenAPI documentation for complete API reference.

Creating a Wallet via API

curl -X POST http://localhost:3000/wallet/create \
  -H "Content-Type: application/json" \
  -d '{
    "network": "signet",
    "ark_server": "https://ark.signet.2nd.dev",
    "chain_source": {
      "type": "esplora",
      "url": "https://esplora.signet.2nd.dev"
    }
  }'

With Bitcoind

{
  "network": "signet",
  "ark_server": "https://ark.signet.2nd.dev",
  "chain_source": {
    "type": "bitcoind",
    "bitcoind": "http://127.0.0.1:38332",
    "bitcoind_auth": {
      "type": "cookie",
      "cookie": "/path/to/.cookie"
    }
  }
}

With User/Pass Authentication

{
  "network": "regtest",
  "ark_server": "http://127.0.0.1:3535",
  "chain_source": {
    "type": "bitcoind",
    "bitcoind": "http://127.0.0.1:18443",
    "bitcoind_auth": {
      "type": "user_pass",
      "user": "rpcuser",
      "pass": "rpcpassword"
    }
  }
}

API Usage Examples

Get Balance

curl http://localhost:3000/wallet/balance

Response:

{
  "offchain": "250000 sats",
  "onchain": "100000 sats",
  "total": "350000 sats"
}

Get Address

curl http://localhost:3000/wallet/address

Response:

{
  "address": "ark1q..."
}

Send Payment

curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "ark1q...",
    "amount": "50000sat"
  }'

Board Funds

curl -X POST http://localhost:3000/board \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100000sat"
  }'

Create Lightning Invoice

curl -X POST http://localhost:3000/lightning/invoice \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25000sat"
  }'

Response:

{
  "invoice": "lnbc250..."
}

List VTXOs

curl http://localhost:3000/vtxos

Client Libraries

Official client libraries are available:

TypeScript

npm install @ark-bitcoin/barkd-client

import { BarkdClient } from '@ark-bitcoin/barkd-client';

const client = new BarkdClient('http://localhost:3000');

const balance = await client.getBalance();
console.log('Balance:', balance.total);

const address = await client.getAddress();
console.log('Address:', address);

await client.send({
  destination: 'ark1q...',
  amount: '50000sat'
});

C#

dotnet add package ArkBitcoin.BarkdClient

using ArkBitcoin.BarkdClient;

var client = new BarkdClient("http://localhost:3000");

var balance = await client.GetBalanceAsync();
Console.WriteLine($"Balance: {balance.Total}");

var address = await client.GetAddressAsync();
Console.WriteLine($"Address: {address}");

await client.SendAsync(new SendRequest {
    Destination = "ark1q...",
    Amount = "50000sat"
});

See the barkd-clients repository for complete documentation.

Running as a Service

systemd (Linux)

Create /etc/systemd/system/barkd.service:

[Unit]
Description=Barkd Daemon
After=network.target

[Service]
Type=simple
User=barkd
Group=barkd
ExecStart=/usr/local/bin/barkd --datadir /var/lib/barkd
Restart=on-failure
RestartSec=10

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/barkd

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable barkd
sudo systemctl start barkd
sudo systemctl status barkd

View logs:

sudo journalctl -u barkd -f

Docker

Create a Dockerfile:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY barkd /usr/local/bin/barkd

RUN useradd -m -U barkd && \
    mkdir -p /var/lib/barkd && \
    chown -R barkd:barkd /var/lib/barkd

USER barkd
WORKDIR /home/barkd

EXPOSE 3000

ENTRYPOINT ["barkd"]
CMD ["--host", "0.0.0.0", "--datadir", "/var/lib/barkd"]

Build and run:

docker build -t barkd .
docker run -d \
  --name barkd \
  -p 3000:3000 \
  -v barkd-data:/var/lib/barkd \
  barkd

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  barkd:
    image: barkd:latest
    container_name: barkd
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - barkd-data:/var/lib/barkd
    environment:
      - BARKD_HOST=0.0.0.0
      - BARKD_PORT=3000
      - BARK_VERBOSE=0

volumes:
  barkd-data:

Run:

docker-compose up -d

Security Considerations

barkd manages bitcoin funds. Follow these security best practices:

Network Binding

Default: Only binds to 127.0.0.1 (localhost)
Public access: Only use --host 0.0.0.0 behind a reverse proxy with authentication
Never expose barkd directly to the internet without authentication

Authentication

The current version does not include built-in authentication. Use:

Reverse proxy (nginx, caddy) with basic auth or JWT
VPN or SSH tunnel for remote access
Firewall rules to restrict access

Example nginx config with basic auth:

location /barkd/ {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

File Permissions

Ensure the datadir has restricted permissions:

chmod 700 ~/.bark
chmod 600 ~/.bark/mnemonic
chmod 600 ~/.bark/db.sqlite

TLS/HTTPS

Always use HTTPS in production:

Use a reverse proxy (nginx, caddy) with TLS certificates
Use Let’s Encrypt for free certificates
Never send API requests over plain HTTP on untrusted networks

Logging

Logs are stored in $DATADIR/debug.log. Enable verbose logging:

barkd -v

Disable console output:

barkd -q

Log rotation with logrotate (/etc/logrotate.d/barkd):

/var/lib/barkd/debug.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        systemctl reload barkd
    endscript
}

Monitoring

Health Check

Check if the daemon is running:

curl http://localhost:3000/wallet/config

If the wallet is loaded, it returns configuration. Otherwise, it returns an error.

Prometheus Metrics

(Note: Metrics endpoint is not yet implemented in the current version)

Troubleshooting

Port Already in Use

# Check what's using port 3000
lsof -i :3000

# Use a different port
barkd --port 8080

Permission Denied

# Check datadir permissions
ls -la ~/.bark

# Fix permissions
chmod 700 ~/.bark

Connection Refused

Verify the daemon is running: ps aux | grep barkd
Check the port and host: netstat -tulpn | grep barkd
Review logs: cat ~/.bark/debug.log

Wallet Not Found

If you start barkd without a wallet:

The daemon will start successfully
API calls will return “wallet not found” errors
Create a wallet via POST /wallet/create

Or create a wallet first:

bark create --signet --ark https://ark.signet.2nd.dev
barkd

Shutdown

Graceful shutdown:

# Send SIGTERM
kill -TERM $(pidof barkd)

# Or use Ctrl+C if running in foreground

The daemon handles SIGTERM and Ctrl+C (and Ctrl+Break on Windows) to shut down gracefully.

Get Started

Core Concepts

Wallet Integration

CLI Tools

​Overview

​Installation

​Starting the Daemon

​With Existing Wallet

​Without Wallet

​Command-Line Options

​Configuration Examples

​REST API Endpoints

​Wallet Management

​Payments

​VTXOs

​Lightning

​Exits

​Creating a Wallet via API

​With Bitcoind

​With User/Pass Authentication

​API Usage Examples

​Get Balance

​Get Address

​Send Payment

​Board Funds

​Create Lightning Invoice

​List VTXOs

​Client Libraries

​TypeScript

​C#

​Running as a Service

​systemd (Linux)

​Docker

​Docker Compose

​Security Considerations

​Network Binding

​Authentication

​File Permissions

​TLS/HTTPS

​Logging

​Monitoring

​Health Check

​Prometheus Metrics

​Troubleshooting

​Port Already in Use

​Permission Denied

​Connection Refused

​Wallet Not Found

​Shutdown

Build docs developers (and LLMs) love

Overview

Installation

Starting the Daemon

With Existing Wallet

Without Wallet

Command-Line Options

Configuration Examples

REST API Endpoints

Wallet Management

Payments

VTXOs

Lightning

Exits

Creating a Wallet via API

With Bitcoind

With User/Pass Authentication

API Usage Examples

Get Balance

Get Address

Send Payment

Board Funds

Create Lightning Invoice

List VTXOs

Client Libraries

TypeScript

C#

Running as a Service

systemd (Linux)

Docker

Docker Compose

Security Considerations

Network Binding

Authentication

File Permissions

TLS/HTTPS

Logging

Monitoring

Health Check

Prometheus Metrics

Troubleshooting

Port Already in Use

Permission Denied

Connection Refused

Wallet Not Found

Shutdown