SimpleFunctions Developer Manual

The runtime is the long-running process that watches active intents and executes authorized workflows. It is the bridge between an analyst writing intents (CLI / API / agent) and orders actually leaving for Kalshi or Polymarket. For automated execution, prefer intents + runtime over raw sf buy / sf sell. Intents are persisted, replayable, race-free, and reviewable before execution.

Two ways to run it

Mode	Where it runs	Credentials	Best for
Local	Your machine, foreground or background	Local Kalshi / Polymarket private keys (file paths)	Operators, dev, single-machine setups.
Cloud (BYOK)	SimpleFunctions cloud	Encrypted exchange credentials, connected by the user and never returned by the API	Always-on automation without keeping a laptop awake.

Quick start (local)

sf setup                                # configure SimpleFunctions + Kalshi keys
sf intent buy KXRATECUT-26DEC31 10 \
  --trigger below:45 --rationale "edge below 45c"
sf runtime start --smart --daemon       # start watching, with LLM soft-condition support
sf runtime status --json

What runtime watches

Each tick (every 30 seconds) the runtime:

Reads your active intents from GET /api/intents?status=....
For each intent, checks the trigger — hard price/time triggers locally, soft NL conditions if --smart is enabled.
Marks newly-firing intents armed → triggered → executing.
Places the order on the configured venue using your local exchange keys.
Tracks fills against the intent (filledQuantity), retries partial fills on the next tick.
Writes structured status / errors to ~/.sf/runtime.log.

Runtime state files live under ~/.sf/:

File	Purpose
`~/.sf/runtime.pid`	PID of the foreground / daemonized runtime.
`~/.sf/runtime.log`	Append-only log of tick activity, fills, and errors.
`~/.sf/runtime-executed.json`	De-dupes execution attempts across crashes.

CLI

`sf runtime start`

sf runtime start                     # foreground
sf runtime start --daemon            # background; logs to ~/.sf/runtime.log
sf runtime start --smart             # enable LLM soft-condition evaluation
sf runtime start --smart --daemon

Flag	Default	Notes
`--daemon`	off	Detach into a background process. PID written to `~/.sf/runtime.pid`.
`--smart`	off	Evaluate `softCondition` strings on intents (“only if VIX < 20”) with the configured LLM. Costs LLM tokens.

Refuses to start if Kalshi credentials aren’t configured; the fix is sf setup --enable-trading.

`sf runtime stop`

sf runtime stop

Sends SIGTERM to the PID in ~/.sf/runtime.pid. Falls back to scanning for orphan runtime processes.

`sf runtime status`

sf runtime status
sf runtime status --json

Returns daemon liveness, last tick timestamp, count of intents per status, and a recent error trail.

Intents

An intent is a persisted instruction to do something on a venue when a trigger fires. Create them with the CLI or the HTTP API.

Create an intent (CLI)

sf intent buy <ticker> <quantity>  [flags]
sf intent sell <ticker> <quantity> [flags]

Flag	Default	Notes
`--price <cents>`	none (market)	Max price per contract in cents (1–99).
`--side <yes\|no>`	`yes`	Direction.
`--trigger <trigger>`	`immediate`	See trigger forms below.
`--soft "<condition>"`	none	NL condition the runtime evaluates each tick when `--smart` is on.
`--expire <duration>`	`1d`	When the intent auto-cancels: `1h`, `6h`, `1d`, `3d`, `1w`.
`--venue <kalshi\|polymarket>`	`kalshi`	Venue.
`--rationale "<text>"`	none	Free-form why-string saved on the intent.
`--auto`	off	Skip the interactive confirmation.
`--style <immediate\|twap>`	`immediate`	Execution style. `twap` slices the order over time.
`--json`	off	Return JSON envelope.

Trigger forms

Form	Meaning
`immediate`	Fire on the next tick (or right now if not arming).
`below:<cents>`	Fire when price ≤ that many cents.
`above:<cents>`	Fire when price ≥ that many cents.
`time:<ISO>`	Fire at the given ISO-8601 timestamp.

Soft conditions (--soft) are evaluated by the configured LLM on every tick when --smart is enabled. Examples:

