> ## Documentation Index
> Fetch the complete documentation index at: https://second.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use your Bark wallet through the API

> List your store's Bark wallet transactions and balance over BTCPay's Greenfield API, match them to BTCPay invoice payments, and use BTCPay's Lightning API with Bark.

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)**.

> [!NOTE]
>
> 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](#identify-a-transaction). |
| `kind` | See [Transaction types](#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](#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](/docs/btcpay/dashboard#label-your-transactions) 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](/docs/btcpay/dashboard#transactions) 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](/docs/btcpay/reporting) 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](/docs/learn/exit#the-emergency-exit-process), 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](/docs/btcpay/vtxos) 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](/docs/btcpay/settings#danger-zone) | The VTXO's final [exit transaction](/docs/learn/exit#the-emergency-exit-process), 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 |

> [!TIP]
>
> 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.

> [!NOTE]
>
> If you [restore the wallet from its recovery phrase](/docs/btcpay/backups#restore-a-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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "Authorization: token $API_KEY" \
  "https://btcpay.example.com/api/v1/stores/$STORE_ID/payment-methods/BTC-ARK/wallet"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/docs/btcpay/settings#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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.