Quickstart

Install

python3 -m venv .venv
source .venv/bin/activate
pip install haltstate-sdk

Environment

export HALTSTATE_TENANT_ID=your-tenant-id
export HALTSTATE_API_KEY=hs_your_api_key
export HALTSTATE_API_BASE=https://haltstate.ai

Guard one action

This is a complete local toy ledger example. Replace write_refund_once with your production refund API or service method after the guard path is working. The fuller worker lifecycle is shown in the Complete Example.

import os
from haltstate import HaltStateClient, ApprovalPending, ActionDenied

ledger = {}

def write_refund_once(order_id: str, amount: int, currency: str) -> None:
    if order_id in ledger:
        raise RuntimeError(f"refund already recorded for {order_id}")
    ledger[order_id] = {"amount": amount, "currency": currency, "status": "EXECUTED"}

client = HaltStateClient(
    tenant_id=os.environ["HALTSTATE_TENANT_ID"],
    api_key=os.environ["HALTSTATE_API_KEY"],
    base_url=os.environ.get("HALTSTATE_API_BASE", "https://haltstate.ai"),
)

try:
    with client.guard(
        action="refund.create",
        params={"amount": 126, "currency": "USD", "merchant_label": "Demo Store"},
        idempotency_key="refund:order-1001:2026-06-17",
    ):
        write_refund_once("order-1001", 126, "USD")
except ApprovalPending:
    print("approval required; no refund executed")
except ActionDenied as exc:
    print(f"denied; no refund executed: {exc}")

Installation video

The installation walkthrough belongs on the Get Started page so operators have a single place for setup video, environment variables, and copyable commands.

TypeScript quickstart

// Install with: npm install @haltstate/sdk
import { HaltStateClient, ApprovalPending, ActionDenied } from '@haltstate/sdk';

const client = new HaltStateClient({
  tenantId: process.env.HALTSTATE_TENANT_ID!,
  apiKey: process.env.HALTSTATE_API_KEY!,
  agentId: 'refund-worker',
});

try {
  const permit = await client.guard('refund.create', {
    params: { amount: 126, currency: 'USD' },
    idempotencyKey: `refund:${ledgerEntryId}`,
  });
  await executeRefundOnce(ledgerEntryId, permit);
} catch (error) {
  if (error instanceof ApprovalPending) process.exit(0);
  if (error instanceof ActionDenied) await markDenied(ledgerEntryId, error.reason);
  else throw error;
}

What just happened

1. The worker prepared a high-risk action and a safe policy context.
2. The guard call evaluated policy before execution.
3. ALLOW let the guarded block run.
4. APPROVAL_REQUIRED raised a control-flow signal and the worker exited or paused without execution.
5. DENY raised a denial signal and the worker recorded no side effect.
6. The idempotency key tied retries back to the same business action.

First policy to create

Start with one action and one threshold. For retail refunds: allow small clean refunds, require approval for medium refunds, and deny high-value, duplicate, stale, suspicious, or high-velocity refunds. After the first action is stable, repeat the same guard boundary for customer data exports, gift cards, loyalty credits, outbound messages, and production writes.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.