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

# LLM agent integration

`bron` is built to be driven by an LLM agent (Claude Code, Codex, Cursor, custom tooling) without any wrapping layer. This page captures the contract: what an agent can rely on, what surfaces it should query first, and how to keep it from doing damage.

## Discovery in one call

The agent doesn't need to memorise the API. `--schema` emits the complete CLI surface as one OpenAPI 3.1 JSON document:

```bash theme={"system"}
bron --schema                          # full CLI: every command, every flag, every type
bron <resource> <verb> --schema        # single-command fragment
bron --output yaml <r> <v> --schema    # same dump in YAML
```

What's in there:

* Every command path (`accounts list`, `tx withdrawal`, `tx subscribe`, …)
* Every flag, with its type, `enum` values, defaults, and short description
* Every request body shape, by `transactionType` discriminator for `tx create`
* Every response shape, indexed by HTTP status code
* The `--embed` tokens each list endpoint accepts, with the resulting `_embedded` shape

For an agent that just spawned, `bron --schema | head -200` is enough orientation to start composing valid commands. Agents driving the [MCP server](/sdk/cli/mcp) instead have an even cheaper entry point: a single `bron_help` call returns the data model, any tool's response shape, and worked `jq` recipes on demand.

## The recommended agent flow

```
1. user: "approve every signing-required withdrawal under $1k"
   ↓
2. agent: bron tx --help               # → see verbs (list, get, approve, ...)
   agent: bron tx list --help          # → see filters
   ↓
3. agent: bron tx list \
            --transactionStatuses signing-required \
            --transactionTypes withdrawal \
            --output jsonl
   → JSONL: agent parses, picks the ones with params.amount < 1000
   ↓
4. agent: bron tx approve <tx>         # for each match
   → exit 0 = success, exit ≠ 0 = stop and report to user
```

Three loops covers most workflows: discover → query → act. `--schema` for static introspection, `--help` for human prose where helpful, `--output jsonl` for machine consumption.

## Stable contracts

These won't break across `0.x` releases:

| Surface                   | Contract                                                                         |
| ------------------------- | -------------------------------------------------------------------------------- |
| Exit codes                | `0` success; `1` other; `3` 401/403; `4` 404; `5` 400; `6` 409; `7` 429; `8` 5xx |
| Error envelope on stderr  | `error: <message>` line + `status:` / `code:` / `id:` lines                      |
| `--schema` document shape | Strict OpenAPI 3.1 fragment; field paths + types                                 |
| Flag/verb names           | `tx`, `tx list`, `tx withdrawal`, `--output`, `--columns`, etc.                  |
| Date rendering            | ISO 8601 UTC in every output format                                              |
| Numeric strings           | Decimals stay strings (no `float64` coercion)                                    |

`--help` text wording, color, and table layout are NOT part of the stable surface. Don't grep `--help` output in agent code; use `--schema`.

## Idempotency

Every `tx <type>` and `tx create` call accepts `--externalId <key>`. Bron de-duplicates by `(workspace, externalId)`: retrying a call with the same key returns the **existing** transaction, not a duplicate.

For an agent, this is critical — LLMs retry on perceived failure, and without an idempotency key a retry would create a second withdrawal:

```bash theme={"system"}
# DON'T — agent retries this on a hiccup → double-spend
bron tx withdrawal --accountId acc --params.amount=100 ...

# DO — agent retries this on a hiccup → same tx, no double-spend
bron tx withdrawal --externalId "agent-task-7f3a" --accountId acc --params.amount=100 ...
```

Generate `--externalId` from a stable identifier of the agent's task (task ID, request ID, hash of the prompt + timestamp) — anything that would be the same on retry.

## Dry-runs before real submits

`bron tx dry-run` validates a transaction body against the API without submitting it: returns the expected fees, blockchain ETA, validation errors:

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

For an agent acting on behalf of a human, a dry-run + summary + explicit confirmation step is the standard pattern. Same body schema as the live call, so the agent can reuse the same JSON.

## Output for agents

The default JSON is fine. JSONL is often easier to parse line-by-line in a streaming agent:

```bash theme={"system"}
bron tx list --output jsonl
```

For really long lists, project just the fields the agent needs:

```bash theme={"system"}
bron tx list \
  --transactionStatuses signing-required \
  --output jsonl \
  --columns transactionId,transactionType,params.amount,params.assetId,createdAt
```

Less to parse, less context spent.

<Warning>
  **Intent vs settlement.** `params.amount` is what a transaction *requested* (the intent / quote); `_embedded.events[].amount` is what *actually moved on-chain* (the settlement). For any financial total — volume, net flow, P\&L — aggregate `_embedded.events[]`, never `params.amount`. Summing `params.amount` looks right but is wrong for swaps, bridges, intents, fiat and fee-bearing transfers. Events are omitted by default — add `--includeEvents` (CLI) or `includeEvents: true` (MCP) to fetch them. `params.amount` is still correct when you genuinely want the requested amount, e.g. filtering withdrawals under a threshold.
</Warning>

## Agent-friendly help topic

```bash theme={"system"}
bron help agents
```

Prints a concise, machine-readable orientation guide: the commands you'll need most, the schema entry point, the idempotency contract, the exit-code map. Reference it from agent system prompts so a fresh agent can self-orient in one call.

## Dedicated skills repo

For Claude Code, packaged skills live in [bronlabs/bron-skills](https://github.com/bronlabs/bron-skills) — `SKILL.md` files with `allowed-tools` declarations, references, and worked examples for the most common flows (`bron-tx-send`, `bron-tx-subscribe`, `bron-balances-read`, `bron-address-book`).

Install for Claude Code in one shot:

```bash theme={"system"}
git clone https://github.com/bronlabs/bron-skills ~/src/bron-skills
~/src/bron-skills/install/install-claude.sh
```

Cross-agent project memory ([`AGENTS.md`](https://github.com/bronlabs/bron-skills/blob/master/AGENTS.md) standard) ships in the same repo for Codex, Cursor, Aider, GitHub Copilot, Junie. Drop the file into any project that uses `bron` and the agent picks it up automatically.

## Safety guardrails to write into your agent prompt

Suggested constraints for a Bron-driving agent — copy into your system prompt and tune:

* **Always** pass `--externalId` on any `tx <type>` or `tx create` call. Generate it from a stable task identifier.
* **Never** pipe credentials anywhere except the local profile config. Don't log JWK contents.
* **Confirm before approve / decline / cancel / sign** — these are state-changing, often irreversible. Show the human the affected transactions and wait for explicit OK.
* **Use `tx dry-run`** before any first-time withdrawal pattern, to surface fees and validation errors.
* **Bound query windows** — `--createdAtFrom` / `--createdAtTo` on list queries to avoid pulling thousands of records into context.
* **Treat exit codes as truth** — `bron tx approve $tx || stop_and_report` instead of grepping success messages.