> For the complete documentation index, see [llms.txt](https://bsv.brc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bsv.brc.dev/wallet/0112.md).

# Balance Baskets: Backwards-Compatible Basket Balance Queries

Ty Everett (<ty@projectbabbage.com>)

## Abstract

This specification defines a backwards-compatible extension to [BRC-100](https://bsv.brc.dev/wallet/0100.md) that allows applications to query a basket's balance using a `balance` prefix in `listOutputs`. The wallet returns no outputs and re-purposes `totalOutputs` to report the sum of satoshis contained in all outputs in the specified basket. P-basket module balances retain the numeric representation described below, with exact internal aggregation before conversion to a numeric summary.

## Motivation

Applications often need a quick way to retrieve the total value of a basket without enumerating all outputs. Extending `listOutputs` with a special basket prefix preserves API compatibility while enabling efficient balance queries.

## Specification

### Balance Basket Prefix

A balance query is requested by using a basket name that begins with `balance` (a lowercase "balance" followed by a space). The remainder of the basket string is treated as the target basket name.

Example:

* `listOutputs({ basket: "balance savings" })`

### Required Behavior

When `listOutputs` is called with a basket name beginning with `balance` :

* The wallet must return **no outputs** in the results array.
* The wallet must re-purpose `totalOutputs` to contain the sum (in satoshis) of **all** outputs currently in the target basket that match any provided tag filters.
* The wallet must still enforce all normal permission checks for access to the target basket.
* The wallet must apply any basket resolution, ownership, internalization, and tag-filtering rules as if the caller had requested outputs from the target basket directly.
* No regard is given to the `limit` or `offset` parameters, since this is a sum of total value.

This behavior is backwards compatible because existing callers will ignore the empty outputs array and read `totalOutputs` as the count of outputs; with this extension, `totalOutputs` is intentionally redefined **only** when the `balance` prefix is used.

### BRC-99 Module Baskets

For module-defined baskets in [BRC-99](https://bsv.brc.dev/wallet/0099.md):

* `balance p <module> <basket>` is **never** allowed and must be rejected.
* `p <module> balance <basket>` **may** be implemented at the module's discretion.

If a module chooses to implement balance semantics, it may interpret `balance <basket>` according to its own rules, including permissioning and aggregation behavior. If a module does not implement this, the wallet must reject the request as unsupported.

### Module Balance Representation

Every supported `p <module> balance <basket>` query MUST use this profile. The module defines its units, eligible records, permissions and tag filters. The result has `outputs: []`, no `BEEF`, and the nonnegative aggregate in `totalOutputs` as a **number** at both the API and JSON boundaries. The number MUST be a finite nonnegative integer. On a JavaScript system it is exact through 2^53 and may be rounded above; enumerating the actual outputs is required for exact accounting or value movement. JSON summary values have no uint64 ceiling. Limits on individual outputs remain the module's concern.

In the BRC-100 binary response, this field is the numeric VarInt of any `listOutputs` result. A numeric value of 2^64 or more does not fit the VarInt and MUST be answered with an error, including a smaller exact aggregate that rounds to 2^64 before serialization. Canonical CompactSize decoding is required; a valid uint64 frame may round when converted to a JavaScript Number. The remaining response fields are unchanged. Ordinary output counts, including P-basket inventories, and all non-P basket responses retain their existing API types and wire formats.

Compute sums exactly. Unsupported module profiles, incapable adapters or exceeded implementation resource limits MUST produce explicit errors, never wrapped, saturated or partial balances. Receivers MUST reject noncanonical or wrong-type results and validate lengths before allocation. Implementations MUST document any resource limits; these do not make larger holdings invalid. Established numeric clients retain their existing representation. Older codecs may explicitly reject magnitudes beyond their implemented bounds; never truncate or claim compatibility outside tested bounds. Exact-balance extensions must be additive; a numeric result must not become a string or a number/string union.

### Validation Rules

* The `balance` prefix must be lowercase and followed by a single space.
* The target basket name that follows must conform to the basket naming rules in [BRC-100](https://bsv.brc.dev/wallet/0100.md) and [BRC-99](https://bsv.brc.dev/wallet/0099.md) where applicable.
* If the target basket does not exist or is not accessible, the wallet must return the appropriate error according to [BRC-100](https://bsv.brc.dev/wallet/0100.md).

## Conclusion

By reserving a `balance` prefix within basket queries, this specification enables efficient balance retrieval while remaining compatible with existing `listOutputs` behavior and the broader wallet permission model.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://bsv.brc.dev/wallet/0112.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
