> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lean.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# An AI agent that trades within a budget

> A research agent proposes trades on a read only key; an execution key places them after approval.

**Who it's for:** teams putting LLM agents (Claude, GPT or your own models) into a trading or
treasury workflow.

**What you build:** an AI analyst that researches markets and proposes trades. A person, or a
policy, approves each one, and the API executes it within limits you set.

## Call sequence

**1. Research on a read only key**

Give the research agent a key with only the `read` scope. It can call
[List markets](https://docs.lean.xyz/api-reference/markets/list-markets.md),
[Quote a market](https://docs.lean.xyz/api-reference/markets/quote-market.md),
[Get a market orderbook](https://docs.lean.xyz/api-reference/markets/retrieve-market-book.md) and
[Get recent trades](https://docs.lean.xyz/api-reference/markets/list-market-trades.md). An order attempt returns 403.

**2. Propose with a preview**

The agent writes a proposal and calls [Preview an order](https://docs.lean.xyz/api-reference/orders/preview-order.md).
The preview is the "here's exactly what would happen" for the approval step: legs, quantity,
prices and whether it `would_submit`.

**3. Execute on approval**

An execution key with the `trade` scope and lowered limits calls
[Place an order](https://docs.lean.xyz/api-reference/orders/create-order.md) with the `client_order_id` from the
proposal, so a double approval never trades twice.

**4. Close the loop**

The stream and [List fills](https://docs.lean.xyz/api-reference/orders/list-fills.md) feed results back to the agent.
[Pause order placement](https://docs.lean.xyz/api-reference/account/pause-trading.md) lets the agent, or a monitor,
stop everything. A person signed in to Lean can revoke either key at any time with
[Revoke an API key](https://docs.lean.xyz/api-reference/api-keys/revoke-api-key.md); a revoked key gets 401.

## Starter

Create both keys in Lean under Settings → **API**: one with only `read`, one with `trade` and low
limits. Then:

```bash theme={"dark"}
# Research agent (read only key)
curl -sS "$LEAN_API_URL/v1/markets?league=nfl&limit=20" \
  -H "Authorization: Bearer $LEAN_READ_KEY"

# Approval step: show the human this response
curl -sS -X POST "$LEAN_API_URL/v1/orders/preview" \
  -H "Authorization: Bearer $LEAN_READ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_order_id":"proposal-42","market_id":"'"$MARKET_ID"'","action":"buy",
       "quantity":"5","limit_price":"0.42","time_in_force":"ioc"}'

# Approved: the execution key sends the same body to /v1/orders
```

## Guardrails

* **Read only keys.** A `read` key can research and preview, and is refused with 403 if it tries
  to place an order.
* **Spending caps.** Per order and rolling 24 hour limits live on the execution key, and the key
  can only lower them.
* **Idempotency.** The proposal's `client_order_id` makes execution safe to retry.
* **Kill switch and revocation.** Pause a key or the whole account in one call, and revoke a key
  from Lean at any time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.