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

# Cookbook

Real-world recipes. Each one is a complete shell snippet you can copy, adjust, and run.

## 1. Bulk-approve every withdrawal awaiting approval

You're the second-of-two approvers for a batch of payouts. Approve all `waiting-approval` withdrawals in one go.

```bash theme={"system"}
# Dry run — list what would be approved.
bron tx list \
  --transactionStatuses waiting-approval \
  --transactionTypes withdrawal \
  --output table \
  --columns transactionId,params.amount,params.assetId,params.toAddress,description

# Approve them.
bron tx list \
  --transactionStatuses waiting-approval \
  --transactionTypes withdrawal \
  --output jsonl \
  | jq -r '.transactionId' \
  | while read -r tx; do
      echo "approving $tx"
      bron tx approve "$tx"
    done
```

For safety, add a `--createdAtFrom` filter to scope the batch to a known window so a stale waiting-approval from last week doesn't sneak in.

## 2. Watch a single transaction to completion

Trigger a withdrawal, then block until it's `completed` (or `failed`).

```bash theme={"system"}
EXTID="payout-$(date +%s)"

TX=$(bron tx withdrawal \
       --externalId  "$EXTID" \
       --accountId   <accountId> \
       --params.amount=100 \
       --params.assetId=5000 \
       --params.networkId=ETH \
       --params.toAddressBookRecordId=<recordId> \
       --output json | jq -r '.transactionId')

echo "tx=$TX"

bron tx subscribe \
  | jq --arg id "$TX" -rc 'select(.transactionId == $id) | "\(.status)\t\(.updatedAt // "")"' \
  | while IFS=$'\t' read -r status updated; do
      echo "$TX: $status @ $updated"
      case "$status" in
        completed) exit 0 ;;
        canceled|expired|failed-on-blockchain|removed-from-blockchain|error) exit 1 ;;
      esac
    done
```

The `--externalId` is critical: if the script crashes between `bron tx withdrawal` and the wait loop and you re-run, idempotency guarantees no duplicate withdrawal. See [`bron help idempotency`](/sdk/cli/errors) for the full contract.

## 3. Daily treasury snapshot — balances + USD totals

A nightly cron that posts a CSV of every non-empty balance with USD value to a shared bucket.

```bash theme={"system"}
DATE=$(date -u +%Y-%m-%d)

bron balances list --nonEmpty true --embed prices --output jsonl \
  | jq -r '[
      .accountId,
      .symbol,
      .totalBalance,
      ._embedded.usdPrice,
      ._embedded.usdValue
    ] | @csv' \
  | (echo '"accountId","symbol","totalBalance","usdPrice","usdValue"'; cat) \
  > "/tmp/balances-$DATE.csv"

aws s3 cp "/tmp/balances-$DATE.csv" "s3://my-bucket/treasury/balances/"
```

`--embed prices` saves you a separate `bron symbols prices` call per balance — the join happens server-side under `_embedded`.

## 4. Audit-trail export for compliance

Every withdrawal in a quarter, with creator + amount + destination, as a single JSON Lines file.

```bash theme={"system"}
QUARTER_FROM=2026-01-01T00:00:00Z
QUARTER_TO=2026-04-01T00:00:00Z

bron tx list \
  --transactionTypes withdrawal \
  --createdAtFrom "$QUARTER_FROM" \
  --createdAtTo   "$QUARTER_TO" \
  --transactionStatuses completed \
  --embed assets \
  --output jsonl \
  > "/tmp/audit-Q1-2026.jsonl"

# How many?
wc -l /tmp/audit-Q1-2026.jsonl

# Sum USD value.
bron balances list --nonEmpty true --embed prices --output jsonl \
  | jq -s 'map(._embedded.usdValue // "0" | tonumber) | add'
```

The `Audit Trail` button in the UI calls the same endpoint — the CLI version is reproducible and trivial to integrate into a pipeline.

## 5. Settled volume for a period — sum the events, not the intents

To total what actually moved, sum `_embedded.events[]` (the on-chain settlement facts), not `params.amount` (the requested amount). They differ for swaps, bridges, intents, fiat and any fee-bearing transfer. Pass `--includeEvents` to fetch the events array.

```bash theme={"system"}
# Total USD volume settled in May.
bron tx list \
  --createdAtFrom 2026-05-01T00:00:00Z \
  --createdAtTo   2026-06-01T00:00:00Z \
  --includeEvents \
  --output json \
  | jq '[.transactions[]._embedded.events[]? | (.usdAmount // "0" | tonumber)] | add'

# Net flow per asset (inflows positive, outflows negative).
bron tx list --createdAtFrom 2026-05-01T00:00:00Z --includeEvents --output json \
  | jq '
      [ .transactions[]._embedded.events[]?
        | { k: (.assetId + "|" + .symbol),
            amt: ((.amount // "0" | tonumber) * (if .eventType == "in" then 1 else -1 end)) } ]
      | group_by(.k)
      | map({ asset: .[0].k, net: (map(.amt) | add) })'
```

From an MCP host the same aggregation goes in the `jq` tool argument, so only the total comes back into context — see [Shaping responses](/sdk/cli/mcp#shaping-responses-with-fields-and-jq).

## 6. Live ops dashboard — react to failed broadcasts in real time

A monitoring loop that subscribes to all failed broadcasts in a workspace and pages the on-call.

```bash theme={"system"}
bron tx subscribe --transactionStatuses failed-on-blockchain,removed-from-blockchain,manual-resolving,error \
  | jq -rc '{
      tx:       .transactionId,
      type:     .transactionType,
      amount:   .params.amount,
      asset:    .params.assetId,
      account:  .accountId,
      time:     .updatedAt
    }' \
  | while read -r line; do
      echo "$line"
      curl -fsS -X POST "$ALERT_WEBHOOK" \
        -H 'content-type: application/json' \
        -d "{\"text\":\"broadcast failed: $line\"}"
    done
```

Auto-reconnect means this loop keeps running across server restarts and idle timeouts — the connection is reopened in seconds without intervention.

## 7. Pre-flight a transaction with `tx dry-run`

Before submitting a real `bron tx withdrawal`, dry-run it to surface validation errors and fee estimates.

```bash theme={"system"}
cat > /tmp/tx.json <<EOF
{
  "accountId":  "<accountId>",
  "externalId": "preflight-$(date +%s)",
  "params": {
    "amount":     "100",
    "assetId":    "5000",
    "networkId":  "ETH",
    "toAddressBookRecordId": "<recordId>"
  }
}
EOF

bron tx dry-run --file /tmp/tx.json --transactionType withdrawal --output yaml
```

If the dry-run prints fee + ETA + no errors, submit for real:

```bash theme={"system"}
bron tx withdrawal --file /tmp/tx.json
```

## 8. Body composition with `--file` + per-field overrides

Reuse a JSON template, override the amount and idempotency key per call:

```bash theme={"system"}
bron tx withdrawal \
  --file ./templates/vendor-payout.json \
  --externalId "payout-$(date +%s)" \
  --params.amount=250
```

Order of body merge:

1. Baseline from `--file <path>` or `--json '{...}'` (mutually exclusive).
2. Per-field flags (`--<name>` / `--<a>.<b>`) override matching paths in the baseline.

`--file -` reads the baseline from stdin — handy for piping templates from another tool.