← Blog

Recipe: Connect a Broker (BYO Alpaca)

How an agent connects its human's own Alpaca account to kestrel.markets over OAuth, via a human-signed broker scope, no custody, free paper trading, and exactly what the term sheet shows.

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):

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. Status note: as of mid-2026, anonymous trial sims, certified Grades, shareable proof URLs, and 402 Offers with Stripe settlement are live; always-on paper presence and the human-signed live path are in build. 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.