Use your Bark wallet through the API

The plugin adds two read-only Greenfield API endpoints for your store’s Bark wallet. One lists every transaction, including refreshes and exits. The other returns the balance. They work like BTCPay’s on-chain wallet endpoints, with BTC-ARK as the payment method ID. Transactions also carry a few extra fields. Use them to connect to accounting tools and match Bark transactions to BTCPay invoice payments. The endpoints appear in your server’s API documentation, at /docs on your BTCPay Server, under Store Wallet (Ark).

BTCPay’s on-chain wallet endpoints don’t list Bark’s transactions. BTCPay’s Lightning API lists only Lightning invoices and payments. For the wallet’s full history, use GET /api/v1/stores/{storeId}/payment-methods/BTC-ARK/wallet/transactions.

Create an API key

Generate an API key with the View wallets permission (btcpay.store.canviewwallet) for the store, on your account’s API Keys page in BTCPay.

List the transactions

curl -H "Authorization: token $API_KEY" \
  "https://btcpay.example.com/api/v1/stores/$STORE_ID/payment-methods/BTC-ARK/wallet/transactions?limit=50"

Transactions come newest first. A new transaction can take up to 15 seconds to appear. All parameters are optional:

Parameter	What it does
`statusFilter`	Only `Confirmed` or `Unconfirmed` transactions. Repeat the parameter to pass both.
`labelFilter`	Only transactions carrying this label, such as `invoice` for the ones that paid an invoice. If you also pass `statusFilter`, the filters combine with OR: the response includes each transaction that matches either filter, once.
`skip`	How many transactions to skip, after filtering.
`limit`	The maximum number of transactions to return. All of them by default.

Each transaction looks like this one, an Ark payment to an invoice:

{
  "id": "1-639275347581234567:eac17c4b3d1f45d2b70f3bccfb3da992ef8d82b803aafa6482d61d27a2631373:0",
  "kind": "ark-receive",
  "movementId": 1,
  "outpoint": "eac17c4b3d1f45d2b70f3bccfb3da992ef8d82b803aafa6482d61d27a2631373:0",
  "paymentHash": null,
  "fee": "0",
  "transactionHash": "eac17c4b3d1f45d2b70f3bccfb3da992ef8d82b803aafa6482d61d27a2631373",
  "comment": "",
  "labels": {
    "invoice": { "ref": "4S6YW64waM9JoAfVHF97DX", "type": "invoice", "text": "invoice" }
  },
  "amount": "0.0015",
  "blockHash": null,
  "blockHeight": null,
  "confirmations": 1,
  "timestamp": 1791937958,
  "status": "Confirmed"
}

Read the fields

Field	What it contains
`id`	The transaction’s ID, unique within the store. Treat it as an opaque string. See Identify a transaction.
`kind`	See Transaction types.
`amount`	The transaction’s net effect on the wallet’s total balance, in BTC, after its `fee`: positive for bitcoin in, negative for bitcoin out. Over the wallet’s full history, the amounts add up to its total balance.
`fee`	What the wallet paid for the transaction, in BTC, already included in `amount`. Zero when the transaction cost nothing. Null on `onchain-receive` transactions, where the sender paid the fee, and when the plugin can’t tell what the fee was.
`status`	`Confirmed` once the transaction’s amount can no longer change, `Unconfirmed` before that. An `Unconfirmed` transaction can still change its amount, gain its `transactionHash`, or disappear (a failed refresh, for example).
`confirmations`	`1` once the transaction is confirmed, `0` before. Boards, offboards to the Bark on-chain wallet, and that wallet’s own on-chain transactions report their block confirmations instead.
`timestamp`	When Bark created the payment or operation. For transactions of the Bark on-chain wallet, when the plugin first saw them, or a time estimated from the block height if they were already confirmed.
`transactionHash`	The ID of the underlying on-chain or Ark transaction, if there is one. See Transaction types. Several transactions in the response can share one.
`outpoint`	On `ark-receive` transactions, the received VTXO, as `txid:vout`. Null on the rare `ark-receive` transaction that covers several VTXOs because the plugin couldn’t split it.
`paymentHash`	On Lightning transactions, the payment hash.
`movementId`	The Bark wallet’s own number for the payment or operation. Transactions share a number when a payment arrived as several VTXOs, and an exit’s `exit-fee` and `exit-claim` transactions carry the `exit` transaction’s number. Null on transactions of the Bark on-chain wallet that belong to no Bark payment. Numbers start over at 1 if the wallet is re-created or restored, so use `id`, not `movementId`, to identify a transaction.
`labels`	The transaction’s labels, as on BTCPay’s on-chain wallet transactions. The `invoice` label’s `ref` is the ID of the BTCPay invoice that the transaction paid. Store labels that you attach on the Bark Receive and Send screens appear as `raw` labels.
`blockHash`, `blockHeight`	The block that confirmed the transaction. Set only on boards, offboards to the Bark on-chain wallet, and that wallet’s own on-chain transactions.

