> ## 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.

# Execution Intents

> Declare, inspect, update, and cancel Kalshi and Polymarket execution intents.

Execution intents are the software workflow layer between analysis and venue order routing. The SDK and Agent SDK execution surfaces support Kalshi and Polymarket through the runtime-backed intent path.

## Create an intent

```http theme={null}
POST /api/intents
```

Required fields:

| Field            | Meaning                                   |
| ---------------- | ----------------------------------------- |
| `action`         | `buy` or `sell`                           |
| `venue`          | `kalshi` or `polymarket`                  |
| `marketId`       | Kalshi ticker or Polymarket CLOB token id |
| `marketTitle`    | Human-readable title                      |
| `direction`      | `yes` or `no`                             |
| `targetQuantity` | Contract quantity                         |

Optional fields include `maxPrice`, `executionStyle`, `triggerType`, `triggerPrice`, `triggerAt`, `softCondition`, `source`, `sourceId`, and `autoExecute`.

SDK and Agent wrappers:

```ts theme={null}
await sf.intents.create({ venue: "kalshi", action: "buy", marketId, marketTitle, direction: "yes", targetQuantity: 1, maxPrice: 32 })
await sf.intents.create({ venue: "polymarket", action: "buy", marketId: tokenId, marketTitle, direction: "yes", targetQuantity: 1, maxPrice: 32 })
await sf.intents.get("intent-id")
await sf.intents.cancel("intent-id")
await sf.execution.place({ ticker: marketId, action: "buy", quantity: 1, limitPrice: 32 })
await sf.execution.place({ venue: "polymarket", tokenId, action: "buy", quantity: 1, limitPrice: 32 })
await sf.runtime.status()
await sf.runtime.ensure()
```

`autoExecute` defaults to `false` on raw intent creation. `sf.execution.place` defaults to `autoExecute: true` and first ensures a runtime by checking cloud and configured SDK runtime candidates. If no runtime is running, it starts or wakes one when allowed. Polymarket execution requires a CLOB token id and explicit limit price. Use `runtime: { mode: "none" }` for an explicit intent-only workflow.

This is a governed workflow path, not the fastest possible venue client. Use raw Kalshi or Polymarket APIs for high-frequency market making, direct orderbook subscription, venue-native order lifecycle handling, and immediate replace/cancel loops. Use SimpleFunctions SDK/Agent execution when you need policy gates, runtime readiness checks, trace, intent state, monitoring, and reconciliation.

## List intents

```http theme={null}
GET /api/intents
GET /api/intents?active=true
GET /api/intents?status=pending
```

Intent statuses:

| Status      | Meaning                                                                 |
| ----------- | ----------------------------------------------------------------------- |
| `pending`   | Created and waiting for the runtime to arm it                           |
| `armed`     | Runtime has accepted it and is evaluating triggers                      |
| `triggered` | Hard trigger fired; waiting for confirmation or execution               |
| `executing` | Runtime has submitted or is submitting an order                         |
| `partial`   | Some quantity filled; remaining quantity is still active                |
| `filled`    | Target quantity filled                                                  |
| `expired`   | Trigger window expired before completion                                |
| `cancelled` | User or runtime cancelled the intent                                    |
| `rejected`  | Runtime rejected execution due to a permanent local/config/risk failure |

## Detail/update/cancel

```http theme={null}
GET /api/intents/{id}
PATCH /api/intents/{id}
DELETE /api/intents/{id}
```

`PATCH` accepts controlled status transitions (`armed`, `triggered`, `executing`, `expired`, `cancelled`, `rejected`) and positive fill reports. Invalid lifecycle transitions return `409` with the current and requested status.

## Runtime

```http theme={null}
POST /api/runtime/exec
GET /api/runtime/exec
```

Runtime endpoints are for execution workers and should be treated as side-effecting unless a route is explicitly read-only.

The SDK package does not depend on the CLI package. Hosted runtime orchestration goes through `/api/runtime/exec`; local or self-hosted runtime integrations use SDK `runtimeControllers`. Hosted status checks the runtime daemon, not just the cloud machine state, before treating execution as usable.

Hosted runtime exec forwards the authenticated `SF_API_KEY` into the runtime process. Live Kalshi and Polymarket order routing still requires exchange credentials in that runtime context, such as encrypted cloud secrets or a local/self-hosted runtime controller. Polymarket global CLOB access is subject to Polymarket's current geographic and terms restrictions; applications should set Agent policy guardrails such as `allowedVenues`, `blockedJurisdictions`, `requireJurisdiction`, max quantity, max cost, required limit prices, and confirmation tokens.