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

# Trade intents

> Server-side intent objects that route to Kalshi or Polymarket execution under risk-gate enforcement.

A trade intent is a server-owned object that says "I want to buy/sell X at price Y, conditional on conditions Z". Once submitted, the autopilot or terminal executes when conditions are met, subject to risk gates.

## Lifecycle

```text theme={null}
create  →  pending  →  active  →  filled | cancelled | expired
```

## Create

```bash theme={null}
sf intent buy KXRATECUT-26DEC31 100 --price 65 --thesis <id>
sf intent sell KXBTC100K 50 --price 30 --json
```

Or via API:

```http theme={null}
POST /api/intents
Authorization: Bearer sf_live_...
Content-Type: application/json

{
  "ticker": "KXRATECUT-26DEC31",
  "side": "yes",
  "action": "buy",
  "qty": 100,
  "priceCents": 65,
  "thesisId": "th_..."
}
```

## List

```bash theme={null}
sf intent list --json
sf intents --json --status active
```

## Cancel

```bash theme={null}
sf intent cancel <intent-id>
```

## Reasons an intent can be rejected

The server runs a gate evaluator on every intent before persisting:

* `RISK_GATE_FAIL` — exceeds per-market or per-day risk limits.
* `STALE_PRICE` — the price you specified is no longer reachable.
* `INSUFFICIENT_BALANCE` — Kalshi/Polymarket balance below what the order would require.
* `CATEGORY_BLOCKED` — your config excludes the market's category (e.g., sports).
* `THESIS_MISMATCH` — the intent's edge doesn't match the linked thesis's direction.

See [Errors](/reference/errors) for the full code list.

## Execution

Once pending, intents are picked up by:

* **portfolio-autopilot** ticks if `execution_mode = 'live'`.
* **manual execution** via the web terminal trade ticket.
* **direct CLI** via `sf buy` / `sf sell`, which bypass the intent layer entirely.

## Next steps

<CardGroup cols={2}>
  <Card title="Intents API" href="/api-reference/execution-intents">
    Endpoint shapes for create / list / cancel.
  </Card>

  <Card title="Risk gates" href="/concepts/risk-gates">
    The pre-trade checks every intent runs through.
  </Card>

  <Card title="Thesis lifecycle" href="/build/thesis-lifecycle">
    Link intents to theses for automated edge tracking.
  </Card>
</CardGroup>