Failed or canceled payments, sent or received, are listed only when they still moved bitcoin, with their real amount. Their status doesn’t show that they failed or were canceled. The Bark wallet page lists every failed or canceled payment.

Transaction types

Each type is a value of the kind field. The Type column of the Bark Wallet report shows the same types under display names.

`kind`	Report Type	What it is	`transactionHash`
`ark-receive`	Ark Receive	A payment to your off-chain balance over Ark, as one VTXO (rarely several)	The received VTXO’s exit transaction, which stays off-chain unless the VTXO is exited
`ark-send`	Ark Send	A payment from your off-chain balance over Ark	None
`lightning-receive`	Lightning Receive	A payment to your off-chain balance over Lightning	None
`lightning-send`	Lightning Send	A payment from your off-chain balance over Lightning	None
`refresh`	Refresh	VTXOs renewed in a round, within your off-chain balance	The on-chain round transaction, once Bark knows it
`board`	Board	Bitcoin moved from the Bark on-chain wallet to your off-chain balance	The on-chain board transaction
`offboard`	Offboard	VTXOs moved from your off-chain balance to an on-chain address, with the fee taken from them	The on-chain transaction that pays the address, once Bark knows it
`send-onchain`	Send On-chain	A payment from your off-chain balance to an on-chain address, with the fee on top	The on-chain transaction that pays the address, once Bark knows it
`exit`	Exit	One VTXO moved from your off-chain balance to the blockchain without the Ark server, in an emergency exit	The VTXO’s final exit transaction, broadcast before the claim
`exit-fee`	Exit Fee	A child-pays-for-parent (CPFP) payment from the Bark on-chain wallet for the fee of one of an exit’s transactions. An exit typically has several.	The on-chain CPFP transaction
`exit-claim`	Exit Claim	Exited bitcoin moved to the Bark on-chain wallet or another address, once the exit’s timelock ends	The on-chain claim transaction
`onchain-receive`	On-chain Receive	A payment to the Bark on-chain wallet from an on-chain address	The on-chain transaction that pays the Bark on-chain wallet
`onchain-send`	On-chain Send	A payment from the Bark on-chain wallet to an on-chain address	The on-chain transaction that pays the address
`onchain-internal`	On-chain Internal	Bitcoin moved within the Bark wallet in an on-chain transaction, such as part of a board, offboard, or exit	The on-chain transaction
`unknown`	The barkd subsystem name and kind, such as `bark.foo (bar)`	A transaction this plugin version doesn’t recognize	None

Later plugin versions may add new kind values. Write your code so that a value missing from this table doesn’t break it.

Identify a transaction

Use id to store transactions in your own system and to recognize the ones you’ve already seen. It’s unique within the store, including when a wallet is re-created and Bark numbers its payments from 1 again. Store a transaction only once it’s Confirmed. After that, its id and amount stay the same. Only its labels and confirmations can still change.

If you restore the wallet from its recovery phrase, Bark doesn’t bring back its transaction history. Ark and Lightning transactions from before the restore drop out of the list. The bitcoin that the restore recovers appears in no transaction, so balance leaves it out. Some transactions can come back with a different id. Match those to the ones you stored by outpoint or transactionHash.If you re-created or restored the wallet before plugin 0.11.0, store labels from before then can still show on unrelated transactions.

Match transactions to invoice payments

BTCPay gives each payment on an invoice a payment ID. Match it to transactions as follows:

Ark payments: BTCPay records one payment per received VTXO, with the ID txid-vout. Replace the hyphen with a colon and match the result to outpoint. The amounts are equal. Don’t match on transactionHash, which several transactions can share.
Lightning payments: The payment ID is the payment hash, so match it to paymentHash. BTCPay’s payment amount is what the customer paid, which is the transaction’s amount plus its fee.

Some Ark payments have a payment ID that covers several transactions:

{invoiceId}#ark-movement-{movementId}-{index}: Ark payments to invoices created before plugin 0.10.0, and the rare payment that the plugin can’t split by VTXO.
{invoiceId}#ark-movement-{movementId}: Ark payments recorded by plugin 0.7.0 or earlier.

Match these to the transactions with that movementId whose invoice label ref is the invoice ID. Their amounts add up to the payment. If one movement paid several invoices, its transactions carry no invoice label.

Get the wallet balance

curl -H "Authorization: token $API_KEY" \
  "https://btcpay.example.com/api/v1/stores/$STORE_ID/payment-methods/BTC-ARK/wallet"

