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

## 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):

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

### 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) and [BRC-99](https://bsv.brc.dev/wallet/0099) 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).

## 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.