# Connect your broker (/docs/activation/broker-connection)



Broker connection is **two different scopes**, split by the two-signer rule.
**Broker-read** — the reversible import of your positions and watchlist that
powers own-book Frames and "sim your own book" — is **agent-supplied**: your
agent is the integration. **Broker-execution** — the legally-weighted authority
to place orders — is separate, human-signed, and arrives later. Kestrel never
takes custody, never buys a data license, and is not a broker-dealer.

## Broker-read: your agent is the integration [#broker-read-your-agent-is-the-integration]

The platform holds **no broker credentials** for the read path and runs **no
third-party OAuth client** against your brokerage. Instead, you authorize your
broker's own tools — its agent-account MCP or API — into **your own agent**, and
your agent hands the book to the platform when it requests own-book Frames or a
sim. The book flows through the agent you already control; nothing about your
brokerage is stored on this side.

That is the design point: the agent already has your delegated authority, so
own-book Frames ride the authority you granted it, not a second delegation to
us. Own-book **perception** is free-tier; own-book **sims and backtests** are
paid, priced per artifact.

## Two signatures, by scope [#two-signatures-by-scope]

Authorization on the platform is one primitive — the Envelope — with two signer
classes. A **wallet** may sign reversible, commerce-only scope (data, sim, grade,
paper). A **human** must sign anything carrying a legal agreement — the
broker-**execution** connection and live trading authority. The two-signer rule
applies **per scope, not per vendor**: reading your book through your agent needs
no execution signature, and no machine payment can establish execution authority.

## Broker-execution: the human-signed leg [#broker-execution-the-human-signed-leg]

Placing real orders is a separate capability that arrives at promotion, at the
term sheet, under a **human-signed live Envelope** and its pre-flight
EnvelopeGuard. It lands late by design, and it is **paper first**:

* **Paper** runs against a live feed with **simulated fills, never live money** —
  a bounded practice environment with hard order, position, and notional caps.
* **Live** trades real capital and is enabled **only** behind a separate human
  signature on the live Envelope, after app review.

Kestrel does not offer live trading today, and nothing on the read path can place
an order. Live capital moves only when a human signs for it.

## Connection states [#connection-states]

| State                 | Meaning                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `agent-supplied`      | Your agent holds the broker authority and hands the book to the platform on request. The platform stores no broker credential. |
| `paper`               | A human-signed paper Envelope is active — simulated fills against a live feed, hard-capped, never live money.                  |
| `live-pending-review` | A live Envelope is requested but cannot trade: it awaits app review and a human signature.                                     |

Revoke a broker's authority in your agent at any time — you granted it there, and
you control it there. A paper or live Envelope is revoked from your signed-in
human account, and the platform honors the revocation immediately.