StateSet iCommerce Engine

The SQLite of commerce. A complete commerce runtime — orders, inventory,
checkout, payments, returns, subscriptions, warehouse operations, finance —
that runs inside your process against one database file. No hosted control
plane, no service account, no rate limit.

For autonomous execution it adds what an AI agent needs before it may spend
money: delegated identity, deny-by-default authority, exact budgets, idempotent
commands, and cryptographically verifiable receipts.

Start here

Scaffold a working storefront:

npm create stateset-app@latest my-store

Then run it:

cd my-store
cp .env.example .env.local
npm run seed          # 10 products, stock, a demo catalog in ./store.db
npm run dev           # http://localhost:3000

That is a Next.js storefront with a real commerce engine behind it — the
generator and the seed step are covered end to end by the
Storefront Golden Path CI job.

Give an AI agent a commerce sandbox

For Claude Desktop, Cursor, Windsurf, or any MCP client:

{
  "mcpServers": {
    "stateset-commerce": {
      "command": "npx",
      "args": ["-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--profile", "core"]
    }
  }
}

Writes are preview-only by default. The core profile — the default —
exposes only the smoke-gated core tier (196 tools); finance, operations,
agents, and all open it up, and --domains a2a,x402 adds individual
domains. Each tool's tier (core, extended, experimental) is listed in
cli/docs/TOOLS.md. Give an agent apply
authority only through operator-owned files, never through tool arguments:

{
  "args": [
    "-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--apply",
    "--kernel-policy", "./kernel-policy.json",
    "--kernel-principal", "./kernel-principal.json",
    "--kernel-store-id", "store:production"
  ]
}

For hosted deployments, stateset-mcp-http serves the same tools over MCP
Streamable HTTP (protocol revision 2026-07-28), stateless by construction — no
session ids, a fresh server per request, so it scales across replicas:

npx -y -p @stateset/cli stateset-mcp-http --db ./store.db --port 8090

Add --host 0.0.0.0 to expose it, --read-only to disable writes at the
transport boundary, or --strict-protocol to refuse pre-2026-07-28 clients.

Install

The Ruby and WASM bindings have published packages that are not kept current:
RubyGems stateset_embedded is at 0.1.9 and npm @stateset/embedded-wasm at
0.7.22, both far behind 1.40.0. PHP, Java, Kotlin, Swift, .NET, and Go have no
published package at all — build those from source, and see
docs/src/api/ for each binding's API and install snippet.

Use it

import { Commerce } from '@stateset/embedded';

const commerce = new Commerce('./store.db');
const customer = await commerce.customers.create({
  email: '[email protected]',
  firstName: 'Ada',
  lastName: 'Lovelace',
});

use stateset_sdk::prelude::*;

let commerce = Commerce::new("store.db")?;
let customer = commerce.customers().create(CreateCustomer {
    email: "[email protected]".into(),
    first_name: "Ada".into(),
    last_name: "Lovelace".into(),
    ..Default::default()
})?;

Amounts are exact decimal values end to end. Every mutation is auditable.

Rust Quickstart → ·
CLI Quickstart → ·
Getting Started (all languages) →

Serve a REST API

stateset-http is an embeddable layer, started from your Rust application. It
binds 127.0.0.1:3000 by default and serves the OpenAPI 3.1 spec at
/api/v1/openapi.json, with an interactive reference at /api/v1/docs. Auth
is on by default: the server generates a token that can be read with
bearer_auth_token() before serve(); logs show only a redacted preview.
A non-loopback bind requires an explicit operator-owned bearer token,
authorization, and rate limiting (or an explicitly trusted gateway). See
step 4 of the Rust quickstart.

Why iCommerce

Most commerce APIs answer "what endpoint can the model call?" StateSet answers
the harder question: "how can this actor commit resources safely, recover from
failure, and prove what happened?"

• State, not chat history. Orders, inventory, balances, approvals, and
  workflows survive process restarts and evolve through guarded state machines.
• Authority, not model confidence. The agent proposes an intent; an
  operator-owned, deny-by-default policy decides whether it may execute.
• Transactions, not tool-call optimism. Domain state, budgets, events, and
  idempotency records commit atomically or roll back together.
• Receipts, not unverifiable narration. Consequential actions return a
  sealed record of actor, principal, intent, policy decision, observed result,
  audit anchor, and settlement evidence.
