# Basket and Custom Instructions Extension for Bitcoin Outpoints

Ty Everett (`ty@projectbabbage.com`)

## Abstract

This document defines a minimal extension to [BRC-36](/outpoints/0036.md) for associating a Bitcoin outpoint with a wallet basket and, optionally, with custom instructions whose meaning is defined by that basket. The purpose of this extension is to support interoperable wallet-managed output organization without standardizing wallet-internal classification systems or forcing a universal instruction schema.

## Motivation

Modern wallets do more than merely store outputs. They organize outputs into permissioned collections, often called baskets, and attach application-relevant metadata needed to later interpret or spend those outputs. This pattern is reflected in [BRC-46](/wallet/0046.md), [BRC-100](/wallet/0100.md), and current Wallet Toolbox implementations.

The original version of BRC-37 used a broad `spendingInstructions` concept whose structure was left entirely to wallet software. That approach was too vague to provide meaningful interoperability. This revision keeps the extension intentionally small and precise: it standardizes basket association and optional custom instructions, while leaving basket-specific semantics to the basket itself and the higher-layer protocols that use it.

## Specification

### Extended Object

A BRC-37 object is a [BRC-36](/outpoints/0036.md) object extended with the following fields:

* `basket` (required): The basket with which the outpoint is associated.
* `customInstructions` (optional): Basket-defined custom instructions associated with the outpoint.

### Semantics

* The `basket` field identifies the basket context in which the output is to be interpreted.
* The meaning of `customInstructions`, when present, is determined by the basket named in `basket`.
* BRC-37 does not define a universal schema for `customInstructions`.
* BRC-37 does not require every basket to use `customInstructions`.
* Software that understands a basket's semantics may interpret the corresponding `customInstructions` value. Software that does not understand that basket may still transport or store the value unchanged.

### Scope Boundaries

BRC-37 does not standardize:

* wallet-internal state such as `spendable` or `change`
* wallet-specific classification fields such as `purpose` or `type`
* storage relations such as spending links, sequence bookkeeping, or script offsets
* a general schema for all possible spending metadata

Those concerns remain outside the scope of this specification unless separately standardized by another BRC.

## Example Guidance

The following examples are non-normative and illustrative only.

### Basket-Defined Meaning

A wallet may define a basket whose outputs all use the same `customInstructions` convention. Software that requests outputs from that basket can then interpret `customInstructions` according to the basket's documented semantics.

### BRC-29 Example

In one possible implementation, outputs placed in the `default` basket may represent [BRC-29](/payments/0029.md) payments. In that context, `customInstructions` could contain a JSON-serialized object carrying payment-related context such as a sender identity key, derivation prefix, derivation suffix, or other information useful to the receiving wallet or application.

This example is illustrative only. BRC-37 does not require the `default` basket to behave this way, nor does it impose a universal JSON schema for such instructions.

## Relationship to Other Standards

* [BRC-36](/outpoints/0036.md) defines the portable base output object.
* [BRC-46](/wallet/0046.md) defines basket-oriented wallet behavior.
* [BRC-100](/wallet/0100.md) defines the current interoperable wallet interface through which basket-associated outputs are commonly exchanged.

## Example

```json
{
  "outpoint": "7001295a287fee8e7ad5de58ed30bd61923977ddc9b7a44830ebb9a68b12dc39.0",
  "satoshis": 500,
  "lockingScript": "76a9148055582669432149141abcf887fced6881f7404288ac",
  "tx": "01010101...",
  "basket": "default",
  "customInstructions": "{\"senderIdentityKey\":\"03...\",\"derivationPrefix\":\"...\",\"derivationSuffix\":\"...\"}"
}
```

## Implementation

Implementations of BRC-37 should adhere to the following guidelines:

* Preserve unknown `customInstructions` values unchanged when transporting or storing BRC-37 objects.
* Define basket-specific semantics in the protocol or implementation documentation for that basket.
* Avoid treating BRC-37 as a general container for arbitrary wallet-internal state.


---

# 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://bsv.brc.dev/outpoints/0037.md?ask=<question>
```

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.