Cookbook - Bron Developer

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.

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

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

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.

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.

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

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.

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.

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:

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:

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

Order of body merge:

Baseline from --file <path> or --json '{...}' (mutually exclusive).
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.

​1. Bulk-approve every withdrawal awaiting approval

​2. Watch a single transaction to completion

​3. Daily treasury snapshot — balances + USD totals

​4. Audit-trail export for compliance

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

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

​7. Pre-flight a transaction with tx dry-run

​8. Body composition with --file + per-field overrides