SDK Portfolio + Intents + Execution

When to use

• Building a TypeScript service that reads portfolio state programmatically
• Creating execution intents from a custom dashboard
• Live Kalshi execution with SimpleFunctions risk gates
• Cancellation/management of pending intents

Prerequisites

npm install @spfunctions/[email protected]
export SF_API_KEY="sf_..."  # required — portfolio is user-scoped

For live execution (sf.execution.place), the API key must have execution scope and BYOK Kalshi credentials must be connected (see sf-autopilot-setup).

Setup

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  apiKey: process.env.SF_API_KEY,
  baseUrl: process.env.SF_API_URL ?? "https://simplefunctions.dev",
})

Portfolio reads

// Current state snapshot
const state = await sf.portfolio.state()
console.log({
  cash: state.cash,
  exposure: state.exposure,
  dailyPnl: state.dailyPnl,
  totalPnl: state.totalPnl,
  positions: state.positions,
  status: state.status,
})

// Recent ticks (each is one evaluation cycle)
const ticks = await sf.portfolio.ticks.list({ limit: 10, envelope: true })
ticks.data.forEach(t => {
  console.log({
    at: t.at,
    handoffNote: t.handoffNote?.slice(0, 80),
    actions: t.actions?.length,
    riskGates: t.riskGates,
  })
})

// Recent trades
const trades = await sf.portfolio.trades.list({ limit: 10, envelope: true })
trades.data.forEach(t => {
  console.log({
    at: t.at,
    ticker: t.ticker,
    action: t.action,
    quantity: t.quantity,
    fillPrice: t.fillPrice,
    pnl: t.pnl,
    linkedThesisId: t.linkedThesisId,
  })
})

Use envelope: true to get pagination metadata (cursor, hasMore) alongside the data array.

Intents

Intents are the safe execution path — propose an order, review, then approve.

List active intents

const intents = await sf.intents.list({ active: true })
console.log(intents.map(i => ({
  id: i.id,
  status: i.status, // "pending" | "approved" | "executed" | "canceled" | "expired"
  ticker: i.marketId,
  action: i.action,
  quantity: i.targetQuantity,
  maxPrice: i.maxPrice,
})))

Get one intent

const intent = await sf.intents.get("intent-id")
console.log({
  ...intent,
  riskGateChecks: intent.riskGateChecks,
  proposedBy: intent.proposedBy, // "autopilot" | "user" | "<agent-id>"
  note: intent.note,
})

Create an intent

const created = await sf.intents.create({
  action: "buy",                          // "buy" | "sell" | "cancel"
  venue: "kalshi",                        // "kalshi" | "polymarket"
  marketId: "KXFED-27APR-T3.50",
  marketTitle: "Fed target rate <= 3.50",
  direction: "yes",                       // "yes" | "no"
  targetQuantity: 1,
  maxPrice: 32,                           // limit price in cents
  autoExecute: false,                     // KEEP false for human-in-the-loop
  note: "Pre-trade check: 28/30 — proceed full size",
})

console.log(created.id, created.status)

autoExecute: false keeps it in pending state until approved. The autopilot also creates intents with this flag — they're the queue you review.

Approve an intent

// HTTP-direct (SDK wrapper may differ by version)
const approved = await fetch(`https://simplefunctions.dev/api/intent/${intentId}/approve`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}` },
}).then(r => r.json())

console.log(approved.status, approved.executionResult)

Approval triggers the execution pipeline: risk gates check, then order to exchange.

Cancel an intent

const canceled = await sf.intents.cancel("intent-id")

Works in pending state. After execution, use sf.execution.place({ action: "cancel", ... }) for exchange-level cancellation.

Live execution (direct)

For unmediated execution (bypass intent queue):

const placed = await sf.execution.place({
  ticker: "KXFED-27APR-T3.50",
  action: "buy",
  quantity: 1,
  limitPrice: 32,
})

console.log(placed.orderId, placed.fillStatus)

This ensures a usable runtime before creating the executable intent unless you pass runtime: { mode: "none" }.

Strongly recommended: don't use sf.execution.place directly. Use sf.intents.create({ autoExecute: false }) → review → approve. The intent path keeps the adversarial check on the record.

Risk gates apply automatically

Before any order placement (via intent or direct execution), SimpleFunctions enforces risk gates configured in your portfolio:

• max_exposure_usd
• max_position_pct
• max_daily_loss_usd
• drawdown_auto_halt_pct

Failed gates return a structured error:

try {
  await sf.intents.create({ /* ... */ })
} catch (e) {
  if (e.code === "RISK_GATE_FAILED") {
    console.log("Gate failed:", e.gate, e.reason, e.currentValue)
  }
}

See concepts/risk-gates for the full list and configuration via sf-autopilot-setup.

Watchlists + alerts

const watched = await sf.watchlists.list({ limit: 20 })
const alerts = await sf.alerts.list({ status: "active", limit: 20 })

These are read-only surfaces. For mutation (create watch, register alert), use HTTP-direct or the CLI — see sf-watch-topic skill.

Full automation pattern

async function autopilotReviewCycle() {
  // 1. Pull state
  const state = await sf.portfolio.state()
  if (state.status === "halted") {
    return { action: "skip", reason: `halted: ${state.haltedReason}` }
  }
  
  // 2. Review pending intents
  const pending = await sf.intents.list({ active: true })
  const ready = pending.filter(i => i.status === "pending")
  
  // 3. For each, fetch market state + decide
  const decisions = await Promise.all(ready.map(async (intent) => {
    const market = await sf.markets.get(intent.marketId)
    
    // Apply local discipline — example: skip if spread > 5¢
    if (market.spread > 5) {
      return { intentId: intent.id, action: "cancel", reason: "spread too wide" }
    }
    
    return { intentId: intent.id, action: "approve" }
  }))
  
  // 4. Execute decisions
  for (const d of decisions) {
    if (d.action === "approve") {
      await fetch(`https://simplefunctions.dev/api/intent/${d.intentId}/approve`, {
        method: "POST",
        headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}` },
      })
    } else if (d.action === "cancel") {
      await sf.intents.cancel(d.intentId)
    }
  }
  
  return { processed: decisions.length, decisions }
}

Errors

• `HttpError 403` on portfolio reads: API key lacks portfolio scope. Generate a scoped key in the dashboard.
• `RISK_GATE_FAILED` on intent.create: order violates a configured gate. Adjust size, price, or wait.
• `KALSHI_CONNECTION_ERROR`: BYOK credentials disconnected. Reconnect via sf portfolio enable --venue kalshi.

Related skills

• sf-sdk-quickstart — install + first call
• sf-autopilot-setup — risk gate + BYOK setup
• sf-portfolio-review — CLI workflow for the same reads
• sf-pre-trade-check — adversarial check before approving an intent

Reference docs

• <https://docs.simplefunctions.dev/guides/authenticated-read-sdk>
• <https://docs.simplefunctions.dev/api-reference/portfolio>
• <https://docs.simplefunctions.dev/api-reference/execution-intents>
• <https://docs.simplefunctions.dev/concepts/risk-gates>