• A small public vocabulary over deep machinery. Agents reason in quote,
  buy, sell, pay, fulfill, return_order, refund, and subscribe
  while the engine keeps its full domain API and generated MCP catalog.
• Embedded by default. SQLite is the zero-infrastructure path; PostgreSQL
  is there when multiple workers need a shared backend.

Kernel-executed commerce

The kernel is the boundary between a model suggesting an action and software
being allowed to perform it:

objective → typed intent → authenticated agent → delegated authority
          → policy + budget → atomic domain command → economic receipt

Identity and policy are trusted runtime inputs. They are never accepted from a
model-authored tool call. Monetary limits use decimal strings; non-fiat assets
use separate asset identifiers; inventory commands bind the authorized quantity
to the executor-observed quantity.

Details: Kernel Execution ·
Trust Foundation (security model and its
explicit gap inventory) · Kernel Roadmap

Agent frameworks

If your agent runtime lives inside your application process and wants
JSON-schema tools rather than stdio MCP, use the embedded toolkit:

Install the Python framework extras in one step with
pip install "stateset-embedded[agents]==1.40.0".

The toolkit also exposes payment-aware helpers (getPayableToolCatalog(),
executePaidTool(), discoverRemotePaymentService()) and contract/replay
helpers (getRuntimeContract(), simulatePlan(), executePlan(),
replayMutation()). Call simulateMutation() or
executePlan({ dryRun: true }) before enabling writes, then set allowApply
only on agents that should mutate commerce state.

Working examples: Embedded Agent Toolkit ·
AI Agents

Agent-to-agent commerce

Direct agent-to-agent payments, quotes and negotiation, escrow with conditional
release, split payments, subscriptions, discovery and reputation, and signed
event streaming are first-class. See
Intelligent Commerce Protocol,
A2A Protocol Overview, and
x402.

The deterministic multi-agent marketplace demo puts a buyer, three merchants,
and a payment agent on one Ed25519-signed, totally ordered message board, where
the winning award crosses two independent kernel boundaries:

(cd bindings/node && npm run build)
node examples/sequencer-marketplace/demo.mjs --self-test --kernel

Architecture

A layered Rust kernel with two outer product surfaces: language bindings, and
the Node-based operator runtime.

stateset-primitives | stateset-crypto | stateset-pricing | stateset-observability
stateset-policy | stateset-authz | stateset-a2a | stateset-jobs
stateset-migrations | stateset-macros
        ->
stateset-core | stateset-sync
        ->
stateset-db
        ->
stateset-embedded
        ->
stateset-http | stateset-sdk | bindings/*
        ->
admin | cli

Read it in this order: stateset-core, stateset-db, stateset-embedded,
then stateset-sync/stateset-policy/stateset-authz/stateset-pricing,
then stateset-http, then bindings/node and admin/ or cli/.

Full walkthrough: Architecture ·
Dependency Direction ·
Workspace Inventory (generated)

Development

nvm use                      # .nvmrc / .node-version (20.20.0)
rustup show active-toolchain # pinned by rust-toolchain.toml (1.90.0)

npm run check                # developer gate across the core workspace surfaces
npm run check:release        # release preflight; run before cutting a tag

Per-surface loops:

cargo test -p stateset-core -p stateset-db -p stateset-embedded
npm --prefix cli test
npm --prefix admin test
npm --prefix bindings/node run check

The authoritative remote gate is CI on master. CI also verifies the workspace
MSRV on Rust 1.85 and runs the binding and admin surfaces on the same pinned
Node 20.20.0.

Contributing: CONTRIBUTING.md ·
Releasing: RELEASING.md ·
Security: SECURITY.md

Documentation

• The book — concepts, every commerce domain, A2A,
  payments, security, policy, adapters, operations, and the API reference.
  Build it locally with mdbook serve docs.
• Tool catalog — generated, authoritative list of the
  MCP/CLI tool surface (923 tools across 87 domains today).
• API reference per binding — Rust, Node, Python, Go,
  Java, Kotlin, Swift, .NET, Ruby, PHP, WASM.
• Examples — runnable end-to-end programs.
• Rust API docs on docs.rs.
• CHANGELOG.md — release history.
• llms.txt — a machine-readable index for agents; AGENTS.md is
  the short orientation for an agent working against this repo.

License

Dual-licensed under MIT or Apache-2.0, at your
option.