wallet

Get wallet balance

Returns the wallet balance broken down by category: spendable sats available for immediate use, sats pending in an Ark round, sats locked in outgoing or incoming Lightning payments, sats awaiting board confirmation, and sats in a pending exit. The balance is computed from local state, which the background daemon keeps reasonably fresh (Lightning syncs every second, mailbox and boards every 30 seconds). For the most up-to-date figures, call sync before this endpoint.

GET

api

wallet

balance

Get wallet balance

curl --request GET \
  --url https://api.example.com/api/v1/wallet/balance \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/api/v1/wallet/balance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/wallet/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/wallet/balance"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/wallet/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "claimable_lightning_receive_sat": 1,
  "needs_refresh_sat": 1,
  "pending_arkoor_send_sat": 1,
  "pending_board_sat": 1,
  "pending_exit_sat": 1,
  "pending_in_round_sat": 1,
  "pending_lightning_send_sat": 1,
  "pending_offboard_sat": 1,
  "spendable_sat": 1
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Base64url-encoded auth token

Response

Returns the wallet balance

The different balances of a Bark wallet.

spendable_sat counts the spendable VTXOs, needs_refresh_sat the ones that have to be refreshed before they can be sent again, and every other field what an operation in progress holds, so the fields never overlap.

See [BalanceSummary] for the totals to show a user.

All amounts are in sats.

claimable_lightning_receive_sat

integer<int64>

required

Sats in HTLC VTXOs of an incoming Lightning payment whose preimage has been revealed but which have not been swapped for spendable VTXOs yet. A payment that can still be cancelled is not counted.

Required range: x >= 0

needs_refresh_sat

integer<int64>

required

Sats in VTXOs that can no longer be sent in an arkoor payment because they have expired or their exit depth has reached the server's limit. They can still be offboarded, exited or refreshed, but are not part of spendable_sat until maintenance has refreshed them.

Required range: x >= 0

pending_arkoor_send_sat

integer<int64>

required

Sats locked in an outgoing arkoor payment that has not completed yet: the whole input amount, until the send finalizes and the change comes back as spendable.

Required range: x >= 0

pending_board_sat

integer<int64>

required

Sats in board transactions that are waiting for sufficient on-chain confirmations before becoming spendable.

Required range: x >= 0

pending_exit_sat

integer<int64>

required

Sats held in VTXOs whose unilateral exit has committed on-chain but which haven't yet been drained to the onchain wallet: their state is [crate::primitives::VtxoStateInfo::Exited] and their exit has not reached [crate::exit::ExitStateKind::Claimed].

Required range: x >= 0

pending_in_round_sat

integer<int64>

required

Sats locked in VTXOs forfeited for a round that has not yet completed.

Required range: x >= 0

pending_lightning_send_sat

integer<int64>

required

Sats locked in an outgoing Lightning payment that has not yet settled.

Required range: x >= 0

pending_offboard_sat

integer<int64>

required

Sats locked in an offboard whose transaction has not been broadcast yet, including any change that comes back. Once the transaction is on the network the sats belong to the on-chain wallet.

Required range: x >= 0

spendable_sat

integer<int64>

required

Sats that are immediately spendable, either in-round or out-of-round.

Required range: x >= 0

⌘I

Get wallet balance

curl --request GET \
  --url https://api.example.com/api/v1/wallet/balance \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/api/v1/wallet/balance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/wallet/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/wallet/balance"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/wallet/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "claimable_lightning_receive_sat": 1,
  "needs_refresh_sat": 1,
  "pending_arkoor_send_sat": 1,
  "pending_board_sat": 1,
  "pending_exit_sat": 1,
  "pending_in_round_sat": 1,
  "pending_lightning_send_sat": 1,
  "pending_offboard_sat": 1,
  "spendable_sat": 1
}

{
  "message": "<string>"
}

Documentation

Bark SDK

Barkd

Run an Ark server

Get wallet balance

Authorizations

Response