--soft "only if Polymarket twin is at least 4c richer"
--soft "skip if SimpleFunctions Index moved more than 3 points in the last hour"

List + cancel

sf intent list                   # active only
sf intent list --all --json      # all statuses, JSON
sf intent list --status armed
sf intent cancel <id>

Lifecycle

created → armed → triggered → executing → filled
                                  │
                                  └→ canceled | expired | failed

Status	Meaning
`created`	Persisted but not yet activated (e.g. waiting for `activateAt`).
`armed`	Watching; trigger has not fired.
`triggered`	Trigger fired this tick; runtime is about to submit.
`executing`	Order submitted, awaiting fill.
`filled`	Fully filled (or partially, if the venue closed early).
`canceled`	User canceled.
`expired`	`expireAt` passed without firing.
`failed`	Venue rejected or runtime errored. The error is captured on the intent row.

Intents API

POST   /api/intents
GET    /api/intents
GET    /api/intents/{id}
PATCH  /api/intents/{id}
DELETE /api/intents/{id}

Auth: required.

POST /api/intents

Required body fields

Field	Type	Notes
`action`	`"buy"` \| `"sell"`	Order direction.
`venue`	`"kalshi"` \| `"polymarket"`	Venue.
`marketId`	string	Kalshi ticker or Polymarket conditionId.
`marketTitle`	string	Display title — saved on the intent for UX.
`direction`	`"yes"` \| `"no"`	Contract side.
`targetQuantity`	integer ≥ 1	Number of contracts to fill.

Optional body fields

Field	Type	Notes
`maxPrice`	integer 1–99	Max price per contract in cents.
`executionStyle`	`"immediate"` \| `"twap"`	TWAP slices the order.
`triggerType`	string	`"immediate"`, `"price_below"`, `"price_above"`, `"time"`.
`triggerPrice`	number	Cents threshold for price triggers.
`triggerAt`	ISO timestamp	For `triggerType: "time"`.
`triggerParams`	object	Trigger-specific extras.
`softCondition`	string	NL condition evaluated each tick when `--smart` is on.
`expireAt`	ISO timestamp	When the intent auto-cancels.
`autoExecute`	boolean	If true, skip confirmation.
`source`	string	Free-form attribution (`"cli"`, `"agent"`, …).
`sourceId`	string	Linked thesis id, evaluation id, etc.
`rationale`	string	Why-string saved on the intent.

Errors

Status	Body	Cause
`400`	`Missing required fields: ...`	Missing required field.
`400`	`action must be "buy" or "sell"`	Bad enum.
`400`	`venue must be "kalshi" or "polymarket"`	Bad enum.
`400`	`direction must be "yes" or "no"`	Bad enum.
`400`	`targetQuantity must be a positive integer`	Bad number.
`400`	`maxPrice must be 1-99 cents`	Out of range.
`401`	unauthorized	No / invalid auth.

GET /api/intents

Query	Notes
`status`	Filter (`active`, `armed`, `triggered`, `executing`, `filled`, `canceled`, `expired`, `failed`).
`venue`	Filter by venue.
`source`	Filter by `source` field.
`limit`	Cap on rows.

PATCH / DELETE

PATCH updates status, softCondition, expireAt, or triggerParams. DELETE cancels.

Smart mode

--smart enables three behaviors:

Soft-condition evaluation. Each tick, if any active intent has a softCondition, the runtime calls the LLM with current market context and the condition. Only fires the order if the LLM returns a clear positive.
Edge re-check before firing. Just before submitting the order, the runtime calls inspect_ticker on the market and aborts if the suggestion has flipped to avoid.
Adaptive delay. Trades that look like they’d cross the spread are deferred until the spread is reasonable — implementation default is 8 cents.

Smart mode costs LLM tokens; budget with sf agent --budget-usd ... and / or per-thesis monthlyBudgetUsd on heartbeat.

Risk gates

The runtime calls the same risk-gate engine as the autopilot tick. Before any order is placed it checks:

per-trade max notional
per-market exposure cap
daily loss circuit breaker
max open positions
minimum balance
per-tick max orders

