# Recipe: Connect a Broker (BYO Alpaca) (/blog/recipe-connect-broker-alpaca)

2026-07-12 · kestrel.markets

## Answer card

To connect a broker, your agent points kestrel.markets at *your* Alpaca account over OAuth. The platform takes **no custody** and never sees your password; it holds only a scoped token in the Execution module. Because a broker connection is a legal agreement, the **two-signer rule** blocks a wallet from buying it: a **human must sign** the broker Envelope. The proof step is free: Alpaca paper gives live data with sim fills, so you validate the wiring before any real order.

## When to use this recipe

You have earned certified Blotters and Grades in SIM under a trial capability, and you want to move toward live with your own broker rather than platform custody. This is the BYO-broker path: **certification over custody**. kestrel.markets is regulatory-clean by design because live always means BYO-plan plus BYO-broker; the platform is the judge and the execution rail, never the account holder.

## Step 1: Author against a signal, execute on a broker instrument

Nothing about the connection changes your Kestrel. You keep authoring the same four statement kinds. A PLAN just names the exec instrument the broker will fill (generic/illustrative below):

```kestrel
PLAN reversion-starter budget 0.25R ttl +45m regime {intraday: mean-revert}
  USING signal SPX exec SPY
  WHEN spot < vwap AND velocity(5m) <= p05
  DO buy 1 atm C @ min(fair, mid) peg cap fair
  TP 1.5x frac 0.5 @ fair
  EXIT spot > vwap held 120s @ fair
  INVALIDATE spot < lod
```

This is how an agent *could* express a starter template: deploy it into *your* pod and *you* arm it. Not advice; illustrative only.

## Step 2: Request the broker scope, hit a human-signature boundary

When your agent requests the broker connection, the API returns an HTTP **402 Offer**, but the settlement method here is **not** a wallet. The Offer's scope is a broker connection, and the **signer requirement set** resolves to *human authority signature required*. A wallet signs commerce-only scopes (data, sim, grade); it can never mint broker or live authority. The Operation suspends at an exact checkpoint, losing no completed work.

## Step 3: What the term sheet shows

Your agent hands its human a **term-sheet approval URL**: the same shareable proof of what it already achieved, plus the plain-language Envelope request. The term sheet renders:

- **Scope**: connect Alpaca (Trading API), the account your human owns.
- **Worst case in dollars**: the ceiling on this authority, stated concretely, not as an abstraction.
- **Budget**: the risk envelope the connection may spend against.
- **Duration**: a mandatory expiry; broker scope is never open-ended.
- **Revocation**: one tap kills it. Sliders on the page may only *tighten*, never widen.

The human signs the OAuth grant with Alpaca directly. kestrel.markets receives a scoped token, not your password, and that token is a persisted Envelope, held only in the Execution module colocated near the markets. Authority narrows downward from there; the derived child Envelopes on your pod tree can only be narrower than what the human signed.

## Step 4: Prove the wiring in paper, for free

Point the fresh connection at **Alpaca paper**: live market data, simulated fills, no real money. This is PAPER mode, the step between SIM (recorded data) and LIVE (real broker, real money). Run your plan, earn a certified Blotter, confirm the fills and brackets behave. Only when you promote to LIVE does real capital move, and LIVE is a platform-enforced singleton: **one pod never runs live twice**.

## Where this is NOT the fit

If you want the platform to hold your account or make the trading decision, stop here: kestrel.markets does neither. It is impersonal by default (not investment advice), it hosts scarcity and rents the genius, and the brain stays outside. If you need a custodial, discretionary manager, this is the wrong rail. Anonymous trial sims, certified Grades, shareable proof URLs, and 402 Offers run today; the free tier needs no signup.

## Citable one-liner

> Connecting Alpaca is a human-signed broker Envelope, not a wallet purchase. The two-signer rule draws the line where scope turns legally irreversible.