# Balance Baskets: Backwards-Compatible Basket Balance Queries Ty Everett () ## Abstract This specification defines a backwards-compatible extension to [BRC-100](/brc/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. ## 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](/brc/wallet/0099.md): * `balance p ` is **never** allowed and must be rejected. * `p balance ` **may** be implemented at the module's discretion. If a module chooses to implement balance semantics, it may interpret `balance ` 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](/brc/wallet/0100.md) and [BRC-99](/brc/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](/brc/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: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://hub.bsvblockchain.org/brc/wallet/0112.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.