A rejected order writes a structured risk_gate_fail reason to the intent and stops there — the intent stays armed for the next tick. See Risk gates.

Cloud runtime (BYOK)

The cloud runner gives you “always on” without keeping a laptop awake. Treat this as an advanced operator surface: start locally, verify dry-run behavior, then connect cloud credentials only when you are ready for unattended automation.

Enable

sf setup --cloud                     # encrypt & upload exchange keys
sf runtime start --remote            # boot cloud container (~3s cold start)
sf runtime stop --remote             # scale to zero
sf --remote agent ...                # route any agent command through the cloud

sf setup --cloud connects encrypted exchange credentials for the cloud runner. The API never returns plaintext credentials; rotate or revoke them from the CLI when access should change. The cloud runner uses the same intent + tick + risk-gate code paths as the local runtime. The only difference is the host.

One-shot remote exec

POST /api/runtime/exec
GET  /api/runtime/exec?runId=...

Used by sf --remote <command>. Sends a single CLI invocation to the cloud runner, returns a runId, and lets you stream or poll output. Auth: Authorization: Bearer sf_live_.... This is not a long-running daemon — for that, use sf runtime start --remote.

Events

Runtime emits webhook events when configured:

Event	When
`intent.armed`	Trigger watcher attached.
`intent.triggered`	Trigger fired.
`intent.executing`	Order submitted.
`intent.filled`	Order fully filled.
`intent.canceled`	User canceled.
`intent.expired`	`expireAt` passed without firing.
`intent.failed`	Venue rejected or runtime errored.

Configure receivers via Webhooks.

Operational tips

Run sf doctor before going live to catch missing keys, time-skew, or a stale CLI.
Use sf intent list --all --json to review what the runtime is watching before you start it in --smart mode (smart-mode runs LLM calls).
Soft conditions are tokens; over-broad conditions on many intents accumulate cost. Prefer hard triggers when the rule is mechanical.
Cloud runner respects executionMode — dry-run evaluates everything but skips placing orders. Flip to live only when you’re satisfied with dry-run output.

sf agent --plain                     # interactive agent (uses intents under the hood)
sf agent --headless --deny trade,runtime
sf telegram --daemon                 # mobile operator visibility

sf agent is for reasoning + tool use. sf telegram is for human-in-the-loop. The runtime is the worker that closes the loop.

Trade intents

The intent-object model in depth.

Risk gates

Pre-trade safety rails.

Portfolio autopilot

Cloud-run portfolio loop with BYOK credential connection.

Webhooks

Signed delivery for runtime events.

CLI for humans and agents

Agent runtime

Portfolio

Agent Runtime

Two ways to run it

Quick start (local)

What runtime watches

CLI

`sf runtime start`

`sf runtime stop`

`sf runtime status`

Intents

Create an intent (CLI)

List + cancel

Lifecycle

Intents API

POST /api/intents

GET /api/intents

PATCH / DELETE

Smart mode

Risk gates

Cloud runtime (BYOK)

Enable

One-shot remote exec

Events

Operational tips

See also

Trade intents

Risk gates

Portfolio autopilot

Webhooks

​Two ways to run it

​Quick start (local)

​What runtime watches

​CLI

​sf runtime start

​sf runtime stop

​sf runtime status

​Intents

​Create an intent (CLI)

​List + cancel

​Lifecycle

​Intents API

​POST /api/intents

​GET /api/intents

​PATCH / DELETE

​Smart mode

​Risk gates

​Cloud runtime (BYOK)

​Enable

​One-shot remote exec

​Events

​Operational tips

​Related

​See also

Trade intents

Risk gates

Portfolio autopilot

Webhooks

Two ways to run it

Quick start (local)

What runtime watches

CLI

`sf runtime start`

`sf runtime stop`

`sf runtime status`

Intents

Create an intent (CLI)

List + cancel

Lifecycle

Intents API

POST /api/intents

GET /api/intents

PATCH / DELETE

Smart mode

Risk gates

Cloud runtime (BYOK)

Enable

One-shot remote exec

Events

Operational tips

Related

See also