{
  "balance": "0.0015",
  "unconfirmedBalance": "-0.0000062",
  "confirmedBalance": "0.0015062",
  "label": ""
}

The endpoint needs the same View wallets permission. Its response has the shape of BTCPay’s on-chain wallet overview, with four fields:

balance is the sum of every transaction’s amount, in BTC, across your off-chain balance and the Bark on-chain wallet. It leaves out the bitcoin that a restore from the recovery phrase brings back.
confirmedBalance adds up the Confirmed transactions, the part of the balance that can no longer change.
unconfirmedBalance adds up the Unconfirmed transactions. It’s negative while more is pending out than in, for example a fee during a refresh.
label is always empty.

The balance can be up to 15 seconds old. It differs from the balance on the Bark wallet page in four cases:

Lightning payment in flight: The endpoint already counts it as spent.
Unconfirmed exit claim: The Bark wallet page counts the claimed bitcoin twice, as a pending exit and as pending on-chain bitcoin. The endpoint counts it once.
Offboard or on-chain send in progress: Until Bark records the payment, the Bark wallet page leaves out the VTXOs it spends. The endpoint still counts them.
After a restore from the recovery phrase: The endpoint leaves out the bitcoin that the restore brought back.

Use BTCPay’s Lightning API

When Bark runs your store’s Lightning (see Lightning settings), BTCPay’s own Lightning API works with the Bark wallet. Its endpoints appear in the API documentation under Lightning (Store). Four of them read and pay through Bark:

Endpoint	What it does	Permission
`GET /api/v1/stores/{storeId}/lightning/BTC/invoices`	Lists the wallet’s Lightning invoices: paid ones, and unpaid ones Bark still waits on. Pass `pendingOnly=true` for unpaid ones only.	`btcpay.store.canviewlightninginvoice`
`GET /api/v1/stores/{storeId}/lightning/BTC/payments`	Lists the Lightning payments the wallet made, completed ones only unless you pass `includePending=true`, which adds pending and failed ones.	`btcpay.store.canuselightningnode`
`GET /api/v1/stores/{storeId}/lightning/BTC/payments/{paymentHash}`	Returns one payment the wallet made.	`btcpay.store.canuselightningnode`
`POST /api/v1/stores/{storeId}/lightning/BTC/invoices/pay`	Pays a BOLT11 invoice from your off-chain balance.	`btcpay.store.canuselightningnode`

Both lists come oldest first, at most 100 items per call. offsetIndex skips that many items, counted after filtering, so to read the next page, add the number of items you received. An invoice expires when its BOLT11 does, and the Ark server sets that expiry, whatever expiry was requested. Once Bark cancels an unpaid invoice, it forgets it, so the invoice drops out of the list. To pay an invoice, send its BOLT11:

curl -X POST -H "Authorization: token $API_KEY" -H "Content-Type: application/json" \
  -d '{"BOLT11": "lnbc..."}' \
  "https://btcpay.example.com/api/v1/stores/$STORE_ID/lightning/BTC/invoices/pay"

The request answers once the payment settles, with its fee and preimage, or fails. If the payment is still in flight after 30 seconds, or after the sendTimeout you pass in seconds (up to 10 minutes), the request answers 202 Accepted with the status Pending. Check it later with GET .../lightning/BTC/payments/{paymentHash}: a payment that can’t reach its recipient can take a few minutes to fail. Paying an invoice the wallet already paid returns that payment rather than paying it again.

Creating and reading single invoices and reading the Lightning balance work too. Node information, channels, and deposit addresses don’t apply to Bark, so those endpoints answer 503.

Errors

These are the errors of the two Store Wallet (Ark) endpoints.

Status	When
401	The request has no API key, or the key is invalid.
403	The API key lacks the View wallets permission for the store.
404	`paymentmethod-not-found`: Bark isn’t set up for the store.
422	A negative `skip` or `limit`, or an unknown status in `statusFilter`.
503	`not-available`: the store’s Bark wallet couldn’t be reached, or didn’t return everything the list needs. When the wallet answered only in part, the message names what’s missing.

Payment method ID migration

Bark’s payment method ID is BTC-ARK, alongside BTCPay’s own BTC-CHAIN and BTC-LN. Before plugin 0.10.0 it was BARK. Invoices created before the upgrade keep BARK and still settle, so a tool that reads payment method IDs from invoices, payments, or webhooks sees both.

​Create an API key

​List the transactions

​Read the fields

​Transaction types

​Identify a transaction

​Match transactions to invoice payments

​Get the wallet balance

​Use BTCPay’s Lightning API

​Errors

​Payment method ID migration

Create an API key

List the transactions

Read the fields

Transaction types

Identify a transaction

Match transactions to invoice payments

Get the wallet balance

Use BTCPay’s Lightning API

Errors

Payment method ID migration